fix: fall back to workflow runs for CI status reads

[quinnbot-ai]

Intent

Prevent the zombie-CI-loop failure class in firstmate when gh pr checks receives a 403 from the check-runs API under the fine-grained token even though the workflow-runs API remains readable. Build the durable local fix in this repository scripts and launch path without patching the external no-mistakes monitor or its parallel upstream proposal. Preserve least privilege: keep the ambient narrow token for CI reads, never expose the classic PR-capable config/gh-credential token to every crew or to the fallback, never print or commit a secret, and document token routing in the owning script header. After only the known 403 and only for the exact JSON gh pr checks shapes used by no-mistakes, resolve the PR current exact head SHA and query every paginated Actions workflow run using actions/runs?head_sha=; never approximate by branch name or stale head. Return correct green, red, cancellation, skipping, and pending buckets, with no runs remaining non-green. Preserve all non-403 failures, interactive check commands, every unrelated gh call, and the existing privileged routing only for pr create and pr edit. Document that workflow-run evidence is GitHub Actions only and cannot reconstruct hidden third-party check providers. Add shellcheck-clean colocated behavioral tests proving a crew whose check-runs read 403s reaches correct green and red exact-head verdicts while the broader token is absent, and run full no-mistakes validation. Deliver only to quinnbot-ai/firstmate: push the branch to its origin and use PR 100 against quinnbot-ai/firstmate main; never push to or open a PR against kunchenguid/firstmate. The accepted starting base is ae95570 from the fork; do not import the rejected 38-commit upstream bundle or require an upstream prerequisite.

What Changed

• Add a least-privilege fallback that converts paginated, exact-head GitHub Actions workflow runs into the check status shape expected by no-mistakes after the known statusCheckRollup permission denial.
• Preserve unrelated failures and interactive gh pr checks behavior while keeping the broader PR credential restricted to pr create and pr edit.
• Document the credential routing and GitHub Actions-only limitation, with behavioral coverage for status mapping, empty runs, head drift, unsupported commands, and token isolation.

Risk Assessment

✅ Low: The fallback is narrowly bounded to the observed statusCheckRollup denial and exact monitor vectors while preserving least-privilege routing, exact-head atomicity, and fail-closed behavior.

Testing

The baseline focused suite passed, expanded pagination and verdict-bucket coverage also passed, and a CLI-level fixture demonstrated exact-head green/red results without privileged-token exposure or stale-head leakage; this is CLI-only, so no visual screenshot applies.

Evidence: Exact-head CI fallback CLI transcript

Green and red gh pr checks fallback results used the exact PR head SHA, read the head twice, retained only the narrow CI token, and excluded stale-head results.

=== GREEN exact-head verdict ===
$ gh pr checks 7 --repo o/r --json name,state,bucket,completedAt,link
exit: 0
response: [{"name":"exact-head-green","state":"success","bucket":"pass","completedAt":"2026-08-07T12:34:56Z","link":"https://github.com/o/r/actions/runs/123"}]
API route: argv:api -X GET repos/o/r/actions/runs?head_sha=abcdefabcdefabcdefabcdefabcdefabcdefabcd&per_page=100 --paginate --slurp
PR head reads: 2
CI token labels observed:
token:narrow-ci-token
broader PR token reached CI: no
stale-head result leaked: no

=== RED exact-head verdict ===
$ gh pr checks 7 --repo o/r --json name,state,bucket,completedAt,link
exit: 0
response: [{"name":"exact-head-red","state":"failure","bucket":"fail","completedAt":"2026-08-07T12:34:56Z","link":"https://github.com/o/r/actions/runs/123"}]
API route: argv:api -X GET repos/o/r/actions/runs?head_sha=abcdefabcdefabcdefabcdefabcdefabcdefabcd&per_page=100 --paginate --slurp
PR head reads: 2
CI token labels observed:
token:narrow-ci-token
broader PR token reached CI: no
stale-head result leaked: no

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 3 issues found → auto-fixed (3) ✅

• 🚨 bin/fm-gh-ci-fallback.sh:168 - The requirement says to return pending evidence "with no runs remaining non-green," but cat "$FALLBACK_OUT"; exit 0 also accepts an empty workflow response as []. The supported no-mistakes v1.41.2 monitor marks an empty check list ready after its grace period, so a head with no registered Actions runs can be falsely certified green. At this fallback output boundary, emit an explicit pending check or retain the original 403 until at least one exact-head run exists.
• 🚨 bin/fm-gh-ci-fallback.sh:130 - The requirement says "resolve the PR current exact head SHA" and "never ... stale head," but the new code reads .head.sha only once before paginating workflow runs. If the PR advances from A to B during that query, green runs for A are returned as the current verdict. Re-read the PR head after pagination and reject or retry when it differs before emitting results.
• 🚨 bin/fm-gh-shim.sh:32 - The requirement says "Preserve ... interactive check commands," but checks) ROUTE=ci-fallback sends every gh pr checks invocation through the helper before validating the exact no-mistakes JSON shape. The helper redirects stdout and stderr to files, so successful --watch calls no longer stream and real gh no longer sees the caller's terminal. Restrict routing at this dispatch boundary, or pre-parse and directly exec non-matching invocations before capture.

🔧 Fix: Harden exact-head CI fallback guarantees
3 issues (2 errors, 1 warning) still open:

• 🚨 bin/fm-gh-ci-fallback.sh:135 - The intent requires fallback "after only the known 403," but this condition accepts either any standalone 403 or the token-denial message. An unrelated failure such as HTTP 403: API rate limit exceeded can therefore be replaced by a workflow verdict if the later reads succeed. Require the known personal-token/check-runs denial signature rather than a bare status code.
• 🚨 bin/fm-gh-ci-fallback.sh:47 - The accepted correction requires bypassing capture for every invocation outside the exact no-mistakes JSON shapes, but this parser also accepts -R, assignment-form flags, arbitrary flag ordering, duplicates, and repository-less PR URLs. Those manual commands can still enter the capturing fallback. Match only the two literal no-mistakes argument vectors at this dispatch boundary.
• ⚠️ docs/no-mistakes-pr-credential.md:44 - This owning documentation still says zero exact-head runs return an empty list, while the corrected implementation emits a pending placeholder. Update this statement and the stale verification counts/transcript, which still describe 15 total/four CI cases instead of 17/six.

🔧 Fix: Narrow CI fallback to exact monitor failures
1 error still open:

• 🚨 bin/fm-gh-ci-fallback.sh:111 - The requirement says fallback must activate “after only the known 403,” but the new hunk matches only HTTP 403: ... check-runs. The installed GitHub CLI 2.92.0 queries GraphQL statusCheckRollup, not the REST check-runs endpoint (source), and fine-grained permission failures are surfaced as GraphQL: Resource not accessible by personal access token (<field path>) (example). Consequently, the real denial misses this matcher, the original failure is replayed, and the zombie polling loop remains reachable. Replace the fabricated REST-shaped fixture with the observed statusCheckRollup denial and narrowly match that actual signature.

🔧 Fix: Match observed statusCheckRollup permission denial
✅ Re-checked - no issues remain.

✅ **Test** - passed

✅ No issues found.

• Baseline bash tests/fm-gh-shim.test.sh
• Added test_ci_maps_cancel_skipping_and_pending_across_pages, then reran bash tests/fm-gh-shim.test.sh
• Manually exercised gh pr checks 7 --repo o/r --json name,state,bucket,completedAt,link through the installed-path shim fixture for exact-head green and red outcomes

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.