tumwater 0.2.0 → 0.4.0

package/dist/src/merge/merge-to-main.js

@@ -1,14 +1,17 @@
-// vocabulary: plain
 import { openQuestions } from "../backlog/backlog.js";
 import { logEventBestEffort, warnEventBestEffort } from "../events/events.js";
 import { changeBaseRev, commitMessage, headOf } from "../git/git.js";
 import { aheadOfMainFiles, treeDiffFiles } from "../git/git-diff.js";
 import { resolvedDiffDiverges } from "./merge-diff.js";
-import { conflictedFileHunks, conflictedFiles, continueRebase, ffMainToOrWhy, hasConflictMarkers, mainCommitsTouching, rebaseOntoMain, rebaseOntoMainLeaveConflicts, } from "./merge-git.js";
+import { conflictedFileHunks, conflictedFiles, continueRebase, ffMainToOrWhy, overwriteBlockedReason, primaryCheckoutBlockers, hasConflictMarkers, mainCommitsTouching, rebaseOntoMain, rebaseOntoMainLeaveConflicts, } from "./merge-git.js";
 import { resolveBacklogInsertConflicts } from "./backlog-conflicts.js";
 import { abortSync } from "../git/worktree.js";
 import { runScopedBuildCheck } from "../build/build-check-scoped.js";
-import { detectBuildCheck, gateCommandOf } from "../build/build-check-detect.js";
+import { detectBuildCheck, gateCommandOf, mergeCommandOf } from "../build/build-check-detect.js";
+import { onlyKnownMainFailures } from "../baseline/main-watch.js";
+import { unverifiedTreeOutcome } from "../build/build-check-events.js";
+import { describeCheck, failureHeadline } from "../build/build-check-report.js";
+import { MERGE_FLAKY_WARNING_PREFIX, quarantineTests } from "../review/known-flakes.js";
 import { noteGreenBaseline, noteInheritedGreen } from "../baseline/main-baseline.js";
 import { isExemptDiff } from "../review/exemptions.js";
 import { falseFixReason } from "../verdict/fix-claim.js";
@@ -24,7 +27,7 @@ import { resolverConfig } from "../config/config-views.js";
  * history linear), verify the rebased tree when it differs from what was reviewed, and
  * fast-forward. On conflict, makes one pi-driven resolution attempt
  * (outside the lock) before giving up. A routine conflict is normal operation, not a warning:
- * success merges as an ordinary `merged` event and failure surfaces via the tick's merge_conflict
+ * success merges as an ordinary `merged` event and failure surfaces via the run's merge_conflict
  * result — no separate log line for the hand-off itself. A merged diff that adds entries under
  * QUESTIONS.md's ## Open also emits one `question_posted` per new heading alongside the `merged`
  * event, so `tumwater logs` shows what the team is asking for (plans/questions-outbox.md).
@@ -80,6 +83,11 @@ async function tryMerge(ctx, wt, summary, verifiedHead) {
         // main moved between commit and merge, which under concurrency is the common case (review
         // runs outside this lock).
         const target = await headOf(wt, "HEAD");
+        const dirty = await primaryCheckoutBlockers(ctx.root, ctx.mainBranch, target);
+        if (dirty !== null) {
+            warnEventBestEffort(ctx.root, ctx.role, `merge blocked: ${overwriteBlockedReason(dirty)}`);
+            return "merge_blocked";
+        }
         if (!(await verifyMerge(ctx, wt, target, verifiedHead)))
             return "merge_blocked";
         const mainBefore = await headOf(ctx.root, ctx.mainBranch);
@@ -98,14 +106,20 @@ async function tryMerge(ctx, wt, summary, verifiedHead) {
         // Best-effort: main has already fast-forwarded, so an unwritable events feed must not turn
         // a completed merge into a rejected one and skip syncRootInstall below — the same
         // no-torn-feed policy as the orchestrator's other post-effect logging.
-        if (commit !== mainBefore)
-            logEventBestEffort(ctx.root, { source: ctx.role, type: "merged", commit, summary });
+        if (commit !== mainBefore) {
+            logEventBestEffort(ctx.root, {
+                source: ctx.role,
+                type: "merged",
+                commit,
+                summary,
+            });
+        }
         logNewQuestions(ctx.root, before, ctx.role);
         // Still under the lock: a merge that moved main's lockfile re-syncs the root install
         // every worktree resolves through before the next merge's check runs (BUGS.md 2026-10-01).
         await syncRootInstall(ctx.root, ctx.role);
         return "changed";
-    });
+    }, ctx.lockTimeoutMs);
 }
 /** The backlog-structure cross-check both verifyMerge paths run (exempt and code diffs
  * alike): when the tree ahead of main duplicates or drops a `## ` section heading, warn on the
@@ -146,12 +160,16 @@ export async function exemptSkipBlockReason(ctx, wt, files) {
  * - a no-op rebase whose exact tree the gate verified (`rebasedHead === verifiedHead`): main
  *   did not move under us, so the merge tree is byte-identical to what the gate's pre-check
  *   already ran green. Seed the red-main baseline with the SHA that becomes main: every role's
- *   next fresh tick then hits the cache instead of re-running the full suite on an
+ *   next fresh run then hits the cache instead of re-running the full suite on an
  *   already-verified tree. A no-op rebase the gate did NOT verify — its pre-check was skipped
  *   (a timeout, a killed run) — falls through and runs the merge-scope check, which fails
  *   closed on the same timeout; an exempt diff or a project with no declared check falls
- *   through to its own arm below. Not taken when a `check.gateCommand` is configured: the gate
- *   then ran only that, not the full check.
+ *   through to its own arm below. Taken (Fast merge "Defaults") whenever a `check.mergeCommand`
+ *   resolves — to its own value or, when absent, to `check.gateCommand`. In the fallback case
+ *   (no separate `mergeCommand`) the in-lock command IS the gate command the gate already ran
+ *   green on the rebased head, so the in-lock run would add nothing; with a separate
+ *   `check.mergeCommand` the gate's green was the gate command, not the merge one. Either way
+ *   it skips and seeds nothing (the main watch decides main's verdict).
  * - doc-only delta ahead of main (the gate's own exemption test): cannot break the build.
  * - a code change whose rebased tree differs from the gate-verified one only in exempt paths
  *   (onlyExemptDriftFromVerified): main moved under the review by doc commits alone, so the
@@ -168,10 +186,15 @@ async function verifyMerge(ctx, wt, rebasedHead, verifiedHead) {
     // re-review sets verifiedHead to the resolved head, and that second rebase is then a no-op).
     // A no-op rebase the gate never verified — its pre-check timed out or was killed and left
     // GateResult.verifiedHead undefined — falls through and runs the merge-scope check, which
-    // fails closed on the same timeout. With a check.gateCommand configured the gate ran only
-    // that cheaper check, so even a verified no-op rebase must run the full check here: the
-    // merge scope is what verifies a single change (and each change of an abandoned stack),
-    // and a gateCommand green must never seed the baseline.
+    // fails closed on the same timeout. With a check.gateCommand or check.mergeCommand
+    // configured (Fast merge "Defaults": the lock runs the gate command when mergeCommand is
+    // absent): in the fallback case (no separate `mergeCommand`) the in-lock command IS the gate
+    // command the gate already ran green on the rebased head, so the verified no-op rebase adds
+    // nothing — skip it; with a separate `mergeCommand` the gate's green was the gate command.
+    // Either way it seeds nothing — a cheaper command's green never seeds the baseline: main's
+    // verdicts come from the main watch's full check on the tip.
+    if (rebasedHead === verifiedHead && mergeCommandOf(ctx.config) !== undefined)
+        return true;
     if (rebasedHead === verifiedHead && gateCommandOf(ctx.config) === undefined) {
         noteGreenBaseline(rebasedHead);
         return true;
@@ -204,19 +227,40 @@ async function verifyMerge(ctx, wt, rebasedHead, verifiedHead) {
     // runScopedBuildCheck, shared with the review gate's pre-check. The merge cell names the
     // check (or its wait for a permit) while it runs, then the merge again for the ff.
     setMergeStage(ctx.root, ctx.role, "build-check");
-    const check = await runScopedBuildCheck(ctx.root, ctx.role, "merge", wt, ctx.config, undefined, undefined, undefined, checkWaitStage(ctx.root, [ctx.role]));
+    const runMergeCheck = () => runScopedBuildCheck(ctx.root, ctx.role, "merge", wt, ctx.config, undefined, undefined, undefined, checkWaitStage(ctx.root, [ctx.role]));
+    let check = await runMergeCheck();
+    if (check?.outcome.status === "failed" && !unverifiedTreeOutcome(check.outcome) && !onlyKnownMainFailures(ctx.root, check.outcome.failingTests)) {
+        // One immediate re-run of the same tree: a pass makes the failed run a flake. The change
+        // merges and each test the failed run named is quarantined.
+        const failed = check.outcome;
+        const retry = await runMergeCheck();
+        if (retry?.outcome.status === "passed") {
+            warnEventBestEffort(ctx.root, ctx.role, `${MERGE_FLAKY_WARNING_PREFIX}${failureHeadline(failed.outputTail) ?? describeCheck(check.check)}`);
+            quarantineTests(ctx.root, failed.failingTests, failed.outputTail);
+            check = retry;
+        }
+    }
     setMergeStage(ctx.root, ctx.role, "merging");
     if (!check)
         return true; // No declared check: nothing to run, exactly like the gate skipping its pre-check.
     if (check.outcome.status === "failed") {
+        // Failing only what main already fails is not a red change: the fast-forward goes ahead, with
+        // no strike and no green seeded for a tree that did not pass.
+        const known = unverifiedTreeOutcome(check.outcome) ? null : onlyKnownMainFailures(ctx.root, check.outcome.failingTests);
+        if (known) {
+            warnEventBestEffort(ctx.root, ctx.role, `merge check fails only main's known failures: ${known.join(", ")}`);
+            return true;
+        }
         ctx.onMergeCheckRed?.(check.check, check.outcome);
         return false;
     }
     if (check.outcome.status === "skipped")
         return true; // No npm / broken toolchain — the helper already warned.
-    // Green on exactly the tree that becomes main: seed it so the next tick's red-main baseline
+    // Green on exactly the tree that becomes main: seed it so the next run's red-main baseline
     // check is a cache hit instead of one redundant full-suite run.
-    noteGreenBaseline(rebasedHead);
+    // A mergeCommand green is not the full check's: main's verdict comes from the main watch.
+    if (mergeCommandOf(ctx.config) === undefined)
+        noteGreenBaseline(rebasedHead);
     return true;
 }
 /** True, after seeding the red-main baseline, when the tree about to merge differs from the tree
@@ -229,14 +273,20 @@ async function verifyMerge(ctx, wt, rebasedHead, verifiedHead) {
  * that only rewrote SHAs) is the verified bytes themselves and seeds an observed green. Any
  * other drift seeds an inherited one, which attribution re-checks before trusting
  * (main-baseline.ts's observedOnly). Not taken without a verified head (the pre-check was skipped
- * or never ran) or with a `check.gateCommand`, for the same reasons the no-op skip above is not.
+ * or never ran). With an in-lock command configured (a gate or merge command — Fast merge
+ * "Defaults": the lock runs the gate command when mergeCommand is absent) the drift merges
+ * without a seed: the main watch decides main's verdict.
  * A git failure means "not proven" and the check runs. */
 async function onlyExemptDriftFromVerified(ctx, wt, rebasedHead, verifiedHead) {
-    if (verifiedHead === undefined || gateCommandOf(ctx.config) !== undefined)
+    if (verifiedHead === undefined)
+        return false;
+    if (gateCommandOf(ctx.config) !== undefined && mergeCommandOf(ctx.config) === undefined)
         return false;
     const drift = await treeDiffFiles(wt, verifiedHead, rebasedHead);
     if (drift === null || !isExemptDiff(drift, ctx.exemptPaths))
         return false;
+    if (mergeCommandOf(ctx.config) !== undefined)
+        return true; // no seed: the watch decides main's verdict
     if (drift.length === 0)
         noteGreenBaseline(rebasedHead);
     else
@@ -269,12 +319,13 @@ async function resolveConflict(ctx, wt, preMergeHead) {
     const files = await conflictedFiles(wt);
     // Deterministic first pass (plans/parallel-work-instances.md, part 3/7): insert-only
     // conflicts in the backlog markdown — two merges pasting different entries as the first
-    // under ## Done — carry no authored bytes, so they are settled without a model run. Only the
-    // files it could not resolve (code, or a same-entry edit) reach the resolver below.
+    // under ## Done, or new entries above an entry the other side deleted — carry no authored
+    // bytes, so they are settled without a model run. Only the files it could not resolve (code,
+    // or a same-entry edit) reach the resolver below.
     const remaining = await resolveBacklogInsertConflicts(wt, files);
     if (remaining.length === 0) {
         // A second stop is only possible when the branch holds more than the one insert-only
-        // commit. One attempt per tick.
+        // commit. One attempt per run.
         return continueOrAbortRebase(wt);
     }
     // The prompt names the project's own check, detected the way the in-lock re-check detects it,
@@ -299,10 +350,10 @@ async function resolveConflict(ctx, wt, preMergeHead) {
             change,
             main: commits,
             mainOmitted: omitted,
-        }), `tumwater-${ctx.role}-${ctx.tick}-conflict`, 
+        }), `tumwater-${ctx.role}-${ctx.runNumber}-conflict`, 
         // The resolver rides the strong tier (plans/model-tiers.md part 4/8): resolution is rare,
         // tolerant of latency, and edits code inside merge. Its spend still folds into the
-        // authoring role's usage — the fold belongs to the loop's wiring, not to the config.
+        // authoring role's usage — the fold belongs to the runner's wiring, not to the config.
         resolverConfig(ctx.config));
     }
     finally {
@@ -312,7 +363,7 @@ async function resolveConflict(ctx, wt, preMergeHead) {
         await abortSync(wt);
         return false;
     }
-    // A second stop is only possible when pi itself authored extra commits during the tick.
-    // One resolution attempt per tick.
+    // A second stop is only possible when pi itself authored extra commits during the run.
+    // One resolution attempt per run.
     return continueOrAbortRebase(wt);
 }

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

@@ -0,0 +1,83 @@
+/** Operator reordering of a waiting merge (PLANS.md `tumwater queue --top <n>`): moving the
+ * Nth queued merge to the head of the execution order. Split out of merge-queue.ts so the
+ * queue stays the pure reader/writer it is: this module owns the reorder half of an
+ * unattempted entry, renaming its queue file to a stamp one below the queue's minimum — the
+ * merge-queue twin of inbox-top.ts (which does the same for the prompt queue). It mirrors
+ * inbox-top.ts's rename-and-event pairing and merge-cancel.ts's stance: no lock, one file per
+ * entry, tolerant of a concurrent drop. */
+import path from "node:path";
+import fs from "node:fs";
+import { logEventBestEffort } from "../events/events.js";
+import { errCode } from "../errno.js";
+import { queueFileStamp, lowestStampName } from "../files/file-queue.js";
+import { queuedMergeFiles } from "./merge-queue.js";
+/** Move the Nth queued merge — 1-based, as `tumwater queue` numbers it and `--cancel`
+ * resolves it — to the head of the execution order, so it is the next due entry the queue
+ * takes when ready. Position 1 reports `already-first` and changes nothing; an out-of-range
+ * position (below 1 or past the readable depth) reports `out-of-range` with the current
+ * depth and changes nothing. The Nth entry is resolved against `queuedMergeFiles` and the
+ * same `topQueuedFile` the by-sha twin shares, so the CLI and the surfaces cannot drift on
+ * what topping means. */
+export function moveQueuedMergeToTop(root, position) {
+    const files = queuedMergeFiles(root);
+    if (position < 1 || position > files.length)
+        return { status: "out-of-range", depth: files.length };
+    return topQueuedFile(root, files, position - 1);
+}
+/** Move the post-position body of a top move to the head of the execution order: the same
+ * rename-and-event work both the position and by-sha variants share. `index` is a 0-based
+ * index into `files`. Position 1 (index 0) reports `already-first` and changes nothing. The
+ * move is one rename: the entry JSON is never rewritten, so every field (`enqueuedAt`,
+ * `notBefore`, `retry`, `revisionRound`, `priorReview`) is unchanged; giving the file a
+ * stamp one below the queue's readable minimum sorts it first (falling back to `Date.now()`
+ * when no stamp parses), stepping one lower while the destination exists (a concurrent
+ * writer may have just taken the name we computed). One `merge_topped` event is logged under
+ * the entry's role. The rename is guarded: if the target vanished between the list and the
+ * rename (a concurrent drain took the change), the move answers `gone` and changes nothing
+ * rather than throwing. No lock and no pin write: the module mirrors merge-cancel.ts's "one
+ * file per entry, tolerant of a concurrent drop" stance. */
+function topQueuedFile(root, files, index) {
+    const target = files[index];
+    if (index === 0) {
+        return {
+            status: "already-first",
+            role: target.entry.role,
+            sha: target.entry.sha,
+            summary: target.entry.summary,
+        };
+    }
+    const stamps = files
+        .map((q) => queueFileStamp(path.basename(q.file)))
+        .filter((s) => s !== null);
+    const dir = path.dirname(target.file);
+    const newFile = lowestStampName(stamps, dir, ".json");
+    try {
+        fs.renameSync(target.file, newFile);
+    }
+    catch (err) {
+        // The queue drained the target between our list and this rename (an orchestrator took
+        // the change): a concurrent drop is a normal race, never an error — the entry has
+        // already left the queue, so there is nothing to top. Any other rename failure is real.
+        if (errCode(err) === "ENOENT")
+            return { status: "gone" };
+        throw err;
+    }
+    logEventBestEffort(root, {
+        source: target.entry.role,
+        type: "merge_topped",
+        commit: target.entry.sha,
+        summary: target.entry.summary,
+    });
+    return { status: "topped", role: target.entry.role, sha: target.entry.sha, summary: target.entry.summary };
+}
+/** Move the queued merge whose entry's pinned sha is `sha` to the head of the queue (the
+ * browser twin of `tumwater queue --top <n>`, resolving by sha because the dashboard rows
+ * carry one). An entry whose sha matches none is `{ status: "gone" }` and changes nothing;
+ * otherwise it runs the same `topQueuedFile` the position variant uses. */
+export function moveQueuedMergeToTopBySha(root, sha) {
+    const files = queuedMergeFiles(root);
+    const i = files.findIndex((q) => q.entry.sha.toLowerCase() === sha.toLowerCase());
+    if (i < 0)
+        return { status: "gone" };
+    return topQueuedFile(root, files, i);
+}

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

@@ -1,14 +1,16 @@
-// vocabulary: plain
 import fs from "node:fs";
 import path from "node:path";
 import { gateRoleConfig } from "../gates/budget-gates.js";
 import { reviewRunConfig, seamConcurrencyKey } from "../config/config-views.js";
 import { providerWaitStage } from "./merge-slot.js";
 import { withProviderLease } from "../concurrency/provider-lease.js";
-import { LoopRunner } from "../loop/loop.js";
-import { branchHead, isMergedInto } from "../git/git.js";
+import { RoleRunner } from "../runner/runner.js";
+import { branchHead, commitMessage, isMergedInto, refSha } from "../git/git.js";
+import { commitRunOf } from "../git/commit-message.js";
+import { recoveredMergeEntry, recoveredMetadata } from "../runner/leftover.js";
 import { addMergeChange, mergeUsage, removeMergeChange, setMergeChangeStatus } from "./merge-slot.js";
-import { dropMerge, entryRevisionFields, queuedMergeFiles, staleHeadFile } from "./merge-queue.js";
+import { dropMerge, enqueueMerge, entryRevisionFields, queuedMergeFiles, staleHeadFile, tornHeadRole } from "./merge-queue.js";
+import { mergeRefName } from "../paths.js";
 import { warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
 import { errorMessage } from "../text/text.js";
 import { verifyRequest } from "./merge-batch.js";
@@ -18,6 +20,13 @@ import { abortOnShutdown, acquireUnlessAborted, discardPinnedRefs, guardMergeTas
  * behind them (BUGS.md 2026-09-18). Exported for merge-drain.ts, whose merge tier sits one
  * below it. */
 export const VERIFY_TIER = -1;
+/** The tier the merge's conflict-resolution runs wait at, one below VERIFY_TIER: ahead of any
+ * verification parked for a permit, because the merge is the one serial step every queued change
+ * waits on. (Nothing that holds a permit ever waits on the merge: no verification takes the merge
+ * lock, and the resolver runs outside it — merge-to-main.ts's mergeToMain — so this cannot
+ * deadlock.) Shared by merge-drain.ts's merge slot and merge-post-review.ts's fix landing, so the
+ * reviewer's fix-merge resolver rides the same tier and the two cannot drift. */
+export const MERGE_TIER = VERIFY_TIER - 1;
 /** How many verifications may be in flight (parked or running) at once: every `maxConcurrent`
  * permit but one, so a deep merge queue never takes the last slot from the roles that could
  * author — at least one, so `maxConcurrent` 1 still merges. The merge's short conflict-resolution
@@ -28,28 +37,68 @@ export function verifyLimit(maxConcurrent) {
 /** Resolve a merge entry's authoring runner: the live runner when the role is enabled
  * (runners are never removed from the array on disable — only a warning event fires); a role
  * disabled before this process started has no runner, so a throwaway one supplies the same
- * wiring (loop-pi.ts, runMergePi, foldMergeUsage) and a disk-loaded state to fold and save
+ * wiring (runner-pi.ts, runMergePi, foldMergeUsage) and a disk-loaded state to fold and save
  * on. Both share the live config, like every runner — the director takes directorConfig (the live
  * config, its budget-gate exemption, unless a used-up window moved it), every other role takes
  * roleConfig (gateRoleConfig's single home for the rule; the scheduler assigns the live runners
  * by it every poll). */
-function resolveAuthor(ctx, role) {
+export function resolveAuthor(ctx, role) {
     const { root, mainBranch, signal, runners, liveConfig, roleConfig, directorConfig } = ctx;
     return (runners.find((r) => r.role === role) ??
-        new LoopRunner(root, role, gateRoleConfig(role, liveConfig, roleConfig, directorConfig), mainBranch, signal));
+        new RoleRunner(root, role, gateRoleConfig(role, liveConfig, roleConfig, directorConfig), mainBranch, signal));
 }
 /** Drop a torn queue head. A torn head (torn or foreign — a partial write an older build left,
  * a hand-placed file) makes headMerge read null forever — nothing else drops it, stranding
- * every live entry behind it and pinning their authors' ticks via the interlock. Drop it with
- * one warning; the healthy entries behind it are verified in the same poll. The crashed
- * entry's commit, if any, still rides its merge ref into next-tick leftover recovery
- * (BUGS.md 2026-09-17). */
-function dropTornHead(root) {
+ * every live entry behind it and pinning their authors' runs via the interlock. Drop it with
+ * one warning naming the file (and, when the head's raw bytes still carry a role, that role);
+ * the healthy entries behind it are verified in the same poll. When a role is recovered, that
+ * role's merge pin is read and, if it resolves, the change is re-queued fresh — in the same
+ * shape leftover recovery builds (recoveredMergeEntry: the commit message's real summary,
+ * body, high-friction flag, and revision round, plus the authoring run from its Run trailer) —
+ * before the drop, so the same poll's queuedMergeFiles sees it and no landing waits forever on
+ * the one unreadable file (BUGS.md 2026-09-17). The re-queue is best-effort: a write failure
+ * (ENOSPC/EMFILE) or an unreadable commit must not wedge the queue, so the torn head is still
+ * dropped (the pin survives and leftover recovery re-queues the full shape on the role's next
+ * run), and the drain's poll never aborts. A torn head with no recoverable role or no pin drops
+ * with the warning alone; the crashed entry's commit, if any, still rides its merge ref into
+ * next-run leftover recovery. Exported for test/merge-queue.test.ts's torn-head step. */
+export async function dropTornHead(root) {
     const stale = staleHeadFile(root);
     if (!stale)
         return;
+    const role = tornHeadRole(stale);
+    let requeued = false;
+    let requeueFailed = false;
+    if (role) {
+        const sha = await refSha(root, mergeRefName(role)).catch(() => null);
+        if (sha) {
+            try {
+                // The shape leftover recovery builds. `run` is recovered from the commit's Run trailer
+                // (the drain has no run number of its own) so session naming keeps the authoring run;
+                // a hand-made commit with no trailer falls back to the zero slot.
+                const meta = await recoveredMetadata(root, sha);
+                const message = await commitMessage(root, sha);
+                const run = message === null ? 0 : (commitRunOf(message) ?? 0);
+                enqueueMerge(root, recoveredMergeEntry(role, sha, meta, run));
+                requeued = true;
+            }
+            catch {
+                // A re-queue that cannot be built or written (ENOSPC/EMFILE on the queue write, an
+                // unreadable commit) must not abort the poll or strand the head: drop it anyway and let
+                // the still-held pin feed next-run leftover recovery, which rebuilds the full shape.
+                requeueFailed = true;
+            }
+        }
+    }
     dropMerge(stale);
-    warnEventBestEffort(root, TUMWATER_SOURCE, `merge queue head ${path.basename(stale)} is unreadable (torn or foreign) — dropped so the queue keeps moving`);
+    const roleNote = !role
+        ? ""
+        : requeued
+            ? `; ${role}'s pinned change was re-queued`
+            : requeueFailed
+                ? `; ${role}'s pinned change could not be re-queued — left for leftover recovery`
+                : `; ${role}'s pin is unreadable — left for leftover recovery`;
+    warnEventBestEffort(root, TUMWATER_SOURCE, `merge queue head ${path.basename(stale)} is unreadable (torn or foreign) — dropped so the queue keeps moving${roleNote}`);
 }
 /** Already-merged verdicts cached per (root, sha) against the main head they were computed
  * against. drainVerify re-runs its dedupe against main every poll, but a queued entry's sha is
@@ -88,7 +137,7 @@ async function mergedIntoMain(root, sha, mainBranch, head) {
  * run, with its marker record; a crash mid-verification leaves both entry and ref, so the entry is
  * verified again — the established crash semantics. */
 export async function drainVerify(ctx, p) {
-    dropTornHead(ctx.root);
+    await dropTornHead(ctx.root);
     const queue = queuedMergeFiles(ctx.root);
     // One main-head read per poll with a non-empty queue (branchHead's ref-file fast path — no
     // spawn), serving every entry's cached dedupe verdict below.
@@ -98,6 +147,9 @@ export async function drainVerify(ctx, p) {
             return;
         if (liveRoles(p).has(entry.role))
             continue;
+        // A re-queued review_error waits out its delay; the entry stays queued and holds its author.
+        if (entry.notBefore !== undefined && Date.now() < entry.notBefore)
+            continue;
         if (await mergedIntoMain(ctx.root, entry.sha, ctx.mainBranch, mainHead)) {
             dropMerge(file);
             removeMergeChange(ctx.root, entry.role);
@@ -107,6 +159,11 @@ export async function drainVerify(ctx, p) {
         // (its role was busy when the queue was listed) or claimed its role. Start nothing for it.
         if (!fs.existsSync(file) || liveRoles(p).has(entry.role))
             continue;
+        // A pre-merge entry during a reviewer hold stays queued instead of starting a parked verify
+        // that fills the verify limit; a review.afterMerge role's entry keeps draining (its review
+        // runs after merging, so the hold is not for it) — ctx's role-scoped start gate decides.
+        if (ctx.startHeld(entry.role))
+            continue;
         startVerify(ctx, p, entry, file);
     }
 }
@@ -150,7 +207,7 @@ export function startVerify(ctx, p, entry, file) {
             verify.parked = false;
             if (lease === null)
                 return; // a shutdown while parked
-            if (verify.controller.signal.aborted || ctx.startHeld()) {
+            if (verify.controller.signal.aborted || ctx.startHeld(role)) {
                 lease.release(); // stopping, or a restart / team hold closed the gate while it waited
                 return;
             }
@@ -163,10 +220,10 @@ export function startVerify(ctx, p, entry, file) {
                 // so a review run that lands on a different provider than the verification's review seam
                 // re-keys it there, and a re-key park is shown by providerWaitStage; its slot wait drops
                 // the key (pool-slot rule).
-                verdict = await withProviderLease(lease, semaphore, () => verifyRequest({ root, mainBranch, config: author.config, signal: () => verify.controller.signal, runGatePi: (opts) => author.runGatePi(opts) }, {
+                verdict = await withProviderLease(lease, semaphore, () => verifyRequest({ root, mainBranch, config: author.config, signal: () => verify.controller.signal, runGatePi: (opts) => author.runGatePi(opts), reviewHeld: () => ctx.startHeld() }, {
                     role,
                     sha: entry.sha,
-                    tick: entry.run,
+                    runNumber: entry.run,
                     summary: entry.summary,
                     body: entry.body,
                     highFriction: entry.highFriction,
@@ -198,7 +255,7 @@ export function startVerify(ctx, p, entry, file) {
             }
             else {
                 const result = verdict.kind === "stack" ? "aborted" : verdict.result;
-                await settleMergeOutcome(root, entry, author.state, result, Date.now() - startedAt, usage, file);
+                await settleMergeOutcome(root, entry, author.state, result, Date.now() - startedAt, usage, file, mainBranch);
                 if (verify.userAborted)
                     await discardPinnedRefs(root, [role]);
             }

package/dist/src/notes-cli.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-// vocabulary: plain
 /** The `tumwater-notes` command — the second bin entry (dist/src/notes-cli.js), the one
  * carrier for writing a role's note on every backend (plans/notes-command.md "The
  * `tumwater-notes` command"). A run finds it on its PATH (src/agent/notes-shim.ts) and hands
@@ -14,9 +13,12 @@
  *   show             print the note (nothing when there is none)
  *   clear            empty the note
  *
- * Exits 0 on success, 1 on a refusal (empty input, over-cap note, or no
- * TUMWATER_NOTES_PATH), and 2 with usage for anything else. */
+ * Exits 0 on success, 1 on a refusal (empty input, over-cap note, a note file that cannot be
+ * written or read, or no TUMWATER_NOTES_PATH), and 2 with usage for an unknown subcommand (a
+ * known subcommand with bad arguments refuses with usage and exit 1). */
 import fs from "node:fs";
+import { readTextIfExists } from "./files/files.js";
+import { errorMessage, stripTerminalControls } from "./text/text.js";
 import { validateRoleNote, writeRoleNote } from "./agent/role-notes-write.js";
 /** The note's path, read ONLY from the environment — never from an argument. */
 const NOTES_PATH = process.env.TUMWATER_NOTES_PATH;
@@ -29,14 +31,10 @@ const USAGE = [
 function readStdin() {
     return fs.readFileSync(0, "utf8");
 }
-/** Read the note's current text; a missing note reads as empty (show prints nothing). */
+/** Read the note's current text; a missing note reads as empty (show prints nothing). Any
+ * other read failure (EACCES, EISDIR) throws, so it is never mistaken for an empty note. */
 function readNote() {
-    try {
-        return fs.readFileSync(NOTES_PATH, "utf8");
-    }
-    catch {
-        return "";
-    }
+    return readTextIfExists(NOTES_PATH) ?? "";
 }
 /** Refuse with `message` on stderr and exit 1 — the exit code for every expected refusal. */
 function refuse(message) {
@@ -51,7 +49,12 @@ function writeNote(text) {
     const error = validateRoleNote(text);
     if (error)
         return refuse(error);
-    writeRoleNote(NOTES_PATH, text);
+    try {
+        writeRoleNote(NOTES_PATH, text);
+    }
+    catch (err) {
+        return refuse(`could not save the note: ${errorMessage(err)}`);
+    }
     process.stdout.write(`notes saved (${Buffer.byteLength(text, "utf8")} bytes)\n`);
     return 0;
 }
@@ -72,8 +75,8 @@ function main() {
                 try {
                     text = fs.readFileSync(flagArg, "utf8");
                 }
-                catch {
-                    return refuse(`cannot read ${flagArg}`);
+                catch (err) {
+                    return refuse(`cannot read ${JSON.stringify(flagArg)}: ${errorMessage(err)}`);
                 }
                 return writeNote(text);
             }
@@ -81,12 +84,29 @@ function main() {
         case "show":
             if (flag !== undefined)
                 return refuse(USAGE);
-            process.stdout.write(readNote());
+            let note;
+            try {
+                note = readNote();
+            }
+            catch (err) {
+                return refuse(`could not read the note: ${errorMessage(err)}`);
+            }
+            // The note is model-authored text, so strip terminal controls at this display
+            // boundary — the same treatment say()/fail()/the TUI frame give every untrusted
+            // string, so a prompt-injected note with an ANSI escape (cursor move, title set,
+            // OSC 52 clipboard write, carriage-return overwrite) cannot drive the operator's
+            // terminal when they run `tumwater-notes show`.
+            process.stdout.write(stripTerminalControls(note));
             return 0;
         case "clear":
             if (flag !== undefined)
                 return refuse(USAGE);
-            writeRoleNote(NOTES_PATH, "");
+            try {
+                writeRoleNote(NOTES_PATH, "");
+            }
+            catch (err) {
+                return refuse(`could not clear the note: ${errorMessage(err)}`);
+            }
             process.stdout.write("notes cleared\n");
             return 0;
         default: