Inspect and maintain persisted observation-store runs and artifacts.

Synopsis

homeboy runs list [--runner <runner-id>] [--kind bench|rig|trace] [--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] [--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 bench-compare --from-run <run-id> --to-run <run-id> [--metric <name>]
homeboy runs fuzz-compare --from-run <run-id> --to-run <run-id> [--hotspot-policy <advisory|blocking|off>]
homeboy runs hotspots <run-id>... [--limit <count>]
homeboy runs hotspots --baseline-run <run-id> --candidate-run <run-id> [--limit <count>]
homeboy runs show <run-id> [--json]
homeboy runs dossier <run-id> [--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 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>]
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 findings reconcile <component> [--findings <path>|--from-output <command=path>] [--apply]
homeboy runs findings reconcile-run <component> [--output-dir <dir>] [--apply]
homeboy runs findings build --from-output <command=path> [--run-url <url>]
homeboy runs finding <finding-id>
homeboy runs latest-finding [--kind bench|rig|trace] [--component <id>] [--rig <id>] [--status <status>] [--tool <tool>] [--file <path>]
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 query --select <jsonpath>[,<jsonpath>...] [--group-by <jsonpath>] [--count] [--format json|table|csv]
homeboy runs drift --metric <jsonpath> [--window 7d] [--threshold 0.0] [--baseline <duration>] [--format json|table]
homeboy runs loop-sync <archive-root> [--component <id>] [--rig <id>] [--label <label>] [--dry-run]

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, and run explicit cleanup or reconciliation tasks.

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.

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.

homeboy runs show <run-id> prints a compact human summary by default: run identity, status, component/rig/SHA, timestamps, bench hotspots, generic coverage summaries when present, key case artifacts, and each recorded artifact’s locator with a concise homeboy runs artifact get <run-id> <artifact-id> command to inspect it. This makes bench artifacts, scenario outputs, slow/hot metric families, and fuzzer coverage gaps/case artifacts easy to find without spelunking temp directories. 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 --json for the full structured payload on stdout; it is also always written to --output <file>.

homeboy runs dossier <run-id> 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 --json for the full structured payload.

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 resume-plan <run-id> reads generic validation_progress metadata from a run and reports the last completed command, any active command, and the next pending command. Homeboy core records this ledger for Homeboy-managed validation command sets without understanding npm, smoke groups, benchmarks, or implementation-specific command names; command manifests come from project configuration or extension-provided runners.

homeboy runs evidence <run-id> emits reviewer-facing evidence using generic artifact addresses. Local operator files are represented as non-reviewer-visible homeboy://run/<run-id>/artifact/<artifact-id> handles with a fetch command instead of absolute machine paths. Remote runner artifacts use runner-artifact://... refs, validated public HTTP(S) URLs are emitted as public evidence links, and metadata-only evidence remains non-public. Lab-specific publication or mirroring policy belongs in runner/extension enrichment, not in the generic evidence serializer.

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 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 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 subtree. Use --runner and --run-id to narrow cleanup to a specific runner or run cache.

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.

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, and --result <path> to write the bare postprocess result contract to disk.

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 and homeboy runs latest-finding select the newest run or finding 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, while homeboy runs finding reads one finding by id. The runs findings reconcile, reconcile-run, and build subcommands normalize finding streams and reconcile them against an issue tracker from the evidence pillar. They default to dry-run planning; pass --apply on reconcile commands to mutate tracker state.

homeboy runs query projects JSONPath expressions over imported run artifact rows. It can return raw JSON rows, grouped counts, Markdown-friendly tables, or CSV without baking domain-specific artifact schemas into Homeboy core. query is the generic projection reader for imported run artifacts.

homeboy runs drift calculates window-based distribution drift for one JSONPath metric across imported artifact rows. It reports value shares for the selected window and can compare them against a longer baseline window. drift is useful for lightweight distribution checks over imported artifact rows.

homeboy runs loop-sync inventories continuous-loop archive directories and, unless --dry-run is passed, records the triage summary as observation evidence. loop-sync bridges existing loop archives into observation evidence.

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.

homeboy runs bench-compare --from-run <baseline-run-id> --to-run <candidate-run-id> compares numeric metrics recorded in two exact benchmark runs. It captures both run IDs, component state, shared benchmark context, selected metric deltas, and a Markdown table under reports.markdown in the JSON payload.

homeboy runs fuzz-compare --from-run <baseline-run-id> --to-run <candidate-run-id> compares persisted fuzz result envelope artifacts for two exact 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.

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 dossier <run-id>
homeboy runs distribution --kind bench --component <component> --field <metadata.path> [--scenario <id>] [--rig <id>] [--status <status>] [--limit 20]
homeboy runs bench-compare --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 query reports these rows as skipped evidence, and 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 downloads.
• 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.
• loop-sync: syncs continuous-loop archive directories into observation artifacts.
• 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-*'