tumwater 0.4.2 → 0.4.3

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

@@ -57,15 +57,11 @@ export function newestRunRow(root, role, classes, models) {
 function newestRunNumber(root, role, classes, models) {
     return newestRunRow(root, role, classes, models)?.run ?? null;
 }
-/** The invocation half of cmdRunDetail: rule out the arity and flag mistakes before any run is
- * resolved, so the shared unknown-role wording and the usage string are the whole validation
- * surface, found by this one name. Succeeds only for a well-formed call; returns the parsed
- * bare/role/classes/models for the resolver. The role is checked first, so a typo is named
- * whatever the count (knownRoleIdsCached: the built-ins plus user-defined roles, read through
- * the never-throwing cached loader so a transiently broken tumwater.json cannot take a
- * read-only view down). The arity, unknown-role and flag-dependency failures all `fail` with
- * the usage. */
-function parseRunDetailInvocation(root, positionals, { last, transcript, prompt, grep, result, model }) {
+/** The positional and role half of parseRunDetailInvocation's validation: the bare/last arity,
+ * the canonical role id, the unknown-role guard (knownRoleIdsCached) and the three arity
+ * `fail`s — one name so the whole positional surface is found by this helper. Returns whether
+ * the call is bare (`--last` with no role) and the resolved role. */
+function runDetailPositionals(root, positionals, last) {
     // Positional arity by form: cli.ts has already peeled the flags off and gated them (only
     // --json and --last are admitted), so anything left over that does not fit the chosen form
     // is a mistake. The role is checked first, so a typo is named whatever the count; then
@@ -91,6 +87,13 @@ function parseRunDetailInvocation(root, positionals, { last, transcript, prompt,
         }
         fail(`usage: ${RUN_DETAIL_USAGE}`);
     }
+    return { bare, role };
+}
+/** The flag-dependency half of parseRunDetailInvocation's validation: the four `fail` guards —
+ * `--prompt`/`--grep` need `--transcript`, `--result`/`--model` need `--last` — one name so the
+ * whole dependency surface is found by this helper. */
+function checkRunDetailFlagDeps(flags) {
+    const { last, transcript, prompt, grep, result, model } = flags;
     if (prompt && !transcript)
         fail(`history --prompt needs --transcript (usage: ${RUN_DETAIL_USAGE})`);
     if (grep !== null && !transcript)
@@ -99,10 +102,67 @@ function parseRunDetailInvocation(root, positionals, { last, transcript, prompt,
         fail(`history --result needs --last on a one-run trail (usage: ${RUN_DETAIL_USAGE})`);
     if (model !== null && !last)
         fail(`history --model needs --last on a one-run trail (usage: ${RUN_DETAIL_USAGE})`);
+}
+/** The invocation half of cmdRunDetail: rule out the arity and flag mistakes before any run is
+ * resolved, so the shared unknown-role wording and the usage string are the whole validation
+ * surface, found by this one name. Succeeds only for a well-formed call; returns the parsed
+ * bare/role/classes/models for the resolver. Delegates the positional/role arity to
+ * runDetailPositionals and the flag-dependency guards to checkRunDetailFlagDeps, then parses
+ * the --result class and --model selector lists. */
+function parseRunDetailInvocation(root, positionals, { last, transcript, prompt, grep, result, model }) {
+    const { bare, role } = runDetailPositionals(root, positionals, last);
+    checkRunDetailFlagDeps({ last, transcript, prompt, grep, result, model });
     const classes = result !== null ? parseHistoryResultList(result) : null;
     const models = model !== null ? parseHistoryModelList(model) : null;
     return { bare, role, classes, models };
 }
+/** The not-found branch of cmdRunDetail for the --last form: the scan came up empty, not found
+ * by construction, the last-form wording — `sayJson(null)` under --json, else
+ * runNotFoundLastMessage. */
+function runDetailLastMiss(parsed, role, json) {
+    // The --last scan came up empty: not found by construction, the last-form wording.
+    if (json)
+        sayJson(null);
+    else
+        say(runNotFoundLastMessage(parsed.bare ? null : role, parsed.classes, parsed.models));
+}
+/** The not-found branch of cmdRunDetail for the numbered form: not found stays exit 0 in both
+ * renderings, but --json still owes a parseable document in every exit-0 case (`null`), else
+ * the runNotFoundMessage prose line. */
+function runDetailNumberMiss(role, runNumber, json) {
+    // Not found stays exit 0 in both renderings, but --json still owes a parseable document in
+    // every exit-0 case (the report --json precedent, the invariant this command's own doc
+    // comment claims): `null` is the JSON answer for a single-record lookup that missed — the
+    // prose line would end a jq pipe mid-team-incident.
+    if (json)
+        sayJson(null);
+    else
+        say(runNotFoundMessage(role, runNumber));
+}
+/** The render half of cmdRunDetail: build the --stat/--patch footer and the --transcript lines,
+ * then emit the --json payload or the human-rendered trail (renderRunDetail plus the footer and
+ * transcript text). */
+async function emitRunDetail(root, role, runNumber, detail, json, opts) {
+    // --json swaps the renderer for the collector's own payload, exactly as history --json: a
+    // JSON document in every exit-0 case, never prose.
+    const footer = {};
+    if (opts.stat)
+        footer.stat = await runDetailStat(root, detail);
+    if (opts.patch)
+        footer.patch = await runDetailPatch(root, detail);
+    const transcriptLines = opts.transcript
+        ? runTranscriptLines(root, role, runNumber, detail, { includePrompts: opts.prompt, grep: opts.grep ?? undefined })
+        : null;
+    if (json) {
+        sayJson({ ...detail, ...footer, ...(transcriptLines === null ? {} : { transcript: transcriptLines.found }) });
+    }
+    else {
+        const transcriptText = transcriptLines === null
+            ? []
+            : [transcriptLines.found.length > 0 ? transcriptLines.found.join("\n") : transcriptLines.note];
+        say([renderRunDetail(detail), ...Object.values(footer), ...transcriptText].join("\n\n"));
+    }
+}
 /** The resolution half of cmdRunDetail: pick the run to open and read its detail. Bare `--last`
  * takes the newest run of any role (its role from the row); `--last` with a role the newest run
  * by number; the numbered path the user's positive integer. An empty or unreadable scan is null
@@ -150,41 +210,12 @@ export async function cmdRunDetail(root, positionals, json, { last = false, stat
     const parsed = parseRunDetailInvocation(root, positionals, { last, transcript, prompt, grep, result, model });
     const { role, runNumber, detail } = resolveRunDetailTarget(root, parsed, positionals, last);
     if (runNumber === null) {
-        // The --last scan came up empty: not found by construction, the last-form wording.
-        if (json)
-            sayJson(null);
-        else
-            say(runNotFoundLastMessage(parsed.bare ? null : role, parsed.classes, parsed.models));
+        runDetailLastMiss(parsed, role, json);
         return;
     }
     if (detail === null) {
-        // Not found stays exit 0 in both renderings, but --json still owes a parseable document in
-        // every exit-0 case (the report --json precedent, the invariant this command's own doc
-        // comment claims): `null` is the JSON answer for a single-record lookup that missed — the
-        // prose line would end a jq pipe mid-team-incident.
-        if (json)
-            sayJson(null);
-        else
-            say(runNotFoundMessage(role, runNumber));
+        runDetailNumberMiss(role, runNumber, json);
         return;
     }
-    // --json swaps the renderer for the collector's own payload, exactly as history --json: a
-    // JSON document in every exit-0 case, never prose.
-    const footer = {};
-    if (stat)
-        footer.stat = await runDetailStat(root, detail);
-    if (patch)
-        footer.patch = await runDetailPatch(root, detail);
-    const transcriptLines = transcript
-        ? runTranscriptLines(root, role, runNumber, detail, { includePrompts: prompt, grep: grep ?? undefined })
-        : null;
-    if (json) {
-        sayJson({ ...detail, ...footer, ...(transcriptLines === null ? {} : { transcript: transcriptLines.found }) });
-    }
-    else {
-        const transcriptText = transcriptLines === null
-            ? []
-            : [transcriptLines.found.length > 0 ? transcriptLines.found.join("\n") : transcriptLines.note];
-        say([renderRunDetail(detail), ...Object.values(footer), ...transcriptText].join("\n\n"));
-    }
+    await emitRunDetail(root, role, runNumber, detail, json, { stat, patch, transcript, prompt, grep });
 }

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

@@ -23,7 +23,7 @@ import { readFeedbackFilings, renderFilingsBlock } from "./feedback-filings.js";
 import { roleNotesPath } from "../paths.js";
 import * as path from "node:path";
 import { pathTokens } from "../text/text.js";
-import { isDirectory, readTextOrNull, statOrNull } from "../files/files.js";
+import { isDirectory, readRegularTextOrNull, readTextOrNull, statOrNull } from "../files/files.js";
 import { dayKey } from "../text/datetime.js";
 import { appendPromptNote, prependPromptNote } from "../text/format.js";
 import { ROLE_NOTES_MAX_BYTES } from "../agent/role-notes-write.js";
@@ -55,9 +55,11 @@ function missingEntryPaths(root, file, range) {
  * brief text reader apply to their hand-editable files. A UTF-8 character is never
  * fewer than one byte, so a note the tool accepted (≤ 4096 bytes) is always ≤ 4096 chars
  * and never trips this bound; only an over-cap file is cut, with truncateWithNote's visible
- * marker naming the loss. */
+ * marker naming the loss. A symlinked note file reads as absent (readRegularTextOrNull never
+ * follows a symlink out of the worktree, INV-G3/G4's lstat policy): a hostile note that is a
+ * symlink cannot pull an arbitrary host file's text into this role's prompt. */
 function readRoleNote(root, role) {
-    const text = readTextOrNull(roleNotesPath(root, role));
+    const text = readRegularTextOrNull(roleNotesPath(root, role));
     return text === null ? undefined : truncateWithNote(text, ROLE_NOTES_MAX_BYTES, "role notes");
 }
 /** The bugfix run's tally of checks the merge gate excused as flaky in the last day, or
@@ -199,55 +201,40 @@ function collectRoleRequest(root, role, preview) {
 function collectSelfcheckDigest(root, base) {
     return base === "selfcheck" || base === "feedback" ? selfcheckDigest(root) : undefined;
 }
-/** The `qa` observer's flow-coverage ledger: rerendered from disk each run, degrading to no
- * block on a missing or unreadable ledger (plans/observer-roles.md 2/2). */
-function collectQaCoverageBlock(root, base) {
-    // The `qa` observer's flow rotation needs a memory of what it last exercised; every run
-    // is a fresh session, and a passing cheap check leaves nothing in the repo. The ledger is
-    // runtime state, and a missing or unreadable one degrades to no block.
-    let coverage;
-    if (base === "qa") {
-        try {
-            coverage = renderCoverageBlock(readQaCoverage(root));
-        }
-        catch {
-            coverage = undefined;
-        }
+/** One observer-ledger block: rendered from disk only for its owning role, degrading to no
+ * block on a missing or unreadable ledger (a throw) so the run prompt stays byte-unchanged in
+ * the common first-run case. The `qa` (flow coverage), `ci` (parity) and `feedback` (filings)
+ * ledgers are runtime state a fresh session must not depend on, and the three collect*Block
+ * functions each rendered their ledger through this same try/catch guard before the helper. */
+function runtimeLedgerBlock(base, role, render) {
+    if (base !== role)
+        return undefined;
+    try {
+        return render();
+    }
+    catch {
+        return undefined;
     }
-    return coverage;
 }
-/** The `ci` observer's parity block: what the last run covered (tip and lock hash) so a
- * fresh session can decide nothing-to-do without re-running the whole suite (part 3/3).
- * Runtime state, and a missing/unreadable record degrades to no block, exactly like qa's. */
+/** The `qa` observer's flow-coverage ledger, rerendered from disk each run (the flow rotation
+ * needs a memory of what it last exercised — every run is a fresh session, and a passing cheap
+ * check leaves nothing in the repo), degrading to no block (plans/observer-roles.md 2/2). */
+function collectQaCoverageBlock(root, base) {
+    return runtimeLedgerBlock(base, "qa", () => renderCoverageBlock(readQaCoverage(root)));
+}
+/** The `ci` observer's parity block: what the last run covered (tip and lock hash) so a fresh
+ * session can decide nothing-to-do without re-running the whole suite (part 3/3). Degrades to
+ * no block exactly like qa's. */
 function collectCiParityBlock(root, config, base) {
-    let ciParity;
-    if (base === "ci") {
-        try {
-            ciParity = parityBlockFor(root, config);
-        }
-        catch {
-            ciParity = undefined;
-        }
-    }
-    return ciParity;
+    return runtimeLedgerBlock(base, "ci", () => parityBlockFor(root, config));
 }
 /** The `feedback` observer's per-install filing ledger: what this install already filed as
  * GitHub issues on znation/tumwater, so the fresh session's charter dedupes against a
- * "previously filed" block instead of the network alone. Runtime state, and a missing or
- * unreadable ledger degrades to no block (plans/feedback-role.md 2/2). */
+ * "previously filed" block instead of the network alone. Degrades to no block
+ * (plans/feedback-role.md 2/2); the render returns undefined for an empty ledger, so the
+ * prompt is unchanged in the common first-run case. */
 function collectFeedbackFilingsBlock(root, base) {
-    // The render returns undefined for an empty ledger, so the prompt is unchanged in the common
-    // first-run case.
-    let filings;
-    if (base === "feedback") {
-        try {
-            filings = renderFilingsBlock(readFeedbackFilings(root));
-        }
-        catch {
-            filings = undefined;
-        }
-    }
-    return filings;
+    return runtimeLedgerBlock(base, "feedback", () => renderFilingsBlock(readFeedbackFilings(root)));
 }
 /** The clean role's deterministic backlog repair: stranded plan headings in the primary
  * checkout's PLANS.md (plans, part 3/4), rendered like the digest and coverage blocks. */
@@ -258,7 +245,7 @@ function collectBacklogStructureBlock(root, base) {
 /** Read the role's own notes plus their saved day and live backlog state (notes-backlog.ts),
  * returning all three in one place. */
 function readPromptNotes(root, role) {
-    // The role's notes (PLANS.md "Role notebook"): its own earlier runs' note. A missing,
+    // The role's own notes (readRoleNote): its earlier runs' note. A missing,
     // empty, or unreadable file yields undefined, so the block is omitted; the write
     // instruction in buildRunPrompt is present either way. The director branch above never
     // reads this path, so it carries no notes.
@@ -312,15 +299,12 @@ function collectRoleDirectives(root, config, base, check) {
         : undefined;
     return { planTargetNote, flakyChecks, noCheck };
 }
-/** Append the shared claim/held/discard/cut-off tail — identical for a director and a role —
- * in its current order, and return the finished prompt. */
-function appendRunEpilogue(root, role, state, prompt, userPrompt, rejectedReview) {
+function appendAssignmentNotes(prompt, root, role, claim, userPrompt) {
     // A work instance holding a claim is told which entry is its one task (plans/parallel-work-
     // instances.md "Claims", part 4/7) — the harness picked it, so the charter's choosing step
     // is replaced. A run that dequeued a user request runs that request instead and keeps the
     // claim for the next non-request run. The range is looked up by key in the current checkout,
     // so it survives a moved section boundary.
-    const claim = role === DIRECTOR_ROLE ? undefined : state.claim;
     if (claim && userPrompt === null) {
         const range = eligibleEntries(root, role).find((e) => e.key === claim.key);
         prompt = appendPromptNote(prompt, buildAssignmentNote(claim, range, range ? missingEntryPaths(root, claim.file, range) : []));
@@ -328,20 +312,32 @@ function appendRunEpilogue(root, role, state, prompt, userPrompt, rejectedReview
         if (merged.length > 0)
             prompt = appendPromptNote(prompt, buildMergedPrerequisitesNote(merged));
     }
+    return prompt;
+}
+function appendWaitingPartsNote(prompt, root, claim, userPrompt) {
     if (claim && userPrompt === null && claim.file === "PLANS.md") {
         const waiting = waitingPartRanges(root, claim.title);
         if (waiting.length > 0)
             prompt = appendPromptNote(prompt, buildWaitingPartsNote(waiting));
     }
+    return prompt;
+}
+function appendHeldElsewhereNote(prompt, role, claim, userPrompt, state) {
     if (!claim && userPrompt === null && role !== DIRECTOR_ROLE && state.heldElsewhere?.length) {
         prompt = appendPromptNote(prompt, buildHeldEntriesNote(state.heldElsewhere));
     }
+    return prompt;
+}
+function prependRejectedReviewNote(prompt, role, rejectedReview) {
     // The director builds its prompt through buildDirectorPrompt, which does not take the rejected
     // note, so the standing rejection leads its prompt here instead (a director-authored change can
     // be rejected too). Kept uniform with the authoring roles: the reasons open the run.
     if (rejectedReview !== undefined && role === DIRECTOR_ROLE) {
         prompt = prependPromptNote(prompt, rejectedReview);
     }
+    return prompt;
+}
+function appendRunMemoryNotes(prompt, state) {
     // Likewise a change leftover recovery discarded as unmergeable: named until the role queues
     // its next change (the discarding run itself appends it after recovery — see runOnce).
     const discard = state.conflictDiscard;
@@ -355,6 +351,23 @@ function appendRunEpilogue(root, role, state, prompt, userPrompt, rejectedReview
     }
     return prompt;
 }
+/** Append the shared claim/held/discard/cut-off tail — identical for a director and a role —
+ * in its current order, and return the finished prompt. It delegates each note group to a
+ * named module-private helper: appendAssignmentNotes (which folds in the merged-prerequisite
+ * follow-up), appendWaitingPartsNote, appendHeldElsewhereNote, prependRejectedReviewNote and
+ * appendRunMemoryNotes. */
+function appendRunEpilogue(root, role, state, prompt, userPrompt, rejectedReview) {
+    // The shared cross-run tail every role prompt carries, ordinally: the claim assignment (with
+    // its merged-prerequisite and waiting-part follow-ups), the held-elsewhere note, the
+    // director's leading rejection, and the discard and cut-off run memory.
+    const claim = role === DIRECTOR_ROLE ? undefined : state.claim;
+    prompt = appendAssignmentNotes(prompt, root, role, claim, userPrompt);
+    prompt = appendWaitingPartsNote(prompt, root, claim, userPrompt);
+    prompt = appendHeldElsewhereNote(prompt, role, claim, userPrompt, state);
+    prompt = prependRejectedReviewNote(prompt, role, rejectedReview);
+    prompt = appendRunMemoryNotes(prompt, state);
+    return prompt;
+}
 /** Assemble the prompt a role's next run operates on — the whole "what should this run see"
  * concern, split out of runner.ts so the runner owns only lifecycle and the prompt owns only
  * content. Returns null when the role has nothing to run this run (a director with an empty

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;