fix(queue): complete head-drifted exact reviews as superseded no-ops

[steipete]

Problem

~9% of review runs still fail post-#962 with Exact-review queue authority source head does not match the current pull request. (sample runs 30558755321, 30558626014). The queued exact-head entry is simply stale — the PR received a newer push, which enqueued its own exact-head event. The reservation command threw, the run failed as codex_or_content_failure, and the item burned one of its eight review-failure park attempts for what is ordinary drift.

Fix

reserve-review-lease now reports {"status":"superseded","reason":"source_head_drift"} on head drift instead of throwing. The workflow already maps a superseded reservation to a successful no-op with a clean queue completion (Export exact review generation result → outcome=success); the newer push's own event (backstopped by the scheduled sweep) owns reviewing the current head. No lease comment is posted on this path.

Proof

• Regression test: fake gh serves a live PR head different from EXACT_REVIEW_SOURCE_HEAD_SHA; asserts exit 0, superseded JSON, and that no lease comment is created. Red on pre-fix code (command exits 1), green with the fix.
• Full test/command.test.ts suite passes.
• Autoreview (codex, xhigh): clean, "patch is correct (0.99)".

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed July 30, 2026, 12:19 PM ET / 16:19 UTC.

ClawSweeper review

What this changes

The PR makes an exact-review lease reservation whose queued source head no longer matches the live pull-request head return a superseded no-op result instead of failing the review queue item.

Merge readiness

⛔ Blocked until real behavior proof from a real setup is added - 4 items remain

Keep open: the queue-handling change is narrowly scoped and has focused regression coverage, but this PR modifies the release-owned changelog and provides only mock/test evidence rather than an after-fix workflow run. Likely related people: steipete (high confidence), based on the merged queue-reliability work in #962.

Priority: P2
Reviewed head: 303c44c52b86a8f0667e297b7b2387889a88dcf1

Review scores

Measure	Result	What it means
Overall readiness	🦪 silver shellfish (2/6)	The implementation is focused and regression-tested, but mock-only proof and the release-owned changelog edit keep the PR below merge-ready quality.
Proof confidence	🦪 silver shellfish (2/6)	Needs real behavior proof before merge: The PR body describes a fake-gh regression test and suite results, but it does not include after-fix evidence from a real exact-review workflow run; attach redacted live output or logs before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs real behavior proof before merge: The PR body describes a fake-gh regression test and suite results, but it does not include after-fix evidence from a real exact-review workflow run; attach redacted live output or logs before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	4 items	Head-drift handling: The proposed branch replaces the source-head mismatch exception with a stderr diagnostic plus a JSON superseded result, so the reservation command returns without creating a lease. Focused regression coverage: The added command test supplies a different live PR head through fake gh, asserts exit success and the superseded result, and verifies no lease-comment write occurs. Release-note policy conflict: The branch adds a normal contributor-PR entry to the release-owned changelog, while the checked repository policy directs normal PRs to preserve release-note context in the PR body and commit message instead.
Findings	1 actionable finding	[P2] Keep release-owned changelog out of this PR
Security	None	None.

How this fits together

Exact-review events enter ClawSweeper's durable review queue and reserve a lease before the workflow generates a Codex review. The reservation step compares the queued authority head with GitHub's current pull-request head, then either reserves work or reports that a newer push owns the review.

flowchart TD
  A[Queued exact review] --> B[Lease reservation]
  B --> C[Compare queued and live PR heads]
  C -->|Heads match| D[Reserve review lease]
  C -->|Head moved| E[Superseded no-op]
  E --> F[Successful queue completion]
  G[Newer PR push] --> A

Loading

Before merge

• Add real behavior proof - Needs real behavior proof before merge: The PR body describes a fake-gh regression test and suite results, but it does not include after-fix evidence from a real exact-review workflow run; attach redacted live output or logs before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Keep release-owned changelog out of this PR (P2) - Remove this entry from CHANGELOG.md. Repository policy reserves release notes for the release process and directs normal PRs to keep user-facing release context in the PR body and commit message instead.
• Resolve merge risk (P1) - Merging changes live review-queue failure classification without captured after-fix evidence from an actual workflow run showing a stale source head completes successfully, posts no lease comment, and does not consume a review-failure attempt.
• Complete next step (P2) - The remaining merge blockers are contributor-owned real workflow proof and repository release-note policy compliance, not a safe autonomous repair task.

Findings

• [P2] Keep release-owned changelog out of this PR — CHANGELOG.md:21

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Patch surface	3 files affected; 96 added, 2 removed	The functional change is small and localized to one command branch, one regression test, and one release-owned documentation file.

Merge-risk options

Maintainer options:

1. Prove the no-op path before merge (recommended)
   Remove the release-owned changelog edit and attach redacted output from a real exact-review workflow run showing head drift completes as superseded without creating a lease comment or spending a failure attempt.

Technical review

Best possible solution:

Keep the focused reservation-command and regression-test change, remove the release-owned CHANGELOG.md edit, and add redacted proof from an actual exact-review workflow run covering the stale-head no-op path.

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

Yes, from source: the focused test models a queued exact-review authority whose source head differs from the live pull-request head and demonstrates the intended command boundary. The review evidence does not include an independently captured real workflow run.

Is this the best way to solve the issue?

No: returning a superseded result is the narrowest apparent queue fix, but the submitted path is not yet the best merge-ready solution because it includes a release-owned changelog edit and lacks real after-fix workflow proof.

Full review comments:

• [P2] Keep release-owned changelog out of this PR — CHANGELOG.md:21
  Remove this entry from CHANGELOG.md. Repository policy reserves release notes for the release process and directs normal PRs to keep user-facing release context in the PR body and commit message instead.
  Confidence: 0.99

Overall correctness: patch is incorrect
Overall confidence: 0.97

AGENTS.md: found and applied where relevant.

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

Labels

Label changes:

• add P2: This is a bounded reliability repair for review-queue failures with limited blast radius.
• add merge-risk: 🚨 automation: The changed result controls whether an exact-review workflow succeeds, creates queue state, and preserves its failure budget.
• add rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🦐 gold shrimp.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body describes a fake-gh regression test and suite results, but it does not include after-fix evidence from a real exact-review workflow run; attach redacted live output or logs before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Label justifications:

• P2: This is a bounded reliability repair for review-queue failures with limited blast radius.
• merge-risk: 🚨 automation: The changed result controls whether an exact-review workflow succeeds, creates queue state, and preserves its failure budget.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🦐 gold shrimp.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body describes a fake-gh regression test and suite results, but it does not include after-fix evidence from a real exact-review workflow run; attach redacted live output or logs before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence

What I checked:

• Head-drift handling: The proposed branch replaces the source-head mismatch exception with a stderr diagnostic plus a JSON superseded result, so the reservation command returns without creating a lease. (src/clawsweeper.ts:22944, 303c44c52b86)
• Focused regression coverage: The added command test supplies a different live PR head through fake gh, asserts exit success and the superseded result, and verifies no lease-comment write occurs. (test/command.test.ts:279, 303c44c52b86)
• Release-note policy conflict: The branch adds a normal contributor-PR entry to the release-owned changelog, while the checked repository policy directs normal PRs to preserve release-note context in the PR body and commit message instead. (CHANGELOG.md:21, 303c44c52b86)
• Current-main ownership trail: The related merged queue-reliability change fix(queue): resolve scheduled target branches #962 was authored by steipete and merged as commit 56d32bee74e43b8784b5a6aca14cad3beba7a73f, making that work the closest current-main provenance for this queue path. (src/clawsweeper.ts:22944, 56d32bee74e4)

Likely related people:

• steipete: Authored the merged related queue repair fix(queue): resolve scheduled target branches #962, whose implementation and deployment context directly precede this stale exact-head follow-up. (role: recent queue reliability contributor; confidence: high; commits: 56d32bee74e4; files: src/clawsweeper.ts, .github/workflows/sweep.yml, test/command.test.ts)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Remove the CHANGELOG.md entry and retain release context in the PR body or commit message.
• Add redacted output from an actual exact-review workflow run that exercises source-head drift, then request a fresh review if the PR body changes.

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.