Inspect and maintain persisted observation-store runs and artifacts.

Friction

homeboy runs friction --last 7d ranks refusal codes, immediate same-command reruns within caller sessions, highest-intervention Cooks, and gate-green but unpublished candidates. --last N selects recent invocations (maximum 1000); duration windows are also capped at 1000 and report truncated when bounded. --component selects invocations targeting Cooks in that component.

The best-effort ledger stores terminal cli-invocation rows in the existing run store, with normal terminal-run retention. It records subcommand names, exit and structured error codes/fields, elapsed milliseconds, build version, bounded caller session identity, and an explicitly named run/Cook id—not argv or error messages. Internal recovery children and store-free startup probes/help fast paths are excluded. Recording failures do not affect command output or exit status.

Cook intervention counts cover commands after submission within the selected ledger window. Submission-to-PR timing uses the existing successful publish span and is null when that evidence is unavailable. Delivery facts, rather than inferred command success, determine stranded green candidates. Version-comparison notifications remain on runs hotspots; friction leaves that comparator/outbox integration separate rather than duplicating notification behavior.

Synopsis

homeboy runs list [--runner <runner-id>] [--kind bench|rig|trace|agent-task] [--component <id>] [--rig <id>] [--scenario <id>] [--status <status>] [--limit 20] [--include-active-runner-jobs]
homeboy runs distribution --field <metadata.path> [--kind bench] [--component <id>] [--rig <id>] [--scenario <id>] [--status <status>] [--limit 20]
homeboy runs latest-run [--kind bench|rig|trace|agent-task] [--component <id>] [--rig <id>] [--status <status>]
homeboy runs compare [--kind bench] [--component <id>] [--rig <id>] [--scenario <id>] [--metric <name>] [--limit 20] [--format table|json]
homeboy runs compare --kind bench --from-run <run-id> --to-run <run-id> [--metric <name>]
homeboy runs compare --kind fuzz --from-run <run-id> --to-run <run-id> [--hotspot-policy <advisory|blocking|off>]
homeboy runs friction [--last <duration|N>] [--component <id>]
homeboy runs hotspots <run-id>... [--limit <count>]
homeboy runs hotspots --coverage <run-id>... [--limit <count>]
homeboy runs hotspots --baseline-run <run-id> --candidate-run <run-id> [--limit <count>]
homeboy runs logs <run-id> [--cursor <cursor>]
homeboy runs show <run-id> [--format json|--json]
homeboy runs evidence <run-id> [--proof|--dossier] [--full] [--kind <kind>] [--task <task-id>] [--failure-only] [--format json|--json] [-q <jsonpath>...]
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-or-name> [--runner <runner-id>] [--to <path>]
homeboy runs artifact get-handle <opaque-handle> [--output <path>]
homeboy runs artifact preview-handle <opaque-handle> [--port <port>]
homeboy runs artifact postprocess [OPTIONS] <PLAN>
homeboy runs artifact cleanup-downloads [--runner <runner-id>] [--run-id <run-id>] [--apply]
homeboy runs artifact cleanup-persisted [--older-than-days <days>] [--run-id <run-id>] [--apply]
homeboy runs findings <run-id> [--tool <tool>] [--file <path>] [--fingerprint <fingerprint>] [--limit 100]
homeboy runs export --run <run-id> --output <dir>
homeboy runs export --since <duration> --output <dir>
homeboy runs import <dir>
homeboy runs import --from-gh-actions --component <id> --repo <owner/repo> --workflow <workflow.yml> --artifact-glob <glob>
homeboy runs import --from-gh-actions --component <id> --repo <owner/repo> --run-id <gh-run-id> --artifact-glob <glob>
homeboy runs report failure-digest --output-dir <dir> --results <json>

Description

homeboy runs is the inspection and maintenance surface for Homeboy’s local observation store. Producers such as bench, rig, and trace write run and artifact records; this command lets humans and agents inspect that evidence without opening SQLite directly, export/import portable bundles, render typed report projections, and run explicit cleanup or reconciliation tasks.

Durable logs

homeboy runs logs <run-id> [--cursor <cursor>] reads the canonical durable ControlPlaneEventPage through the agent-task service, not the observation store. Run and Cook IDs resolve exactly as in other durable lifecycle reads. Resume with the opaque cursor returned by the page. The command preserves the compact human log summary and the canonical JSON payload; no task filter or limit flag is exposed.

Failure digest

homeboy runs report failure-digest --output-dir <dir> --results <json> renders a Markdown failure digest from Homeboy command output JSON files and prints it directly.

homeboy runs artifacts and homeboy runs evidence also accept durable agent-task mission and attempt IDs. Mission IDs select the current Cook candidate using the lifecycle resolver. These reads use lifecycle-owned artifacts and evidence (not observation-store copies), preserve the Cook payload schemas, and include source: "agent_task_lifecycle". Use artifacts --show <artifact-id> [--tail <lines>] for artifact contents; evidence --kind <kind>, --task <task-id>, and --failure-only select Cook evidence. --full disables the bounded collection preview. Non-agent-task run projections are unchanged.

homeboy runs list reads only the local observation store by default. Pass --include-active-runner-jobs to also append active jobs from connected runner daemons, which may inspect runner sessions. homeboy runs list --runner <runner-id> queries a connected runner daemon instead of the local observation store, preserving the normal runs.list JSON payload while returning evidence from the runner machine. For benchmark records, --scenario <id> filters to runs whose stored metadata includes that scenario.

Use homeboy runs list --running for in-flight observation runs, homeboy runs list --kind agent-task for durable cooks and attempts, and homeboy runner status for runner-resident work.

The JSON output includes stable run fields: run id, kind, status, timestamps, component id, rig id, git SHA, command, cwd, metadata, and artifact records where relevant.

Workflow instance ids (wf-…) are a controller-local run kind: runs show <wf-id> returns the daemon workflow view, and runs watch <wf-id> streams step progress to stderr and follows chain successors. Watch honors --interval, --timeout (default 5m), and --forever; workflow notifications via --notify are not supported. runs list --kind workflow returns the daemon’s workflow instances; observation/Cook discovery filters are rejected. Use workflow list for registered definitions and daemon cadences, and keep mutations under workflow.

homeboy runs show <run-id> prints a bounded, action-first human summary by default: terminal status, failure digest, recorded recovery commands, run identity, key case artifacts, and up to eight primary artifact locators with concise homeboy runs artifact get <run-id> <artifact-id> commands. Its default command-result data is bounded too: it retains phase/state, root cause, the authoritative runner terminal projection, legal recovery, artifact refs, and explicit detail refs instead of embedding handoff, event, source-snapshot, transcript, or runtime payloads. Cleanup-inventory artifacts are omitted whenever primary evidence exists, and every omission is declared with the runs artifacts command for the complete inventory. The summary always ends with explicit refs for the full run JSON, failure/evidence detail, and full artifacts. This makes failures and their recovery path visible without spelunking temp directories while preserving all persisted evidence behind explicit detail commands. Coverage rendering is schema-blind and only uses generic metadata fields such as coverage_summary, coverage_gaps, surface_count, operation_count, exercised_count, skipped_count, failed_count, declared_count, executable_count, proven_count, skipped_reason_counts, and skipped_reasons; key case artifact detection uses generic artifact id/kind/name markers such as key_case, fuzz_case, failing_case, case_artifact, and repro_case. Pass --format json (or the equivalent legacy --json) for the full structured payload on stdout; it is also always written to --output <file>.

homeboy runs evidence <run-id> --dossier aggregates the existing read-only run inspection surfaces into one actionable report. It includes status and stale/failure category, failure/gate data when recorded, run/job/handoff/result refs when present in generic metadata, redacted environment provenance counts, artifact/evidence refs with reviewer-visible versus operator-local hints, inspection commands, and repair/next commands only when existing data supports them. The command reads the observation store and artifact registry; it does not mutate runs, artifacts, or external systems. Pass --format json (or the equivalent legacy --json) for the full structured payload.

runs show, runs evidence <id> --proof, and runs evidence <id> --dossier share the canonical presentation vocabulary (--format {auto,json,markdown,text} and --detail {summary,full}). --format json and the legacy --json bool are exactly equivalent; either alone is enough and passing both agrees. --detail is accepted for symmetry with the rest of the CLI: these commands render their documented default at both levels, so the compact human summary stays the default and the full payload stays behind --format json.

homeboy runs evidence <run-id> --proof projects compact verdict, gate-failure, and declared proof/scorecard signals. --proof and --dossier are mutually exclusive and retain their distinct JSON schemas and human summaries. Without either flag, evidence keeps its bounded report by default and its complete registry report with --full.

For full-coverage claims, prefer persisted evidence that distinguishes declared, executable, and proven states. A declared surface/workload is inventory, an executable surface/workload has a runnable command or manifest path, and a proven surface/workload has a persisted run plus reviewer-visible coverage/case artifacts or fetch commands. runs show, runs artifacts, and runs evidence surface those cues generically; missing proven counts or missing artifacts should be treated as incomplete proof.

homeboy runs refs emits a compact machine-readable ref index for matching runs. It is intended for matrix orchestration scripts and agents that need stable run refs and aggregate artifact refs without scraping human stdout. The output includes homeboy://run/<id> refs, homeboy://run/<id>/artifact/<artifact-id> refs, evidence/artifact follow-up commands, and detected aggregate artifact refs. Aggregate detection is schema-blind by default (aggregate in artifact id/kind/path); pass --aggregate-artifact-kind <kind> to mark additional artifact kinds as aggregate outputs.

homeboy --output json runs refs --kind bench --component studio --rig studio-bfb --since 24h
homeboy --output json runs refs --kind trace --component gutenberg --aggregate-artifact-kind trace_summary

homeboy runs evidence <run-id> emits a byte- and cardinality-bounded operator projection: run status, failure summary, selected failure.diagnostic, its exact continuation, artifact totals, and returned/omitted counts. The complete pretty-serialized homeboy/command-result/v3 envelope is capped at 16,384 bytes for both stdout and --output; when necessary, optional artifact rows and guidance are omitted deterministically while schema, status, counts, and the selected diagnostic handle remain available. Standard bounded run IDs remain exact in run_id, complete_command, and full_report_command; an abnormal persisted ID that exceeds the public budget causes those optional locator fields to be omitted rather than truncated. Each returned artifact carries a stable opaque ah_... handle derived from durable ownership identity; homeboy runs artifact get-handle <opaque-handle> resolves file artifacts and homeboy runs artifact preview-handle <opaque-handle> safely serves directory artifacts without a run id, ordinal, name token, or shell interpolation. The selected diagnostic is first in the bounded artifact list; strings are deterministically shortened with an omitted-byte marker. The output is explicitly versioned as homeboy/runs-evidence-summary/v1 under the evidence_summary variant. Consumers that require the established lossless evidence variant must use --full; this preserves the prior report schema unchanged. Use runs artifacts <run-id> for the full artifact inventory, or -q/--field with JSONPath selectors such as -q '$.failure.diagnostic' for a narrow machine-readable projection. Lab sibling artifacts sharing the runner job are included in both views. Local operator files are represented as non-reviewer-visible handles with a fetch command instead of absolute machine paths. Directory diagnostics continue with runs artifact preview-handle, and URL diagnostics continue with their validated URL. Lab-specific publication or mirroring policy belongs in runner/extension enrichment, not in the generic evidence serializer.

Evidence manifest

Every runs evidence report carries an evidence_manifest: the run’s interpretation contract (homeboy/evidence-manifest/v1). It answers what does this evidence mean and what is blocking in one place, so an orchestrator does not have to re-derive that from status strings, gate failures, and artifact addresses.

evidence_manifest.source says where the interpretation came from and is stamped by Homeboy, not by the producer:

An attached manifest always wins and is surfaced verbatim — Homeboy never overwrites a producer’s judgement. A manifest that fails to parse or fails contract validation is reported in evidence_manifest_errors and a derived manifest is used instead, so a producer bug is visible rather than silent.

A derived manifest is a mechanical reading, not a judgement. Treat it as such: gate it on source == "derived" if a decision needs an independent assertion. It maps run status to status.state conservatively — a status label Homeboy does not own becomes unknown rather than a guess, and a run recorded as passing that also recorded a critical blocker is reported as blocked. interpretation.confidence grades reviewability: low for a non-terminal run or one with no artifacts, medium when every artifact is operator-local, high when at least one reviewer-visible evidence link exists.

Producers can validate a candidate manifest before attaching it:

homeboy contract show evidence-manifest
homeboy contract validate homeboy/evidence-manifest/v1 --file manifest.json

When a run passed but runs evidence has zero artifacts, the command completed but did not produce reviewable evidence. Preserve the run id and output directory, then promote or attach artifacts through the command-specific surface when it is available. See Artifact loop for runner and matrix workflows for generic runner, static HTML, and matrix examples.

homeboy runs artifacts <run-id> --pull retrieves every retrievable artifact’s bytes for a run to the operator-local artifact root in one pass, so a completed run is self-contained instead of pointing only at runner-resident paths or non-resolving tunnel URLs. The retrieval is best-effort and per-artifact: the listing still prints, and the JSON output gains a pull summary where each artifact reports already_local (file/directory already on the controller), pulled (bytes copied from a runner/remote store), skipped (metadata-only or non-file artifacts), or failed (with the error message) — so it is clear exactly which diagnostics are unreachable and why. Pass --pull-dir <dir> to write pulled bytes into a chosen directory instead of the default run-scoped path under the artifact root. --pull operates on the local mirrored observation store and is mutually exclusive with --runner.

homeboy runs artifact get accepts storage IDs, producer artifact IDs, and unique artifact names through the same resolver. --to <path> (also --output / -o) selects the destination file. Without it the file is named after the artifact in the current directory, never after a temporary source filename. JSON always reports an absolute output_path.

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 a named local file, or into --to 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.

homeboy runs artifact cleanup-persisted plans cleanup for persisted local run artifacts and their database records. By default it is a dry run; pass --apply to delete planned artifact files/directories and remove their database rows. --older-than-days and --limit default to the configured retention.terminal_run_days and retention.limit rather than to command-local literals, so this specialist and homeboy cleanup --include persisted-run-artifacts always apply the same window; the resolved policy is echoed as retention in the JSON output. Artifacts owned by a run that is still active or whose lifecycle state cannot be read are never released, and no flag widens that.

homeboy runs retention was removed. It carried no argument the aggregate could not express, so homeboy cleanup --include terminal-runs [--older-than-days <days>] [--limit <n>] [--apply] is now the only surface for terminal observation-record retention. See Cleanup Retention Scope.

homeboy runs artifact postprocess <PLAN> runs a generic artifact postprocess plan over declared persisted artifact roots and emits the artifact-postprocess result contract. The plan can be a JSON file, @file spec, or - for stdin. Use --artifact-root-id and --input-root-id to select named roots from the plan, --result <path> to write the bare result contract, and --run-id <id> when a Lab invocation must persist produced artifacts as resolvable run evidence.

homeboy runs reconcile marks orphaned running observation records stale. Treat it as a mutating maintenance command, not a reader.

homeboy runs distribution aggregates categorical values from dot-separated JSON metadata paths. Scalar string, number, and boolean values are counted directly; arrays are flattened and counted by scalar element. The output reports inspected runs, matched/missing runs per field, total and unique value counts, value percentages, and repeated values.

homeboy runs latest-run selects the newest run that matches the provided filters. latest-run is useful when automation starts from component/kind/status context instead of a known run id.

homeboy runs findings lists recorded findings for a run.

Compare Metrics Across History

homeboy runs compare compares selected persisted metrics across recent observation runs. It defaults to benchmark history and the total_elapsed_ms metric:

homeboy runs compare --kind bench --component studio --metric total_elapsed_ms --limit 20
homeboy runs compare --kind bench --component studio --rig studio-bfb --scenario studio-agent-site-build --metric total_elapsed_ms --metric p95_ms

The default output is a Markdown table with run id, status, start time, git SHA, rig id, artifact count, scenario, and selected metric columns. Use --format=json for structured output, or pair it with global --output <file> to write command JSON to disk:

homeboy runs compare --kind bench --component studio --metric total_elapsed_ms --format=json --output runs-compare.json

Metric lookup supports top-level run metadata such as results.total_elapsed_ms, direct dotted paths, and benchmark scenario metrics recorded under scenario_metrics[].metrics or metric_groups.

With --from-run <baseline-run-id> --to-run <candidate-run-id>, runs compare compares two exact runs through the kind’s adapter on the shared compare engine (the same engine behind --baseline/--ratchet and homeboy fuzz compare). Run-to-run output is always JSON.

• --kind bench compares the numeric metrics recorded in two benchmark runs. It refuses runs with a different shared benchmark context (settings, scenarios, workloads, iterations, runs, concurrency) and reports both run IDs, component state, the shared context, metric deltas (every metric either run recorded, or those selected with --metric), missing metrics, and a Markdown table under reports.markdown.
• --kind fuzz compares the persisted fuzz result envelope artifacts of two runs. It resolves fuzz_result_envelope artifacts from the observation store, folds in related persisted fuzz hotspot/observation artifacts for hotspot analysis, and returns the same homeboy/fuzz-compare/v1 payload as homeboy fuzz compare without requiring local file paths. --hotspot-policy sets whether hotspot regressions block.

Version regression checks

homeboy runs hotspots --kind agent-task --baseline-version previous --candidate-version current

Phase cohorts include comparison.verdict (regressed, clean, or insufficient_samples) and regressions[] with metric names, both values and sample counts. Only regressed gives a non-zero comparison exit. A phase p50 or p95 must increase by both 25% and 5000 ms, with 10 samples per side. Reliability needs 20 missions per side and flags a Homeboy infrastructure or unclassified failure-rate increase of 5 percentage points. Any eligible metric can establish a clean comparison; undersampled metrics are not evidence of regression. No eligible metric means insufficient_samples.

Override policy with --phase-regression-relative (fraction), --phase-regression-floor-ms, --min-phase-samples, --failure-rate-increase (fraction), and --min-missions. current is the running product version. previous chooses the highest semantic version below the candidate with enough phase samples or missions for the selected kind and component; non-semantic versions fall back to most recently observed. Selection and comparison share the recent --last window (default 100, maximum 1000). If no baseline qualifies, the verdict is insufficient_samples. The query is read-only and skips malformed rows with a status log.

For a quiet daily check, save this as regression-check.json, replace the transport and route with an installed transport’s destination, then register it with homeboy workflow run regression-check.json:

{
  "schema": "homeboy/workflow/v1",
  "id": "homeboy.regression-check",
  "every": { "interval": "24h", "overlap": "skip" },
  "steps": [
    {
      "id": "compare",
      "homeboy": [
        "runs", "hotspots", "--kind", "agent-task",
        "--baseline-version", "previous", "--candidate-version", "current",
        "--notify-regressions",
        "--notification-transport", "installed.transport",
        "--notification-route", "destination"
      ]
    }
  ]
}

A homeboy step’s exit status settles its outcome; a regression fails the step and workflow. Generic workflow completion does not itself send a notification. --notify-regressions opts this command into the existing notification transport/outbox, only on regressed. A persistent atomic claim outside the observation store deduplicates resolved (baseline, candidate) pairs across cadence slots and restarts. Clean and undersampled checks stay silent. A queued delivery owns retries; dropped delivery releases the claim. Without this flag the comparison writes no notification state.

homeboy runs hotspots --coverage <run-id>... reads durable run.phase_spans events and reports wall time (wall_ms), union-covered time (covered_ms), covered_percentage, and the largest unattributed gaps, with preceding and following span ids. Intervals are clipped to the run window and overlaps count only once. For active runs the window ends now; completed runs use finished_at. Spans carry absolute RFC 3339 millisecond started_at timestamps, including across processes; timer-relative offsets are no longer supported. Coverage requires newly recorded spans, not event creation times. Waiting is attributed separately as promote.wait, not acquisition work.

homeboy runs hotspots <run-id>... ranks generic fuzz hotspots from persisted fuzz artifacts. It reads typed homeboy/fuzz-hotspot-set/v1 artifacts directly, ranks typed homeboy/fuzz-observation-set/v1 artifacts into hotspot points, and falls back to generic finding or coverage-gap signals only when typed hotspot data is absent:

homeboy runs hotspots fuzz-run-1 fuzz-run-2 --limit 10

For threshold-free cohort comparison, pass one or more baseline and candidate runs. The comparison reports new, resolved, increased, decreased, and unchanged hotspot movement without adding gate, pass/fail, or product-specific threshold semantics:

homeboy runs hotspots 
  --baseline-run fuzz-baseline-1 
  --baseline-run fuzz-baseline-2 
  --candidate-run fuzz-candidate-1 
  --limit 20

Related Readers

homeboy runs list --kind bench --component <component> [--scenario <id>] [--rig <id>] [--limit 20]
homeboy runs evidence <run-id> --dossier
homeboy runs distribution --kind bench --component <component> --field <metadata.path> [--scenario <id>] [--rig <id>] [--status <status>] [--limit 20]
homeboy runs compare --kind bench --from-run <run-id> --to-run <run-id>

Portable Bundles

homeboy runs export writes an inspectable directory bundle for moving observation evidence between machines without copying raw SQLite:

homeboy-observations/
  manifest.json
  runs.json
  artifacts.json
  trace_spans.json
  findings.json
  test_failures.json

The v1 bundle is metadata-only: artifact records are exported, but artifact file bytes are not copied. Imported local file and directory artifacts are stored as metadata-only records with portable labels rather than source-machine paths. homeboy runs artifact get explains that bytes are unavailable. findings.json contains normalized observation findings, and test_failures.json is an additive subset of findings where test commands recorded individual failures. Zip output is intentionally out of scope for v1; pass a directory path to --output.

homeboy runs import is idempotent. Existing identical records are accepted, while conflicting records with the same primary key fail clearly.

homeboy runs export writes a directory bundle. homeboy runs import mutates the local observation store by inserting the bundle’s records when they are new or identical.

GitHub Actions Artifacts

homeboy runs import --from-gh-actions imports JSON files from matching GitHub Actions artifacts into the local observation store. Use --workflow to scan recent workflow runs, or --run-id when triage starts from an exact GitHub Actions run URL or ID and the workflow filename is irrelevant.

The structured output includes stable Homeboy run/artifact IDs and persisted local artifact paths under artifacts[], so agents can read the copied JSON directly without searching temporary download directories.

Mutating Subcommands

Most homeboy runs subcommands are readers. These subcommands write files, delete files, or update the local observation store:

• artifact get: copies a recorded or selected runner-side file artifact to a local destination.
• artifact attach: copies an existing runner-side file into the persisted local artifact store and inserts an artifact record.
• artifact cleanup-downloads --apply: deletes locally cached runner artifact download directories that are past the fixed 24h floor and unclaimed by a non-terminal run.
• artifact cleanup-persisted --apply: deletes persisted local artifact files/directories and their database records.
• export: writes an observation bundle directory.
• import: inserts observation bundle or GitHub Actions artifact records into the local observation store.
• reconcile: marks orphaned running records stale.

homeboy runs import --from-gh-actions 
  --component wp-site-generator 
  --repo example-org/wp-site-generator 
  --run-id 26731420339 
  --artifact-glob 'php-transformer-iterator-transcript-*'

Durable Cook discovery

homeboy runs list --kind agent-task returns the lifecycle discovery payload unchanged (not observation run records). --active adds liveness triage buckets, record health, and per-record reconciliation guidance.

Both modes default to 20 newest rows; --limit 1 selects the newest match. Bounded pages inspect at most 100 physical rows and return at most 100 matches. requested_limit preserves a supplied limit above 100; limit reports the effective ceiling. Continue incomplete searches using --cursor <next_cursor> and the same filters. --full opts out of bounded pagination and conflicts with --limit and --cursor.

Cook list filters: --repo, --task-url, --run-placement, --parent-id, --branch, --workspace, --status (queued/running/succeeded/failed/cancelled), and --since (RFC3339 or relative age). Active mode accepts only --limit, --cursor, --branch, and --full. Cook-only flags are rejected without --kind agent-task. Observation-only filters are rejected for Cook discovery.

Fleet repair is homeboy agent-task reconcile --all: preview by default, mutation only with --apply. Use agent-task reconcile <run-id> for one run/group.