tumwater 0.2.0 → 0.4.0

package/dist/src/merge/backlog-conflicts.js

@@ -7,35 +7,67 @@
  * for that shape has an empty base section and both sides non-empty; keeping both inserted sides
  * adds no authored bytes, so no model run is needed.
  *
- * One more shape settles the same way: inside a live `## Done`/`## Fixed` section, the change
- * added whole `### ` entries right above lines that main has since removed or rewritten — a
- * change committed before its repository's history moved to the archive, whose entries sat
- * right below the insertion point. The change's side is then its new entries followed by
- * exactly the base lines, and keeping those entries on top of main's side again adds no
- * authored bytes. Anything else — the same entry edited on both sides, a code file, a deleted
- * side — goes to the pi resolver untouched. */
+ * Two more shapes settle the same way:
+ * - Entries above a deleted entry, in any `## ` section: one side added whole `### ` entries
+ *   right above an entry the other side deleted. Typically the plan role prepends a plan on
+ *   main while the change finishes the plan below it into PLANS-DONE.md, or the other way
+ *   round. The inserting side is its new entries followed by exactly the base lines and the
+ *   deleting side is empty, so the new entries alone carry both sides' edits.
+ * - Entries above a rewritten history: inside a live `## Done`/`## Fixed` section, the change
+ *   added whole `### ` entries right above lines that main has since rewritten — a change
+ *   committed before its repository's history moved to the archive, whose entries sat right
+ *   below the insertion point. The change's side is then its new entries followed by exactly
+ *   the base lines, and keeping those entries on top of main's side again adds no authored
+ *   bytes.
+ * A fourth shape settles entry by entry instead of hunk by hunk (mergeBacklogEntries): each side
+ * finished or added different whole entries, so git's hunks cut through entries and match none
+ * of the shapes above. It reads the three index stages of PLANS.md, BUGS.md and QUESTIONS.md,
+ * not the hunks.
+ * Anything else — the same entry edited on both sides, a code file, a file one side deleted —
+ * goes to the pi resolver untouched. */
 import fs from "node:fs";
 import path from "node:path";
-import { BACKLOG_FILES, FINISHED_ARCHIVES } from "../backlog/backlog-md.js";
-import { writeTextAtomic } from "../files/files.js";
-import { git } from "../git/git-run.js";
-/** The lines the change inserted in `hunk`, when it is one of the two shapes this pass settles,
- * or null. Insert-only: an empty base section and both sides carrying lines — all of the
- * change's side. Entries above a rewritten history (see the module comment): the hunk sits in a
- * finished section, and the change's side is whole `### ` entries followed by exactly the base
- * lines — the part before them. */
-function insertedLines(hunk, lines) {
-    if (hunk.base.length === 0)
-        return hunk.ours.length > 0 && hunk.theirs.length > 0 ? hunk.theirs : null;
-    if (!inFinishedSection(lines, hunk.start) || hunk.theirs.length <= hunk.base.length)
+import { BACKLOG_FILES, FINISHED_ARCHIVES, fenceTracker } from "../backlog/backlog-md.js";
+import { readTextOrNull, writeTextAtomic } from "../files/files.js";
+import { git, gitTry } from "../git/git-run.js";
+/** The lines that replace `hunk`, when it is one of the shapes this pass settles (see the
+ * module comment), or null. Insert-only: an empty base section and both sides carrying lines —
+ * the change's side stacked on main's. Entries above a deleted entry: one side empty, the other
+ * whole `### ` entries followed by exactly the base lines — those entries alone. Entries above
+ * a rewritten history: the hunk sits in a finished section, and the change's side is whole
+ * `### ` entries followed by exactly the base lines — those entries stacked on main's side. */
+function settledLines(hunk, lines) {
+    if (hunk.base.length === 0) {
+        return hunk.ours.length > 0 && hunk.theirs.length > 0 ? stacked(hunk.theirs, hunk.ours) : null;
+    }
+    if (hunk.theirs.length === 0)
+        return entriesAboveBase(hunk.ours, hunk.base);
+    if (hunk.ours.length === 0)
+        return entriesAboveBase(hunk.theirs, hunk.base);
+    if (!inFinishedSection(lines, hunk.start))
+        return null;
+    const inserted = entriesAboveBase(hunk.theirs, hunk.base);
+    return inserted === null ? null : stacked(inserted, hunk.ours);
+}
+/** The lines `side` adds above the `base` lines, when `side` is whole `### ` entries followed
+ * by exactly those base lines, or null — a side no longer than the base, a base line changed or
+ * missing, or added lines that do not open at a `### ` heading. */
+function entriesAboveBase(side, base) {
+    if (side.length <= base.length)
         return null;
-    const cut = hunk.theirs.length - hunk.base.length;
-    if (hunk.theirs.slice(cut).some((line, i) => line !== hunk.base[i]))
+    const cut = side.length - base.length;
+    if (side.slice(cut).some((line, i) => line !== base[i]))
         return null;
-    const inserted = hunk.theirs.slice(0, cut);
+    const inserted = side.slice(0, cut);
     const first = inserted.find((line) => line.trim() !== "");
     return first?.startsWith("### ") ? inserted : null;
 }
+/** `upper` then `lower`, with a blank separator when neither already supplies one, so the
+ * later merge (the change, `upper`) stays first. */
+function stacked(upper, lower) {
+    const separated = lower.length === 0 || upper[upper.length - 1] === "" || lower[0] === "";
+    return separated ? [...upper, ...lower] : [...upper, "", ...lower];
+}
 /** True when the nearest `## ` heading above line `at` is a finished section (`## Done` or
  * `## Fixed`), with no conflict marker in between — an earlier hunk's sides leave the section
  * unknown, so the answer is then no. */
@@ -52,10 +84,8 @@ function inFinishedSection(lines, at) {
 /** The finished sections' titles, from FINISHED_ARCHIVES. */
 const FINISHED_SECTIONS = new Set(FINISHED_ARCHIVES.map((a) => a.section));
 /** Rewrite every settleable conflict hunk in `text` and return the result, or null when any
- * hunk is neither shape insertedLines accepts (or the markers are malformed) — the caller then
- * leaves the file for the model resolver. Each hunk is replaced by the lines the change (theirs)
- * inserted, a blank separator when neither side already supplies one, then main's (ours)
- * lines, so the later merge stays first. */
+ * hunk is no shape settledLines accepts (or the markers are malformed) — the caller then
+ * leaves the file for the model resolver. Each hunk is replaced by settledLines' lines. */
 export function resolveInsertOnlyText(text) {
     const lines = text.split("\n");
     const hunks = parseHunks(lines);
@@ -63,16 +93,13 @@ export function resolveInsertOnlyText(text) {
         return null;
     if (hunks.length === 0)
         return null;
-    const inserted = hunks.map((hunk) => insertedLines(hunk, lines));
-    if (inserted.some((ins) => ins === null))
+    const settled = hunks.map((hunk) => settledLines(hunk, lines));
+    if (settled.some((replacement) => replacement === null))
         return null;
     // Replace from the end so earlier indices stay valid.
     for (let h = hunks.length - 1; h >= 0; h--) {
         const hunk = hunks[h];
-        const theirs = inserted[h];
-        const separated = hunk.ours.length === 0 || theirs[theirs.length - 1] === "" || hunk.ours[0] === "";
-        const replacement = separated ? [...theirs, ...hunk.ours] : [...theirs, "", ...hunk.ours];
-        lines.splice(hunk.start, hunk.end - hunk.start + 1, ...replacement);
+        lines.splice(hunk.start, hunk.end - hunk.start + 1, ...settled[h]);
     }
     return lines.join("\n");
 }
@@ -117,6 +144,133 @@ function collectUntilMarker(lines, start, marker, into) {
         into.push(lines[i++]);
     return i >= lines.length ? null : i + 1;
 }
+/** Split `text` into ParsedBacklog blocks, or null when a fence is still open at EOF or a
+ * section holds two entries with the same heading line. */
+function parseBacklogBlocks(text) {
+    const fenced = fenceTracker();
+    const parsed = { preamble: "", sections: [] };
+    let current = [];
+    let flush = (block) => {
+        parsed.preamble = block;
+    };
+    const close = () => {
+        while (current.length > 0 && current[current.length - 1].trim() === "")
+            current.pop();
+        flush(current.join("\n"));
+        current = [];
+    };
+    for (const line of text.split("\n")) {
+        const structural = !fenced.inside(line);
+        if (structural && line.startsWith("## ")) {
+            close();
+            const section = { header: "", entries: [] };
+            parsed.sections.push(section);
+            flush = (block) => {
+                section.header = block;
+            };
+        }
+        else if (structural && line.startsWith("### ") && parsed.sections.length > 0) {
+            close();
+            const section = parsed.sections[parsed.sections.length - 1];
+            flush = (block) => section.entries.push({ key: line, text: block });
+            // The entry's heading line is `line` itself; the closure above captured it.
+        }
+        current.push(line);
+    }
+    if (fenced.open())
+        return null;
+    close();
+    for (const section of parsed.sections) {
+        if (new Set(section.entries.map((e) => e.key)).size !== section.entries.length)
+            return null;
+    }
+    return parsed;
+}
+/** The one text all three versions agree on after at most one side's edit: the changed side
+ * when only one changed, else the shared text, or null when both changed differently. */
+function settleBlock(base, ours, theirs) {
+    if (ours === theirs || theirs === base)
+        return ours;
+    return ours === base ? theirs : null;
+}
+/** Merge one section's entries (see mergeBacklogEntries), or null on a same-entry conflict. */
+function mergeSectionEntries(base, ours, theirs) {
+    const baseBy = new Map(base.map((e) => [e.key, e.text]));
+    const theirsBy = new Map(theirs.map((e) => [e.key, e.text]));
+    const oursKeys = new Set(ours.map((e) => e.key));
+    const result = [];
+    for (const { key, text: o } of ours) {
+        const b = baseBy.get(key);
+        const t = theirsBy.get(key);
+        if (b === undefined) {
+            if (t !== undefined && t !== o)
+                return null;
+            result.push({ key, text: o });
+        }
+        else if (t === undefined) {
+            if (o !== b)
+                return null; // main edited what the change deleted
+        }
+        else {
+            const settled = settleBlock(b, o, t);
+            if (settled === null)
+                return null;
+            result.push({ key, text: settled });
+        }
+    }
+    // An entry main deleted stays deleted, unless the change edited it.
+    for (const { key, text: b } of base) {
+        const t = theirsBy.get(key);
+        if (!oursKeys.has(key) && t !== undefined && t !== b)
+            return null;
+    }
+    for (let i = 0; i < theirs.length; i++) {
+        const added = theirs[i];
+        if (baseBy.has(added.key) || oursKeys.has(added.key))
+            continue;
+        let at = 0;
+        for (let j = i - 1; j >= 0; j--) {
+            const found = result.findIndex((e) => e.key === theirs[j].key);
+            if (found >= 0) {
+                at = found + 1;
+                break;
+            }
+        }
+        result.splice(at, 0, added);
+    }
+    return result;
+}
+/** Merge three versions of a backlog file entry by entry — `ours` is main, `theirs` the change —
+ * or null when that cannot be done without judgment: an open fence, a duplicate entry heading,
+ * differing `## ` heading sequences, a preamble or section header both sides changed, or the
+ * same entry edited on both sides (or edited by one side and deleted by the other). */
+export function mergeBacklogEntries(base, ours, theirs) {
+    const [b, o, t] = [base, ours, theirs].map(parseBacklogBlocks);
+    if (!b || !o || !t)
+        return null;
+    const count = b.sections.length;
+    if (o.sections.length !== count || t.sections.length !== count)
+        return null;
+    const blocks = [];
+    const preamble = settleBlock(b.preamble, o.preamble, t.preamble);
+    if (preamble === null)
+        return null;
+    if (preamble !== "")
+        blocks.push(preamble);
+    for (let i = 0; i < count; i++) {
+        const [bs, os, ts] = [b.sections[i], o.sections[i], t.sections[i]];
+        const heading = (header) => header.split("\n")[0];
+        if (heading(bs.header) !== heading(os.header) || heading(bs.header) !== heading(ts.header)) {
+            return null;
+        }
+        const header = settleBlock(bs.header, os.header, ts.header);
+        const entries = mergeSectionEntries(bs.entries, os.entries, ts.entries);
+        if (header === null || entries === null)
+            return null;
+        blocks.push(header, ...entries.map((e) => e.text));
+    }
+    return `${blocks.join("\n\n")}\n`;
+}
 /** Settle the insert-only conflicts among `files` in `wt` (plans/parallel-work-instances.md,
  * part 3/7): every conflicted repo-root backlog file (BACKLOG_FILES: PLANS.md, BUGS.md,
  * QUESTIONS.md and the two archive files) whose hunks all settle is rewritten without markers and
@@ -131,15 +285,29 @@ export async function resolveBacklogInsertConflicts(wt, files) {
             continue;
         }
         const p = path.join(wt, file);
-        let text;
+        // lstat, not stat: a symlink among the conflicted files is never followed out of the
+        // worktree (INV-G3 — a symlink holds no text of its own and its target could point out
+        // of it, so what a change that adds one put there is the link, not the target). Leaving
+        // it to the pi resolver keeps the same policy the conflict-marker and secret-leak gates
+        // pin: the resolver, like those gates, must not read an arbitrary host file.
+        let st;
         try {
-            text = fs.readFileSync(p, "utf8");
+            st = fs.lstatSync(p);
         }
         catch {
             remaining.push(file); // deleted side or unreadable path — leave it to the resolver
             continue;
         }
-        const resolved = resolveInsertOnlyText(text);
+        if (!st.isFile()) {
+            remaining.push(file); // symlink, directory or gitlink — leave it to the resolver
+            continue;
+        }
+        const text = readTextOrNull(p);
+        if (text === null) {
+            remaining.push(file); // deleted side or unreadable path — leave it to the resolver
+            continue;
+        }
+        const resolved = resolveInsertOnlyText(text) ?? (await mergeStagedEntries(wt, file));
         if (resolved === null) {
             remaining.push(file);
             continue;
@@ -153,3 +321,15 @@ export async function resolveBacklogInsertConflicts(wt, files) {
     }
     return remaining;
 }
+/** The entry-by-entry merge of `file`'s three index stages (1 base, 2 main, 3 the change), or
+ * null for an archive file, a stage missing on one side, or a merge needing judgment. */
+async function mergeStagedEntries(wt, file) {
+    if (FINISHED_ARCHIVES.some((a) => a.archive === file))
+        return null;
+    const base = await gitTry(wt, "show", `:1:${file}`);
+    const ours = await gitTry(wt, "show", `:2:${file}`);
+    const theirs = await gitTry(wt, "show", `:3:${file}`);
+    if (base === null || ours === null || theirs === null)
+        return null;
+    return mergeBacklogEntries(base, ours, theirs);
+}

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

@@ -1,4 +1,3 @@
-// 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
@@ -31,7 +30,7 @@ export async function verifyRequest(ctx, req, w) {
             purpose: "verify",
             ref: req.sha,
             signal: ctx.signal(),
-            // The live view's pool budget, same rule as the tick path: a broken tumwater.json
+            // The live view's pool budget, same rule as the run path: a broken tumwater.json
             // must not error the verify before its reviewer runs.
             slotBudget: slotCount(ctx.config),
         });
@@ -108,8 +107,10 @@ async function verifyRequestIn(ctx, req, w, wt) {
  * Un-assemblable (a cherry-pick conflict, on the first stack or any prefix) → ABANDON the changes
  * 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
- * merges re-verified in-lock whenever they differ from what their verify judged.
+ * resolver. main is not left red unchecked: the only bytes this path ff's are a checked tip or
+ * per-change merges re-verified in-lock whenever they differ from what their verify judged (the
+ * in-lock check is `check.mergeCommand` when set, and the main watch then runs the full check
+ * after the merge).
  *
  * 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 merge, so a stopping merge
@@ -136,6 +137,9 @@ export async function mergeApproved(ctx, approved, wiringFor) {
         runGatePi: (opts) => w.runGatePi(opts),
         foldUsage: w.foldUsage,
         signal: ctx.signal,
+        reviewHeld: ctx.reviewHeld,
+        reviewRetries: ctx.reviewRetries,
+        reviewRetryDelayMs: ctx.reviewRetryDelayMs,
     });
     let aborted = false;
     // Every finalized result goes through here: record it, then hand it to the caller's
@@ -230,7 +234,8 @@ export async function mergeApproved(ctx, approved, wiringFor) {
             break;
         }
         else if (outcome.kind === "blocked") {
-            // The race was lost on every attempt — main is moving faster than a check completes.
+            // The race was lost on every attempt (main is moving faster than a check completes), or
+            // the primary checkout holds files the stack changes (found before the check).
             // 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++)
@@ -247,10 +252,11 @@ export async function mergeApproved(ctx, approved, wiringFor) {
         // 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
+        // sha misses the approved short-circuit. main is not left red unchecked — mergeToMain's in-lock
         // 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.
+        // judged (with check.mergeCommand set, by that cheaper command; the main watch runs the full
+        // check after the merge). 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++) {

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

@@ -0,0 +1,53 @@
+/** Operator cancellation of a waiting merge (PLANS.md `tumwater queue --cancel <n>`), split
+ * out of merge-queue.ts so the queue stays the pure reader/writer it is: this module owns the
+ * destructive half of an unattempted entry — removing the queue file and deleting the role's
+ * merge pin so next-run leftover recovery cannot silently re-enqueue the change. It mirrors
+ * merge-requeue.ts (the other settled-entry editor living outside merge-queue.ts) and takes no
+ * lock: the queue is the inbox idiom (one file per entry, dropMerge tolerant of a concurrent
+ * drop) and the pin delete is value-guarded. */
+import { queuedMergeFiles, dropMerge } from "./merge-queue.js";
+import { mergeRefName } from "../paths.js";
+import { deleteRefIfAt } from "../git/git.js";
+import { logEventBestEffort } from "../events/events.js";
+/** Remove one readable queue entry: delete that role's merge pin first (deleteRefIfAt, a no-op
+ * when the ref is gone or names a different sha, so a newer pin is never removed), then drop
+ * the queue file (ENOENT already a no-op), logging one `merge_cancelled` event under the role,
+ * and return the `cancelled` outcome naming what was removed. The single removal both
+ * `cancelQueuedMerge` (by position) and `cancelQueuedMergeBySha` (by sha) share, so the CLI and
+ * the dashboard's queue-cancel cannot drift on what cancelling means. */
+async function removeQueuedEntry(root, target) {
+    await deleteRefIfAt(root, mergeRefName(target.entry.role), target.entry.sha);
+    dropMerge(target.file);
+    logEventBestEffort(root, {
+        source: target.entry.role,
+        type: "merge_cancelled",
+        commit: target.entry.sha,
+        summary: target.entry.summary,
+    });
+    return { status: "cancelled", role: target.entry.role, sha: target.entry.sha, summary: target.entry.summary };
+}
+/** Remove the Nth queued merge — 1-based, as `tumwater queue` numbers it — and delete that
+ * entry's role's merge pin, so next-run leftover recovery finds no pin and no branch-ahead
+ * commit and does not re-enqueue the change. `position` is resolved against
+ * `queuedMergeFiles` (the same readable, filename-ordered list the queue renderer shows), so
+ * the position matches the line `tumwater queue` printed. The pin is deleted first with
+ * deleteRefIfAt (a no-op when the ref is gone or names a different sha, so a newer pin is
+ * never removed), then the queue file is dropped (ENOENT already a no-op). Logs one
+ * `merge_cancelled` event under the role. Out-of-range changes nothing and returns the
+ * current readable depth. */
+export async function cancelQueuedMerge(root, position) {
+    const files = queuedMergeFiles(root);
+    if (position < 1 || position > files.length)
+        return { status: "out-of-range", depth: files.length };
+    return removeQueuedEntry(root, files[position - 1]);
+}
+/** Remove the queued merge whose entry's pinned sha is `sha` (the browser twin of
+ * `tumwater queue --cancel <n>`, resolving by sha because the dashboard rows carry one). An
+ * entry whose sha matches none is `{ status: "gone" }` and changes nothing; otherwise it runs
+ * the same `removeQueuedEntry` the position variant uses. */
+export async function cancelQueuedMergeBySha(root, sha) {
+    const target = queuedMergeFiles(root).find((q) => q.entry.sha.toLowerCase() === sha.toLowerCase());
+    if (!target)
+        return { status: "gone" };
+    return removeQueuedEntry(root, target);
+}

package/dist/src/merge/merge-check-failures.js

@@ -1,16 +1,16 @@
-// vocabulary: plain
 import { deleteRef, headOf, patchId } from "../git/git.js";
 import { mergeRefName } from "../paths.js";
-import { recordReview } from "../tick/tick-apply.js";
-import { saveLoopState } from "../loop/loop-state.js";
+import { recordReview } from "../run/run-apply.js";
+import { saveRunnerStateBestEffort } from "../runner/runner-state.js";
 import { unverifiedTreeOutcome } from "../build/build-check-events.js";
 import { checkFailureReasons, describeCheck, failureHeadline } from "../build/build-check-report.js";
+import { onlyKnownMainFailures } from "../baseline/main-watch.js";
 import { mainTipVerdict } from "../baseline/main-red.js";
 import { logEventBestEffort, warnEventBestEffort } from "../events/events.js";
 import { mainRedNotMine } from "../text/phrases.js";
 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
+/** Consecutive red in-lock merge checks of one patch (RunnerState.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
@@ -28,7 +28,7 @@ function pinKept(patch, count) {
     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.mergeCheckFailures's count across
+ * head and its patch-id against main, carry RunnerState.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.
@@ -60,8 +60,9 @@ async function keepPinOrAttribute(ctx, wt, reason, attribute) {
     return attribute(head);
 }
 /** The terminal deterministic-reject sink shared by mergeBlocked and attributeRedCheck:
- * record the reject review, reset the unreviewed-failure streak, persist state, delete the
- * merge ref, and log review_rejected. The shared `_merge` checkout is left in place
+ * record the reject review, reset the unreviewed-failure streak, persist state best-effort
+ * (a failed save warns; the merge write-back saves the same state later), delete the merge
+ * ref, and log review_rejected, even on a full disk. 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
@@ -69,7 +70,7 @@ async function keepPinOrAttribute(ctx, wt, reason, attribute) {
 async function rejectChange(ctx, role, head, reasons, state) {
     recordReview(state, "reject", reasons, head);
     state.unreviewFailures = 0;
-    saveLoopState(ctx.root, state);
+    saveRunnerStateBestEffort(ctx.root, state);
     await deleteRef(ctx.root, mergeRefName(role));
     logEventBestEffort(ctx.root, { source: role, type: "review_rejected", head, reasons });
     return "rejected";
@@ -82,6 +83,18 @@ async function rejectChange(ctx, role, head, reasons, state) {
 function firstCheckReason(red) {
     return checkFailureReasons(red.check, red.outcome)[0];
 }
+/** Keep the pin when a red check fails only main's known failures (onlyKnownMainFailures): not
+ * the change's failure and not a strike, so recovery's re-merge — whose verifyMerge lets such a
+ * check through — lands it. Null when the red names a test outside the known set. */
+function keepForKnownFailures(ctx, role, label, red, state) {
+    const known = onlyKnownMainFailures(ctx.root, red.outcome.failingTests);
+    if (!known)
+        return null;
+    state.lastError = `${label} failed only main's known failures, merge kept: ${known.join(", ")}`;
+    warnEventBestEffort(ctx.root, role, `${label} fails only main's known failures: ${known.join(", ")}`);
+    saveRunnerStateBestEffort(ctx.root, state);
+    return "merge_blocked";
+}
 /** 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
@@ -95,6 +108,9 @@ export async function mergeCheckRed(ctx, role, wt, red) {
         ctx.state.lastError = `merge failed: ${firstCheckReason(red)}`;
         return "merge_blocked";
     }
+    const kept = keepForKnownFailures(ctx, role, "merge check", red, ctx.state);
+    if (kept)
+        return kept;
     const reason = firstCheckReason(red);
     let attributed = false;
     const result = await keepPinOrAttribute(ctx, wt, reason, (head) => {
@@ -103,7 +119,7 @@ export async function mergeCheckRed(ctx, role, wt, red) {
     });
     // 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
+    // only place this reason is written, is overwritten by the leftover-recovery run 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.
@@ -117,7 +133,7 @@ export async function mergeCheckRed(ctx, role, wt, red) {
 }
 /** 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
+ * doctor's `flaky checks` and the run 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. */
@@ -134,7 +150,7 @@ export function noteMergeRetryPassed(ctx, role, pinPatch) {
  * 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
+ * cross-check on every re-resolve pays a fresh conflict-resolver run each run, forever
  * (BUGS.md 2026-10-02: five resolver sessions for one fix-claim-blocked pin). */
 export async function mergeBlocked(ctx, role, wt, blocked) {
     return keepPinOrAttribute(ctx, wt, blocked, (head) => rejectChange(ctx, role, head, [`merge blocked: ${blocked}`], ctx.state));
@@ -144,15 +160,18 @@ export async function mergeBlocked(ctx, role, wt, blocked) {
  * 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,
+ * — reasons in lastReview for the author's next run, 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-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. 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. */
+ * ref kept and unreviewFailures untouched, so the orchestrator poll (requeueMainRedPin) re-queues
+ * it once main's head moves to one the watch has not found red, and leftover recovery holds it
+ * until then. No verdict → reject, the
+ * safe default, and the reasons say so. The verdict
+ * is persisted best-effort 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
+ * (RunnerState.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-merge and name the sleep
@@ -160,22 +179,25 @@ export async function attributeRedCheck(ctx, role, head, label, red, state) {
     // only live when the check produced a verdict.
     if (unverifiedTreeOutcome(red.outcome)) {
         state.lastError = `${label}: ${firstCheckReason(red)}`;
-        saveLoopState(ctx.root, state);
+        saveRunnerStateBestEffort(ctx.root, state);
         return "merge_blocked";
     }
+    const kept = keepForKnownFailures(ctx, role, label, red, state);
+    if (kept)
+        return kept;
     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);
+        saveRunnerStateBestEffort(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)}`;
-        saveLoopState(ctx.root, state);
+        saveRunnerStateBestEffort(ctx.root, state);
         return "main_red";
     }
     const reasons = checkFailureReasons(red.check, red.outcome);