tumwater 0.2.0 → 0.4.0

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

@@ -1,16 +1,16 @@
-// 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 { humanAgo, humanSeconds, secondsSince, secondsUntil } from "../text/datetime.js";
 import { roleLabel } from "../roles/role-labels.js";
 import { shortSha } from "../text/format.js";
+import { filterKeepPositions } from "../collections.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,
+/** The bracketed-label text for one queue entry, in the wording the role rows use (status-model's
+ * rolePhase): `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. */
@@ -44,28 +44,65 @@ export function revisionNote(entry) {
         note += " · " + plural(reasons.length, "prior objection");
     return note;
 }
+/** One re-queued entry's what-brought-it-back note:
+ * `re-queued after <result>`, plus ` · ×<n>` while it has bounced more than once, plus
+ * ` · eligible in <duration>` while a `review_error` 60 s deferral still holds (its `notBefore`
+ * in the future). "" for a fresh entry with no `retry` field, so a first submission's queue
+ * line is byte-identical. */
+export function retryNote(entry, now) {
+    if (entry.retry === undefined)
+        return "";
+    let note = `re-queued after ${entry.retry}`;
+    if ((entry.retryCount ?? 0) > 1)
+        note += ` · ×${entry.retryCount}`;
+    if (entry.notBefore !== undefined && entry.notBefore > now) {
+        note += ` · eligible in ${humanSeconds(secondsUntil(entry.notBefore, now))}`;
+    }
+    return note;
+}
+/** Narrows a whole-queue view to the entries whose role `keep` accepts, and returns the
+ * `scope` renderMergeQueue takes: the kept roles, each kept entry's 1-based place in the whole
+ * queue, and the whole queue's entry count. `unreadable` stays whole because an unreadable file
+ * has no role to attribute it to. */
+export function scopeMergeQueue(whole, roles, keep) {
+    const { kept, positions } = filterKeepPositions(whole.entries, (e) => keep(e.role));
+    return { view: { ...whole, entries: kept }, scope: { roles, positions, total: whole.entries.length } };
+}
 /** 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
+ * one 1-based line per readable entry, oldest first, carrying the role, run 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) {
+ * (queueEntryMergeLabel). With the optional `scope` (`queue --role`: `view` holds only the
+ * listed roles' entries, `positions` their 1-based places in the whole queue, `total` the whole
+ * queue's entry count) each line keeps its whole-queue number, the header reads
+ * `merge queue (<kept> of <whole depth>, --role <ids>):`, and a scope that keeps nothing of a
+ * non-empty queue prints `no queued merges for <ids> (merge queue holds <depth>)`. Without
+ * `scope` the output is the whole queue's. */
+export function renderMergeQueue(view, now, inFlight, scope) {
     const depth = view.entries.length + view.unreadable;
+    const wholeDepth = scope ? scope.total + view.unreadable : depth;
+    const ids = scope ? scope.roles.join(",") : "";
     const lines = [];
-    if (depth === 0) {
+    if (wholeDepth === 0) {
         lines.push("merge queue empty");
     }
+    else if (scope && view.entries.length === 0) {
+        lines.push(`no queued merges for ${ids} (merge queue holds ${wholeDepth})`);
+    }
     else {
-        lines.push(`merge queue (${depth}):`);
+        lines.push(scope ? `merge queue (${view.entries.length} of ${wholeDepth}, --role ${ids}):` : `merge queue (${depth}):`);
         view.entries.forEach((e, i) => {
-            const age = humanSeconds(secondsSince(e.enqueuedAt, now));
+            const age = humanAgo(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}`);
+            const retry = retryNote(e, now);
+            const retryTag = retry ? ` · ${retry}` : "";
+            const frictionTag = e.highFriction === true ? " · high friction" : "";
+            lines.push(`  ${scope ? scope.positions[i] : i + 1}. ${roleLabel(e.role)} run #${e.run} · ${shortSha(e.sha)} · ${age}${tag}${frictionTag}${retryTag}${noteTag} · ${e.summary}`);
         });
     }
     if (view.unreadable > 0) {

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

@@ -1,3 +1,4 @@
+import { errCode } from "../errno.js";
 import fs from "node:fs";
 import path from "node:path";
 import { listQueueFiles, queueFileName, removeQueueFile } from "../files/file-queue.js";
@@ -10,7 +11,7 @@ let seq = 0;
 /** 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
+ * enqueue runs while the process can be hard-killed mid-write (the run 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. */
@@ -20,7 +21,7 @@ export function enqueueMerge(root, entry) {
     writeJsonAtomic(path.join(dir, name), entry);
 }
 /** 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
+ * surfaces (drain, verify) and the run-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) {
@@ -45,7 +46,7 @@ function queueFiles(root) {
 export function legacyMigrateLandQueueDir(root) {
     const from = legacyLandQueueDir(root);
     const to = mergeQueueDir(root);
-    const notes = [];
+    const notes = { moved: [], kept: [], failed: [] };
     const files = listQueueFiles(from, ".json");
     if (files.length > 0)
         fs.mkdirSync(to, { recursive: true });
@@ -53,15 +54,15 @@ export function legacyMigrateLandQueueDir(root) {
         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`);
+            notes.kept.push(`${name} already in merge-queue, left in place`);
             continue;
         }
         try {
             fs.renameSync(file, dest);
-            notes.push(`moved ${name}`);
+            notes.moved.push(`moved ${name}`);
         }
         catch (err) {
-            if (err.code !== "ENOENT")
+            if (errCode(err) !== "ENOENT")
                 throw err;
         }
     }
@@ -86,12 +87,12 @@ const entryCache = new Map();
  * 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 MergeEntry` cast unsound: a foreign file that
- * happened to carry those two fields was handed downstream with `tick` and `summary`
+ * happened to carry those two fields was handed downstream with `run` 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.
  *
  * The three numeric fields go through nonNegativeNumber, not a bare `typeof === "number"`:
- * JSON's `1e999` parses to Infinity, so a hand-edited file could carry a non-finite tick or
+ * JSON's `1e999` parses to Infinity, so a hand-edited file could carry a non-finite run or
  * enqueuedAt past a typeof check, and both feed plumbing downstream (session names, queue
  * ordering, the status payload). */
 function isPriorReview(v) {
@@ -114,7 +115,10 @@ function isMergeEntry(v) {
         (e.body === undefined || typeof e.body === "string") &&
         (e.highFriction === undefined || typeof e.highFriction === "boolean") &&
         (e.revisionRound === undefined || nonNegativeNumber(e.revisionRound, null) !== null) &&
-        (e.priorReview === undefined || isPriorReview(e.priorReview)));
+        (e.priorReview === undefined || isPriorReview(e.priorReview)) &&
+        (e.notBefore === undefined || nonNegativeNumber(e.notBefore, null) !== null) &&
+        (e.retry === undefined || typeof e.retry === "string") &&
+        (e.retryCount === undefined || nonNegativeNumber(e.retryCount, null) !== null));
 }
 /** 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
@@ -127,9 +131,9 @@ function readEntry(file) {
         // 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 (isJsonObject(parsed) && parsed.run === undefined && parsed.tick !== undefined) { // retired-name-ok: legacy name
+            const { tick, ...rest } = parsed; // retired-name-ok: legacy name
+            parsed = { ...rest, run: tick }; // retired-name-ok: legacy name
         }
         if (!isMergeEntry(parsed))
             return null;
@@ -176,6 +180,19 @@ export function readMergeQueue(root) {
     }
     return { entries, unreadable };
 }
+/** The full path of every queue file `readMergeQueue` skips — torn, foreign, or vanished
+ * mid-listing — in filename order. This names what `readMergeQueue.unreadable` counts, through
+ * the same skip policy, so the count and the list cannot drift: nothing else ages a skipped
+ * file (the drain repairs only an unreadable head), so each here is a stranded entry the
+ * queue reader silently passes over. A missing queue directory reads as an empty list. */
+export function unreadableMergeQueueFiles(root) {
+    const out = [];
+    for (const file of queueFiles(root)) {
+        if (readEntry(file) === null)
+            out.push(file);
+    }
+    return out;
+}
 /** 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 headMerge(root) {
@@ -190,8 +207,8 @@ export function headMerge(root) {
  * 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: 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 merge ref — next-tick leftover recovery
+ * author's interlock, the per-poll queued-roles set, pins its runs along with them). The
+ * crashed entry's commit, if any, still lives in its merge ref — next-run 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];
@@ -199,8 +216,28 @@ export function staleHeadFile(root) {
         return null;
     return readEntry(file) === null ? file : null;
 }
+/** The role a torn queue file was being written for, recovered from its raw bytes: MergeEntry
+ * serializes `role` first, so even a head a crash cut mid-write keeps a `"role":"<id>"`
+ * substring the drain can read back without a JSON parse. Tolerant by design — the regex, not
+ * a JSON.parse — because the file's tail is exactly the part the tear may have lost. Null when
+ * the file has no readable role: a foreign file, or a tear that cut the write before the role
+ * landed. Best-effort: an unreadable file reads as null, never a throw. The drain uses it to
+ * name the torn head's owner and re-queue its pinned change before dropping the file. */
+export function tornHeadRole(file) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const m = /"role"\s*:\s*"([^"]+)"/.exec(raw);
+    if (!m)
+        return null;
+    return canonicalRoleId(m[1]);
+}
 /** 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
+ * non-terminal outcome keeps the merge ref; the retry is the role's next fresh run, 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 dropMerge(file) {

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

@@ -0,0 +1,103 @@
+/** Re-queuing a settled merge entry (plans/fast-merge.md "Lever 1"), split out of
+ * merge-slot.ts so the kept-change policy reads on its own screen: merge-slot.ts owns the
+ * in-flight marker, the per-merge usage accounting, and the write-back that folds an outcome
+ * into the authoring role's state and drops its queue entry; this module owns the other half
+ * of a settled entry — putting a kept change back on the queue itself, either at once (a
+ * retriable result) or once main's head stops being red (a `main_red` pin). */
+import { enqueueMerge, queuedMerges } from "./merge-queue.js";
+import { RETRIABLE_MERGE_RESULTS } from "./merge-core.js";
+import { pinnedRetrySha } from "../runner/leftover.js";
+import { branchHead } from "../git/git.js";
+import { cachedBaselineVerdict } from "../baseline/main-baseline.js";
+import { saveRunnerStateBestEffort } from "../runner/runner-state.js";
+import { logEventBestEffort, warnEventBestEffort } from "../events/events.js";
+import { errorMessage } from "../text/text.js";
+/** How long a re-queued `review_error` change waits before its verification may start. */
+const REVIEW_ERROR_RETRY_MS = 60_000;
+/** The queue entry that re-queues a settled one: its run, summary, body, friction flag and
+ * revision fields unchanged (so the summary is not a recovery label), the pin's current `sha`,
+ * and `retry` naming the result it retries. */
+function retryEntry(from, sha, result) {
+    const { notBefore: _notBefore, retry: _retry, ...rest } = from;
+    return {
+        ...rest,
+        sha,
+        retry: result,
+        retryCount: (from.retryCount ?? 0) + 1,
+        enqueuedAt: Date.now(),
+        ...(result === "review_error" ? { notBefore: Date.now() + REVIEW_ERROR_RETRY_MS } : {}),
+    };
+}
+function enqueueRetry(root, entry) {
+    enqueueMerge(root, entry);
+    logEventBestEffort(root, {
+        source: entry.role,
+        type: "merge_queued",
+        commit: entry.sha,
+        summary: entry.summary,
+        retry: entry.retry,
+    });
+}
+/** After a settled merge dropped its entry, put a kept change back on the queue itself, so a
+ * retry needs no author run (plans/fast-merge.md "Lever 1"). A `merge_blocked`, `review_error`
+ * or `merge_conflict` result re-queues at once when its pin survives and pinnedRetrySha allows
+ * it (not stale, not held, under MERGE_CONFLICT_LIMIT); a `main_red` pin is recorded on the
+ * state with main's head, for requeueMainRedPin to re-queue once main moves to a head whose
+ * verdict is not red. Anything else, or a pin that is gone, changes nothing — leftover recovery
+ * stays the backstop. */
+export async function requeueKeptChange(root, mainBranch, entry, state, result) {
+    const isMainRed = result === "main_red";
+    if (!isMainRed && !RETRIABLE_MERGE_RESULTS.has(result))
+        return;
+    const sha = await pinnedRetrySha(root, entry.role, mainBranch, state);
+    if (!sha)
+        return;
+    if (isMainRed) {
+        const { sha: _sha, notBefore: _nb, retry: _r, ...rest } = entry;
+        state.mainRedRetry = { head: (await branchHead(root, mainBranch)) ?? "", entry: rest };
+        saveRunnerStateBestEffort(root, state);
+        return;
+    }
+    if (queuedMerges(root).some((e) => e.role === entry.role))
+        return;
+    enqueueRetry(root, retryEntry(entry, sha, result));
+}
+/** The longest a kept `main_red` pin waits for the main watch's verdict on a moved head before it
+ * is re-queued anyway. This bounds the wait when no verdict ever arrives, for example after a
+ * watch check that timed out or a restart's cold cache. */
+export const MAIN_RED_VERDICT_WAIT_MS = 15 * 60_000;
+/** Re-queue a `main_red` pin once main's head differs from the one recorded when its attempt
+ * settled (the orchestrator poll calls this for every runner), by the head's cached verdict: red
+ * leaves the record untouched, so a later poll asks again; no verdict starts (and saves) a wait
+ * at `now`, and the pin re-queues once MAIN_RED_VERDICT_WAIT_MS has passed; green re-queues at
+ * once. Re-queuing clears the record; no entry is queued when the pin is gone or held back by
+ * pinnedRetrySha, or the role already has one queued. It never throws: the poll
+ * loop calls it with no catch. */
+export async function requeueMainRedPin(root, mainBranch, state, mainHead, now = Date.now()) {
+    const kept = state.mainRedRetry;
+    if (!kept || mainHead === "" || mainHead === kept.head)
+        return;
+    const verdict = cachedBaselineVerdict(mainHead);
+    if (verdict === "red")
+        return;
+    if (verdict === undefined) {
+        if (kept.waitingSince === undefined) {
+            state.mainRedRetry = { ...kept, waitingSince: now };
+            saveRunnerStateBestEffort(root, state);
+            return;
+        }
+        if (now - kept.waitingSince < MAIN_RED_VERDICT_WAIT_MS)
+            return;
+    }
+    state.mainRedRetry = undefined;
+    saveRunnerStateBestEffort(root, state);
+    const sha = await pinnedRetrySha(root, kept.entry.role, mainBranch, state);
+    if (!sha || queuedMerges(root).some((e) => e.role === kept.entry.role))
+        return;
+    try {
+        enqueueRetry(root, retryEntry(kept.entry, sha, "main_red"));
+    }
+    catch (err) {
+        warnEventBestEffort(root, kept.entry.role, `the kept main_red change could not be re-queued: ${errorMessage(err)}`);
+    }
+}

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

@@ -1,16 +1,16 @@
-// vocabulary: plain
 import { dropMerge } from "./merge-queue.js";
 import { runCostIsReal } from "../pi/pi-run-result.js";
 import { reviewRunConfig, seamHoldKey, seamPairName } from "../config/config-views.js";
-import { saveLoopState } from "../loop/loop-state.js";
-import { applyMergeOutcome, ERROR_STREAK_WARN } from "../tick/tick-apply.js";
-import { observeClaudeAccount } from "../agent/claude/claude-account.js";
+import { saveRunnerStateBestEffort } from "../runner/runner-state.js";
+import { applyMergeOutcome, ERROR_STREAK_WARN } from "../run/run-apply.js";
+import { observeAccount } from "../agent/subscription-account.js";
 import { logEventBestEffort, usageFragment, warnEventBestEffort } from "../events/events.js";
 import { readJsonFile, writeJsonAtomic } from "../files/json-files.js";
 import { isJsonObject, nonNegativeNumber } from "../files/json-object.js";
 import { removeQuiet } from "../files/files.js";
 import { mergeStatePath } from "../paths.js";
 import { consecutiveFailuresWarning } from "../text/phrases.js";
+import { truncate } from "../text/text.js";
 import { canonicalRoleId } from "../roles/legacy-role-ids.js";
 /** How each merge stage names itself in the merge cell. */
 export const MERGE_STAGE_LABELS = {
@@ -18,6 +18,7 @@ export const MERGE_STAGE_LABELS = {
     "check-wait": "waiting to check",
     "build-check": "checking",
     reviewing: "reviewing",
+    "reviewing-check": "reviewing, checking",
     "resolve-wait": "waiting to resolve conflicts",
     resolving: "resolving conflicts",
     "provider-wait": "waiting for the provider",
@@ -232,22 +233,48 @@ export function isMergeChange(value) {
         (value.status === "merging" || value.status === "approved" || value.status === "done") &&
         (value.stageSince === undefined || nonNegativeNumber(value.stageSince, null) !== null));
 }
+/** Why a merge ended without landing, for the `merge_failed` event, or undefined when the
+ * state names none. `rejected` reads the review's first reason, only when that review was
+ * recorded during this merge (`at >= startedAt`; an older one is stale). Every other failure
+ * reads `lastError`, minus its `merge failed: ` and `<result> — ` prefixes; a bare result
+ * (the catch-all `merge failed: merge_conflict`) names no reason. */
+export function mergeFailureReason(state, result, startedAt) {
+    if (result === "changed" || result === "aborted")
+        return undefined;
+    if (result === "rejected") {
+        const review = state.lastReview;
+        if (!review || review.at < startedAt)
+            return undefined;
+        return review.reasons[0]?.trim() || undefined;
+    }
+    let reason = (state.lastError ?? "").trim();
+    if (reason.startsWith("merge failed: "))
+        reason = reason.slice("merge failed: ".length);
+    if (reason.startsWith(`${result} — `))
+        reason = reason.slice(`${result} — `.length);
+    reason = reason.trim();
+    return reason === "" || reason === result ? undefined : reason;
+}
 /** Fold one merge's outcome into its role's state and drop its queue entry — the 3/5
  * write-back every pipeline outcome goes through (a verification's final verdict, a merged change,
  * an aborted approved change): apply the result to the live state object (paired with the entry's
  * change for the last-result cell — applyMergeOutcome), persist it, log merge_done/merge_failed
+ * (the failed event carries the reason mergeFailureReason derives)
  * with the merge's own duration (from its verification's start) and usage (omitted when zero — the
  * 4/5 idiom, so review-exempt merges render bare), and drop the entry: EVERY defined result
  * drops. Both event writes are best-effort: an unwritable feed (ENOSPC, EACCES) must not
  * skip the drop, or the settled entry would stay queued and be re-verified and re-merged on
- * the next drain — the queue's "drop after EVERY outcome" contract (merge-queue.ts). The
- * change's marker record is the caller's concern (removeMergeChange). */
+ * the next drain — the queue's "drop after EVERY outcome" contract (merge-queue.ts). A failed
+ * state save warns and does not skip the drop either: the in-memory state already holds the
+ * outcome and the runner's next save writes it. The change's marker record is the caller's
+ * concern (removeMergeChange). */
 export function writeMergeOutcome(root, entry, state, result, durationMs, usage, file) {
     applyMergeOutcome(state, result, entry);
-    saveLoopState(root, state);
+    saveRunnerStateBestEffort(root, state);
+    const reason = result === "changed" ? undefined : mergeFailureReason(state, result, Date.now() - durationMs);
     // One warning per error episode, merge side (BUGS.md 2026-09-30): a review rejection
-    // feeds the same streak the tick-side warn reads (src/tick/tick-finalize.ts), but it resolves
-    // AFTER the tick's end-save, so the crossing warn belongs here — same shape, same bar.
+    // feeds the same streak the run-side warn reads (src/run/run-finalize.ts), but it resolves
+    // AFTER the run's end-save, so the crossing warn belongs here — same shape, same bar.
     if (result === "rejected" && (state.consecutiveErrors ?? 0) === ERROR_STREAK_WARN) {
         warnEventBestEffort(root, entry.role, consecutiveFailuresWarning(state.consecutiveErrors ?? 0, state.lastError ?? "review rejected"));
     }
@@ -260,6 +287,7 @@ export function writeMergeOutcome(root, entry, state, result, durationMs, usage,
         commit: entry.sha,
         result,
         summary: entry.summary,
+        ...(reason !== undefined ? { reason: truncate(reason, 300) } : {}),
         durationMs,
         // Enqueue-to-outcome span, including the slot's own durationMs. A leftover-recovery
         // re-enqueue writes a new entry with its own enqueuedAt, so a retried change counts from
@@ -271,6 +299,13 @@ export function writeMergeOutcome(root, entry, state, result, durationMs, usage,
         // sees a merge's spend under its reviewer's provider. Omitted when empty (a merge
         // whose runs carried no provider), the same omit-when-empty idiom the usage fields use.
         ...(Object.keys(usage.providerCost).length > 0 ? { providerCost: usage.providerCost } : {}),
+        // The merge's notional spend per backend (plans/codex-backend.md part 3d/9): the
+        // subscription seam whose runs made the merge's API-equivalent cost, so a codex merge's
+        // subscription spend names codex, not a generic claude line. Omitted when the merge spent
+        // no notional, the same omit-when-empty idiom the usage fields use.
+        ...(Object.keys(usage.notionalByBackend ?? {}).length > 0
+            ? { notionalByBackend: usage.notionalByBackend }
+            : {}),
     });
     dropMerge(file);
 }
@@ -283,7 +318,7 @@ export function writeMergeOutcome(root, entry, state, result, durationMs, usage,
  * folded onto the rate-limit and backend-failure stamps this fold writes: a 429 on a claude
  * reviewer must hold `claude`, not the pi author's provider (PLANS.md "Mixed claude + pi
  * fleets, part 2/4"). The reviewer's final runs are folded HERE (merge-core.ts's
- * reviewPinnedChange), not inside LoopPi — loop-pi.ts stamps the retried first attempt; this
+ * reviewPinnedChange), not inside RunnerPi — runner-pi.ts stamps the retried first attempt; this
  * stamps the final run, which ends on a different seam when the reviewer runs on a
  * non-pi backend. */
 /** Fetch-or-create a provider's accumulator entry in `usage.providerCost` and add `amount`
@@ -298,8 +333,16 @@ function addProviderCost(usage, provider, amount, notional) {
         e.costUsd += amount;
     usage.providerCost[provider] = e;
 }
+/** Add a subscription run's notional spend to the merge's per-backend tally, keyed by the
+ * run's agent (falling back to the claude default, like the run-end fold), so the merge event
+ * names the backend whose runs made its API-equivalent cost (plans/codex-backend.md part 3d/9). */
+function addBackendNotional(usage, agent, amount) {
+    const backend = agent && agent !== "" ? agent : "claude";
+    usage.notionalByBackend = usage.notionalByBackend ?? {};
+    usage.notionalByBackend[backend] = (usage.notionalByBackend[backend] ?? 0) + amount;
+}
 export function mergeUsage(author, root) {
-    const usage = { tokens: 0, cost: 0, providerCost: {} };
+    const usage = { tokens: 0, cost: 0, providerCost: {}, notionalByBackend: {} };
     const reviewConfig = reviewRunConfig(author.config);
     const reviewProvider = seamHoldKey(reviewConfig);
     const reviewPair = seamPairName(reviewConfig);
@@ -308,13 +351,14 @@ export function mergeUsage(author, root) {
         foldUsage: (run) => {
             author.foldMergeUsage(run, reviewProvider, reviewPair);
             // A claude reviewer's or resolver's billing/window readings reach the account file the
-            // moment this run folds, not at the author's next tick end — so a pi-author team's
-            // claude reviewer still updates the five-hour window before the author's next tick
-            // starts (PLANS.md "Mixed claude + pi fleets, part 3/4"). Best-effort like tick-finalize.ts's
-            // call; the file is a cache and an unwritable state dir must not fail the merge.
+            // moment this run folds, not at the author's next run end — so a pi-author team's
+            // claude reviewer still updates the five-hour window before the author's next run
+            // starts (PLANS.md "Mixed claude + pi fleets, part 3/4"). The run's agent names the
+            // backend's own file. Best-effort like run-finalize.ts's call; the file is a cache and
+            // an unwritable state dir must not fail the merge.
             if (run.billing !== undefined || run.rateWindows !== undefined) {
                 try {
-                    observeClaudeAccount(root, { billing: run.billing, rateWindows: run.rateWindows });
+                    observeAccount(root, run.agent ?? "pi", run);
                 }
                 catch {
                     // The next reporting run rewrites it; nothing this merge depends on is lost.
@@ -331,6 +375,7 @@ export function mergeUsage(author, root) {
             }
             else {
                 usage.notionalCost = (usage.notionalCost ?? 0) + run.costUsd;
+                addBackendNotional(usage, run.agent, run.costUsd);
                 if (reviewProvider !== undefined) {
                     addProviderCost(usage, reviewProvider, run.costUsd, true);
                 }

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

@@ -1,4 +1,3 @@
-// vocabulary: plain
 /** The stack merger — the merge-half machinery of a multi-change batch (extracted from
  * merge-batch.ts, whose header scopes that file to the verify and merge halves): assemble the
  * approved changes as a cherry-picked stack on main's current tip, run ONE scope-`batch` build
@@ -6,8 +5,9 @@
  * re-stack loop for a main that moves mid-check, the doc-only exemption and its cross-checks,
  * and the per-attempt abort observation. The bisect over a red stack (mergeApproved, in
  * merge-batch.ts) drives this file's mergeStack one prefix at a time. */
-import { COMMIT_IDENT, gitTry } from "../git/git-run.js";
-import { branchHead, deleteRef, gitLines, headOf } from "../git/git.js";
+import { committerIdentArgs, gitTry } from "../git/git-run.js";
+import { branchHead, deleteRef, headOf } from "../git/git.js";
+import { treeDiffFiles } from "../git/git-diff.js";
 import { mergeRefName, mergeLockDir } from "../paths.js";
 import { ensureDetachedWorktree } from "../git/worktree.js";
 import { useWorktree } from "../git/worktree-use.js";
@@ -15,11 +15,14 @@ import { exemptSkipBlockReason } from "./merge-to-main.js";
 import { logNewQuestions } from "./merge-questions.js";
 import { openQuestions } from "../backlog/backlog.js";
 import { logEventBestEffort, warnEventBestEffort } from "../events/events.js";
-import { ffMainToOrWhy } from "./merge-git.js";
+import { ffMainToOrWhy, overwriteBlockedReason, primaryCheckoutBlockers } from "./merge-git.js";
 import { syncRootInstall } from "../build/dep-install.js";
 import { withLock } from "../concurrency/lock.js";
 import { runScopedBuildCheck } from "../build/build-check-scoped.js";
+import { mergeCommandOf } from "../build/build-check-detect.js";
 import { noteGreenBaseline } from "../baseline/main-baseline.js";
+import { onlyKnownMainFailures } from "../baseline/main-watch.js";
+import { unverifiedTreeOutcome } from "../build/build-check-events.js";
 import { isExemptDiff } from "../review/exemptions.js";
 import { checkWaitStage, setMergeStage } from "./merge-slot.js";
 /** How many times a batch whose fast-forward lost the race to a moved main re-stacks onto the
@@ -62,7 +65,7 @@ async function assembleStack(root, mainBranch, wtPath, entries) {
         // from merging only its last diff and orphaning the work beneath it. (Not a
         // rebase: after 2/5 the role branches sit at main and each merge lives only in its
         // pinned ref — there is nothing to rebase.)
-        const pick = await gitTry(wt, ...COMMIT_IDENT, "cherry-pick", `${base}..${entry.sha}`);
+        const pick = await gitTry(wt, ...(await committerIdentArgs(wt)), "cherry-pick", `${base}..${entry.sha}`);
         if (pick === null) {
             // A conflict (or an already-applied patch — the crash-window re-drain): abort the
             // pick and abandon to one-at-a-time. The worktree may be left mid-state; its next
@@ -84,8 +87,8 @@ async function assembleStack(root, mainBranch, wtPath, entries) {
  * --no-renames so a rename out of a code path lists the deleted source, not only its exempt
  * destination. An unreadable diff is not exempt: the caller runs the check. */
 async function exemptTreeDelta(root, from, to, exemptPaths) {
-    const out = await gitTry(root, "diff", "--no-renames", "--name-only", from, to);
-    return out !== null && isExemptDiff(gitLines(out), exemptPaths);
+    const files = await treeDiffFiles(root, from, to);
+    return files !== null && isExemptDiff(files, exemptPaths);
 }
 /** Merge `entries` — the whole stack, or one bisect prefix of it — as ONE fast-forward on its
  * own green check: assemble them on main's current tip in `wtPath`, run ONE scope-`batch`
@@ -97,6 +100,8 @@ async function exemptTreeDelta(root, from, to, exemptPaths) {
  * build (the reasoning verifyMerge's exempt arm applies) — and runs the same cross-checks
  * that arm runs, the backlog heading structure and the false-fix claim; one that fails either
  * returns `conflict`, so the per-change fallback applies the gate's own verdict per change.
+ * A primary checkout on main that holds uncommitted or untracked files the stack changes
+ * returns `blocked` before any check runs, with no re-stack.
  * On `landed` every entry's ref is deleted and the red-main baseline is seeded with the tip
  * when a check PASSED on exactly it — a skipped check seeds nothing, like verifyMerge's
  * exempt arm. The check's events log under the first entry's role. */
@@ -121,6 +126,12 @@ async function mergeStackIn(ctx, wtPath, entries) {
             return { kind: "conflict" }; // main unreadable or a pick conflicted
         const { base, mergeDone } = assembled;
         const tip = mergeDone.at(-1).sha;
+        // A dirty primary checkout is one `git status` away: block before the check, not after it.
+        const dirty = await primaryCheckoutBlockers(ctx.root, ctx.mainBranch, tip);
+        if (dirty !== null) {
+            warnEventBestEffort(ctx.root, mergeDone.at(-1).role, `merge blocked: ${overwriteBlockedReason(dirty)}`);
+            return { kind: "blocked" };
+        }
         // The expensive deterministic half, shared: ONE run over the combined tree. Outcome
         // routing — null: no declared check, merge directly; "failed": red or a merge-scope
         // timeout, the caller bisects; "skipped": no npm / broken toolchain (the helper warned),
@@ -133,8 +144,7 @@ async function mergeStackIn(ctx, wtPath, entries) {
             // stacked on — decides like verifyMerge does: doc-only cannot break the build, so no
             // check runs (a doc-only stack, or a bisect's size-1 doc-only remainder, merges on the
             // exemption instead of paying a suite run no code change asked for).
-            const stackDiff = await gitTry(ctx.root, "diff", "--no-renames", "--name-only", base, tip);
-            const stackFiles = stackDiff === null ? null : gitLines(stackDiff);
+            const stackFiles = await treeDiffFiles(ctx.root, base, tip);
             if (stackFiles !== null && isExemptDiff(stackFiles, exemptPaths)) {
                 // The same cross-checks verifyMerge's exempt arm runs (merge-to-main.ts's
                 // exemptSkipBlockReason): the skip must not wave through an md-only edit the gate would
@@ -153,10 +163,16 @@ async function mergeStackIn(ctx, wtPath, entries) {
                 const check = await runScopedBuildCheck(ctx.root, roles[0], "batch", wtPath, ctx.config, undefined, undefined, undefined, checkWaitStage(ctx.root, roles));
                 for (const e of entries)
                     setMergeStage(ctx.root, e.role, "merging");
-                if (check !== null && check.outcome.status === "failed")
+                // Failing only main's known failures is not a red stack (verifyMerge's rule): the ff goes
+                // ahead, and no green seeds for a tree that did not pass.
+                const knownOnly = check !== null && check.outcome.status === "failed" &&
+                    !unverifiedTreeOutcome(check.outcome) &&
+                    onlyKnownMainFailures(ctx.root, check.outcome.failingTests) !== null;
+                if (check !== null && check.outcome.status === "failed" && !knownOnly)
                     return { kind: "red", ...check };
                 checkedTip = tip;
-                if (check !== null && check.outcome.status === "passed")
+                // A mergeCommand green seeds nothing: main's verdict comes from the main watch.
+                if (check !== null && check.outcome.status === "passed" && mergeCommandOf(ctx.config) === undefined)
                     seed = tip;
             }
         }