tumwater 0.1.2 → 0.2.0

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

@@ -1,46 +1,48 @@
-import { deleteRef, headOf, setRef } from "../git/git.js";
-import { landingRefName, mergeWorktreePath, rejectedRefName, reviewRunSessionDir } from "../paths.js";
+// vocabulary: plain
+import { deleteRef, headOf, patchId, setRef } from "../git/git.js";
+import { mergeRefName, mergeWorktreePath, rejectedRefName, reviewRunSessionDir } from "../paths.js";
 import { ensureDetachedWorktree } from "../git/worktree.js";
 import { useWorktree } from "../git/worktree-use.js";
-import { mergeToMain } from "./landing-merge.js";
-import { rebaseOntoMain } from "./landing-git.js";
-import { landingCheckRed, landingBlocked } from "./landing-check-failures.js";
+import { mergeToMain } from "./merge-to-main.js";
+import { rebaseOntoMain } from "./merge-git.js";
+import { mergeCheckRed, mergeBlocked, noteMergeRetryPassed } from "./merge-check-failures.js";
 import { reviewAheadOfMain } from "../review/review.js";
 import { reviewRunConfig, modelSelectorField } from "../config/config-views.js";
 import { warnEventBestEffort, logEventBestEffort } from "../events/events.js";
 import { saveLoopState } from "../loop/loop-state.js";
-import { REVISION_LIMIT } from "../loop/revision.js";
+import { REVISION_FINAL_ON_REPEAT, REVISION_BACKSTOP } from "../loop/revision.js";
+import { priorObjectionNumber } from "../review/review-verdict.js";
 import { DIRECTOR_ROLE } from "../roles/roles.js";
 import { shortSha } from "../text/format.js";
-import { setLandingStage } from "./landing-slot.js";
+import { setMergeStage } from "./merge-slot.js";
 /** Rebase a pinned change in its leased pool slot `wt` (checked out detached at `req.sha`) onto
  * main's CURRENT head before its review gate, and return the request that gate must judge.
  * The gate must review main's current tree, not the main the author started from: when main
- * moved after the pin (the common queued-landing case), a pre-check against the stale tree
- * fails on a failure main already fixed and every queued landing rejects in a cascade — and a
+ * moved after the pin (the common queued-merge case), a pre-check against the stale tree
+ * fails on a failure main already fixed and every queued merge rejects in a cascade — and a
  * reviewer whose checkout is behind main reads main's newer commits as the change deleting
  * them (BUGS.md 2026-09-23: d13cf2e, a sound feature, rejected for "reverting" five commits
- * that landed after its pin). A no-op when main has not moved; on a clean rebase the ref and
- * the request track the synced head so the strike-cap tell and the landing ref name the tree
- * that can actually land. On a conflict rebaseOntoMain has already aborted and restored the
- * detached pin — the gate reviews the pinned tree and mergeToMain's resolver lands it. Every
- * vet runs it before its gate (landing-batch.ts's vetRequest), so a gate never judges a stale
+ * that merged after its pin). A no-op when main has not moved; on a clean rebase the ref and
+ * the request track the synced head so the strike-cap tell and the merge ref name the tree
+ * that can actually merge. On a conflict rebaseOntoMain has already aborted and restored the
+ * detached pin — the gate reviews the pinned tree and mergeToMain's resolver merges it. Every
+ * verify runs it before its gate (merge-batch.ts's verifyRequest), so a gate never judges a stale
  * pin; each call rebases only its own worktree, onto main itself — never onto another queued
- * change — so concurrent vets in distinct pool slots cannot interfere. */
+ * change — so concurrent verifies in distinct pool slots cannot interfere. */
 export async function syncPinToMain(ctx, wt, req) {
     if (!(await rebaseOntoMain(wt, ctx.mainBranch)))
         return req;
     const syncedHead = await headOf(wt, "HEAD");
     if (syncedHead === req.sha)
         return req;
-    await setRef(ctx.root, landingRefName(req.role), syncedHead);
+    await setRef(ctx.root, mergeRefName(req.role), syncedHead);
     return { ...req, sha: syncedHead };
 }
-/** The ReviewContext for judging landing request `req` in worktree `wt` — the single
- * home of that argument object, shared by reviewPinnedChange's pinned vet and
- * landApprovedChange's re-review of a resolved conflict (its recheckResolved callback), so the
+/** The ReviewContext for judging merge request `req` in worktree `wt` — the single
+ * home of that argument object, shared by reviewPinnedChange's pinned verify and
+ * mergeApprovedChange's re-review of a resolved conflict (its recheckResolved callback), so the
  * two gate invocations cannot drift on which fields the reviewer sees. Both callers' contexts
- * (ReviewGateContext and LanderContext) carry the root/mainBranch/config/signal/runGatePi fields
+ * (ReviewGateContext and MergerContext) carry the root/mainBranch/config/signal/runGatePi fields
  * this reads. */
 function reviewContextFor(ctx, req, wt) {
     return {
@@ -50,8 +52,8 @@ function reviewContextFor(ctx, req, wt) {
         mainBranch: ctx.mainBranch,
         config: ctx.config,
         tick: req.tick,
-        // One directory per review of one change: tick plus the pinned sha, so a re-vet of the
-        // same sha reuses it and the vet and the conflict-resolved re-review agree.
+        // One directory per review of one change: tick plus the pinned sha, so a re-verify of the
+        // same sha reuses it and the verify and the conflict-resolved re-review agree.
         sessionDir: reviewRunSessionDir(ctx.root, req.role, `${req.tick}-${shortSha(req.sha)}`),
         signal: ctx.signal(),
         runGatePi: ctx.runGatePi,
@@ -60,29 +62,29 @@ function reviewContextFor(ctx, req, wt) {
     };
 }
 /** Run one pinned change through the review gate in its leased pool slot `wt` and handle the
- * immediate bookkeeping — the heart of every vet (landing-batch.ts's vetRequest). Persists the
+ * immediate bookkeeping — the heart of every verify (merge-batch.ts's verifyRequest). Persists the
  * verdict at once, folds the reviewer's usage, and routes
- * the three terminal outcomes: aborted (ref kept — fail closed, the next tick re-lands it),
+ * the three terminal outcomes: aborted (ref kept — fail closed, the next tick re-merges it),
  * rejected (ref deleted — final for this sha), and failed (a strike-cap discard — the gate
  * reports it as `discarded` — deletes the ref; an under-cap failure, a red main's included,
- * keeps it for the next re-land). Returns
- * the gate result only when the change may be landed, alongside the head to land it at. An
+ * keeps it for the next re-merge). Returns
+ * the gate result only when the change may be merged, alongside the head to merge it at. An
  * abort that has already fired is observed HERE, before the gate starts, not only by the
- * gate's pi runs: a gate that short-circuits on an already-approved head (a re-vetted change's)
+ * gate's pi runs: a gate that short-circuits on an already-approved head (a re-verified change's)
  * runs no pi at all, and one that does still spends its build pre-check first — so a stopping
- * landing (a restart hand-off past its deadline, BUGS.md 2026-09-23) would otherwise sail
+ * merge (a restart hand-off past its deadline, BUGS.md 2026-09-23) would otherwise sail
  * through its gate into the check. */
 export async function reviewPinnedChange(ctx, req, wt, state, foldUsage) {
     const { root, config } = ctx;
     const { role } = req;
-    const ref = landingRefName(role);
+    const ref = mergeRefName(role);
     // Both uses below — a rejection and a strike-cap discard — end a pinned change without
     // keeping it: drop the held-selector note and the pin ref together, so the two-part cleanup
-    // cannot drift between them. The vet's checkout is a pooled slot (plans/worktree-pool.md,
-    // "Vets and merges"): vetRequest releases the lease in its finally, and a slot is reused, so
+    // cannot drift between them. The verify's checkout is a pooled slot (plans/worktree-pool.md,
+    // "Vets and merges"): verifyRequest releases the lease in its finally, and a slot is reused, so
     // this path must not remove the worktree it ran in.
     const discardPin = async () => {
-        state.landingReviewError = undefined;
+        state.mergeReviewError = undefined;
         await deleteRef(root, ref);
     };
     // Already stopping: the gate never starts, so nothing is persisted or folded — the ref stays
@@ -90,28 +92,30 @@ export async function reviewPinnedChange(ctx, req, wt, state, foldUsage) {
     if (ctx.signal().aborted)
         return { kind: "result", result: "aborted" };
     const gate = await reviewAheadOfMain(reviewContextFor(ctx, req, wt), state, req.summary, req.body, req.highFriction);
-    // The gate is over, whatever it decided: move the landing cell off the gate's stages (a no-op
-    // outside a queued landing). What follows is the wait for the merge — the vet marks the change
-    // `vetted` next, and the merge slot re-stages it `merging` when it takes it — and a finished
+    // The gate is over, whatever it decided: move the merge cell off the gate's stages (a no-op
+    // outside a queued merge). What follows is the wait for the merge — the verify marks the change
+    // `approved` next, and the merge slot re-stages it `merging` when it takes it — and a finished
     // reviewer's last turns left in the cell would accrue a false `no pi output` flag for as long
     // as the change waits.
-    setLandingStage(root, role, "merging");
+    setMergeStage(root, role, "merging");
     // A rejection keeps the rejected commit alive while a revision is due (plans/revise-rejected.md):
     // point the rejected ref at the head the gate judged and record the round, so the author's next
-    // tick re-applies it. Past REVISION_LIMIT the rejection is final: clear the state, delete the
-    // ref, and log `exhausted`. Done before the save below so the round rides the persisted state.
+    // tick re-applies it. A rejection is final — clear the state, delete the ref, and log
+    // `exhausted` — when the same objection has survived two revisions or the chain hit the
+    // backstop (BUGS.md 2026-10-14). Done before the save below so the round rides the
+    // persisted state.
     if (gate.decision === "rejected") {
-        await recordRejectedChange(root, role, state, state.lastReview?.head ?? req.sha, req.revisionRound);
+        await recordRejectedChange(root, role, state, state.lastReview?.head ?? req.sha, req.revisionRound, req.priorReview?.counts);
     }
     // Persist the verdict immediately, not at the tick's end save: the gate's bookkeeping is
     // cross-tick memory (a persisted "reject" injects a "your previous change was rejected"
-    // note into the next prompt), and this tick's tail — the landing plus the still-to-come
+    // note into the next prompt), and this tick's tail — the merge plus the still-to-come
     // authoring run — can outlive a sudden death by hours. A mid-run crash (power loss,
     // kill -9) would otherwise roll the state file back to the last tick-boundary snapshot
     // and re-inject a superseded rejection even though its replacement is already on main.
     saveLoopState(root, state);
     // The reviewer's usage is folded exactly once per attempt: runGatePi folds a RETRIED first
-    // attempt at retry time (stamping the fleet-wide rate-limit hold promptly, BUGS.md
+    // attempt at retry time (stamping the team-wide rate-limit hold promptly, BUGS.md
     // 2026-10-01), and the final run is folded HERE — not also inside the wiring, which would
     // count the reviewer twice.
     if (gate.run)
@@ -124,7 +128,7 @@ export async function reviewPinnedChange(ctx, req, wt, state, foldUsage) {
     // produced it — one more line here, because a GateResult carries a third run now.
     if (gate.nudgeRun)
         foldUsage(gate.nudgeRun);
-    // Shutdown/user abort mid-review: fail closed — the ref stays and the next tick re-lands it.
+    // Shutdown/user abort mid-review: fail closed — the ref stays and the next tick re-merges it.
     // The caller routes "aborted" through its own abort handling (which discards the pin too when
     // the abort was a deliberate user stop).
     if (gate.aborted)
@@ -136,7 +140,7 @@ export async function reviewPinnedChange(ctx, req, wt, state, foldUsage) {
     }
     if (gate.decision === "failed" && gate.mainRed) {
         // Main is red at its tip: nothing judged this diff and nothing is wrong with the reviewer,
-        // so it is main_red, not review_error — the pin stays for a re-land once main is green.
+        // so it is main_red, not review_error — the pin stays for a re-merge once main is green.
         state.lastError = `gate check failed: ${gate.detail}`;
         return { kind: "result", result: "main_red" };
     }
@@ -148,7 +152,7 @@ export async function reviewPinnedChange(ctx, req, wt, state, foldUsage) {
         // 2026-10-06). A discarded pin is gone, so no hold is recorded for it.
         if (gate.configError && !gate.discarded) {
             const selector = modelSelectorField(reviewRunConfig(config)).model;
-            state.landingReviewError = {
+            state.mergeReviewError = {
                 sha: req.sha,
                 ...(selector ? { selector } : {}),
                 message: state.lastError,
@@ -157,7 +161,7 @@ export async function reviewPinnedChange(ctx, req, wt, state, foldUsage) {
         }
         // Strike-cap discard: the gate says so directly (it reset the worktree off the pin) — the
         // commit is gone and the ref goes too. An under-cap failure — a dead reviewer — keeps the
-        // pin as it is: the gate never commits, so the pin still names the tree the next re-land
+        // pin as it is: the gate never commits, so the pin still names the tree the next re-merge
         // reviews.
         if (gate.discarded) {
             await discardPin();
@@ -166,7 +170,7 @@ export async function reviewPinnedChange(ctx, req, wt, state, foldUsage) {
         return { kind: "result", result: "review_error" };
     }
     // Approved or exempt: track the pin to the head the verdict judged, so a merge that cannot
-    // finish (conflict/blocked) leaves recovery re-landing that tree, not a stale pin.
+    // finish (conflict/blocked) leaves recovery re-merging that tree, not a stale pin.
     // verifiedHead carries it when the pre-check ran green; otherwise the worktree head does. An
     // unreadable head keeps the old pin (fail closed).
     const sha = gate.verifiedHead ?? (await headOf(wt, "HEAD").catch(() => req.sha));
@@ -174,73 +178,92 @@ export async function reviewPinnedChange(ctx, req, wt, state, foldUsage) {
         await setRef(root, ref, sha);
         req = { ...req, sha };
     }
-    // The change may land: nothing is held against the previous reviewer selector any more.
-    state.landingReviewError = undefined;
+    // The change may merge: nothing is held against the previous reviewer selector any more.
+    state.mergeReviewError = undefined;
     return { kind: "gate", gate, sha };
 }
-/** The failed landing outcomes that KEEP the pin for another attempt: an under-cap review
- * failure, or a merge that could not be rebased/landed. They are exactly a landing's
+/** The failed merge outcomes that KEEP the pin for another attempt: an under-cap review
+ * failure, or a merge that could not be rebased/merged. They are exactly a merge's
  * non-terminal failures (`rejected` is final and deletes the pin; `aborted` is a shutdown;
- * `changed` landed), so a run of them on the leftover-recovery path is what feeds the error
+ * `changed` merged), so a run of them on the leftover-recovery path is what feeds the error
  * streak — a dead reviewer backend raises the alarm instead of resetting it every tick
  * (BUGS.md 2026-09-21). */
-export const RETRIABLE_LANDING_RESULTS = new Set([
+export const RETRIABLE_MERGE_RESULTS = new Set([
     "review_error",
     "merge_conflict",
     "merge_blocked",
 ]);
-/** Record a gate rejection for the revise-rejected feature (plans/revise-rejected.md): while
- * the round is within REVISION_LIMIT, point `refs/tumwater/rejected/<role>` at the head the gate
- * judged and set LoopState.revision so the author's next tick re-applies it; past the limit,
- * clear the revision, delete the ref and log `exhausted`. Shared by a pinned change's rejection
- * (reviewPinnedChange) and the in-lock re-review rejection of a resolved conflict
- * (landApprovedChange), so both send the change back for revision the same way. A rejection
- * with no `revisionRound` is a fresh change's first round (1). The director never revises. */
-async function recordRejectedChange(root, role, state, rejectedHead, revisionRound) {
+/** Record a gate rejection for the revise-rejected feature (plans/revise-rejected.md; the
+ * repeat-finality policy in BUGS.md 2026-10-14): a rejection sends the change back for another
+ * round UNLESS the same objection has survived two revisions — a `(prior N)` restatement whose
+ * count reaches REVISION_FINAL_ON_REPEAT, counted from `priorCounts` — or the chain has reached
+ * the REVISION_BACKSTOP cap, when it ends even if the objections never repeat. While it keeps
+ * revising, point `refs/tumwater/rejected/<role>` at the head the gate judged and set
+ * LoopState.revision (with each reason's persistence count) so the author's next tick re-applies
+ * it; when final, clear the revision, delete the ref and log `exhausted`. `priorCounts` is the
+ * previous round's per-reason persistence counts, carried from the queued merge's PriorReview;
+ * absent for a fresh change's first rejection and on a recovery merge, a `(prior N)` tag then
+ * reads as a fresh objection. Shared by a pinned change's rejection (reviewPinnedChange) and the
+ * in-lock re-review rejection of a resolved conflict (mergeApprovedChange), so both send the
+ * change back for revision the same way. A rejection with no `revisionRound` is a fresh change's
+ * first round (1). The director never revises. */
+async function recordRejectedChange(root, role, state, rejectedHead, revisionRound, priorCounts) {
     if (role === DIRECTOR_ROLE)
         return;
     const nextRound = (revisionRound ?? 0) + 1;
-    if (nextRound <= REVISION_LIMIT) {
-        await setRef(root, rejectedRefName(role), rejectedHead);
-        state.revision = { sha: rejectedHead, round: nextRound, at: Date.now() };
+    const reasons = state.lastReview?.reasons ?? [];
+    // Each reason's persistence count: a new (untagged) objection starts at 0; a `(prior N)`
+    // restatement has survived one more revision than that objection's own count from the prior
+    // round, so an objection standing across two revisions reaches REVISION_FINAL_ON_REPEAT. An
+    // out-of-range or missing tag (a stale prior list, no prior round) reads as a fresh objection.
+    const prior = priorCounts ?? [];
+    const counts = reasons.map((r) => {
+        const n = priorObjectionNumber(r);
+        return n === null ? 0 : 1 + (prior[n - 1] ?? 0);
+    });
+    const repeatedFinal = counts.some((c) => c >= REVISION_FINAL_ON_REPEAT);
+    if (nextRound >= REVISION_BACKSTOP || repeatedFinal) {
+        state.revision = undefined;
+        await deleteRef(root, rejectedRefName(role));
+        // The next tick gets the plain rejected note, not a revision note; mark it final so that
+        // note says the rejected diff is gone rather than inviting another revision.
+        if (state.lastReview)
+            state.lastReview.exhausted = true;
+        logEventBestEffort(root, { source: role, type: "revision", action: "exhausted", round: nextRound, sha: rejectedHead });
         return;
     }
-    state.revision = undefined;
-    await deleteRef(root, rejectedRefName(role));
-    // The next tick gets the plain rejected note, not a revision note; mark it final so that
-    // note says the rejected diff is gone rather than inviting another revision.
-    if (state.lastReview)
-        state.lastReview.exhausted = true;
-    logEventBestEffort(root, { loop: role, type: "revision", action: "exhausted", round: nextRound, sha: rejectedHead });
+    await setRef(root, rejectedRefName(role), rejectedHead);
+    state.revision = { sha: rejectedHead, round: nextRound, at: Date.now(), reasonCounts: counts };
 }
-/** Land a head that already passed its OWN gate in its vet — the merge slot's one-change landing
- * and each landing of an abandoned stack's one-at-a-time fallback (landing-batch.ts's landVetted)
+/** Merge a head that already passed its OWN gate in its verify — the merge slot's one-change merge
+ * and each merge of an abandoned stack's one-at-a-time fallback (merge-batch.ts's mergeApproved)
  * — without a second gate. Re-gating would rebase first, and by then main has usually moved (a
- * fallback's earlier entries just landed): the rebase rewrites the approved sha, the gate's
- * exact-sha `lastApprovedHead` short-circuit misses, and every such landing paid a second build
+ * fallback's earlier entries just merged): the rebase rewrites the approved sha, the gate's
+ * exact-sha `lastApprovedHead` short-circuit misses, and every such merge paid a second build
  * check and model review of a change it had already approved (BUGS.md 2026-09-23). Here a clean
  * rebase of the approved head is accepted as-is: mergeToMain's own in-lock rebase moves it onto
  * main's tip, and because the pre-merge head it captures is the approved `req.sha`,
- * verifyLanding runs one bounded scope-`landing` check whenever that rebase rewrote anything
+ * verifyMerge runs one bounded scope-`merge` check whenever that rebase rewrote anything
  * (and skips only for the exact bytes the gate judged, seeding the red-main baseline when
  * `req.verifiedHead` names them). A conflicting rebase gets mergeToMain's resolver — the rule for
  * a pin whose pre-gate rebase conflicted. `lastApprovedHead` is neither read nor widened: the
- * caller vouches for `req.sha` (only approved/exempt changes are vetted). Owns the landing ref's
- * lifecycle from here: deleted on landing, KEPT on every non-terminal outcome (aborted,
- * merge_conflict, merge_blocked) for the next tick's leftover recovery. An abort that has
+ * caller vouches for `req.sha` (only changes the gate approved or exempted are merged). Owns
+ * the merge ref's lifecycle from here: deleted on merge, KEPT on every non-terminal outcome
+ * (aborted, merge_conflict, merge_blocked) for the next tick's leftover recovery. An abort that has
  * already fired returns "aborted" before anything starts, ref kept — the merge's step-boundary
  * stop (BUGS.md 2026-09-23): with no gate here, nothing else on this path would notice it
- * before the in-lock check and the merge. Never throws for a failed landing: git-level failures
+ * before the in-lock check and the merge. Never throws for a failed merge: git-level failures
  * propagate like any other failure. */
-export async function landApprovedChange(ctx, req) {
+export async function mergeApprovedChange(ctx, req) {
     if (ctx.signal().aborted)
         return "aborted";
     // Hold the merge worktree from before ensureDetachedWorktree (its reset is part of the
     // use) through the merge (plans/disk-floor.md, part 2/4).
-    return useWorktree(ctx.root, mergeWorktreePath(ctx.root), () => landApprovedChangeIn(ctx, req));
+    return useWorktree(ctx.root, mergeWorktreePath(ctx.root), () => mergeApprovedChangeIn(ctx, req));
 }
-async function landApprovedChangeIn(ctx, req) {
+async function mergeApprovedChangeIn(ctx, req) {
     const wt = await ensureDetachedWorktree(ctx.root, mergeWorktreePath(ctx.root), req.sha);
+    const pinPatch = await patchId(wt, ctx.mainBranch, req.sha).catch(() => null);
     let red;
     let blocked;
     const result = await mergeToMain({
@@ -251,10 +274,10 @@ async function landApprovedChangeIn(ctx, req) {
         config: ctx.config,
         tick: req.tick,
         runPi: ctx.runPi,
-        onLandingCheckRed: (check, outcome) => {
+        onMergeCheckRed: (check, outcome) => {
             red = { check, outcome };
         },
-        onLandingBlocked: (reason) => {
+        onMergeBlocked: (reason) => {
             blocked = reason;
         },
         recheckResolved: async (resolvedWt) => {
@@ -262,7 +285,7 @@ async function landApprovedChangeIn(ctx, req) {
                 return { verdict: "retry" };
             // A resolved diff that left the reviewed change's lines goes back through the same gate
             // the pin went through (BUGS.md 2026-10-01: a resolution that restored code main had
-            // deliberately reverted landed on the build check alone). Same gate, same worktree
+            // deliberately reverted merged on the build check alone). Same gate, same worktree
             // convention as reviewPinnedChange: the reject path records the verdict, resets the
             // worktree to main and logs review_rejected itself; the ref and the lastError are ours.
             const gate = await reviewAheadOfMain(reviewContextFor(ctx, req, resolvedWt), ctx.state, req.summary, req.body, req.highFriction);
@@ -272,7 +295,7 @@ async function landApprovedChangeIn(ctx, req) {
                 ctx.foldUsage(gate.followUpRun);
             if (gate.nudgeRun)
                 ctx.foldUsage(gate.nudgeRun);
-            setLandingStage(ctx.root, req.role, "merging");
+            setMergeStage(ctx.root, req.role, "merging");
             saveLoopState(ctx.root, ctx.state);
             if (gate.aborted)
                 return { verdict: "retry" };
@@ -284,34 +307,35 @@ async function landApprovedChangeIn(ctx, req) {
                 // author for revision (plans/revise-rejected.md), exactly as a pinned change's
                 // rejection does, then drop this pin. Persist before returning — the state save above
                 // predates this bookkeeping.
-                await recordRejectedChange(ctx.root, req.role, ctx.state, ctx.state.lastReview?.head ?? req.sha, req.revisionRound);
+                await recordRejectedChange(ctx.root, req.role, ctx.state, ctx.state.lastReview?.head ?? req.sha, req.revisionRound, req.priorReview?.counts);
                 saveLoopState(ctx.root, ctx.state);
-                await deleteRef(ctx.root, landingRefName(req.role)); // the verdict is final for this pin
+                await deleteRef(ctx.root, mergeRefName(req.role)); // the verdict is final for this pin
                 ctx.state.lastError = "merge failed: conflict resolution rejected on re-review";
                 return { verdict: "rejected" };
             }
             // A failed gate (dead reviewer, aborted run) is no verdict about the tree: under the
-            // strike cap the pin stays for recovery's re-land (the gate's own discard fires here as
+            // strike cap the pin stays for recovery's re-merge (the gate's own discard fires here as
             // "discarded", and then the commit is gone anyway).
             ctx.state.lastError = `merge failed: re-review failed: ${gate.detail}`;
             if (gate.discarded) {
-                await deleteRef(ctx.root, landingRefName(req.role));
+                await deleteRef(ctx.root, mergeRefName(req.role));
                 return { verdict: "rejected" };
             }
             return { verdict: "retry" };
         },
     }, wt, req.summary, req.verifiedHead);
     if (result === "changed") {
-        await deleteRef(ctx.root, landingRefName(req.role)); // landed: the pin has done its job
+        await deleteRef(ctx.root, mergeRefName(req.role)); // merged: the pin has done its job
+        noteMergeRetryPassed(ctx, req.role, pinPatch);
         return result;
     }
     if (result === "merge_blocked" && red)
-        return landingCheckRed(ctx, req.role, wt, red);
+        return mergeCheckRed(ctx, req.role, wt, red);
     if (result === "merge_blocked" && blocked !== undefined) {
-        return landingBlocked(ctx, req.role, wt, blocked);
+        return mergeBlocked(ctx, req.role, wt, blocked);
     }
-    // merge_conflict / merge_blocked: keep the ref — the next tick's recovery re-lands it.
-    // (Cross-check blocks no longer come through here: landing-check-failures.ts's landingBlocked
+    // merge_conflict / merge_blocked: keep the ref — the next tick's recovery re-merges it.
+    // (Cross-check blocks no longer come through here: merge-check-failures.ts's mergeBlocked
     // counts them.)
     // A rejected recheck already wrote its own lastError and deleted its ref — leave it.
     if (result !== "rejected")

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

@@ -1,6 +1,6 @@
 import { increment } from "../collections.js";
 import { gitTry } from "../git/git-run.js";
-/** The landing-scope DIFF COMPARISON (see landing-merge.ts for the merge flow that consults
+/** The merge-scope DIFF COMPARISON (see merge-to-main.ts for the merge flow that consults
  * it): whether a conflict-resolved tree's diff ahead of main stays inside the diff the review
  * gate approved. Pure multiset comparison over unified diffs, plus the git reads that produce
  * them — kept apart from the merge flow so the hunk-aware parsing (BUGS.md 2026-10-02) is

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

@@ -0,0 +1,212 @@
+// vocabulary: plain
+import { mergeApproved } from "./merge-batch.js";
+import { removeMergeChange, resolveWaitStage, setMergeChangeStatus } from "./merge-slot.js";
+import { seamConcurrencyKey } from "../config/config-views.js";
+import { withProviderLease } from "../concurrency/provider-lease.js";
+import { dropMerge, entryRevisionFields, queuedMergeFiles } from "./merge-queue.js";
+import { errorMessage } from "../text/text.js";
+import { warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
+import { saveLoopState } from "../loop/loop-state.js";
+import { abortOnShutdown, discardPinnedRefs, guardMergeTask, settleMergeOutcome, } from "./merge-pipeline.js";
+import { drainVerify, VERIFY_TIER } from "./merge-verify.js";
+/** The tier the merge slot's conflict-resolution runs wait at: 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.) */
+const MERGE_TIER = VERIFY_TIER - 1;
+/** One poll of the merge queue (the scheduler's WHEN: after the gates, never while a restart or
+ * a team hold is pending): start a verification for every queued change the pipeline does not
+ * already hold (drainVerify, in merge-verify.ts), and start the merge when the slot is free and
+ * something is approved (drainMerge). A queued merge is COMMITTED work awaiting completion, not
+ * a new tick, so the budget and user-pause gates deliberately do not hold it (pausing it would
+ * leave main behind while the interlock blocks that role's next tick forever). Starts tasks and
+ * returns; never awaits them — authors keep ticking behind them, which is the entire point. */
+export async function drainMergeQueue(ctx, p) {
+    await drainVerify(ctx, p);
+    drainMerge(ctx, p);
+}
+/** Settle every approved change `tumwater abort --role` flagged (consumeAbortRequests over
+ * abortableMerges): it has no task to stop, so it ends here exactly as an aborted merge
+ * does — "aborted" written back, entry dropped, pin discarded (the deliberate stop throws the
+ * committed work away). The scheduler runs it every poll right after consuming the requests,
+ * held or not: a restart hold that skipped it would hand the flagged change, pin intact, to
+ * the next generation to merge.
+ *
+ * Unlike a verification or a merge, this settles in the poll body with nothing to guard it: a throw
+ * out of the outcome write — an unwritable state file — would end the team's run. It must also
+ * never leave the deliberately aborted change queued (an abandoned queue file would be
+ * re-verified and merged next poll, against the operator's intent) or keep its pin. So a failed
+ * write is reported and the abort honored by hand: queue file and marker dropped, pin
+ * discarded. */
+export async function settleAbortedApproved(root, p) {
+    for (const [role, v] of [...p.approved]) {
+        if (!v.userAborted)
+            continue;
+        p.approved.delete(role);
+        try {
+            await settleMergeOutcome(root, v.entry, v.author.state, "aborted", Date.now() - v.startedAt, v.usage, v.file);
+        }
+        catch (err) {
+            warnEventBestEffort(root, TUMWATER_SOURCE, `the stopped merge for ${role} could not be settled: ${errorMessage(err)}`);
+            dropMerge(v.file);
+            removeMergeChange(root, role);
+        }
+        await discardPinnedRefs(root, [role]);
+    }
+}
+/** Start the merge when the slot is free and something is approved: every approved change, up to
+ * mergeBatchMax, in queue order among the approved — an unapproved entry ahead of them in the queue
+ * (a slow review) does not hold them back. An approved change whose queue entry is gone is
+ * forgotten (nothing in-process drops one; defensive). */
+export function drainMerge(ctx, p) {
+    if (p.merge !== null || p.approved.size === 0)
+        return;
+    const queued = queuedMergeFiles(ctx.root);
+    const files = new Set(queued.map((q) => q.file));
+    for (const [role, v] of [...p.approved]) {
+        if (files.has(v.file))
+            continue;
+        p.approved.delete(role);
+        removeMergeChange(ctx.root, role);
+    }
+    const picks = queued.flatMap((q) => {
+        const v = p.approved.get(q.entry.role);
+        return v?.file === q.file ? [v] : [];
+    });
+    picks.splice(ctx.liveConfig.mergeBatchMax);
+    if (picks.length === 0)
+        return;
+    for (const v of picks)
+        p.approved.delete(v.entry.role);
+    p.merge = startMerge(ctx, p, picks);
+}
+/** The merge task — main's one writer in the pipeline: merge `picks` through mergeApproved on
+ * main's current tip — one change through mergeApprovedChange, two or more as one stack with one
+ * scope-`batch` check, one fast-forward, and 3d's largest-passing-prefix bisect — with no second
+ * review. An approved change whose main moved since its verification is re-checked on the tree that
+ * merges (the in-lock re-check, or the stack's check), so an approval that outlived its base never
+ * merges unverified. Each defined result is written back and its entry dropped; an unattempted
+ * change (behind a bisect's attributed one) goes back to `approved` for the next merge. A plumbing
+ * throw keeps every entry queued, but unapproved: each is verified afresh from its pin next poll. A
+ * user abort of any merged role stops the whole stack, and every change it had not merged ends
+ * "aborted" with its pin discarded; a shutdown keeps the pins. The task takes no permit of its
+ * own — its only model run is mergeToMain's conflict resolver, which takes a shared permit at
+ * MERGE_TIER for the run's length, outside the merge lock. */
+function startMerge(ctx, p, picks) {
+    const { root, mainBranch, signal, roleConfig, semaphore } = ctx;
+    const merge = {
+        promise: Promise.resolve(), // Replaced below; the placeholder satisfies the type.
+        controller: new AbortController(),
+        roles: picks.map((v) => v.entry.role),
+        userAborted: false,
+    };
+    const detachShutdown = abortOnShutdown(signal, merge.controller);
+    const wiring = new Map(picks.map((v) => [
+        v.entry.role,
+        {
+            state: v.author.state,
+            foldUsage: v.foldUsage,
+            runGatePi: (opts) => v.author.runGatePi(opts),
+            runPi: async (w, prompt, s, cfg) => {
+                // A parked resolver names its wait (resolve-wait, then resolving once granted) the way
+                // a parked check does (withCheckPermit): on 2026-10-12 one waited 2.5 min for a permit
+                // with the merge queue behind it, reading as "merging". The lease is keyed on the
+                // resolver config's provider (the `cfg` it is handed), so the conflict resolution
+                // counts against the strong tier's provider cap like any other strong-tier run
+                // (plans/provider-concurrency.md §4). canLeaseAtOnce is acquireLease's own fast path
+                // decided synchronously, so a free permit shows no wait; MERGE_TIER ignores the
+                // maintenance reserve.
+                const key = cfg ? seamConcurrencyKey(cfg, ctx.piDefault) : undefined;
+                const hooks = resolveWaitStage(root, v.entry.role);
+                if (!semaphore.canLeaseAtOnce(MERGE_TIER, key))
+                    hooks.waiting();
+                const lease = await semaphore.acquireLease(MERGE_TIER, key);
+                hooks.granted();
+                try {
+                    // The resolver's lease rides in the provider-lease store for its run, so the run
+                    // re-keys it to the provider it actually uses (plans/provider-concurrency.md §5).
+                    return await withProviderLease(lease, semaphore, () => v.author.runMergePi(w, prompt, s, cfg), { piDefault: ctx.piDefault });
+                }
+                finally {
+                    lease.release();
+                }
+            },
+        },
+    ]));
+    const task = (async () => {
+        let results;
+        let threw = false;
+        // A result reaches settleMergeOutcome the moment mergeApproved finalizes it, not after the
+        // whole batch; this set lets the end-of-batch loop skip what is already written back.
+        const settled = new Set();
+        const settleOne = async (s, result) => {
+            const v = picks[s];
+            settled.add(s);
+            await settleMergeOutcome(root, v.entry, v.author.state, result, Date.now() - v.startedAt, v.usage, v.file);
+        };
+        try {
+            results = await mergeApproved({
+                root,
+                mainBranch,
+                config: roleConfig,
+                signal: () => merge.controller.signal,
+                onChangeStatus: (role, status) => setMergeChangeStatus(root, role, status),
+                onResult: settleOne,
+                runGatePi: (opts) => picks[0].author.runGatePi(opts),
+            }, picks.map((v) => ({
+                role: v.entry.role,
+                sha: v.sha,
+                tick: v.entry.run,
+                summary: v.entry.summary,
+                body: v.entry.body,
+                highFriction: v.entry.highFriction,
+                ...entryRevisionFields(v.entry),
+                ...(v.verifiedHead !== undefined ? { verifiedHead: v.verifiedHead } : {}),
+            })), (role) => wiring.get(role));
+        }
+        catch (err) {
+            threw = true;
+            results = picks.map(() => undefined);
+            const head = picks[0].author;
+            head.state.lastError = errorMessage(err);
+            // The catch exists to keep every entry queued and unapproved when mergeApproved throws. A
+            // throw out of this write — an unwritable state file — must not skip the settle loop
+            // and the finally that frees the merge slot, or the pipeline wedges with p.merge set
+            // forever; the write is bookkeeping a later save retries, so warn and keep going.
+            try {
+                saveLoopState(root, head.state);
+            }
+            catch (writeErr) {
+                warnEventBestEffort(root, TUMWATER_SOURCE, `the merge error for ${head.state.role} could not be saved: ${errorMessage(writeErr)}`);
+            }
+        }
+        try {
+            for (let s = 0; s < picks.length; s++) {
+                const v = picks[s];
+                const { role } = v.entry;
+                if (settled.has(s))
+                    continue; // already written back through onResult
+                const result = results[s] ?? (merge.userAborted ? "aborted" : undefined);
+                if (result === undefined && !threw) {
+                    p.approved.set(role, v);
+                    setMergeChangeStatus(root, role, "approved");
+                    continue;
+                }
+                if (result !== undefined) {
+                    await settleOne(s, result);
+                }
+                else {
+                    removeMergeChange(root, role);
+                }
+            }
+        }
+        finally {
+            detachShutdown();
+            if (merge.userAborted)
+                await discardPinnedRefs(root, merge.roles);
+            p.merge = null;
+        }
+    })();
+    merge.promise = guardMergeTask(root, merge.roles.join(", "), task);
+    return merge;
+}