hivectl: make --socket a global flag instead of per-verb

The host admin socket path was duplicated on every daemon-assisted verb
(agents restart/restart-all, stop, start). Hoist it to a single global arg
on the top-level Cli (`--socket`, default DEFAULT_HOST_SOCKET, accepted
before or after the subcommand) and thread cli.socket through dispatch.
Verbs that don't talk to the daemon ignore it. Pure CLI-ergonomics change;
no wire/behaviour change. Regenerated docs/tools/hivectl-cli.md.

docs/tools/hivectl-cli.md

@@ -28,7 +28,7 @@ This document contains the help content for the `hivectl` command-line program.
 
 Sibling to the `hive-c0re` daemon binary. Covers host-side admin operations that don't go through the broker — manual user provisioning on the bundled forge + matrix containers, plus future recovery / debugging verbs.
 
-**Usage:** `hivectl <COMMAND>`
+**Usage:** `hivectl [OPTIONS] <COMMAND>`
 
 ###### **Subcommands:**
 
@@ -40,6 +40,12 @@ Sibling to the `hive-c0re` daemon binary. Covers host-side admin operations that
 * `stop` — Stop containers hive-wide in one operator action. Bare `hivectl stop` stops **everything** — all sub-agents plus the ci, forge, gateway, and matrix infra containers. Narrow it with scope flags: `--agents` (all sub-agents), `--ci` / `--forge` / `--gateway` / `--matrix` (named infra), and `--agent <name>` (repeatable) for specific sub-agents. Flags are additive (e.g. `--agents --matrix`). Requires the hive-c0re daemon (connects to the host admin socket). hive-c0re itself is never stopped — it services the request
 * `start` — Start containers hive-wide — the inverse of `hivectl stop`. Bare `hivectl start` starts everything back up; the same scope flags as `stop` narrow it (`--agents`, `--ci`, `--forge`, `--gateway`, `--matrix`, `--agent <name>`). Requires the hive-c0re daemon
 
+###### **Options:**
+
+* `--socket <SOCKET>` — Path to the hive-c0re host admin socket, used by the daemon-assisted verbs (`agents`, `stop`, `start`). Global: accepted before or after the subcommand. Verbs that don't talk to the daemon ignore it
+
+  Default value: `/run/hyperhive/host.sock`
+
 
 
 ## `hivectl forge`
@@ -251,31 +257,19 @@ Agent container management. Requires the hive-c0re daemon to be running (connect
 
 Stop and start a single agent container without rebuilding config. Useful for "kick the container" when the process is stuck or the container needs a clean restart without changing the NixOS config
 
-**Usage:** `hivectl agents restart [OPTIONS] <NAME>`
+**Usage:** `hivectl agents restart <NAME>`
 
 ###### **Arguments:**
 
 * `<NAME>` — Agent name (e.g. `damocles`, `ruth`)
 
-###### **Options:**
-
-* `--socket <SOCKET>` — Path to the hive-c0re host admin socket
-
-  Default value: `/run/hyperhive/host.sock`
-
 
 
 ## `hivectl agents restart-all`
 
 Stop and restart ALL managed agent containers in sequence. Iterates the live container list and restarts each one. Any per-agent failure is reported at the end rather than stopping mid-run, so all containers get a restart attempt
 
-**Usage:** `hivectl agents restart-all [OPTIONS]`
+**Usage:** `hivectl agents restart-all`
-
-###### **Options:**
-
-* `--socket <SOCKET>` — Path to the hive-c0re host admin socket
-
-  Default value: `/run/hyperhive/host.sock`
 
 
 
@@ -318,9 +312,6 @@ Stop containers hive-wide in one operator action. Bare `hivectl stop` stops **ev
 * `--graceful` — Gracefully quiesce each agent (finish the current turn, drain the inbox) before stopping, instead of a hard stop.
 
    NOTE: not yet effective — the per-agent quiesce is still being implemented (see the graceful-agent-stop tracker), so today this falls through to a hard stop. The flag is accepted now so the wire/CLI shape is stable when the quiesce lands.
-* `--socket <SOCKET>` — Path to the hive-c0re host admin socket
-
-  Default value: `/run/hyperhive/host.sock`
 
 
 
@@ -338,9 +329,6 @@ Start containers hive-wide — the inverse of `hivectl stop`. Bare `hivectl star
 * `--forge` — The forge container (`hive-forge`)
 * `--gateway` — The gateway container (`hive-gateway`)
 * `--matrix` — The matrix container (`hive-matrix`)
-* `--socket <SOCKET>` — Path to the hive-c0re host admin socket
-
-  Default value: `/run/hyperhive/host.sock`
 
 
 

hive-c0re/src/bin/hivectl.rs

@@ -34,6 +34,11 @@ recovery / debugging verbs.\
 "
 )]
 struct Cli {
+    /// Path to the hive-c0re host admin socket, used by the daemon-assisted
+    /// verbs (`agents`, `stop`, `start`). Global: accepted before or after
+    /// the subcommand. Verbs that don't talk to the daemon ignore it.
+    #[arg(long, global = true, default_value = DEFAULT_HOST_SOCKET)]
+    socket: PathBuf,
     #[command(subcommand)]
     cmd: Cmd,
 }
@@ -120,9 +125,6 @@ enum Cmd {
         /// the wire/CLI shape is stable when the quiesce lands.
         #[arg(long)]
         graceful: bool,
-        /// Path to the hive-c0re host admin socket.
-        #[arg(long, default_value = DEFAULT_HOST_SOCKET)]
-        socket: PathBuf,
     },
     /// Start containers hive-wide — the inverse of `hivectl stop`. Bare
     /// `hivectl start` starts everything back up; the same scope flags as
@@ -131,9 +133,6 @@ enum Cmd {
     Start {
         #[command(flatten)]
         scope: ScopeArgs,
-        /// Path to the hive-c0re host admin socket.
-        #[arg(long, default_value = DEFAULT_HOST_SOCKET)]
-        socket: PathBuf,
     },
     /// Emit the full CLI reference as `CommonMark` to stdout.
     ///
@@ -369,19 +368,12 @@ enum AgentsCmd {
     Restart {
         /// Agent name (e.g. `damocles`, `ruth`).
         name: String,
-        /// Path to the hive-c0re host admin socket.
-        #[arg(long, default_value = DEFAULT_HOST_SOCKET)]
-        socket: PathBuf,
     },
     /// Stop and restart ALL managed agent containers in sequence.
     /// Iterates the live container list and restarts each one. Any per-agent
     /// failure is reported at the end rather than stopping mid-run, so all
     /// containers get a restart attempt.
-    RestartAll {
+    RestartAll,
-        /// Path to the hive-c0re host admin socket.
-        #[arg(long, default_value = DEFAULT_HOST_SOCKET)]
-        socket: PathBuf,
-    },
 }
 
 #[tokio::main]
@@ -393,6 +385,7 @@ async fn main() -> Result<()> {
         )
         .init();
     let cli = Cli::parse();
+    let socket = cli.socket;
     match cli.cmd {
         Cmd::Forge { cmd } => match cmd {
             ForgeCmd::CreateUser {
@@ -423,15 +416,11 @@ async fn main() -> Result<()> {
             GatewayCmd::ListUsers { file } => gateway_list_users(&file),
         },
         Cmd::Agents { cmd } => match cmd {
-            AgentsCmd::Restart { name, socket } => agents_restart(&socket, &name).await,
+            AgentsCmd::Restart { name } => agents_restart(&socket, &name).await,
-            AgentsCmd::RestartAll { socket } => agents_restart_all(&socket).await,
+            AgentsCmd::RestartAll => agents_restart_all(&socket).await,
         },
-        Cmd::Stop {
+        Cmd::Stop { scope, graceful } => stop(&socket, scope.to_scope(), graceful).await,
-            scope,
+        Cmd::Start { scope } => start(&socket, scope.to_scope()).await,
-            graceful,
-            socket,
-        } => stop(&socket, scope.to_scope(), graceful).await,
-        Cmd::Start { scope, socket } => start(&socket, scope.to_scope()).await,
         Cmd::Choom { name, fresh } => choom(&name, fresh),
         Cmd::MarkdownDocs => {
             print!("{}", clap_markdown::help_markdown::<Cli>());