tumwater 0.1.2 → 0.2.0

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

@@ -1,46 +1,47 @@
-/** Two of the three halves of a landing (plans/merge-queue.md 5/5, PLANS.md land-queue speed
- * 2c): the per-change vet (vetRequest) that landing-vetting.ts's vetting stage runs for every
- * queued change, and the merge (landVetted) its one merge slot runs over the vetted ones — a
+// vocabulary: plain
+/** Two of the three halves of a merge (plans/merge-queue.md 5/5, PLANS.md land-queue speed
+ * 2c): the per-change verify (verifyRequest) that merge-verify.ts's verify stage runs for every
+ * queued change, and the merge (mergeApproved) its one merge slot runs over the approved ones — a
  * stack of two or more sharing a single build check, with a per-change fallback. The stack
- * lander landVetted drives (assemble → one shared check → ff, with re-stack and bisect) lives
- * beside it in landing-stack.ts. The shared review gate (reviewPinnedChange) and the
- * one-change landing (landApprovedChange) live beside both in landing-core.ts. */
+ * merger mergeApproved drives (assemble → one shared check → ff, with re-stack and bisect) lives
+ * beside it in merge-stack.ts. The shared review gate (reviewPinnedChange) and the
+ * one-change merge (mergeApprovedChange) live beside both in merge-core.ts. */
 import { leaseSlot } from "../git/worktree-pool.js";
 import { slotCount } from "../config/config.js";
 import { mergeWorktreePath } from "../paths.js";
-import { landApprovedChange, reviewPinnedChange, syncPinToMain, } from "./landing-core.js";
-import { attributeRedCheck } from "./landing-check-failures.js";
+import { mergeApprovedChange, reviewPinnedChange, syncPinToMain, } from "./merge-core.js";
+import { attributeRedCheck } from "./merge-check-failures.js";
 import { errorMessage } from "../text/text.js";
-import { landStack } from "./landing-stack.js";
-/** Vet one request — the whole of a vetting-stage task: lease a pooled slot for the role, check
+import { mergeStack } from "./merge-stack.js";
+/** Verify one request — the whole of a verify-stage task: lease a pooled slot for the role, check
  * its pin out detached there, rebase it onto main's current tip (syncPinToMain — so the head
  * approved here is the head its merge starts from, and a conflict leaves the pin for the gate
  * and, at the merge, mergeToMain's resolver), and run the review gate, the verdict persisted
  * immediately by reviewPinnedChange (the drain's write-back of an approved change happens only
- * once it lands, so a crash must not lose what the vet earned). The lease is released in every
- * outcome (plans/worktree-pool.md, "Vets and merges"): the vet passes its result on through the
- * landing ref and VettedLanding, never through the slot, and every merge-side step re-ensures at
+ * once it merges, so a crash must not lose what the verify earned). The lease is released in every
+ * outcome (plans/worktree-pool.md, "Vets and merges"): the verify passes its result on through the
+ * merge ref and ApprovedMerge, never through the slot, and every merge-side step re-ensures at
  * a commit. leaseSlot holds the slot through the disk-floor registry and resets it to the pin, so
- * two vets rebasing at once — or one rebasing while a merge moves main — cannot interfere. */
-export async function vetRequest(ctx, req, w) {
+ * two verifies rebasing at once — or one rebasing while a merge moves main — cannot interfere. */
+export async function verifyRequest(ctx, req, w) {
     let lease;
     try {
         lease = await leaseSlot(ctx.root, {
             role: req.role,
-            purpose: "vet",
+            purpose: "verify",
             ref: req.sha,
             signal: ctx.signal(),
             // The live view's pool budget, same rule as the tick path: a broken tumwater.json
-            // must not error the vet before its reviewer runs.
+            // must not error the verify before its reviewer runs.
             slotBudget: slotCount(ctx.config),
         });
     }
     catch (err) {
-        // An abort while waiting for a free slot is the vet never starting — the same terminal
+        // An abort while waiting for a free slot is the verify never starting — the same terminal
         // "aborted" reviewPinnedChange returns when it observes an already-fired signal.
         if (err instanceof Error && err.name === "AbortError")
             return { kind: "result", result: "aborted" };
-        // The queue entry outlived its pinned commit — the land queue outlives the ref by design
+        // The queue entry outlived its pinned commit — the merge queue outlives the ref by design
         // (a crash between pin and drop, or an outside gc), so a checkout of `req.sha` can fail
         // with the commit gone. Degrade to a terminal "error" for this request so the drain drops
         // its entry and the queue advances; a throw would keep the entry, and a lost pin would then
@@ -50,13 +51,13 @@ export async function vetRequest(ctx, req, w) {
         return { kind: "result", result: "error" };
     }
     try {
-        return await vetRequestIn(ctx, req, w, lease.dir);
+        return await verifyRequestIn(ctx, req, w, lease.dir);
     }
     finally {
         lease.release();
     }
 }
-async function vetRequestIn(ctx, req, w, wt) {
+async function verifyRequestIn(ctx, req, w, wt) {
     const synced = await syncPinToMain(ctx, wt, req);
     const outcome = await reviewPinnedChange(ctx, synced, wt, w.state, w.foldUsage);
     if (outcome.kind === "result")
@@ -66,67 +67,67 @@ async function vetRequestIn(ctx, req, w, wt) {
     const { verifiedHead } = outcome.gate;
     return verifiedHead === outcome.sha ? { kind: "stack", sha: outcome.sha, verifiedHead } : { kind: "stack", sha: outcome.sha };
 }
-/** Land changes whose own vet already approved them — the merge slot's whole task
- * (landing-drain.ts, land-queue speed 2c), over every vetted entry up to landBatchMax. `vetted` is
- * in queue order, each request at the head its vet approved (the synced pin its landing ref names);
- * none is gated again, so no model review runs here (an adversarial review of a stack would blur
- * which change a criticism applies to, so each change was reviewed alone). The flow:
+/** Merge changes whose own verify already approved them — the merge slot's whole task
+ * (merge-drain.ts, land-queue speed 2c), over every approved entry up to mergeBatchMax. `approved`
+ * is in queue order, each request at the head its verify approved (the synced pin its merge ref
+ * names); none is gated again, so no model review runs here (an adversarial review of a stack would
+ * blur which change a criticism applies to, so each change was reviewed alone). The flow:
  *
- * One change — land it through landApprovedChange: git + ff, plus an in-lock scope-`landing`
- * re-check whenever main moved since its vet (and a seeded baseline when it did not and its vet's
- * pre-check ran green on exactly that head).
+ * One change — merge it through mergeApprovedChange: git + ff, plus an in-lock scope-`merge`
+ * re-check whenever main moved since its verify (and a seeded baseline when it did not and its
+ * verify's pre-check ran green on exactly that head).
  *
  * Two or more — assemble the stack in the shared `_merge` checkout, checked out detached at
- * main's CURRENT tip, then cherry-pick each change's full range from that tip to its head to land,
+ * main's CURRENT tip, then cherry-pick each change's full range from that tip to its head to merge,
  * in queue order — `base..sha`, every commit ahead of main (normally one), capturing each
  * post-pick tip — and run ONE scope-`batch` runScopedBuildCheck over the combined tree: the
- * expensive, deterministic half the stack shares. null (no declared check) → land directly;
+ * expensive, deterministic half the stack shares. null (no declared check) → merge directly;
  * "failed" (a red tree or a timeout remapped to a reject — the tree is unverified) → bisect;
  * "skipped" (no npm / broken toolchain — the helper already warned) → proceed, never
  * fail-closed; "passed" → green. Green: under the merge lock, ffStackToMain ff's main through the
  * stack in ONE fast-forward, emits one `merged` event per change, and — only when the check
  * PASSED on exactly that tip — seeds noteGreenBaseline with the stacked tip. ff failure (main
  * moved while the check ran: the window is the whole check, and main still has writers outside the
- * land queue) → RE-STACK: assemble the same changes afresh on main's new tip and go round again,
+ * merge queue) → RE-STACK: assemble the same changes afresh on main's new tip and go round again,
  * up to BATCH_RESTACK_ATTEMPTS times, stopping before any attempt on an abort. A re-stacked tree
  * that differs from the last tree a check ran on only in review-exempt paths goes straight to the
  * ff; any other re-stack pays one more check. Only a race lost on every attempt leaves each change
- * not yet landed its ref with "merge_blocked", nothing seeded, for leftover recovery.
+ * not yet merged its ref with "merge_blocked", nothing seeded, for leftover recovery.
  *
- * Red → LAND THE LARGEST PASSING PREFIX: bisect in queue order, each
- * step the same assemble → check → ff (landStack) over a prefix of the changes not yet landed
- * — the first half of the ones the last red check ran over — so every prefix that lands, lands
- * on its own green check with nothing rewritten before its ff. A green prefix lands and the rest of
- * the red run is bisected next; a red one is halved. The one change a red check ran over alone is
- * attributed through main's own baseline (landing-check-failures.ts's attributeRedCheck): main
+ * Red → MERGE THE LARGEST PASSING PREFIX: bisect in queue order, each
+ * step the same assemble → check → ff (mergeStack) over a prefix of the changes not yet merged
+ * — the first half of the ones the last red check ran over — so every prefix that merges, merges
+ * on its own green check with nothing rewritten before its ff. A green prefix merges and the rest
+ * of the red run is bisected next; a red one is halved. The one change a red check ran over alone
+ * is attributed through main's own baseline (merge-check-failures.ts's attributeRedCheck): main
  * green → rejected with the check's reasons, no pi run; main red → "main_red", pin kept. Its
  * red is the second one observed with it in the tree, so a single flaky run never rejects a change.
  * The changes after it stay unattempted for the next merge. A stack of N with one broken change
  * costs about log2(N) + 1 extra checks, never a second model review.
  *
  * Un-assemblable (a cherry-pick conflict, on the first stack or any prefix) → ABANDON the changes
- * not yet landed to one-at-a-time, in queue order, stopping at the first non-terminal outcome, each
- * through landApprovedChange — no second gate and no model run but mergeToMain's conflict
+ * not yet merged to one-at-a-time, in queue order, stopping at the first non-terminal outcome, each
+ * through mergeApprovedChange — no second gate and no model run but mergeToMain's conflict
  * resolver. main is never left red: the only bytes this path ff's are a checked tip or per-change
- * landings re-verified in-lock whenever they differ from what their vet judged.
+ * merges re-verified in-lock whenever they differ from what their verify judged.
  *
  * An abort is observed between steps, not only by the pi runs it kills: before each
- * assembly-and-check attempt and before each one-change or fallback landing, so a stopping merge
+ * assembly-and-check attempt and before each one-change or fallback merge, so a stopping merge
  * ends at its next step boundary (BUGS.md 2026-09-23). A shared check that has already run is
  * followed through: its fast-forward is the merge's bounded commit point.
  *
  * Returns one result per request in order; `undefined` means unattempted (behind a bisect's
  * attributed change, or a fallback early stop) — entry and ref kept for the next merge. On an
  * abort every request without a result reads "aborted" (refs kept). `wiringFor` must return the
- * same wiring for a role on every call (its usage accumulator is the landing's). Never throws for a
- * failed landing — per-change landApprovedChange failures degrade to "error", and so does a throw
+ * same wiring for a role on every call (its usage accumulator is the merge's). Never throws for a
+ * failed merge — per-change mergeApprovedChange failures degrade to "error", and so does a throw
  * from any bisect step after the first stack attempt, on the change at the front of that step (a
  * prefix may already be on main, and a throw would lose its "changed"); only the first stack
  * attempt's git plumbing propagates, and the merge slot then keeps every entry. */
-export async function landVetted(ctx, vetted, wiringFor) {
-    const results = vetted.map(() => undefined);
-    const report = (s, status) => ctx.onChangeStatus?.(vetted[s].role, status);
-    const landerCtx = (w) => ({
+export async function mergeApproved(ctx, approved, wiringFor) {
+    const results = approved.map(() => undefined);
+    const report = (s, status) => ctx.onChangeStatus?.(approved[s].role, status);
+    const mergerCtx = (w) => ({
         root: ctx.root,
         mainBranch: ctx.mainBranch,
         config: ctx.config,
@@ -145,62 +146,62 @@ export async function landVetted(ctx, vetted, wiringFor) {
         await ctx.onResult?.(s, result);
     };
     const finish = () => aborted ? results.map((r) => r ?? "aborted") : results;
-    // The landing step the degenerate case and the abandon fallback share: land one request
-    // through landApprovedChange on its role's wiring, and degrade a throw to "error" on that
+    // The merge step the degenerate case and the abandon fallback share: merge one request
+    // through mergeApprovedChange on its role's wiring, and degrade a throw to "error" on that
     // change (its ref kept for recovery) with the reason on the role's state — a throw means
     // this change's plumbing failed, never that an earlier one is lost (see the catches below
-    // and test/lander-errors.test.ts, which pins the degradation).
-    const landOne = async (s, req) => {
+    // and test/merger-errors.test.ts, which pins the degradation).
+    const mergeOne = async (s, req) => {
         try {
-            await emit(s, await landApprovedChange(landerCtx(wiringFor(req.role)), req));
+            await emit(s, await mergeApprovedChange(mergerCtx(wiringFor(req.role)), req));
         }
         catch (err) {
             wiringFor(req.role).state.lastError = errorMessage(err);
             await emit(s, "error");
         }
     };
-    // ── The degenerate case: one vetted change lands on its own ──────────────────────────
-    if (vetted.length === 1) {
-        const req = vetted[0];
-        report(0, "landing");
-        await landOne(0, req);
+    // ── The degenerate case: one approved change merges on its own ──────────────────────────
+    if (approved.length === 1) {
+        const req = approved[0];
+        report(0, "merging");
+        await mergeOne(0, req);
         return results;
     }
     // ── Assemble the stack in the shared `_merge` checkout: ONE check over the whole tree, and
     // on a red one, the largest passing prefix
     // The shared `_merge` checkout hosts every assembly and the attribution's baseline check:
-    // the drain is serial, so one checkout is enough, and no vet runs for a role while its
+    // the drain is serial, so one checkout is enough, and no verify runs for a role while its
     // change is being merged (plans/worktree-pool.md, part 2c).
     const wtPath = mergeWorktreePath(ctx.root);
-    const entries = vetted.map((req) => ({ role: req.role, sha: req.sha, summary: req.summary }));
+    const entries = approved.map((req) => ({ role: req.role, sha: req.sha, summary: req.summary }));
     let abandon = false;
-    // Every stacked change is landing now: they share the assembly, the check, and the ff.
-    for (let s = 0; s < vetted.length; s++)
-        report(s, "landing");
-    // Stack positions [0, landedCount) are on main. `suspect` is how many of the rest, from the
+    // Every stacked change is merging now: they share the assembly, the check, and the ff.
+    for (let s = 0; s < approved.length; s++)
+        report(s, "merging");
+    // Stack positions [0, mergeDoneCount) are on main. `suspect` is how many of the rest, from the
     // front, the last red check ran over — the prefix that still holds what broke it; null when
     // no red check stands against the rest, which are then tried together.
-    let landedCount = 0;
+    let mergeDoneCount = 0;
     let suspect = null;
-    while (landedCount < entries.length) {
-        const front = landedCount;
+    while (mergeDoneCount < entries.length) {
+        const front = mergeDoneCount;
         const size = suspect === null ? entries.length - front : suspect === 1 ? 1 : Math.floor(suspect / 2);
         const firstAttempt = front === 0 && suspect === null;
         let outcome;
         try {
-            outcome = await landStack(ctx, wtPath, entries.slice(front, front + size));
+            outcome = await mergeStack(ctx, wtPath, entries.slice(front, front + size));
             if (outcome.kind === "red" && size === 1) {
                 // The one change this red check ran over alone: attribute it, and leave every change
                 // after it unattempted for the next drain.
                 const { state } = wiringFor(entries[front].role);
                 const entry = entries[front];
-                await emit(front, await attributeRedCheck(ctx, entry.role, entry.sha, "batch check", outcome, state));
+                await emit(front, await attributeRedCheck(ctx, entry.role, entry.sha, "merge check", outcome, state));
                 report(front, "done");
                 break;
             }
         }
         catch (err) {
-            // The first attempt's plumbing propagates, as it always has — nothing has landed. A
+            // The first attempt's plumbing propagates, as it always has — nothing has merged. A
             // later step's degrades to "error" on the change at its front (ref kept for recovery),
             // the rest unattempted, so the prefixes already on main keep their "changed".
             if (firstAttempt)
@@ -210,13 +211,13 @@ export async function landVetted(ctx, vetted, wiringFor) {
             report(front, "done");
             break;
         }
-        if (outcome.kind === "landed") {
+        if (outcome.kind === "landed") { // vocabulary-ok: persisted state value or event type, renamed by a later series
             for (let s = front; s < front + size; s++) {
                 await emit(s, "changed");
                 report(s, "done");
             }
-            landedCount += size;
-            // The shared `_merge` checkout persists across merges, so a landed stack leaves it.
+            mergeDoneCount += size;
+            // The shared `_merge` checkout persists across merges, so a merged stack leaves it.
             // What broke the red run is still in its remainder, unless this prefix WAS that run —
             // then the red did not reproduce, and the rest are tried together.
             suspect = suspect !== null && suspect > size ? suspect - size : null;
@@ -230,8 +231,8 @@ export async function landVetted(ctx, vetted, wiringFor) {
         }
         else if (outcome.kind === "blocked") {
             // The race was lost on every attempt — main is moving faster than a check completes.
-            // Every change not yet landed keeps its ref with "merge_blocked": leftover recovery
-            // re-lands each through its own gate + tryMerge, whose in-lock check cannot lose it.
+            // Every change not yet merged keeps its ref with "merge_blocked": leftover recovery
+            // re-merges each through its own gate + tryMerge, whose in-lock check cannot lose it.
             for (let s = front; s < entries.length; s++)
                 await emit(s, "merge_blocked");
             break;
@@ -242,20 +243,20 @@ export async function landVetted(ctx, vetted, wiringFor) {
         }
     }
     if (abandon) {
-        // One-at-a-time through landApprovedChange, queue order, stopping at the first non-terminal
-        // outcome (the rest keep entry + ref for the next merge). Each request lands its approved
-        // head (the synced pin its vet judged, not the bare pin) — no second gate, so no model run:
+        // One-at-a-time through mergeApprovedChange, queue order, stopping at the first non-terminal
+        // outcome (the rest keep entry + ref for the next merge). Each request merges its approved
+        // head (the synced pin its verify judged, not the bare pin) — no second gate, so no model run:
         // re-gating would rebase onto the main the earlier entries just moved, and the rewritten
         // sha misses the approved short-circuit. main is never left red — mergeToMain's in-lock
-        // rebase + verifyLanding re-check every change whose tree differs from the one its vet
-        // judged. Only the change being landed reads `landing`; the rest are back to awaiting
-        // their turn, and each one landed is done.
-        for (let s = landedCount; s < vetted.length; s++)
-            report(s, "vetted");
-        for (let s = landedCount; s < vetted.length; s++) {
-            const req = vetted[s];
-            report(s, "landing");
-            await landOne(s, req);
+        // rebase + verifyMerge re-check every change whose tree differs from the one its verify
+        // judged. Only the change being merged reads `merging`; the rest are back to awaiting
+        // their turn, and each one merged is done.
+        for (let s = mergeDoneCount; s < approved.length; s++)
+            report(s, "approved");
+        for (let s = mergeDoneCount; s < approved.length; s++) {
+            const req = approved[s];
+            report(s, "merging");
+            await mergeOne(s, req);
             if (results[s] === "aborted")
                 aborted = true;
             report(s, "done");
@@ -265,7 +266,7 @@ export async function landVetted(ctx, vetted, wiringFor) {
     }
     // A change the merge stopped short of is out of it (its entry and ref wait for the next
     // merge, or an abort's write-back), so it must not keep a live row meanwhile.
-    for (let s = 0; s < vetted.length; s++) {
+    for (let s = 0; s < approved.length; s++) {
         if (results[s] === undefined)
             report(s, "done");
     }

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

@@ -1,53 +1,56 @@
+// vocabulary: plain
 import { deleteRef, headOf, patchId } from "../git/git.js";
-import { landingRefName } from "../paths.js";
+import { mergeRefName } from "../paths.js";
 import { recordReview } from "../tick/tick-apply.js";
 import { saveLoopState } from "../loop/loop-state.js";
 import { unverifiedTreeOutcome } from "../build/build-check-events.js";
-import { checkFailureReasons } from "../build/build-check-report.js";
+import { checkFailureReasons, describeCheck, failureHeadline } from "../build/build-check-report.js";
 import { mainTipVerdict } from "../baseline/main-red.js";
-import { logEventBestEffort } from "../events/events.js";
+import { logEventBestEffort, warnEventBestEffort } from "../events/events.js";
 import { mainRedNotMine } from "../text/phrases.js";
-/** Consecutive red in-lock landing checks of one patch (LoopState.landingCheckFailures) before
- * the landing is attributed instead of retried: the first red keeps the pin for one more
+import { normalizeClusterKey } from "../failure/failure-cluster.js";
+import { MERGE_FLAKY_WARNING_PREFIX, isKnownFlake } from "../review/known-flakes.js";
+/** Consecutive red in-lock merge checks of one patch (LoopState.mergeCheckFailures) before
+ * the merge is attributed instead of retried: the first red keeps the pin for one more
  * attempt — a load flake gets its retry, as the gate's pre-check gets one (PLANS.md land-queue
  * 1/3) — and the second is judged by main's own verdict at its tip (attributeRedCheck). Without
- * a limit a change whose gate passes but whose landing check fails (a cheaper check.gateCommand
+ * a limit a change whose gate passes but whose merge check fails (a cheaper check.gateCommand
  * than the full check) would re-queue as merge_blocked forever, its role never authoring. */
-export const LANDING_CHECK_FAILURE_LIMIT = 2;
-/** Whether a deterministic failure keeps its pin for one more re-land instead of being
+export const MERGE_CHECK_FAILURE_LIMIT = 2;
+/** Whether a deterministic failure keeps its pin for one more re-merge instead of being
  * attributed to the change: always when the patch-id could not be read (it cannot be matched
- * to a prior strike, so it never reaches LANDING_CHECK_FAILURE_LIMIT — the pre-cap behavior,
+ * to a prior strike, so it never reaches MERGE_CHECK_FAILURE_LIMIT — the pre-cap behavior,
  * never a wrong attribution), otherwise while the strike count is still under the limit. The
  * one home of that rule: tallyCheckFailure's strike store and keepPinOrAttribute's
  * keep-or-attribute branch both read it, so the two cannot disagree on when the limit is
  * reached. */
 function pinKept(patch, count) {
-    return patch === null || count < LANDING_CHECK_FAILURE_LIMIT;
+    return patch === null || count < MERGE_CHECK_FAILURE_LIMIT;
 }
 /** Tally one deterministic failure of the same patch toward attribution: read the worktree's
- * head and its patch-id against main, carry LoopState.landingCheckFailures's count across
- * re-lands of the identical patch (a clean rebase onto a moved main keeps the patch-id, so the
+ * head and its patch-id against main, carry LoopState.mergeCheckFailures's count across
+ * re-merges of the identical patch (a clean rebase onto a moved main keeps the patch-id, so the
  * retries of one change add up while a different change starts fresh), and store the strike.
  * An unreadable patch-id cannot be matched, so pinKept never counts it toward the limit.
  * Keeping the strike only under the limit (pinKept) is what ends the streak at attribution. */
 async function tallyCheckFailure(ctx, wt) {
     const head = await headOf(wt, "HEAD");
     const patch = await patchId(wt, ctx.mainBranch, head);
-    const prior = ctx.state.landingCheckFailures;
+    const prior = ctx.state.mergeCheckFailures;
     const count = (patch !== null && prior?.patchId === patch ? prior.count : 0) + 1;
     if (pinKept(patch, count)) {
-        ctx.state.landingCheckFailures = patch === null ? undefined : { patchId: patch, count };
+        ctx.state.mergeCheckFailures = patch === null ? undefined : { patchId: patch, count };
     }
     else {
-        ctx.state.landingCheckFailures = undefined;
+        ctx.state.mergeCheckFailures = undefined;
     }
     return { head, patch, count };
 }
-/** The shared re-land rule of the two deterministic-block paths below (landingCheckRed and
- * landingBlocked): tally the strike on this patch (tallyCheckFailure), then either keep the
+/** The shared re-merge rule of the two deterministic-block paths below (mergeCheckRed and
+ * mergeBlocked): tally the strike on this patch (tallyCheckFailure), then either keep the
  * pin for one more attempt — merge_blocked with `reason` named in lastError — or hand the head
  * to the caller's terminal sink `attribute`. Both paths decide keep-vs-attribute through
- * pinKept, so the LANDING_CHECK_FAILURE_LIMIT rule has one home. */
+ * pinKept, so the MERGE_CHECK_FAILURE_LIMIT rule has one home. */
 async function keepPinOrAttribute(ctx, wt, reason, attribute) {
     const { head, patch, count } = await tallyCheckFailure(ctx, wt);
     if (pinKept(patch, count)) {
@@ -56,9 +59,9 @@ async function keepPinOrAttribute(ctx, wt, reason, attribute) {
     }
     return attribute(head);
 }
-/** The terminal deterministic-reject sink shared by landingBlocked and attributeRedCheck:
+/** The terminal deterministic-reject sink shared by mergeBlocked and attributeRedCheck:
  * record the reject review, reset the unreviewed-failure streak, persist state, delete the
- * landing ref, and log review_rejected. The shared `_merge` checkout is left in place
+ * merge ref, and log review_rejected. The shared `_merge` checkout is left in place
  * (plans/worktree-pool.md, part 2c): it persists across merges like `_gate-main`, and a
  * rejection discards the pinned ref, not the checkout. Returns "rejected". review.ts's reject
  * path is a different sink — it resets the branch instead of deleting the ref — and keeps its
@@ -67,58 +70,92 @@ async function rejectChange(ctx, role, head, reasons, state) {
     recordReview(state, "reject", reasons, head);
     state.unreviewFailures = 0;
     saveLoopState(ctx.root, state);
-    await deleteRef(ctx.root, landingRefName(role));
-    logEventBestEffort(ctx.root, { loop: role, type: "review_rejected", head, reasons });
+    await deleteRef(ctx.root, mergeRefName(role));
+    logEventBestEffort(ctx.root, { source: role, type: "review_rejected", head, reasons });
     return "rejected";
 }
 /** The one-line reason a red check's lastError carries: checkFailureReasons' first entry (it
- * always returns at least one). Shared by the blocked-landing paths below — landingCheckRed's
+ * always returns at least one). Shared by the blocked-merge paths below — mergeCheckRed's
  * two branches and attributeRedCheck's unverified branch — so the "name the red by its first
  * reason" rule has one home while the full reason list stays where a whole review needs it
  * (attributeRedCheck's reject reasons). */
 function firstCheckReason(red) {
     return checkFailureReasons(red.check, red.outcome)[0];
 }
-/** A landing blocked because its in-lock check went red on the rebased tree (landing-merge.ts's
- * verifyLanding). The count is keyed by the patch-id; under LANDING_CHECK_FAILURE_LIMIT the
- * pin is kept (merge_blocked) for recovery's re-land; at the limit the red is attributed like
+/** A merge blocked because its in-lock check went red on the rebased tree (merge-to-main.ts's
+ * verifyMerge). The count is keyed by the patch-id; under MERGE_CHECK_FAILURE_LIMIT the
+ * pin is kept (merge_blocked) for recovery's re-merge; at the limit the red is attributed like
  * any single-change red. The other merge_blocked causes — a fast-forward that fails on a dirty
  * primary checkout, or main moving under the ff — are never the change's fault and never
  * counted. An unverified red made no verdict about the tree — the run spanned a host sleep
  * (BUGS.md 2026-09-30) — so it is not a strike against the patch: the pin stays for the next
  * attempt and the lastError names the sleep instead of a test failure. */
-export async function landingCheckRed(ctx, role, wt, red) {
+export async function mergeCheckRed(ctx, role, wt, red) {
     if (unverifiedTreeOutcome(red.outcome)) {
         ctx.state.lastError = `merge failed: ${firstCheckReason(red)}`;
         return "merge_blocked";
     }
-    return keepPinOrAttribute(ctx, wt, firstCheckReason(red), (head) => attributeRedCheck(ctx, role, head, "landing check", red, ctx.state));
+    const reason = firstCheckReason(red);
+    let attributed = false;
+    const result = await keepPinOrAttribute(ctx, wt, reason, (head) => {
+        attributed = true;
+        return attributeRedCheck(ctx, role, head, "merge check", red, ctx.state);
+    });
+    // The first red of a patch's in-lock check is exactly the retry that exists for load flakes,
+    // so it is the ONE signal that could name a flaky test after the fact — and lastError, the
+    // only place this reason is written, is overwritten by the leftover-recovery tick a second
+    // later (BUGS.md 2026-10-14). Log it as a warning so the failure digest and a later audit can
+    // name the flaky test; the second red at MERGE_CHECK_FAILURE_LIMIT is attributed through
+    // review_rejected, whose reasons are already durable.
+    if (result === "merge_blocked" && !attributed) {
+        warnEventBestEffort(ctx.root, role, `merge check failed (kept for one retry): ${reason}`);
+        if (ctx.state.mergeCheckFailures) {
+            ctx.state.mergeCheckFailures.headline = failureHeadline(red.outcome.outputTail) ?? describeCheck(red.check);
+        }
+    }
+    return result;
+}
+/** Record a merge check that failed and then passed on its kept-pin retry as a flake, in the
+ * form the gate's pre-check uses (MERGE_FLAKY_WARNING_PREFIX), so the gate's known-flake memory,
+ * doctor's `flaky checks` and the tick prompt's flake note count it (PLANS.md 2026-10-16). Reads
+ * the headline mergeCheckRed stored on the strike record only when its patch-id is the merged
+ * pin's (a stale strike of a discarded pin must not be logged); a pin that was never red (or
+ * only cross-check blocked) has none and logs nothing. Call before the strike is cleared. */
+export function noteMergeRetryPassed(ctx, role, pinPatch) {
+    const strike = ctx.state.mergeCheckFailures;
+    const headline = strike?.patchId === pinPatch ? strike?.headline : undefined;
+    if (headline)
+        warnEventBestEffort(ctx.root, role, MERGE_FLAKY_WARNING_PREFIX + headline);
 }
-/** A landing blocked by a deterministic cross-check (onLandingBlocked's fix-claim or
+/** A merge blocked by a deterministic cross-check (onMergeBlocked's fix-claim or
  * backlog-structure reason — a property of the tree ahead of main, not a flaky run). The
- * block is counted like a red landing check, keyed by the same patch-id: under
- * LANDING_CHECK_FAILURE_LIMIT the pin is kept for one recovery re-land — main may have moved
+ * block is counted like a red merge check, keyed by the same patch-id: under
+ * MERGE_CHECK_FAILURE_LIMIT the pin is kept for one recovery re-merge — main may have moved
  * under the rebase, and a differently-rebased tree can pass the cross-check — but at the
  * limit the block is attributed to the change: rejected deterministically with the block
  * reason, the pin deleted, no model run. Without this a resolution that trips the same
  * cross-check on every re-resolve pays a fresh conflict-resolver run each tick, forever
  * (BUGS.md 2026-10-02: five resolver sessions for one fix-claim-blocked pin). */
-export async function landingBlocked(ctx, role, wt, blocked) {
-    return keepPinOrAttribute(ctx, wt, blocked, (head) => rejectChange(ctx, role, head, [`landing blocked: ${blocked}`], ctx.state));
+export async function mergeBlocked(ctx, role, wt, blocked) {
+    return keepPinOrAttribute(ctx, wt, blocked, (head) => rejectChange(ctx, role, head, [`merge blocked: ${blocked}`], ctx.state));
 }
-/** Attribute a check that went red over ONE change's tree after its vet approved it — a batch
- * bisect's last step (landing-batch.ts), or a single landing's in-lock check at
- * LANDING_CHECK_FAILURE_LIMIT — by the gate's rule: ask main's own
- * verdict at its current tip (mainTipVerdict — usually a cache hit, since every landing seeds
+/** Attribute a check that went red over ONE change's tree after its verify approved it — a batch
+ * bisect's last step (merge-batch.ts), or a single merge's in-lock check at
+ * MERGE_CHECK_FAILURE_LIMIT — by the gate's rule: ask main's own
+ * verdict at its current tip (mainTipVerdict — usually a cache hit, since every merge seeds
  * the SHA it moved main to). Main green → the change broke the check: rejected deterministically
  * — reasons in lastReview for the author's next tick, the strike count reset, ref deleted,
  * review_rejected logged, no pi run. Main red → not this change's failure: "main_red" with the
- * ref kept and unreviewFailures untouched, so recovery re-lands it once main-red.ts's repair
+ * ref kept and unreviewFailures untouched, so recovery re-merges it once main-red.ts's repair
  * turns main green. No verdict → reject, the safe default, and the reasons say so. The verdict
- * is persisted before it returns. */
+ * is persisted before it returns. A red whose headline matches a flake the gate or a merge
+ * retry recorded (isKnownFlake) is excused once per headline per pin (LoopState.mergeFlakeExcused):
+ * "merge_blocked" with the ref kept, before main's verdict, because that verdict is usually a
+ * cached green that would reject a change over a flaky test (PLANS.md 2026-10-16, BUGS.md
+ * 2026-10-06). A repeat of the same headline is attributed as above. */
 export async function attributeRedCheck(ctx, role, head, label, red, state) {
     // An unverified red — a run that spanned a host sleep, the tree never judged — is not the
-    // change's failure and not a strike: keep the ref for recovery's re-land and name the sleep
+    // change's failure and not a strike: keep the ref for recovery's re-merge and name the sleep
     // (BUGS.md 2026-09-30). Main's own verdict is beside the point: the attribution question is
     // only live when the check produced a verdict.
     if (unverifiedTreeOutcome(red.outcome)) {
@@ -126,6 +163,15 @@ export async function attributeRedCheck(ctx, role, head, label, red, state) {
         saveLoopState(ctx.root, state);
         return "merge_blocked";
     }
+    const headline = failureHeadline(red.outcome.outputTail) ?? describeCheck(red.check);
+    const key = normalizeClusterKey(headline);
+    if (isKnownFlake(ctx.root, headline) && state.mergeFlakeExcused !== key) {
+        state.mergeFlakeExcused = key;
+        state.lastError = `${label} failed: known-flaky failure, merge kept: ${headline}`;
+        warnEventBestEffort(ctx.root, role, `${label}: known-flaky failure, merge kept: ${headline}`);
+        saveLoopState(ctx.root, state);
+        return "merge_blocked";
+    }
     const main = await mainTipVerdict(ctx.root, role, ctx.mainBranch, ctx.config);
     if (main.status === "red") {
         state.lastError = `${label} failed: ${mainRedNotMine(main.sha)}`;
@@ -134,7 +180,7 @@ export async function attributeRedCheck(ctx, role, head, label, red, state) {
     }
     const reasons = checkFailureReasons(red.check, red.outcome);
     if (main.status === "unavailable") {
-        reasons.push(`main's own baseline was unavailable (${main.why}), so the red ${label} is attributed to this change`);
+        reasons.push(`main's own baseline was unavailable (${main.why}), so the failed ${label} is attributed to this change`);
     }
     // Terminal rejection: the sink deletes the pin; the shared `_merge` checkout persists.
     return rejectChange(ctx, role, head, reasons, state);