tumwater 0.1.2 → 0.2.0

package/dist/src/{landing/landing-merge.js → merge/merge-to-main.js}

@@ -1,9 +1,10 @@
+// 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 "./landing-diff.js";
-import { conflictedFiles, continueRebase, ffMainTo, hasConflictMarkers, mainCommitsTouching, rebaseOntoMain, rebaseOntoMainLeaveConflicts, } from "./landing-git.js";
+import { resolvedDiffDiverges } from "./merge-diff.js";
+import { conflictedFileHunks, conflictedFiles, continueRebase, ffMainToOrWhy, 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";
@@ -15,25 +16,25 @@ import { backlogStructureReason } from "../backlog/backlog-structure.js";
 import { withLock } from "../concurrency/lock.js";
 import { buildConflictPrompt } from "../prompt/gate-prompts.js";
 import { mergeLockDir } from "../paths.js";
-import { logNewQuestions } from "./landing-questions.js";
-import { checkWaitStage, setLandingStage } from "./landing-slot.js";
+import { logNewQuestions } from "./merge-questions.js";
+import { checkWaitStage, setMergeStage } from "./merge-slot.js";
 import { syncRootInstall } from "../build/dep-install.js";
 import { resolverConfig } from "../config/config-views.js";
-/** Land the worktree branch on main under the shared merge lock: rebase it onto main (keeping
+/** Merge the worktree branch on main under the shared merge lock: rebase it onto main (keeping
  * 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 lands 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 tick'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 fleet is asking for (plans/questions-outbox.md).
+ * event, so `tumwater logs` shows what the team is asking for (plans/questions-outbox.md).
  * `verifiedHead` is the head the review gate's pre-check just ran green on
  * (GateResult.verifiedHead) — when the rebase turns out to be a no-op it names the exact tree
- * about to land, so the in-lock re-check can both skip and seed the baseline from it; pass
+ * about to merge, so the in-lock re-check can both skip and seed the baseline from it; pass
  * undefined when no fresh green observation was made (exempt diff, review disabled,
  * already-approved early return). */
 export async function mergeToMain(ctx, wt, summary, verifiedHead) {
-    // The branch tip before ANY rebase of this landing. Captured once here — not per tryMerge —
+    // The branch tip before ANY rebase of this merge. Captured once here — not per tryMerge —
     // because the conflict-retry path rebases twice: after pi resolves, the second attempt's
     // rebase is a no-op even though its tree (the resolution) was never checked.
     const preMergeHead = await headOf(wt, "HEAD");
@@ -46,8 +47,8 @@ export async function mergeToMain(ctx, wt, summary, verifiedHead) {
     // removes lines the reviewed change never removed, has left the reviewer's scope: those bytes
     // were never judged, and the in-lock build check cannot judge intent (BUGS.md 2026-10-01: a
     // resolver restored 158 lines main had deliberately reverted). Re-run the gate over the
-    // resolved tree before anything lands; a resolution that stays inside the reviewed change's
-    // lines — including one that drops branch edits main superseded — re-lands with no extra run.
+    // resolved tree before anything merges; a resolution that stays inside the reviewed change's
+    // lines — including one that drops branch edits main superseded — re-merges with no extra run.
     if (ctx.recheckResolved && (await resolvedDiffDiverges(ctx, wt, preMergeHead))) {
         const recheck = await ctx.recheckResolved(wt);
         if (recheck.verdict === "rejected")
@@ -59,66 +60,69 @@ export async function mergeToMain(ctx, wt, summary, verifiedHead) {
     return tryMerge(ctx, wt, summary, verifiedHead);
 }
 /** Emit one `question_posted` event per entry QUESTIONS.md's ## Open gained since `before`,
- * recorded by landing-questions.ts's logNewQuestions alongside this module's `merged` event. */
+ * recorded by merge-questions.ts's logNewQuestions alongside this module's `merged` event. */
 async function tryMerge(ctx, wt, summary, verifiedHead) {
     return withLock(mergeLockDir(ctx.root), async () => {
         // Capture the Open questions before the rebase so a merged diff that posts new ones can
-        // emit one question_posted per entry. The lock keeps no other merge landing between capture
+        // emit one question_posted per entry. The lock keeps no other merge between capture
         // and compare, so the diff is exact; on the conflict path only the second tryMerge call ever
         // reaches the post-ff code, so nothing double-emits.
         const before = openQuestions(ctx.root);
         if (!(await rebaseOntoMain(wt, ctx.mainBranch)))
             return "merge_conflict";
         // The gate's pre-check ran OUTSIDE this lock against the head as it stood then; a rebase
-        // that rewrote anything means the tree about to land is new bytes (BUGS.md 2026-09-08).
+        // that rewrote anything means the tree about to merge is new bytes (BUGS.md 2026-09-08).
         // Re-verify exactly what will become main before fast-forwarding.
         // The worktree's POST-REBASE HEAD: fetched once and used for both the re-check and the
         // fast-forward. A branch ref tracks its own tip through the rebase (so this is
         // behavior-preserving for role branches), but a pinned bare sha does not move when git
         // rebase rewrites it — ff'ing main to the original pin would fail as merge_blocked whenever
-        // main moved between commit and landing, which under concurrency is the common case (review
+        // main moved between commit and merge, which under concurrency is the common case (review
         // runs outside this lock).
         const target = await headOf(wt, "HEAD");
-        if (!(await verifyLanding(ctx, wt, target, verifiedHead)))
+        if (!(await verifyMerge(ctx, wt, target, verifiedHead)))
             return "merge_blocked";
         const mainBefore = await headOf(ctx.root, ctx.mainBranch);
-        if (!(await ffMainTo(ctx.root, target, ctx.mainBranch)))
+        const ffFailure = await ffMainToOrWhy(ctx.root, target, ctx.mainBranch);
+        if (ffFailure !== null) {
+            warnEventBestEffort(ctx.root, ctx.role, `merge blocked: ${ffFailure}`);
             return "merge_blocked";
+        }
         const commit = await headOf(ctx.root, ctx.mainBranch);
         // A fast-forward to a commit main already contains is a no-op ("Already up to date"): the
-        // change is already an ancestor of main (a leftover-recovery re-land of an entry main
+        // change is already an ancestor of main (a leftover-recovery re-merge of an entry main
         // holds), so main's head is some later commit that did not produce this summary. Logging a
-        // `merged` event there would count the already-counted landing a second time and pair the
+        // `merged` event there would count the already-counted merge a second time and pair the
         // change's summary with the wrong commit (BUGS.md 2026-10-10). Only a fast-forward that
-        // moved main records a landing.
+        // moved main records a merge.
         // Best-effort: main has already fast-forwarded, so an unwritable events feed must not turn
-        // a completed landing into a rejected one and skip syncRootInstall below — the same
+        // 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, { loop: ctx.role, type: "merged", commit, summary });
+            logEventBestEffort(ctx.root, { source: ctx.role, type: "merged", commit, summary });
         logNewQuestions(ctx.root, before, ctx.role);
-        // Still under the lock: a landing that moved main's lockfile re-syncs the root install
-        // every worktree resolves through before the next landing's check runs (BUGS.md 2026-10-01).
+        // 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";
     });
 }
-/** The backlog-structure cross-check both verifyLanding paths run (exempt and code diffs
+/** 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
- * role's feed with the one "landing blocked:" phrasing and return the reason (null when the
+ * role's feed with the one "merge blocked:" phrasing and return the reason (null when the
  * headings are intact). Shared so the wording and the block action cannot drift between the
  * paths. */
 async function structureBlocked(ctx, wt, files) {
     const structure = await backlogStructureReason(wt, ctx.mainBranch, files);
     if (!structure)
         return null;
-    warnEventBestEffort(ctx.root, ctx.role, `landing blocked: ${structure}`);
+    warnEventBestEffort(ctx.root, ctx.role, `merge blocked: ${structure}`);
     return structure;
 }
 /** The exempt arm's full cross-check — backlog structure, then fix-claim — shared by
- * verifyLanding and landing-batch.ts's stack skip: an md-only tree delta that skips the build
+ * verifyMerge and merge-batch.ts's stack skip: an md-only tree delta that skips the build
  * check must not wave through an edit the gate would have rejected. Returns the first blocking
- * reason (a structure reason already warned as "landing blocked: ..."), or null when the skip
+ * reason (a structure reason already warned as "merge blocked: ..."), or null when the skip
  * may proceed. */
 export async function exemptSkipBlockReason(ctx, wt, files) {
     const structure = await structureBlocked(ctx, wt, files);
@@ -130,43 +134,43 @@ export async function exemptSkipBlockReason(ctx, wt, files) {
     // caller may warn twice for one change (here, then again when the fallback's exempt arm
     // blocks it) — a duplicated line is harmless next to a silent block.
     if (fix)
-        warnEventBestEffort(ctx.root, ctx.role, `landing blocked: ${fix}`);
+        warnEventBestEffort(ctx.root, ctx.role, `merge blocked: ${fix}`);
     return fix ?? null;
 }
-/** Verify the exact tree about to land on main — the post-rebase head (BUGS.md 2026-09-08: the
+/** Verify the exact tree about to reach main — the post-rebase head (BUGS.md 2026-09-08: the
  * gate's pre-check ran outside this lock against a head the rebase may have rewritten, so the
  * bytes that become main were never run through a check). Returns false when the tree is
  * structurally unsound (backlogStructureReason: a duplicated or dropped `## ` section heading,
  * with a warning event so a broken conflict resolution shows on the dashboards) or when the
- * project's declared check FAILS on the rebased tree; every other outcome lands. Skips:
+ * project's declared check FAILS on the rebased tree; every other outcome merges. Skips:
  * - a no-op rebase whose exact tree the gate verified (`rebasedHead === verifiedHead`): main
- *   did not move under us, so the landing tree is byte-identical to what the gate's pre-check
+ *   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
  *   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 landing-scope check, which fails
+ *   (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.
  * - 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
- *   bytes about to land are the verified ones plus a delta that same rule exempts.
+ *   bytes about to merge are the verified ones plus a delta that same rule exempts.
  * - no declared check at all: nothing to run, exactly like the gate skipping its pre-check.
  * An environmental skip (no npm / broken toolchain) warns and proceeds — deliberately NOT
  * fail-closed, so a broken toolchain that would fail every check regardless of the tree
- * (BUGS.md 2026-09-15) cannot wedge every landing behind the merge lock. A TIMEOUT is not
+ * (BUGS.md 2026-09-15) cannot wedge every merge behind the merge lock. A TIMEOUT is not
  * environmental here: the tree is unverified, so runScopedBuildCheck remaps it to a failed
- * check and the landing rejects (BUGS.md: an unverified landing must not reach main). */
-async function verifyLanding(ctx, wt, rebasedHead, verifiedHead) {
+ * check and the merge rejects (BUGS.md: an unverified merge must not reach main). */
+async function verifyMerge(ctx, wt, rebasedHead, verifiedHead) {
     // Trust only the tree the gate actually verified. The identity means the in-lock rebase was
     // a no-op on exactly the head the pre-check ran green on (a real conflict resolution's
     // 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 landing-scope check, which
+    // 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
-    // landing scope is what verifies a single change (and each change of an abandoned stack),
+    // merge scope is what verifies a single change (and each change of an abandoned stack),
     // and a gateCommand green must never seed the baseline.
     if (rebasedHead === verifiedHead && gateCommandOf(ctx.config) === undefined) {
         noteGreenBaseline(rebasedHead);
@@ -178,34 +182,34 @@ async function verifyLanding(ctx, wt, rebasedHead, verifiedHead) {
         // must not wave through an md-only edit the gate would have rejected — and this is the
         // site that catches what the gate cannot see: a conflict resolution happens AFTER the
         // gate, inside this lock, so a resolution that kept both sides of a `## Done` conflict and
-        // duplicated the heading lands here or not at all (PLANS.md 2026-09-25, 9eaae5ac).
+        // duplicated the heading merges here or not at all (PLANS.md 2026-09-25, 9eaae5ac).
         const reason = await exemptSkipBlockReason(ctx, wt, files);
         if (reason !== null) {
-            ctx.onLandingBlocked?.(reason);
+            ctx.onMergeBlocked?.(reason);
             return false;
         }
         return true;
     }
     // The heading check for code diffs too, before the build check: a conflict resolution that
     // broke backlog structure reads as an explained block on the dashboards, not as an
-    // unexplained red check run on a tree that could never land.
+    // unexplained red check run on a tree that could never merge.
     const structure = await structureBlocked(ctx, wt, files);
     if (structure) {
-        ctx.onLandingBlocked?.(structure);
+        ctx.onMergeBlocked?.(structure);
         return false;
     }
     if (await onlyExemptDriftFromVerified(ctx, wt, rebasedHead, verifiedHead))
         return true;
     // The run itself (build_check event, environmental-skip warning) lives in
-    // runScopedBuildCheck, shared with the review gate's pre-check. The landing cell names the
+    // 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.
-    setLandingStage(ctx.root, ctx.role, "build-check");
-    const check = await runScopedBuildCheck(ctx.root, ctx.role, "landing", wt, ctx.config, undefined, undefined, undefined, checkWaitStage(ctx.root, [ctx.role]));
-    setLandingStage(ctx.root, ctx.role, "merging");
+    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]));
+    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") {
-        ctx.onLandingCheckRed?.(check.check, check.outcome);
+        ctx.onMergeCheckRed?.(check.check, check.outcome);
         return false;
     }
     if (check.outcome.status === "skipped")
@@ -215,12 +219,12 @@ async function verifyLanding(ctx, wt, rebasedHead, verifiedHead) {
     noteGreenBaseline(rebasedHead);
     return true;
 }
-/** True, after seeding the red-main baseline, when the tree about to land differs from the tree the
- * gate's pre-check ran green on (`verifiedHead`) only in review-exempt paths. That is the usual
+/** True, after seeding the red-main baseline, when the tree about to merge differs from the tree
+ * the gate's pre-check ran green on (`verifiedHead`) only in review-exempt paths. That is the usual
  * shape of "main moved under the review" here: 43% of main's commits are doc-only (plan, readme
- * and qa land them all day), and 165 of 750 in-lock checks over 2026-10-02..12 re-ran the full
+ * and qa merge them all day), and 165 of 750 in-lock checks over 2026-10-02..12 re-ran the full
  * suite, holding the merge lock, for a tree that differed from its verified one by markdown
- * alone. The exempt-diff rule above already lets such a delta land with no check at all, so the
+ * alone. The exempt-diff rule above already lets such a delta merge with no check at all, so the
  * same rule covers drift on top of a verified tree. An identical tree (empty drift, a rebase
  * 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
@@ -264,7 +268,7 @@ async function resolveConflict(ctx, wt, preMergeHead) {
         return false;
     const files = await conflictedFiles(wt);
     // Deterministic first pass (plans/parallel-work-instances.md, part 3/7): insert-only
-    // conflicts in the backlog markdown — two landings pasting different entries as the first
+    // 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.
     const remaining = await resolveBacklogInsertConflicts(wt, files);
@@ -274,7 +278,7 @@ async function resolveConflict(ctx, wt, preMergeHead) {
         return continueOrAbortRebase(wt);
     }
     // The prompt names the project's own check, detected the way the in-lock re-check detects it,
-    // as the one verifyLanding runs on the resolution — so the resolver neither guesses a runner
+    // as the one verifyMerge runs on the resolution — so the resolver neither guesses a runner
     // (BUGS.md 2026-10-05) nor re-runs the check itself while the merge slot waits on it.
     const check = detectBuildCheck(wt, ctx.config) ?? undefined;
     // Show both sides' intent: the change's own commit message and the main commits that touched
@@ -283,20 +287,26 @@ async function resolveConflict(ctx, wt, preMergeHead) {
     const since = await changeBaseRev(wt, ctx.mainBranch, preMergeHead);
     const change = (await commitMessage(wt, preMergeHead)) ?? "";
     const { commits, omitted } = await mainCommitsTouching(wt, since, ctx.mainBranch, remaining);
-    // The landing cell names the resolver run, not "merging" (a no-op outside a queued landing):
-    // the run holds the merge slot, and every queued landing waits on it. Back to `merging` once it
-    // ends, whatever happened — the merge's git steps come next, or the landing ends.
-    setLandingStage(ctx.root, ctx.role, "resolving");
+    // The merge cell names the resolver run, not "merging" (a no-op outside a queued merge):
+    // the run holds the merge slot, and every queued merge waits on it. Back to `merging` once it
+    // ends, whatever happened — the merge's git steps come next, or the merge ends.
+    setMergeStage(ctx.root, ctx.role, "resolving");
     let pi;
     try {
-        pi = await ctx.runPi(wt, buildConflictPrompt(ctx.role, remaining, check, { change, main: commits, mainOmitted: omitted }), `tumwater-${ctx.role}-${ctx.tick}-conflict`, 
+        pi = await ctx.runPi(wt, 
+        // Each file's hunk ranges, so the resolver reads the hunks rather than the file from line 1.
+        buildConflictPrompt(ctx.role, conflictedFileHunks(wt, remaining), check, {
+            change,
+            main: commits,
+            mainOmitted: omitted,
+        }), `tumwater-${ctx.role}-${ctx.tick}-conflict`, 
         // The resolver rides the strong tier (plans/model-tiers.md part 4/8): resolution is rare,
-        // tolerant of latency, and edits code inside landing. Its spend still folds into the
+        // 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.
         resolverConfig(ctx.config));
     }
     finally {
-        setLandingStage(ctx.root, ctx.role, "merging");
+        setMergeStage(ctx.root, ctx.role, "merging");
     }
     if (!pi.ok || hasConflictMarkers(wt, remaining)) {
         await abortSync(wt);

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

@@ -0,0 +1,212 @@
+// 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 { addMergeChange, mergeUsage, removeMergeChange, setMergeChangeStatus } from "./merge-slot.js";
+import { dropMerge, entryRevisionFields, queuedMergeFiles, staleHeadFile } from "./merge-queue.js";
+import { warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
+import { errorMessage } from "../text/text.js";
+import { verifyRequest } from "./merge-batch.js";
+import { abortOnShutdown, acquireUnlessAborted, discardPinnedRefs, guardMergeTask, liveRoles, settleMergeOutcome, } from "./merge-pipeline.js";
+/** The semaphore tier a verification waits at, below every roleTier (0/1): committed work whose
+ * author the interlock has already blocked jumps ahead of parked role waiters rather than starving
+ * behind them (BUGS.md 2026-09-18). Exported for merge-drain.ts, whose merge tier sits one
+ * below it. */
+export const 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
+ * run is not counted: it is the one serial step every queued change waits on. */
+export function verifyLimit(maxConcurrent) {
+    return Math.max(1, maxConcurrent - 1);
+}
+/** 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
+ * 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) {
+    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));
+}
+/** 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) {
+    const stale = staleHeadFile(root);
+    if (!stale)
+        return;
+    dropMerge(stale);
+    warnEventBestEffort(root, TUMWATER_SOURCE, `merge queue head ${path.basename(stale)} is unreadable (torn or foreign) — dropped so the queue keeps moving`);
+}
+/** 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
+ * fixed and merge-base --is-ancestor against the same head always returns the same answer — the
+ * verdict can only change when main itself moves (a merge's fast-forward). Serving the verdict
+ * from this cache makes a poll whose queue is waiting on busy authors or the merge slot cost one
+ * branchHead ref-file read instead of one git spawn per entry, and a moved main recomputes each
+ * entry's verdict once (the new head misses the cache). Bounded: verdicts computed against an
+ * older head are stale falses no future poll can reuse, so they are the first pruned. */
+const mergedIntoMainCache = new Map();
+const MERGED_INTO_MAIN_CACHE_MAX = 128;
+/** The cached dedupe verdict for `sha` against main at `head`, computing it through
+ * isMergedInto on a cache miss. `head` is the caller's already-resolved main head ("" when main
+ * does not exist yet — isMergedInto then fails and reads false, a verdict worth caching like any
+ * other since the key matches). */
+async function mergedIntoMain(root, sha, mainBranch, head) {
+    const key = `${root}\u0000${sha}`;
+    const hit = mergedIntoMainCache.get(key);
+    if (hit?.head === head)
+        return hit.merged;
+    const merged = await isMergedInto(root, sha, mainBranch);
+    if (mergedIntoMainCache.size >= MERGED_INTO_MAIN_CACHE_MAX && !mergedIntoMainCache.has(key)) {
+        for (const [k, v] of mergedIntoMainCache)
+            if (v.head !== head)
+                mergedIntoMainCache.delete(k);
+        if (mergedIntoMainCache.size >= MERGED_INTO_MAIN_CACHE_MAX)
+            mergedIntoMainCache.clear();
+    }
+    mergedIntoMainCache.set(key, { head, merged });
+    return merged;
+}
+/** Start a verification, in queue order, for every queued entry whose role the pipeline does not
+ * already hold, up to verifyLimit — the shared semaphore bounds how many of them run. The torn-head
+ * drop comes first, and each entry is deduped against main before its verification starts: an entry
+ * whose sha main already holds (a crash between the fast-forward and the drop) is dropped without a
+ * 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);
+    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.
+    const mainHead = queue.length === 0 ? "" : ((await branchHead(ctx.root, ctx.mainBranch)) ?? "");
+    for (const { entry, file } of queue) {
+        if (p.verifying.size >= verifyLimit(ctx.semaphore.limit))
+            return;
+        if (liveRoles(p).has(entry.role))
+            continue;
+        if (await mergedIntoMain(ctx.root, entry.sha, ctx.mainBranch, mainHead)) {
+            dropMerge(file);
+            removeMergeChange(ctx.root, entry.role);
+            continue;
+        }
+        // The dedupe awaited git: a task that settled meanwhile may have dropped this very entry
+        // (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;
+        startVerify(ctx, p, entry, file);
+    }
+}
+/** Start one verification task and record it in `p.verifying`: parked until a shared permit comes,
+ * at VERIFY_TIER (a shutdown settles a parked verification at once, and one granted while the start
+ * gate is closed hands its permit back — either way nothing ran, and its entry and pin stay queued
+ * with no outcome written), then, holding the permit for its whole length: open the change's
+ * marker record and verify it — checkout at the pin, rebase onto main, gate check, review
+ * (verifyRequest), the verdict persisted by the gate. An approval moves it to `approved` (record
+ * `approved, awaiting merge`). Any other verdict — rejected, a review_error of either kind,
+ * main_red, a lost pin's "error", aborted — is final for this queue entry, so its outcome is
+ * written at once and its entry dropped, which frees its author on the next poll while the
+ * other verifications run on (BUGS.md 2026-09-23's early-rejection rule). A user-aborted
+ * verification discards its pin; a shutdown keeps it. Never rejects for a failed merge: an
+ * unexpected throw becomes an "error" outcome. Exported for
+ * test/fixtures/orchestrator-fixtures.ts's mergeHead, which merges one queue entry through the
+ * pipeline without draining the rest of the queue. */
+export function startVerify(ctx, p, entry, file) {
+    const { root, mainBranch, signal, semaphore } = ctx;
+    const { role } = entry;
+    const author = resolveAuthor(ctx, role);
+    // The verification's provider key: the review seam's key for the author's role, so its reviewer
+    // run counts toward the same provider cap as the roles that share it
+    // (plans/provider-concurrency.md §4). The gate off runs no model, so then there is no key — the
+    // verification is bounded by the team total alone.
+    const reviewKey = ctx.liveConfig.review.enabled
+        ? seamConcurrencyKey(reviewRunConfig(author.config), ctx.piDefault)
+        : undefined;
+    const verify = {
+        promise: Promise.resolve(), // Replaced below; the placeholder satisfies the type.
+        controller: new AbortController(),
+        roles: [role],
+        userAborted: false,
+        parked: true,
+    };
+    const detachShutdown = abortOnShutdown(signal, verify.controller);
+    p.verifying.set(role, verify);
+    const task = (async () => {
+        try {
+            const lease = await acquireUnlessAborted(semaphore, VERIFY_TIER, verify.controller.signal, reviewKey);
+            verify.parked = false;
+            if (lease === null)
+                return; // a shutdown while parked
+            if (verify.controller.signal.aborted || ctx.startHeld()) {
+                lease.release(); // stopping, or a restart / team hold closed the gate while it waited
+                return;
+            }
+            const { usage, foldUsage } = mergeUsage(author, root);
+            let verdict;
+            const startedAt = Date.now();
+            try {
+                addMergeChange(root, entry, liveRoles(p));
+                // The verification's lease rides in the provider-lease store for the verification's body,
+                // 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) }, {
+                    role,
+                    sha: entry.sha,
+                    tick: entry.run,
+                    summary: entry.summary,
+                    body: entry.body,
+                    highFriction: entry.highFriction,
+                    ...entryRevisionFields(entry),
+                }, { state: author.state, foldUsage, runPi: (w, prompt, s, cfg) => author.runMergePi(w, prompt, s, cfg), runGatePi: (opts) => author.runGatePi(opts) }), { piDefault: ctx.piDefault, hooks: providerWaitStage(root, role) });
+            }
+            catch (err) {
+                verdict = { kind: "result", result: "error" };
+                author.state.lastError = errorMessage(err);
+            }
+            finally {
+                lease.release();
+            }
+            if (verdict.kind === "stack" && !verify.userAborted) {
+                p.approved.set(role, {
+                    entry,
+                    file,
+                    sha: verdict.sha,
+                    ...(verdict.verifiedHead !== undefined ? { verifiedHead: verdict.verifiedHead } : {}),
+                    startedAt,
+                    author,
+                    usage,
+                    foldUsage,
+                    roles: [role],
+                    controller: new AbortController(),
+                    userAborted: false,
+                });
+                setMergeChangeStatus(root, role, "approved");
+            }
+            else {
+                const result = verdict.kind === "stack" ? "aborted" : verdict.result;
+                await settleMergeOutcome(root, entry, author.state, result, Date.now() - startedAt, usage, file);
+                if (verify.userAborted)
+                    await discardPinnedRefs(root, [role]);
+            }
+        }
+        finally {
+            detachShutdown();
+            p.verifying.delete(role);
+        }
+    })();
+    verify.promise = guardMergeTask(root, role, task);
+}

package/dist/src/notes-cli.js

@@ -0,0 +1,97 @@
+#!/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
+ * it only the note `TUMWATER_NOTES_PATH` names — the path comes from the environment tumwater
+ * set, never from an argument. It replaces the three legacy carriers (the pi extension, and
+ * the MCP server for Claude Code and OpenCode), validating and writing through the same
+ * validateRoleNote / writeRoleNote as those, so the 4 KB cap and atomic write cannot drift.
+ *
+ * Subcommands:
+ *   write            replace the note with stdin (refuses empty input)
+ *   write --file <p> replace the note with the file at <p>
+ *   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. */
+import fs from "node:fs";
+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;
+const USAGE = [
+    "usage: tumwater-notes <write [--file <path>] | show | clear>",
+    "  write replaces the note with stdin, clear empties it, show prints it (--file reads <path> instead of stdin)",
+    "  the note is the file TUMWATER_NOTES_PATH names",
+].join("\n");
+/** Read the child's stdin to EOF as UTF-8. */
+function readStdin() {
+    return fs.readFileSync(0, "utf8");
+}
+/** Read the note's current text; a missing note reads as empty (show prints nothing). */
+function readNote() {
+    try {
+        return fs.readFileSync(NOTES_PATH, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+/** Refuse with `message` on stderr and exit 1 — the exit code for every expected refusal. */
+function refuse(message) {
+    process.stderr.write(`${message}\n`);
+    return 1;
+}
+/** Write a non-empty note and announce it; assumes NOTES_PATH is set. Returns the exit code. */
+function writeNote(text) {
+    if (text === "") {
+        return refuse("nothing to write — use `tumwater-notes clear` to empty the note");
+    }
+    const error = validateRoleNote(text);
+    if (error)
+        return refuse(error);
+    writeRoleNote(NOTES_PATH, text);
+    process.stdout.write(`notes saved (${Buffer.byteLength(text, "utf8")} bytes)\n`);
+    return 0;
+}
+function main() {
+    if (NOTES_PATH === undefined || NOTES_PATH === "") {
+        return refuse("this run keeps no notes");
+    }
+    const args = process.argv.slice(2);
+    const [command, flag, flagArg] = args;
+    switch (command) {
+        case "write":
+            if (flag === undefined)
+                return writeNote(readStdin());
+            if (flag === "--file") {
+                if (flagArg === undefined || args.length > 3)
+                    return refuse(USAGE);
+                let text;
+                try {
+                    text = fs.readFileSync(flagArg, "utf8");
+                }
+                catch {
+                    return refuse(`cannot read ${flagArg}`);
+                }
+                return writeNote(text);
+            }
+            return refuse(USAGE);
+        case "show":
+            if (flag !== undefined)
+                return refuse(USAGE);
+            process.stdout.write(readNote());
+            return 0;
+        case "clear":
+            if (flag !== undefined)
+                return refuse(USAGE);
+            writeRoleNote(NOTES_PATH, "");
+            process.stdout.write("notes cleared\n");
+            return 0;
+        default:
+            process.stderr.write(`${USAGE}\n`);
+            return 2;
+    }
+}
+process.exit(main());