Resolve runner-owned runtime pins before local validation (#11918)

* fix(agent-task): resolve runner-owned runtime pins

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.

* fix(test): isolate runner pin resolution from transport

AI assistance: OpenAI gpt-5.6-sol via OpenCode was used to diagnose the Candidate Test shard failures, implement, 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

@@ -979,23 +979,7 @@ fn delegate_agent_task_lifecycle_to_pinned_runtime(
     let Some(run_id) = run_id else {
         return Ok(None);
     };
-    let Some(pinned) = crate::agents::agent_tasks::lifecycle::pinned_runtime_for_mutation(run_id)?
-    else {
-        return Ok(None);
-    };
-    let status = ProcessCommand::new(&pinned)
-        .args(&normalized_args[1..])
-        .status()
-        .map_err(|error| {
-            homeboy::core::Error::internal_io(
-                error.to_string(),
-                Some(format!(
-                    "execute pinned controller runtime {}",
-                    pinned.display()
-                )),
-            )
-        })?;
-    Ok(Some(status.code().unwrap_or(1)))
+    delegate_agent_task_lifecycle_to_resolved_runtime(run_id, normalized_args)
 }
 
 fn delegate_cook_continue_to_pinned_runtime(
@@ -1007,31 +991,59 @@ fn delegate_cook_continue_to_pinned_runtime(
     if current_runtime_owns_terminal_cook_continuation(&run_id)? {
         return Ok(None);
     }
+    delegate_agent_task_lifecycle_to_resolved_runtime(&run_id, normalized_args)
+}
+
+enum AgentTaskLifecyclePinnedRuntime {
+    Runner(crate::agents::agent_tasks::lifecycle::RunnerPinnedRuntime),
+    Controller(std::path::PathBuf),
+}
+
+/// Select runner authority before validating a controller-local pin. Historical
+/// runner records carry paths that are intentionally unavailable on controller.
+fn agent_task_lifecycle_pinned_runtime_for_mutation(
+    run_id: &str,
+) -> homeboy::core::Result<Option<AgentTaskLifecyclePinnedRuntime>> {
     if let Some(pinned) =
-        crate::agents::agent_tasks::lifecycle::runner_pinned_runtime_for_mutation(&run_id)?
+        crate::agents::agent_tasks::lifecycle::runner_pinned_runtime_for_mutation(run_id)?
     {
-        return delegate_cook_continue_to_runner_pinned_runtime(&pinned, normalized_args).map(Some);
+        return Ok(Some(AgentTaskLifecyclePinnedRuntime::Runner(pinned)));
+    }
+    Ok(
+        crate::agents::agent_tasks::lifecycle::pinned_runtime_for_mutation(run_id)?
+            .map(AgentTaskLifecyclePinnedRuntime::Controller),
+    )
+}
+
+fn delegate_agent_task_lifecycle_to_resolved_runtime(
+    run_id: &str,
+    normalized_args: &[String],
+) -> homeboy::core::Result<Option<i32>> {
+    match agent_task_lifecycle_pinned_runtime_for_mutation(run_id)? {
+        Some(AgentTaskLifecyclePinnedRuntime::Runner(pinned)) => {
+            delegate_agent_task_lifecycle_to_runner_pinned_runtime(&pinned, normalized_args)
+                .map(Some)
+        }
+        Some(AgentTaskLifecyclePinnedRuntime::Controller(pinned)) => {
+            let status = ProcessCommand::new(&pinned)
+                .args(&normalized_args[1..])
+                .status()
+                .map_err(|error| {
+                    homeboy::core::Error::internal_io(
+                        error.to_string(),
+                        Some(format!(
+                            "execute pinned controller runtime {}",
+                            pinned.display()
+                        )),
+                    )
+                })?;
+            Ok(Some(status.code().unwrap_or(1)))
+        }
+        None => Ok(None),
     }
-    let Some(pinned) = crate::agents::agent_tasks::lifecycle::pinned_runtime_for_mutation(&run_id)?
-    else {
-        return Ok(None);
-    };
-    let status = ProcessCommand::new(&pinned)
-        .args(&normalized_args[1..])
-        .status()
-        .map_err(|error| {
-            homeboy::core::Error::internal_io(
-                error.to_string(),
-                Some(format!(
-                    "execute pinned controller runtime {}",
-                    pinned.display()
-                )),
-            )
-        })?;
-    Ok(Some(status.code().unwrap_or(1)))
 }
 
-fn delegate_cook_continue_to_runner_pinned_runtime(
+fn delegate_agent_task_lifecycle_to_runner_pinned_runtime(
     pinned: &crate::agents::agent_tasks::lifecycle::RunnerPinnedRuntime,
     normalized_args: &[String],
 ) -> homeboy::core::Result<i32> {
@@ -1044,14 +1056,36 @@ fn delegate_cook_continue_to_runner_pinned_runtime(
             raw_exec: true,
             ..Default::default()
         },
-    )?;
+    )
+    .map_err(|error| annotate_runner_pinned_runtime_failure(error, &pinned.runner_id))?;
     if !output.stderr.is_empty() {
         eprint!("{}", output.stderr);
     }
     print!("{}", output.stdout);
     Ok(exit_code)
 }
 
+fn annotate_runner_pinned_runtime_failure(
+    mut error: homeboy::core::Error,
+    runner_id: &str,
+) -> homeboy::core::Error {
+    error.message = format!(
+        "runner `{runner_id}` could not execute its pinned controller runtime: {}",
+        error.message
+    );
+    if !error.details.is_object() {
+        error.details = serde_json::json!({});
+    }
+    error.details["runner_id"] = serde_json::json!(runner_id);
+    error.details["next_actions"] = serde_json::json!([
+        format!("homeboy runner status {runner_id}"),
+        format!("homeboy runner connect {runner_id}")
+    ]);
+    error.with_hint(format!(
+        "Verify runner `{runner_id}` is reachable, then retry the exact durable command."
+    ))
+}
+
 /// A terminal recipe-bound continuation is controller-owned. Provider execution
 /// remains pinned, but harvest, artifact hydration, gates, and finalization must
 /// run where the immutable Cook recipe is stored rather than on Lab.
@@ -3203,6 +3237,62 @@ mod tests {
         );
     }
 
+    #[test]
+    fn run_delegates_a_runner_owned_linux_v2_pin_before_controller_validation() {
+        crate::test_support::with_isolated_home(|_| {
+            let run_id = "runner-owned-linux-v2-run";
+            let plan: crate::agents::agent_tasks::scheduler::AgentTaskPlan = serde_json::from_str(
+                include_str!("../../../tests/fixtures/agent_task_smoke_plan.json"),
+            )
+            .expect("deserialize durable test plan");
+            crate::agents::agent_tasks::lifecycle::submit_plan(&plan, Some(run_id))
+                .expect("persist durable run");
+            crate::agents::agent_tasks::lifecycle::record_detached_lab_run(
+                crate::agents::agent_tasks::lifecycle::DetachedLabRunRecord {
+                    run_id,
+                    runner_id: "homeboy-lab",
+                    runner_job_id: "linux-v2-pin-job",
+                    remote_workspace: "/home/chubes/reaped-lab-workspace",
+                    remote_command: &[
+                        "homeboy".to_string(),
+                        "agent-task".to_string(),
+                        "run".to_string(),
+                    ],
+                },
+            )
+            .expect("persist runner authority");
+            crate::agents::agent_tasks::lifecycle::rewrite_record_for_test(run_id, |record| {
+                record.metadata[homeboy::core::controller_runtime::CONTROLLER_RUNTIME_METADATA_KEY] =
+                    serde_json::json!({
+                        "schema": "homeboy/controller-runtime-pin/v2",
+                        "originating": {
+                            "build_identity": "homeboy linux-runner",
+                            "pinned_executable": "/home/chubes/.local/share/homeboy/controller-runtimes/linux/homeboy",
+                            "sha256": "linux-runner-sha256"
+                        }
+                    });
+            })
+            .expect("persist runner-owned v2 pin");
+
+            let runtime = agent_task_lifecycle_pinned_runtime_for_mutation(run_id)
+                .expect("runner authority is selected before controller-local validation")
+                .expect("runner-owned v2 pin selects a runtime");
+            assert!(matches!(
+                runtime,
+                AgentTaskLifecyclePinnedRuntime::Runner(ref pinned)
+                    if pinned.runner_id == "homeboy-lab"
+                        && pinned.executable
+                            == std::path::Path::new("/home/chubes/.local/share/homeboy/controller-runtimes/linux/homeboy")
+            ));
+            assert_eq!(
+                crate::agents::agent_tasks::lifecycle::status(run_id)
+                    .expect("runtime resolution leaves the durable record intact")
+                    .run_id,
+                run_id
+            );
+        });
+    }
+
     #[cfg(unix)]
     #[test]
     fn terminal_cook_with_a_controller_recipe_does_not_route_to_lab_or_origin_runtime() {