fix(runs): preserve legacy artifact API pagination (#11943)

AI assistance: OpenAI gpt-5.6-sol via OpenCode; used to implement mixed-version API compatibility, focused tests, and CLI reference regeneration.

Author: Chris Huber

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

@@ -231,31 +231,7 @@ fn active_runner_job_run_summary_if_durable(
 
 pub fn runner_artifacts(runner_id: &str, args: &RunsArtifactsArgs) -> CmdResult<RunsOutput> {
     let run_id = &args.run_id;
-    let mut query = Vec::new();
-    for (key, value) in [
-        ("token", args.token.as_deref()),
-        ("kind", args.kind.as_deref()),
-        ("mime", args.mime.as_deref()),
-        ("original_path", args.original_path.as_deref()),
-        ("path_suffix", args.path_suffix.as_deref()),
-        ("fixture", args.fixture.as_deref()),
-        ("surface", args.surface.as_deref()),
-        ("scenario", args.scenario.as_deref()),
-        ("name_glob", args.name_glob.as_deref()),
-    ] {
-        if let Some(value) = value {
-            query.push(format!("{key}={}", encode_uri_component(value)));
-        }
-    }
-    if !args.full {
-        query.push(format!("limit={}", args.limit.clamp(1, 1000)));
-        query.push(format!("offset={}", args.offset.max(0)));
-    } else {
-        query.push("full=1".to_string());
-    }
-    let query = (!query.is_empty())
-        .then(|| format!("?{}", query.join("&")))
-        .unwrap_or_default();
+    let query = artifact_query(args);
     let data = runner::daemon_api_get(
         runner_id,
         &format!("/runs/{}/artifacts{}", encode_uri_component(run_id), query),
@@ -295,6 +271,34 @@ pub fn runner_artifacts(runner_id: &str, args: &RunsArtifactsArgs) -> CmdResult<
     ))
 }
 
+fn artifact_query(args: &RunsArtifactsArgs) -> String {
+    let mut query = Vec::new();
+    for (key, value) in [
+        ("token", args.token.as_deref()),
+        ("kind", args.kind.as_deref()),
+        ("mime", args.mime.as_deref()),
+        ("original_path", args.original_path.as_deref()),
+        ("path_suffix", args.path_suffix.as_deref()),
+        ("fixture", args.fixture.as_deref()),
+        ("surface", args.surface.as_deref()),
+        ("scenario", args.scenario.as_deref()),
+        ("name_glob", args.name_glob.as_deref()),
+    ] {
+        if let Some(value) = value {
+            query.push(format!("{key}={}", encode_uri_component(value)));
+        }
+    }
+    if !args.full {
+        query.push(format!("limit={}", args.limit.clamp(1, 1000)));
+        query.push(format!("offset={}", args.offset.max(0)));
+    } else {
+        query.push("full=1".to_string());
+    }
+    (!query.is_empty())
+        .then(|| format!("?{}", query.join("&")))
+        .unwrap_or_default()
+}
+
 fn directory_publication_guidance_for_artifacts(
     artifacts: &[ArtifactRecord],
 ) -> Vec<RunsDirectoryArtifactPublicationGuidance> {
@@ -431,6 +435,19 @@ mod tests {
         assert!(guide.fetch_hint.contains("--runner <runner-id>"));
     }
 
+    #[test]
+    fn cli_artifact_listing_explicitly_requests_its_bounded_page() {
+        #[derive(clap::Parser)]
+        struct Wrapper {
+            #[command(flatten)]
+            args: RunsArtifactsArgs,
+        }
+
+        let args = <Wrapper as clap::Parser>::parse_from(["homeboy", "run-123"]).args;
+
+        assert_eq!(artifact_query(&args), "?limit=50&offset=0");
+    }
+
     #[test]
     fn append_missing_run_summaries_adds_active_runner_jobs_without_duplicates() {
         let mut runs = vec![RunSummary {

crates/homeboy-core/src/http_api.rs

@@ -239,35 +239,44 @@ where
         HttpEndpoint::RunArtifacts { id } => {
             let store = ObservationStore::open_initialized()?;
             require_run(&store, id)?;
-            let filter = ArtifactListFilter {
-                token: query_value(&request.path, "token"),
-                kind: query_value(&request.path, "kind"),
-                mime: query_value(&request.path, "mime"),
-                original_path: query_value(&request.path, "original_path"),
-                path_suffix: query_value(&request.path, "path_suffix"),
-                fixture: query_value(&request.path, "fixture"),
-                surface: query_value(&request.path, "surface"),
-                scenario: query_value(&request.path, "scenario"),
-                name_glob: query_value(&request.path, "name_glob"),
-                limit: if query_value(&request.path, "full").as_deref() == Some("1") {
-                    0
-                } else {
-                    query_value(&request.path, "limit")
+            // This route predates pagination. Keep an absent pagination request
+            // exhaustive for deployed old clients; new CLI clients opt in by
+            // sending `limit` and `offset` explicitly.
+            if query_value(&request.path, "limit").is_none()
+                && query_value(&request.path, "offset").is_none()
+            {
+                json!({
+                    "command": "api.runs.artifacts",
+                    "run_id": id,
+                    "artifacts": store.list_artifacts(id)?,
+                })
+            } else {
+                let filter = ArtifactListFilter {
+                    token: query_value(&request.path, "token"),
+                    kind: query_value(&request.path, "kind"),
+                    mime: query_value(&request.path, "mime"),
+                    original_path: query_value(&request.path, "original_path"),
+                    path_suffix: query_value(&request.path, "path_suffix"),
+                    fixture: query_value(&request.path, "fixture"),
+                    surface: query_value(&request.path, "surface"),
+                    scenario: query_value(&request.path, "scenario"),
+                    name_glob: query_value(&request.path, "name_glob"),
+                    limit: query_value(&request.path, "limit")
                         .and_then(|value| value.parse().ok())
-                        .unwrap_or(50)
-                },
-                offset: query_value(&request.path, "offset")
-                    .and_then(|value| value.parse().ok())
-                    .unwrap_or(0),
-            };
-            let page = store.list_artifacts_page(id, &filter)?;
-            json!({
-                "command": "api.runs.artifacts",
-                "run_id": id,
-                "artifacts": page.artifacts,
-                "page": { "total": page.total, "limit": page.limit, "offset": page.offset,
-                    "next_offset": (page.offset + page.artifacts.len() < page.total).then_some(page.offset + page.artifacts.len()) },
-            })
+                        .unwrap_or(50),
+                    offset: query_value(&request.path, "offset")
+                        .and_then(|value| value.parse().ok())
+                        .unwrap_or(0),
+                };
+                let page = store.list_artifacts_page(id, &filter)?;
+                json!({
+                    "command": "api.runs.artifacts",
+                    "run_id": id,
+                    "artifacts": page.artifacts,
+                    "page": { "total": page.total, "limit": page.limit, "offset": page.offset,
+                        "next_offset": (page.offset + page.artifacts.len() < page.total).then_some(page.offset + page.artifacts.len()) },
+                })
+            }
         }
         HttpEndpoint::RunArtifactContent { id, artifact_id } => artifact_content(id, artifact_id)?,
         HttpEndpoint::RunFindings { id } => {

docs/commands/runs.md

@@ -17,7 +17,7 @@ homeboy runs show <run-id> [--format json|--json]
 homeboy runs dossier <run-id> [--format json|--json]
 homeboy runs resume-plan <run-id>
 homeboy runs evidence <run-id>
-homeboy runs artifacts <run-id> [--runner <runner-id>] [--pull] [--pull-dir <dir>]
+homeboy runs artifacts <run-id> [--runner <runner-id>] [--pull] [--pull-dir <dir>] [--limit <count>] [--offset <count>] [--full]
 homeboy runs refs [--kind bench] [--component <id>] [--rig <id>] [--status <status>] [--since 24h] [--artifact-kind <kind>] [--aggregate-artifact-kind <kind>]
 homeboy runs artifact attach <run-id> --runner <runner-id> --path <runner-path> --name <artifact-name>
 homeboy runs artifact get <run-id> <artifact-id> [--runner <runner-id>] [--output <path>]
@@ -116,6 +116,8 @@ for generic runner, static HTML, and matrix examples.
 
 `homeboy runs artifacts <run-id> --runner <runner-id>` queries a connected runner daemon for the run's artifact records from the controller machine. `homeboy runs artifact get <run-id> <artifact-id> --runner <runner-id>` pulls selected runner-side artifact bytes through that connection into the local artifact cache, or into `--output` when provided, and reports the runner id plus source content path in JSON output. The Lab-oriented wrapper form `homeboy --runner <runner-id> runs artifact get <run-id> <artifact-id>` is accepted for the same fetch path. Use these commands when a controller-side agent has a run id and artifact id but should not SSH into the runner or know runner filesystem paths.
 
+`homeboy runs artifacts` requests a 50-record page by default and returns `page.total`, `page.offset`, and `page.next_offset`; use `--limit` and `--offset` to traverse a larger inventory. `--full` explicitly requests the exhaustive legacy listing and derived summaries. The daemon HTTP route remains mixed-version compatible: `GET /runs/<run-id>/artifacts` without pagination parameters keeps its original exhaustive response, while callers that send `limit` or `offset` receive the paginated response.
+
 `homeboy runs artifact attach <run-id> --runner <runner-id> --path <runner-path> --name <artifact-name>` copies an existing runner-side file into the local persisted artifact store and records it against an existing run. The runner path must be absolute and under the runner's configured `workspace_root`, `policy.workspace_roots`, or `HOMEBOY_ARTIFACT_ROOT` output root. Use this for post-run evidence files that already exist on the runner; it does not promote runner exec output or infer changed files.
 
 `homeboy runs artifact cleanup-downloads` plans cleanup for local runner artifact downloads under Homeboy's artifact root (`<artifact-root>/runner`). By default it is a dry run; pass `--apply` to remove the planned cache directories. Removal is per `<runner-id>/<run-id>` cache directory, never whole-root, and a cache is reclaimable only when its *newest* byte is at least 24 hours old and no non-terminal run claims it. That floor is fixed and deliberately not exposed as a flag: this cache holds bytes an operator asked for. Anything else under the root — a loose file, a symlink, an entry that is not the canonical `<runner-id>/<run-id>` shape — is reported and never removed, and an unreadable modification time or an unavailable observation store retains rather than releases. Use `--runner` and `--run-id` to narrow *which* caches are considered; they never waive the predicate. A cache directory is only reclaimable at all when the writer tagged it `internal_fetch` in its `.homeboy-download.json` marker; an operator pull, an unreadable marker, and an absent marker all retain, and each row reports which case it was in its `intent` field. This category is excluded from a bare `homeboy cleanup --apply` and requires `homeboy cleanup --include runner-downloads`. See [cleanup](cleanup.md#why-runner-downloads-is-opt-in-only).

docs/reference/cli/commands/index.md

@@ -6,7 +6,7 @@ Hand-written narrative for these commands lives in `docs/commands/`. -->
 
 # Homeboy CLI reference (generated)
 
-`homeboy` exposes 549 visible commands across 41 top-level command families. Every page below is generated from the clap command tree in `crates/homeboy-cli`, so it cannot drift from the binary.
+`homeboy` exposes 552 visible commands across 41 top-level command families. Every page below is generated from the clap command tree in `crates/homeboy-cli`, so it cannot drift from the binary.
 
 Hand-written narrative lives in the [commands index](../../../commands/commands-index.md). Global flags are documented in [the root command reference](../homeboy-root-command.md). Machine-readable safety, docs, output, and Lab metadata come from `homeboy contract manifest`.
 

docs/reference/cli/commands/release.md

@@ -29,6 +29,8 @@ Plan release workflows
 | `-p`, `--project` | `<PROJECT>` | Release all components in a project that need a release |
 | `--outdated` | flag | Only release components with unreleased code commits (use with --project) |
 | `--path` | `<PATH>` | Override local_path for version file lookup (single component only) |
+| `--preflight-runner` | `<RUNNER_ID>` | Run portable lint and test release gates through the existing Lab review commands before controller-owned release mutation |
+| `--preflight-placement` | `<PREFLIGHT_PLACEMENT>` | Placement policy for portable release preflight gates Values: `local`, `lab`. |
 | `--dry-run` | flag | _no help text_ |
 | `--apply` | flag | Confirm risky release execution modes |
 | `--deploy` | flag | Deploy to all projects using this component after release |
@@ -58,6 +60,7 @@ Plan release workflows
 | `homeboy release artifact-source-authority` | Write a source-authority manifest for assembled release artifacts |
 | `homeboy release contains` | Report which release first contained a commit, and whether the installed build has it |
 | `homeboy release gap` | Report how far the installed build is behind the newest release |
+| `homeboy release readiness` | Inspect retained portable release-readiness evidence |
 
 ## `homeboy release changes`
 
@@ -182,3 +185,40 @@ Report how far the installed build is behind the newest release
 | `--component` | `<COMPONENT_ID>` | Component whose release tag namespace to search (default: the component discovered from the working directory) |
 | `--path` | `<PATH>` | Checkout to inspect directly. Useful for unregistered clones, CI runners, and worktrees |
 | `--installed` | `<VERSION>` | Version to treat as installed instead of the running binary's version |
+
+## `homeboy release readiness`
+
+```sh
+homeboy release readiness <COMMAND>
+```
+
+Inspect retained portable release-readiness evidence
+
+| Subcommand | Summary |
+| --- | --- |
+| `homeboy release readiness show` | Show one retained readiness operation by operation:// reference or ID |
+| `homeboy release readiness list` | List retained readiness operations for a component |
+
+## `homeboy release readiness show`
+
+```sh
+homeboy release readiness show <REFERENCE>
+```
+
+Show one retained readiness operation by operation:// reference or ID
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `<REFERENCE>` | yes | _no help text_ |
+
+## `homeboy release readiness list`
+
+```sh
+homeboy release readiness list <COMPONENT_ID>
+```
+
+List retained readiness operations for a component
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `<COMPONENT_ID>` | yes | _no help text_ |

tests/core/http_api_test.rs

@@ -892,6 +892,43 @@ fn test_handle() {
     });
 }
 
+#[test]
+fn run_artifacts_keeps_legacy_http_clients_exhaustive_and_pages_explicit_requests() {
+    with_isolated_home(|home| {
+        let _xdg = XdgGuard::unset();
+        let store = ObservationStore::open_initialized().expect("store");
+        let run = store
+            .start_run(sample_run("bench", "homeboy", "artifact-pagination"))
+            .expect("run");
+        let artifact_path = home.path().join("artifact.json");
+        std::fs::write(&artifact_path, b"{}").expect("artifact");
+        for index in 0..51 {
+            store
+                .record_artifact(&run.id, &format!("artifact-{index}"), &artifact_path)
+                .expect("record artifact");
+        }
+
+        let legacy = http_api::handle(HttpApiRequest {
+            method: HttpMethod::Get,
+            path: format!("/runs/{}/artifacts", run.id),
+            body: None,
+        })
+        .expect("legacy artifacts");
+        assert_eq!(legacy.body["artifacts"].as_array().unwrap().len(), 51);
+        assert!(legacy.body.get("page").is_none());
+
+        let paged = http_api::handle(HttpApiRequest {
+            method: HttpMethod::Get,
+            path: format!("/runs/{}/artifacts?limit=50&offset=0", run.id),
+            body: None,
+        })
+        .expect("paged artifacts");
+        assert_eq!(paged.body["artifacts"].as_array().unwrap().len(), 50);
+        assert_eq!(paged.body["page"]["total"], 51);
+        assert_eq!(paged.body["page"]["next_offset"], 50);
+    });
+}
+
 #[test]
 fn runs_list_reconciles_old_ownerless_running_records_before_responding() {
     with_isolated_home(|_home| {