tumwater 0.1.2 → 0.2.0

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

@@ -6,12 +6,13 @@ import { currentBranch, gitLines, headOf } from "../git/git.js";
 import { unquotePorcelainPath } from "../git/git-diff.js";
 import { CONFIG_BASENAME, configPath, primaryWorktreeLockPath } from "../paths.js";
 import { withStateLockAsync } from "../concurrency/lock.js";
-/** Git plumbing for the landing flow: rebasing a worktree branch onto main, inspecting and
- * finishing a conflicted rebase, and fast-forwarding main — the mechanics, with no landing policy
- * of their own. Landing policy (lock → rebase → verify → ff, conflict resolution, batch ff)
- * lives in landing-merge.ts on top of these. Moved here from landing-merge.ts: the cluster started
- * as landing-merge.ts-only helpers (organize tick 78, moving them out of git/git.ts), but the
- * lander and the batch lander grew to call them directly, leaving landing-merge.ts exporting
+import { errorMessage } from "../text/text.js";
+/** Git plumbing for the merge flow: rebasing a worktree branch onto main, inspecting and
+ * finishing a conflicted rebase, and fast-forwarding main — the mechanics, with no merge policy
+ * of their own. Merge policy (lock → rebase → verify → ff, conflict resolution, batch ff)
+ * lives in merge-to-main.ts on top of these. Moved here from merge-to-main.ts: the cluster started
+ * as merge-to-main.ts-only helpers (organize tick 78, moving them out of git/git.ts), but the
+ * merger and the batch merger grew to call them directly, leaving merge-to-main.ts exporting
  * generic rebase/ff plumbing that had nothing to do with merging. */
 /** Paths currently in conflict (unmerged) in the worktree. C-quoted names are decoded to
  * real paths — a non-ASCII conflicted file arrives as `"h\303\251llo.ts"` (core.quotePath is on
@@ -60,7 +61,7 @@ export async function mainCommitsTouching(wt, since, mainBranch, files) {
  * cleaning up: "rebased" (including already up to date), "conflict" (the rebase stopped on
  * unmerged paths, which remain in the worktree for a resolver), or "other" (any other
  * failure). Shared by the two rebase wrappers below, which differ only in cleanup policy.
- * Rebase — not merge — keeps main's history linear: each tick lands as its own commit on top
+ * Rebase — not merge — keeps main's history linear: each tick merges as its own commit on top
  * of whatever main holds. */
 async function attemptRebase(wt, mainBranch) {
     try {
@@ -93,6 +94,10 @@ export async function rebaseOntoMainLeaveConflicts(wt, mainBranch) {
         await gitTry(wt, "rebase", "--abort");
     return state === "rebased" ? "clean" : state === "conflict" ? "conflict" : "failed";
 }
+/** A conflict block's start or end marker line: seven `<` or `>`, then a space or the line's end.
+ * The one marker definition hasConflictMarkers and conflictHunkRanges share, so the ranges a
+ * conflict prompt names are exactly the blocks the marker check later rejects. */
+const MARKER_EDGE = /^(<{7}|>{7})( |$)/m;
 /** True if any of the given files still contains a git conflict marker.
  * A deleted file counts as resolved (the resolver chose the deletion). */
 export function hasConflictMarkers(wt, files) {
@@ -101,21 +106,65 @@ export function hasConflictMarkers(wt, files) {
     // characters), and flagging it would reject clean resolutions forever. A resolver that
     // leaves only a separator line behind is treated as resolved; its stray line is content the
     // project's own tests can catch.
-    const marker = /^(<{7}|>{7})( |$)/m;
     return files.some((f) => {
         const p = path.join(wt, f);
         try {
-            return marker.test(fs.readFileSync(p, "utf8"));
+            return MARKER_EDGE.test(fs.readFileSync(p, "utf8"));
         }
         catch {
             return false;
         }
     });
 }
+/** How many conflict hunks a conflict prompt lists per file: every hunk of a typical backlog or
+ * code conflict, and a bound on a file pasted over wholesale. */
+export const MAX_LISTED_HUNKS = 10;
+/** The 1-based inclusive line ranges of the conflict hunks in `text`, each from a start marker
+ * line through the next end marker line. Markers are matched by line prefix alone, so a hunk
+ * inside a markdown code fence counts too: git writes its markers wherever the conflict falls.
+ * A second start marker inside an open hunk stays part of it, and an unterminated hunk runs to
+ * the last line. */
+export function conflictHunkRanges(text) {
+    const lines = text.split("\n");
+    const ranges = [];
+    let start;
+    lines.forEach((line, i) => {
+        if (!MARKER_EDGE.test(line))
+            return;
+        if (line.startsWith("<"))
+            start ??= i + 1;
+        else if (start !== undefined) {
+            ranges.push({ start, end: i + 1 });
+            start = undefined;
+        }
+    });
+    const lastLine = text.endsWith("\n") ? lines.length - 1 : lines.length;
+    if (start !== undefined)
+        ranges.push({ start, end: lastLine });
+    return ranges;
+}
+/** Each of `files` (repo-relative, under `wt`) with its conflict hunks' line ranges, for the
+ * conflict prompts to name, so whoever resolves them reads the hunks instead of opening the file
+ * from line 1. Over 2026-10-17..19 the merge's conflict resolvers spent 2.0M chars reading the
+ * conflicted PLANS.md from its top, 16-47K chars a read because its lines are long. Any text
+ * file counts, backlog or code; a deleted, unreadable or binary (NUL-bearing) file lists none. */
+export function conflictedFileHunks(wt, files) {
+    return files.map((f) => {
+        let text = "";
+        try {
+            text = fs.readFileSync(path.join(wt, f), "utf8");
+        }
+        catch {
+            // Deleted or unreadable: no ranges to name.
+        }
+        const all = text.includes("\0") ? [] : conflictHunkRanges(text);
+        return { path: f, hunks: all.slice(0, MAX_LISTED_HUNKS), more: Math.max(0, all.length - MAX_LISTED_HUNKS) };
+    });
+}
 /** The reason naming every changed file that still carries a conflict marker, or undefined when
  * none do — the one home of the wording, shared by the stage check's pre-queue finding
  * (stage-check.ts) and the review gate's hard rejection (review.ts), so the two surfaces cannot
- * name the same leftover marker differently. Committing or landing one would put raw `<<<<<<<`
+ * name the same leftover marker differently. Committing or merge one would put raw `<<<<<<<`
  * lines on main (PLANS.md "Robust conflict landing, part 2/2"). Builds on hasConflictMarkers
  * above, the shared definition of what a marker is. */
 export function conflictMarkerReason(wt, files) {
@@ -126,14 +175,14 @@ export function conflictMarkerReason(wt, files) {
  * GIT_EDITOR=true so `rebase --continue` can never block on a commit-message prompt. A
  * resolution that leaves no unique content (the branch's change was fully superseded by
  * main) is skipped automatically by git, finishing the rebase cleanly. Throws when the
- * rebase stops again — e.g. on a second conflict from an extra commit pi authored during
- * the tick; the caller aborts and reports merge_conflict. */
+ * rebase stops again — e.g. on a second conflict from a later commit the resolution run
+ * added; the caller aborts and reports merge_conflict. */
 export async function continueRebase(wt) {
     await git(wt, "add", "-A");
     await runGit(wt, [...COMMIT_IDENT, "rebase", "--continue"], { GIT_EDITOR: "true" });
     return headOf(wt, "HEAD");
 }
-/** The live config's bytes, when the landing about to fast-forward `ref` would delete it
+/** The live config's bytes, when the merge about to fast-forward `ref` would delete it
  * (plans/portability.md §4b/7): the config file exists, is tracked in the current index (and
  * HEAD — a staged-or-dirty config makes `git merge --ff-only` refuse below, so the two agree
  * on every merge that can succeed), and is absent from the incoming tree. Anything else —
@@ -168,24 +217,48 @@ export function restoreConfigBytes(root, saved) {
  * post-rebase HEAD — a bare sha, which both arms accept (`merge --ff-only <sha>` and
  * `push . <sha>:<main>`). Uses a working-tree merge when the primary checkout is on main (so its
  * files update), otherwise a local ref push. Returns true on success. The working-tree arm
- * preserves the live config across a landing that untracks it (plans/portability.md §4b/7):
- * without the write-back, the commit that removes the tracked config would delete the fleet's
+ * preserves the live config across a merge that untracks it (plans/portability.md §4b/7):
+ * without the write-back, the commit that removes the tracked config would delete the team's
  * running config out from under it and the next config poll would fall back to defaults. */
-export async function ffMainTo(root, ref, mainBranch) {
+export async function ffMainToOrWhy(root, ref, mainBranch) {
     const primaryBranch = await currentBranch(root);
     if (primaryBranch === mainBranch) {
         // The working-tree arm rewrites the same tracked files the CLI backlog writers read and
         // rewrite, so it shares their primary-worktree lock (paths.ts): without it a `tumwater bug`
-        // that read before this merge can rename its stale whole-file write over the landed change.
+        // that read before this merge can rename its stale whole-file write over the merged change.
         // The ref-push arm below touches no working tree and needs no lock; the save/merge/restore
         // stays one short section, never held across a build re-check.
         return withStateLockAsync(primaryWorktreeLockPath(root), async () => {
             const saved = await configBytesToPreserve(root, ref);
-            if ((await gitTry(root, "merge", "--ff-only", ref)) === null)
-                return false;
+            try {
+                await git(root, "merge", "--ff-only", ref);
+            }
+            catch (err) {
+                return ffFailureReason(root, ref, mainBranch, err);
+            }
             restoreConfigBytes(root, saved);
-            return true;
+            return null;
         });
     }
-    return (await gitTry(root, "push", ".", `${ref}:${mainBranch}`)) !== null;
+    try {
+        await git(root, "push", ".", `${ref}:${mainBranch}`);
+        return null;
+    }
+    catch (err) {
+        return ffFailureReason(root, ref, mainBranch, err);
+    }
+}
+/** Why a fast-forward to `ref` failed: main having moved off `ref`'s base (a commit that did not
+ * take the merge lock) is named with its new head and subject; any other cause reports git's own
+ * error, e.g. a dirty primary checkout. */
+async function ffFailureReason(root, ref, mainBranch, err) {
+    if ((await gitTry(root, "merge-base", "--is-ancestor", mainBranch, ref)) === null) {
+        const now = await gitTry(root, "log", "-1", "--format=%h %s", mainBranch);
+        return `main moved outside the merge lock (now ${now?.trim() ?? mainBranch})`;
+    }
+    return `fast-forward failed: ${errorMessage(err).trim().split("\n")[0]}`;
+}
+/** Boolean form of ffMainToOrWhy for callers that need no reason. */
+export async function ffMainTo(root, ref, mainBranch) {
+    return (await ffMainToOrWhy(root, ref, mainBranch)) === null;
 }

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

@@ -0,0 +1,99 @@
+import { runOnAbort } from "../process/process.js";
+import { warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
+import { errorMessage } from "../text/text.js";
+import { deleteRef } from "../git/git.js";
+import { removeMergeChange, writeMergeOutcome } from "./merge-slot.js";
+import { mergeRefName, rejectedRefName } from "../paths.js";
+/** A fresh pipeline: nothing in flight anywhere — no verification running, no approved change
+ * waiting, no merge holding main. The orchestrator builds one per team start (orchestrator.ts). */
+export function newMergePipeline() {
+    return { verifying: new Map(), approved: new Map(), merge: null };
+}
+/** Every merge task in flight — each verification holding its permit, and the merge — for the
+ * shutdown and restart waits. A parked verification is not one of them: it has started nothing, and
+ * a shutdown (its controller) or a closed start gate (at its grant) settles it without a run. */
+export function mergeTasks(p) {
+    return [...[...p.verifying.values()].filter((v) => !v.parked), ...(p.merge ? [p.merge] : [])];
+}
+/** Everything `tumwater abort --role` can reach: every task in flight, plus each approved change
+ * waiting with no task of its own. A parked verification is out of reach, as a plainly queued entry
+ * always was: its change has not started merging. */
+export function abortableMerges(p) {
+    return [...mergeTasks(p), ...p.approved.values()];
+}
+/** Wire harness shutdown to one task's own controller — through the shared register/abort
+ * race helper, so an already-fired signal aborts at once. Returns the detach function. The
+ * team shutdown signal outlives every merge, so each task that settles while the signal is
+ * still live must detach in its own finally; without that, the one long-lived signal
+ * accumulates a listener (and the retained controller behind it) for every merge the team
+ * ever runs, growing without bound until the shutdown it was waiting for. */
+export function abortOnShutdown(signal, controller) {
+    return runOnAbort(signal, () => controller.abort());
+}
+/** Wrap a merge task's stored promise so it can never reject: the tasks are fire-and-forget
+ * during normal operation (only the shutdown/restart drain awaits them), and an unexpected
+ * throw out of their bookkeeping — an unwritable state file, event feed, or marker while
+ * settling an outcome — would otherwise surface as an unhandled rejection and take the
+ * orchestrator down. The throw is reported best-effort; the task's own finally has already
+ * released its slot and controller, and the surviving queue entry and pin recover on the next
+ * poll. */
+export function guardMergeTask(root, role, promise) {
+    return promise.catch((err) => {
+        warnEventBestEffort(root, TUMWATER_SOURCE, `merge task for ${role} could not settle: ${errorMessage(err)}`);
+    });
+}
+/** Take a permit at `tier` (on `key` when given) unless `signal` fires first: resolves to its
+ * release, or to null when the signal won — a grant that arrives after that is handed straight
+ * back (a hop, never a leak), so a parked verification that a shutdown settles holds nothing. When
+ * `key` is set the permit is a keyed lease, so the verification also counts against its provider's
+ * cap (plans/provider-concurrency.md §4). */
+export async function acquireUnlessAborted(semaphore, tier, signal, key) {
+    if (signal.aborted)
+        return null;
+    const granted = semaphore.acquireLease(tier, key);
+    const stopped = new Promise((resolve) => signal.addEventListener("abort", () => resolve(false), { once: true }));
+    if (await Promise.race([granted, stopped])) {
+        return granted;
+    }
+    void granted.then((lease) => lease.release());
+    return null;
+}
+/** The roles the pipeline holds right now — verifying (parked or not), approved, or merging. */
+export function liveRoles(p) {
+    return new Set([...p.verifying.keys(), ...p.approved.keys(), ...(p.merge?.roles ?? [])]);
+}
+/** Discard the pinned merge refs of every role in a deliberately-aborted merge.
+ * `tumwater abort --role` throws the committed work away, and the pin is what would otherwise
+ * recover it, so the ref must go; a shutdown abort leaves `userAborted` unset and every ref
+ * survives for recovery. Shared by every task's settling code so their discard semantics
+ * cannot drift. A ref that is already gone is not an error. */
+export async function discardPinnedRefs(root, roles) {
+    for (const role of roles) {
+        try {
+            await deleteRef(root, mergeRefName(role));
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}
+/** Settle a merge queue entry that reached a terminal outcome — the one home of the
+ * write-plus-drop pairing every settled merge goes through: the result lands in the role's
+ * state and the merge_done/merge_failed event (writeMergeOutcome), then the change's marker
+ * record is dropped (removeMergeChange — merge-slot leaves the marker to the caller). Shared by
+ * settleAbortedApproved, the verification's final-verdict branch, and the merge's per-change
+ * write-back, so no settled entry can keep a stale marker or lose its outcome write. The pinned-ref
+ * discard stays with the callers: only a user abort throws work away, and the merge discards its
+ * whole stack at once rather than change by change. */
+export async function settleMergeOutcome(root, entry, state, result, durationMs, usage, file) {
+    writeMergeOutcome(root, entry, state, result, durationMs, usage, file);
+    // A revision that merges ends the rejected change's life: drop the rejected ref (plans/revise-
+    // rejected.md). A rejection repoints or deletes it in merge-core.ts, so this is the only
+    // ref cleanup a merged revision needs here. Guarded on the entry's revisionRound, not just a
+    // `changed` result: a fresh change can merge while a different rejection's revision is still
+    // pending, and its merge must leave that pending revision's ref alone.
+    if (result === "changed" && entry.revisionRound !== undefined) {
+        await deleteRef(root, rejectedRefName(entry.role));
+    }
+    removeMergeChange(root, entry.role);
+}

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

@@ -1,16 +1,19 @@
 import { openQuestions } from "../backlog/backlog.js";
 import { logEventBestEffort } from "../events/events.js";
 /** Emit one `question_posted` event per entry QUESTIONS.md's ## Open gained since `before` —
- * the capture-and-diff both merge paths record alongside their `merged` events (landing-merge.ts's
- * tryMerge and landing-stack.ts's ffStackToMain). The capture (`openQuestions(root)` under the
+ * the capture-and-diff both merge paths record alongside their `merged` events (merge-to-main.ts's
+ * tryMerge and merge-stack.ts's ffStackToMain). The capture (`openQuestions(root)` under the
  * merge lock, before the ff) stays with the callers: the lock window is theirs to define, and the
  * diff is only exact while the capture and this call share it. Best-effort: the questions have
  * already been posted to QUESTIONS.md and main already fast-forwarded, so an unwritable feed
- * must not reject the landing around it (landing-merge.ts's tryMerge, landing-stack.ts). */
+ * must not reject the merge around it. `position` is the entry's 1-based place in ## Open (the
+ * `<n>` `tumwater questions answer` takes now) and `open` is the list's length, so the page can
+ * name the answering command (merge-to-main.ts's tryMerge, merge-stack.ts). */
 export function logNewQuestions(root, before, role) {
-    for (const question of openQuestions(root)) {
+    const titles = openQuestions(root);
+    titles.forEach((question, index) => {
         if (!before.includes(question)) {
-            logEventBestEffort(root, { loop: role, type: "question_posted", question });
+            logEventBestEffort(root, { source: role, type: "question_posted", question, position: index + 1, open: titles.length });
         }
-    }
+    });
 }

package/dist/src/merge/merge-queue-render.js

@@ -0,0 +1,75 @@
+// vocabulary: plain
+/** The renderer behind `tumwater queue` — the operator-facing text for the merge queue view the
+ * reader gathers (merge-queue.ts's readMergeQueue, beside it): one line per queued merge
+ * in execution order, plus the count of queue files the reader skipped. Pure function of the
+ * collected view and a `now` instant — no I/O, no clock reads — so the age it prints can be
+ * pinned by a test. */
+import { humanSeconds, secondsSince } from "../text/datetime.js";
+import { roleLabel } from "../roles/role-labels.js";
+import { shortSha } from "../text/format.js";
+import { plural } from "../text/phrases.js";
+import { mergeChanges, MERGE_STAGE_LABELS } from "./merge-slot.js";
+/** The bracketed-label text for one queue entry, in the wording the loop rows use (status-model's
+ * loopPhase): `merge <elapsed> · <stage>` while a verify or the merge holds the change,
+ * `approved, awaiting merge` once approved, and "" when the marker is absent, names no record for
+ * `sha`, or the record is `done`. Reads the marker through mergeChanges, so an older-generation
+ * single-change marker counts as one `merge` record. */
+export function queueEntryMergeLabel(sha, inFlight, now) {
+    if (!inFlight)
+        return "";
+    const change = mergeChanges(inFlight).find((c) => c.sha === sha);
+    if (!change || change.status === "done")
+        return "";
+    if (change.status === "approved")
+        return "approved, waiting to merge";
+    let label = "merging";
+    if (change.startedAt)
+        label += ` ${humanSeconds(secondsSince(change.startedAt, now))}`;
+    if (change.stage)
+        label += ` · ${MERGE_STAGE_LABELS[change.stage]}`;
+    if (change.stageSince !== undefined)
+        label += ` ${humanSeconds(secondsSince(change.stageSince, now))}`;
+    return label;
+}
+/** One re-submitted change's revision note (plans/revise-rejected.md): `revision <round>`,
+ * plus ` · <n> prior objection(s)` when the change answered any prior review objections
+ * (its `priorReview.reasons`). "" for a fresh change with no revision-round field, so a
+ * first submission's queue line is byte-identical to before. */
+export function revisionNote(entry) {
+    if (entry.revisionRound === undefined)
+        return "";
+    let note = "revision " + entry.revisionRound;
+    const reasons = entry.priorReview?.reasons;
+    if (Array.isArray(reasons) && reasons.length > 0)
+        note += " · " + plural(reasons.length, "prior objection");
+    return note;
+}
+/** Render the queue as the text `tumwater queue` prints: a `merge queue (<depth>):` header then
+ * one 1-based line per readable entry, oldest first, carrying the loop, tick number, short
+ * pinned sha, age, and summary. An empty queue (no entries and nothing skipped) prints
+ * `merge queue empty`; a non-zero skip count appends one `(+N unreadable queue file(s) skipped)`
+ * line so a torn or foreign file the reader dropped is visible rather than silent. An entry the
+ * optional in-flight marker has a live record for carries ` · [<label>]` after its age
+ * (queueEntryMergeLabel). */
+export function renderMergeQueue(view, now, inFlight) {
+    const depth = view.entries.length + view.unreadable;
+    const lines = [];
+    if (depth === 0) {
+        lines.push("merge queue empty");
+    }
+    else {
+        lines.push(`merge queue (${depth}):`);
+        view.entries.forEach((e, i) => {
+            const age = humanSeconds(secondsSince(e.enqueuedAt, now));
+            const label = queueEntryMergeLabel(e.sha, inFlight, now);
+            const tag = label ? ` · [${label}]` : "";
+            const note = revisionNote(e);
+            const noteTag = note ? ` · ${note}` : "";
+            lines.push(`  ${i + 1}. ${roleLabel(e.role)} run #${e.run} · ${shortSha(e.sha)} · ${age} ago${tag}${noteTag} · ${e.summary}`);
+        });
+    }
+    if (view.unreadable > 0) {
+        lines.push(`  (+${plural(view.unreadable, "unreadable queue file")} skipped)`);
+    }
+    return lines.join("\n");
+}

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

@@ -1,41 +1,91 @@
+import fs from "node:fs";
 import path from "node:path";
 import { listQueueFiles, queueFileName, removeQueueFile } from "../files/file-queue.js";
 import { isJsonObject, nonNegativeNumber } from "../files/json-object.js";
 import { readJsonFile, writeJsonAtomic } from "../files/json-files.js";
 import { cachedByStat } from "../files/stat-cache.js";
-import { landQueueDir } from "../paths.js";
+import { mergeQueueDir, legacyLandQueueDir } from "../paths.js";
+import { canonicalRoleId } from "../roles/legacy-role-ids.js";
 let seq = 0;
-/** Append one landing to the queue as a single timestamped file (creating the queue dir if
+/** Append one merge to the queue as a single timestamped file (creating the queue dir if
  * needed). The filename orders entries across processes by wall-clock time; the per-process
  * counter and pid break ties within one process. Written atomically (tmp + rename): the
  * enqueue runs while the process can be hard-killed mid-write (the tick deadline's
  * process-group kill, a shutdown), and a torn entry the crash left behind is not always
  * recoverable — the drain repairs only an unreadable HEAD (staleHeadFile), so a torn file
  * that sorts after a healthy entry would sit in the queue dir unread forever. */
-export function enqueueLanding(root, entry) {
-    const dir = landQueueDir(root);
+export function enqueueMerge(root, entry) {
+    const dir = mergeQueueDir(root);
     const name = queueFileName(entry.enqueuedAt, seq++, ".json");
     writeJsonAtomic(path.join(dir, name), entry);
 }
-/** Every queue file in execution order (oldest first) — the same filename sort queuedLandings,
- * headLanding, and the orchestrator's per-poll queued-roles set read. A missing queue dir
+/** The revision fields of a queue entry, serialized only when present — the shape merge
+ * surfaces (drain, verify) and the tick-stage enqueue re-emit when they build their own
+ * entry/request objects, so the `revisionRound`/`priorReview` names live in one place and
+ * cannot drift. */
+export function entryRevisionFields(e) {
+    return {
+        ...(e.revisionRound !== undefined ? { revisionRound: e.revisionRound } : {}),
+        ...(e.priorReview !== undefined ? { priorReview: e.priorReview } : {}),
+    };
+}
+/** Every queue file in execution order (oldest first) — the same filename sort queuedMerges,
+ * headMerge, and the orchestrator's per-poll queued-roles set read. A missing queue dir
  * reads as an empty queue. */
 function queueFiles(root) {
-    return listQueueFiles(landQueueDir(root), ".json");
+    // Files an old build enqueued into the legacy directory still count until the startup
+    // migration moves them; the sort is by basename because the queue order lives in the name.
+    const all = [...listQueueFiles(mergeQueueDir(root), ".json"), ...listQueueFiles(legacyLandQueueDir(root), ".json")];
+    return all.sort((a, b) => path.basename(a).localeCompare(path.basename(b)));
+}
+/** The startup migration step: move every `*.json` from the legacy queue directory into the
+ * current one, keeping the basename (the order lives in it) and the contents. A basename already
+ * present in the new directory stays put and is noted; the old directory is removed once empty.
+ * A file that vanished mid-move (a concurrent run) is skipped. */
+export function legacyMigrateLandQueueDir(root) {
+    const from = legacyLandQueueDir(root);
+    const to = mergeQueueDir(root);
+    const notes = [];
+    const files = listQueueFiles(from, ".json");
+    if (files.length > 0)
+        fs.mkdirSync(to, { recursive: true });
+    for (const file of files) {
+        const name = path.basename(file);
+        const dest = path.join(to, name);
+        if (fs.existsSync(dest)) {
+            notes.push(`${name} already in merge-queue, left in place`);
+            continue;
+        }
+        try {
+            fs.renameSync(file, dest);
+            notes.push(`moved ${name}`);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+        }
+    }
+    try {
+        fs.rmdirSync(from);
+    }
+    catch {
+        // Missing, or still holding a file left in place or placed since: nothing to remove.
+    }
+    return notes;
 }
-/** Number of landings currently queued — a directory listing only; no file content is read.
+/** Number of merges currently queued — a directory listing only; no file content is read.
  * A missing queue dir reads as 0, like every other reader here. */
 export function queueDepth(root) {
     return queueFiles(root).length;
 }
 // Per-poll entry-content cache (stat-cache.cachedByStat): dashboard polls must not re-parse
-// every queued entry — each file is written once by enqueueLanding and only deleted on drop,
+// every queued entry — each file is written once by enqueueMerge and only deleted on drop,
 // the same write-once discipline the inbox caches for prompts.
 const entryCache = new Map();
-/** True when `v` carries every field a LandingEntry requires, with the right type. The land
+/** True when `v` carries every field a MergeEntry requires, with the right type. The merge
  * queue is one JSON object per file, so a file that parses to anything else — a scalar, an
  * array, an object missing a required field — is foreign or torn and reads as no entry.
- * Checking only `role` and `sha` left the `as LandingEntry` cast unsound: a foreign file that
+ * Checking only `role` and `sha` left the `as MergeEntry` cast unsound: a foreign file that
  * happened to carry those two fields was handed downstream with `tick` and `summary`
  * undefined, which surface as bogus session names (`tumwater-<role>-undefined-review`) and
  * `undefined` in the reviewer's prompt. Optional fields are checked only when present.
@@ -49,15 +99,16 @@ function isPriorReview(v) {
         return false;
     return (typeof v.sha === "string" &&
         Array.isArray(v.reasons) &&
-        v.reasons.every((r) => typeof r === "string"));
+        v.reasons.every((r) => typeof r === "string") &&
+        (v.counts === undefined || (Array.isArray(v.counts) && v.counts.every((c) => nonNegativeNumber(c, null) !== null))));
 }
-function isLandingEntry(v) {
+function isMergeEntry(v) {
     if (!isJsonObject(v))
         return false;
     const e = v;
     return (typeof e.role === "string" &&
         typeof e.sha === "string" &&
-        nonNegativeNumber(e.tick, null) !== null &&
+        nonNegativeNumber(e.run, null) !== null &&
         typeof e.summary === "string" &&
         nonNegativeNumber(e.enqueuedAt, null) !== null &&
         (e.body === undefined || typeof e.body === "string") &&
@@ -67,22 +118,30 @@ function isLandingEntry(v) {
 }
 /** Read one queue file through the stat-keyed cache: null when it vanishes mid-listing (a
  * concurrent drop — the inbox.ts race policy), is unreadable, or fails to parse or to carry
- * every required LandingEntry field (a foreign or torn file is skipped, never thrown on). A
+ * every required MergeEntry field (a foreign or torn file is skipped, never thrown on). A
  * shallow copy out: the entry's fields are all scalars and callers treat the result as
  * read-only. */
 function readEntry(file) {
     return cachedByStat(entryCache, file, file, () => {
         // readJsonFile is the shared "missing or torn reads as no data" policy; a foreign shape
-        // is still rejected by isLandingEntry.
-        const parsed = readJsonFile(file);
-        return isLandingEntry(parsed) ? parsed : null;
+        // is still rejected by isMergeEntry.
+        let parsed = readJsonFile(file);
+        // An entry an old build wrote carries `tick` where the current shape has `run`.
+        if (isJsonObject(parsed) && parsed.run === undefined && parsed.tick !== undefined) {
+            const { tick, ...rest } = parsed;
+            parsed = { ...rest, run: tick };
+        }
+        if (!isMergeEntry(parsed))
+            return null;
+        const role = canonicalRoleId(parsed.role);
+        return role === parsed.role ? parsed : { ...parsed, role };
     }, (e) => ({ ...e }));
 }
-/** Every queued landing in execution order (oldest first) paired with the file to drop on
- * completion. The batch drain (merge queue 5/5) reads this slice because `dropLanding` needs
+/** Every queued merge in execution order (oldest first) paired with the file to drop on
+ * completion. The batch drain (merge queue 5/5) reads this slice because `dropMerge` needs
  * the file, which the bare-entry readers never return. A missing queue directory reads as an
  * empty queue. */
-export function queuedLandingFiles(root) {
+export function queuedMergeFiles(root) {
     const out = [];
     for (const file of queueFiles(root)) {
         const entry = readEntry(file);
@@ -91,21 +150,21 @@ export function queuedLandingFiles(root) {
     }
     return out;
 }
-/** All queued landings in execution order (oldest first). A missing queue directory reads as
+/** All queued merges in execution order (oldest first). A missing queue directory reads as
  * an empty queue. */
-export function queuedLandings(root) {
-    return queuedLandingFiles(root).map((q) => q.entry);
+export function queuedMerges(root) {
+    return queuedMergeFiles(root).map((q) => q.entry);
 }
-/** The roles currently holding a queued landing — the maintenance quota's and the permit
+/** The roles currently holding a queued merge — the maintenance quota's and the permit
  * reserve's "already in flight" input, and the scheduler's per-poll merge-queue interlock.
  * A missing queue directory reads as an empty set, like every reader here. */
-export function queuedLandingRoles(root) {
-    return new Set(queuedLandingFiles(root).map((q) => q.entry.role));
+export function queuedMergeRoles(root) {
+    return new Set(queuedMergeFiles(root).map((q) => q.entry.role));
 }
 /** Read every queue file once through the stat-keyed cache, collecting the readable entries
  * (filename order) and counting the rest — the torn/foreign file policy readEntry already
  * applies, surfacing the skip count instead of hiding it. */
-export function readLandingQueue(root) {
+export function readMergeQueue(root) {
     const entries = [];
     let unreadable = 0;
     for (const file of queueFiles(root)) {
@@ -119,7 +178,7 @@ export function readLandingQueue(root) {
 }
 /** The head of the queue — its oldest entry — plus the file to drop on completion, or null when
  * the queue is empty or its oldest file is a vanished/torn entry. */
-export function headLanding(root) {
+export function headMerge(root) {
     const file = queueFiles(root)[0];
     if (!file)
         return null;
@@ -127,23 +186,23 @@ export function headLanding(root) {
     return entry ? { entry, file } : null;
 }
 /** The oldest queue file when the queue is non-empty but its head is unreadable — torn or
- * foreign (a partial write an older build left, a hand-placed file) — i.e. when headLanding
+ * foreign (a partial write an older build left, a hand-placed file) — i.e. when headMerge
  * reads null while the queue holds files; null when the queue is empty or its head is healthy.
- * The drain drops this file with a warning so the queue can drain: headLanding reads null for
+ * The drain drops this file with a warning so the queue can drain: headMerge reads null for
  * it forever and nothing else will remove it, stranding every live entry behind it (each
  * author's interlock, the per-poll queued-roles set, pins its ticks along with them). The
- * crashed entry's commit, if any, still lives in its landing ref — next-tick leftover recovery
- * re-lands it — so the drop loses nothing recoverable from the file (BUGS.md 2026-09-16). */
+ * crashed entry's commit, if any, still lives in its merge ref — next-tick leftover recovery
+ * re-merges it — so the drop loses nothing recoverable from the file (BUGS.md 2026-09-16). */
 export function staleHeadFile(root) {
     const file = queueFiles(root)[0];
     if (!file)
         return null;
     return readEntry(file) === null ? file : null;
 }
-/** Remove one queued landing's file after its landing outcome — terminal or not (a
- * non-terminal outcome keeps the landing ref; the retry is the role's next fresh tick, not a
+/** Remove one queued merge's file after its merge outcome — terminal or not (a
+ * non-terminal outcome keeps the merge ref; the retry is the role's next fresh tick, not a
  * queue re-drain). ENOENT is a no-op: a concurrent drop between listing and removal is a
  * normal race (the inbox.ts policy), not an error. */
-export function dropLanding(file) {
+export function dropMerge(file) {
     removeQueueFile(file);
 }