tumwater 0.2.0 → 0.3.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, revert: 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,90 @@
+import { revertSkipReason } from "../baseline/main-revert.js";
+import { reviewRunConfig, seamConcurrencyKey } from "../config/config-views.js";
+import { warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
+import { POST_REVIEW_FAILURE_LIMIT, readPostReviews, reviewMergedCommit, settlePostReview, } from "../review/post-merge-review.js";
+import { shortSha } from "../text/format.js";
+import { errorMessage } from "../text/text.js";
+import { abortOnShutdown, acquireUnlessAborted, guardMergeTask } from "./merge-pipeline.js";
+import { resolveAuthor, VERIFY_TIER } from "./merge-verify.js";
+/** Pipelines with a revert skip check in flight, so a poll does not start a second one. */
+const skipChecks = new WeakSet();
+/** One poll of the post-merge reviews (review.afterMerge): a reviewed-and-rejected commit goes to
+ * the revert slot when it and the merge slot are free, 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;
+    const rejected = pending.find((e) => e.rejected !== undefined);
+    // The entry stays in the file until its revert has run (startRevert settles it), so a shutdown,
+    // or the main-red watch replacing the slot, only delays the revert to a later poll.
+    if (rejected && p.revert === null && p.merge === null && !skipChecks.has(p)) {
+        // Check the skip reason before filling the slot: drainMerge starts the revert in the same poll.
+        skipChecks.add(p);
+        const culprit = { commit: rejected.commit, runner: rejected.role, failingTests: [], tip: rejected.commit, postReview: { reasons: rejected.rejected } };
+        void revertSkipReason(ctx.root, ctx.mainBranch, culprit)
+            .then((skip) => {
+            if (skip !== null) {
+                settlePostReview(ctx.root, rejected.commit, null);
+                warnEventBestEffort(ctx.root, rejected.role, `not reverting ${shortSha(rejected.commit)} after its post-merge rejection: ${skip}`);
+            }
+            else if (p.revert === null && p.merge === null)
+                p.revert = culprit;
+        })
+            .finally(() => skipChecks.delete(p));
+    }
+    if (p.postReview !== null || ctx.startHeld())
+        return;
+    const next = pending.find((e) => e.rejected === 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 {
+                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`);
+                    settlePostReview(root, entry.commit, null);
+                }
+                else
+                    settlePostReview(root, entry.commit, { ...entry, failures });
+            }
+        }
+        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;
+}

package/dist/src/merge/merge-queue-render.js

@@ -1,16 +1,15 @@
-// vocabulary: plain
 /** The renderer behind `tumwater queue` — the operator-facing text for the merge queue view the
  * reader gathers (merge-queue.ts's readMergeQueue, beside it): one line per queued merge
  * in execution order, plus the count of queue files the reader skipped. Pure function of the
  * collected view and a `now` instant — no I/O, no clock reads — so the age it prints can be
  * pinned by a test. */
-import { humanSeconds, secondsSince } from "../text/datetime.js";
+import { humanAgo, humanSeconds, secondsSince, secondsUntil } from "../text/datetime.js";
 import { roleLabel } from "../roles/role-labels.js";
 import { shortSha } from "../text/format.js";
 import { plural } from "../text/phrases.js";
 import { mergeChanges, MERGE_STAGE_LABELS } from "./merge-slot.js";
-/** The bracketed-label text for one queue entry, in the wording the loop rows use (status-model's
- * loopPhase): `merge <elapsed> · <stage>` while a verify or the merge holds the change,
+/** The bracketed-label text for one queue entry, in the wording the role rows use (status-model's
+ * rolePhase): `merge <elapsed> · <stage>` while a verify or the merge holds the change,
  * `approved, awaiting merge` once approved, and "" when the marker is absent, names no record for
  * `sha`, or the record is `done`. Reads the marker through mergeChanges, so an older-generation
  * single-change marker counts as one `merge` record. */
@@ -44,28 +43,67 @@ export function revisionNote(entry) {
         note += " · " + plural(reasons.length, "prior objection");
     return note;
 }
+/** One re-queued entry's what-brought-it-back note:
+ * `re-queued after <result>`, plus ` · eligible in <duration>` while a `review_error` 60 s
+ * deferral still holds (its `notBefore` in the future). "" for a fresh entry with no `retry`
+ * field, so a first submission's queue line is byte-identical. */
+export function retryNote(entry, now) {
+    if (entry.retry === undefined)
+        return "";
+    let note = `re-queued after ${entry.retry}`;
+    if (entry.notBefore !== undefined && entry.notBefore > now) {
+        note += ` · eligible in ${humanSeconds(secondsUntil(entry.notBefore, now))}`;
+    }
+    return note;
+}
+/** Narrows a whole-queue view to the entries whose role `keep` accepts, and returns the
+ * `scope` renderMergeQueue takes: the kept roles, each kept entry's 1-based place in the whole
+ * queue, and the whole queue's entry count. `unreadable` stays whole because an unreadable file
+ * has no role to attribute it to. */
+export function scopeMergeQueue(whole, roles, keep) {
+    const positions = [];
+    const entries = whole.entries.filter((e, i) => {
+        const kept = keep(e.role);
+        if (kept)
+            positions.push(i + 1);
+        return kept;
+    });
+    return { view: { ...whole, entries }, scope: { roles, positions, total: whole.entries.length } };
+}
 /** Render the queue as the text `tumwater queue` prints: a `merge queue (<depth>):` header then
- * one 1-based line per readable entry, oldest first, carrying the loop, tick number, short
+ * one 1-based line per readable entry, oldest first, carrying the role, run number, short
  * pinned sha, age, and summary. An empty queue (no entries and nothing skipped) prints
  * `merge queue empty`; a non-zero skip count appends one `(+N unreadable queue file(s) skipped)`
  * line so a torn or foreign file the reader dropped is visible rather than silent. An entry the
  * optional in-flight marker has a live record for carries ` · [<label>]` after its age
- * (queueEntryMergeLabel). */
-export function renderMergeQueue(view, now, inFlight) {
+ * (queueEntryMergeLabel). With the optional `scope` (`queue --role`: `view` holds only the
+ * listed roles' entries, `positions` their 1-based places in the whole queue, `total` the whole
+ * queue's entry count) each line keeps its whole-queue number, the header reads
+ * `merge queue (<kept> of <whole depth>, --role <ids>):`, and a scope that keeps nothing of a
+ * non-empty queue prints `no queued merges for <ids> (merge queue holds <depth>)`. Without
+ * `scope` the output is the whole queue's. */
+export function renderMergeQueue(view, now, inFlight, scope) {
     const depth = view.entries.length + view.unreadable;
+    const wholeDepth = scope ? scope.total + view.unreadable : depth;
+    const ids = scope ? scope.roles.join(",") : "";
     const lines = [];
-    if (depth === 0) {
+    if (wholeDepth === 0) {
         lines.push("merge queue empty");
     }
+    else if (scope && view.entries.length === 0) {
+        lines.push(`no queued merges for ${ids} (merge queue holds ${wholeDepth})`);
+    }
     else {
-        lines.push(`merge queue (${depth}):`);
+        lines.push(scope ? `merge queue (${view.entries.length} of ${wholeDepth}, --role ${ids}):` : `merge queue (${depth}):`);
         view.entries.forEach((e, i) => {
-            const age = humanSeconds(secondsSince(e.enqueuedAt, now));
+            const age = humanAgo(e.enqueuedAt, now);
             const label = queueEntryMergeLabel(e.sha, inFlight, now);
             const tag = label ? ` · [${label}]` : "";
             const note = revisionNote(e);
             const noteTag = note ? ` · ${note}` : "";
-            lines.push(`  ${i + 1}. ${roleLabel(e.role)} run #${e.run} · ${shortSha(e.sha)} · ${age} ago${tag}${noteTag} · ${e.summary}`);
+            const retry = retryNote(e, now);
+            const retryTag = retry ? ` · ${retry}` : "";
+            lines.push(`  ${scope ? scope.positions[i] : i + 1}. ${roleLabel(e.role)} run #${e.run} · ${shortSha(e.sha)} · ${age}${tag}${retryTag}${noteTag} · ${e.summary}`);
         });
     }
     if (view.unreadable > 0) {