Use this loop when a runner, matrix job, or CI workflow produces output that a reviewer should inspect later:

1. Run the workload on the intended runner or CI worker.
2. Write structured output and reviewer assets under a declared output directory.
3. Promote or attach that directory to the Homeboy run when the command supports it.
4. Verify the result through homeboy runs show, homeboy runs artifacts, and homeboy runs evidence.
5. Share reviewer-visible URLs from runs evidence, not machine-local paths.

The key distinction is stdout versus evidence. Stdout is useful operator context, but it is not durable review evidence unless it is captured as an artifact or a persisted run record. Prefer small JSON summaries plus static HTML, screenshots, logs, or archives that can be fetched through Homeboy artifact commands.

Artifact Mechanisms

Use the narrowest mechanism that matches the workflow:

Avoid embedding private paths, local hostnames, or temporary runner directories in PR comments. Let runs evidence translate recorded artifacts into fetch commands or public links.

Generic Runner Command

For ad hoc runner work, create a known output directory inside the runner workspace and pass a stable run id:

Use homeboy runner refresh-plan first when you want a read-only preflight that checks the runner/workspace/source inputs and prints the next runner doctor, runner workspace sync, runner exec, and runs evidence commands. Its execution_envelope field is the canonical runner handoff contract for the planned lifecycle, cleanup guidance, secret env plan, artifact declarations, and result refs.

run_id="review-static-html-$(date -u +%Y%m%dT%H%M%SZ)"

homeboy runner exec lab-runner 
  --cwd /workspace/example-component 
  --run-id "$run_id" 
  -- 
  sh -lc 'mkdir -p artifacts/review && npm run build-report -- --out artifacts/review'

homeboy runs show "$run_id"
homeboy runs artifacts "$run_id"
homeboy runs evidence "$run_id"

If runs evidence reports success with zero artifacts, the workload is not yet reviewable. Keep the run id and output directory, then use the artifact promotion or attach command that matches the output shape:

# Attach an existing runner-side file to an existing run.
homeboy runs artifact attach "$run_id" 
  --runner lab-runner 
  --path /workspace/example-component/artifacts/review/summary.json 
  --name review-summary

# Proposed/upcoming: promote a runner-side directory to an existing run.
homeboy runner artifact promote lab-runner "$run_id" 
  --path artifacts/review 
  --kind static_html 
  --entry index.html

Until directory promotion exists, prefer workflows that already register directory artifacts through the runner daemon, a command-specific artifact contract, CI artifact upload, or runs import --from-gh-actions.

Static HTML Example

Static HTML reports work well when paired with a small JSON manifest:

artifacts/review/
  index.html
  manifest.json
  screenshots/
    homepage.png
  data/
    matrix-summary.json

Example manifest:

{
  "schema": "example/review-artifacts/v1",
  "entry": "index.html",
  "summary": "Static review report for the runner workload.",
  "artifacts": [
    { "path": "index.html", "kind": "static_html" },
    { "path": "screenshots/homepage.png", "kind": "screenshot" },
    { "path": "data/matrix-summary.json", "kind": "matrix_summary" }
  ]
}

The HTML should use relative links so it works whether Homeboy fetches it into a local directory, CI uploads it as an archive, or a public artifact base URL serves it from a mirrored artifact root.

Matrix Example

Matrix cells should produce one artifact directory per cell plus an aggregate summary. Keep axis metadata in JSON so runs evidence can later group cells without understanding the project domain:

run_id="matrix-review-20260625"

for runtime in runtime-a runtime-b; do
  for browser in chromium firefox; do
    cell="runtime=${runtime},browser=${browser}"
    out="artifacts/matrix/${runtime}/${browser}"

    homeboy runner exec lab-runner 
      --cwd /workspace/example-component 
      --run-id "${run_id}-${runtime}-${browser}" 
      -- 
      sh -lc "mkdir -p ${out} && ./scripts/run-cell --runtime ${runtime} --browser ${browser} --out ${out}"
  done
done

./scripts/render-matrix-summary 
  --input artifacts/matrix 
  --output artifacts/matrix/index.html 
  --json artifacts/matrix/matrix-summary.json

Proposed/upcoming aggregate directory promotion shape:

homeboy runner artifact promote lab-runner "$run_id" 
  --path artifacts/matrix 
  --kind matrix_static_html 
  --entry index.html
homeboy runs evidence "$run_id"

For rig matrix work, use rig artifacts when the rig owns setup, service state, or workload paths. Use generic runner artifacts when the command is an ad hoc worker command and the output directory is enough to understand the result.

Public Links

Set HOMEBOY_PUBLIC_ARTIFACT_BASE_URL on the runner only when promoted artifact files are mirrored to a stable HTTP(S) origin. With that variable configured, Homeboy can derive public links for fetchable run artifacts and runs evidence can expose reviewer-visible URLs after validation.

If the variable is absent, evidence remains valid but non-public: reviewers use homeboy runs artifact get <run-id> <artifact-id> -o <path> or CI-provided artifact downloads.

Success Checklist

• homeboy runs show <run-id> lists the run and does not rely on stdout alone.
• homeboy runs artifacts <run-id> lists at least one file, URL, or remote file artifact.
• homeboy runs evidence <run-id> shows reviewer-visible public links or explicit fetch commands.
• Matrix output includes axis metadata and one aggregate summary artifact.
• Shared docs and PR comments use public URLs or Homeboy artifact refs, not local paths.