tumwater 0.2.0 → 0.4.0

package/dist/src/merge/merge-git.js

@@ -1,26 +1,30 @@
 import fs from "node:fs";
 import path from "node:path";
-import { COMMIT_IDENT, git, gitTry, runGit } from "../git/git-run.js";
-import { writeBytesAtomic } from "../files/files.js";
+import { GitError, committerIdentArgs, git, gitCouldNotStart, gitTry, runGit } from "../git/git-run.js";
+import { readTextOrNull, writeBytesAtomic } from "../files/files.js";
 import { currentBranch, gitLines, headOf } from "../git/git.js";
-import { unquotePorcelainPath } from "../git/git-diff.js";
-import { CONFIG_BASENAME, configPath, primaryWorktreeLockPath } from "../paths.js";
-import { withStateLockAsync } from "../concurrency/lock.js";
-import { errorMessage } from "../text/text.js";
+import { treeDiffFiles, unquotePorcelainPath } from "../git/git-diff.js";
+import { errCode } from "../errno.js";
+import { CONFIG_BASENAME, configPath } from "../paths.js";
+import { withPrimaryWorktreeLockAsync } from "../concurrency/lock.js";
+import { TUMWATER_SOURCE, warnEventBestEffort } from "../events/events.js";
+import { errorFirstLine, errorMessage, joinWithMore } from "../text/text.js";
 /** Git plumbing for the merge flow: rebasing a worktree branch onto main, inspecting and
  * finishing a conflicted rebase, and fast-forwarding main — the mechanics, with no merge policy
  * of their own. Merge policy (lock → rebase → verify → ff, conflict resolution, batch ff)
  * lives in merge-to-main.ts on top of these. Moved here from merge-to-main.ts: the cluster started
- * as merge-to-main.ts-only helpers (organize tick 78, moving them out of git/git.ts), but the
+ * as merge-to-main.ts-only helpers (organize run 78, moving them out of git/git.ts), but the
  * merger and the batch merger grew to call them directly, leaving merge-to-main.ts exporting
  * generic rebase/ff plumbing that had nothing to do with merging. */
 /** Paths currently in conflict (unmerged) in the worktree. C-quoted names are decoded to
  * real paths — a non-ASCII conflicted file arrives as `"h\303\251llo.ts"` (core.quotePath is on
  * by default), and undecoded it does not exist on disk: hasConflictMarkers could never read
  * it, so an unresolved conflict in such a file passed the marker check and continueRebase
- * committed its markers to main. */
+ * committed its markers to main. A failed `git diff` throws: read as "no conflicts", it sent
+ * the resolver's caller straight to `continueRebase`, which stages every marker, and a
+ * stopped cherry-pick down the path that deletes a hand-back's ref. */
 export async function conflictedFiles(wt) {
-    const out = await gitTry(wt, "diff", "--name-only", "--diff-filter=U");
+    const out = await git(wt, "diff", "--name-only", "--diff-filter=U");
     return gitLines(out).map(unquotePorcelainPath);
 }
 /** How many main commits the resolver prompt lists, and how many body lines it keeps per
@@ -61,22 +65,26 @@ export async function mainCommitsTouching(wt, since, mainBranch, files) {
  * cleaning up: "rebased" (including already up to date), "conflict" (the rebase stopped on
  * unmerged paths, which remain in the worktree for a resolver), or "other" (any other
  * failure). Shared by the two rebase wrappers below, which differ only in cleanup policy.
- * Rebase — not merge — keeps main's history linear: each tick merges as its own commit on top
- * of whatever main holds. */
+ * Rebase — not merge — keeps main's history linear: each run merges as its own commit on top
+ * of whatever main holds. A rebase git could not start throws (gitCouldNotStart), as does a
+ * failed conflict listing: neither says anything about the change, so neither may count as a
+ * merge conflict. */
 async function attemptRebase(wt, mainBranch) {
     try {
         // The -c ident is needed for the rewritten committer identity. diff3 carries the base
         // section of every conflict, which the deterministic backlog resolver reads
         // (plans/parallel-work-instances.md, part 3/7); rebaseOntoMain aborts on conflict, so the
         // marker style only matters to its leave-conflicts sibling.
-        await runGit(wt, [...COMMIT_IDENT, "-c", "merge.conflictStyle=diff3", "rebase", mainBranch]);
+        await runGit(wt, [...(await committerIdentArgs(wt)), "-c", "merge.conflictStyle=diff3", "rebase", mainBranch]);
         return "rebased";
     }
-    catch {
+    catch (err) {
+        if (gitCouldNotStart(err))
+            throw err;
         return (await conflictedFiles(wt)).length > 0 ? "conflict" : "other";
     }
 }
-/** Rebase the worktree branch onto main (main may have advanced during the tick).
+/** Rebase the worktree branch onto main (main may have advanced during the run).
  * Returns false and aborts the rebase on conflict. */
 export async function rebaseOntoMain(wt, mainBranch) {
     const state = await attemptRebase(wt, mainBranch);
@@ -98,23 +106,44 @@ export async function rebaseOntoMainLeaveConflicts(wt, mainBranch) {
  * The one marker definition hasConflictMarkers and conflictHunkRanges share, so the ranges a
  * conflict prompt names are exactly the blocks the marker check later rejects. */
 const MARKER_EDGE = /^(<{7}|>{7})( |$)/m;
+/** One file's marker check: "clean", "marked" (holds a start/end marker) or "unreadable". Only
+ * a path with no file (deleted, a parent replaced, or a directory/gitlink) is clean without
+ * being read; any other read error cannot be vouched for. */
+function markerState(wt, f) {
+    // lstat, not stat: a symlink is never followed out of the worktree. A symlink (or a
+    // directory/gitlink) holds no text of its own to check, so it counts as clean — the same
+    // policy secret-leaks (INV-G4) already pins: a change that adds a symlink writes no
+    // content, and its target is not what the worktree put there.
+    let st;
+    try {
+        st = fs.lstatSync(path.join(wt, f));
+    }
+    catch (err) {
+        const code = errCode(err);
+        return code === "ENOENT" || code === "ENOTDIR" ? "clean" : "unreadable";
+    }
+    if (!st.isFile())
+        return "clean";
+    let text;
+    try {
+        text = fs.readFileSync(path.join(wt, f), "utf8");
+    }
+    catch (err) {
+        const code = errCode(err);
+        return code === "ENOENT" || code === "ENOTDIR" || code === "EISDIR" ? "clean" : "unreadable";
+    }
+    return MARKER_EDGE.test(text) ? "marked" : "clean";
+}
 /** True if any of the given files still contains a git conflict marker.
- * A deleted file counts as resolved (the resolver chose the deletion). */
+ * A missing path counts as resolved (the resolver chose the deletion), but an unreadable one
+ * counts as conflicted: a check that cannot read a file cannot vouch for it. */
 export function hasConflictMarkers(wt, files) {
     // Only start/end markers are checked: every real conflict block carries them, while a bare
     // `=======` line is legitimate content (a markdown setext or RST underline of exactly seven
     // characters), and flagging it would reject clean resolutions forever. A resolver that
     // leaves only a separator line behind is treated as resolved; its stray line is content the
     // project's own tests can catch.
-    return files.some((f) => {
-        const p = path.join(wt, f);
-        try {
-            return MARKER_EDGE.test(fs.readFileSync(p, "utf8"));
-        }
-        catch {
-            return false;
-        }
-    });
+    return files.some((f) => markerState(wt, f) !== "clean");
 }
 /** How many conflict hunks a conflict prompt lists per file: every hunk of a typical backlog or
  * code conflict, and a bound on a file pasted over wholesale. */
@@ -150,13 +179,17 @@ export function conflictHunkRanges(text) {
  * file counts, backlog or code; a deleted, unreadable or binary (NUL-bearing) file lists none. */
 export function conflictedFileHunks(wt, files) {
     return files.map((f) => {
-        let text = "";
+        // Deleted or unreadable reads as empty: no ranges to name. A symlink is never followed
+        // out of the worktree (it holds no text of its own), so it too reads as empty.
+        let full = path.join(wt, f);
         try {
-            text = fs.readFileSync(path.join(wt, f), "utf8");
+            if (!fs.lstatSync(full).isFile())
+                return { path: f, hunks: [], more: 0 };
         }
         catch {
-            // Deleted or unreadable: no ranges to name.
+            return { path: f, hunks: [], more: 0 };
         }
+        const text = readTextOrNull(full) ?? "";
         const all = text.includes("\0") ? [] : conflictHunkRanges(text);
         return { path: f, hunks: all.slice(0, MAX_LISTED_HUNKS), more: Math.max(0, all.length - MAX_LISTED_HUNKS) };
     });
@@ -168,8 +201,17 @@ export function conflictedFileHunks(wt, files) {
  * lines on main (PLANS.md "Robust conflict landing, part 2/2"). Builds on hasConflictMarkers
  * above, the shared definition of what a marker is. */
 export function conflictMarkerReason(wt, files) {
-    const marked = files.filter((f) => hasConflictMarkers(wt, [f]));
-    return marked.length > 0 ? `conflict markers remain in: ${marked.join(", ")}` : undefined;
+    const states = files.map((f) => [f, markerState(wt, f)]);
+    const named = (state) => states.filter(([, s]) => s === state).map(([f]) => f);
+    const marked = named("marked");
+    const unreadable = named("unreadable");
+    const clauses = [
+        ...(marked.length > 0 ? [`conflict markers remain in: ${marked.join(", ")}`] : []),
+        ...(unreadable.length > 0
+            ? [`could not be read to check for conflict markers: ${unreadable.join(", ")}`]
+            : []),
+    ];
+    return clauses.length > 0 ? clauses.join("; ") : undefined;
 }
 /** Conclude an in-progress rebase with everything in the worktree as the resolution.
  * GIT_EDITOR=true so `rebase --continue` can never block on a commit-message prompt. A
@@ -179,24 +221,40 @@ export function conflictMarkerReason(wt, files) {
  * added; the caller aborts and reports merge_conflict. */
 export async function continueRebase(wt) {
     await git(wt, "add", "-A");
-    await runGit(wt, [...COMMIT_IDENT, "rebase", "--continue"], { GIT_EDITOR: "true" });
+    await runGit(wt, [...(await committerIdentArgs(wt)), "rebase", "--continue"], { GIT_EDITOR: "true" });
     return headOf(wt, "HEAD");
 }
 /** The live config's bytes, when the merge about to fast-forward `ref` would delete it
  * (plans/portability.md §4b/7): the config file exists, is tracked in the current index (and
  * HEAD — a staged-or-dirty config makes `git merge --ff-only` refuse below, so the two agree
  * on every merge that can succeed), and is absent from the incoming tree. Anything else —
- * already untracked, already absent, present in `ref` — needs no preserve step. */
+ * already untracked, already absent, present in `ref` — needs no preserve step. A failed
+ * `cat-file` reads as absent, which only preserves bytes the write-back then leaves alone. */
 export async function configBytesToPreserve(root, ref) {
     const cfg = configPath(root);
     if (!fs.existsSync(cfg))
         return null;
-    if ((await gitTry(root, "ls-files", "--error-unmatch", CONFIG_BASENAME)) === null)
+    if (!(await configTracked(root)))
         return null;
     if ((await gitTry(root, "cat-file", "-e", `${ref}:${CONFIG_BASENAME}`)) !== null)
         return null;
     return fs.readFileSync(cfg);
 }
+/** Whether the live config is tracked in `root`'s index: `ls-files --error-unmatch` exits 1 for
+ * an untracked path, and any other failure throws. Read as "untracked", an unreadable index or
+ * a git that could not start skipped the preserve step, so a merge that untracks the config
+ * deleted the live one. */
+async function configTracked(root) {
+    try {
+        await git(root, "ls-files", "--error-unmatch", CONFIG_BASENAME);
+        return true;
+    }
+    catch (err) {
+        if (err instanceof GitError && err.code === 1)
+            return false;
+        throw err;
+    }
+}
 /** The preserve step's write-back, restore-only-when-absent: write the saved bytes only when
  * the live config is absent at write-back time. The merge deletes the file mid-window, so a
  * config request applied in that window (3/7's applyConfigRequest runs outside the merge lock)
@@ -219,7 +277,9 @@ export function restoreConfigBytes(root, saved) {
  * files update), otherwise a local ref push. Returns true on success. The working-tree arm
  * preserves the live config across a merge that untracks it (plans/portability.md §4b/7):
  * without the write-back, the commit that removes the tracked config would delete the team's
- * running config out from under it and the next config poll would fall back to defaults. */
+ * running config out from under it and the next config poll would fall back to defaults. The
+ * merge has already happened by the time of the write-back, so a failed write-back is a warning
+ * event and the function still returns null. */
 export async function ffMainToOrWhy(root, ref, mainBranch) {
     const primaryBranch = await currentBranch(root);
     if (primaryBranch === mainBranch) {
@@ -228,7 +288,7 @@ export async function ffMainToOrWhy(root, ref, mainBranch) {
         // that read before this merge can rename its stale whole-file write over the merged change.
         // The ref-push arm below touches no working tree and needs no lock; the save/merge/restore
         // stays one short section, never held across a build re-check.
-        return withStateLockAsync(primaryWorktreeLockPath(root), async () => {
+        return withPrimaryWorktreeLockAsync(root, async () => {
             const saved = await configBytesToPreserve(root, ref);
             try {
                 await git(root, "merge", "--ff-only", ref);
@@ -236,7 +296,13 @@ export async function ffMainToOrWhy(root, ref, mainBranch) {
             catch (err) {
                 return ffFailureReason(root, ref, mainBranch, err);
             }
-            restoreConfigBytes(root, saved);
+            try {
+                restoreConfigBytes(root, saved);
+            }
+            catch (err) {
+                warnEventBestEffort(root, TUMWATER_SOURCE, `main fast-forwarded, but writing the live ${CONFIG_BASENAME} back failed: ` +
+                    `${errorMessage(err)}; restore it by hand (it is no longer tracked on main)`);
+            }
             return null;
         });
     }
@@ -249,14 +315,87 @@ export async function ffMainToOrWhy(root, ref, mainBranch) {
     }
 }
 /** Why a fast-forward to `ref` failed: main having moved off `ref`'s base (a commit that did not
- * take the merge lock) is named with its new head and subject; any other cause reports git's own
- * error, e.g. a dirty primary checkout. */
+ * take the merge lock) is named with its new head and subject; a dirty primary checkout is
+ * reported with the files it would overwrite; any other cause reports git's first error line. */
 async function ffFailureReason(root, ref, mainBranch, err) {
     if ((await gitTry(root, "merge-base", "--is-ancestor", mainBranch, ref)) === null) {
         const now = await gitTry(root, "log", "-1", "--format=%h %s", mainBranch);
         return `main moved outside the merge lock (now ${now?.trim() ?? mainBranch})`;
     }
-    return `fast-forward failed: ${errorMessage(err).trim().split("\n")[0]}`;
+    const blockers = overwriteBlockers(errorMessage(err));
+    if (blockers.uncommitted.length > 0 || blockers.untracked.length > 0) {
+        return `fast-forward failed: ${overwriteBlockedReason(blockers)}`;
+    }
+    return `fast-forward failed: ${errorFirstLine(err)}`;
+}
+/** The files git lists under its two "would be overwritten by merge:" headers. */
+export function overwriteBlockers(gitError) {
+    const out = { uncommitted: [], untracked: [] };
+    let group = null;
+    for (const line of gitError.split("\n")) {
+        if (line.includes("Your local changes to the following files would be overwritten by merge:")) {
+            group = out.uncommitted;
+        }
+        else if (line.includes("untracked working tree files would be overwritten by merge:")) {
+            group = out.untracked;
+        }
+        else if (group && line.startsWith("\t")) {
+            group.push(line.trim());
+        }
+        else {
+            group = null;
+        }
+    }
+    return out;
+}
+const MAX_BLOCKERS_LISTED = 5;
+/** Why a dirty primary checkout blocks a merge: up to 5 files per group. Callers prefix it with
+ * their own stage (`fast-forward failed: `, or none from the pre-flight). */
+export function overwriteBlockedReason(blockers) {
+    const list = (names) => joinWithMore(names, MAX_BLOCKERS_LISTED);
+    const groups = [];
+    if (blockers.uncommitted.length > 0)
+        groups.push(`uncommitted: ${list(blockers.uncommitted)}`);
+    if (blockers.untracked.length > 0)
+        groups.push(`untracked: ${list(blockers.untracked)}`);
+    const where = `the primary checkout (${groups.join("; ")})`;
+    return `the merge would overwrite files in ${where} — commit, stash or remove them there`;
+}
+/** The primary checkout's dirty paths a merge to `tip` would overwrite, read before any check
+ * runs: null when the checkout is not on main (the ref push touches no working tree), when
+ * nothing the merge changes is dirty, or when a git read fails — the fast-forward still decides. */
+export async function primaryCheckoutBlockers(root, mainBranch, tip) {
+    if ((await currentBranch(root)) !== mainBranch)
+        return null;
+    const changed = await treeDiffFiles(root, mainBranch, tip);
+    const status = await gitTry(root, "--no-optional-locks", "status", "--porcelain=v1", "-z", "--untracked-files=all");
+    if (changed === null || status === null)
+        return null;
+    const untrackedSet = new Set();
+    const dirtySet = new Set();
+    const records = status.split("\0");
+    for (let i = 0; i < records.length; i++) {
+        const rec = records[i];
+        if (rec.length < 4)
+            continue;
+        const xy = rec.slice(0, 2);
+        const file = rec.slice(3);
+        if (xy === "??") {
+            untrackedSet.add(file);
+            continue;
+        }
+        dirtySet.add(file);
+        if (xy.startsWith("R") || xy.startsWith("C")) {
+            const source = records[++i];
+            if (source)
+                dirtySet.add(source);
+        }
+    }
+    const out = {
+        uncommitted: changed.filter((f) => dirtySet.has(f)),
+        untracked: changed.filter((f) => untrackedSet.has(f)),
+    };
+    return out.uncommitted.length > 0 || out.untracked.length > 0 ? out : null;
 }
 /** Boolean form of ffMainToOrWhy for callers that need no reason. */
 export async function ffMainTo(root, ref, mainBranch) {

package/dist/src/merge/merge-pipeline.js

@@ -3,17 +3,18 @@ import { warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
 import { errorMessage } from "../text/text.js";
 import { deleteRef } from "../git/git.js";
 import { removeMergeChange, writeMergeOutcome } from "./merge-slot.js";
+import { requeueKeptChange } from "./merge-requeue.js";
 import { mergeRefName, rejectedRefName } from "../paths.js";
 /** A fresh pipeline: nothing in flight anywhere — no verification running, no approved change
  * waiting, no merge holding main. The orchestrator builds one per team start (orchestrator.ts). */
 export function newMergePipeline() {
-    return { verifying: new Map(), approved: new Map(), merge: null };
+    return { verifying: new Map(), approved: new Map(), merge: null, postReview: null };
 }
 /** Every merge task in flight — each verification holding its permit, and the merge — for the
  * shutdown and restart waits. A parked verification is not one of them: it has started nothing, and
  * a shutdown (its controller) or a closed start gate (at its grant) settles it without a run. */
 export function mergeTasks(p) {
-    return [...[...p.verifying.values()].filter((v) => !v.parked), ...(p.merge ? [p.merge] : [])];
+    return [...[...p.verifying.values()].filter((v) => !v.parked), ...(p.merge ? [p.merge] : []), ...(p.postReview && !p.postReview.parked ? [p.postReview] : [])];
 }
 /** Everything `tumwater abort --role` can reach: every task in flight, plus each approved change
  * waiting with no task of its own. A parked verification is out of reach, as a plainly queued entry
@@ -85,7 +86,7 @@ export async function discardPinnedRefs(root, roles) {
  * write-back, so no settled entry can keep a stale marker or lose its outcome write. The pinned-ref
  * discard stays with the callers: only a user abort throws work away, and the merge discards its
  * whole stack at once rather than change by change. */
-export async function settleMergeOutcome(root, entry, state, result, durationMs, usage, file) {
+export async function settleMergeOutcome(root, entry, state, result, durationMs, usage, file, mainBranch) {
     writeMergeOutcome(root, entry, state, result, durationMs, usage, file);
     // A revision that merges ends the rejected change's life: drop the rejected ref (plans/revise-
     // rejected.md). A rejection repoints or deletes it in merge-core.ts, so this is the only
@@ -96,4 +97,15 @@ export async function settleMergeOutcome(root, entry, state, result, durationMs,
         await deleteRef(root, rejectedRefName(entry.role));
     }
     removeMergeChange(root, entry.role);
+    // A kept change goes straight back on the queue (the callers pass the main branch; a
+    // direct caller without one leaves the retry to the author's leftover recovery). The write-back
+    // above already happened, so a failure here must not lose the settled outcome.
+    if (mainBranch !== undefined) {
+        try {
+            await requeueKeptChange(root, mainBranch, entry, state, result);
+        }
+        catch (err) {
+            warnEventBestEffort(root, entry.role, `could not re-queue the kept change: ${errorMessage(err)}`);
+        }
+    }
 }

package/dist/src/merge/merge-post-review.js

@@ -0,0 +1,214 @@
+import { withProviderLease } from "../concurrency/provider-lease.js";
+import { reviewRunConfig, seamConcurrencyKey } from "../config/config-views.js";
+import { subscribeEvents, warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
+import { deleteRef, headOf, subjectOfCommit } from "../git/git.js";
+import { ensureDetachedWorktree } from "../git/worktree.js";
+import { useWorktree } from "../git/worktree-use.js";
+import { postReviewWorktreePath, reviewFixRef } from "../paths.js";
+import { POST_REVIEW_FAILURE_LIMIT, addPostReview, readPostReviews, reviewMergedCommit, settlePostReview, } from "../review/post-merge-review.js";
+import { shortSha } from "../text/format.js";
+import { formatDate } from "../text/datetime.js";
+import { collapseWhitespace, errorMessage } from "../text/text.js";
+import { fileBugsOnMain } from "../backlog/backlog-archive.js";
+import { abortOnShutdown, acquireUnlessAborted, guardMergeTask } from "./merge-pipeline.js";
+import { resolveWaitStage } from "./merge-slot.js";
+import { mergeToMain } from "./merge-to-main.js";
+import { MERGE_TIER, resolveAuthor, VERIFY_TIER } from "./merge-verify.js";
+/** One poll of the post-merge reviews (review.afterMerge): a rejected-and-not-fixed commit is
+ * answered by the reviewer's own landed fix (Forward, never back 1/6) — never by a revert — and
+ * the next unreviewed commit starts its review when a permit is free right now. One review at a
+ * time; starts a task and returns. */
+export function drainPostReviews(ctx, p) {
+    const pending = readPostReviews(ctx.root);
+    if (pending.length === 0)
+        return;
+    if (p.postReview !== null || ctx.startHeld())
+        return;
+    // A `fixed` entry is a settled record naming both shas (the reviewed commit and its landed fix)
+    // — it is not a pending unreviewed commit, so it is never re-reviewed (Forward never back 1a/6).
+    const next = pending.find((e) => e.rejected === undefined && e.fixed === undefined);
+    if (next)
+        p.postReview = startPostReview(ctx, p, next);
+}
+function startPostReview(ctx, p, entry) {
+    const { root, semaphore } = ctx;
+    const task = { promise: Promise.resolve(), controller: new AbortController(), roles: [], userAborted: false, parked: true };
+    const detach = abortOnShutdown(ctx.signal, task.controller);
+    const author = resolveAuthor(ctx, entry.role);
+    const key = seamConcurrencyKey(reviewRunConfig(ctx.liveConfig), ctx.piDefault);
+    const run = (async () => {
+        try {
+            if (!semaphore.canLeaseAtOnce(VERIFY_TIER, key))
+                return; // permits are busy; try again next poll
+            const lease = await acquireUnlessAborted(semaphore, VERIFY_TIER, task.controller.signal, key);
+            task.parked = false;
+            if (lease === null)
+                return;
+            let outcome;
+            try {
+                outcome = await reviewMergedCommit(root, ctx.liveConfig, entry, (opts) => author.runGatePi(opts), task.controller.signal);
+            }
+            finally {
+                lease.release();
+            }
+            if (task.controller.signal.aborted)
+                return; // a shutdown: the entry stays for the next generation
+            if (outcome.kind === "approve")
+                settlePostReview(root, entry.commit, null);
+            else if (outcome.kind === "reject")
+                settlePostReview(root, entry.commit, { ...entry, rejected: outcome.reasons });
+            else if (outcome.kind === "fixed")
+                await mergeReviewerFix(ctx, entry, outcome.fix);
+            else if (outcome.kind === "exhausted") {
+                // A self-fix chain at the backstop: reviewMergedCommit has already recorded the surviving
+                // findings; the entry is cleared so nothing re-reviews it (Forward never back 2/6).
+                settlePostReview(root, entry.commit, null);
+            }
+            else {
+                const failures = (entry.failures ?? 0) + 1;
+                warnEventBestEffort(root, entry.role, `the post-merge review of ${shortSha(entry.commit)} failed (${outcome.detail})`);
+                if (failures >= POST_REVIEW_FAILURE_LIMIT) {
+                    warnEventBestEffort(root, entry.role, `dropping the post-merge review of ${shortSha(entry.commit)} after ${failures} failed runs; it stays on main unreviewed`);
+                    await fileDroppedReview(ctx, entry, outcome.detail);
+                    settlePostReview(root, entry.commit, null);
+                }
+                else
+                    settlePostReview(root, entry.commit, { ...entry, failures, lastFailure: outcome.detail });
+            }
+        }
+        catch (err) {
+            warnEventBestEffort(root, TUMWATER_SOURCE, `the post-merge review of ${shortSha(entry.commit)} could not run: ${errorMessage(err)}`);
+        }
+        finally {
+            detach();
+            p.postReview = null;
+        }
+    })();
+    task.promise = guardMergeTask(root, `post-merge review of ${shortSha(entry.commit)}`, run);
+    return task;
+}
+/** File a post-merge review that is being dropped at POST_REVIEW_FAILURE_LIMIT (its commit stays
+ * on main, so it becomes ordinary backlog work a role can pick up) as one BUGS.md `## Open`
+ * entry in a best-effort `tumwater(operator):` commit. A skipped filing (off-base checkout or a
+ * BUGS.md with uncommitted changes) or a throw logs one warning and returns, so a filing problem
+ * never prevents the entry from being dropped and never throws out of the drain. */
+async function fileDroppedReview(ctx, entry, failure) {
+    const root = ctx.root;
+    try {
+        const outcome = await fileBugsOnMain(root, [
+            {
+                title: `post-merge review of ${shortSha(entry.commit)} never reached a verdict (found by the review role ${formatDate(new Date())})`,
+                // The failure text is untrusted and can carry newlines (a backend/stderr trace) or a
+                // `## `/code-fence line that would make appendBugEntryLocked call fail() and exit the
+                // whole drain; folding it to one line keeps the body structurally sound, so a hostile
+                // failure skips the filing via the ordinary throw path instead of killing the process.
+                body: collapseWhitespace(`The post-merge review of commit \`${entry.commit}\` (${entry.summary}) never reached a verdict: ${failure}. It stays on main as ordinary unreviewed backlog work.`),
+            },
+        ], () => "File an unreviewed post-merge commit in BUGS.md");
+        if (outcome.status === "skipped") {
+            warnEventBestEffort(root, entry.role, `could not file the dropped post-merge review of ${shortSha(entry.commit)} in BUGS.md (${outcome.reason})`);
+        }
+    }
+    catch (err) {
+        warnEventBestEffort(root, entry.role, `could not file the dropped post-merge review of ${shortSha(entry.commit)} in BUGS.md: ${errorMessage(err)}`);
+    }
+}
+/** Land a reviewer's fix commit on main through the ordinary change path — mergeToMain, whose
+ * gate runs over the fix tree and whose mergeLockDir lock serializes it with every other write
+ * to main — then settle the entry `fixed` naming both shas. A landing that fails (a conflict, a
+ * red gate, a refused fast-forward) leaves main at the reviewed commit and keeps the entry with
+ * its failure recorded for the next poll's retry, exactly as a failed run is kept today — up to
+ * the same POST_REVIEW_FAILURE_LIMIT the verdict-less-review path obeys, so the at-risk doctor
+ * row/alert's "one more failed run drops it" stays true and the reviewer is not re-run forever;
+ * the review-fix ref survives so leftover recovery can still reach the commit.
+ * Throws when git could not start; a failed merge itself returns a non-terminal RunResult and
+ * is never a throw. */
+async function mergeReviewerFix(ctx, entry, fix) {
+    const author = resolveAuthor(ctx, entry.role);
+    // The fix merge's conflict resolver rides the same provider lease the merge slot's resolver
+    // does (merge-drain.ts startMerge): the MERGE_TIER lease is keyed on the resolver config's
+    // provider and rides in the provider-lease store, so a conflict resolution counts against the
+    // strong tier's cap like any other strong-tier run instead of acquiring a provider unchecked.
+    const runPi = async (wt, prompt, sessionName, config) => {
+        const key = config ? seamConcurrencyKey(config, ctx.piDefault) : undefined;
+        const hooks = resolveWaitStage(ctx.root, entry.role);
+        if (!ctx.semaphore.canLeaseAtOnce(MERGE_TIER, key))
+            hooks.waiting();
+        const lease = await ctx.semaphore.acquireLease(MERGE_TIER, key);
+        hooks.granted();
+        try {
+            return await withProviderLease(lease, ctx.semaphore, () => author.runMergePi(wt, prompt, sessionName, config), { piDefault: ctx.piDefault });
+        }
+        finally {
+            lease.release();
+        }
+    };
+    // Land through the merge's own write path — mergeToMain fast-forwards main under the shared
+    // mergeLockDir mutex, so a fix landing and the ordinary merge slot serialize on main's one
+    // writer either way — but from the DEDICATED post-review worktree (which already holds the fix
+    // commit), NOT the shared `_merge` checkout that belongs to the merge slot. That removes the
+    // race the merge slot's mergeApprovedChangeIn has: each resets and merges its own worktree, so
+    // a fix landing can never reset or merge the shared `_merge` worktree concurrently with the
+    // merge slot (both could start in one poll), while main's writes stay serialized by the real
+    // mergeLockDir mutex. Hold the worktree from before ensureDetachedWorktree through the merge
+    // (plans/disk-floor.md part 2/4); this task is the only user of the post-review worktree while
+    // p.postReview is held, so the reset-and-merge cannot collide with a fresh review.
+    let result;
+    // The commit that actually merges, from our own `merged` event (not the pre-rebase `fix`):
+    // mergeToMain rebases `fix` onto main's tip, so when main moved under the review the landed
+    // commit is a different sha — and `fixed` must name a commit that is provably on main.
+    // Subscribing mirrors the merge slot's startMerge, so a concurrent merge of another role
+    // landing after ours cannot overwrite the sha we record.
+    const mergedMine = new Map();
+    const unsubscribe = subscribeEvents((e) => {
+        if (e.type === "merged" && typeof e.commit === "string")
+            mergedMine.set(e.source, e.commit);
+    });
+    try {
+        result = await useWorktree(ctx.root, postReviewWorktreePath(ctx.root), async () => {
+            const wt = await ensureDetachedWorktree(ctx.root, postReviewWorktreePath(ctx.root), fix);
+            return mergeToMain({
+                root: ctx.root,
+                role: entry.role,
+                mainBranch: ctx.mainBranch,
+                config: ctx.liveConfig,
+                exemptPaths: ctx.liveConfig.review.exemptPaths,
+                runNumber: author.state.runs,
+                runPi,
+                // A conflict resolution of the reviewer's fix is resolver-authored bytes the reviewer
+                // never judged; unlike the merge slot's mergeApprovedChangeIn there is no review gate
+                // here to re-run, so a diverging resolution must not merge on the in-lock build check
+                // alone (BUGS.md 2026-10-01). Withhold it: the landing reports the conflict, the fix
+                // ref and the entry stay for the next poll's retry, and main never carries resolver
+                // bytes it was never judged against.
+                recheckResolved: async () => ({ verdict: "retry" }),
+            }, wt, (await subjectOfCommit(wt, fix)) ?? `Fix ${shortSha(entry.commit)}`);
+        });
+    }
+    finally {
+        unsubscribe();
+    }
+    if (result === "changed") {
+        const merged = mergedMine.get(entry.role) ?? (await headOf(ctx.root, ctx.mainBranch));
+        await deleteRef(ctx.root, reviewFixRef(entry.commit)); // the fix is on main; the ref has done its job
+        settlePostReview(ctx.root, entry.commit, { ...entry, fixed: merged }); // the entry names the landed fix
+        // A landed fix is a new post-review entry (Forward never back 2/6): re-queue it so the next
+        // iteration reviews it like any unreviewed commit, counting its round toward the same
+        // REVISION_BACKSTOP — the round lives on the fix commit's `Revision:` trailer.
+        addPostReview(ctx.root, { commit: merged, role: entry.role, summary: entry.summary });
+        return;
+    }
+    // A failed merge: main is unmoved, the fix ref survives. Count it against the drop limit -
+    // keeping the entry (with the failure recorded) so the next poll retries the review, but
+    // dropping it once the limit is reached, so the reviewer is not re-run unboundedly.
+    const failures = (entry.failures ?? 0) + 1;
+    if (failures >= POST_REVIEW_FAILURE_LIMIT) {
+        warnEventBestEffort(ctx.root, entry.role, `dropping the post-merge review of ${shortSha(entry.commit)} after ${failures} failed fix merges; the fix stays unreviewed`);
+        await deleteRef(ctx.root, reviewFixRef(entry.commit)); // the merge gave up on the fix; the ref must not pin it forever
+        await fileDroppedReview(ctx, entry, `fix did not merge: ${result}`);
+        settlePostReview(ctx.root, entry.commit, null);
+        return;
+    }
+    warnEventBestEffort(ctx.root, entry.role, `the post-merge fix of ${shortSha(entry.commit)} could not merge (${result}); it stays queued for the next poll`);
+    settlePostReview(ctx.root, entry.commit, { ...entry, failures, lastFailure: `fix did not merge: ${result}` });
+}