🐛 [fix] github: pause runs when required reads fail

[EricTechPro]

Note

⏳ In review · round 1 · ✅ 6/6 AC · head 3668990

Depends on #23. This draft targets codex/approval-freshness so the diff contains only the GitHub failure handling change. Retarget to main after #23 lands.

Problem

A failed gh pr diff request became an empty diff, so the merge gate could miss a risky change and continue to migrations or merge. Other required reads could turn failures into an empty board, an open issue, or full API quota.

A run also had no shared local pause state. A worker could keep dispatching or writing after another worker lost the GitHub evidence it needed.

Solution

• Route required reads in the merge, approval, planning, preflight, legacy runner, and issue-filing paths through a read-only helper. Each logical read gets three total attempts. Known query, authentication, or permission errors stop immediately.
• Check response fields and completeness before using them. Reject partial GraphQL pages, incomplete diffs, malformed board data, and capped duplicate searches.
• Save the first failure locally in a halt file shared across linked worktrees. Preserve work, claims, locks, and approval evidence. Future dispatch and guarded writes stop with exit 79.
• Resume only after an explicit recovery check succeeds. A corrected query or fresh diff metadata can replace the failed read during recovery; the original failure stays in the archived record.
• Attempt writes once. A lost merge response gets a readback of the merge state. Other uncertain write outcomes pause for inspection before restarting.
• Teach workflow agents to report halted, stop queued work, and check the shared halt before writes. Install the helper with the existing script pack and include it in setup checks and repair.
• Merge current main while preserving head-bound approval, upgrade recovery, and status-restoration protections.
• Route duplicate/adopt writes through the shared repository pause check before each comment, label, or project mutation; preserve existing issue IDs and exit 79 for mid-run pauses.
• Regression exercises existing pauses, pauses during discovery, labeling, and placement:12 failures on the unfixed router,66 assertions green after the fix.

Acceptance criteria

• Three failed attempts pause the run; temporary failures can recover and later reads start with a fresh attempt count.
  ↳ tests/test_github_reads.py
• Missing or incomplete evidence cannot permit dispatch, migration, or merge.
  ↳ tests/test_github_reads.py, tests/test-merge-gate.sh, tests/test-preflight.sh
• Worktrees share the pause, keep local work and claims, and require checked recovery.
  ↳ tests/test_github_reads.py, including failed recovery and corrected-query recovery
• The workflow stops queued work after a lane reports the pause.
  ↳ tests/test-workflow-halt.sh, 5 scenarios
• Failed duplicate checks cannot create issues; uncertain writes are not replayed or reported as success.
  ↳ merge-gate, bug filer, refactor filer, collector, and legacy runner regressions
• Existing safety checks pass and an independent review has no remaining findings.
  ↳ bash tests/run-safety.sh: 36 suites passed; all 8 GitHub checks passed on final head 3668990; setup 10 and install 17 scenarios passed after the helper-check follow-up; git diff --check passed

Iteration history

Lane	Done	Time	Details
🔨 builder	✅	Oct 3, 11:24 PDT	39ce91b; 36 safety suites passed
🧐 reviewer	✅	Oct 3, 11:24 PDT	Independent review cleared; read, approval, workflow, merge, and filer suites rerun
🔨 builder	✅	Oct 3, 11:29 PDT	3668990; helper check/repair coverage passed; independent delta review cleared

Risk

🟡 Medium · shared failure handling changes several CLI paths. Tests use offline GitHub stubs; live board, database, and release actions were not run.

Workflow cancellation takes effect at checkpoints. Already-running agent commands cannot be recalled. The legacy runner signals only workers it launched. Unknown write outcomes require checking GitHub before clearing the halt. Duplicate searches that reach the existing 200-item limit pause instead of assuming no match. Automatic database or other tool outage detection is outside this change.

[qodo-code-review]

Qodo reviews are paused for this user.

Troubleshooting steps vary by plan Learn more →

On a Teams plan?
Reviews resume once this user has a paid seat and their Git account is linked in Qodo.
Link Git account →

Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center?
These require an Enterprise plan - Contact us
Contact us →