Skip to content

fix(docs): fail when batch recovery retains failed requests - #1154

Merged
steipete merged 3 commits into
mainfrom
codex/fix-batch-recovery-exit-20260924
Sep 24, 2026
Merged

steipete merged 3 commits into
mainfrom
codex/fix-batch-recovery-exit-20260924

Conversation

@steipete

@steipete steipete commented Sep 24, 2026 •

Copy link
Copy Markdown
Collaborator

batch end --continue-on-error reported exit 0 even when individual requests failed and remained queued, so scripts could mistake a partially applied batch for success. Write the existing JSON/text summary, then return exit 1 with the retained batch ID and failure count when recovery leaves failures. Successful recovery still returns 0; request retention and revision sequencing are unchanged. This adopts the documented success/failure contract: scripts intentionally tolerating partial completion must handle exit 1 and inspect failed; the guide explicitly describes the effect on set -e. The compatibility decision is recorded in the PR discussion.

Validation:

  • Focused tests cover mixed failure, total failure, successful recovery, result summaries, retained requests, and revision state.
  • Full make ci passed, including lint, deadcode, Go/script tests, docs coverage, and generated skills.
  • Live Google Docs before/after: one valid insertion and one invalid index produced the same requests:2, chunks:1, failed:1 summary; the original binary exited 0 and the fixed binary exited 1. Provider readback confirmed no edit before submission and the valid insertion afterward. The failed request remained available, total failure returned 1, and successful submission returned 0. All synthetic batches were aborted or completed and the disposable Doc was trashed with verified cleanup.
  • Independent Codex review through P2: scoped-clean, no findings.
  • Hosted checks passed on 58691e89efcd0c2bad1418bff2f6207cd38fafbe: Linux, Windows, macOS, minimum Go, and worker, Docker, and CodeQL. ClawSweeper re-reviewed the final head and found no blocking defect after the compatibility decision was recorded.

@clawsweeper clawsweeper Bot added P2 Normal priority bug or improvement with limited blast radius. merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. proof: sufficient Contributor real behavior proof is sufficient. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. labels Sep 24, 2026
@clawsweeper

clawsweeper Bot commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge. Reviewed September 24, 2026, 6:55 AM ET / 10:55 UTC (Revision 2).

ClawSweeper review

What this changes

The PR makes Google Docs batch recovery return a failure status when requests remain queued, and updates tests, documentation, and the changelog.

Merge readiness

✅ Ready for maintainer review

Keep open: current main still reports success after partial Google Docs batch recovery. The prior compatibility concern has been explicitly accepted in the PR discussion, and this review found no blocking patch defect.

Priority: P2
Reviewed head: 58691e89efcd0c2bad1418bff2f6207cd38fafbe

Review scores

Measure Result What it means
Overall readiness 🐚 platinum hermit (4/6) Focused code, recovery-state tests, documentation, and reported live before/after behavior support a normal mergeable-quality review.
Proof confidence 🐚 platinum hermit (4/6) Sufficient (live_output): The PR body reports a live Google Docs batch submission through the changed CLI path: partial recovery kept its summary and failed request while exit status changed from 0 to 1; total failure and successful submission statuses were also checked. No stored-data format changes.
Patch quality 🦞 diamond lobster (5/6) No actionable review findings were identified.

Verification

Check Result Evidence
Real behavior Verified Sufficient (live_output): The PR body reports a live Google Docs batch submission through the changed CLI path: partial recovery kept its summary and failed request while exit status changed from 0 to 1; total failure and successful submission statuses were also checked. No stored-data format changes.
Evidence reviewed 9 items Current main remains affected: After individual recovery, current main returns the summary writer's result without checking the failed-request count.
Introduced status check: The introduced code writes the summary first, then returns an error containing the failure count and retained batch ID when failures remain.
Recovery regression coverage: Tests cover mixed failure, total failure, and successful recovery, including JSON summaries, retained requests, and revision state.
Findings None None.
Security None None.

How this fits together

The batch command submits locally queued edits to Google Docs and records any requests that fail during recovery. Its summary and process exit status tell scripts whether the submission completed.

flowchart LR
A[Queued Docs edits] --> B[Batch end command]
B --> C[Google Docs API]
C --> D{Validation failure?}
D -- No --> G[Summary and exit status]
D -- Yes --> E[Individual recovery]
E --> F[Retained batch state]
E --> G
Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

Metric Value Why it matters
Code and test delta production +7/-1 lines; tests +85/-28 lines The small exit-status change has focused coverage for three recovery outcomes.

Technical review

Best possible solution:

Preserve the result summary and retained requests while giving scripts a dependable failure signal and clear guidance for handling partial completion.

Do we have a high-confidence way to reproduce the issue?

Yes. Current-main source shows the success return after failed individual requests, and the PR reports a live Google Docs before/after check; this review did not execute the command locally.

Is this the best way to solve the issue?

Yes. Checking failures after writing the summary and persisting recovery state addresses the defined exit-status contract without changing request handling.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 7381ec9d1ccb.

Labels

Label changes:

No label changes.

Label justifications:

  • P2: Incorrect success status can mislead Docs batch automation, but the affected recovery mode is opt-in.
  • merge-risk: 🚨 compatibility: Existing scripts that tolerate partial recovery may now stop on exit code 1; the PR discussion explicitly accepts and documents that tradeoff.
  • rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🦞 diamond lobster.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body reports a live Google Docs batch submission through the changed CLI path: partial recovery kept its summary and failed request while exit status changed from 0 to 1; total failure and successful submission statuses were also checked. No stored-data format changes.
  • proof: sufficient: Contributor real behavior proof is sufficient. The PR body reports a live Google Docs batch submission through the changed CLI path: partial recovery kept its summary and failed request while exit status changed from 0 to 1; total failure and successful submission statuses were also checked. No stored-data format changes.

Evidence

What I checked:

Likely related people:

  • steipete: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rating scale

Score Internal tier Crab rank Meaning
6/6 S 🦀 challenger crab Exceptional readiness
5/6 A 🦞 diamond lobster Very strong readiness
4/6 B 🐚 platinum hermit Good normal PR; ordinary maintainer review
3/6 C 🦐 gold shrimp Useful, but confidence is limited
2/6 D 🦪 silver shellfish Proof or implementation needs work
1/6 F 🧂 unranked krab Not merge-ready
N/A NA 🌊 off-meta tidepool Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (1 earlier review cycle)
  • reviewed 2026-09-24T10:37:12.288Z sha 988da28 :: blocked before merge. :: none

@steipete

Copy link
Copy Markdown
Collaborator Author

Maintainer decision: adopt exit code 1 when recovery retains failed requests. This is a correction to the documented automation contract (0 means success), not a new opt-in strict mode. --continue-on-error continues processing; it does not make failed requests successful.

The existing JSON/text summary, successful edits, failed-request retention, and revision handling remain intact. Scripts intentionally tolerating partial completion must handle status 1 and inspect failed; the batching guide now explicitly explains the effect on set -e and cautions against retrying without inspecting the retained batch. The Unreleased changelog records the behavior change.

The compatibility tradeoff is accepted for this bug fix. Live Google proof establishes the before/after status and preserved state; independent review found no code defects. No compatibility flag will be added.

@steipete
steipete merged commit 67094ba into main Sep 24, 2026
13 of 14 checks passed
@steipete
steipete deleted the codex/fix-batch-recovery-exit-20260924 branch September 24, 2026 11:04
@steipete

Copy link
Copy Markdown
Collaborator Author

Landed as 67094ba. The merged tree matches the expected combination of reviewed head 58691e89efcd0c2bad1418bff2f6207cd38fafbe and current main (including #1155).

Validation:

  • go test ./internal/cmd -run '^(TestBatch|TestDocs.*Batch|TestValidateDocsBatch)' -count=1
  • make ci TOOLS_DIR=/Users/steipete/Projects/gogcli/.tools
  • Independent Codex review through P2: scoped-clean. ClawSweeper's final review found no blocking defect after the compatibility decision and upgrade guidance were recorded.
  • Live built CLI used an isolated local batch directory and one disposable Google Doc. It queued docs insert <doc> <text> --index 1 --batch <batch> and another insertion at --index 999999, then ran batch end <batch> --continue-on-error --json. Original exit 0 changed to exit 1 while preserving requests:2, chunks:1, failed:1. Readback confirmed no edits during queueing, the successful insertion after submission, and the exact invalid request retained with the updated revision. Total failure returned 1; complete success returned 0. All retained test batches were aborted, the isolated batch list was empty, and the exact synthetic Doc was trashed with readback verification.
  • Hosted cross-platform CI, Docker, and CodeQL passed on the final head.

Scripts that intentionally tolerate partial recovery must now handle exit 1 and inspect failed; successful edits are not rolled back. This accepted behavior correction is documented in the guide and Unreleased changelog.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. P2 Normal priority bug or improvement with limited blast radius. proof: sufficient Contributor real behavior proof is sufficient. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant