tumwater 0.2.0 → 0.3.0

package/dist/src/{loop → runner}/leftover.js

@@ -1,36 +1,87 @@
-// vocabulary: plain
-import { aheadOfMain, commitMessage, deleteRef, headOf, isMergedInto, refSha, setRef } from "../git/git.js";
+import { aheadOfMain, commitExists, commitMessage, deleteRef, deleteRefIfAt, headOf, isMergedInto, refSha, setRef } from "../git/git.js";
 import { parseCommitMetadata } from "../git/commit-message.js";
 import { logEventBestEffort, warnEventBestEffort } from "../events/events.js";
 import { enqueueMerge, queuedMerges } from "../merge/merge-queue.js";
 import { mergeRefName } from "../paths.js";
 import { shortSha } from "../text/format.js";
-/** Salvaging a commit a previous tick left unmerged (plans/merge-queue.md). Since merge queue
+/** Salvaging a commit a previous run left unmerged (plans/merge-queue.md). Since merge queue
  * 2/5 the role's branch is reset to main the moment its commit is pinned, so the leftover
  * normally lives in `refs/tumwater/landing/<role>`: recovery puts that sha back on the durable
- * merge queue, so it merges through the SAME slot, gate, and strike cap a fresh tick's change
+ * merge queue, so it merges through the SAME slot, gate, and strike cap a fresh run's change
  * does — no crash or abort path smuggles unreviewed work into main (invariant 1), and main keeps
- * exactly one writer, the orchestrator's merge slot (an in-tick recovery merge used to race
+ * exactly one writer, the orchestrator's merge slot (an in-run recovery merge used to race
  * the slot's batches into `merge_blocked`). A commit with NO pin — a crash in the window between
- * the tick's commit and its pin write, or a failed pin write itself — still sits on the branch
+ * the run's commit and its pin write, or a failed pin write itself — still sits on the branch
  * ahead of main; recovery adopts that tip into the pin scheme and queues it, so invariant 1
- * holds whether or not the pin survived. Split out of loop.ts — which keeps the tick lifecycle
+ * holds whether or not the pin survived. Split out of runner.ts — which keeps the run lifecycle
  * around it — because this is a self-contained concern with its own entry condition and git
- * surface; the only things it borrows from the loop are identity, the tick number, the
+ * surface; the only things it borrows from the runner are identity, the run number, the
  * worktree (for the no-pin fallback), and three pieces of the role's merge state: its
  * conflict streak, outstanding hand-back, and permanent-reviewer hold. */
 /** Consecutive merges of one pinned sha that may end `merge_conflict` before recovery stops
- * re-queuing it (LoopState.mergeConflicts). Each attempt costs a conflict-resolution run, and
+ * re-queuing it (RunnerState.mergeConflicts). Each attempt costs a conflict-resolution run, and
  * a role holding a pin never authors: without a cap an unmergeable change would re-queue
  * forever, burning one resolution run per drain. At the cap the pin is handed back to its
  * author with the markers in place rather than discarded (PLANS.md "Robust conflict landing,
  * part 2/2"); a lineage already handed back once is discarded instead. */
 export const MERGE_CONFLICT_LIMIT = 2;
-/** Queue a commit a previous tick left unmerged. Entry condition: the merge ref exists and
+/** Delete a pin main already contains — the work merged and a crash skipped its un-pinning —
+ * so nothing re-merges what main holds. True when it was stale and is gone. Shared by the
+ * author's recovery and the pipeline's re-queue (pinnedRetrySha). */
+async function dropStalePin(root, ref, sha, mainBranch) {
+    if (!(await isMergedInto(root, sha, mainBranch)))
+        return false;
+    await deleteRef(root, ref);
+    return true;
+}
+/** Delete a pin whose commit is missing from the repository, with a warning: it can never merge,
+ * and re-queuing it would end every run on an error. True when it was dangling and is gone. */
+async function dropDanglingPin(root, role, ref, sha) {
+    if (await commitExists(root, sha))
+        return false;
+    await deleteRefIfAt(root, ref, sha);
+    warnEventBestEffort(root, role, `dropped merge pin ${shortSha(sha)}: its commit is missing from the repository, so it can never merge`);
+    return true;
+}
+/** The permanent-reviewer-config hold when it names `sha`, else undefined. */
+function reviewHold(held, sha) {
+    return held?.sha === sha ? held : undefined;
+}
+/** Consecutive conflict-ended merges of `sha` (0 when the streak names another sha). */
+function conflictAttempts(streak, sha) {
+    return streak?.sha === sha ? streak.count : 0;
+}
+/** The sha of a role's kept pin when the merge pipeline may re-queue it itself: the pin exists,
+ * main does not already contain it (a stale pin is deleted, as recovery does), no reviewer
+ * configuration hold names it, and its conflict streak is under MERGE_CONFLICT_LIMIT. Null
+ * otherwise — a pin at the limit is the author's conflict hand-back, a held one waits for a
+ * config change, and both stay with recoverLeftover. */
+export async function pinnedRetrySha(root, role, mainBranch, state) {
+    const ref = mergeRefName(role);
+    const sha = await refSha(root, ref).catch(() => null);
+    if (!sha)
+        return null;
+    if (await dropDanglingPin(root, role, ref, sha))
+        return null;
+    if (await dropStalePin(root, ref, sha, mainBranch))
+        return null;
+    if (reviewHold(state.mergeReviewError, sha))
+        return null;
+    if (conflictAttempts(state.mergeConflicts, sha) >= MERGE_CONFLICT_LIMIT)
+        return null;
+    return sha;
+}
+/** Whether the role holds a kept merge pin — the ref `recoverLeftover` reads. Ref presence is the
+ * whole answer: a pin main already holds is left to `recoverLeftover`, which deletes it. */
+export async function hasUnmergedPin(root, role) {
+    return (await refSha(root, mergeRefName(role)).catch(() => null)) !== null;
+}
+/** Queue a commit a previous run left unmerged. Entry condition: the merge ref exists and
  * its sha is not yet contained in main — or, with no pin at all, the role's branch is ahead of
  * main (crash between the commit and the pin). A present-but-contained ref is stale — a crash
- * between the ff-merge and the ref deletion — and is deleted without queuing anything. Returns
- * null when there was nothing to salvage. The queued entry carries the pin's sha plus the
+ * between the ff-merge and the ref deletion — and is deleted without queuing anything, and so is
+ * a pin whose commit is missing from the repository (with a warning — it can never merge).
+ * Returns null when there was nothing to salvage. The queued entry carries the pin's sha plus the
  * summary, body, and high-friction flag read back from its commit message, because the
  * authoring run that set them is gone; from there the merge slot keeps or deletes the ref per
  * the merger's usual policy. An unreadable ref or worktree reads as no leftover — only git-level
@@ -44,18 +95,16 @@ export async function recoverLeftover(ctx) {
     const ref = mergeRefName(ctx.role);
     let sha = await refSha(ctx.root, ref).catch(() => null);
     if (sha) {
-        if (await isMergedInto(ctx.root, sha, ctx.mainBranch)) {
-            // Stale pin: the work already merged and a crash skipped its un-pinning. Clean it up so
-            // the next tick does not re-merge what main already holds.
-            await deleteRef(ctx.root, ref);
+        if (await dropDanglingPin(ctx.root, ctx.role, ref, sha))
+            return null;
+        if (await dropStalePin(ctx.root, ref, sha, ctx.mainBranch))
             return null;
-        }
     }
     else {
         // No pin: either nothing was left behind, or a crash hit the commit→pin window (or
         // the pin write failed) and the commit still sits on the branch ahead of main. Recover that
         // tip too — invariant 1 must hold whether or not the pin survived. An unreadable worktree
-        // reads as "no leftover", exactly like a failed ref read: never propagate into the tick.
+        // reads as "no leftover", exactly like a failed ref read: never propagate into the run.
         const ahead = await aheadOfMain(ctx.wt, ctx.mainBranch).catch(() => 0);
         if (ahead <= 0)
             return null;
@@ -76,10 +125,16 @@ export async function recoverLeftover(ctx) {
     // full gate check for a request that can never succeed until the model config changes. The
     // caller clears the hold (and re-queues) once the resolved reviewer selector differs, so a
     // fixed config recovers automatically (BUGS.md 2026-10-06).
-    const held = ctx.mergeReviewError;
-    if (held?.sha === sha)
+    const held = reviewHold(ctx.mergeReviewError, sha);
+    if (held)
         return { kind: "held", sha, message: held.message };
-    const attempts = ctx.mergeConflicts?.sha === sha ? ctx.mergeConflicts.count : 0;
+    // `requeueMainRedPin` owns the re-queue of a main_red pin, once main's head moves. Queuing it
+    // here would pay a full gate check against the same red head, whose result is already known.
+    if (ctx.mainRedRetry) {
+        const message = `kept change ${shortSha(sha)} waits for main to move past red ${shortSha(ctx.mainRedRetry.head)} before its next merge`;
+        return { kind: "main_red_wait", sha, message };
+    }
+    const attempts = conflictAttempts(ctx.mergeConflicts, sha);
     if (attempts >= MERGE_CONFLICT_LIMIT) {
         const summary = meta.subject ?? `leftover ${shortSha(sha)}`;
         if (ctx.conflictHandback) {
@@ -91,14 +146,14 @@ export async function recoverLeftover(ctx) {
         }
         // Main has moved too far under this change for the resolver to reconcile it: keep the pin
         // and hand it back to its author, who re-applies it over current main with the markers in
-        // place and resolves them. The loop's next step logs the conflict_handback event and sets
-        // LoopState.conflictHandback (the pin survives until that re-apply).
+        // place and resolves them. The runner's next step logs the conflict_handback event and sets
+        // RunnerState.conflictHandback (the pin survives until that re-apply).
         return { kind: "handback", sha, summary, attempts };
     }
     const entry = {
         role: ctx.role,
         sha,
-        run: ctx.tick,
+        run: ctx.runNumber,
         // Name what merges, not merely that a recovery happened: the recovered commit's own subject
         // rides the merge, so the failure digest's "Merged in the window" can correlate a
         // recovered merge with the work it names (BUGS.md 2026-09-21). Unreadable messages fall
@@ -121,7 +176,7 @@ export async function recoverLeftover(ctx) {
 /** The review-gate metadata a pinned leftover commit carries in its own message: its
  * subject, high-friction flag, and author's body, or an empty object when the commit
  * predates the contract or the message cannot be read. Recovery merges through the same gate
- * as a fresh tick, so it must present those fields the same way — otherwise a flagged change
+ * as a fresh run, so it must present those fields the same way — otherwise a flagged change
  * is silently reviewed as routine (BUGS.md 2026-09-19), and the merged event names the
  * recovery but not the work (BUGS.md 2026-09-21). */
 async function recoveredMetadata(root, sha) {

package/dist/src/{loop → runner}/model-fallback.js

@@ -5,18 +5,18 @@ export const MODEL_FALLBACK_COOLDOWN_MS = 5 * 60_000;
 /** The ceiling a repeatedly-failing probe's cooldown doubles toward. */
 export const MODEL_FALLBACK_MAX_COOLDOWN_MS = 30 * 60_000;
 /** True only while the role is in a fallback episode whose probe is still in the future — the
- * ticks that run on the fallback pair. */
+ * runs that use the fallback pair. */
 export function modelFallbackActive(state, now) {
     return state !== undefined && state.since > 0 && now < state.probeAt;
 }
 /** True only while the role is in a fallback episode whose cooldown has elapsed: the next
- * tick runs on the primary as the probe. */
+ * run uses the primary as the probe. */
 export function modelFallbackProbe(state, now) {
     return state !== undefined && state.since > 0 && now >= state.probeAt;
 }
-/** Classify one authoring run's verdict about the primary (src/tick/tick-usage.ts records the
- * same flags for the team-wide hold). A run that was aborted, quiet-killed, or timed out — or
- * that read an image its model cannot see (the runner killed it, plans/image-input.md) — is
+/** Classify one authoring agent run's verdict about the primary (src/run/run-usage.ts records the
+ * same flags for the team-wide hold). An agent run that was aborted, quiet-killed, or timed out
+ * — or that read an image its model cannot see (the runner killed it, plans/image-input.md) — is
  * inconclusive even when it also reports provider evidence: the harness killed it, so it is
  * no verdict about the primary's health. */
 export function modelFallbackVerdict(pi) {
@@ -26,17 +26,17 @@ export function modelFallbackVerdict(pi) {
         return "provider-failure";
     return "answered";
 }
-/** Fold one authoring run's verdict into the role's fallback state, returning the next state
+/** Fold one authoring agent run's verdict into the role's fallback state, returning the next state
  * or undefined for "running the primary" (no episode).
  *
  * - Not in fallback, provider failure: increment the consecutive count; the
  *   MODEL_FALLBACK_FAILURES-th trips the episode.
- * - Not in fallback, an answering run: clear the running count (undefined).
- * - Not in fallback, an inconclusive run: unchanged — a harness kill is not evidence the
+ * - Not in fallback, an answering agent run: clear the running count (undefined).
+ * - Not in fallback, an inconclusive agent run: unchanged — a harness kill is not evidence the
  *   primary recovered, so the running count survives it.
- * - In fallback, a fallback tick (`probe` false): unchanged — its outcome neither returns
+ * - In fallback, a fallback run (`probe` false): unchanged — its outcome neither returns
  *   the role to primary nor re-trips it.
- * - In fallback, a probe tick: an inconclusive probe is unchanged (retried on the next tick);
+ * - In fallback, a probe run: an inconclusive probe is unchanged (retried on the next run);
  *   an answering probe clears the episode; a provider-class failed probe doubles the cooldown
  *   (capped) and schedules the next one.
  */
@@ -68,8 +68,8 @@ export function recordModelFallback(state, outcome) {
     }
     return { failures, since: 0, probeAt: 0, cooldownMs: 0, reason };
 }
-/** The reason label one run's provider evidence yields: "rate-limit" for a 429, else the
- * backend-failure kind. Exported so the loop's evidence assembly and tests share one
+/** The reason label one agent run's provider evidence yields: "rate-limit" for a 429, else the
+ * backend-failure kind. Exported so the runner's evidence assembly and tests share one
  * spelling. */
 export function providerFailureReason(rateLimit, kind) {
     return rateLimit ? "rate-limit" : (kind ?? "backend failure");

package/dist/src/runner/revision.js

@@ -0,0 +1,202 @@
+import path from "node:path";
+import { readTextIfExists, readTextOrNull, writeTextAtomic } from "../files/files.js";
+import { commitOperatorBacklogEdit } from "../backlog/backlog-commit.js";
+import { gitTry, gitTryStarted } from "../git/git-run.js";
+import { resetWorktreeToMain } from "../git/worktree.js";
+import { resolveBacklogInsertConflicts } from "../merge/backlog-conflicts.js";
+import { conflictedFiles } from "../merge/merge-git.js";
+import { shortSha } from "../text/format.js";
+import { formatDate } from "../text/datetime.js";
+import { stampedSubject } from "../git/commit-message.js";
+import { baseRoleOf } from "../roles/runner-ids.js";
+import { entryKey } from "../backlog/backlog-parts.js";
+import { actionableEntryRanges } from "../backlog/backlog-structure.js";
+import { withPrimaryWorktreeLock } from "../concurrency/lock.js";
+import { logEventBestEffort } from "../events/events.js";
+/** The persistence count at which one repeated objection makes a rejection final
+ * (plans/revise-rejected.md; the repeat-finality policy in BUGS.md 2026-10-14): each numbered
+ * reason records how many consecutive revisions it has survived — a new (untagged) objection is
+ * 0, a `(prior N)` restatement is 1 plus the prior round's count for that objection — and when
+ * any reason reaches this count it was raised and then survived two revisions, so the change has
+ * stopped converging and the rejection is final. A converging chain keeps revising while each
+ * round's objections differ. */
+export const REVISION_FINAL_ON_REPEAT = 2;
+/** The hard backstop on one change's revision chain (plans/revise-rejected.md; BUGS.md
+ * 2026-10-14): at this many total rejections the rejection is final even when the objections
+ * never repeat, so a non-converging author cannot revise forever. Replaces the old fixed
+ * `REVISION_LIMIT = 2`, which ended a converging chain at its third rejection whenever each
+ * round raised a new objection. */
+export const REVISION_BACKSTOP = 6;
+/** The convergence rule (PLANS.md "Reviewer as a regular role, part 3/4"): when a rejection is
+ * final — the round cap or an objection that survived its revisions — the author could not
+ * converge, so the PLANS.md plan it was revising is held for the plan role instead of being left
+ * eligible for a fresh author pick that would restart the same cycle (plans/revise-rejected.md's
+ * motivation: the cap stops one cycle, the re-pick starts another). The hold is a
+ * **Needs review …** note under the entry's heading — the same needs-review hold every surface
+ * renders `[blocked: needs review]` and that the plan role resolves by splitting or replanning
+ * the plan (doctor-backlog-plans' checkStalledPlans names it) — whose text names the surviving
+ * objections verbatim (they are already in `RunnerState.lastReview.reasons`), so the plan role
+ * sees exactly what would not converge. PLANS.md plans only: no role clears a Needs-review note
+ * on a BUGS.md entry (`tumwater bug --release` keeps it, INV-AT1, and no role resolves one for
+ * a bug), so holding a bug would be a permanent dead-end; a bug that cannot converge stays with
+ * the existing re-pick behaviour (reviewer-feedback delivery, part 4/4, addresses that churn).
+ * Written through the primary worktree lock, as every other backlog write is, and then committed
+ * on main by commitOperatorBacklogEdit — the commit every other backlog writer makes — so the
+ * primary checkout stays clean for the next fast-forward and the hold reaches the worktrees
+ * that branch from main. Best-effort (write and commit each avoid throwing), so a non-converged
+ * but already-final rejection can never throw on the terminal-exhaustion path. No-op when the
+ * entry is gone (already moved or done), the role carries no claim, or the claim is a bug. */
+export async function holdEntryAfterExhaustion(root, role, claim, reasons) {
+    if (claim?.file !== "PLANS.md")
+        return;
+    const note = `**Needs review ${formatDate(new Date())} by ${baseRoleOf(role)}: could not converge` +
+        (reasons.length === 0 ? "" : ` — ${reasons.join("; ")}`) +
+        `**`;
+    try {
+        withPrimaryWorktreeLock(root, () => {
+            const file = path.join(root, claim.file);
+            const md = readTextIfExists(file) ?? "";
+            const entry = actionableEntryRanges(md, "Planned").find((e) => entryKey(e.title) === claim.key);
+            if (entry === undefined)
+                return;
+            const lines = md.split("\n");
+            // The entry's 0-based line span is [start-1, end-1] inclusive (a non-last entry's range
+            // carries its trailing separator blank; the last entry's ends at its last content line).
+            // Find the last non-blank line inside that span, then rebuild the file with the note,
+            // one blank on each side, directly after the body and before whatever follows (the next
+            // heading, or EOF) — never inside the following entry.
+            let lastContent = entry.end - 1;
+            while (lastContent > entry.start - 1 && (lines[lastContent] ?? "").trim() === "")
+                lastContent--;
+            const rebuilt = [...lines.slice(0, lastContent + 1), "", note, "", ...lines.slice(entry.end)];
+            writeTextAtomic(file, rebuilt.join("\n"));
+        });
+        // Commit the hold on the base branch so the primary stays clean for ff-only and the note
+        // reaches the worktrees that branch from main — the same best-effort commit every other
+        // backlog writer makes (a primary not on the base branch just skips the commit).
+        await commitOperatorBacklogEdit(root, claim.file, stampedSubject("operator", `Hold converged plan: ${claim.key}`)); // vocabulary-ok: the tumwater(operator): commit prefix is a machine string
+    }
+    catch (err) {
+        logEventBestEffort(root, {
+            source: role,
+            type: "revision",
+            action: "hold-failed",
+            message: `could not hold the entry after a final rejection: ${String(err)}`,
+        });
+    }
+}
+/** The picks a stopped `cherry-pick` sequence still owes after the one it stopped on, oldest
+ * first — read from the sequencer's todo, whose first line is the stopped pick. null when the
+ * todo cannot be read, so the caller never settles a stop it cannot finish. */
+async function picksAfterStop(wt) {
+    const todo = await gitTry(wt, "rev-parse", "--git-path", "sequencer/todo");
+    const text = todo === null ? null : readTextOrNull(path.resolve(wt, todo));
+    if (text === null)
+        return null;
+    const picks = text.split("\n").flatMap((line) => /^(?:p|pick)\s+(\S+)/.exec(line)?.[1] ?? []);
+    return picks.slice(1);
+}
+/** Cherry-pick `<base>..<sha>` onto `wt` as uncommitted edits, settling backlog conflicts
+ * without a model run on the way. A rejected or handed-back diff that prepends to PLANS-DONE.md
+ * or BUGS-FIXED.md conflicts with every entry main archived since, the same insert-only shape the
+ * merge's first pass settles (resolveBacklogInsertConflicts); left alone, its author got markers
+ * in a 1.9 MB file (feature-5, 2026-10-19). On a stop whose conflicted files all settle, the
+ * sequencer is quit (`--continue` refuses in `--no-commit` mode) and the picks it still owed are
+ * replayed the same way onto the settled index. */
+async function pickSettlingBacklog(wt, base, sha) {
+    let picks = [`${base}..${sha}`];
+    for (;;) {
+        // diff3 carries the base section of every conflict, which the backlog settler reads; the
+        // markers an author is handed keep it too.
+        const picked = await gitTryStarted(wt, "-c", "merge.conflictStyle=diff3", "cherry-pick", "--no-commit", ...picks);
+        if (picked !== null)
+            return { status: "clean" };
+        // conflictedFiles, not a raw diff: it decodes git's C-quoted names, so a non-ASCII
+        // conflicted path is the on-disk name the prompt and hasConflictMarkers can use.
+        const conflicted = await conflictedFiles(wt);
+        if (conflicted.length === 0)
+            return { status: "failed" };
+        const rest = await picksAfterStop(wt);
+        // A settler that fails part-way (a failed `git add`) leaves every file to the author.
+        const remaining = rest === null ? conflicted : await resolveBacklogInsertConflicts(wt, conflicted).catch(() => conflicted);
+        await gitTry(wt, "cherry-pick", "--quit");
+        if (remaining.length > 0)
+            return { status: "conflicted", files: remaining };
+        if (rest === null || rest.length === 0)
+            return { status: "clean" };
+        picks = rest;
+    }
+}
+/** The exclusive start of the range to re-apply for `sha`: the merge-base with main, except that a
+ * commit already on main (a reverted change, plans/fast-merge.md part 4c) has merge-base `sha`
+ * itself and an empty range, so its own parent is the base and the range is that one commit. null
+ * (the caller drops the hand-back) only on git's own answer, never because git could not start. */
+async function pickBase(wt, mainBranch, sha) {
+    const base = await gitTryStarted(wt, "merge-base", mainBranch, sha);
+    if (base === null)
+        return null;
+    const full = await gitTryStarted(wt, "rev-parse", sha);
+    if (full?.trim() !== base.trim())
+        return base;
+    // A commit main merely fast-forwarded onto keeps the empty range; only one main reverted is
+    // handed back to be re-applied.
+    const reverts = (await gitTryStarted(wt, "log", mainBranch, "--format=%s", "--fixed-strings", `--grep=Revert ${shortSha(sha)}`)) ?? "";
+    if (!reverts.split("\n").some((subject) => subject.endsWith(`Revert ${shortSha(sha)}`)))
+        return base;
+    return gitTryStarted(wt, "rev-parse", `${sha}^`);
+}
+/** Re-apply a rejected change `sha` onto current main as uncommitted edits in `wt`
+ * (plans/revise-rejected.md): the author's next run starts from the rejected diff instead of
+ * re-deriving it. `git cherry-pick --no-commit <merge-base>..<sha>` leaves the edits in the
+ * worktree without committing; a conflict confined to the backlog's insert-only shape is settled
+ * on the way (pickSettlingBacklog). On any other git failure — most often a conflict with what
+ * main merged since the rejection, but also a missing object — the cherry-pick is aborted and
+ * the worktree reset to main, and false is returned so the caller falls back to a plain
+ * rejection note. A git that could not start, or a stopped pick whose conflicts git cannot list,
+ * throws instead, keeping the revision and its ref for the next run. */
+export async function applyRevision(wt, mainBranch, sha) {
+    const base = await pickBase(wt, mainBranch, sha);
+    if (base === null) {
+        await resetWorktreeToMain(wt, mainBranch);
+        return false;
+    }
+    if ((await pickSettlingBacklog(wt, base, sha)).status !== "clean") {
+        await gitTry(wt, "cherry-pick", "--abort");
+        await resetWorktreeToMain(wt, mainBranch);
+        return false;
+    }
+    return true;
+}
+/** Re-apply a handed-back change's diff onto current main with the conflict markers left in
+ * place as ordinary uncommitted edits, so its author can resolve them (PLANS.md "Robust
+ * conflict landing, part 2/2"). Like applyRevision it cherry-picks
+ * `<merge-base>..<sha> --no-commit` onto the worktree's current main, settling backlog
+ * insert-only conflicts on the way (pickSettlingBacklog), so only files that settler cannot
+ * settle keep markers. A conflicted pick is NOT aborted: its sequencer state is quit, a mixed
+ * `git reset` drops the index's unmerged entries so the marker-bearing files are plain
+ * working-tree edits the run can commit normally, and `{ applied: true, conflicted }` is
+ * returned. A failure with no unmerged paths (a missing object, a bad revision) aborts, resets
+ * to main, and returns `{ applied: false }` so the caller falls back to a fresh start. A git
+ * that could not start, or a stopped pick whose conflicts git cannot list, throws instead, so the
+ * run errors with the hand-back and its ref kept for the next. */
+export async function applyWithConflicts(wt, mainBranch, sha) {
+    const base = await pickBase(wt, mainBranch, sha);
+    if (base === null) {
+        await resetWorktreeToMain(wt, mainBranch);
+        return { applied: false, conflicted: [] };
+    }
+    const picked = await pickSettlingBacklog(wt, base, sha);
+    if (picked.status === "conflicted") {
+        // Keep the marker-bearing files, drop only the index's unmerged stage entries: a mixed
+        // reset leaves the working tree untouched, so the markers are uncommitted edits the run
+        // stages and commits like any other author work.
+        await gitTry(wt, "reset");
+        return { applied: true, conflicted: picked.files };
+    }
+    if (picked.status === "failed") {
+        await gitTry(wt, "cherry-pick", "--abort");
+        await resetWorktreeToMain(wt, mainBranch);
+        return { applied: false, conflicted: [] };
+    }
+    return { applied: true, conflicted: [] };
+}

package/dist/src/{loop/loop-fallback.js → runner/runner-fallback.js}

@@ -1,15 +1,15 @@
 import { logEventBestEffort } from "../events/events.js";
 import { modelFallbackVerdict, providerFailureReason, recordModelFallback } from "./model-fallback.js";
-/** Fold one AUTHORING run's verdict into the role's model-fallback state
- * (src/loop/model-fallback.ts) and emit the episode's started/ended events. Only the run
- * that actually happened is evidence: a tick that never invoked pi (a skipped director
- * inbox, a recovered leftover, a red-main block) returns from runTick before this is
- * reached, and modelFallbackVerdict reports an aborted/killed/timed-out run as
+/** Fold one AUTHORING agent run's verdict into the role's model-fallback state
+ * (src/runner/model-fallback.ts) and emit the episode's started/ended events. Only the agent run
+ * that actually happened is evidence: a run that never invoked pi (a skipped director
+ * inbox, a recovered leftover, a red-main block) returns from runOnce before this is
+ * reached, and modelFallbackVerdict reports an aborted/killed/timed-out agent run as
  * inconclusive — so neither can end an episode without the primary having answered.
  * A role whose tier resolves to no fallback pair never trips, and an episode persisted from a
  * config that HAD a pair is cleared when a live edit removes it (or sets it to "pause"), so a
  * stale "on fallback" mark cannot outlive the config that created it. Persists on any state
- * change; the tick's own finalize save carries it too. */
+ * change; the run's own finalize save carries it too. */
 export function foldModelFallbackPhase(ctx, fallbackCtx, pi) {
     const s = ctx.state;
     const prior = s.modelFallback;
@@ -19,8 +19,8 @@ export function foldModelFallbackPhase(ctx, fallbackCtx, pi) {
     const wasIn = prior !== undefined && prior.since > 0;
     if (fallbackCtx.fallback === null) {
         // No fallback pair resolves any more: the feature is off for this role. End a persisted
-        // episode (the primary just ran, so this tick IS the return), and drop any pre-trip count
-        // so a later config starts from zero. A killed/aborted/timed-out run is no verdict, so it
+        // episode (the primary just ran, so this run IS the return), and drop any pre-trip count
+        // so a later config starts from zero. A killed/aborted/timed-out agent run is no verdict, so it
         // leaves the episode in place exactly as it does on a configured fallback.
         if (prior === undefined)
             return;

package/dist/src/runner/runner-outcome.js

@@ -0,0 +1,107 @@
+/** The post-run outcome half of a role run, split out of src/runner/runner-run.ts: after the
+ * authoring pi run finishes, everything that turns the result into an outcome — the verdict
+ * classification (abort, config request, quiet kill, timeout, refusal, failure, no-change)
+ * through resolveRunVerdict, and the fulfillable path's staging of the work for the merge
+ * queue — plus the refusal-note merge path. The run-lifecycle phases that lead up to the pi
+ * run live in runner-run.ts; this module keeps only the outcome's own dependencies, and
+ * shares runner-run.ts's `RunnerRunContext` binder — the one contract between the two halves —
+ * so either half can change without touching the other's imports. */
+import { mergeToMain } from "../merge/merge-to-main.js";
+import { MERGE_LOCK_WAIT_MS } from "../paths.js";
+import { resolveRunVerdict } from "../run/run-verdict.js";
+import { modelTrailerLine } from "../git/commit-message.js";
+import { seamAgent } from "../config/model-selector.js";
+import { stageRunMerge } from "../run/run-stage.js";
+import { stageCheckFindings } from "../run/stage-check.js";
+/** Merge the worktree branch on main (see src/merge/merge-to-main.ts for the
+ * rebase → verify → ff-merge → conflict-retry flow): delegates with the runner identity, run
+ * number, and shared pi wiring so a conflict-resolution run folds into this run's counters
+ * like any other pi run. Only the refusal-note merge (src/verdict/refusal.ts) still uses it —
+ * reviewed changes merge through the merge pipeline's leased verification slot instead; md-only
+ * notes are review-exempt by construction, so they keep this branch path (plans/merge-queue.md
+ * 2/5). The refusal path waits MERGE_LOCK_WAIT_MS for merge.lock, not withLock's default: a
+ * merge holds it through its in-lock check, which outlasts the default. */
+async function mergePhase(ctx, wt, summary) {
+    return mergeToMain({
+        root: ctx.root,
+        role: ctx.role,
+        mainBranch: ctx.mainBranch,
+        exemptPaths: ctx.config.review.exemptPaths,
+        config: ctx.config,
+        runNumber: ctx.state.runs,
+        lockTimeoutMs: MERGE_LOCK_WAIT_MS,
+        runPi: (w, prompt, sessionName, config) => ctx.pi.runRolePi(w, prompt, sessionName, false, config),
+    }, wt, summary);
+}
+/** Turn a finished pi run into its RunOutcome: the post-run half of runOnce, split off so each
+ * half reads on its own screen — the setup above ends at the pi return. The verdict
+ * classification (abort, config request, quiet kill, timeout, refusal, failure, no-change) lives
+ * in resolveRunVerdict (src/run/run-verdict.ts), and the fulfillable path — staging —
+ * stays here. `userPrompt` is the raw director prompt this run is executing (null for role
+ * runners) so unfulfilled outcomes can re-queue it; `revisionRound` is the revision this run holds
+ * (undefined when it is not a revision); `flow` is the qa observer's FLOW line (null for every
+ * other role); `filed` is the feedback observer's FILED line (null for every other role). */
+export async function handlePiResultPhase(ctx, pi, userPrompt, revisionRound, wt, flow, filed, piStartedAt, cfg) {
+    // Everything that decides the run left nothing mergeable — abort, config request,
+    // quiet kill, timeout, refusal, failure without changes, no change — lives in
+    // resolveRunVerdict (src/run/run-verdict.ts); null means the run IS fulfillable.
+    const modelLine = modelTrailerLine(seamAgent(cfg), cfg.provider, cfg.model);
+    const verdict = await resolveRunVerdict({
+        modelLine,
+        root: ctx.root,
+        role: ctx.role,
+        mainBranch: ctx.mainBranch,
+        state: ctx.state,
+        pending: ctx.pending,
+        turns: ctx.usage.turns,
+        userPrompt,
+        revisionRound,
+        wt,
+        pi,
+        flow,
+        filed,
+        // The image-reroute arm resolves its target from the live config and the current
+        // regime, and names the model this run ran on as the handoff's `from`.
+        config: ctx.config,
+        rerouteRegime: ctx.rerouteRegime(piStartedAt),
+        runModel: cfg.model,
+        warn: (message) => ctx.warn(message),
+        merge: (w, sum) => mergePhase(ctx, w, sum),
+        finishAbortedRun: () => ctx.finishAbortedRun(userPrompt, wt),
+    });
+    if (verdict)
+        return verdict;
+    // The commit is pinned and the worktree is free (src/run/run-stage.ts): stage it for the
+    // merge queue and END the run — the orchestrator drains the queue on its single merge
+    // slot, outside the author semaphore, so this slot is free the moment the work is
+    // committed (plans/merge-queue.md 3/5). Staging derives the commit message from the reply's
+    // SUMMARY block (one bounded follow-up turn when the run left none), flags high-friction
+    // runs, pins the commit by the role's merge ref BEFORE freeing the worktree (invariant
+    // 4 — a failed pin defers to next-run recovery), and enqueues the merge, which runs the
+    // same gate + merge flow through runMergePi/foldMergeUsage on this same state object
+    // — recording the commit count, the outcome, and the reviewer spend into it — and logs
+    // merge_done/merge_failed; a non-terminal outcome keeps the pin for next-run leftover recovery.
+    // `commits` was NOT incremented above: it counts merged changes only.
+    return stageRunMerge({
+        modelLine,
+        root: ctx.root,
+        role: ctx.role,
+        state: ctx.state,
+        config: ctx.config,
+        runTurns: ctx.usage.turns,
+        userPrompt,
+        revisionRound,
+        mainBranch: ctx.mainBranch,
+        wt,
+        finalText: pi.finalText,
+        flow,
+        filed,
+        piStartedAt,
+        warn: (message) => ctx.warn(message),
+        requestSummary: (w, n) => ctx.pi.requestSummary(w, cfg, n),
+        stageCheck: (w) => stageCheckFindings(w, ctx.mainBranch, ctx.config.review.exemptPaths, ctx.role),
+        requestStageFix: (w, findings, change) => ctx.pi.requestStageFix(w, findings, change, cfg),
+        pinAndReset: (w, sha) => ctx.pinAndReset(w, sha),
+        finishAbortedRun: () => ctx.finishAbortedRun(userPrompt, wt),
+    });
+}