tumwater 0.2.0 → 0.3.0

package/dist/src/review/review.js

@@ -1,18 +1,10 @@
-import { REVIEW_RESUME_LIMIT, saveLoopState } from "../loop/loop-state.js";
-import { modelSelectorField, resolvedAgentConfig, reviewRunConfig } from "../config/config-views.js";
 import { logEventBestEffort, warnEventBestEffort } from "../events/events.js";
-import { git } from "../git/git-run.js";
-import { changeBaseRev, headOf, patchId } from "../git/git.js";
-import { aheadOfMainDiff, aheadOfMainFiles, revisionInterdiff } from "../git/git-diff.js";
+import { headOf, patchId } from "../git/git.js";
+import { aheadOfMainFiles } from "../git/git-diff.js";
 import { resetWorktreeToMain } from "../git/worktree.js";
-import { nativeLogPath, piLogPath } from "../paths.js";
-import { readPrinciples } from "../prompt/principles.js";
-import { buildReviewPrompt, buildReviewResumePrompt } from "../prompt/gate-prompts.js";
-import { agentSessionResumable } from "../agent/agent-backend.js";
-import { requestNoRerun, requestVerdict } from "./review-followup.js";
-import { parseVerdict } from "./review-verdict.js";
-import { recordReview } from "../tick/tick-apply.js";
-import { shortSha } from "../text/format.js";
+import { recordReview } from "../run/run-apply.js";
+import { baseRoleOf } from "../roles/runner-ids.js";
+import { errorMessage } from "../text/text.js";
 import { firstReason } from "../text/phrases.js";
 import { isExemptDiff } from "./exemptions.js";
 import { falseFixReason } from "../verdict/fix-claim.js";
@@ -20,52 +12,72 @@ import { conflictMarkerReason } from "../merge/merge-git.js";
 import { protectedEditReason } from "./protected-edits.js";
 import { secretLeakReason } from "./secret-leaks.js";
 import { backlogStructureReason } from "../backlog/backlog-structure.js";
-import { suiteRerunWarning } from "./suite-rerun.js";
+import { idleWithoutProviderLease } from "../concurrency/provider-lease.js";
 import { setMergeStage } from "../merge/merge-slot.js";
 import { gateBuildPrecheck } from "./review-precheck.js";
-/** Attach the review gate's pi runs onto a partial GateResult — `run` plus the optional
- * verdict-recovery follow-up (`followUpRun`) and no-re-run nudge (`nudgeRun`) fields, each
- * present only when its turn actually ran. Spelled once so every return site of
- * reviewAheadOfMain that carries runs shares one shape for the usage-folding caller
- * (merge-core.ts folds run, then followUpRun, then nudgeRun), instead of one conditional
- * spread per site that a new run kind would have to update everywhere. */
-function withRuns(r, run, followUp, nudge) {
-    return {
-        ...r,
-        run,
-        ...(followUp ? { followUpRun: followUp } : {}),
-        ...(nudge ? { nudgeRun: nudge } : {}),
-    };
-}
-/** Put the worktree back on the exact head the gate reviewed: the reviewer's only output is its
- * verdict, so a commit it made must never reach the merge pin or the next re-review. */
-async function restoreReviewedHead(wt, head, root, role) {
-    const now = await headOf(wt, "HEAD").catch(() => null);
-    if (now && now !== head) {
-        warnEventBestEffort(root, role, `the reviewer moved HEAD to ${shortSha(now)} during review; restored the reviewed head ${shortSha(head)}`);
+export { REVIEW_FAILURE_LIMIT } from "./review-run.js";
+import { restoreReviewedHead, runReviewer, withRuns } from "./review-run.js";
+/** In-place retries of a failed reviewer run within one verify, after the first run. */
+const REVIEW_RETRIES = 2;
+/** The pause before each retry (ReviewContext.retryDelayMs overrides it in tests). */
+const REVIEW_RETRY_DELAY_MS = 30_000;
+/** Overrides the pause for tests that drive a whole runner or orchestrator, where no context
+ * reaches the review. */
+const REVIEW_RETRY_DELAY_ENV = "TUMWATER_REVIEW_RETRY_DELAY_MS";
+/** A second pool slot for the gate check, or null when the context cannot lease one, none is free
+ * right now, or the lease failed (the check then runs first, in the change's own slot). */
+async function leaseCheckSlot(ctx, head) {
+    if (!ctx.leaseCheckSlot)
+        return null;
+    try {
+        return await ctx.leaseCheckSlot(head);
+    }
+    catch (err) {
+        warnEventBestEffort(ctx.root, ctx.role, `no second workspace for the gate check (${errorMessage(err)}); running it before the review`);
+        return null;
     }
-    await git(wt, "reset", "--hard", head);
 }
-/** Consecutive failed reviews of one branch HEAD after which the leftover is discarded with
- * a warning: a misconfigured reviewer model must not be able to wedge a loop into re-reviewing
- * the same commit forever. */
-export const REVIEW_FAILURE_LIMIT = 3;
+/** Start the gate check in `lease`'s checkout of `head`. A rejection is recorded, not applied:
+ * resetting the change's branch is left to reviewAttempt, after the reviewer has stopped. */
+function startOverlappedCheck(ctx, state, head, lease) {
+    const overlap = { abort: new AbortController(), done: false };
+    const reject = async (reasons) => {
+        overlap.rejectedReasons = reasons;
+        return { decision: "rejected", detail: firstReason(reasons) };
+    };
+    overlap.gate = gateBuildPrecheck({ ...ctx, wt: lease.dir }, state, head, reject)
+        .then((pre) => {
+        overlap.done = true;
+        if (pre.resolved)
+            overlap.abort.abort();
+        else
+            setMergeStage(ctx.root, ctx.role, "reviewing");
+        return pre;
+    }, (err) => {
+        overlap.done = true;
+        overlap.abort.abort();
+        throw err;
+    })
+        .finally(() => lease.release());
+    overlap.gate.catch(() => { }); // surfaced where reviewAttempt awaits it
+    return overlap;
+}
 /** Run the adversarial review gate over everything ahead of main in `wt` and update `state`
- * accordingly. Shared by the tick path (after commitAll) and leftover recovery
+ * accordingly. Shared by the run path (after commitAll) and leftover recovery
  * (leftover.ts's recoverLeftover) — every path
  * that can move a commit into main routes through here, so no crash or abort path smuggles
  * unreviewed work in:
  * - gate disabled, or an already-approved HEAD, or an exempt (doc-only) diff → merge as-is;
- * - a new HEAD carrying the last approved patch (lastApprovedPatchId) → approved after the
+ * - a new HEAD carrying an approved patch (approvedPatchIds) → approved after the
  *   build pre-check, with no reviewer run;
  * - approve → record lastApprovedHead and its patch-id, and discard the reviewer's stray
  *   working-tree edits (its only output channel is the verdict);
  * - reject → reset the branch to main, record reasons in state.lastReview (injected into the
- *   role's next tick prompt), log review_rejected;
+ *   role's next run prompt), log review_rejected;
  * - fail with an unparseable reply (the reviewer ran to completion but emitted no VERDICT) →
  *   one capped follow-up turn on the reviewer's own session asks for the missing line
  *   (mirroring requestSummary — BUGS.md 2026-09-29); only a follow-up that also yields
- *   nothing counts the strike. Leave the commit on the branch for the next tick's re-review,
+ *   nothing counts the strike. Leave the commit on the branch for the next run's re-review,
  *   counting consecutive failures per HEAD; past REVIEW_FAILURE_LIMIT discard the leftover
  *   with a warning.
  * - fail because the run itself failed (transport/spawn/timeout, pi.ok false) → leave the
@@ -77,7 +89,7 @@ export const REVIEW_FAILURE_LIMIT = 3;
  * `highFriction` marks a change whose authoring run burned more than the configured turn/time
  * thresholds (plans/refusal-and-thrash.md): the flag rides along in the review prompt so the
  * reviewer applies extra scrutiny to whether the work should exist at all. */
-export async function reviewAheadOfMain(ctx, state, summary, commitBody, highFriction) {
+async function reviewAttempt(ctx, state, summary, commitBody, highFriction, retry) {
     const { root, role, wt, mainBranch, config } = ctx;
     if (!config.review.enabled) {
         state.reviewResume = undefined;
@@ -86,7 +98,7 @@ export async function reviewAheadOfMain(ctx, state, summary, commitBody, highFri
     const head = await headOf(wt, "HEAD");
     // The one reject path: every rejection of this HEAD — deterministic build-check failure or
     // model verdict — shares this bookkeeping. Record lastReview (injected into the role's next
-    // tick prompt), reset the failure count (a verdict about this HEAD is a successful review
+    // run prompt), reset the failure count (a verdict about this HEAD is a successful review
     // either way), discard the branch by resetting it to main, and log review_rejected.
     // Callers attach `run` when a pi run was consumed.
     const reject = async (reasons, durationMs) => {
@@ -103,6 +115,22 @@ export async function reviewAheadOfMain(ctx, state, summary, commitBody, highFri
         });
         return { decision: "rejected", detail: firstReason(reasons) };
     };
+    // Every exit below that keeps the change leaves the worktree at the head this gate reviewed.
+    const keep = async (r) => {
+        await restoreReviewedHead(wt, head, root, role);
+        return r;
+    };
+    // Settle the attempt on an overlapped check that did not pass: the sequential pre-check's own
+    // outcome, with the reviewer's run (when one started) dropped and no verdict recorded. A
+    // rejection is applied now, after the reviewer stopped touching the tree; every other outcome
+    // keeps the change at the head the gate reviewed.
+    const settleFailedCheck = async (o, pre, pi) => {
+        state.reviewResume = undefined;
+        const settled = o.rejectedReasons
+            ? await reject(o.rejectedReasons)
+            : await keep(pre.resolved ?? { decision: "failed", detail: "the gate check did not complete" });
+        return pi ? withRuns(settled, pi, null, null) : settled;
+    };
     // Already reviewed this exact HEAD (e.g. a merge_blocked retry): do not burn another run.
     if (state.lastApprovedHead === head) {
         state.reviewResume = undefined;
@@ -130,7 +158,7 @@ export async function reviewAheadOfMain(ctx, state, summary, commitBody, highFri
         // Fixed must have its fix's symbols on this tree, or it records code that does not
         // exist (BUGS.md 2026-09-22 — 9cea8c3 merged a Fix paragraph naming runScriptGroup
         // and signalTree with no source behind it). A deterministic rejection, like the
-        // pre-check below: no pi run consumed, reasons injected into the author's next tick.
+        // pre-check below: no pi run consumed, reasons injected into the author's next run.
         const falseFix = await falseFixReason(wt, mainBranch, files);
         if (falseFix)
             return reject([falseFix]);
@@ -154,336 +182,103 @@ export async function reviewAheadOfMain(ctx, state, summary, commitBody, highFri
     // Deterministic build pre-check — after BOTH early returns above (an md-only diff cannot
     // break the build) and before any reviewer run or the phase/event that would show
     // "reviewing": a deterministic rejection never shows as reviewing on the dashboards. Both
-    // gate callers (the tick path and leftover.ts's recoverLeftover) get it for free. Its run,
+    // gate callers (the run path and leftover.ts's recoverLeftover) get it for free. Its run,
     // flake re-run, and attribution live in review-precheck.ts (the check run itself lives in
     // runScopedBuildCheck, shared with the merge path's in-lock re-check); a resolved result
     // here is returned verbatim and a pass hands the verified head to the merge path below.
     // The pre-check sets the merge cell's stage (a no-op outside a queued merge) —
     // "build-check" while it runs, "reviewing" when the reviewer run starts below.
-    const pre = await gateBuildPrecheck(ctx, state, head, reject);
-    if (pre.resolved) {
-        state.reviewResume = undefined;
-        return pre.resolved;
-    }
-    const { verifiedHead, verifiedByHarness } = pre;
+    // A retried attempt keeps the first attempt's passing pre-check (a green, or a red naming
+    // only main's known failures): the tree is the same head.
     // A review judges a diff, not a sha: a head carrying exactly the patch this role's last
     // approval judged (the approved head cleanly rebased onto a moved main) reuses that verdict
     // instead of paying a second reviewer run. Only the model review is reused — the pre-check
-    // above has just run on this tree (a failure rejected it there), and its verifiedHead rides
-    // on the result as for any approval.
+    // has just run on this tree (a failure rejected it there), and its verifiedHead rides on the
+    // result as for any approval.
     const reviewedPatchId = (await patchId(wt, mainBranch, head)) ?? undefined;
-    if (state.lastApprovedPatchId !== undefined) {
-        if (reviewedPatchId === state.lastApprovedPatchId) {
-            state.reviewResume = undefined;
-            state.lastApprovedHead = head;
-            return { decision: "approved", verifiedHead };
-        }
-    }
-    // The reviewer's model selector (plans/model-tiers.md "Observability"): resolved from the
-    // same config the run below gets, so the event names what the reviewer actually runs on —
-    // the budget fallback included. Omitted when no model is configured (pi's own default).
-    const reviewCfg = reviewRunConfig(config);
-    // The team claude config dir (plans/notes-command.md "Keeping funes out of team runs"), so
-    // a claude review's resume guard looks under the same dir the review run writes its transcript
-    // to — a team that set one must resume under it, not the default ~/.claude.
-    const claudeConfigDir = resolvedAgentConfig(config, "claude").configDir;
-    // A progressing timeout left this run's session for the next attempt (LoopState.reviewResume):
-    // resume it only while the patch is unchanged (the same diff), the resume budget lasts, and
-    // the directory still holds a gate session to `--continue`. Otherwise the stale marker is
-    // cleared and this attempt reviews the change from scratch.
-    const priorResume = state.reviewResume;
-    const resuming = priorResume !== undefined &&
-        priorResume.patchId === reviewedPatchId &&
-        priorResume.attempts < REVIEW_RESUME_LIMIT &&
-        agentSessionResumable(priorResume.sessionDir, {
-            kind: "gate",
-            agent: reviewCfg.agent ?? "pi",
-        }, claudeConfigDir);
-    if (resuming) {
-        // Count the resume before the run: a crash must not let the same session be resumed
-        // forever without ever spending the budget.
-        priorResume.attempts += 1;
-        saveLoopState(root, state);
-    }
-    else {
-        state.reviewResume = undefined;
-    }
-    // The directory this run actually uses: a resumed attempt continues the timed-out run's
-    // session, a fresh one its own. Both the run and its follow-up turns must target this dir —
-    // a follow-up that used ctx.sessionDir while the review resumed another dir would
-    // `--continue` a session that never held this review.
-    const reviewSessionDir = resuming ? state.reviewResume.sessionDir : ctx.sessionDir;
-    // The follow-up turns (verdict recovery, no-re-run nudge) continue the just-finished review,
-    // so they must read the same directory. A fresh run's dir is already ctx's, so only a resume
-    // needs the override.
-    const followupCtx = reviewSessionDir === ctx.sessionDir ? ctx : { ...ctx, sessionDir: reviewSessionDir };
-    logEventBestEffort(root, {
-        source: role,
-        type: "review_start",
-        head,
-        ...(ctx.revisionRound !== undefined ? { revision: ctx.revisionRound } : {}),
-        ...(resuming ? { resumed: true } : {}),
-        ...modelSelectorField(reviewCfg),
-    });
-    // Persist the phase BEFORE the run so a dashboard mid-review shows "reviewing" and a crash
-    // mid-review is distinguishable from a crash mid-author-run on resume (stray edits are the
-    // reviewer's then, not the author's). Cleared at tick end alongside `running`.
-    state.phase = "review";
-    saveLoopState(root, state);
-    // Freeze the revision the diff is measured from once, before the run: main moves while a
-    // merge is approved, and a reviewer comparing against the live `main` ref reads another loop's
-    // just-merged work as this change reverting it (BUGS.md 2026-10-06). The prompt names this SHA
-    // and tells the reviewer to compare against it instead.
-    const base = await changeBaseRev(wt, mainBranch);
-    const diff = await aheadOfMainDiff(wt, mainBranch);
-    // A revision's re-review gets the prior review's objections and the interdiff between the two
-    // versions (plans/revise-rejected.md part 2/2), so it checks what the revision had to resolve
-    // instead of starting from no memory. A missing prior object yields an empty interdiff, never
-    // a throw (revisionInterdiff).
-    const priorReview = ctx.priorReview
-        ? {
-            round: ctx.revisionRound ?? 1,
-            reasons: ctx.priorReview.reasons,
-            interdiff: await revisionInterdiff(wt, mainBranch, ctx.priorReview.sha, head),
-        }
-        : undefined;
-    // The reviewer run's wall time rides on its verdict event: a reviewer that takes an hour per
-    // merge on local hardware is a team-level cost an operator must be able to see.
-    const reviewStartedAt = Date.now();
-    // The reviewer's started tool calls, collected only when the no-re-run rule stands (a verified
-    // pre-check) — the one case the suite-rerun tripwire below can fire.
-    const reviewerCalls = [];
-    // The merge cell switches to the reviewer run's live detail (no-op outside a queued
-    // merge). runPi writes the run's `tumwater_run` label line before spawning pi, and that
-    // line resets the gate progress accumulator, so the cell never shows a previous run's counts.
-    setMergeStage(root, role, "reviewing");
-    // The author's claimed WHY/RISK/VERIFIED ride along when present — checking those claims
-    // against the actual diff is exactly the adversarial angle (recovery merges reconstruct
-    // them from the pinned commit's message).
-    const pi = await ctx.runGatePi({
-        cwd: wt,
-        kind: "gate",
-        prompt: resuming
-            ? buildReviewResumePrompt(base, state.reviewResume.patchId)
-            : buildReviewPrompt(diff, summary, commitBody, readPrinciples(root), highFriction, verifiedByHarness, base, undefined, priorReview),
-        // The reviewer runs on its own time budget (review.timeoutSeconds), never longer than a
-        // tick's: a timed-out review is a FAILED run (pi.ok false), so it takes the dead-backend
-        // path below — commit kept, no strike — and re-merges through the author's next tick
-        // instead of holding the merge queue for a whole authoring tick.
-        config: reviewCfg,
-        // This run's own session directory (per-run, keyed by tick and pinned sha): a follow-up
-        // turn, or a later attempt that resumes this review, continues exactly this run instead
-        // of whichever review wrote last. A fresh review carries no --continue — the reviewer
-        // must not inherit the author's context — and old files are collected by the age-based
-        // prune at orchestrator start.
-        sessionDir: reviewSessionDir,
-        ...(resuming ? { continueSession: true } : {}),
-        sessionName: `tumwater-review-${role}-${ctx.tick}`,
-        rawLogFile: piLogPath(root, role),
-        nativeLogFile: nativeLogPath(root, role, reviewCfg.agent ?? "pi"),
-        // Label this run in the shared transcript (src/ui/transcript.ts renders it as
-        // `── review @ <ts> ──`) so an operator can tell reviewer runs from author ticks.
-        label: "review",
-        signal: ctx.signal,
-        // A stalled tool call during review hangs the gate just like one during authoring —
-        // name it in the event feed while the quiet watchdog still counts down.
-        onToolCallStalled: (message) => warnEventBestEffort(root, role, message),
-        onToolCallStart: verifiedByHarness
-            ? (toolName, args) => {
-                reviewerCalls.push({ toolName, args });
+    const patchApproved = reviewedPatchId !== undefined && state.approvedPatchIds?.includes(reviewedPatchId) === true;
+    // The check runs alongside the reviewer when a second pool slot is free right now (Fast merge
+    // part 12): it starts here, in its own checkout of this head, while the reviewer run below
+    // starts in the change's own slot. An already-approved patch has no reviewer to overlap, and
+    // with no free slot (or no way to lease one) the check runs first, as it always did.
+    const afterMerge = (config.review.afterMerge ?? []).includes(baseRoleOf(role));
+    let overlap;
+    if (!retry.pre) {
+        const lease = patchApproved || afterMerge ? null : await leaseCheckSlot(ctx, head);
+        if (lease)
+            overlap = startOverlappedCheck(ctx, state, head, lease);
+        else {
+            const pre = await gateBuildPrecheck(ctx, state, head, reject);
+            if (pre.resolved) {
+                state.reviewResume = undefined;
+                return pre.resolved;
             }
-            : undefined,
-        // A gate run that read an image its model cannot see is logged, not killed (plans/
-        // image-input.md "Detecting a blind read"): the reviewer keeps working from what it CAN
-        // see, and the image_blind line names the file, the model, and this tick so the operator
-        // knows the diff was judged under a blind read.
-        onBlindRead: (path, action) => logEventBestEffort(root, {
-            source: role,
-            type: "image_blind",
-            run: ctx.tick,
-            path,
-            model: reviewCfg.model,
-            action,
-        }),
-    });
-    // A reviewer told the pre-check passed that re-ran the full suite anyway held the merge
-    // slot and loaded the shared host for a result the harness already had (BUGS.md 2026-09-23:
-    // scratch copies under /tmp, `npm ci` and `npm test` there). Warned on every outcome, abort
-    // included — the run happened either way; the verdict itself is not touched.
-    const rerun = suiteRerunWarning(reviewerCalls);
-    if (rerun)
-        warnEventBestEffort(root, role, rerun);
-    // Every exit below that keeps the change leaves the worktree at the head this gate reviewed.
-    const keep = async (r) => {
-        await restoreReviewedHead(wt, head, root, role);
-        return r;
-    };
-    if (pi.aborted) {
-        // Shutdown mid-review: fail closed — the commit stays on the branch and the
-        // resumed/following tick re-reviews it via the combined ahead-of-main diff. Any resume
-        // marker from an earlier attempt is dropped: an abort says nothing about the diff, and the
-        // next attempt starts clean rather than inheriting a half-counted session.
-        state.reviewResume = undefined;
-        return keep(withRuns({ decision: "failed", aborted: true }, pi, null, null));
-    }
-    // The bounded nudge (BUGS.md 2026-10-02): the reviewer broke the no-re-run rule despite a
-    // green pre-check, so one turn on its own session names the call and asks it to finish
-    // without re-running. A repeat on the nudge's own tool calls fails the review — strike-free,
-    // commit kept, re-reviewed under the normal path — instead of paying a third suite run.
-    let nudge = null;
-    let nudgeRepeat = null;
-    if (rerun && pi.ok) {
-        const nudgeCalls = [];
-        nudge = await requestNoRerun(followupCtx, rerun, nudgeCalls);
-        if (nudge?.aborted) {
-            return keep(withRuns({ decision: "failed", aborted: true }, pi, null, nudge));
-        }
-        nudgeRepeat = nudge ? (suiteRerunWarning(nudgeCalls) ?? null) : null;
-        if (nudgeRepeat) {
-            warnEventBestEffort(root, role, `${nudgeRepeat} the repeat fails this review: the commit stays, and the merge re-reviews it without a third suite run`);
-        }
-    }
-    let verdict = parseVerdict(pi.verdictText ?? "");
-    // The nudge turn's reply can carry the verdict the review run lost — use it before spending
-    // any other recovery turn, but never on a repeat (the repeat fails the review regardless).
-    if (!verdict && nudge && !nudgeRepeat) {
-        const recovered = parseVerdict(nudge.verdictText ?? "");
-        if (recovered) {
-            verdict = recovered;
-            warnEventBestEffort(root, role, "the reviewer's reply had no VERDICT line — recovered it with the no-re-run nudge turn on its session");
+            retry.pre = { verifiedHead: pre.verifiedHead, knownMainFailures: pre.knownMainFailures };
         }
     }
-    // A run that FAILED (`ok` false: transport error, failed spawn, timeout) produced no reply,
-    // so no follow-up is attempted — it is evidence about the backend, and the strike-free
-    // branch below keeps it that way (BUGS.md 2026-09-20). Only a run that completed and
-    // replied without a parseable VERDICT earns the recovery turn: that is evidence about the
-    // reviewer's output format, not about the diff, and it is as recoverable as the author
-    // side's missing SUMMARY (BUGS.md 2026-09-29). The nudge turn is the bounded follow-up when
-    // the reviewer broke the no-re-run rule — one turn total, so a spent nudge never earns the
-    // verdict-recovery turn on top.
-    let followUp = null;
-    if (!verdict && pi.ok && !nudge) {
-        followUp = await requestVerdict(followupCtx);
-        if (followUp?.aborted)
-            return keep(withRuns({ decision: "failed", aborted: true }, pi, followUp, nudge));
-        const recovered = followUp ? parseVerdict(followUp.verdictText ?? "") : null;
-        if (recovered) {
-            verdict = recovered;
-            warnEventBestEffort(root, role, "the reviewer's reply had no VERDICT line — recovered it with a follow-up turn on its own session");
-        }
-    }
-    // A repeat after the nudge (BUGS.md 2026-10-02): the reviewer re-ran the suite on the nudge
-    // turn too. Fail the review — strike-free like a dead backend (BUGS.md 2026-09-20): the
-    // commit stays for the next merge's re-review, the discard counter never advances, and no
-    // rejection is recorded against the author's diff.
-    if (nudgeRepeat) {
-        const message = `${nudgeRepeat} The review is failed on this repeat: the commit is kept, and the merge re-reviews it under the normal path.`;
-        logEventBestEffort(root, { source: role, type: "review_failed", head, message, durationMs: Date.now() - reviewStartedAt });
+    const knownMainFailures = retry.pre?.knownMainFailures;
+    // A role listed in review.afterMerge merges on its gate alone: the deterministic rejects and the
+    // pre-check above still ran, and the merged commit is reviewed after it lands
+    // (reviewMergedCommit, run by the merge pipeline's post-review drain).
+    if (afterMerge && retry.pre) {
         state.reviewResume = undefined;
-        recordReview(state, "failed", [message], head);
-        return keep(withRuns({ decision: "failed", detail: message }, pi, followUp, nudge));
+        state.lastApprovedHead = head;
+        return { decision: "approved", verifiedHead: retry.pre.verifiedHead };
     }
-    if (!verdict) {
-        const followUpError = followUp && !followUp.ok ? followUp.errorMessage : undefined;
-        // The nudge turn's own death is backend evidence, exactly like the verdict-recovery
-        // follow-up's: a nudge that died with a transport error is the backend failing after the
-        // reviewer judged nothing — about the world, never about the diff — so the strike-free
-        // branch below must see it, and its error names the failure.
-        const nudgeError = nudge && !nudge.ok ? nudge.errorMessage : undefined;
-        // A progressing timeout of the REVIEW run itself (never a follow-up or nudge turn, both of
-        // which run only after pi ok) leaves the session for the next attempt while the patch is
-        // identifiable and the resume budget lasts. That is what makes the recorded failure honest:
-        // while a resume remains the next attempt continues this review, and once the budget is
-        // spent or the failure cannot resume, it reviews the change from scratch (BUGS.md
-        // 2026-09-30). A string rewrite of runPi's exact suffix, so any other cause — and the plain
-        // no-progress timeout, which promises nothing — passes through untouched.
-        const resumeAttempts = resuming ? state.reviewResume?.attempts ?? 0 : 0;
-        const resumeRemains = !pi.ok &&
-            !pi.aborted &&
-            pi.timedOutProgressing &&
-            reviewedPatchId !== undefined &&
-            resumeAttempts < REVIEW_RESUME_LIMIT &&
-            // The promise must be one the next attempt can keep: only a dir whose backend still
-            // holds a gate session to resume earns the marker (and the "continues this review"
-            // wording). Without this a backend that leaves no session file would record a resume the
-            // next attempt silently declines, reviewing from scratch anyway.
-            agentSessionResumable(reviewSessionDir, {
-                kind: "gate",
-                agent: reviewCfg.agent ?? "pi",
-            }, claudeConfigDir);
-        const reviewTimeoutRewrite = (message) => message.replace(" — session and worktree edits preserved for resume", resumeRemains
-            ? " — the commit is kept; the next attempt continues this review"
-            : " — the commit is kept; the next attempt reviews it from scratch");
-        const message = reviewTimeoutRewrite(followUpError ??
-            nudgeError ??
-            pi.errorMessage ??
-            `no parseable VERDICT line in the reviewer's reply${nudge
-                ? ", even after the no-re-run nudge turn on its session"
-                : followUp
-                    ? ", even after a follow-up turn on its session"
-                    : ""}`);
-        logEventBestEffort(root, { source: role, type: "review_failed", head, message, durationMs: Date.now() - reviewStartedAt });
-        // A dead reviewer must never destroy committed work (BUGS.md 2026-09-20): leave the commit
-        // for the next tick's re-review and do not advance the per-HEAD discard counter. That
-        // holds for the review run itself (BUGS.md 2026-09-20), for the verdict-recovery
-        // follow-up (BUGS.md 2026-09-29), and for the no-re-run nudge turn (BUGS.md 2026-10-02):
-        // each one's death is the backend failing after the reviewer had already judged nothing —
-        // evidence about the world, never about the diff.
-        if (!pi.ok || (followUp && !followUp.ok) || (nudge && !nudge.ok)) {
-            if (resumeRemains) {
-                // Record the session this run used (the resumed directory, or this fresh run's own),
-                // so the next attempt `--continue`s exactly it.
-                state.reviewResume = {
-                    patchId: reviewedPatchId,
-                    sessionDir: reviewSessionDir,
-                    attempts: resumeAttempts,
-                    at: Date.now(),
-                };
-                saveLoopState(root, state);
-            }
-            else {
-                state.reviewResume = undefined;
-            }
-            recordReview(state, "failed", [message], head);
-            const configError = pi.configError || Boolean(followUp?.configError) || Boolean(nudge?.configError);
-            return keep(withRuns({ decision: "failed", detail: message, ...(configError ? { configError: true } : {}) }, pi, followUp, nudge));
-        }
-        // Consecutive failures of THIS HEAD only: a new commit (new HEAD) starts fresh. Read
-        // *before* overwriting lastReview with this failure.
-        const prev = state.lastReview;
-        const sameHead = prev?.verdict === "failed" && prev.head === head;
+    if (patchApproved && retry.pre) {
         state.reviewResume = undefined;
-        state.unreviewFailures = (sameHead ? (state.unreviewFailures ?? 0) : 0) + 1;
-        recordReview(state, "failed", [message], head);
-        let discarded = false;
-        if ((state.unreviewFailures ?? 0) >= REVIEW_FAILURE_LIMIT) {
-            await resetWorktreeToMain(wt, mainBranch);
-            state.unreviewFailures = 0; // The HEAD is gone; nothing left to count against.
-            discarded = true;
-            warnEventBestEffort(root, role, `discarding unreviewed leftover after ${REVIEW_FAILURE_LIMIT} failed reviews (${shortSha(head)})`);
-        }
-        const failed = { ...withRuns({ decision: "failed", detail: message }, pi, followUp, nudge), ...(discarded ? { discarded: true } : {}) };
-        return discarded ? failed : keep(failed);
+        state.lastApprovedHead = head;
+        return { decision: "approved", verifiedHead: retry.pre.verifiedHead };
     }
-    if (verdict.verdict === "reject") {
-        const rejected = await reject(verdict.reasons, Date.now() - reviewStartedAt);
-        return withRuns({ ...rejected }, pi, followUp, nudge);
+    return runReviewer(ctx, state, {
+        head, overlap, knownMainFailures, retry, summary, commitBody, highFriction,
+        reviewedPatchId, reject, keep, settleFailedCheck,
+    });
+}
+/** Review the change ahead of main, retrying a failed reviewer run in place (twice, 30 s apart)
+ * before the attempt ends `failed`: a run that timed out, was killed, died in transport or at
+ * the provider, or stated no VERDICT after its recovery turn. A resumable session is resumed,
+ * otherwise the retry starts fresh (reviewAttempt). A configuration error and an abort are not
+ * retried. While the reviewer's provider is held the retry waits for the hold to lift and
+ * costs nothing. Each pause runs without the caller's team permit (idleWithoutProviderLease):
+ * a verification hands its lease back while it waits and takes it back before the next attempt.
+ * See reviewAttempt for the rest of the gate's contract. */
+export async function reviewAheadOfMain(ctx, state, summary, commitBody, highFriction) {
+    const retry = { attempt: 1, retriesLeft: ctx.retries ?? REVIEW_RETRIES };
+    const delayMs = ctx.retryDelayMs ?? Number(process.env[REVIEW_RETRY_DELAY_ENV] ?? REVIEW_RETRY_DELAY_MS);
+    for (;;) {
+        const result = await reviewAttempt(ctx, state, summary, commitBody, highFriction, retry);
+        if (!result.retryable)
+            return result;
+        for (const run of [result.run, result.followUpRun, result.nudgeRun])
+            if (run)
+                ctx.foldUsage?.(run);
+        const held = ctx.reviewHeld?.() ?? false;
+        warnEventBestEffort(ctx.root, ctx.role, `the reviewer run failed (${result.detail ?? "no detail"}) — ${held ? "waiting for the provider hold to lift, then " : ""}retrying the review in place`);
+        // The pause holds no team permit: a verification's lease is handed back while it waits and
+        // re-taken before the next attempt, so a reviewer that keeps failing does not starve the roles.
+        await idleWithoutProviderLease(async () => {
+            await sleepUnlessAborted(delayMs, ctx.signal);
+            while (ctx.reviewHeld?.() && !ctx.signal?.aborted)
+                await sleepUnlessAborted(Math.min(delayMs, 5000), ctx.signal);
+        }, ctx.signal);
+        if (ctx.signal?.aborted)
+            return { decision: "failed", aborted: true };
+        if (!held)
+            retry.retriesLeft -= 1;
+        retry.attempt += 1;
     }
-    // Approve: record the reviewed HEAD and discard any stray working-tree edits the reviewer
-    // made while reading around — its only output channel is the verdict. The patch-id keys the
-    // approval to the diff it judged; unreadable, it clears any older one (no reuse at all).
-    state.lastApprovedHead = head;
-    state.lastApprovedPatchId = reviewedPatchId;
-    state.reviewResume = undefined;
-    recordReview(state, "approve", verdict.reasons, head);
-    state.unreviewFailures = 0;
-    await restoreReviewedHead(wt, head, root, role);
-    logEventBestEffort(root, {
-        source: role,
-        type: "review_verdict",
-        head,
-        reason: verdict.reasons[0],
-        durationMs: Date.now() - reviewStartedAt,
+}
+function sleepUnlessAborted(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted)
+            return resolve();
+        const done = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        signal?.addEventListener("abort", done, { once: true });
     });
-    return withRuns({ decision: "approved", verifiedHead }, pi, followUp, nudge);
 }