tumwater 0.4.2 → 0.4.4

package/dist/src/run/run-resume.js

@@ -29,12 +29,10 @@ export function planWithSalvagedWork(role, plan, restored, note) {
         restored,
     };
 }
-/** Resolve how a run starts, consuming the resume flags as a side effect (a flag is consumed
- * here so a resume that fails falls back to a normal fresh run; another shutdown mid-resume
- * sets it again) and reclaiming the interrupted run's re-queued prompt. Owns every read and
- * write of the resume flags, so a new cause or handoff rule is added here. */
-function resolveRunStartDecision(opts) {
-    const s = opts.state;
+/** A run-start's first phase: read the last merge's failure and clear it, so a merge that
+ * failed non-terminally (kept its pin) still feeds the error streak when this run's recovery
+ * re-queues that pin (finishRecoveryRun). */
+function readPriorMergeFailure(s) {
     // The last merge's failure, read before the clear below: a merge that failed
     // non-terminally kept its pin (the merger's own vocabulary — review_error, merge_conflict,
     // merge_blocked — with the detail it wrote into `lastError`), and when this run's recovery
@@ -43,6 +41,13 @@ function resolveRunStartDecision(opts) {
         ? (s.lastError ?? `merge failed: ${s.lastResult}`)
         : undefined;
     s.lastError = undefined;
+    return priorMergeFailure;
+}
+/** A run-start's second phase: resolve, from the session ledger, which session a continue
+ * would reach and whether the backend can resume it, capturing the pending resume cause
+ * before the flags are consumed. */
+function resolveResumeTarget(opts) {
+    const s = opts.state;
     // A run interrupted by a harness shutdown left its pi session and its worktree's
     // uncommitted edits in place: resume that session instead of starting fresh. The flag
     // is consumed here so a resume that fails falls back to a normal fresh run; another
@@ -69,7 +74,6 @@ function resolveRunStartDecision(opts) {
     const resumable = resumePending && !resumeMissing
         ? backendSessionResumable(dir, { kind: "author", agent }, opts.claudeConfigDir)
         : false;
-    const resumableSession = resumable;
     // A newest line our backend cannot resume is not ours to continue: another kind's or
     // another agent's session, OR our own author line whose session the backend no longer holds
     // (a `--resume` that answered "No conversation found" mid-run, leaving `resumeMissing`, or a
@@ -83,48 +87,82 @@ function resolveRunStartDecision(opts) {
     // forward.
     // Captured before the flag is consumed below; a stale cause must not leak into a later resume.
     const pendingResumeCause = s.resumeCause;
+    return { latest, resumable, pendingResumeCause };
+}
+/** A run-start's third phase: decide whether this run resumes its interrupted session or hands
+ * off to a fresh session over the kept worktree. */
+function resumeMode(latest, resumable, budgetCapped, imageReroute, resumeBlocked) {
+    const handoff = (latest !== null && !resumable) || budgetCapped || imageReroute;
+    // A budget-capped handback never resumes the session whose seam the cap moved off of, even
+    // when its transcript is still resumable: it hands off instead. An image reroute likewise.
+    const resuming = resumable && !resumeBlocked && !budgetCapped && !imageReroute;
+    const handingOff = handoff && !resumeBlocked;
+    return { resuming, handingOff };
+}
+/** A run-start's last phase: derive which cause reaches the bridge, naming a quiet-kill, the
+ * cut-off streak, the resume's own cause, or a plain restart/handoff. */
+function resumeCauseFor(handingOff, budgetCapped, imageReroute, pendingResumeCause, cutOffStreak) {
+    // Why the resume: a named quiet-kill means the last run died on a stalled tool call (the
+    // bridge then warns against re-running it unchanged) or on the run deadline while still
+    // making progress (the bridge asks for the smallest finish against the same limit); a
+    // cut-off streak means the last run ran out of context and pi compacted the session (the
+    // bridge asks for the smallest finish); otherwise a shutdown/crash. A handoff names itself,
+    // except a budget-capped one, which names the cap that ended the run, and an image reroute,
+    // whose bridge names the blind read.
+    const resumeCause = handingOff
+        ? budgetCapped
+            ? "budget-capped"
+            : imageReroute
+                ? "image-reroute"
+                : "handoff"
+        : pendingResumeCause ?? (cutOffStreak > 0 ? "cut-off" : "restart");
+    return resumeCause;
+}
+/** Resolve how a run starts, consuming the resume flags as a side effect (a flag is consumed
+ * here so a resume that fails falls back to a normal fresh run; another shutdown mid-resume
+ * sets it again) and reclaiming the interrupted run's re-queued prompt. Owns every read and
+ * write of the resume flags, so a new cause or handoff rule is added here. The body composes
+ * the four named phases — readPriorMergeFailure, resolveResumeTarget, resumeMode and
+ * resumeCauseFor — in order. */
+function resolveRunStartDecision(opts) {
+    const s = opts.state;
+    const priorMergeFailure = readPriorMergeFailure(s);
+    const { latest, resumable, pendingResumeCause } = resolveResumeTarget(opts);
     // A budget-capped API claude run is a handback onto the fallback seam: the kept worktree must
     // survive, but the next run is a FRESH session — the fallback seam may be a different backend,
     // and claude keeps no flags across `--resume` (plans/agent-backends.md §7, part 7a/7).
     const budgetCapped = pendingResumeCause === "budget-capped";
-    const handoff = (latest !== null && !resumable) || budgetCapped;
-    s.resumePending = false;
-    s.resumeCause = undefined;
-    s.resumeMissing = undefined;
+    // An image-blind run with an image-capable peer tier ends `aborted` with this cause
+    // (plans/image-input.md part 4/5): the next run runs a FRESH session on the TARGET seam
+    // over the kept worktree — never `--continue` — because the old session carries pi's
+    // "image omitted" note and the target may be a different backend.
+    const imageReroute = pendingResumeCause === "image-reroute";
     // An interruption during the review gate leaves the author's work fully committed — there
     // is nothing left to finish in its session. Recover (and re-review) the leftover commits
     // via a fresh run instead: continuing the author session would burn a run on finished
     // work, and any uncommitted edits are the reviewer's stray output, discarded by the fresh
     // path's reset below.
     const resumeBlocked = s.phase === "review";
-    // A budget-capped handback never resumes the session whose seam the cap moved off of, even
-    // when its transcript is still resumable: it hands off instead.
-    const resuming = resumableSession && !resumeBlocked && !budgetCapped;
-    const handingOff = handoff && !resumeBlocked;
+    const { resuming, handingOff } = resumeMode(latest, resumable, budgetCapped, imageReroute, resumeBlocked);
+    s.resumePending = false;
+    s.resumeCause = undefined;
+    s.resumeMissing = undefined;
     // Reclaim the prompt the interrupted run re-queued for its resume (src/inbox/pending-prompt.ts):
     // the resumed session still owns that request in its context, so this run's bookkeeping
     // operates on the queue's copy. A handoff runs a FRESH session, so it does not reclaim — the
     // fresh run dequeues the re-queued request like any other. Consumed even when this run does
     // not resume, so a stale record never survives into a later resume.
     opts.pending.reclaimForResume(s, resuming);
-    // Why the resume: a named quiet-kill means the last run died on a stalled tool call (the
-    // bridge then warns against re-running it unchanged) or on the run deadline while still
-    // making progress (the bridge asks for the smallest finish against the same limit); a
-    // cut-off streak means the last run ran out of context and pi compacted the session (the
-    // bridge asks for the smallest finish); otherwise a shutdown/crash. A handoff names itself,
-    // except a budget-capped one, which names the cap that ended the run.
-    const resumeCause = handingOff
-        ? budgetCapped
-            ? "budget-capped"
-            : "handoff"
-        : pendingResumeCause ?? ((s.cutOffStreak ?? 0) > 0 ? "cut-off" : "restart");
-    return { priorMergeFailure, resuming, handoff: handingOff, resumeCause };
+    const resumeCause = resumeCauseFor(handingOff, budgetCapped, imageReroute, pendingResumeCause, s.cutOffStreak ?? 0);
+    return { priorMergeFailure, resuming, handoff: handingOff, resumeCause, imageReroute };
 }
 /** Build the run's prompt from the resolved decision: the resume bridge on a resume, the
- * handoff bridge on a handoff, the assembled prompt otherwise. Returns null only when a
+ * handoff bridge (with the image-reroute facts) on a handoff, the assembled prompt otherwise.
+ * Reads the image-reroute facts before consuming their flag, and returns null only when a
  * handoff/fresh assemble yields nothing. The raw user prompt is read by the caller only when a
  * prompt exists. */
 function buildRunStartPrompt(opts, d) {
+    const s = opts.state;
     const agent = opts.agent ?? "pi";
     let prompt;
     if (d.resuming) {
@@ -132,11 +170,20 @@ function buildRunStartPrompt(opts, d) {
     }
     else {
         const assembled = opts.runPrompt(agent);
+        // The image-reroute handoff note names the model the blind run was on and the image it
+        // read; those facts ride the one-shot marker, which is consumed here. A handoff's fresh
+        // session also needs the to-be-run model named for its own side of the note, but the
+        // bridge already carries the facts that matter.
+        const rerouteFacts = d.imageReroute && s.imageReroute
+            ? { from: s.imageReroute.from ?? "the prior model", path: s.imageReroute.path ?? "an image" }
+            : undefined;
+        if (d.imageReroute)
+            s.imageReroute = undefined;
         prompt =
             assembled === null
                 ? null
                 : d.handoff
-                    ? buildHandoffPrompt(opts.role, assembled, d.resumeCause)
+                    ? buildHandoffPrompt(opts.role, assembled, d.resumeCause, rerouteFacts)
                     : assembled;
     }
     return prompt;

package/dist/src/run/run-stage.js

@@ -3,7 +3,7 @@ import { changedFiles } from "../git/git-diff.js";
 import { buildCommitMessage, commitTrailer, extractCommitBody, extractSummary, summaryOverCap, fallbackSummary, formatCommitBody, appendSelfCheckNotes, stampedSubject, } from "../git/commit-message.js";
 import { logEventBestEffort } from "../events/events.js";
 import { enqueueMerge, entryRevisionFields, queuedMerges } from "../merge/merge-queue.js";
-import { hasUnmergedPin } from "../runner/leftover.js";
+import { hasUnmergedPin } from "../runner/runner-leftover.js";
 import { plural } from "../text/phrases.js";
 import { squash } from "../text/text.js";
 import { recordDismissedFiling, recordDismissedFlow } from "./run-dismiss.js";
@@ -56,75 +56,114 @@ function revisionFields(ctx) {
         : undefined;
     return { revisionRound, priorReview };
 }
+/** The bounded follow-up turn both recovery paths share: fold the follow-up's commits past the
+ * head it started from, and end the run aborted (returning the outcome to surface) when the
+ * follow-up aborted, else hand back the follow-up run. */
+async function requestSummaryFollowUp(ctx, over) {
+    const base = await headOf(ctx.wt, "HEAD");
+    const followUp = await ctx.requestSummary(ctx.wt, over);
+    await foldAgentCommitsSince(ctx, ctx.wt, base);
+    if (followUp?.aborted)
+        return { aborted: await ctx.finishAbortedRun() };
+    return { followUp };
+}
+/** Recover a summary when the reply left none: take the shared follow-up turn, refill `pending`
+ * from it, fall back to the changed paths when it still yields none, and warn about the recovery.
+ * Returns an outcome only when the follow-up aborted, else `undefined`. */
+async function recoverMissingSummary(ctx, pending) {
+    const result = await requestSummaryFollowUp(ctx);
+    if ("aborted" in result)
+        return result.aborted;
+    const followUp = result.followUp;
+    if (followUp) {
+        pending.summary = extractSummary(followUp.finalText);
+        pending.body = pending.body ?? extractCommitBody(followUp.finalText);
+    }
+    if (pending.summary === null) {
+        pending.summary = fallbackSummary(await changedFiles(ctx.wt), ctx.role, ctx.state.runs);
+        pending.summaryDerived = true;
+    }
+    ctx.warn(missingSummaryWarning(followUp, pending.summary));
+    return undefined;
+}
+/** The missing-SUMMARY warning's four-way wording: "recovered it with a follow-up turn", or the
+ * derived-subject variants naming the follow-up's failure or absence. */
+function missingSummaryWarning(followUp, summary) {
+    return (`reply had no SUMMARY line — ` +
+        (followUp && extractSummary(followUp.finalText) !== null
+            ? "recovered it with a follow-up turn"
+            : followUp && !followUp.ok
+                ? `the follow-up run failed (${followUp.errorMessage || "no error message"}); ` +
+                    `subject derived from the changed files: "${summary}"`
+                : followUp
+                    ? `follow-up gave none; subject derived from the changed files: "${summary}"`
+                    : `no follow-up session was available; subject derived from the changed files: "${summary}"`));
+}
+/** Shorten a SUMMARY the cap would cut mid-word: take the shared follow-up turn asking for it
+ * restated short, keep the restated subject when it fits, and warn. Returns an outcome only when
+ * the follow-up aborted, else `undefined`. */
+async function shortenOverCapSummary(ctx, pending) {
+    const over = summaryOverCap(ctx.finalText);
+    if (over === null)
+        return undefined;
+    // A SUMMARY the cap would cut mid-word gets one follow-up turn asking for it restated short.
+    const result = await requestSummaryFollowUp(ctx, over);
+    if ("aborted" in result)
+        return result.aborted;
+    const followUp = result.followUp;
+    const short = followUp && summaryOverCap(followUp.finalText) === null ? extractSummary(followUp.finalText) : null;
+    if (short !== null) {
+        pending.summary = short;
+        pending.body = pending.body ?? extractCommitBody(followUp.finalText);
+    }
+    ctx.warn(short !== null
+        ? `SUMMARY was ${over} characters — shortened with a follow-up turn`
+        : `SUMMARY was ${over} characters — follow-up gave no shorter one; subject truncated`);
+    return undefined;
+}
 /** Derive the commit's subject and body from the reply's SUMMARY block, running one bounded
  * follow-up turn when the reply left none or a SUMMARY the cap would cut mid-word. Returns the
  * aborted-run outcome when a follow-up aborts, otherwise the description. */
 async function resolveCommitDescription(ctx) {
-    const s = ctx.state;
     // The commit subject and body come from the reply's closing block. A run that changed files
     // without one — a cut-off final message, or plain non-compliance — gets one bounded follow-up
     // turn in its own session to produce it (the session still holds everything the run did);
     // only if that too yields nothing is the subject derived from the changed paths.
-    let summary = extractSummary(ctx.finalText);
-    let body = extractCommitBody(ctx.finalText);
-    // True when no reply named the change, so the subject below is derived from its paths.
-    let summaryDerived = false;
-    if (summary === null) {
-        const base = await headOf(ctx.wt, "HEAD");
-        const followUp = await ctx.requestSummary(ctx.wt);
-        await foldAgentCommitsSince(ctx, ctx.wt, base);
-        if (followUp?.aborted)
-            return ctx.finishAbortedRun();
-        if (followUp) {
-            summary = extractSummary(followUp.finalText);
-            body = body ?? extractCommitBody(followUp.finalText);
-        }
-        if (summary === null) {
-            summary = fallbackSummary(await changedFiles(ctx.wt), ctx.role, s.runs);
-            summaryDerived = true;
-        }
-        ctx.warn(`reply had no SUMMARY line — ` +
-            (followUp && extractSummary(followUp.finalText) !== null
-                ? "recovered it with a follow-up turn"
-                : followUp && !followUp.ok
-                    ? `the follow-up run failed (${followUp.errorMessage || "no error message"}); ` +
-                        `subject derived from the changed files: "${summary}"`
-                    : followUp
-                        ? `follow-up gave none; subject derived from the changed files: "${summary}"`
-                        : `no follow-up session was available; subject derived from the changed files: "${summary}"`));
-    }
-    else {
-        // A SUMMARY the cap would cut mid-word gets one follow-up turn asking for it restated short.
-        const over = summaryOverCap(ctx.finalText);
-        if (over !== null) {
-            const base = await headOf(ctx.wt, "HEAD");
-            const followUp = await ctx.requestSummary(ctx.wt, over);
-            await foldAgentCommitsSince(ctx, ctx.wt, base);
-            if (followUp?.aborted)
-                return ctx.finishAbortedRun();
-            const short = followUp && summaryOverCap(followUp.finalText) === null ? extractSummary(followUp.finalText) : null;
-            if (short !== null) {
-                summary = short;
-                body = body ?? extractCommitBody(followUp.finalText);
-            }
-            ctx.warn(short !== null
-                ? `SUMMARY was ${over} characters — shortened with a follow-up turn`
-                : `SUMMARY was ${over} characters — follow-up gave no shorter one; subject truncated`);
-        }
-    }
-    return { summary, body, summaryDerived };
+    const pending = {
+        summary: extractSummary(ctx.finalText),
+        body: extractCommitBody(ctx.finalText),
+        // True when no reply named the change, so the subject below is derived from its paths.
+        summaryDerived: false,
+    };
+    const outcome = pending.summary === null
+        ? await recoverMissingSummary(ctx, pending)
+        : await shortenOverCapSummary(ctx, pending);
+    if (outcome)
+        return outcome;
+    return { summary: pending.summary, body: pending.body, summaryDerived: pending.summaryDerived };
 }
-/** Run the gate's deterministic backlog checks before the commit, giving the author's session
+/** Run the gate's remaining checks before the commit, giving the author's session
  * one bounded fix-up turn, and end the run `no_change` when the fix-up reverts the whole change
  * (leaving nothing to commit). Returns an outcome only when the run must end early; otherwise
  * mutates `desc.summary`/`desc.body` with any fix-up recovery, exactly as the inline block did. */
 async function runStageSelfCheck(ctx, desc) {
-    const s = ctx.state;
-    // The gate's deterministic backlog checks run here, before the commit, while the authoring
-    // session can still be continued: a finding that reaches review costs a queue slot,
-    // a verification, and a rejection that discards the work. One bounded follow-up turn on the
-    // author's own session gets to fix them; the gate still has the final say, and the change commits
-    // and queues either way.
+    // The gate's remaining checks (a protected edit, a leaked credential) run here, before the
+    // commit, while the authoring session can still be continued: a finding that reaches review
+    // costs a queue slot, a verification, and a rejection that discards the work. One bounded
+    // follow-up turn on the author's own session gets to fix them, and the change commits and
+    // queues either way.
+    const moved = await stagedBacklogMoves(ctx);
+    const movedFindings = recordStagedClaims(ctx, moved);
+    const findings = await ctx.stageCheck(ctx.wt);
+    findings.push(...movedFindings);
+    if (findings.length === 0)
+        return undefined;
+    return applyStageFixUp(ctx, desc, findings);
+}
+/** Decide whether this is a claim-staging run and, if so, read the backlog entries its diff moved
+ * out of their actionable section (plans/parallel-work-instances.md "Claims", part 4/7). Returns
+ * `[]` for every non-claim-staging run and on any unreadable file or git hiccup. */
+async function stagedBacklogMoves(ctx) {
     // Claims made at staging (plans/parallel-work-instances.md "Claims", part 4/7): an
     // unassigned run of a MULTI-instance base whose diff moved a backlog entry out of its
     // actionable section records the claim so a sibling is not assigned it while this change
@@ -139,6 +178,13 @@ async function runStageSelfCheck(ctx, desc) {
         configuredInstances(ctx.config, ctx.role) > 1
         ? await stagedMovedEntries(ctx.wt, ctx.mainBranch, ctx.role).catch(() => [])
         : [];
+    return moved;
+}
+/** Record the run's staged claim for the first claimable moved entry (when it has none yet) and
+ * return the moved-entry findings in the order the inline body pushed them: `assignedMoved`
+ * first, then `heldMoved`. */
+function recordStagedClaims(ctx, moved) {
+    const s = ctx.state;
     const heldBySiblings = new Set(s.claim === undefined ? (s.heldElsewhere ?? []).map(entryKey) : []);
     const heldMoved = heldMovedFinding(heldBySiblings, moved);
     const claimable = moved.filter((m) => !heldBySiblings.has(m.key));
@@ -157,45 +203,50 @@ async function runStageSelfCheck(ctx, desc) {
         });
     }
     const assignedMoved = s.claim ? assignedMovedFinding(s.claim.key, moved) : undefined;
-    const findings = await ctx.stageCheck(ctx.wt);
+    const findings = [];
     if (assignedMoved)
         findings.push(assignedMoved);
     if (heldMoved)
         findings.push(heldMoved);
-    if (findings.length > 0) {
-        const before = findings.length;
-        const fixBase = await headOf(ctx.wt, "HEAD");
-        const fixUp = await ctx.requestStageFix(ctx.wt, findings, {
-            summary: desc.summaryDerived ? null : desc.summary,
-            body: desc.body ? formatCommitBody(desc.body) : "",
-        });
-        await foldAgentCommitsSince(ctx, ctx.wt, fixBase);
-        if (fixUp?.aborted)
+    return findings;
+}
+/** Run the author's one bounded fix-up turn over the stage findings, fold its commits, recover
+ * `desc.summary`/`desc.body` from the reply, and end the run `no_change` when the follow-up left
+ * the worktree clean; otherwise stage-check again and log the outcome warning. Returns an outcome
+ * only when it ends the run early, else `undefined`. */
+async function applyStageFixUp(ctx, desc, findings) {
+    const before = findings.length;
+    const fixBase = await headOf(ctx.wt, "HEAD");
+    const fixUp = await ctx.requestStageFix(ctx.wt, findings, {
+        summary: desc.summaryDerived ? null : desc.summary,
+        body: desc.body ? formatCommitBody(desc.body) : "",
+    });
+    await foldAgentCommitsSince(ctx, ctx.wt, fixBase);
+    if (fixUp) {
+        if (fixUp.aborted)
             return ctx.finishAbortedRun();
-        if (fixUp) {
-            // The fix-up reply answers the findings, not the change, so it never replaces the
-            // change's description (BUGS.md 2026-10-21): its SUMMARY is taken only over a subject
-            // derived from the paths, and its RISK/VERIFIED are appended as self-check notes.
-            const fixSummary = desc.summaryDerived ? extractSummary(fixUp.finalText) : null;
-            if (fixSummary !== null)
-                desc.summary = fixSummary;
-            desc.body = appendSelfCheckNotes(desc.body, extractCommitBody(fixUp.finalText));
-        }
-        // A fix-up turn may resolve its findings by reverting the whole change. With nothing left
-        // in the worktree there is nothing to commit or queue: end the run no_change here instead
-        // of handing a clean tree to commitAll. The worktree is left clean and no pin is taken.
-        // isDirty, not changedFiles: a `git status` that fails must throw, not read as clean — on
-        // 2026-10-21 a spawn failure here ended bugfix-2's 17-minute run no_change and released
-        // its edits unpinned; thrown, the run ends unsettled and its next run gets them back.
-        if (!(await isDirty(ctx.wt))) {
-            logSelfCheckOutcome(ctx, "stage self-check: the follow-up turn left no change; nothing to land", findings);
-            return { result: "no_change" };
-        }
-        const remaining = await ctx.stageCheck(ctx.wt);
-        logSelfCheckOutcome(ctx, remaining.length === 0
-            ? `stage self-check: ${plural(before, "finding")} — fixed by the follow-up turn`
-            : `stage self-check: ${plural(before, "finding")}; ${remaining.length} still open, queued for the gate`, findings, remaining);
+        // The fix-up reply answers the findings, not the change, so it never replaces the
+        // change's description (BUGS.md 2026-10-21): its SUMMARY is taken only over a subject
+        // derived from the paths, and its RISK/VERIFIED are appended as self-check notes.
+        const fixSummary = desc.summaryDerived ? extractSummary(fixUp.finalText) : null;
+        if (fixSummary !== null)
+            desc.summary = fixSummary;
+        desc.body = appendSelfCheckNotes(desc.body, extractCommitBody(fixUp.finalText));
+    }
+    // A fix-up turn may resolve its findings by reverting the whole change. With nothing left
+    // in the worktree there is nothing to commit or queue: end the run no_change here instead
+    // of handing a clean tree to commitAll. The worktree is left clean and no pin is taken.
+    // isDirty, not changedFiles: a `git status` that fails must throw, not read as clean — on
+    // 2026-10-21 a spawn failure here ended bugfix-2's 17-minute run no_change and released
+    // its edits unpinned; thrown, the run ends unsettled and its next run gets them back.
+    if (!(await isDirty(ctx.wt))) {
+        logSelfCheckOutcome(ctx, "stage self-check: the follow-up turn left no change; nothing to land", findings);
+        return { result: "no_change" };
     }
+    const remaining = await ctx.stageCheck(ctx.wt);
+    logSelfCheckOutcome(ctx, remaining.length === 0
+        ? `stage self-check: ${plural(before, "finding")} — fixed by the follow-up turn`
+        : `stage self-check: ${plural(before, "finding")}; ${remaining.length} still open, queued for the gate`, findings, remaining);
     return undefined;
 }
 /** Compute the run's friction signal over this run's pre-commit authoring runs: minutes of wall

package/dist/src/run/run-timing.js

@@ -89,16 +89,22 @@ export async function runTimedRoleRun(signal, acquire, release, run, now = Date.
 /** Sleep up to ms, but wake immediately when `signal` aborts — so shutdown (SIGTERM →
  * abort) is prompt instead of waiting out the current poll cycle. The listener is removed
  * on either exit path so long-running orchestrators don't accumulate one per poll, and an
- * already-aborted signal returns synchronously through runOnAbort. Exported as a unit-test
+ * already-aborted signal returns synchronously through runOnAbort. Without a signal it is a
+ * plain setTimeout sleep. The review gate's retry wait (src/review/review.ts, whose signal is
+ * optional) shares this helper rather than keeping a second copy. Exported as a unit-test
  * seam, like runTimedRoleRun above. */
 export function sleepInterruptible(ms, signal) {
     return new Promise((resolve) => {
+        if (signal === undefined) {
+            setTimeout(resolve, ms);
+            return;
+        }
         const onAbort = () => {
             clearTimeout(timer);
             resolve();
         };
         const timer = setTimeout(() => {
-            signal.removeEventListener("abort", onAbort);
+            signal?.removeEventListener("abort", onAbort);
             resolve();
         }, ms);
         runOnAbort(signal, onAbort);

package/dist/src/run/run-usage.js

@@ -108,9 +108,24 @@ export class RunUsage {
      * through foldMergeUsage: those never advance the run's pre-edit counter, which measures
      * the authoring search. */
     fold(s, run, authoring = true, provider, pair) {
+        this.foldLifetimeTotals(s, run);
+        this.foldCost(s, run, provider, pair);
+        this.foldAccount(run);
+        this.foldPromptTokens(run, authoring);
+        this.turns += run.turns;
+        this.foldEpisodes(run, provider);
+    }
+    /** Grow the role's lifetime totals on `s` from this run: its generated tokens and the real
+     * spend both accumulate through the healed counter, and the peak context is the new max. */
+    foldLifetimeTotals(s, run) {
         s.generatedTokens = counter(s.generatedTokens) + run.outputTokens;
         s.peakContextTokens = Math.max(counter(s.peakContextTokens), run.peakContextTokens);
         s.totalCostUsd = counter(s.totalCostUsd) + run.costUsd;
+    }
+    /** Split this run's cost real from notional: a subscription run's cost is notional and never
+     * charges the daily cap; an API run's — or a run that ever saw overage — is real money.
+     * totalCostUsd still counts both: it is lifetime usage, not a budget figure. */
+    foldCost(s, run, provider, pair) {
         // The billing split (plans/agent-backends.md §7): a subscription run's cost is notional
         // and never charges the daily cap; an API run's — or a run that ever saw overage — is real
         // money. totalCostUsd still counts both: it is lifetime usage, not a budget figure.
@@ -126,12 +141,21 @@ export class RunUsage {
             this.notionalCostUsd += run.costUsd;
             this.bumpProviderCost(provider, run.costUsd, 'notionalCostUsd');
         }
+    }
+    /** Carry the newest account readings this run reported: the billing state, the subscription
+     * rate windows, and the agent they came from (whose name is only meaningful beside them). */
+    foldAccount(run) {
         if (run.billing !== undefined)
             this.billing = run.billing;
         if (run.rateWindows !== undefined)
             this.rateWindows = run.rateWindows;
         if (run.billing !== undefined || run.rateWindows !== undefined)
             this.agent = run.agent;
+    }
+    /** Advance the token counters: the prompt and cache-read shares count every run, while the
+     * pre-edit prefix freezes at the first edit — authoring-only, and skipped for a merge/review
+     * run. */
+    foldPromptTokens(run, authoring) {
         this.promptTokens += run.promptTokens;
         this.cacheReadTokens += run.cacheReadTokens;
         // The pre-edit prefix freezes at the run's first edit: every authoring run while no edit
@@ -143,7 +167,13 @@ export class RunUsage {
             if (run.firstEditTurn !== undefined)
                 this.editSeen = true;
         }
-        this.turns += run.turns;
+    }
+    /** Stamp the team-wide hold's failure observations for a run that ENDED on them: pi exits on
+     * a 429 or backend error, so "now" is when the provider refused. A run that merely logged one
+     * inside pi's own auto-retry and then finished would stamp a false observation, possibly hours
+     * late. The backend kind travels with its stamp (src/pi/pi-failure.ts classified the text at
+     * parse time); a 429 never ends up here — pi-stream checks rate-limit first. */
+    foldEpisodes(run, provider) {
         // The team-wide hold's rate-limit input (lastRateLimit above), from the same
         // once-per-run choke point. Only a run that ENDED on the 429 counts: pi exits on the error,
         // so "now" is when the provider refused — a run that merely logged one inside pi's own