Terminal review-unavailable output gate and collection-failure recovery¶
Terminal review-unavailable output gate: A core T0 PR collection failure is process failure, not review result.
- Start with a plain-English explanation of the stopped operation and its effect, then state
PR Review Availability: unavailableandReason:with the classified failure before verification, confidence, or next-step detail; also stateSource findings: not assessedandMerge decision: not made. New handoffs use the shared presentation-version-12 renderer and its artifact-bound diagnostic contract; historical output remains readable under its original version. - Use plain diagnostic prose with exactly process diagnostic, recovery action, and evidence path.
- Emit the presentation-12 display-only status table; neither
PR Evidence Collection RecoverynorReview Findings and Merge Blocksapplies before source assessment. Do not invent assessed findings or a merge recommendation. - Do not emit
needs-more-work,minor-changes,reject,not-aligned, or any other merge recommendation. - Retain current-attempt metadata, checkout state, or partial diff artifacts for diagnosis, but label them unassessed and never turn them into findings.
- Name classified failure and
<run-directory>/pr-error.txt, then stop. For a review-worktree creation or source-state failure, explain the exact isolated checkout obstruction and link<run-directory>/worktree-preflight.jsonor<run-directory>/checkout-state.jsonwhen available; invoking-worktree edits are not checkout overlap. Do not insert protected path lists into the bound summary. Follow the final-handoff redaction contract; never summarize this as generic collector failure. - For presentation 12, set the sole recovery row ID to
collection-recoveryand its action to “Inspect the classified<label>collector failure.Resume only after a fresh collector run produces and validates the PR source bundle.” Copy the exact classified recovery action from the Recovery:paragraph inreview-notes.md. UseCollection failureforpr-error.txt,Command failureforcommand-failure.json,Checkout stateforcheckout-state.json,Worktree preflightforworktree-preflight.json,PR head fetchforpr-head-fetch.json,Target branchfortarget-branch.json, andReview notesforreview-notes.md; the finalizer adds theResultartifact. Include each retained diagnostic required by the validator, and do not add custom labels or text. - Still write canonical
result.jsonwithstatus=fail, zero findings,review_status=unavailable, andcollection_failure={"code": "<pr-error.txt text>", "artifact": "pr-error.txt"}; review-specific validator rejects review decision, source findings, specialist artifacts, any table, or assessed-review sections. - Apply the shared final-handoff contract’s current unavailable confidence profile: score the delivered failure report and its production and checks; disclose the unreviewed PR with zero deduction; separately record each supported material diagnostic limitation and use a residual only for a genuinely unexplained shortfall. If a known material limitation cannot be represented, stop and disclose it; do not hide it in the residual. Historical profiles stay readable for earlier presentations.
- For new unavailable results, all five canonical PR checks are explicitly
not-applicablewith nonempty reasons: collection stopped before PR verification. Use--skip-lint,--skip-format,--skip-types,--skip-tests, and--skip-review; never run print-only diagnostic commands as passing checks. Keep any independently executed recovery diagnostics in separate evidence, not PR verification. The generated versioned handoff must say checks were not run; historical artifacts retain their reading contract.
Before handing collection failure to user, inspect available pr-error.txt, command-failure.json, checkout-state.json, worktree-preflight.json, pr-head-fetch.json, and target-branch.json yourself. Compare expected and observed commit IDs when present; use non-mutating git status --short, git branch --show-current, and git rev-parse HEAD if local state remains uncertain. Retain failed attempt before new collection. Explain failing operation and observed cause first, followed by its exact code/evidence; missing detail stays explicitly unknown. Do not assign generic recovery to "local review environment" or tell user only to "repair the checkout failure".
For retryable github-network, github-rate-limit, or command-timeout, perform permitted diagnostics and use already-authorized bounded recovery when evidence supports it; rate-limit diagnostics deliberately retain no server interval. Ask user only for specific unavailable access, approval, or external-state change. An unchanged deterministic failure is not reason to retry blindly. If newly fetched head proves PR advanced since collected metadata, treat it as changed source: recollect metadata once under existing authorization, rebuild bundle, and verify new identity before review rather than asking user to update branch.
- If
checkout-state.jsonexists, inspect local state yourself before any allowed retry, state observed branch/head and any affected paths, and never claim no checkout was produced. If safe diagnosis is unavailable, name missing evidence and exact next action rather than inventing repair. - For
github-author permission failure, stop and explain that localghconfiguration/account access needs repair; tell user to rungh auth statusand, if needed,gh auth loginprivately outside agent workflow, verify repository access, and never paste tokens, keychain data, or credential output into chat. - For
missing-command:gh, tell user to install or repairghlocally before retrying. - For
github-not-found, ask for canonical PR URL and repository identity. - For definitive
unsafe-gh-command, invalid protocol/JSON, missing required PR identity, or an unclassified deterministic collector error, stop at the unavailable result, explain the classified code and artifact, and suggest filing a Codex Rig bug with the plugin version, command label, failure code, and sanitized artifacts. - Never retry deterministic target, permission, safety-guard, or plugin-contract failure automatically.