fix: discover retained Cook artifacts by task id (#10668)

* fix: discover retained Cook artifacts by task id

* fix: classify retained artifact commands

* docs: update retained artifact CLI reference

* docs: preserve generated CLI reference EOF

Author: chubes4

crates/homeboy-agents/src/agent_task_lifecycle/workspace_authority.rs

@@ -20,6 +20,16 @@ pub struct WorkspaceTerminalAuthorityReceipt {
     pub remote_workspace: String,
 }
 
+/// A retained Lab workspace that remains authoritatively bound to one terminal
+/// agent task. Callers address files below this root relatively.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct RetainedWorkspace {
+    pub run_id: String,
+    pub runner_id: String,
+    pub runner_job_id: String,
+    pub remote_workspace: String,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 struct WorkspaceTerminalAuthorityRelease {
     schema: String,
@@ -39,6 +49,15 @@ fn authority_digest(run_id: &str, runner_id: &str, remote_workspace: &str) -> St
     format!("{:x}", digest.finalize())
 }
 
+fn run_index_path(run_id: &str) -> Result<PathBuf> {
+    let mut digest = Sha256::new();
+    digest.update(run_id.as_bytes());
+    Ok(paths::homeboy_data()?
+        .join("workspace-terminal-authority")
+        .join("by-run")
+        .join(format!("{:x}.json", digest.finalize())))
+}
+
 fn receipt_path(run_id: &str, runner_id: &str, remote_workspace: &str) -> Result<PathBuf> {
     Ok(paths::homeboy_data()?
         .join("workspace-terminal-authority")
@@ -112,7 +131,10 @@ fn persist_workspace_terminal_authority(receipt: WorkspaceTerminalAuthorityRecei
                     Error::internal_json(error.to_string(), Some(path.display().to_string()))
                 })?;
             if existing == receipt {
-                return Ok(());
+                return homeboy_core::engine::local_files::write_json_file_owner_only(
+                    &run_index_path(&receipt.run_id)?,
+                    &existing,
+                );
             }
             return Err(Error::validation_invalid_argument(
                 "workspace_terminal_authority",
@@ -121,7 +143,11 @@ fn persist_workspace_terminal_authority(receipt: WorkspaceTerminalAuthorityRecei
                 None,
             ));
         }
-        homeboy_core::engine::local_files::write_json_file_owner_only(&path, &receipt)
+        homeboy_core::engine::local_files::write_json_file_owner_only(&path, &receipt)?;
+        homeboy_core::engine::local_files::write_json_file_owner_only(
+            &run_index_path(&receipt.run_id)?,
+            &receipt,
+        )
     })
 }
 
@@ -187,6 +213,49 @@ pub fn resolve_workspace_terminal_authority(
     })
 }
 
+/// Resolve the retained Lab workspace for a terminal agent task without
+/// relying on a caller-provided runner path. A released receipt deliberately
+/// fails closed so callers can distinguish a reaped workspace from an empty
+/// discovery result.
+pub fn resolve_retained_workspace(run_id: &str) -> Result<RetainedWorkspace> {
+    let index_path = run_index_path(run_id)?;
+    if !index_path.exists() {
+        return Err(Error::validation_invalid_argument(
+            "run_id",
+            "agent task has no retained Lab workspace record",
+            Some(run_id.to_string()),
+            None,
+        ));
+    }
+    let receipt: WorkspaceTerminalAuthorityReceipt =
+        serde_json::from_slice(&std::fs::read(&index_path).map_err(|error| {
+            Error::internal_io(error.to_string(), Some(index_path.display().to_string()))
+        })?)
+        .map_err(|error| {
+            Error::internal_json(error.to_string(), Some(index_path.display().to_string()))
+        })?;
+    let receipt = resolve_workspace_terminal_authority(
+        run_id,
+        &receipt.runner_id,
+        &receipt.remote_workspace,
+        Some(&receipt.runner_job_id),
+    )?
+    .ok_or_else(|| {
+        Error::validation_invalid_argument(
+            "run_id",
+            "retained Lab workspace authority is unavailable; the workspace may have been reaped before artifacts were attached",
+            Some(run_id.to_string()),
+            None,
+        )
+    })?;
+    Ok(RetainedWorkspace {
+        run_id: receipt.run_id,
+        runner_id: receipt.runner_id,
+        runner_job_id: receipt.runner_job_id,
+        remote_workspace: receipt.remote_workspace,
+    })
+}
+
 pub fn workspace_terminal_authority_release_is_pending(
     run_id: &str,
     runner_id: &str,
@@ -335,6 +404,11 @@ mod tests {
             persist_workspace_terminal_authority(receipt)
                 .expect("terminal progression is idempotent");
 
+            assert!(resolve_retained_workspace("run-1")
+                .expect("discover from run id after record compaction")
+                .remote_workspace
+                .ends_with("workspace-1"));
+
             assert!(resolve_workspace_terminal_authority(
                 "run-1",
                 "reverse-or-direct",
@@ -350,6 +424,7 @@ mod tests {
                 Some("other-job")
             )
             .is_err());
+            assert!(resolve_retained_workspace("run-1").is_err());
             begin_workspace_terminal_authority_release(
                 "run-1",
                 "reverse-or-direct",

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

@@ -18,6 +18,7 @@ pub mod doctor;
 pub mod fanout;
 pub mod loop_definition;
 pub mod prompts;
+pub mod retained_artifacts;
 pub mod review;
 pub mod run;
 pub mod status;
@@ -39,8 +40,8 @@ pub use args::{
     CompileLoopArgs, ContractArgs, ContractFormat, CookContinueArgs, DiagnoseArgs, EvidenceArgs,
     FinalizePrArgs, GateFeedbackArgs, LatestArgs, ListArgs, LogsArgs, PromoteArgs,
     PromotionProviderArgs, ProvidersArgs, ReconcileRecordsArgs, ReplayProviderBoundaryArgs,
-    RetryArgs, ReviewArgs, RunPlanArgs, RuntimeRecoverArgs, RuntimeValidateArgs, StatusArgs,
-    SubmitArgs, VerifyGateArgs,
+    RetainedArtifactsArgs, RetainedArtifactsCommand, RetryArgs, ReviewArgs, RunPlanArgs,
+    RuntimeRecoverArgs, RuntimeValidateArgs, StatusArgs, SubmitArgs, VerifyGateArgs,
 };
 pub(crate) use status::diagnostic_summary_from_aggregate;
 
@@ -142,6 +143,7 @@ pub(crate) fn run_with_cook_progress(
         ),
         AgentTaskCommand::Logs(status_args) => status::logs(status_args),
         AgentTaskCommand::Artifacts(status_args) => status::artifacts(status_args),
+        AgentTaskCommand::RetainedArtifacts(args) => retained_artifacts::run(args),
         AgentTaskCommand::Evidence(evidence_args) => status::evidence(evidence_args),
         AgentTaskCommand::Diagnose(diagnose_args) => status::diagnose(diagnose_args),
         AgentTaskCommand::RuntimeRecover(args) => status::recover_runtime(args),

crates/homeboy-cli/src/commands/agent_task/args/definitions/command.rs

@@ -69,6 +69,8 @@ pub enum AgentTaskCommand {
     Latest(LatestArgs),
     Logs(LogsArgs),
     Artifacts(StatusArgs),
+    /// Discover or attach selected outputs retained in a terminal Lab Cook workspace.
+    RetainedArtifacts(RetainedArtifactsArgs),
     Evidence(EvidenceArgs),
     Diagnose(DiagnoseArgs),
     /// Recover a missing or corrupted immutable controller runtime pin.
@@ -180,6 +182,28 @@ pub struct AgentTaskControllerArgs {
     #[command(subcommand)]
     pub command: AgentTaskControllerCommand,
 }
+
+#[derive(Args, Debug)]
+pub struct RetainedArtifactsArgs {
+    #[command(subcommand)]
+    pub command: RetainedArtifactsCommand,
+}
+
+#[derive(Subcommand, Debug)]
+pub enum RetainedArtifactsCommand {
+    /// Resolve the retained workspace and print bounded, run-ID-only attach guidance.
+    Discover { run_id: String },
+    /// Attach one repository-relative file or directory from the retained workspace.
+    Attach {
+        run_id: String,
+        /// Repository-relative path below the retained workspace.
+        #[arg(long)]
+        path: String,
+        /// Durable artifact name to record on the owning run.
+        #[arg(long)]
+        name: String,
+    },
+}
 #[derive(Args, Debug)]
 pub struct ProvidersArgs {
     #[arg(long = "backend", value_name = "BACKEND")]

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

@@ -0,0 +1,125 @@
+//! Retained Lab Cook output discovery and adoption.
+//!
+//! This command deliberately accepts only an owning agent-task ID and a path
+//! relative to its immutable retained workspace receipt. It never exposes a
+//! caller-supplied runner root or creates a diagnostic runner job to inspect it.
+
+use std::path::{Component, Path};
+
+use serde::Serialize;
+use serde_json::{json, Value};
+
+use homeboy::agents::agent_task_lifecycle::resolve_retained_workspace;
+use homeboy::core::Error;
+
+use super::super::CmdResult;
+use super::args::{RetainedArtifactsArgs, RetainedArtifactsCommand};
+
+const RETAINED_ARTIFACTS_SCHEMA: &str = "homeboy/retained-agent-task-artifacts/v1";
+
+#[derive(Serialize)]
+struct RetainedWorkspaceOutput {
+    schema: &'static str,
+    command: &'static str,
+    run_id: String,
+    runner_id: String,
+    runner_job_id: String,
+    workspace_status: &'static str,
+    attachment_root: String,
+    attachment_path_policy: &'static str,
+    commands: RetainedArtifactCommands,
+}
+
+#[derive(Serialize)]
+struct RetainedArtifactCommands {
+    attach: String,
+    artifacts: String,
+}
+
+pub(super) fn run(args: RetainedArtifactsArgs) -> CmdResult<Value> {
+    match args.command {
+        RetainedArtifactsCommand::Discover { run_id } => discover(&run_id),
+        RetainedArtifactsCommand::Attach { run_id, path, name } => attach(&run_id, &path, &name),
+    }
+}
+
+fn discover(run_id: &str) -> CmdResult<Value> {
+    let workspace = resolve_retained_workspace(run_id)?;
+    let output = RetainedWorkspaceOutput {
+        schema: RETAINED_ARTIFACTS_SCHEMA,
+        command: "agent-task.retained-artifacts.discover",
+        run_id: workspace.run_id,
+        runner_id: workspace.runner_id,
+        runner_job_id: workspace.runner_job_id,
+        workspace_status: "retained",
+        attachment_root: ".".to_string(),
+        attachment_path_policy: "repository-relative; absolute and parent paths are rejected",
+        commands: RetainedArtifactCommands {
+            attach: format!(
+                "homeboy agent-task retained-artifacts attach {run_id} --path <relative-path> --name <artifact-name>"
+            ),
+            artifacts: format!("homeboy runs artifacts {run_id}"),
+        },
+    };
+    Ok((serde_json::to_value(output).unwrap_or(Value::Null), 0))
+}
+
+fn attach(run_id: &str, relative_path: &str, name: &str) -> CmdResult<Value> {
+    validate_relative_path(relative_path)?;
+    let workspace = resolve_retained_workspace(run_id)?;
+    let source_path = format!(
+        "{}/{}",
+        workspace.remote_workspace.trim_end_matches('/'),
+        relative_path
+    );
+    let artifact = crate::commands::runs::attach_runner_artifact(
+        workspace.run_id.clone(),
+        workspace.runner_id.clone(),
+        source_path,
+        name.to_string(),
+    )?;
+    Ok((
+        json!({
+            "schema": RETAINED_ARTIFACTS_SCHEMA,
+            "command": "agent-task.retained-artifacts.attach",
+            "run_id": workspace.run_id,
+            "runner_id": workspace.runner_id,
+            "runner_job_id": workspace.runner_job_id,
+            "workspace_status": "retained",
+            "relative_path": relative_path,
+            "artifact": artifact,
+        }),
+        0,
+    ))
+}
+
+fn validate_relative_path(path: &str) -> homeboy::core::Result<()> {
+    let path = Path::new(path);
+    if path.as_os_str().is_empty()
+        || path.is_absolute()
+        || path
+            .components()
+            .any(|component| matches!(component, Component::ParentDir | Component::RootDir))
+    {
+        return Err(Error::validation_invalid_argument(
+            "path",
+            "retained artifact path must be a non-empty repository-relative path without parent components",
+            Some(path.display().to_string()),
+            None,
+        ));
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn retained_artifact_paths_are_bounded_to_the_workspace() {
+        assert!(validate_relative_path("artifacts/result.json").is_ok());
+        assert!(validate_relative_path("/tmp/result.json").is_err());
+        assert!(validate_relative_path("artifacts/../secret.txt").is_err());
+        assert!(validate_relative_path("").is_err());
+    }
+}

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

@@ -47,6 +47,24 @@ pub use dispatch::{global_runner_error, run, run_markdown};
 pub use handlers::list_runs;
 pub use types::{RunsArgs, RunsOutput, HOSTED_BLUEPRINT_VIEWER};
 
+/// Attach a runner artifact from another command surface without exposing the
+/// `runs artifact` clap types outside this module.
+pub(crate) fn attach_runner_artifact(
+    run_id: String,
+    runner: String,
+    path: String,
+    name: String,
+) -> homeboy::core::Result<serde_json::Value> {
+    let (output, _) = remote_artifact::attach(types::RunsArtifactAttachArgs {
+        run_id,
+        runner,
+        path,
+        name,
+    })?;
+    serde_json::to_value(output)
+        .map_err(|error| homeboy::core::Error::internal_json(error.to_string(), None))
+}
+
 // Intra-module re-exports so sibling submodules (and the test modules) can
 // reference shared items via `super::` without depending on each other's
 // internal module paths. `pub(super)` items are re-exported with a private

crates/homeboy-cli/src/commands/utils/resource_policy/classification.rs

@@ -74,6 +74,16 @@ pub(super) fn agent_task_resource_behavior(
         // the answer describes (#9763).
         | agent_task::AgentTaskCommand::Providers(_)
         | agent_task::AgentTaskCommand::Review(_) => AgentTaskResourceBehavior::BoundedMetadataRead,
+        agent_task::AgentTaskCommand::RetainedArtifacts(retained) => match &retained.command {
+            // Discovery reads only the local immutable workspace receipt.
+            agent_task::RetainedArtifactsCommand::Discover { .. } => {
+                AgentTaskResourceBehavior::BoundedMetadataRead
+            }
+            // Attach may transfer a selected runner-side artifact and persists it.
+            agent_task::RetainedArtifactsCommand::Attach { .. } => {
+                AgentTaskResourceBehavior::AdmittedWorkload
+            }
+        },
         agent_task::AgentTaskCommand::Active(active) if !active.reconcile => {
             AgentTaskResourceBehavior::BoundedMetadataRead
         }