tumwater 0.4.2 → 0.4.4

package/dist/src/process/run-marker.js

@@ -4,14 +4,14 @@
  * probe's runMarkers check and doctor's orphan judgment), and the sweep that SIGTERMs
  * this run's leftovers whatever process group they ended up in. Split out of
  * process-table.ts — which keeps the doctor-facing probe interface and the ps/lsof/top
- * parsing it is made of — because this half serves src/agent/run-spawn.ts's run stamping and
+ * parsing it is made of — because this half serves src/agent/agent-spawn.ts's run stamping and
  * the exit sweep, and shares none of the probe's table-parsing concerns; the probe reads marks
  * through the same parsers exported here. */
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { plural } from "../text/phrases.js";
-import { execFileAsync, withoutLaunchServicesCheckIn } from "./process.js";
+import { agree, plural } from "../text/phrases.js";
+import { execFileAsync, KILL_GRACE_MS, withoutLaunchServicesCheckIn } from "./process.js";
 /** Every lookup normally finishes in well under a second; a wedged one must not hang
  * its caller — the same ceiling process-table.ts's probe lookups carry. */
 const PS_ENVIRON_TIMEOUT_MS = 10_000;
@@ -22,14 +22,33 @@ const PS_ENVIRON_TIMEOUT_MS = 10_000;
  * command `detached`, a group leader in its own right, so a backgrounded grandchild sits in
  * a group whose leader is not pi and the group sweep's kill(-pi.pid) never reaches it. */
 const RUN_MARKER_VAR = "TUMWATER_RUN";
-/** A fresh marker for one pi run: `<harness pid>-<random hex>`. The pid prefix is what a
- * reader of a leaked process's environment needs to tell a live run's straggler (its own
- * sweep will reap it at exit) from a dead run's orphan (nothing will): a future doctor check
- * can report the latter wherever the leak's cwd is. The random half makes the marker unique
- * per run, so one run's sweep can never signal a concurrent sibling run's processes — a
- * machine running the team has several pi runs alive at once. */
-export function makeRunMarker(pid = process.pid) {
-    return `${pid}-${crypto.randomBytes(6).toString("hex")}`;
+/** The first 8 hex of sha1 of `root`'s realpath — the short stable token that names a team
+ * root inside a run marker's third segment, so a dead-marked orphan can be attributed to the
+ * checkout that minted it (BUGS.md, "Reap the doctor's orphans, part 1/3"). Realpath-resolving
+ * first keeps two spellings of one root (e.g. macOS's /var vs /private/var) hashing identically;
+ * an unreadable root realpaths to its resolved given path. */
+export function rootToken(root) {
+    const resolved = path.resolve(root);
+    let real;
+    try {
+        real = fs.realpathSync(resolved);
+    }
+    catch {
+        real = resolved;
+    }
+    return crypto.createHash("sha1").update(real).digest("hex").slice(0, 8);
+}
+/** A fresh marker for one pi run: `<harness pid>-<random hex>` (`<rootToken>` appended when a
+ * team `root` is given). The pid prefix is what a reader of a leaked process's environment needs
+ * to tell a live run's straggler (its own sweep will reap it at exit) from a dead run's orphan
+ * (nothing will): a future doctor check can report the latter wherever the leak's cwd is. The
+ * random half makes the marker unique per run, so one run's sweep can never signal a concurrent
+ * sibling run's processes — a machine running the team has several pi runs alive at once. The
+ * optional root token stamps the team root the run belongs to, so a reader that sees a dead
+ * mark can tell this checkout's orphan from another checkout's and never signal the latter. */
+export function makeRunMarker(pid = process.pid, root) {
+    const base = `${pid}-${crypto.randomBytes(6).toString("hex")}`;
+    return root === undefined ? base : `${base}-${rootToken(root)}`;
 }
 /** `base` plus this run's marker APPENDED to any inherited one, comma-separated. A harness
  * run under test inside a pi run inherits the outer run's mark; keeping it means the inner
@@ -43,7 +62,7 @@ export function runMarkerEnv(base, marker) {
  * check-in preload removed (`withoutLaunchServicesCheckIn`) and this run's marker appended
  * (`runMarkerEnv`). All three adapters (pi, claude, opencode) layer their own settings on
  * top, so the composition lives here rather than being re-derived in each. `binDir`, when
- * given, is prepended to PATH — run-spawn passes the notes shim dir (notesShimDir) so every
+ * given, is prepended to PATH — agent-spawn passes the notes shim dir (notesShimDir) so every
  * run finds the `tumwater-notes` command first (plans/notes-command.md "Reaching it from a
  * run"). */
 export function backendBaseEnv(marker, base = process.env, binDir) {
@@ -188,8 +207,7 @@ async function findMarkedPids(marker) {
 export function leftoversSweptMessage(kind, count, killed) {
     if (count === 0 || killed)
         return undefined;
-    const verb = count === 1 ? "was" : "were";
-    return `run sweep: ${plural(count, "process", "processes")} the ${kind} run started ${verb} still running after pi exited; sent SIGTERM`;
+    return `run sweep: ${plural(count, "process", "processes")} the ${kind} run started ${agree(count, "was", "were")} still running after pi exited; sent SIGTERM`;
 }
 /** SIGTERM every same-user process whose environment names `marker`, escalating to SIGKILL
  * after 10 s for any that survive — the run's cross-group leftovers: what a tool call
@@ -226,7 +244,7 @@ export async function sweepRunMarker(marker) {
                     // Already gone.
                 }
             }
-        }, 10_000).unref();
+        }, KILL_GRACE_MS).unref();
     }
     return signaled;
 }

package/dist/src/process/supervisor.js

@@ -113,37 +113,55 @@ export const MAX_RAPID_RESPAWNS = 5;
 function exitCodeOf(exit) {
     return exit.code ?? 1;
 }
+/** The code supervision must exit with when this generation ends it, or null when the
+ * generation asked for a restart and the loop should respawn it. A restart request while the
+ * operator is stopping is an asked-for ending, so it maps to the child's own code. */
+function terminalExitCode(exit, stopping) {
+    if (exit.code === RESTART_EXIT_CODE && !stopping)
+        return null;
+    return exitCodeOf(exit);
+}
+/** Whether a terminal exit is a failure the operator did not ask for and so must be recorded
+ * through onTeamDown: not a clean exit, not a `run --once` failed round, and not while stopping. */
+function isUnaskedFailure(code, stopping) {
+    return code !== 0 && code !== ONCE_FAILED_EXIT_CODE && !stopping;
+}
+/** Record one respawn at `at`, drop the ones that aged out of RESPAWN_WINDOW_MS, and return
+ * whether the rapid-respawn guard is now tripped. Mutates `recentRespawns`, the loop's window. */
+function trackRespawn(recentRespawns, at) {
+    while (recentRespawns.length > 0 && at - (recentRespawns[0] ?? at) > RESPAWN_WINDOW_MS)
+        recentRespawns.shift();
+    recentRespawns.push(at);
+    return recentRespawns.length > MAX_RAPID_RESPAWNS;
+}
+/** Run a best-effort hook: a throwing hook must not change the supervisor's exit, so its error
+ * is swallowed. Used for onTeamDown (the trace) and onDone (the build repair). */
+async function runBestEffort(hook) {
+    try {
+        await hook?.();
+    }
+    catch {
+        // Best-effort: the hook's own reporting is its responsibility.
+    }
+}
 /** Run child generations until one exits with something other than a restart request, and
  * return the code the supervisor should exit with. Pure apart from the injected effects. */
 export async function superviseStart(opts, signal) {
     const now = opts.now ?? Date.now;
     let generation = 1;
     const recentRespawns = [];
-    const teamDown = async (down) => {
-        try {
-            await opts.onTeamDown?.(down);
-        }
-        catch {
-            // Best-effort (see onTeamDown): a trace that cannot be written must not change the exit.
-        }
-    };
+    const teamDown = (down) => runBestEffort(() => opts.onTeamDown?.(down));
     try {
         for (;;) {
             const exit = await opts.spawnChild(signal);
-            if (exit.code !== RESTART_EXIT_CODE || opts.stopping()) {
-                // A clean exit (a child stopped by its own SIGTERM logs orchestrator_stop) and anything
-                // while the operator is stopping are asked-for endings, and so is a once round that
-                // finished with failed runs; everything else is the team dying.
-                const code = exitCodeOf(exit);
-                if (code !== 0 && code !== ONCE_FAILED_EXIT_CODE && !opts.stopping())
+            const stopping = opts.stopping();
+            const terminal = terminalExitCode(exit, stopping);
+            if (terminal !== null) {
+                if (isUnaskedFailure(terminal, stopping))
                     await teamDown({ generation, exit, crashLoop: false });
-                return exitCodeOf(exit);
+                return terminal;
             }
-            const t = now();
-            while (recentRespawns.length > 0 && t - (recentRespawns[0] ?? t) > RESPAWN_WINDOW_MS)
-                recentRespawns.shift();
-            recentRespawns.push(t);
-            if (recentRespawns.length > MAX_RAPID_RESPAWNS) {
+            if (trackRespawn(recentRespawns, now())) {
                 opts.onCrashLoop?.();
                 await teamDown({ generation, exit, crashLoop: true });
                 return 1;
@@ -153,17 +171,11 @@ export async function superviseStart(opts, signal) {
         }
     }
     finally {
-        // The end-of-supervision repair (see onDone): a hook that throws must not change the exit.
-        try {
-            await opts.onDone?.();
-        }
-        catch {
-            // Best-effort — see onDone.
-        }
+        await runBestEffort(() => opts.onDone?.());
     }
 }
 /** The `supervisor_exit` event for a team that went down (see onTeamDown). `diagnosis` is the
- * startup gate re-asked after the death (startup-gate.ts's runStartupProblem): the likeliest
+ * startup gate re-asked after the death (startup-gates.ts's runStartupProblem): the likeliest
  * reason a generation dies right after a respawn is an environment that no longer boots, and the
  * child's own message reached only the terminal. Null when every precondition passes — the event
  * then carries no reason rather than a guess. A crash loop's reason is the guard itself. */

package/dist/src/prompt/dialect.js

@@ -56,7 +56,7 @@ export const CODEX_DIALECT = {
     ],
 };
 /** The dialect table keyed by backend id: every backend but claude speaks pi's dialect (and
- * an unknown id falls back to pi because run-agent.ts routes an unregistered id to the pi
+ * an unknown id falls back to pi because agent-run.ts routes an unregistered id to the pi
  * backend). Adding a backend means one row here, not another branch. */
 const DIALECTS = {
     pi: PI_DIALECT,

package/dist/src/prompt/gate-notes.js

@@ -51,7 +51,7 @@ export function buildRejectedReviewNote(review, role) {
     return `Your previous change was rejected; fix each numbered objection or drop the change — it is this run's primary task${context}:\n${list}${tail}`;
 }
 /** The note injected into a role's run prompt when its rejected change has been re-applied to
- * current main as uncommitted edits (plans/revise-rejected.md, runner/revision.ts's
+ * current main as uncommitted edits (plans/revise-rejected.md, runner/runner-revision.ts's
  * applyRevision): this run's one task is to revise the change already in the worktree, not
  * author a new one. The prior objections are numbered so the author can work through them; a
  * revision round past the first also reaches here. The chain keeps revising while each round
@@ -156,7 +156,7 @@ ${lines.join("\n")}
 </merged-prerequisites>`;
 }
 /** The note injected into a role's prompt after leftover recovery discarded its pinned change
- * at MERGE_CONFLICT_LIMIT (src/runner/leftover.ts): at the cap recovery ordinarily hands the
+ * at MERGE_CONFLICT_LIMIT (src/runner/runner-leftover.ts): at the cap recovery ordinarily hands the
  * change back to its author with markers instead, so a discard means that lineage already used
  * its hand-back. The merge failures were harness-level, so without the note the author would
  * never learn its work is gone — or that redoing it from memory of the old diff would conflict

package/dist/src/prompt/gate-prompts.js

@@ -156,7 +156,7 @@ ${TEST_RUNNER_RULE}${noCheckRunRule}
  * revision of a previously rejected change (plans/revise-rejected.md part 2/2): it names the round
  * and shows the prior objections plus the interdiff so the re-review checks each one first.
  * Omitted, the prompt is unchanged from a fresh change's. `postMerge` marks the post-merge review
- * of a commit already on main (review.afterMerge): a finding the reviewer can repair is the work —
+ * of a commit already on main: a finding the reviewer can repair is the work —
  * it makes the minimal fix in the worktree, leaves the edit, and ends with the verdict line plus a
  * `FIX:` line — so the instruction and the repair rule render only for that caller, and every other
  * (pre-merge) caller's prompt is byte-identical. */
@@ -286,49 +286,6 @@ ${TEST_RUNNER_RULE}
   FIX: <files you changed>` : ""}`);
     return parts.join("\n\n");
 }
-/** The prompt for the next attempt at a review whose previous run hit its time budget while
- * still making progress (RunnerState.reviewResume): that run continues the timed-out reviewer's
- * own session (`--continue`), so the diff and everything the reviewer already read are in
- * context. This prompt carries no diff — re-sending it would defeat the resume — and names the
- * frozen comparison base and the unchanged patch-id so the reviewer knows the change it was
- * judging has not moved. `baseRev` is changeBaseRev's frozen revision (see buildReviewPrompt);
- * `patchId` is git/git.ts's patchId for the change. It closes with the same VERDICT_ENDING
- * contract as the full review prompt, so the accepted forms cannot drift. */
-export function buildReviewResumePrompt(baseRev, patchId) {
-    return `${dateLine()}
-
-You are resuming an adversarial review of a tumwater change: the previous attempt hit its time budget while still making progress, and this run continues that same reviewer session. Everything you already read — the diff and the files you checked — is in your context; do not re-read it.
-
-The change is unchanged since that attempt (patch-id ${patchId}) and is still measured against ${shortSha(baseRev)}. Other roles merge on main while you review, so compare against ${shortSha(baseRev)}, never against \`main\`.
-
-Finish the checks you had not completed, then end your reply with exactly one line in this form:
-  ${VERDICT_ENDING.replace(/\n/g, "\n  ")}`;
-}
-/** The one-turn follow-up sent into the REVIEWER's own session (--continue) when its run
- * completed but the reply carried no parseable VERDICT line — the review-gate sibling of
- * prompt-followup.ts's buildSummaryRequestPrompt. The session already holds the full review, so one
- * short reply recovers the verdict the gate needs without paying a second full review run;
- * the caller bounds the run tightly and counts the strike against the HEAD only when this
- * too yields nothing (BUGS.md 2026-09-29). It shares the review prompt's closing rule
- * (reply-contract.ts's VERDICT_ENDING), so the accepted forms cannot drift between the prompts. */
-export function buildVerdictRequestPrompt() {
-    return `Your review reply above did not include the verdict line tumwater parses, so
-your judgment was lost. Reply now with ONLY the closing block — no tool calls, no other text:
-one line in this form:
-  ${VERDICT_ENDING}`;
-}
-/** The no-re-run nudge (BUGS.md 2026-10-02): the reviewer broke the prompt's no-re-run rule
- * despite a green pre-check, so this turn on its own session names the exact tool call and
- * asks it to finish the review from what it already read. The reviewer's only output channel
- * is the verdict, so the closing rule names both accepted forms like the review prompt does. */
-export function buildNoRerunPrompt(rerun) {
-    return `You started a tool call tumwater's pre-check already covered, so it must not run:
-  ${rerun}
-The full check passed at this exact tree before your review began. Do not re-run it — not in
-this worktree, not in a scratch copy. Finish the review now from what you have already read:
-reply with ONLY the closing block — no tool calls, no other text — one line in this form:
-  ${VERDICT_ENDING}`;
-}
 /** The one-turn follow-up sent into a run's OWN session (--continue) when the harness's
  * pre-queue self-check found problems likely to get the change rejected. Only some findings are
  * the merge gate's own deterministic checks; the rest (path drift, plan dependencies) are

package/dist/src/prompt/notes-backlog.js

@@ -96,63 +96,70 @@ function holdWording(state) {
         return "eligible";
     if (state === "refused")
         return "refused (only the operator clears it)"; // vocabulary-ok: the plan-mandated refused hold wording refers to the tumwater operator
-    if (state === "needs-review" || state === "held-for-operator")
-        return "needs review"; // vocabulary-ok: the deprecated held-for-operator hold name, kept only until part 2f/6 retires it
+    if (state === "needs-review")
+        return "needs review";
     return `waits on ${state.blockedBy.join(", ")}`;
 }
 /** The one summary line of a named series' planned-part state. */
 function seriesSummary(info) {
     const counts = [];
     if (info.review > 0)
-        counts.push(`${info.review} ${info.review === 1 ? "needs review" : "need review"}`);
+        counts.push(plural(info.review, "needs review", "need review"));
     if (info.waiting > 0)
-        counts.push(`${info.waiting} ${info.waiting === 1 ? "waits" : "wait"} on an earlier part`);
+        counts.push(`${plural(info.waiting, "waits", "wait")} on an earlier part`);
     counts.push(info.refused === 0 ? "none refused" : `${info.refused} refused`);
     return `${plural(info.plannedCount, "part")} planned: ${counts.join(", ")}`;
 }
-/** The live backlog block for the notes, or undefined when they name nothing live. */
-export function notesBacklogBlock(notes, backlog) {
-    const { planned, openBugs, donePlanTitles } = backlog;
-    const series = seriesInfos(planned, donePlanTitles);
-    const allParts = plannedPartKeys(planned);
+/** Index each live series' first word to its count, so a bare first word names a series only
+ * when no other live series shares it. */
+function firstWordCountsOf(series) {
     const firstWordCounts = new Map();
     for (const info of series.values()) {
         const w = firstWord(info.name);
         firstWordCounts.set(w, (firstWordCounts.get(w) ?? 0) + 1);
     }
-    const allEntries = [...planned, ...openBugs];
-    const namedSeries = new Set();
-    const namedParts = new Map();
-    const namedEntries = new Map();
-    for (const rawLine of notes.split("\n")) {
-        const line = collapseWhitespace(rawLine).toLowerCase();
-        if (line === "")
+    return firstWordCounts;
+}
+/** The state a named part renders for one part key: its planned hold, `done`, or `not in the
+ * backlog`. */
+function partStateOf(info, key) {
+    return info.holds.has(key) ? info.holds.get(key) : info.done.has(key) ? "done" : "not-in-backlog";
+}
+/** Name the live series a line mentions: by full name, or by its sole-shared first word; the
+ * `i/n` part refs of that series fill `namedParts` (under a `\u0000`-joined key) and a line with
+ * a series token but no part ref names the series. */
+function nameSeriesInLine(line, series, firstWordCounts, namedSeries, namedParts) {
+    for (const [sLower, info] of series) {
+        const hasFull = lineHas(line, info.name.toLowerCase());
+        const fw = firstWord(info.name);
+        const hasFirst = firstWordCounts.get(fw) === 1 && lineHas(line, fw);
+        if (!hasFull && !hasFirst)
             continue;
-        for (const [sLower, info] of series) {
-            const hasFull = lineHas(line, info.name.toLowerCase());
-            const fw = firstWord(info.name);
-            const hasFirst = firstWordCounts.get(fw) === 1 && lineHas(line, fw);
-            if (!hasFull && !hasFirst)
-                continue;
-            const refs = partRefsInLine(line).filter((r) => r.of === info.of);
-            if (refs.length === 0) {
-                namedSeries.add(sLower);
-            }
-            else {
-                for (const r of refs) {
-                    const key = partKey(info.name, r.part);
-                    const state = info.holds.has(key) ? info.holds.get(key) : info.done.has(key) ? "done" : "not-in-backlog";
-                    namedParts.set(`${sLower}\u0000${r.part}\u0000${r.of}`, { seriesLower: sLower, part: r.part, of: r.of, state });
-                }
-            }
+        const refs = partRefsInLine(line).filter((r) => r.of === info.of);
+        if (refs.length === 0) {
+            namedSeries.add(sLower);
         }
-        for (const [i, entry] of allEntries.entries()) {
-            const phrase = firstSixWords(entryKey(entry.title));
-            if (phrase !== "" && line.includes(phrase)) {
-                namedEntries.set(entryKey(entry.title), { title: entry.title, file: i < planned.length ? "plans" : "bugs", state: entryHoldAgainst(entry, allParts) });
+        else {
+            for (const r of refs) {
+                const state = partStateOf(info, partKey(info.name, r.part));
+                namedParts.set(`${sLower}\u0000${r.part}\u0000${r.of}`, { seriesLower: sLower, part: r.part, of: r.of, state });
             }
         }
     }
+}
+/** Name a planned entry or Open bug whose first six words (entryKey-normalized) appear in the
+ * line. */
+function nameEntriesInLine(line, allEntries, allParts, plannedCount, namedEntries) {
+    for (const [i, entry] of allEntries.entries()) {
+        const phrase = firstSixWords(entryKey(entry.title));
+        if (phrase !== "" && line.includes(phrase)) {
+            namedEntries.set(entryKey(entry.title), { title: entry.title, file: i < plannedCount ? "plans" : "bugs", state: entryHoldAgainst(entry, allParts) });
+        }
+    }
+}
+/** Render the named series summaries, part lines and entry lines, truncating to `MAX_BLOCK_LINES`
+ * with a remainder line naming the dropped items; undefined when nothing live was named. */
+function renderNamedItems(namedSeries, namedParts, namedEntries, series) {
     const lines = [];
     for (const sLower of namedSeries) {
         const info = series.get(sLower);
@@ -175,3 +182,25 @@ export function notesBacklogBlock(notes, backlog) {
     const shown = lines.slice(0, cap - 1);
     return [HEADER, ...shown, `… and ${plural(lines.length - shown.length, "more named item")}`].join("\n");
 }
+/** Build the live backlog block: index each series' first word (`firstWordCountsOf`), read every
+ * notes line naming the series, parts and entries it mentions (`nameSeriesInLine`/
+ * `nameEntriesInLine`), then render and truncate the names (`renderNamedItems`). Returns undefined
+ * when the notes name nothing live. */
+export function notesBacklogBlock(notes, backlog) {
+    const { planned, openBugs, donePlanTitles } = backlog;
+    const series = seriesInfos(planned, donePlanTitles);
+    const allParts = plannedPartKeys(planned);
+    const firstWordCounts = firstWordCountsOf(series);
+    const allEntries = [...planned, ...openBugs];
+    const namedSeries = new Set();
+    const namedParts = new Map();
+    const namedEntries = new Map();
+    for (const rawLine of notes.split("\n")) {
+        const line = collapseWhitespace(rawLine).toLowerCase();
+        if (line === "")
+            continue;
+        nameSeriesInLine(line, series, firstWordCounts, namedSeries, namedParts);
+        nameEntriesInLine(line, allEntries, allParts, planned.length, namedEntries);
+    }
+    return renderNamedItems(namedSeries, namedParts, namedEntries, series);
+}

package/dist/src/prompt/principles.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { readTextOrNull } from "../files/files.js";
+import { readRegularTextOrNull } from "../files/files.js";
 import { truncateWithNote } from "../text/text.js";
 /** Cap on the PRINCIPLES.md text injected into every prompt, so a runaway file cannot blow up
  * each run's prefill. */
@@ -7,10 +7,12 @@ export const PRINCIPLES_MAX_CHARS = 4000;
 /** The project's design principles (PRINCIPLES.md), capped for injection into prompts. Empty
  * string when the file is missing or unreadable — prompt building must never throw on it.
  * (Extracted from prompt.ts, which now builds prompts on top of this reader; the truncation
- * marker format is truncateWithNote's in text.ts.) */
+ * marker format is truncateWithNote's in text.ts.) A symlinked PRINCIPLES.md is read as empty
+ * (readRegularTextOrNull never follows a symlink out of the worktree, INV-G3/G4's lstat
+ * policy), so a hostile tree cannot inject an arbitrary host file into every run's prompt. */
 export function readPrinciples(root) {
     const file = path.join(root, "PRINCIPLES.md");
-    return truncateWithNote(readTextOrNull(file)?.trim() ?? "", PRINCIPLES_MAX_CHARS, "PRINCIPLES.md");
+    return truncateWithNote(readRegularTextOrNull(file)?.trim() ?? "", PRINCIPLES_MAX_CHARS, "PRINCIPLES.md");
 }
 /** True when PRINCIPLES.md's trimmed text exceeds the prompt cap, so every run's <principles>
  * block carries only its head plus a truncation marker — the always-on amber twin of the doctor
@@ -20,6 +22,6 @@ export function readPrinciples(root) {
  * (the directory-in-place case readPrinciples degrades to "") and at-or-under-cap files are all
  * false. */
 export function principlesBlockOverCap(root) {
-    const raw = readTextOrNull(path.join(root, "PRINCIPLES.md"));
+    const raw = readRegularTextOrNull(path.join(root, "PRINCIPLES.md"));
     return raw !== null && raw.trim().length > PRINCIPLES_MAX_CHARS;
 }

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

@@ -68,16 +68,24 @@ ${REPLY_ENDINGS}`;
  * so the bridge must send the new run to `git diff` before it starts its own work. A `salvaged`
  * handoff's edits were restored from a patch of a run the harness lost track of
  * (src/git/slot-salvage.ts) rather than kept in place. */
-export function buildHandoffPrompt(roleId, runPrompt, cause = "handoff") {
+export function buildHandoffPrompt(roleId, runPrompt, cause = "handoff", 
+/** Named facts an image-reroute handoff note needs that the cause alone cannot carry: the
+ * model the blind run was on and the image file it read. */
+imageReroute) {
     const note = cause === "budget-capped"
         ? `An earlier API-billed claude run of the "${roleId}" role hit its per-run budget cap before it
 could finish; its uncommitted edits are in your worktree — review \`git diff\`, then finish or
 discard them. This run starts on the model job the daily budget left you.`
-        : cause === "salvaged"
-            ? `An earlier run of the "${roleId}" role was cut short before tumwater could save its work;
+        : cause === "image-reroute"
+            ? `An earlier run of the "${roleId}" role on ${imageReroute?.from ?? "another model"} stopped
+when it read ${imageReroute?.path ?? "an image"}, because that model cannot read images; its
+uncommitted edits are in your worktree — review \`git diff\`, then finish or discard them. This
+run is on a model that CAN read images, so read the image again.`
+            : cause === "salvaged"
+                ? `An earlier run of the "${roleId}" role was cut short before tumwater could save its work;
 its uncommitted edits were recovered and are in your worktree — review \`git status\` and
 \`git diff\` (new files show as untracked), then finish or discard them.`
-            : `An earlier run of the "${roleId}" role on another model was interrupted; its
+                : `An earlier run of the "${roleId}" role on another model was interrupted; its
 uncommitted edits are in your worktree — review \`git diff\`, then finish or discard them.`;
     return `${runPrompt}\n\n${note}`;
 }

package/dist/src/prompt/prompt.js

@@ -82,6 +82,20 @@ export const KILL_BY_PID_RULE = `Never kill processes by name or pattern (\`pkil
 export const TEST_RUNNER_RULE = `- Run tests only through the project's declared check or the test framework it already uses —
   never a runner you guessed (say, \`npx vitest\` in a suite written for node:test): a mismatched
   runner finds no tests at best, and can kill them mid-run, leaking processes and temp files.`;
+/** The synthetic-load rule every run that may run commands carries, word for word: the run and
+ * director rules (full and compact). The bounding sentence is the point — a loader that ends with
+ * the command cannot leak. 2026-10-28: seven leaked \`while :; do :; done\` loops from bugfix runs
+ * reproducing a load flake stood at PPID 1 loading the shared host (BUGS.md): macOS \`ps -E\`
+ * hides the environment of platform binaries like bash, so the end-of-run marker sweep cannot
+ * attribute them to a run to reap them. The only reliable prevention is never starting unbounded
+ * load in the first place — a leaked platform-binary loader cannot be reaped on macOS by any
+ * sweep that exists. */
+export const SYNTHETIC_LOAD_RULE = `The host is shared by every run, review, and check on the team,
+  and already under load; never add synthetic CPU load (a \`while :; do :; done\` spinner, a
+  CPU-spinning node process) to reproduce a load flake unless it ends with the command that starts
+  it — a \`timeout\`, or backgrounded and killed with \`kill $!\` before that tool call returns. A
+  loader that outlives its command is an orphan no sweep can reliably reap, and loads the host
+  every sibling run and check runs on until a \`tumwater doctor\` sweep or a human stops it.`;
 /** Render a dialect's `backendRules` as one bullet each, or nothing when the dialect has none
  * (pi and claude) — so a backend's extra shell/reasoning guidance rides the reading-budget
  * section right after the oversized-output rule. */
@@ -128,9 +142,9 @@ export const DEFAULT_SCOPE = `- Do exactly ONE focused task, then stop. Small, c
  * ~2.5k tokens of every run before its first edit (2026-10-17 audit). */
 function commonRules(check, briefFile = "README.md", scope = DEFAULT_SCOPE, dialect = PI_DIALECT, assigned = false, gateCommand) {
     const verify = check && gateCommand
-        ? `verify with \`${gateCommand}\` (lint, compile and the tests your change affects) — run it
-  after your change and fix what you broke. Tumwater runs the full check (${describeCheck(check)})
-  itself; do not run it.`
+        ? `verify the change with a compile or the one or two test files that cover it — run them
+  after your change and fix what you broke. Tumwater runs the full gate (\`${gateCommand}\`)
+  itself before the change merges; do not run it.`
         : check
             ? `verify with ${describeCheck(check)} (the project's declared check) — run it after your
   change and fix what you broke.`
@@ -178,6 +192,7 @@ Where you work:
   servers, watch modes). To test such a program, background it with a hard time limit (at most
   30 minutes) and never give it a real TTY.
 - ${KILL_BY_PID_RULE} A pattern also kills other agents' runs and checks.
+- ${SYNTHETIC_LOAD_RULE}
 - Leave the project working: ${verify} Write the check's full output to a scratch file once
   (\`${gateCommand ? "<gate>" : "<check>"} > <scratch-dir>/check.log 2>&1\`) and \`tail\` it; grep that file for anything else, and
   re-run the check only after an edit changes the tree.
@@ -307,48 +322,83 @@ from the repo.`,
 }
 /** The prompt for one role run. */
 export function buildRunPrompt(input) {
-    const { role, rejectedReview, principles, digest, coverage, ciParity, filings, backlogStructure, backlogIndex, notes, notesSavedDay, notesBacklog, extraInstructions, planTargetNote, flakyChecks, noCheck, check, gateCommand, briefFile, today, userRequest, agent, assigned } = input;
-    const dialect = dialectFor(agent);
-    const day = today ?? todayStamp();
+    const dialect = dialectFor(input.agent);
+    const day = input.today ?? todayStamp();
     const parts = [
+        ...runIdentityBlocks(input.role, input.rejectedReview, day),
+        ...runContextBlocks(input),
+        ...runEvidenceBlocks(input),
+        ...runNotesBlocks(input, day),
+        ...runTaskBlocks(input),
+        ...runRulesBlocks(input, dialect),
+    ];
+    return parts.join("\n\n");
+}
+/** The role identity line and the shared worktree + date preamble. */
+function runIdentityBlocks(role, rejectedReview, day) {
+    return [
         ...(rejectedReview ? [rejectedReview.trim()] : []),
         `You are the "${role.id}" role (${role.title}) on this project's tumwater team — tumwater runs a team of AI roles that develop the project.`,
         ...sharedPreamble(day),
     ];
-    if (principles)
-        parts.push(principlesBlock(principles));
-    if (userRequest)
+}
+/** The principles block and the explicit user-request steering block, in that order. */
+function runContextBlocks(input) {
+    const parts = [];
+    if (input.principles)
+        parts.push(principlesBlock(input.principles));
+    if (input.userRequest)
         parts.push(`An explicit request from the user, aimed at this role. Treat it as this run's steering;
 your role's rules and the merge gate still apply unchanged. If the request is out of this
-role's scope, say so in your reply instead of doing it anyway.\n<user-request>\n${userRequest.trim()}\n</user-request>`);
-    if (coverage)
-        parts.push(coverage);
-    if (ciParity)
-        parts.push(ciParity);
-    if (filings)
-        parts.push(filings);
-    if (digest)
-        parts.push(digestBlock(digest));
-    if (backlogStructure)
-        parts.push(backlogStructure);
-    if (backlogIndex)
-        parts.push(backlogIndex);
-    if (notes && notes.trim() !== "")
-        parts.push(roleNotesBlock(notes, Boolean(backlogIndex), notesSavedDay, day));
-    if (notesBacklog)
-        parts.push(notesBacklog);
-    parts.push(`Your task this run:\n${role.find.trim()}`);
-    if (noCheck)
-        parts.push(noCheck.trim());
-    if (planTargetNote)
-        parts.push(planTargetNote.trim());
-    if (flakyChecks)
-        parts.push(flakyChecks.trim());
-    if (extraInstructions)
-        parts.push(`Additional standing instructions from the user:\n${extraInstructions.trim()}`);
-    parts.push(roleNotesInstruction());
-    parts.push(commonRules(check, briefFile, role.scope, dialect, assigned, gateCommand).trim());
-    return parts.join("\n\n");
+role's scope, say so in your reply instead of doing it anyway.\n<user-request>\n${input.userRequest.trim()}\n</user-request>`);
+    return parts;
+}
+/** The six rendered evidence blocks, in the fixed order. */
+function runEvidenceBlocks(input) {
+    const parts = [];
+    if (input.coverage)
+        parts.push(input.coverage);
+    if (input.ciParity)
+        parts.push(input.ciParity);
+    if (input.filings)
+        parts.push(input.filings);
+    if (input.digest)
+        parts.push(digestBlock(input.digest));
+    if (input.backlogStructure)
+        parts.push(input.backlogStructure);
+    if (input.backlogIndex)
+        parts.push(input.backlogIndex);
+    return parts;
+}
+/** The role-notes block (only when a note exists) and the live backlog state block. */
+function runNotesBlocks(input, day) {
+    const parts = [];
+    if (input.notes && input.notes.trim() !== "")
+        parts.push(roleNotesBlock(input.notes, Boolean(input.backlogIndex), input.notesSavedDay, day));
+    if (input.notesBacklog)
+        parts.push(input.notesBacklog);
+    return parts;
+}
+/** The task text and its optional noCheck/plan-target/flake/extra notes. */
+function runTaskBlocks(input) {
+    const parts = [];
+    parts.push(`Your task this run:\n${input.role.find.trim()}`);
+    if (input.noCheck)
+        parts.push(input.noCheck.trim());
+    if (input.planTargetNote)
+        parts.push(input.planTargetNote.trim());
+    if (input.flakyChecks)
+        parts.push(input.flakyChecks.trim());
+    if (input.extraInstructions)
+        parts.push(`Additional standing instructions from the user:\n${input.extraInstructions.trim()}`);
+    return parts;
+}
+/** The note-write instruction and the shared rules, which close the prompt. */
+function runRulesBlocks(input, dialect) {
+    return [
+        roleNotesInstruction(),
+        commonRules(input.check, input.briefFile, input.role.scope, dialect, input.assigned, input.gateCommand).trim(),
+    ];
 }
 /** The prompt for a director run, which routes a user request into the project. */
 export function buildDirectorPrompt(userPrompt, principles,