Skip to content

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: unavailable and Reason: with the classified failure before verification, confidence, or next-step detail; also state Source findings: not assessed and Merge 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 Recovery nor Review Findings and Merge Blocks applies 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.json or <run-directory>/checkout-state.json when 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-recovery and 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 in review-notes.md. Use Collection failure for pr-error.txt, Command failure for command-failure.json, Checkout state for checkout-state.json, Worktree preflight for worktree-preflight.json, PR head fetch for pr-head-fetch.json, Target branch for target-branch.json, and Review notes for review-notes.md; the finalizer adds the Result artifact. Include each retained diagnostic required by the validator, and do not add custom labels or text.
  • Still write canonical result.json with status=fail, zero findings, review_status=unavailable, and collection_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-applicable with 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.json exists, 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-auth or permission failure, stop and explain that local gh configuration/account access needs repair; tell user to run gh auth status and, if needed, gh auth login privately 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 repair gh locally 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.