tumwater 0.1.2 → 0.2.0

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

@@ -0,0 +1,340 @@
+// 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 { 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 { canonicalRoleId } from "../roles/legacy-role-ids.js";
+/** How each merge stage names itself in the merge cell. */
+export const MERGE_STAGE_LABELS = {
+    rebasing: "rebasing",
+    "check-wait": "waiting to check",
+    "build-check": "checking",
+    reviewing: "reviewing",
+    "resolve-wait": "waiting to resolve conflicts",
+    resolving: "resolving conflicts",
+    "provider-wait": "waiting for the provider",
+    merging: "finishing the merge",
+};
+/** Publish the in-flight merge marker — the one place its shape is constructed, so the
+ * interface is enforced here rather than at each caller's inline `writeJsonFile`: every
+ * writer names a stage. Atomic (tmp + rename) because the marker is rewritten mid-merge at
+ * every stage and per-change status transition while observers poll it every second — a plain
+ * overwrite would let a poll read a torn file as "no merge" and flicker the merge row back
+ * to its idle label. */
+export function writeMergeMarker(root, marker) {
+    writeJsonAtomic(mergeStatePath(root), marker);
+}
+/** Read the in-flight merge marker; null when missing or unreadable. Never throws —
+ * observers poll it every second, and a torn write (a crash mid-write) must not take them
+ * down (the readOrchestratorInfo precedent). */
+export function readMergeMarker(root) {
+    const marker = readJsonFile(mergeStatePath(root));
+    if (!marker || typeof marker.role !== "string")
+        return marker;
+    const out = { ...marker, role: canonicalRoleId(marker.role) };
+    if (Array.isArray(marker.changes)) {
+        out.changes = marker.changes.map((c) => (c && typeof c.role === "string" ? { ...c, role: canonicalRoleId(c.role) } : c));
+    }
+    return out;
+}
+/** Rewrite the marker after one of its records changed: re-point the top level at the first
+ * change in `merging` (see MergeInFlight — left as is while none is), then write it. Never
+ * throws: the marker is display-only, and a failed write must not fail a merge (the
+ * observers keep the previous frame's record until the next write). */
+function rewriteMarker(root, marker) {
+    const headline = marker.changes.find((c) => isMergeChange(c) && c.status === "merging");
+    if (headline) {
+        marker.role = headline.role;
+        marker.sha = headline.sha;
+        marker.summary = headline.summary;
+        marker.startedAt = headline.startedAt ?? marker.startedAt;
+        marker.stage = headline.stage ?? "merging";
+    }
+    try {
+        writeMergeMarker(root, { ...marker, stage: marker.stage ?? "merging" });
+    }
+    catch {
+        /* display-only — see above */
+    }
+}
+/** Read-modify-write one change's record in the live marker — the skeleton setMergeChangeStatus
+ * and setMergeStage share: read the marker off disk, hand `apply` the change named by `role`,
+ * and write the marker back through rewriteMarker. A read-modify-write of the file, not a
+ * rewrite from memory, so the stage a gate last set (the same process) survives. A no-op when
+ * there is no marker or it has no record for `role`; `apply` returns whether to write the
+ * marker — true when it changed anything, false to skip the write (setMergeStage's guard
+ * against re-staging an unchanged stage). Never throws (rewriteMarker). */
+function updateMergeChange(root, role, apply) {
+    const marker = readMergeMarker(root);
+    // A `changes` field that is not an array is as unusable as an absent one — treat it as no
+    // per-change records (the legacy shape) and leave the marker untouched, rather than reading
+    // `.find` off a scalar and throwing into a live merge.
+    if (!marker || !Array.isArray(marker.changes))
+        return;
+    const change = marker.changes.find((c) => isMergeChange(c) && c.role === role);
+    if (!change)
+        return;
+    if (!apply(change))
+        return;
+    rewriteMarker(root, { ...marker, changes: marker.changes });
+}
+/** Advance one change's record in the live marker — the verification's move to `approved` and the
+ * merge's per-change status hook (BatchContext.onChangeStatus). A read-modify-write of the file,
+ * not a rewrite from memory, so the stage a gate last set (setMergeStage, the same process)
+ * survives. Each move to `merging` resets the change's stage to `merging` and stamps its
+ * `startedAt` if it has none. A no-op when there is no marker or it has no record for `role`.
+ * Never throws (rewriteMarker). */
+export function setMergeChangeStatus(root, role, status) {
+    updateMergeChange(root, role, (change) => {
+        change.status = status;
+        if (status === "merging") {
+            change.startedAt ??= Date.now();
+            change.stage = "merging";
+        }
+        return true;
+    });
+}
+/** Add one change's record as its verification starts: each change is its own task, so records come
+ * and go one at a time. The new record starts `merging` at `rebasing` with its own `startedAt` (a
+ * verification opens with its checkout and rebase onto main). Every other record is kept only while
+ * its role is in `live` — the roles the pipeline holds right now — so a record a crashed generation
+ * left behind never rides along. Never throws (rewriteMarker). */
+export function addMergeChange(root, entry, live) {
+    const marker = readMergeMarker(root);
+    const kept = marker ? mergeChanges(marker).filter((c) => c.role !== entry.role && live.has(c.role)) : [];
+    const startedAt = Date.now();
+    const change = {
+        role: entry.role,
+        sha: entry.sha,
+        summary: entry.summary,
+        status: "merging",
+        startedAt,
+        stage: "rebasing",
+        stageSince: startedAt,
+    };
+    rewriteMarker(root, {
+        role: entry.role,
+        sha: entry.sha,
+        summary: entry.summary,
+        startedAt,
+        stage: "rebasing",
+        stageSince: startedAt,
+        changes: [...kept, change],
+    });
+}
+/** Remove one change's record once the pipeline has written its outcome (or dropped it as
+ * already on main), deleting the marker when it was the last. A no-op when the marker names no
+ * such role. Never throws. */
+export function removeMergeChange(root, role) {
+    const marker = readMergeMarker(root);
+    if (!marker)
+        return;
+    const all = mergeChanges(marker);
+    const changes = all.filter((c) => c.role !== role);
+    if (changes.length === all.length)
+        return;
+    if (changes.length === 0) {
+        removeQuiet(mergeStatePath(root));
+        return;
+    }
+    rewriteMarker(root, { ...marker, changes });
+}
+/** Advance a merge's stage — called by the merge path at each transition: review.ts before
+ * its pre-check (`build-check`) and before its reviewer run (`reviewing`), merge-to-main.ts
+ * around its conflict resolver run (`resolving`, then `merging`), merge-core.ts's
+ * reviewPinnedChange once the gate returns (`merging`, whatever it decided — a finished
+ * reviewer's last turns must not sit in the cell accruing a false `no pi output` flag while the
+ * change waits for its merge), and merge-stack.ts around a stack's shared check. It stages
+ * `role`'s own record — every concurrent verification advances its own change's cell. A no-op for a
+ * role with no record (a gate run outside the pipeline, as the unit tests drive it). Only the stage
+ * changes: sha and startedAt are what the snapshot cross-check and the merge's elapsed read. */
+export function setMergeStage(root, role, stage) {
+    updateMergeChange(root, role, (change) => {
+        if (change.stage === stage)
+            return false; // already there — keep the marker as written
+        change.stage = stage;
+        change.stageSince = Date.now();
+        return true;
+    });
+}
+/** The merge cell's save-point hooks one of the pipeline's permit waits parks on: `wait` (the
+ * stage shown while the caller is parked) set on each of `roles`' records, and `granted` (the
+ * stage once the permit arrives). The three permit waits the pipeline uses — the build check's,
+ * the conflict resolver's, and the re-key verification's — share this one pair of callbacks,
+ * which differ only in their two stage names, so a fourth wait reuses it instead of re-copying
+ * the waiting/granted shape. A no-op for a role with no record, like setMergeStage. */
+function waitStageHooks(root, roles, wait, granted) {
+    return {
+        waiting: () => roles.forEach((role) => setMergeStage(root, role, wait)),
+        granted: () => roles.forEach((role) => setMergeStage(root, role, granted)),
+    };
+}
+/** The merge cell's hooks around a build check's wait for its permit (runScopedBuildCheck's
+ * `permitWait`): `check-wait` on each of `roles`' records while parked, `build-check` once the
+ * permit arrives. Called only when the permit was not free, so an unqueued check never
+ * flickers. */
+export function checkWaitStage(root, roles) {
+    return waitStageHooks(root, roles, "check-wait", "build-check");
+}
+/** The merge cell's hooks around the merge's conflict resolver waiting for its agent permit
+ * (merge-drain.ts's merge wiring): `resolve-wait` while parked, `resolving` once the permit
+ * arrives — checkWaitStage's shape for the maxConcurrent semaphore, so a resolver queued behind
+ * busy agents never reads as one running. Called only when the permit was not free. */
+export function resolveWaitStage(root, role) {
+    return waitStageHooks(root, [role], "resolve-wait", "resolving");
+}
+/** The verification's hooks around a re-key onto a full provider (plans/provider-concurrency.md §5,
+ * "A re-key wait is visible"): `provider-wait` while the verification's lease parks on the target
+ * provider's full cap, `reviewing` once the key frees and the review proceeds. resolveWaitStage's
+ * shape for the re-key path — a verification that normally shares its review seam never
+ * re-keys, so the stage fires only when a run actually moves to a different, full provider. */
+export function providerWaitStage(root, role) {
+    return waitStageHooks(root, [role], "provider-wait", "reviewing");
+}
+/** The marker's per-change records, whichever shape it has: `changes` as written, or — for a
+ * marker an older generation wrote with one top-level change — that change, `merging` since the
+ * marker's start at the marker's stage. Reads both shapes into records, so addMergeChange's
+ * stale-record filtering and status-model's per-role cell cannot disagree about which changes a
+ * marker names. */
+export function mergeChanges(marker) {
+    return Array.isArray(marker.changes)
+        ? marker.changes.filter(isMergeChange)
+        : [
+            {
+                role: marker.role,
+                sha: marker.sha,
+                summary: marker.summary,
+                status: "merging",
+                startedAt: marker.startedAt,
+                stage: marker.stage,
+                ...(marker.stageSince !== undefined ? { stageSince: marker.stageSince } : {}),
+            },
+        ];
+}
+/** True when a persisted `changes` entry is a record the pipeline and the observers can act on:
+ * a role, sha and summary string and one of the three statuses. A hand-edited, torn, or foreign
+ * entry (a `null`/scalar, or one missing `status`) is dropped by mergeChanges rather than read
+ * field-by-field — without this, `c.role` on a `null` entry threw `Cannot read properties of
+ * null` straight into setMergeChangeStatus and the every-second status poll. */
+export function isMergeChange(value) {
+    return (isJsonObject(value) &&
+        typeof value.role === "string" &&
+        typeof value.sha === "string" &&
+        typeof value.summary === "string" &&
+        (value.status === "merging" || value.status === "approved" || value.status === "done") &&
+        (value.stageSince === undefined || nonNegativeNumber(value.stageSince, null) !== null));
+}
+/** 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
+ * 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). */
+export function writeMergeOutcome(root, entry, state, result, durationMs, usage, file) {
+    applyMergeOutcome(state, result, entry);
+    saveLoopState(root, state);
+    // 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.
+    if (result === "rejected" && (state.consecutiveErrors ?? 0) === ERROR_STREAK_WARN) {
+        warnEventBestEffort(root, entry.role, consecutiveFailuresWarning(state.consecutiveErrors ?? 0, state.lastError ?? "review rejected"));
+    }
+    // `merged` still fires from merge-to-main.ts itself — these events mark the QUEUE's
+    // bookkeeping: the slot picked the entry up (merge_queued, logged at enqueue) and finished
+    // with or without merge.
+    logEventBestEffort(root, {
+        source: entry.role,
+        type: result === "changed" ? "merge_done" : "merge_failed",
+        commit: entry.sha,
+        result,
+        summary: entry.summary,
+        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
+        // its last enqueue.
+        queuedMs: Math.max(0, Date.now() - entry.enqueuedAt),
+        ...usageFragment(usage.tokens, usage.cost, usage.notionalCost),
+        // The merge's per-provider spend, keyed to its reviewer seam (the same reviewProvider
+        // key the author-side foldMergeUsage charges), so the report's `Cost by provider` line
+        // 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 } : {}),
+    });
+    dropMerge(file);
+}
+/** A fresh usage accumulator for one merge plus the foldUsage callback that charges each of
+ * its pi runs to BOTH the authoring runner's live state (foldMergeUsage: reviewer and
+ * conflict-resolution spend belongs to the authoring role) and the merge's own accumulator
+ * (the merge_done/merge_failed event's usage). Every verification builds its wiring through this,
+ * and its merge reuses it, so the accounting — and any future change to it — lives in one place.
+ * `reviewProvider` is this merge's reviewer seam hold key (seamHoldKey of reviewRunConfig),
+ * 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
+ * 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`
+ * to one of its two fields — the single home of the real/notional provider bump both
+ * branches of foldUsage do, so a future change to the entry shape (or the
+ * noUncheckedIndexedAccess seed) is merged once instead of twice. */
+function addProviderCost(usage, provider, amount, notional) {
+    const e = usage.providerCost[provider] ?? { costUsd: 0, notionalCostUsd: 0 };
+    if (notional)
+        e.notionalCostUsd += amount;
+    else
+        e.costUsd += amount;
+    usage.providerCost[provider] = e;
+}
+export function mergeUsage(author, root) {
+    const usage = { tokens: 0, cost: 0, providerCost: {} };
+    const reviewConfig = reviewRunConfig(author.config);
+    const reviewProvider = seamHoldKey(reviewConfig);
+    const reviewPair = seamPairName(reviewConfig);
+    return {
+        usage,
+        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.
+            if (run.billing !== undefined || run.rateWindows !== undefined) {
+                try {
+                    observeClaudeAccount(root, { billing: run.billing, rateWindows: run.rateWindows });
+                }
+                catch {
+                    // The next reporting run rewrites it; nothing this merge depends on is lost.
+                }
+            }
+            usage.tokens += run.outputTokens;
+            if (runCostIsReal(run)) {
+                usage.cost += run.costUsd;
+                // Only a resolved reviewer seam bears a provider: a pi reviewer whose provider was
+                // never pinned (reviewProvider undefined) attributes nothing, like the author side.
+                if (reviewProvider !== undefined) {
+                    addProviderCost(usage, reviewProvider, run.costUsd, false);
+                }
+            }
+            else {
+                usage.notionalCost = (usage.notionalCost ?? 0) + run.costUsd;
+                if (reviewProvider !== undefined) {
+                    addProviderCost(usage, reviewProvider, run.costUsd, true);
+                }
+            }
+        },
+    };
+}

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

@@ -1,42 +1,43 @@
-/** The stack lander — the merge-half machinery of a multi-change batch (extracted from
- * landing-batch.ts, whose header scopes that file to the vet and merge halves): assemble the
- * vetted changes as a cherry-picked stack on main's current tip, run ONE scope-`batch` build
+// 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
  * check over the combined tree, and fast-forward main through the captured shas — with the
  * 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 (landVetted, in
- * landing-batch.ts) drives this file's landStack one prefix at a time. */
+ * 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 { landingRefName, mergeLockDir } from "../paths.js";
+import { mergeRefName, mergeLockDir } from "../paths.js";
 import { ensureDetachedWorktree } from "../git/worktree.js";
 import { useWorktree } from "../git/worktree-use.js";
-import { exemptSkipBlockReason } from "./landing-merge.js";
-import { logNewQuestions } from "./landing-questions.js";
+import { exemptSkipBlockReason } from "./merge-to-main.js";
+import { logNewQuestions } from "./merge-questions.js";
 import { openQuestions } from "../backlog/backlog.js";
-import { logEventBestEffort } from "../events/events.js";
-import { ffMainTo } from "./landing-git.js";
+import { logEventBestEffort, warnEventBestEffort } from "../events/events.js";
+import { ffMainToOrWhy } 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 { noteGreenBaseline } from "../baseline/main-baseline.js";
 import { isExemptDiff } from "../review/exemptions.js";
-import { checkWaitStage, setLandingStage } from "./landing-slot.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
  * new tip and goes round again before handing every change to leftover recovery as
  * `merge_blocked`. The race window is the whole batch check, and main still has writers
- * outside the land queue (a human commit, or a second fleet on the same repo), so a
+ * outside the merge queue (a human commit, or a second team on the same repo), so a
  * lost race is routine and one re-stack almost always wins it — the second is headroom for a
  * busy stretch. The bound keeps a main that moves faster than a check completes from holding
- * the merge slot (and every vetted landing behind it) indefinitely: each re-stack
+ * the merge slot (and every approved merge behind it) indefinitely: each re-stack
  * whose new tree is not doc-only pays one more full check. Past it the per-change path takes
- * over, whose in-lock re-check another harness landing cannot race. */
+ * over, whose in-lock re-check another harness merge cannot race. */
 export const BATCH_RESTACK_ATTEMPTS = 2;
-/** Assemble a batch's stack in `wtPath` (the shared `_merge` checkout a landing drain passes)
+/** Assemble a batch's stack in `wtPath` (the shared `_merge` checkout a merge drain passes)
  * on main's CURRENT tip, once
  * per attempt — a re-stack after a lost fast-forward race is the same assembly on the tip that
- * won. `entries` carry each change's head to land (its synced pin); the result carries that
+ * won. `entries` carry each change's head to merge (its synced pin); the result carries that
  * base (`base` — the tip the stack's own delta is measured against) plus each change's
- * captured post-pick sha, in queue order — the stack ffStackToMain lands. Returns null when
+ * captured post-pick sha, in queue order — the stack ffStackToMain merges. Returns null when
  * the stack cannot be assembled on this tip: main is unreadable, or a pick conflicts (or
  * applies nothing — the crash-window re-drain); the caller abandons to one-at-a-time. */
 async function assembleStack(root, mainBranch, wtPath, entries) {
@@ -45,21 +46,21 @@ async function assembleStack(root, mainBranch, wtPath, entries) {
     // main the FIRST batch already moved; stacking from S[0].sha there would put the ff
     // against diverged history on every attempt. When main hasn't moved since the pins were
     // created (the common single-batch case) the picks reconstruct the same tree and the ff
-    // lands the same tip. Every entry — the head included — carries its captured post-pick sha
+    // merges the same tip. Every entry — the head included — carries its captured post-pick sha
     // into the ff and the per-change merged events.
     const base = await branchHead(root, mainBranch);
     if (base === null)
         return null; // main unreadable: cannot stack
     // One idempotent ensure at the fresh base covers the worktree-a-moment-ago case (the
-    // change's vet, or the previous attempt's assembly).
+    // change's verify, or the previous attempt's assembly).
     const wt = await ensureDetachedWorktree(root, wtPath, base);
-    const landed = [];
+    const mergeDone = [];
     for (const entry of entries) {
-        // Cherry-pick the whole RANGE from main's tip to the entry's head to land — `base..sha`,
+        // Cherry-pick the whole RANGE from main's tip to the entry's head to merge — `base..sha`,
         // every commit ahead of main, in queue order. A pin is normally one commit, so the range is
         // that commit; picking the range rather than the head alone keeps a pin that carries more
-        // from landing only its last diff and orphaning the work beneath it. (Not a
-        // rebase: after 2/5 the role branches sit at main and each landing lives only in its
+        // 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}`);
         if (pick === null) {
@@ -69,44 +70,44 @@ async function assembleStack(root, mainBranch, wtPath, entries) {
             await gitTry(wt, "cherry-pick", "--abort");
             return null;
         }
-        landed.push({ role: entry.role, sha: await headOf(wt, "HEAD"), summary: entry.summary });
+        mergeDone.push({ role: entry.role, sha: await headOf(wt, "HEAD"), summary: entry.summary });
     }
-    return { base, landed };
+    return { base, mergeDone };
 }
 /** True when the tree at `to` differs from the tree at `from` only in review-exempt paths —
  * the gate's own doc-only test (isExemptDiff over config.review.exemptPaths). A re-stack whose
  * new commits from main were doc-only rebuilds the checked tree with nothing but doc bytes
- * changed, and a doc-only delta cannot break the build: the reasoning verifyLanding
- * (src/landing/landing-merge.ts) applies when it skips its in-lock re-check for a moved
- * doc-only landing. Its false-fix cross-check has no counterpart here — the delta is
- * commits main already landed through their own gate, not a claim this batch makes.
+ * changed, and a doc-only delta cannot break the build: the reasoning verifyMerge
+ * (src/merge/merge-to-main.ts) applies when it skips its in-lock re-check for a moved
+ * doc-only merge. Its false-fix cross-check has no counterpart here — the delta is
+ * commits main already merged through their own gate, not a claim this batch makes.
  * --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);
 }
-/** Land `entries` — the whole stack, or one bisect prefix of it — as ONE fast-forward on its
+/** 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`
  * check over the combined tree, and ff main through the captured shas (ffStackToMain) with
  * nothing rewritten in between — the in-lock invariant. A lost race re-stacks on the tip that
  * won, up to BATCH_RESTACK_ATTEMPTS times, and a re-stack whose tree is the checked tree plus
  * doc-only commits skips its re-check (exemptTreeDelta). A stack whose whole delta ahead of
  * its assembly base is review-exempt skips the check too — a doc-only delta cannot break the
- * build (the reasoning verifyLanding's exempt arm applies) — and runs the same cross-checks
+ * 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.
  * 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 verifyLanding's
+ * 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. */
-export async function landStack(ctx, wtPath, entries) {
+export async function mergeStack(ctx, wtPath, entries) {
     // Hold the merge checkout from before assembleStack (its reset is part of the use) through
     // the ff (plans/disk-floor.md, part 2/4).
-    return useWorktree(ctx.root, wtPath, () => landStackIn(ctx, wtPath, entries));
+    return useWorktree(ctx.root, wtPath, () => mergeStackIn(ctx, wtPath, entries));
 }
-async function landStackIn(ctx, wtPath, entries) {
+async function mergeStackIn(ctx, wtPath, entries) {
     // The last stacked tip a build check actually ran on: a re-stack whose tree differs from it
-    // only in doc-only paths lands on that run's verdict instead of paying another.
+    // only in doc-only paths merges on that run's verdict instead of paying another.
     let checkedTip = null;
     const exemptPaths = ctx.config.review.exemptPaths;
     for (let attempt = 0; attempt <= BATCH_RESTACK_ATTEMPTS; attempt++) {
@@ -118,10 +119,10 @@ async function landStackIn(ctx, wtPath, entries) {
         const assembled = await assembleStack(ctx.root, ctx.mainBranch, wtPath, entries);
         if (assembled === null)
             return { kind: "conflict" }; // main unreadable or a pick conflicted
-        const { base, landed } = assembled;
-        const tip = landed.at(-1).sha;
+        const { base, mergeDone } = assembled;
+        const tip = mergeDone.at(-1).sha;
         // The expensive deterministic half, shared: ONE run over the combined tree. Outcome
-        // routing — null: no declared check, land directly; "failed": red or a merge-scope
+        // 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),
         // proceed — never fail-closed; "passed": green. A re-stack skips the run only when its
         // tree is the checked tree plus doc-only changes (exemptTreeDelta).
@@ -129,13 +130,13 @@ async function landStackIn(ctx, wtPath, entries) {
         const docOnlyRestack = checkedTip !== null && (await exemptTreeDelta(ctx.root, checkedTip, tip, exemptPaths));
         if (!docOnlyRestack) {
             // The stack's own delta ahead of its assembly base — main here is the tip assembleStack
-            // stacked on — decides like verifyLanding does: doc-only cannot break the build, so no
-            // check runs (a doc-only stack, or a bisect's size-1 doc-only remainder, lands on the
+            // 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);
             if (stackFiles !== null && isExemptDiff(stackFiles, exemptPaths)) {
-                // The same cross-checks verifyLanding's exempt arm runs (landing-merge.ts's
+                // 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
                 // have rejected. A failure here cannot name a red check (none ran), so it hands the
                 // stack to the one-at-a-time fallback, whose exempt arm blocks or rejects each change
@@ -144,14 +145,14 @@ async function landStackIn(ctx, wtPath, entries) {
                     return { kind: "conflict" };
             }
             else {
-                // The landing cell names the check while it runs, then the merge steps after it — the ff
+                // The merge cell names the check while it runs, then the merge steps after it — the ff
                 // or what the caller does next — on every stacked change's own record.
                 const roles = entries.map((e) => e.role);
                 for (const role of roles)
-                    setLandingStage(ctx.root, role, "build-check");
+                    setMergeStage(ctx.root, role, "build-check");
                 const check = await runScopedBuildCheck(ctx.root, roles[0], "batch", wtPath, ctx.config, undefined, undefined, undefined, checkWaitStage(ctx.root, roles));
                 for (const e of entries)
-                    setLandingStage(ctx.root, e.role, "merging");
+                    setMergeStage(ctx.root, e.role, "merging");
                 if (check !== null && check.outcome.status === "failed")
                     return { kind: "red", ...check };
                 checkedTip = tip;
@@ -159,57 +160,60 @@ async function landStackIn(ctx, wtPath, entries) {
                     seed = tip;
             }
         }
-        if ((await ffStackToMain(ctx.root, ctx.mainBranch, landed)) === "changed") {
+        if ((await ffStackToMain(ctx.root, ctx.mainBranch, mergeDone)) === "changed") {
             // A PASSED stack check ran on exactly the future main tip — seed the red-main
             // baseline after (not before) the successful ff, so a merge_blocked stack seeds
             // nothing; a skipped check seeds nothing either (skips never seed), and neither does
-            // a doc-only re-stack (like verifyLanding's exempt arm: nothing ran on this tip).
+            // a doc-only re-stack (like verifyMerge's exempt arm: nothing ran on this tip).
             if (seed !== undefined)
                 noteGreenBaseline(seed);
             for (const e of entries)
-                await deleteRef(ctx.root, landingRefName(e.role));
-            return { kind: "landed" };
+                await deleteRef(ctx.root, mergeRefName(e.role));
+            return { kind: "landed" }; // vocabulary-ok: persisted state value or event type, renamed by a later series
         }
         // Main moved under the batch while the check ran (a human commit): diverged history, ff
         // failed. Re-stack on the tip that won.
     }
     return { kind: "blocked" };
 }
-/** Fast-forward main through a WHOLE batch of already-reviewed landings in one (merge queue
- * 5/5): `landed` is the stack in queue order, each entry the change's captured post-pick sha
+/** Fast-forward main through a WHOLE batch of already-reviewed merges in one (merge queue
+ * 5/5): `mergeDone` is the stack in queue order, each entry the change's captured post-pick sha
  * plus its own role and summary. Under the merge lock: one `ffMainTo` to the stacked tip (the
  * LAST entry's sha — a single ff through N stacked commits), one `merged` event PER entry so
  * the report counts the batch as N commits, and the question_posted diff around that single ff
  * (one-shot, as tryMerge's). No rebase and no in-lock re-check inside this helper — that is
  * what makes the batch's one shared stack check sufficient (the design invariant): nothing
- * rewrites between the lander's green check and this ff, so a successful ff makes main
+ * rewrites between the merger's green check and this ff, so a successful ff makes main
  * byte-identical to the checked tip (or, after a doc-only re-stack, to that tip plus the
- * doc-only commits main gained). `noteGreenBaseline` stays out of it too — the lander
+ * doc-only commits main gained). `noteGreenBaseline` stays out of it too — the merger
  * seeds the stacked tip, because it alone knows whether its own check passed. A failed ff
  * (main moved under the batch — diverged history) returns "merge_blocked" with NO events and
- * no ref changes: the lander re-stacks onto the new tip and calls this again (bounded by
+ * no ref changes: the merger re-stacks onto the new tip and calls this again (bounded by
  * BATCH_RESTACK_ATTEMPTS), and only a race lost on every attempt keeps every
  * change's ref for one-at-a-time recovery, whose tryMerge carries the in-lock check. The
  * single-change path is untouched. */
-export async function ffStackToMain(root, mainBranch, landed) {
-    const tip = landed.at(-1);
+export async function ffStackToMain(root, mainBranch, mergeDone) {
+    const tip = mergeDone.at(-1);
     if (!tip)
-        return "changed"; // Empty stack: nothing to fast-forward (never called in production — the lander stacks at least one change).
+        return "changed"; // Empty stack: nothing to fast-forward (never called in production — the merger stacks at least one change).
     return withLock(mergeLockDir(root), async () => {
         const before = openQuestions(root);
-        if (!(await ffMainTo(root, tip.sha, mainBranch)))
+        const ffFailure = await ffMainToOrWhy(root, tip.sha, mainBranch);
+        if (ffFailure !== null) {
+            warnEventBestEffort(root, tip.role, `merge blocked: ${ffFailure}`);
             return "merge_blocked";
+        }
         // Best-effort like tryMerge's merged events: the stack is already fast-forwarded, so an
-        // unwritable feed must not flip a landed batch to a failure and skip syncRootInstall below.
-        for (const entry of landed) {
+        // unwritable feed must not flip a merged batch to a failure and skip syncRootInstall below.
+        for (const entry of mergeDone) {
             logEventBestEffort(root, {
-                loop: entry.role,
+                source: entry.role,
                 type: "merged",
                 commit: entry.sha,
                 summary: entry.summary,
             });
         }
-        logNewQuestions(root, before, landed[0].role);
+        logNewQuestions(root, before, mergeDone[0].role);
         await syncRootInstall(root, tip.role); // As tryMerge: re-sync the root install under the lock.
         return "changed";
     });