runner-diagnostics

name

runner-diagnostics

description

Diagnose issue-spec comment Runner failures using preflight output, persistent NDJSON logs, ACPX/Codex adapter output, bubblewrap metadata, proxy inheritance, host SSH, webhook intake, and Provider bridge evidence. Use when a /new, /resume, or /cancel command is ignored, a Runner job fails, Codex does not start, a model is rejected, clone/push fails, a webhook is rejected, or a PR/MR was not created.

Diagnose a Runner failure

Trace the failure from a public status comment to bounded local diagnostics. Keep tokens, internal hostnames, absolute paths, raw adapter output, and private deployment details out of issue comments and public pull requests.

Start from the failing identifier

1. Record the public session ID, job ID, trigger-comment URL, status-comment URL, approximate time, and command (/new, /resume, or /cancel).
2. Locate the scoped Runner directory containing state.json and logs/. Use the runner's configured --state path rather than assuming a repository name or service-account layout.
3. Resolve the job or session through logs/index.ndjson, then read only the matching job and session records.

state.json
logs/
  runner.ndjson
  errors.ndjson
  index.ndjson
  jobs/<job-id>.ndjson
  jobs/<job-id>-acpx-stdout.log
  jobs/<job-id>-acpx-stderr.log
  sessions/<public-session-id>/<turn-correlation-id>.ndjson

Use jq and narrow rg queries. Do not dump all logs.

rg -n '"id":"<job-id>"|"id":"<public-session-id>"' logs/index.ndjson
rg -n '"level":"error"|"component":"(intake|dispatch|acpx)"' logs/jobs/<job-id>.ndjson
tail -100 logs/jobs/<job-id>-acpx-stderr.log