tumwater 0.4.0 → 0.4.2

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

@@ -1,5 +1,5 @@
 import { shortSha } from "../text/format.js";
-import { NEEDS_REPLAN_NOTE, NEEDS_REVIEW_NOTE } from "../roles/role-guidance.js";
+import { NEEDS_REVIEW_PREFIX, NEEDS_REVIEW_NOTE, CHECK_DECLARATION_MARKER } from "../roles/role-guidance.js";
 import { baseRoleOf } from "../roles/runner-ids.js";
 import { formatTimestamp } from "../text/datetime.js";
 import { numberedList } from "../text/markdown.js";
@@ -29,12 +29,12 @@ export function buildRejectedReviewNote(review, role) {
     }
     // On exhaustion the rejected diff is gone. Feature's rejected change often implemented a
     // PLANS.md entry, and re-authoring the same plan from scratch is what produced the long
-    // rejection runs this note exists to end, so feature is sent to replan the entry instead.
-    // A plan-less role has no downstream role to replan for it, so it is sent to its own
-    // notes instead: it records the abandoned purpose and any instances that remain
-    // unhandled, then takes a different theme on the next run. Re-authoring the same purpose
-    // from the same objections is what restarted the round and produced the long rejection
-    // runs this note exists to end. The markdown-only replan note merges review-exempt, but a
+    // rejection runs this note exists to end, so feature is sent to write a Needs-review note so
+    // the plan role rewrites the entry. A plan-less role has no downstream role to replan for it,
+    // so it is sent to its own notes instead: it records the abandoned purpose and any instances
+    // that remain unhandled, then takes a different theme on the next run. Re-authoring the same
+    // purpose from the same objections is what restarted the round and produced the long rejection
+    // runs this note exists to end. The markdown-only Needs-review note merges review-exempt, but a
     // merged change clears the standing rejection (clearSupersededRejection, run-apply.ts), so
     // the instruction does not re-inject once the note has merged. `role` is the runner id, so
     // feature's instances (`feature-2`, …) are matched through their base role: matched bare,
@@ -44,7 +44,7 @@ export function buildRejectedReviewNote(review, role) {
     if (review.exhausted) {
         finality =
             role !== undefined && baseRoleOf(role) === "feature"
-                ? ` This was the change's final revision round — the same objection survived two revisions (or the chain hit its cap), so the rejected diff and ref are gone. If it implemented a PLANS.md entry, do not re-author it: append ${NEEDS_REPLAN_NOTE} under that entry's heading, with the numbered objections above quoted beneath it, and merge that markdown-only change and nothing else so the plan role can rewrite the plan. Otherwise, redo the change against current main.`
+                ? ` This was the change's final revision round — the same objection survived two revisions (or the chain hit its cap), so the rejected diff and ref are gone. If it implemented a PLANS.md entry, do not re-author it: append ${NEEDS_REVIEW_PREFIX}<YYYY-MM-DD> by feature: rejected after <N> review rounds** under that entry's heading, with the numbered objections above quoted beneath it, and merge that markdown-only change and nothing else so the plan role can rewrite the plan. Otherwise, redo the change against current main.`
                 : " This was the change's final revision round — the same objection survived two revisions (or the chain hit its cap), so the rejected diff and ref are gone. Do not re-author it. Record the abandoned purpose and any instances of it that remain unhandled in your notes, then take a different theme on this run: re-deriving the same purpose from the same objections is what produced the long rejection runs this note exists to end.";
     }
     const tail = finality === "" ? "" : `\n${finality.trim()}`;
@@ -106,6 +106,25 @@ Sibling instances hold these backlog entries; do not pick, edit, or implement th
 ${titles.map((t) => `- "${t}"`).join("\n")}
 </held-entries>`;
 }
+/** The note injected into a `plan` or `feature` run when the project has no declared
+ * deterministic check (detectBuildCheck returned null) and the team should close the gap itself
+ * — the plan role writes the declaration entry, the feature role implements it. Exactly one of
+ * the two notes is in flight, decided by CHECK_DECLARATION_MARKER rather than prose (see
+ * declarationPlanEntry, src/backlog/backlog.ts): no marker → the plan note (write the
+ * declaration); marker → the feature note (implement it). run-prompt.ts picks which note to
+ * render from the base role and whether a marker entry waits, so a work instance (`feature-2`, …)
+ * matches through its base role and the marker test decides the rest. A pure function so its
+ * shape is pinned in tests. */
+export function buildNoCheckNote(role) {
+    if (baseRoleOf(role) === "plan") {
+        return `<no-check>
+This project declares no deterministic check, so the safety gates are off. Before anything else, write the entry that declares one: headed \`### Declare the project's deterministic check\`, marked on its own line with ${CHECK_DECLARATION_MARKER}, naming the exact command and the route it lands by — a \`test\`/\`typecheck\`/\`build\` script added to package.json when the walked-up install root carries one, else \`check.command\` — with acceptance criteria that the doctor's \`check\` row reads ok and the \`no-check\` alert is gone. Writing it is this run's work even when the eligible-plan target is already met, so the in-prompt queue-full stop yields to it; a full plan backlog defers the plan role before this prompt is built, so this note only reaches a run already admitted past that stop. A Needs-review lift and an assigned claim still come first. A project with nothing to verify yet — no source, no script to wire — gets no plan: end with ${NOTHING_TO_DO} instead.
+</no-check>`.trim();
+    }
+    return `<no-check>
+The PLANS.md \`## Planned\` entry marked ${CHECK_DECLARATION_MARKER} is this run's task unless the run was handed another entry: implement its declaration so a merge makes it live — the doctor's \`check\` row reads ok and \`tumwater status --json\` carries no \`noDeclaredCheck\`. Do not chase an in-run re-read, though: while the change is unmerged, both still reflect the pre-declaration state, so live is confirmed when the change merges, not in this run — mark the plan done when the declaration is complete and correct, and let the merge confirm it. Choose the route the repo takes: (1) add the verifying script to package.json as \`test\`/\`typecheck\`/\`build\` (detection's preference order), a tracked diff the reviewer sees, live the moment it merges; (2) otherwise write \`{ "check": { "command": "…" } }\` to \`.tumwater-config-request.json\` at the worktree root, never tumwater.json — the request is run green before it is applied, then the file is deleted. A marker entry held with a Needs-review note is not available to you, so end the run there rather than forcing it.
+</no-check>`.trim();
+}
 /** The longest title an entry list quotes: a PLANS.md heading's tail names the plan's dates and
  * every file it touches, which its range already leads to. */
 const LISTED_TITLE_CHARS = 100;
@@ -150,9 +169,9 @@ export function buildConflictDiscardNote(summary, attempts) {
 }
 /** The note injected into the `ci` healer's prompt when main's own suite is red (PLANS.md
  * "Red-main handoff"): the gate's warning event is harness-level and no role prompt reads it, so
- * the one role allowed to author on a red main is told what failed and that fixing it is this
- * run's job. The healer's normal charter is a starting point, not a fit — a red main blocks
- * every other code role, and the gate's deterministic pre-check rejects any change that leaves
+ * the healer — whose job is to make main green — is told what failed and that fixing it is this
+ * run's task. The healer's normal charter is a starting point, not a fit — a red main keeps the
+ * whole team working on it, and the gate's deterministic pre-check rejects any change that leaves
  * the suite red, so authoring anything else first is waste. A pure function so its shape is
  * pinned in tests; script/headline are optional because a red carries a failing script, but the
  * note must still read sensibly if it is ever absent. */
@@ -172,22 +191,28 @@ export function buildMainRedNote(sha, script, headline, tail) {
         ? `\nFailing check output (${output.length} lines):\n\`\`\`\n${output.join("\n")}\n\`\`\`\n`
         : "";
     return `<main-red>
-main's own suite is red at ${shortSha(sha)} (${what}). Every code-producing role is skipping authoring and no change merges until main is green.
+main's own suite is red at ${shortSha(sha)} (${what}). Every role keeps working on the red main, but no change that leaves the suite red merges until main is green.
 This run your job is to make main green: reproduce that failure, fix it (add a regression test where one is feasible), and merge the fix.
 The review gate's deterministic pre-check runs main + your change, so a change that leaves the suite red is rejected — do not author anything else first.
 If the failure is environmental — flaky, load-sensitive, or a broken local toolchain — say so plainly in your reply rather than editing unrelated code.
 ${tailBlock}</main-red>`;
 }
-/** The note every role but bugfix gets while main is red with named failures: the tests that
- * already fail on main (at most 20 listed, then a `…and N more` line) and who owns them. A pure
- * function so its shape is pinned in tests. */
+/** The note injected into every role's prompt but the `ci` healer's own while main is red with
+ * named failures (the `<main-known-red>` block part 3a/3 dropped with the red-main authoring
+ * gate, re-added by the "Every role may fix main's failing check" decision 2026-10-25): the
+ * tests that already fail on main, and who owns them. The `ci` role owns the repair but does
+ * not monopolize it — any role whose change touches what a named test covers, or that can land
+ * a fix, fixes it in its own worktree and lets the change land normally. It is worded as
+ * permission to proceed (a main that names its failures stops nobody), never as "leave them
+ * alone". A pure function so its shape is pinned in tests; at most 20 tests are listed, then a
+ * `…and N more` line. */
 export function buildMainKnownRedNote(failingTests) {
     const shown = failingTests.slice(0, 20).map((t) => `- ${t}`);
     if (failingTests.length > 20)
         shown.push(`- …and ${failingTests.length - 20} more`);
     return `<main-known-red>
 ${shown.join("\n")}
-These tests already fail on main. Tumwater or the bugfix role owns them. Leave them alone unless your task is about them; a change merges when it adds no new failures.
+Main's tip already fails these tests. The ci role owns them and fixes them on its own clock. A role whose change touches what they test, or that can land a fix for one, fixes it in its own worktree and lets the change land normally — never weaken or delete a test to make the suite pass.
 </main-known-red>`;
 }
 /** The note appended to an assigned series part's prompt naming the later planned parts that

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

@@ -3,7 +3,7 @@
  * the previous note; when a note states something about the backlog (an entry is refused, a
  * series is dead, a part is done) nothing used to check that claim again — on 2026-10-21 a plan
  * run wrote "Codex 2b/9 carry Refused — never re-add or re-author them; the Codex theme is dead",
- * then both Refused notes became Needs-replan notes the plan role exists to act on, but its own
+ * then both Refused notes became Needs-review notes the plan role exists to act on, but its own
  * notes kept telling it to skip them and the series stalled. This module renders, from the notes
  * and the live backlog, a short block saying what is currently true of each entry and series the
  * notes name, so the live state wins without anyone editing a notes file.
@@ -17,10 +17,13 @@
  *    names that entry.
  * Each named planned part carries its eligibility hold (entryHoldAgainst); a part in
  * PLANS-DONE.md reads `done`, a part found nowhere reads `not in the backlog`. Each named series
- * gets one summary line of its planned-part state. The block is at most 12 lines and returns
- * undefined when the notes name nothing live. */
-import { entryHoldAgainst, entryKindLabel } from "../backlog/backlog-eligibility.js";
+ * gets one summary line of its planned-part state. The block is at most 12 lines and, when the
+ * notes name more items than fit, its last line says how many were dropped (`… and N more named
+ * items`) so a dropped item cannot read as a complete answer; it returns undefined when the notes
+ * name nothing live. */
+import { entryHoldAgainst } from "../backlog/backlog-eligibility.js";
 import { entryKey, partKey, plannedPartKeys, seriesPart } from "../backlog/backlog-parts.js";
+import { plural } from "../text/phrases.js";
 import { collapseWhitespace, escapeRegExp } from "../text/text.js";
 const MAX_BLOCK_LINES = 12;
 const HEADER = "What the backlog says now about entries your notes name (PLANS.md and BUGS.md as of this run; where your notes disagree, this is current):";
@@ -37,16 +40,14 @@ function seriesInfos(planned, doneTitles) {
         const key = partKey(part.series, part.part);
         let info = map.get(part.series.toLowerCase());
         if (info === undefined) {
-            info = { name: part.series, of: part.of, plannedCount: 0, replan: 0, review: 0, waiting: 0, refused: 0, holds: new Map(), done: new Set() };
+            info = { name: part.series, of: part.of, plannedCount: 0, review: 0, waiting: 0, refused: 0, holds: new Map(), done: new Set() };
             map.set(part.series.toLowerCase(), info);
         }
         info.plannedCount++;
         const hold = entryHoldAgainst(entry, allParts);
         info.holds.set(key, hold);
-        if (hold === "needs-replan")
-            info.replan++;
-        else if (hold === "needs-review" || hold === "held-for-operator")
-            info.review++; // vocabulary-ok: the held-for-operator hold is an operator decision
+        if (hold === "needs-review")
+            info.review++;
         else if (hold === "refused")
             info.refused++;
         else if (typeof hold === "object" && hold !== null)
@@ -85,11 +86,8 @@ function partRefsInLine(line) {
 function firstSixWords(normalizedKey) {
     return normalizedKey.split(/\s+/).slice(0, 6).join(" ");
 }
-/** The wording of one named item's state: an eligibility hold, `done`, or `not in the backlog`.
- * `file` is which backlog the entry lives in, so a held-for-operator entry names the operator's
- * matching release command (`tumwater plan --release` for a plan, `tumwater bug --release` for a
- * bug) — the same Plan/Bug derivation the operator-held alert uses. */
-function holdWording(state, file = "plans") {
+/** The wording of one named item's state: an eligibility hold, `done`, or `not in the backlog`. */
+function holdWording(state) {
     if (state === "done")
         return "done";
     if (state === "not-in-backlog")
@@ -98,27 +96,19 @@ function holdWording(state, file = "plans") {
         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")
-        return "needs review";
-    if (state === "needs-replan")
-        return "needs replan (the plan role rewrites it)";
-    if (state === "held-for-operator")
-        return `held for the operator (tumwater ${entryKindLabel(file).toLowerCase()} --release)`; // vocabulary-ok: names the operator-held wording and the operator's release command
-    if (state === "waiting-for-failure")
-        return "waiting for the next failure";
+    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
     return `waits on ${state.blockedBy.join(", ")}`;
 }
 /** The one summary line of a named series' planned-part state. */
 function seriesSummary(info) {
     const counts = [];
-    if (info.replan > 0)
-        counts.push(`${info.replan} ${info.replan === 1 ? "needs a replan" : "need a replan"}`);
     if (info.review > 0)
         counts.push(`${info.review} ${info.review === 1 ? "needs review" : "need review"}`);
     if (info.waiting > 0)
         counts.push(`${info.waiting} ${info.waiting === 1 ? "waits" : "wait"} on an earlier part`);
     counts.push(info.refused === 0 ? "none refused" : `${info.refused} refused`);
-    return `${info.plannedCount} ${info.plannedCount === 1 ? "part" : "parts"} planned: ${counts.join(", ")}`;
+    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) {
@@ -173,12 +163,15 @@ export function notesBacklogBlock(notes, backlog) {
         const info = series.get(p.seriesLower);
         if (info === undefined)
             continue;
-        lines.push(`- ${info.name}, part ${p.part}/${p.of} — ${holdWording(p.state, "plans")}`);
+        lines.push(`- ${info.name}, part ${p.part}/${p.of} — ${holdWording(p.state)}`);
     }
     for (const entry of namedEntries.values())
-        lines.push(`- ${entry.title} — ${holdWording(entry.state, entry.file)}`);
+        lines.push(`- ${entry.title} — ${holdWording(entry.state)}`);
     if (lines.length === 0)
         return undefined;
-    const shown = lines.slice(0, MAX_BLOCK_LINES - 1);
-    return [HEADER, ...shown].join("\n");
+    const cap = MAX_BLOCK_LINES - 1; // the item lines; the header is the twelfth line
+    if (lines.length <= cap)
+        return [HEADER, ...lines].join("\n");
+    const shown = lines.slice(0, cap - 1);
+    return [HEADER, ...shown, `… and ${plural(lines.length - shown.length, "more named item")}`].join("\n");
 }

package/dist/src/prompt/principles.js

@@ -12,3 +12,14 @@ export function readPrinciples(root) {
     const file = path.join(root, "PRINCIPLES.md");
     return truncateWithNote(readTextOrNull(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
+ * `principles` row's over-cap warn, surfaced on `tumwater status`, the dashboard and the TUI
+ * without a doctor run. Uses the doctor row's own predicate (raw.trim().length >
+ * PRINCIPLES_MAX_CHARS), so the alert and the doctor row cannot disagree. Missing, unreadable
+ * (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"));
+    return raw !== null && raw.trim().length > PRINCIPLES_MAX_CHARS;
+}

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

@@ -68,24 +68,16 @@ ${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", 
-/** 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) {
+export function buildHandoffPrompt(roleId, runPrompt, cause = "handoff") {
     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 === "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;
+        : 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

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { describeCheck } from "../build/build-check-report.js";
-import { DECOMPOSITION_GUIDANCE, NEEDS_REPLAN_NOTE, NEEDS_REVIEW_NOTE, PLAN_QUEUE_GUIDANCE, PLAN_SIZING } from "../roles/role-guidance.js";
+import { DECOMPOSITION_GUIDANCE, NEEDS_REVIEW_NOTE, PLAN_QUEUE_GUIDANCE, PLAN_SIZING } from "../roles/role-guidance.js";
 import { CLAIMS_RULE, REPLY_ENDINGS } from "../verdict/reply-contract.js";
 import { todayStamp } from "../budget/budget.js";
 import { daysBetween } from "../text/datetime.js";
@@ -93,7 +93,7 @@ function backendRuleLines(rules) {
 /** The date line every pi prompt carries — run and director (via sharedPreamble) and the gate's
  * conflict and review runs — naming the local calendar day as YYYY-MM-DD. No prompt
  * used to say what day it is, so a run that had to write one (a BUGS.md heading's "(found by …
- * YYYY-MM-DD)", a Fixed or Refused date, NEEDS_REVIEW_NOTE's and NEEDS_REPLAN_NOTE's
+ * YYYY-MM-DD)", a Fixed or Refused date, NEEDS_REVIEW_NOTE's
  * <YYYY-MM-DD>, a plan deadline)
  * inferred it from the newest dates in the repo, which were themselves drifting: the team
  * stamped entries days into the future and each wrong date seeded the next. The day is
@@ -261,7 +261,7 @@ note's say-so.`
 source of what is currently true of each entry and series, so check the entry itself (and, when this run carries
 one, its line in the backlog) before acting on a note's say-so.`;
     return `Notes your role wrote in earlier runs (${savedClause(savedDay, today)}yours, unverified — check against the code before
-relying on them). A claim they make about an entry's backlog state — refused, blocked, abandoned, needs-replan,
+relying on them). A claim they make about an entry's backlog state — refused, blocked, abandoned,
 done, behind another entry — is a snapshot of the past, not the present: ${liveSource}
 A note that tells you to skip or never re-author an entry is always overridden by the backlog.
 <role-notes>\n${notes.trim()}\n</role-notes>`;
@@ -307,7 +307,7 @@ 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, check, gateCommand, briefFile, today, userRequest, agent, assigned } = 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 parts = [
@@ -338,6 +338,8 @@ role's scope, say so in your reply instead of doing it anyway.\n<user-request>\n
     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)
@@ -396,8 +398,7 @@ work yourself:
   direction — so roles can pick it up again.
 - A decision about a marked plan (e.g. "split plan X", "keep plan X whole", "replan X"):
   split it into independently landable sub-plans per PLAN_SIZING, or clear the
-  ${NEEDS_REVIEW_NOTE} note, or clear a ${NEEDS_REPLAN_NOTE} note and rewrite the entry — per
-  the user's direction.
+  ${NEEDS_REVIEW_NOTE} note — per the user's direction.
 - A request to manage custom roles ("add a role named X that does Y", "remove X",
   "move X before Y"): write the FULL replacement customRoles array to
   .tumwater-config-request.json at your worktree root — the shape is
@@ -421,12 +422,14 @@ work yourself:
         parts.push(`Additional standing instructions from the user:\n${extraInstructions.trim()}`);
     // Before the shared rules, not after them: the closing reply contract stays the last thing
     // in the prompt, where a model attends to it most (the run prompt's invariant too).
-    parts.push(`Note on one boundary in the rules below, director only: user-defined-role requests are
-executed by writing .tumwater-config-request.json in your worktree (shape and worked example
-above) — never by editing tumwater.json, which stays off-limits to you as to every role. Tumwater
-validates the request and applies only its customRoles array; a request that also names
-any other setting (timeouts, budgets, role enablement, review settings) has that key discarded
-with a warning, so such a request is guidance to record per the routing rules, not an edit you
+    parts.push(`Note on one boundary in the rules below, director only: user-defined-role requests and a
+project check declaration are executed by writing .tumwater-config-request.json in your worktree
+(shape and worked example above) — never by editing tumwater.json, which stays off-limits to you
+as to every role. The request may carry only customRoles and check.command: tumwater validates it
+and runs a declared check.command green in the worktree before writing it. A request that also
+names any other setting (timeouts, budgets, role enablement, review settings, gateCommand,
+mergeCommand, check.cwd) has that key discarded with a warning, so such a request is guidance
+that stays staged or is recorded per the routing rules, not an edit you
 can make.`);
     // A director run is never assigned an entry.
     parts.push(commonRules(check, briefFile, undefined, dialectFor(backend)).trim());

package/dist/src/redeploy/redeploy-probes.js

@@ -20,7 +20,10 @@ export function track(promise) {
  * shape prewarms nothing further — there is no point staging a compile for a tree the check
  * condemned — and is simply not adopted (the episode re-runs it under its own rules).
  * Skipped while an episode is pending: its own steps are the warm-up, and the mirror worktree
- * both run in must not serve two checks at once. */
+ * both run in must not serve two checks at once. A new head that arrives while a step is still
+ * running is likewise not adopted: returning without resetting keeps the mirror pointed at the
+ * head the running check (or compile) is testing, never re-pointed under it; the next poll after
+ * both settle takes the newest head as today. */
 export class PrewarmProbes {
     deps;
     head = null;
@@ -37,6 +40,13 @@ export class PrewarmProbes {
         if (pending)
             return;
         if (this.head !== head) {
+            // A newer head arrived while this head's green check or staged compile is still running
+            // (!done): never re-point the mirror under a running step — it may still be testing the
+            // sha it read before the reset, and a verdict recorded under that sha would not cover the
+            // tree it tested. Keep probing for the older head; the next poll after both settle adopts
+            // the newest head as today.
+            if ((this.green !== null && !this.green.done) || (this.compiled !== null && !this.compiled.done))
+                return;
             this.head = head;
             this.green = null;
             this.compiled = null;

package/dist/src/redeploy/redeployer.js

@@ -254,6 +254,32 @@ export class Redeployer {
         this.autoRestartOn = autoRestart;
         if (!this.selfHosted || !mainHead)
             return this.endDrain();
+        await this.observeHead(mainHead, now);
+        // The sustained-pin escalation runs BEFORE the early returns below: a latched block on a
+        // frozen main never re-enters the episode logic, and that pinned-and-stuck state is exactly
+        // what must escalate (BUGS.md 2026-09-29).
+        if (this.staleness?.stale && autoRestart)
+            this.escalateIfSustained(now);
+        if (!this.staleness?.stale || !autoRestart || this.blockedHead === mainHead)
+            return this.endDrain();
+        const cooldown = this.cooldownStage(mainHead, now);
+        if (cooldown !== null)
+            return cooldown;
+        const start = await this.startEpisode(mainHead, inFlight, now);
+        if (start !== null)
+            return start;
+        const green = this.greenStage(mainHead, now);
+        if (green !== null)
+            return green;
+        const compile = this.compileStage(mainHead, now);
+        if (compile !== null)
+            return compile;
+        return this.drainAndSwap(mainHead, inFlight, now);
+    }
+    /** Observe a moved main head (a no-op on an unchanged head): update staleness, log build_stale
+     * on the fresh transition, run the sustained-pin clock and its forced-restart waiver, and drop
+     * any restart pending for a superseded head. */
+    async observeHead(mainHead, now) {
         if (mainHead !== this.lastHead) {
             const wasStale = this.staleness?.stale ?? false;
             this.lastHead = mainHead;
@@ -286,13 +312,12 @@ export class Redeployer {
             if (this.pendingHead !== null && this.pendingHead !== mainHead)
                 this.clearPending();
         }
-        // The sustained-pin escalation runs BEFORE the early returns below: a latched block on a
-        // frozen main never re-enters the episode logic, and that pinned-and-stuck state is exactly
-        // what must escalate (BUGS.md 2026-09-29).
-        if (this.staleness?.stale && autoRestart)
-            this.escalateIfSustained(now);
-        if (!this.staleness?.stale || !autoRestart || this.blockedHead === mainHead)
-            return this.endDrain();
+    }
+    /** The restart cooldown / forced-restart waiver gate: while the deferral holds, warn once, keep
+     * the team running on the stale build, prewarm the deferred head's green check and compile, and
+     * end any drain. Once lapsed, say why a red running build starts the episode early. Returns
+     * null when the cooldown has passed and the episode may begin. */
+    cooldownStage(mainHead, now) {
         // Completed auto-restarts are rate-limited to one per RESTART_COOLDOWN_MS (BUGS.md 2026-09-11):
         // under sustained churn every stale head would otherwise drive a full hold+drain+swap episode
         // back to back. Inside the cooldown the team keeps running on the stale build exactly as when
@@ -341,6 +366,12 @@ export class Redeployer {
             this.warn(`auto-restart of ${shortSha(mainHead)} proceeding early — the running version ${shortSha(this.build.sha)} fails its check, ` +
                 `the cooldown was cut to ${RESTART_URGENT_COOLDOWN_MIN} min and that deadline has already passed`);
         }
+        return null;
+    }
+    /** The boot gate behind which an episode opens: refuse to hold onto a generation that cannot
+     * boot here, else adopt the pre-warmed green/compile verdicts and hold the team until the
+     * staged tree is ready. Returns null when an episode is already pending. */
+    async startEpisode(mainHead, inFlight, now) {
         if (this.pendingHead === null) {
             // Before holding anything: could a new generation even boot here? A refusal here costs
             // nothing — no hold, no green check, no compile — so asking again every poll is how a
@@ -369,6 +400,11 @@ export class Redeployer {
                 this.logRestartPending(mainHead);
             return "hold";
         }
+        return null;
+    }
+    /** The green check: hold while it is unresolved, drop the episode when it could not run, block
+     * when it returns a red verdict. Returns null (proceed to compile) only on a green verdict. */
+    greenStage(mainHead, now) {
         if (!this.green?.done)
             return "hold";
         // A REJECTED check is not a verdict: it could not run (git broke inside the mirror worktree,
@@ -390,6 +426,12 @@ export class Redeployer {
             this.block(mainHead, reason, `${reason} — holding the restart until main is green`);
             return this.endDrain();
         }
+        return null;
+    }
+    /** The compile stage: kick off (or hold on) the staged build, and on a verdict block or drop the
+     * episode when the tree failed to build. Returns null (proceed to drain) only on a successful
+     * compile. */
+    compileStage(mainHead, now) {
         if (!this.compiled) {
             this.compiled = this.probes.adoptCompile(mainHead) ?? track(this.deps.compile(mainHead));
             this.logRestartPending(mainHead);
@@ -425,6 +467,11 @@ export class Redeployer {
             this.block(mainHead, reason, `${reason} — staying on version ${shortSha(this.build.sha)}: ${detail}`);
             return this.endDrain();
         }
+        return null;
+    }
+    /** The drain and swap: hold while runs keep the drain open, re-ask the boot gate before the
+     * point of no return, then swap the staged tree in and record the completed restart. */
+    async drainAndSwap(mainHead, inFlight, now) {
         // The drain rule, split by who requested the work (BUGS.md 2026-09-08): a director run is
         // an explicit human prompt and outranks the redeploy — while one is in flight the hold has no
         // time cap: no swap and no abort until it finishes. The per-run watchdogs already bound how

package/dist/src/redeploy/self-reload.js

@@ -5,6 +5,7 @@ import { RESTART_EXIT_CODE } from "./redeploy-policy.js";
 import { childEnv } from "../process/process.js";
 import { startParentDeathWatch } from "../process/supervisor.js";
 import { liveNodeBin } from "../process/node-bin.js";
+import { parsePositiveInt } from "../text/text.js";
 /** Auto-reload for the user-launched dashboards (`tumwater tui`, `tumwater gui`).
  *
  * Unlike the orchestrator — which the supervisor respawns onto a fresh build — a dashboard is
@@ -50,12 +51,16 @@ export function watchReloadSupervisor(onGone, seams = {}) {
     const mark = (seams.env ?? process.env)[DASHBOARD_CHILD_ENV];
     if (mark === undefined)
         return () => { };
-    const supervisor = Number(mark);
+    // The mark is a pid spelled in plain decimal (reexecSelf writes String(process.pid)); a
+    // hex/exponent/whitespace spelling is never a pid the writer meant, so read it by the shared
+    // plain-decimal rule rather than Number()'s silent coercion — the supervisor's expecter twin
+    // parses the same way.
+    const supervisor = parsePositiveInt(mark);
     return startParentDeathWatch(onGone, {
         ...(seams.ppid ? { ppid: seams.ppid } : {}),
         intervalMs: seams.intervalMs ?? SUPERVISOR_POLL_MS,
         // An older supervisor's "1" names no pid (1 is launchd/init): the watch's first read stands.
-        ...(Number.isInteger(supervisor) && supervisor > 1 ? { expectedPpid: supervisor } : {}),
+        ...(supervisor !== null && supervisor > 1 ? { expectedPpid: supervisor } : {}),
     });
 }
 /** Hand this process's dashboard duty to a fresh copy of itself (`process.argv.slice(1)` re-runs