refactor(cli): delete GlobalArgs and the dead ops descriptor spec column (#10554)

* refactor(cli): delete the fieldless GlobalArgs handler parameter

`GlobalArgs` was a zero-field struct with no derives and no impls, built
from nothing at dispatch time (`GlobalArgs {}`) and threaded by reference
through 98 function signatures across 67 files, two function-type aliases
(`JsonCommandExecutor`, `BoundCommandAdapter::run`), one function-pointer
field (`ReviewStageDescriptor::run`), and ~140 call sites.

It never participated in argument parsing: it does not derive `clap::Args`,
is never a struct field, never appears in a `#[command(flatten)]`, and is
never referenced from `cli_surface::Cli`. Real process-wide CLI state lives
on `Cli` as `global = true` clap arguments. Removing the type therefore
cannot change the rendered `--help` surface or the accepted argv surface.

Adds `root_global_flag_surface_is_pinned` to lock the globally-propagated
flag set, because that set *is* rendered help and `homeboy-lab-runner`
negotiates its lease-less recovery contract by parsing a remote binary's
rendered `Options:` block.

Refs #10322

* refactor(cli): drop the dead spec column from ops_command_descriptors

`ops_command_descriptors!` is expanded exactly twice:
`commands::register_ops_command_modules` (uses $module) and
`json_output::ops::registered_ops_dispatch` (uses $variant and $handler).
Neither consumer ever referenced $args or $spec, so the fifteen
`CommandSpec` expressions duplicated from `ops_command_spec!` expanded to no
code at all — they were pure maintenance load, requiring every
safety-metadata edit to be made in two places with nothing enforcing the
pairing.

Delete both dead columns. Each row is now `(module, Variant, handler)`, the
ops `CommandSpec` lives once in `ops_command_spec!`, and the descriptor
table fits on readable lines — which matters because rustfmt does not format
`macro_rules!` bodies.

Adds `every_ops_descriptor_is_registered_in_the_ops_json_family`, which
asserts the invariant the deleted column only ever documented.

Refs #10323

* style(cli): rustfmt the GlobalArgs edits cargo fmt cannot reach

`cargo fmt --all` does not visit the fifteen ops command modules. They are
declared by `$(pub mod $module;)*` inside `register_ops_command_modules!`,
and rustfmt does not expand macros, so `commands/{daemon,deploy,logs,schedule,
ssh,status,triage,upgrade,...}.rs` and everything beneath them — including the
`#[cfg(test)] #[path = "../../tests/..."]` modules they pull in — are invisible
to the formatter. Verified empirically: appending `fn __fmt_probe(){let x=1;}`
to daemon.rs survives `cargo fmt --all` unformatted.

Consequence: those files carry pre-existing formatting drift (daemon.rs 11
blocks, deploy.rs 14, ssh.rs 3, triage.rs 3, status/mod.rs 5, ...) on main
today. This commit does not sweep that up. It only rustfmts the call sites the
GlobalArgs removal reflowed, so per-file `rustfmt --check` block counts are
<= main everywhere and this branch adds no new drift.

Refs #10322

* fix(cli): drop five forwarded _global arguments the sweep missed

CI caught five call sites that forwarded the parameter by its
underscore-prefixed name: contract/mod.rs:431, refactor.rs:455 and :460,
runner/dispatch.rs:466, and self_cmd.rs:147.

The underscore prefix only suppresses the unused-variable warning; it does
not make the binding unusable, and these five handlers genuinely read and
forwarded it. My verification grep matched the word `global`, which does not
match `_global` — so the sweep left the definitions correct and the callers
dangling (E0425 + E0061).

Refs #10322

* fix(cli): clear the two audit findings the GlobalArgs sweep introduced

The differential audit gate rejected the branch at current=21 base=20.
Reproduced locally with `homeboy review audit --changed-since origin/main`,
which named both:

- `structural::cli_surface/mod.rs::GodFile` — main sits at 1490 lines against
  a 1500 threshold, so the 47-line pinning test tripped it. Moved the test to
  its own `cli_surface/global_flag_surface_tests.rs`; `mod.rs` is now main
  plus three lines. Deliberately not splitting the existing 679-line inline
  `mod tests` block: doing so just moves the finding to `HighItemCount` (35
  top-level items against a threshold of 30), which I verified, and a proper
  `cli_surface/tests/` split is a separate change with real conflict surface.
- `Commands::commands/deploy.rs::SignatureMismatch` — removing the parameter
  left `pub fn run(\n mut args: DeployArgs,\n)` wrapped across three lines,
  which the signature normalizer read as a 4-token signature. Collapsed to one
  line, which is what rustfmt wants anyway and cannot do here (deploy.rs is
  macro-declared, so `cargo fmt` never reaches it).

`homeboy review audit` now reports zero unbaselined findings.

Refs #10322

---------

Co-authored-by: chubes-bot <266378653+homeboy-ci[bot]@users.noreply.github.com>

Author: chubes4

crates/homeboy-cli/src/cli_runtime.rs

@@ -14,7 +14,6 @@ use crate::commands;
 use crate::commands::cli;
 use crate::commands::output_runtime;
 use crate::commands::utils::{args, entity_suggest, resource_policy, response as output};
-use crate::commands::GlobalArgs;
 use homeboy::extension::{
     list_summaries, load_all_extensions, CliConfig,
     ExtensionManifest as InstalledExtensionManifest, ExtensionSummary,
@@ -359,7 +358,6 @@ impl CliRuntime {
     }
 
     fn run_matches(&self, matches: ArgMatches, normalized: Vec<String>) -> std::process::ExitCode {
-        let global = GlobalArgs {};
         let command_identity = command_identity_from_matches(&matches);
 
         // Extract --output early so it's available for all code paths (including
@@ -389,7 +387,7 @@ impl CliRuntime {
                 identifier: extension_cmd.project_id,
                 args: extension_cmd.args,
             };
-            let result = cli::run(cli_args, &global);
+            let result = cli::run(cli_args);
 
             let (json_result, exit_code) = output::map_cmd_result_to_json(result);
             output_runtime::emit_json_result_for_identity(
@@ -567,7 +565,6 @@ impl CliRuntime {
             commands::output_runtime::run_command(
                 cli.command,
                 command_spec,
-                &global,
                 output_file.as_deref(),
                 &command_identity,
             )

crates/homeboy-cli/src/cli_surface/global_flag_surface_tests.rs

@@ -0,0 +1,55 @@
+//! Pins the globally-propagated clap argument surface.
+//!
+//! Lives beside `cli_surface/mod.rs` rather than inside its `mod tests` block
+//! because that file sits 7 lines under the audit's 1500-line `god_file`
+//! threshold; anything added inline trips it.
+
+use super::Cli;
+use clap::CommandFactory;
+
+/// The globally-propagated flag set is a wire protocol, not just documentation:
+/// `homeboy-lab-runner` negotiates the lease-less recovery contract by parsing
+/// a remote binary's rendered `Options:` block
+/// (`negotiate_leaseless_recovery_contract`), and every `global = true`
+/// argument is rendered into that block for every subcommand. Pin the set so
+/// any addition or removal is a deliberate, reviewed protocol change.
+///
+/// This also anchors the invariant that motivated deleting the fieldless
+/// `GlobalArgs` handler parameter: process-wide CLI state is carried by these
+/// clap arguments on `Cli`, never by a separate struct threaded through
+/// command handlers.
+#[test]
+fn root_global_flag_surface_is_pinned() {
+    let mut longs: Vec<String> = Cli::command()
+        .get_arguments()
+        .filter(|arg| arg.is_global_set())
+        .filter_map(|arg| arg.get_long())
+        // `help`/`version` are clap-generated; this pins Homeboy-declared
+        // globals only.
+        .filter(|long| !matches!(*long, "help" | "version"))
+        .map(str::to_string)
+        .collect();
+    longs.sort();
+
+    assert_eq!(
+        longs.iter().map(String::as_str).collect::<Vec<_>>(),
+        vec![
+            "allow-dirty-lab-workspace",
+            "artifact-root",
+            "detach-after-handoff",
+            "lab-env-json",
+            "notification-route",
+            "notification-transport",
+            "output",
+            "placement",
+            "preserve-workspace-on-failure",
+            "runner",
+            "runner-env",
+            "runner-workspace-root",
+            "skip-deps-hydration",
+            "wait",
+        ],
+        "the globally-propagated flag surface changed; update remote \
+         capability negotiation and docs before accepting this",
+    );
+}

crates/homeboy-cli/src/cli_surface/mod.rs

@@ -1488,3 +1488,6 @@ mod tests {
         }
     }
 }
+
+#[cfg(test)]
+mod global_flag_surface_tests;

crates/homeboy-cli/src/command_contract/descriptors.rs

@@ -2,39 +2,56 @@
 
 /// Expands the Ops command descriptors into a consumer macro.
 ///
-/// Each row owns the command module, parsed Clap variant, contract metadata, and
-/// JSON handler binding. Consumers select the fields they need while preserving
-/// command-owned dynamic output and Lab predicates.
+/// Each row binds a command module to its parsed Clap variant and JSON handler.
+/// That is the whole descriptor: module registration and JSON dispatch are the
+/// only two things a `Commands` variant needs from this table.
+///
+/// Contract metadata (a `CommandSpec`) is deliberately **not** a column here. It
+/// lives once, in [`ops_command_spec`], because `spec.rs` splices the ops rows
+/// into a hand-ordered `COMMANDS` array at fifteen non-contiguous positions —
+/// a shape this block-emitting macro cannot produce. Carrying a second copy of
+/// the spec expressions in this table bought nothing: neither consumer ever
+/// referenced it, so the copies expanded to no code while still requiring every
+/// safety-metadata edit to be made twice.
+///
+/// Registry/parser parity is enforced by
+/// `cli_surface::tests::command_registry_manifest_and_docs_metadata_align`,
+/// which asserts a bijection between the clap subcommand set and
+/// `COMMAND_SPECS`. That guard is stronger than macro co-location: it catches a
+/// missing spec for *any* command, not just the ops family.
 #[macro_export]
 macro_rules! ops_command_descriptors {
     ($consumer:ident) => {
         $consumer! {
-            (ssh, Ssh, crate::commands::ssh::SshArgs, command_spec("ssh", CommandJsonFamily::Ops), crate::commands::ssh::run),
-            (server, Server, crate::commands::server::ServerArgs, CommandSpec { subcommand_safety: SERVER_SUBCOMMAND_SAFETY, ..command_spec("server", CommandJsonFamily::Ops) }, crate::commands::server::run),
-            (db, Db, crate::commands::db::DbArgs, CommandSpec { subcommand_safety: DB_SUBCOMMAND_SAFETY, ..command_spec("db", CommandJsonFamily::Ops) }, crate::commands::db::run),
-            (file, File, crate::commands::file::FileArgs, CommandSpec { subcommand_safety: FILE_SUBCOMMAND_SAFETY, ..command_spec("file", CommandJsonFamily::Ops) }, crate::commands::file::run),
-            (logs, Logs, crate::commands::logs::LogsArgs, command_spec("logs", CommandJsonFamily::Ops), crate::commands::logs::run),
-            (triage, Triage, crate::commands::triage::TriageArgs, command_spec_with_safety("triage", CommandJsonFamily::Ops, operator_safety(None, TRIAGE_DANGEROUS_FLAGS)), crate::commands::triage::run),
-            (deploy, Deploy, crate::commands::deploy::DeployArgs, command_spec_with_safety("deploy", CommandJsonFamily::Ops, operator_safety(Some("--dry-run"), DEPLOY_DANGEROUS_FLAGS)), crate::commands::deploy::run),
-            (harvest, Harvest, crate::commands::harvest::HarvestArgs, command_spec_with_safety("harvest", CommandJsonFamily::Ops, operator_safety(Some("--dry-run"), &["--apply"])), crate::commands::harvest::run),
-            (daemon, Daemon, crate::commands::daemon::DaemonArgs, command_spec("daemon", CommandJsonFamily::Ops), crate::commands::daemon::run),
-            (schedule, Schedule, crate::commands::schedule::ScheduleArgs, command_spec("schedule", CommandJsonFamily::Ops), crate::commands::schedule::run),
-            (status, Status, crate::commands::status::StatusArgs, command_spec("status", CommandJsonFamily::Ops), crate::commands::status::run),
-            (git, Git, crate::commands::git::GitArgs, CommandSpec { subcommand_safety: GIT_SUBCOMMAND_SAFETY, ..command_spec("git", CommandJsonFamily::Ops) }, crate::commands::git::run),
-            (self_cmd, SelfCmd, crate::commands::self_cmd::SelfArgs, CommandSpec { subcommand_safety: SELF_SUBCOMMAND_SAFETY, ..command_spec_with_output_notes("self", CommandJsonFamily::Ops, "inspects the active Homeboy runtime and renders built-in CLI documentation") }, crate::commands::self_cmd::run),
-            (api, Api, crate::commands::api::ApiArgs, CommandSpec { subcommand_safety: API_SUBCOMMAND_SAFETY, ..command_spec("api", CommandJsonFamily::Ops) }, crate::commands::api::run),
-            (upgrade, Upgrade, crate::commands::upgrade::UpgradeArgs, command_spec_with_output_notes_and_safety("upgrade", CommandJsonFamily::Ops, "upgrades the active Homeboy binary, extensions, runners, and services unless --check or skip flags are used", operator_safety(None, UPGRADE_DANGEROUS_FLAGS)), crate::commands::upgrade::run),
+            (ssh, Ssh, crate::commands::ssh::run),
+            (server, Server, crate::commands::server::run),
+            (db, Db, crate::commands::db::run),
+            (file, File, crate::commands::file::run),
+            (logs, Logs, crate::commands::logs::run),
+            (triage, Triage, crate::commands::triage::run),
+            (deploy, Deploy, crate::commands::deploy::run),
+            (harvest, Harvest, crate::commands::harvest::run),
+            (daemon, Daemon, crate::commands::daemon::run),
+            (schedule, Schedule, crate::commands::schedule::run),
+            (status, Status, crate::commands::status::run),
+            (git, Git, crate::commands::git::run),
+            (self_cmd, SelfCmd, crate::commands::self_cmd::run),
+            (api, Api, crate::commands::api::run),
+            (upgrade, Upgrade, crate::commands::upgrade::run),
         }
     };
 }
 
-/// Commands-free spec table for the ops command family.
+/// Canonical `CommandSpec` table for the ops command family.
+///
+/// This is the single source of truth for ops contract metadata. It is expanded
+/// inside `command_contract` (`spec.rs`), which cannot name `crate::commands`
+/// types, so it deliberately holds no Args type or handler binding — those live
+/// in [`ops_command_descriptors`], which is expanded only on the CLI side.
 ///
-/// This mirrors the `$spec` field of [`ops_command_descriptors`] but omits the
-/// `crate::commands` Args type and handler binding, so it can be expanded inside
-/// `command_contract` (e.g. `spec.rs`) without depending on the `commands`
-/// module. The full descriptor macro (with Args + handler) is expanded only on
-/// the CLI side.
+/// The per-name arms exist because `spec.rs` interleaves these rows with
+/// non-ops entries in one hand-ordered array; a single block-emitting arm could
+/// not be spliced into those positions.
 #[macro_export]
 macro_rules! ops_command_spec {
     (ssh) => { command_spec("ssh", CommandJsonFamily::Ops) };

crates/homeboy-cli/src/commands/activity.rs

@@ -16,7 +16,7 @@ use super::utils::response::{
     CommandActionableMetadata, CommandAgentTaskRef, CommandJobRef, CommandNextAction,
     CommandNextActionKind, CommandResultRefs, CommandRunRef,
 };
-use super::{CmdResult, GlobalArgs};
+use super::CmdResult;
 
 const TIMEOUT_EXIT_CODE: i32 = 124;
 
@@ -101,7 +101,7 @@ pub struct ActivityWatchOutput {
     pub notify: Option<NotifyOutcome>,
 }
 
-pub fn run(args: ActivityArgs, _global: &GlobalArgs) -> CmdResult<ActivityOutput> {
+pub fn run(args: ActivityArgs) -> CmdResult<ActivityOutput> {
     match args
         .command
         .unwrap_or(ActivityCommand::List(ActivityListArgs {

crates/homeboy-cli/src/commands/agent_task.rs

@@ -7,7 +7,7 @@
 use serde::Serialize;
 use serde_json::Value;
 
-use super::{CmdResult, GlobalArgs};
+use super::CmdResult;
 
 pub mod args;
 pub mod auth;
@@ -44,7 +44,7 @@ pub use args::{
 };
 pub(crate) use status::diagnostic_summary_from_aggregate;
 
-pub fn run(args: AgentTaskArgs, _global: &GlobalArgs) -> CmdResult<Value> {
+pub fn run(args: AgentTaskArgs) -> CmdResult<Value> {
     // Announce durable identity exactly once, on the first progress event that
     // carries a run id, and do it outside the TTY gate. Phase chatter stays
     // TTY-gated so non-interactive logs are not spammed, but the operator

crates/homeboy-cli/src/commands/api/auth.rs

@@ -10,7 +10,7 @@ use homeboy::core::server::auth_profiles::{
 };
 
 use crate::commands::utils::tty::{prompt, prompt_password};
-use crate::commands::{CmdResult, GlobalArgs};
+use crate::commands::CmdResult;
 
 #[derive(Args)]
 pub struct AuthArgs {
@@ -146,7 +146,7 @@ pub enum AuthOutput {
     ProfileRemove(ProfileRemoveResult),
 }
 
-pub fn run(args: AuthArgs, _global: &GlobalArgs) -> CmdResult<AuthOutput> {
+pub fn run(args: AuthArgs) -> CmdResult<AuthOutput> {
     match args.command {
         AuthCommand::Login {
             project,

crates/homeboy-cli/src/commands/api/http.rs

@@ -2,7 +2,7 @@ use clap::{Args, Subcommand};
 
 use homeboy::core::http_request::{self, HttpRequestInput, HttpRequestOutput};
 
-use crate::commands::{parse_key_val, CmdResult, GlobalArgs};
+use crate::commands::{parse_key_val, CmdResult};
 
 #[derive(Args)]
 pub struct HttpArgs {
@@ -54,7 +54,7 @@ pub(crate) struct RequestArgs {
     form: Vec<(String, String)>,
 }
 
-pub fn run(args: HttpArgs, _global: &GlobalArgs) -> CmdResult<HttpRequestOutput> {
+pub fn run(args: HttpArgs) -> CmdResult<HttpRequestOutput> {
     let input = match args.command {
         HttpCommand::Get(args) => build_input("GET", args),
         HttpCommand::Request {

crates/homeboy-cli/src/commands/api/mod.rs

@@ -93,10 +93,10 @@ pub enum ApiCommandOutput {
     Http(homeboy::core::http_request::HttpRequestOutput),
 }
 
-pub fn run(args: ApiArgs, global: &crate::commands::GlobalArgs) -> CmdResult<ApiCommandOutput> {
+pub fn run(args: ApiArgs) -> CmdResult<ApiCommandOutput> {
     match args.command {
-        ApiCommand::Auth(args) => map_nested(auth::run(args, global), ApiCommandOutput::Auth),
-        ApiCommand::Http(args) => map_nested(http::run(args, global), ApiCommandOutput::Http),
+        ApiCommand::Auth(args) => map_nested(auth::run(args), ApiCommandOutput::Auth),
+        ApiCommand::Http(args) => map_nested(http::run(args), ApiCommandOutput::Http),
         command => run_project(ApiArgs { command })
             .map(|(output, code)| (ApiCommandOutput::Project(output), code)),
     }

crates/homeboy-cli/src/commands/artifact_postprocess.rs

@@ -6,7 +6,7 @@ use homeboy::core::artifacts::{
 };
 use serde::Serialize;
 
-use super::{CmdResult, GlobalArgs};
+use super::CmdResult;
 
 #[derive(Args, Clone)]
 pub struct ArtifactPostprocessArgs {
@@ -37,10 +37,7 @@ pub struct ArtifactPostprocessCommandOutput {
     pub result: homeboy::core::artifacts::ArtifactPostprocessResult,
 }
 
-pub fn run(
-    args: ArtifactPostprocessArgs,
-    _global: &GlobalArgs,
-) -> CmdResult<ArtifactPostprocessCommandOutput> {
+pub fn run(args: ArtifactPostprocessArgs) -> CmdResult<ArtifactPostprocessCommandOutput> {
     let raw = homeboy::core::config::read_json_spec_to_string(&args.plan)?;
     let plan: ArtifactPostprocessPlan = serde_json::from_str(&raw).map_err(|error| {
         homeboy::core::Error::validation_invalid_json(