fix(runs): route artifact queries to runners (#11913)

AI assistance: OpenAI gpt-5.6-sol via OpenCode was used to implement, review, and verify this change. Chris Huber reviewed and is responsible for every line.

Co-authored-by: Chris Huber <chris@chubes.net>

Author: chubes4

crates/homeboy-cli/src/cli_runtime.rs

@@ -1763,6 +1763,7 @@ fn is_interactive_shell() -> bool {
 
 fn normalize_runs_runner_options(cli: &mut Cli, normalized_args: &[String]) {
     if is_runs_list_runner_option(normalized_args)
+        || matches!(&cli.command, Commands::Runs(args) if args.is_artifacts())
         || is_runs_artifact_get_runner_option(normalized_args)
         || matches!(&cli.command, Commands::Runs(args) if args.is_artifact_get())
     {
@@ -2844,6 +2845,68 @@ mod tests {
         .expect("runs artifact get accepts global runner for command-local fetch");
     }
 
+    #[test]
+    fn runs_artifacts_command_local_runner_is_routable_for_runner_only_and_mirrored_runs() {
+        let _env = EnvGuard::remove(crate::core::observation::LAB_OFFLOAD_METADATA_ENV);
+
+        for run_id in ["runner-only-run", "mirrored-run"] {
+            let mut cli = Cli::parse_from([
+                "homeboy",
+                "runs",
+                "artifacts",
+                run_id,
+                "--runner",
+                "homeboy-lab",
+            ]);
+            let argv = vec![
+                "homeboy".into(),
+                "runs".into(),
+                "artifacts".into(),
+                run_id.into(),
+                "--runner".into(),
+                "homeboy-lab".into(),
+            ];
+
+            // Clap initially hydrates the global field. Normalize it into the
+            // command-local query option before generic Lab routing runs.
+            normalize_runs_runner_options(&mut cli, &argv);
+
+            assert_eq!(
+                cli.runner, None,
+                "{run_id} must not enter Lab offload routing"
+            );
+            let Commands::Runs(args) = &cli.command else {
+                panic!("expected runs command");
+            };
+            assert!(args.is_artifacts());
+            assert_eq!(args.artifacts_runner(), Some("homeboy-lab"));
+            crate::commands::route::route_after_parse(&cli, &argv, None)
+                .expect("command-local runner query is accepted");
+        }
+    }
+
+    #[test]
+    fn runs_artifacts_without_runner_remains_a_local_query() {
+        let _env = EnvGuard::remove(crate::core::observation::LAB_OFFLOAD_METADATA_ENV);
+        let mut cli = Cli::parse_from(["homeboy", "runs", "artifacts", "local-run"]);
+        let argv = vec![
+            "homeboy".into(),
+            "runs".into(),
+            "artifacts".into(),
+            "local-run".into(),
+        ];
+
+        normalize_runs_runner_options(&mut cli, &argv);
+
+        assert_eq!(cli.runner, None);
+        let Commands::Runs(args) = &cli.command else {
+            panic!("expected runs command");
+        };
+        assert!(args.is_artifacts());
+        assert_eq!(args.artifacts_runner(), None);
+        assert!(!args.has_command_local_runner_option());
+    }
+
     #[test]
     fn wrapper_global_runner_preserves_trailing_output_request() {
         let matches = Cli::command_with_scoped_lab_args()

crates/homeboy-cli/src/commands/infra/route.rs

@@ -3124,6 +3124,7 @@ fn is_runs_list_runner_option(args: &[String]) -> bool {
 
 fn is_command_local_runner_option(command: &Commands) -> bool {
     match command {
+        Commands::Runs(args) if args.has_command_local_runner_option() => true,
         Commands::AgentTask(crate::commands::agent_task::AgentTaskArgs {
             command: crate::commands::agent_task::AgentTaskCommand::Doctor(_),
         }) => true,

crates/homeboy-cli/src/commands/runs/dispatch.rs

@@ -5,7 +5,10 @@
 
 use homeboy::core::Error;
 
-use super::types::{RunsArgs, RunsArtifactArgs, RunsArtifactCommand, RunsCommand, RunsOutput};
+use super::types::{
+    RunsArgs, RunsArtifactArgs, RunsArtifactCommand, RunsArtifactGetArgs, RunsArtifactsArgs,
+    RunsCommand, RunsOutput,
+};
 use super::CmdResult;
 use super::{
     bench, compare, distribution, dossier, drift, evidence, findings, fuzz_compare, handlers,
@@ -63,6 +66,15 @@ impl RunsArgs {
             {
                 None
             }
+            (RunsCommand::Artifacts(args), Some(runner_id)) if args.runner.is_none() => {
+                args.runner = Some(runner_id);
+                None
+            }
+            (RunsCommand::Artifacts(args), Some(runner_id))
+                if args.runner.as_deref() == Some(runner_id.as_str()) =>
+            {
+                None
+            }
             (
                 RunsCommand::Artifact(RunsArtifactArgs {
                     command: RunsArtifactCommand::Get(args),
@@ -89,6 +101,17 @@ impl RunsArgs {
         }
     }
 
+    pub fn is_artifacts(&self) -> bool {
+        matches!(self.command, RunsCommand::Artifacts(_))
+    }
+
+    pub fn artifacts_runner(&self) -> Option<&str> {
+        match &self.command {
+            RunsCommand::Artifacts(args) => args.runner.as_deref(),
+            _ => None,
+        }
+    }
+
     pub fn is_markdown_mode(&self) -> bool {
         matches!(self.command, RunsCommand::Compare(ref compare) if compare::is_table_mode(compare))
     }
@@ -118,7 +141,15 @@ impl RunsArgs {
     pub fn has_command_local_runner_option(&self) -> bool {
         matches!(
             self.command,
-            RunsCommand::Artifact(RunsArtifactArgs {
+            RunsCommand::Artifacts(RunsArtifactsArgs {
+                runner: Some(_),
+                ..
+            }) | RunsCommand::Artifact(RunsArtifactArgs {
+                command: RunsArtifactCommand::Get(RunsArtifactGetArgs {
+                    runner: Some(_),
+                    ..
+                }),
+            }) | RunsCommand::Artifact(RunsArtifactArgs {
                 command: RunsArtifactCommand::Attach(_),
             })
         )
@@ -150,18 +181,6 @@ impl RunsArgs {
                     "Use `homeboy runs artifact get <run-id> <artifact-id>` for retrievable runner artifacts recorded in the local observation store.".to_string(),
                 ],
             ),
-            RunsCommand::Artifacts(args) => (
-                format!(
-                    "Lab-offloaded run records are mirrored locally; inspect run `{}` with `homeboy runs show {}` without top-level --runner.",
-                    args.run_id, args.run_id
-                ),
-                vec![
-                    format!("Run `homeboy runs artifacts {}` to list mirrored artifact records.", args.run_id),
-                    format!("Run `homeboy runs artifacts {} --pull` to retrieve runner/remote artifact bytes to the operator-local artifact root.", args.run_id),
-                    format!("Run `homeboy runs artifacts {} --runner {runner_id}` to query the connected runner daemon directly.", args.run_id),
-                    "Use `homeboy runs artifact get <run-id> <artifact-id> --runner <id>` to pull selected runner-side artifact bytes, or `homeboy --runner <id> runs artifact get <run-id> <artifact-id>` from Lab-oriented workflows.".to_string(),
-                ],
-            ),
             RunsCommand::Artifact(_) => (
                 "Runner artifact commands use the local mirrored observation store; rerun without top-level --runner.".to_string(),
                 vec![