tumwater 0.4.0 → 0.4.2

package/dist/src/cli/cli-query-commands.js

@@ -16,7 +16,7 @@ import { renderStatus } from "../ui/status-render.js";
 import { backlogPayload } from "../backlog/backlog.js";
 import { backlogHolds, backlogInProgress } from "../backlog/backlog-eligibility.js";
 import { readyBacklog, grepBacklog, renderBacklogMarkdown } from "../backlog/backlog-render.js";
-import { loadQuarantine } from "../review/known-flakes.js";
+import { loadQuarantine, releaseQuarantinedTest } from "../review/known-flakes.js";
 import { quarantineRows, renderQuarantine } from "../review/quarantine-render.js";
 import { collectChangeOverlaps, scopeChangeOverlaps, scopeChangeOverlapsToPath, collectTeamChanges, collectRoleChange, collectRoleChanges, normalizeDiffPath } from "../change/change-data.js";
 import { renderChangeOverlaps, renderTeamChange, renderRoleChange, renderRoleChanges } from "../change/change-render.js";
@@ -338,14 +338,49 @@ export async function cmdBacklog(root, args, seams = {}) {
     const result = readBacklog();
     sayJsonOrRender(rest, result.view, () => renderBacklogText(result));
 }
-// `tumwater quarantine [--json]` — the read-only view of the review gate's flake
-// quarantine. No requireReadyRepo gate: loadQuarantine degrades an absent or malformed
-// file to the empty list (the cmdBacklog rationale), so the command prints the empty line
-// in any directory, and it never writes quarantine.json (a test leaves the list only
-// through releaseQuarantine). --json serves the same positioned rows to scripts.
+// `tumwater quarantine [--release <n>] [--json]` — the view of the review gate's flake
+// quarantine, read-only except the one destructive `--release <n>` mode that removes the Nth
+// entry the list prints at the operator's request. The read path keeps its no-gate
+// refuseTeamWorkspace stance: loadQuarantine degrades an absent or malformed file to the empty
+// list, so the command prints the empty line in any directory and the read never writes
+// quarantine.json (a test otherwise leaves the list through releaseQuarantine). --json serves
+// the same positioned rows to scripts.
 export async function cmdQuarantine(root, args) {
+    // `--release <n>` is the read-only command's one destructive mode: route it to its own
+    // branch before the read gate, exactly as cmdReviews routes `--accept`.
+    if (args.includes("--release")) {
+        await cmdQuarantineRelease(root, args);
+        return;
+    }
     rejectUnknownArgs("quarantine", args, [JSON_FLAG]);
     refuseTeamWorkspace(root);
     const rows = quarantineRows(loadQuarantine(root));
     sayJsonOrRender(args, { tests: rows }, () => renderQuarantine(rows, Date.now()));
 }
+/** The `tumwater quarantine --release <n>` branch: remove the Nth entry `tumwater quarantine`
+ * lists (the same oldest-first 1..N row `quarantineRows` prints) at the operator's request,
+ * the manual twin of the auto-release that fires when a filed bug leaves `## Open`. Parsed the
+ * way cmdReviewsAccept parses `--accept`: `--release <n>` the one valued flag, `--json` the one
+ * boolean (at most once), `--help`/`-h` tolerated, anything else refused. An out-of-range
+ * position fails naming the current depth; a concurrent removal answers `false`. */
+async function cmdQuarantineRelease(root, args) {
+    const { json, position, rest } = scanPositionArgs(args, "--release", "--release 2");
+    rejectUnknownArgs("quarantine", rest, []);
+    if (position === null)
+        fail("--release needs a position (usage: tumwater quarantine --release <n>)");
+    await requireReadyRepo(root);
+    const rows = quarantineRows(loadQuarantine(root));
+    if (position < 1 || position > rows.length) {
+        fail(`no quarantined test at position ${position} (flake quarantine holds ${rows.length} tests)`);
+    }
+    const test = rows[position - 1].test;
+    if (!releaseQuarantinedTest(root, test)) {
+        fail(`quarantined test at position ${position} is already gone`);
+    }
+    if (json) {
+        sayJson({ released: { position, test } });
+    }
+    else {
+        say(`released quarantined test ${position}: ${test} — the gate no longer excuses it`);
+    }
+}

package/dist/src/cli/cli-review-commands.js

@@ -4,7 +4,8 @@
  * `readPostReviews` reads a missing, torn or hand-edited file as the well-formed subset (or `[]`),
  * so the command prints the empty line in any directory. Read-only except the one destructive
  * `--accept <n>` mode, which removes the Nth entry the operator deliberately accepts unreviewed
- * (the action the at-risk alert's advice names); that mode adds no new ready-repo requirement to
+ * (the action the doctor's at-risk post-review row's advice names); that mode adds no new
+ * ready-repo requirement to
  * the read path and gates the write with `requireReadyRepo`. Unlike `cmdQueue`'s `--cancel`, the
  * read case still writes no file. */
 import { JSON_FLAG, ROLE_FLAG, rejectUnknownArgs, statusFlagSpec } from "./cli-flag-specs.js";

package/dist/src/cli/cli-role-command.js

@@ -17,7 +17,7 @@ import { renderRoleMarkdown } from "../roles/role-render.js";
 import { DIRECTOR_ROLE, unknownRoleMessage } from "../roles/roles.js";
 import { saveRoleNote } from "../agent/role-notes-write.js";
 import { roleNotesPath } from "../paths.js";
-import { errorMessage } from "../text/text.js";
+import { errorMessage, isExponentSpelling } from "../text/text.js";
 import { readPromptFileArg } from "./cli-command-args.js";
 import { canonicalRoleId } from "../roles/legacy-role-ids.js";
 import { INSTANCE_ROLES, baseRoleOf } from "../roles/runner-ids.js";
@@ -44,12 +44,6 @@ const CAP_SPEC = { names: ["--cap"], value: true, valueName: "<usd>" };
 function plainDecimalToJson(raw) {
     return /^\d*\.?\d+$/.test(raw) ? String(Number(raw)) : null;
 }
-/** Detect exponent spellings that the cap, interval and instances writes must reject
- * before JSON parsing can turn them into otherwise valid numeric config values. Other
- * invalid spellings fall through to the config validator, which names the key. */
-function isExponentSpelling(raw) {
-    return raw.trim() !== "" && plainDecimalToJson(raw) === null && /^\d+(\.\d+)?[eE][+-]?\d+$/.test(raw.trim());
-}
 /** `role`'s min-run-interval write flags: clear it, or set it to a second count (0 is
  * back-to-back). */
 const CLEAR_MIN_RUN_INTERVAL_SPEC = { names: ["--clear-min-run-interval"] };
@@ -119,6 +113,19 @@ function requireKnownRole(root, id) {
     if (!knownRoleIds(cfg).includes(id))
         throw new Error(unknownRoleMessage(id, knownRoleIds(cfg)));
 }
+/** Refuse the two mistakes a per-role config write must reject up front: handing both a
+ * set flag and its clear twin (e.g. `--model` with `--clear-model`), and passing --json,
+ * which only the read/render path honors. `setFlag`/`clearFlag` are the exact spellings the
+ * refusal names (the clear twin is not always `--clear` + the set flag — `--notes-file`'s
+ * twin is `--clear-notes`), and `writeNoun` is the "<a|an> X write" phrase the --json
+ * refusal needs. Every set/clear write branch opens with the same two-line prelude, so
+ * this keeps it in one place. */
+function rejectSetClearAndJson(rest, setFlag, clearFlag, writeNoun) {
+    if (rest.includes(setFlag) && rest.includes(clearFlag))
+        fail(`give ${clearFlag} or ${setFlag}, not both`);
+    if (rest.includes("--json"))
+        fail(`--json does not apply to ${writeNoun}`);
+}
 /** The config-key write the seven per-role hold branches (quiet hours, daily cap, min run
  * interval, provider, model, thinking and backend) share: with `clear`, or an empty typed
  * value, unset `key` under `base`; else set it. `serialize` shapes the value `setConfigKey`
@@ -237,10 +244,7 @@ export async function cmdRole(root, args) {
     if (writes.length > 1)
         fail(`${writes.join(" and ")} writes cannot share one invocation`);
     if (notesWrite) {
-        if (clear && rest.includes("--notes-file"))
-            fail("give --clear-notes or --notes-file, not both");
-        if (rest.includes("--json"))
-            fail("--json does not apply to a notes write");
+        rejectSetClearAndJson(rest, "--notes-file", "--clear-notes", "a notes write");
         if (id === DIRECTOR_ROLE)
             fail("the director has no notes");
         requireKnownRole(root, id);
@@ -259,10 +263,7 @@ export async function cmdRole(root, args) {
     // enforces the 4096-char cap and the write is atomic. The director is allowed here (its
     // override reaches its own runs), unlike the notes branch's director refusal.
     if (instructionsWrite) {
-        if (clearInst && rest.includes("--instructions-file"))
-            fail("give --clear-instructions or --instructions-file, not both");
-        if (rest.includes("--json"))
-            fail("--json does not apply to an instructions write");
+        rejectSetClearAndJson(rest, "--instructions-file", "--clear-instructions", "an instructions write");
         requireKnownRole(root, id);
         const base = baseRoleOf(id);
         if (clearInst) {
@@ -287,10 +288,7 @@ export async function cmdRole(root, args) {
     // The director is exempt — its quietHoursPerRole.director entry is inert (the gate and
     // doctor both exempt it), like the notes branch's director refusal.
     if (quietWrite) {
-        if (clearQuiet && rest.includes("--quiet-hours"))
-            fail("give --clear-quiet-hours or --quiet-hours, not both");
-        if (rest.includes("--json"))
-            fail("--json does not apply to a quiet-hours write");
+        rejectSetClearAndJson(rest, "--quiet-hours", "--clear-quiet-hours", "a quiet-hours write");
         requireKnownRole(root, id);
         if (id === DIRECTOR_ROLE)
             fail("the director has no quiet hours");
@@ -307,10 +305,7 @@ export async function cmdRole(root, args) {
     // atomic. The director is exempt — it has no cap, like the notes and quiet-hours branches'
     // director refusals.
     if (capWrite) {
-        if (clearCap && rest.includes("--cap"))
-            fail("give --clear-cap or --cap, not both");
-        if (rest.includes("--json"))
-            fail("--json does not apply to a cap write");
+        rejectSetClearAndJson(rest, "--cap", "--clear-cap", "a cap write");
         requireKnownRole(root, id);
         if (id === DIRECTOR_ROLE)
             fail("the director has no daily cap");
@@ -326,7 +321,7 @@ export async function cmdRole(root, args) {
         // already a plain decimal, so the exponent form is exactly the silent-write set; hex,
         // negative and non-numeric spellings fall through to the write path, whose
         // validateConfig message names the key.
-        if (isExponentSpelling(cap))
+        if (isExponentSpelling(cap.trim()))
             fail(`${cfgKey} must be a plain dollar amount like 25, 12.50, or .5 — no +/-, exponent, or hex notation`);
         writeRoleConfigKey(root, base, clearCap, cap, cfgKey, "daily cap", (v) => plainDecimalToJson(v) ?? v, (v) => v);
         return;
@@ -339,10 +334,7 @@ export async function cmdRole(root, args) {
     // write is atomic. Unlike the notes/quiet-hours/cap branches there is no director refusal:
     // the director runs on the same clock.
     if (intervalWrite) {
-        if (clearInterval && rest.includes("--min-run-interval"))
-            fail("give --clear-min-run-interval or --min-run-interval, not both");
-        if (rest.includes("--json"))
-            fail("--json does not apply to a min-run-interval write");
+        rejectSetClearAndJson(rest, "--min-run-interval", "--clear-min-run-interval", "a min-run-interval write");
         requireKnownRole(root, id);
         const base = baseRoleOf(id);
         const cfgKey = `roles.${base}.minRunIntervalSeconds`;
@@ -356,7 +348,7 @@ export async function cmdRole(root, args) {
         // plain decimal, so the exponent form is exactly the silent-write set; hex, negative and
         // non-numeric spellings fall through to the write path, whose validateConfig message
         // names the key.
-        if (isExponentSpelling(secs))
+        if (isExponentSpelling(secs.trim()))
             fail(`${cfgKey} must be a plain second count like 300, 0.5, or .5 — no +/-, exponent, or hex notation`);
         writeRoleConfigKey(root, base, clearInterval, secs, cfgKey, "min run interval", (v) => plainDecimalToJson(v) ?? v, (v) => `${v}s`);
         return;
@@ -369,10 +361,7 @@ export async function cmdRole(root, args) {
     // validateConfig's `!INSTANCE_ROLES.has(id)` branch answers for the director and every
     // custom role, and an unset/empty value clears the key.
     if (instancesWrite) {
-        if (clearInstances && rest.includes("--instances"))
-            fail("give --clear-instances or --instances, not both");
-        if (rest.includes("--json"))
-            fail("--json does not apply to an instances write");
+        rejectSetClearAndJson(rest, "--instances", "--clear-instances", "an instances write");
         const loaded = loadConfigSafe(root);
         const cfg = loaded.config ?? defaultConfig();
         if (!knownRoleIds(cfg).includes(id))
@@ -389,7 +378,7 @@ export async function cmdRole(root, args) {
         // or out ("9e0" → 9 too) — is refused here, while fractional, hex, negative and plain
         // out-of-range integer spellings fall through to the write path, whose validateConfig
         // message names the key.
-        if (isExponentSpelling(n))
+        if (isExponentSpelling(n.trim()))
             fail(`${cfgKey} must be a plain integer from 1 to 8 — no exponent notation`);
         // An absent count already means 1 (instanceCount's default), so asking for 1 is a no-op —
         // but only for a role that may split; any other role falls through to validateConfig's refusal.
@@ -401,65 +390,30 @@ export async function cmdRole(root, args) {
         writeRoleConfigKey(root, base, clearInstances, n, `roles.${base}.instances`, "instances", (v) => v, (v) => v);
         return;
     }
-    // The model-triple writes: the terminal twins of `config set roles.<base>.provider|model|thinking
-    // <value>` and `config unset` — the three fields configForRole resolves through seamOverrides.
-    // `tumwater role <id>` renders them as its Model: line. Each lands in roles.<base>.<field>.
-    // Through setConfigKey/unsetConfigKey, validateConfig's checkModelTripleField ("tier-name"
-    // shape) owns validation (model accepts a tier name; thinking must be a THINKING_LEVELS level)
-    // and each write is atomic. No director refusal: accepted exactly as --min-run-interval is.
-    if (providerWrite) {
-        if (clearProvider && rest.includes("--provider"))
-            fail("give --clear-provider or --provider, not both");
-        if (rest.includes("--json"))
-            fail("--json does not apply to a provider write");
-        const cfg = loadConfigSafe(root).config ?? defaultConfig();
-        if (!knownRoleIds(cfg).includes(id))
-            throw new Error(unknownRoleMessage(id, knownRoleIds(cfg)));
-        const base = baseRoleOf(id);
-        const provider = flagValue(rest, "--provider") ?? "";
-        writeRoleConfigKey(root, base, clearProvider, provider, `roles.${base}.provider`, "provider", (v) => JSON.stringify(v), (v) => v);
-        return;
-    }
-    if (modelWrite) {
-        if (clearModel && rest.includes("--model"))
-            fail("give --clear-model or --model, not both");
-        if (rest.includes("--json"))
-            fail("--json does not apply to a model write");
-        const cfg = loadConfigSafe(root).config ?? defaultConfig();
-        if (!knownRoleIds(cfg).includes(id))
-            throw new Error(unknownRoleMessage(id, knownRoleIds(cfg)));
-        const base = baseRoleOf(id);
-        const model = flagValue(rest, "--model") ?? "";
-        writeRoleConfigKey(root, base, clearModel, model, `roles.${base}.model`, "model", (v) => JSON.stringify(v), (v) => v);
-        return;
-    }
-    if (thinkingWrite) {
-        if (clearThinking && rest.includes("--thinking"))
-            fail("give --clear-thinking or --thinking, not both");
-        if (rest.includes("--json"))
-            fail("--json does not apply to a thinking write");
-        const cfg = loadConfigSafe(root).config ?? defaultConfig();
-        if (!knownRoleIds(cfg).includes(id))
-            throw new Error(unknownRoleMessage(id, knownRoleIds(cfg)));
-        const base = baseRoleOf(id);
-        const level = flagValue(rest, "--thinking") ?? "";
-        writeRoleConfigKey(root, base, clearThinking, level, `roles.${base}.thinking`, "thinking", (v) => JSON.stringify(v), (v) => v);
-        return;
-    }
-    // The backend write: the twin of the provider/model/thinking writes, landing the role's
-    // backend (`pi`, `claude`, `opencode` or `codex`) in roles.<base>.backend through the same
-    // setConfigKey/unsetConfigKey core, so validateConfig's checkEntryBackend owns the id
-    // (rejecting an unknown one, and a `model` that cannot pair with the named backend) and
-    // the write stays atomic. An instance id writes its base role's key, like the others.
-    if (backendWrite) {
-        if (clearBackend && rest.includes("--backend"))
-            fail("give --clear-backend or --backend, not both");
-        if (rest.includes("--json"))
-            fail("--json does not apply to a backend write");
+    // The model-writing branches — provider, model, thinking and backend — are one shape: each
+    // lands the role's field in roles.<base>.<field> (the terminal twin of `config set
+    // roles.<base>.<field> <value>` and `config unset`) through the same setConfigKey/unsetConfigKey
+    // core, so validateConfig owns the id — checkModelTripleField ("tier-name" shape: model
+    // accepts a tier name, thinking a THINKING_LEVELS level) for the provider/model/thinking
+    // fields that configForRole resolves through seamOverrides, checkEntryBackend for backend
+    // (`pi`, `claude`, `opencode` or `codex`, refusing an unknown one and a model that cannot
+    // pair with it) — and each write is atomic. No director refusal: each is accepted exactly as
+    // --min-run-interval is, and an instance id writes its base role's key. Every branch calls
+    // writeRoleConfigKey with the same JSON-encode/identity shaping, differing only in the flag
+    // spellings, the key field and the noun the confirmation line names — one table, one body.
+    for (const { flag, clearFlag, write, clear, field, noun } of [
+        { flag: "--provider", clearFlag: "--clear-provider", write: providerWrite, clear: clearProvider, field: "provider", noun: "provider" },
+        { flag: "--model", clearFlag: "--clear-model", write: modelWrite, clear: clearModel, field: "model", noun: "model" },
+        { flag: "--thinking", clearFlag: "--clear-thinking", write: thinkingWrite, clear: clearThinking, field: "thinking", noun: "thinking" },
+        { flag: "--backend", clearFlag: "--clear-backend", write: backendWrite, clear: clearBackend, field: "backend", noun: "backend" },
+    ]) {
+        if (!write)
+            continue;
+        rejectSetClearAndJson(rest, flag, clearFlag, `a ${noun} write`);
         requireKnownRole(root, id);
         const base = baseRoleOf(id);
-        const backend = flagValue(rest, "--backend") ?? "";
-        writeRoleConfigKey(root, base, clearBackend, backend, `roles.${base}.backend`, "backend", (v) => JSON.stringify(v), (v) => v);
+        const value = flagValue(rest, flag) ?? "";
+        writeRoleConfigKey(root, base, clear, value, `roles.${base}.${field}`, noun, (v) => JSON.stringify(v), (v) => v);
         return;
     }
     // The enable/disable write: the scoped write for the enabled state `tumwater role <id>`
@@ -489,7 +443,7 @@ export async function cmdRole(root, args) {
         say(`${base}: ${state}`);
         return;
     }
-    // The review-after-merge write: the one command the post-merge churn alert's remedy
+    // The review-after-merge write: the one command the post-merge churn row's remedy
     // needs — add the role to, or remove it from, review.afterMerge for the base id, the
     // membership test reviewedAfterMerge shares. The whole-list value lands through the same
     // setConfigKey core `config set review.afterMerge <json>` uses, so validateConfig owns the

package/dist/src/cli/cli-start.js

@@ -24,25 +24,10 @@ import { ONCE_FAILURE_RESULTS, inheritedWindowStart, onceFailures, onceReport, o
  * renames the other. */
 const GUI_TOKEN_ENV = "TUMWATER_GUI_TOKEN";
 export { ONCE_FAILURE_RESULTS, inheritedWindowStart, onceFailures, onceReport, onceSummary, parseRunWindow, renderOnceSummary, windowReport, windowSummary, };
-/** `tumwater start`: boot the team and stream its event feed to this terminal until it stops.
- * Three layers cooperate here: without SUPERVISED_ENV this process becomes the supervisor
- * (superviseStartCommand below), spawning the real orchestrator as a child generation; the child
- * runs runOrchestrator to completion, handing the terminal back via RESTART_EXIT_CODE after a
- * self-redeploy so the supervisor respawns on the new build; --once collapses the whole thing
- * into one round of runs and a summary line (onceSummary below), for cron-style invocations.
- * `--for <duration>` keeps the daemon shape (redeployer, LaunchServicesWatch, supervisor hand-off
- * all stay) but arms a deadline: at the deadline the same graceful stop a Ctrl+C runs fires, and
- * the process exits after printing the summary. A mid-run self-redeploy hands the same args
- * (including `--for`) to the supervisor's next child, and the supervisor hands every generation
- * the same window start (RUN_WINDOW_START_ENV), so the deadline and the summary span the whole
- * window; only the final exit prints the summary. */
-export async function cmdStart(root, args) {
-    // The one function the self-redeploy asks before swapping onto a successor and the supervisor
-    // asks when a generation dies, so the three cannot disagree about what boots. The supervisor
-    // half runs it too, so a start that cannot boot fails before any child spawns. The flag
-    // vocabulary is validated by the dispatcher (cli.ts, from the same START_FLAG_SPECS).
-    const once = args.includes("--once");
-    const json = args.includes("--json");
+/** Refuse the --once run-mode rivals: a TUI and a dashboard each cannot be hosted by a run that
+ * is about to stop, so both are refused together before any boot. --for stays allowed — both
+ * serve for the window. Owns the run-mode rival refusals. */
+function assertOnceRivalFlags(args, once) {
     // The TUI cannot be hosted by a run that is about to stop, like the dashboard: a --once round
     // drains and exits within the same invocation, so the two shapes are refused together before
     // any boot. --for stays allowed — the TUI runs for the window, like the dashboard.
@@ -53,6 +38,10 @@ export async function cmdStart(root, args) {
     // stays allowed — the dashboard serves for the window.
     if (once && args.includes("--gui"))
         failRivalShapes("--gui", "--once", "a one-round run cannot serve a dashboard it is about to kill");
+}
+/** Refuse the dashboard-only flags that name nothing without --gui. Owns the dashboard-only
+ * refusals. */
+function assertDashboardOnlyFlags(args) {
     // `--port` chooses the `--gui` dashboard's port; without `--gui` it names no port for this
     // command, so refuse it (a valid value already passed the spec's shape gate) before any boot.
     if (args.includes("--port") && !args.includes("--gui"))
@@ -65,6 +54,10 @@ export async function cmdStart(root, args) {
         fail("--all-interfaces is only valid with --gui (e.g. `tumwater start --gui --all-interfaces`); the standalone dashboard is `tumwater gui --all-interfaces`");
     if (args.includes("--token") && !args.includes("--gui"))
         fail("--token is only valid with --gui (e.g. `tumwater start --gui --token s3cret`); the standalone dashboard is `tumwater gui --token <secret>`");
+}
+/** Check the --token value and scrub `--token <value>` off this process's argv. Owns the --token
+ * value check and the argv scrub. */
+function handleTokenFlag(args) {
     // A malformed --token (valueless, empty, or flag-looking) must fail here before any boot, so
     // a bad secret never leaves the team running behind a dashboard that exited. The same
     // tokenValueProblem `tumwater gui` runs, named for the one-command form the operator typed.
@@ -82,12 +75,10 @@ export async function cmdStart(root, args) {
         process.argv.splice(argvToken, 2);
         say(`removed --token from this process's command line; prefer the ${GUI_TOKEN_ENV} env var`);
     }
-    const forMs = parseRunWindow(args, once);
-    const branchArg = parseBranchFlag(args);
-    const startup = await runStartupCheck(root, branchArg);
-    if ("problem" in startup)
-        fail(startup.problem);
-    const { config, mainBranch } = startup;
+}
+/** Parse the --role filter against the live config and guard it to --once rounds. Owns the
+ * --role parse and its --once guard; the disabled/unknown guards stay separate (see below). */
+function resolveRoleFilter(args, config, once) {
     // A scoped once round: `--role <id>[,<id>...]` names the runners that run. Parsed here, where the
     // live config is readable. The parser accepts every known id (custom roles included, enabled
     // or not) so a typo still fails with the did-you-mean hint; an id that is known but has no
@@ -97,6 +88,11 @@ export async function cmdStart(root, args) {
     const roleFilter = parseRoleListFlag(args, knownRoleIds(config));
     if (roleFilter !== null && !once)
         fail("--role is only valid with --once");
+    return roleFilter;
+}
+/** Refuse --json without --once or --for, and the --gui/--tui rivals of a --json round/window.
+ * Owns the --json mode refusals. */
+function assertJsonMode(args, json, once, forMs) {
     if (json && !once && forMs === null)
         fail("--json is only valid with --once or --for");
     // Both interactive modes write their own banner to the stdout a JSON document must own, so a
@@ -105,6 +101,10 @@ export async function cmdStart(root, args) {
         failRivalShapes("--json", "--gui", "the dashboard writes its banner to the stdout a JSON document must own");
     if (json && args.includes("--tui"))
         failRivalShapes("--json", "--tui", "a TUI owns the terminal");
+}
+/** Guard a non-null --role filter against a disabled or unknown id. Owns the disabled/unknown
+ * --role guards, firing after the --json mode refusals so the fire order upstream is unchanged. */
+function assertRoleFilterRunnable(roleFilter, config) {
     if (roleFilter !== null) {
         const runners = runnerIds(config);
         const missing = roleFilter.find((id) => !runners.includes(id));
@@ -115,6 +115,10 @@ export async function cmdStart(root, args) {
             fail(unknownRoleMessage(missing, runners));
         }
     }
+}
+/** Refuse a second team in one repo by naming the running pid and the two ways to stop it. Owns
+ * the already-running-orchestrator refusal. */
+function assertNoRunningOrchestrator(root) {
     // The refusal an operator hits by trying to start a second team in one repo: name the
     // running pid and the two ways to stop it, so the fix is in the message instead of a
     // separate `tumwater status`/help lookup. The info file is read once and reused for the
@@ -122,20 +126,38 @@ export async function cmdStart(root, args) {
     const running = readOrchestratorInfo(root);
     if (running !== null && orchestratorAlive(root, running))
         fail(`an orchestrator is already running for this repo (pid ${running.pid}) — stop it with \`tumwater stop\` from another terminal, or press Ctrl+C in the terminal that started it`);
-    // The team-booting machinery loads only once a run actually boots: the orchestrator's
-    // module graph (with its merge pipeline, review gate, and scheduler) is the CLI's heaviest
-    // compile, and the supervisor/redeploy/launch-services pieces ride beside it. Loading them
-    // dynamically, after the fail-fast gates above, keeps every other command's spawn — and
-    // `run`'s fail-fast paths — off that cost (see cli.ts's matching lazy dispatch).
-    const { SUPERVISED_ENV, RUN_WINDOW_START_ENV, ONCE_FAILED_EXIT_CODE, startParentDeathWatch, expectedSupervisorPid } = await import("../process/supervisor.js");
-    if (!process.env[SUPERVISED_ENV]) {
-        // `args` are the flags after the command token — forward them so the child generation
-        // targets the same branch (or whatever else the invocation named).
-        // A stop marker left by a team that died before its deadline must not stop this run.
-        cancelScheduledStop(root);
-        await superviseStartCommand(root, args, branchArg, forMs);
-        return;
-    }
+}
+/** Parse and validate the invocation before any team boots: the --tui/--gui/--json/--port/
+ * --all-interfaces/--token/--role/--for/--branch guards, the --token argv scrub, runStartupCheck,
+ * and the already-running-orchestrator refusal. Returns the resolved invocation. The per-job
+ * guard groups each live in a named helper — assertOnceRivalFlags, assertDashboardOnlyFlags,
+ * handleTokenFlag, resolveRoleFilter, assertJsonMode, assertRoleFilterRunnable and
+ * assertNoRunningOrchestrator — called here in fire order. */
+async function parseStartInvocation(root, args) {
+    const once = args.includes("--once");
+    const json = args.includes("--json");
+    assertOnceRivalFlags(args, once);
+    assertDashboardOnlyFlags(args);
+    handleTokenFlag(args);
+    const forMs = parseRunWindow(args, once);
+    const branchArg = parseBranchFlag(args);
+    const startup = await runStartupCheck(root, branchArg);
+    if ("problem" in startup)
+        fail(startup.problem);
+    const { config, mainBranch } = startup;
+    const roleFilter = resolveRoleFilter(args, config, once);
+    assertJsonMode(args, json, once, forMs);
+    assertRoleFilterRunnable(roleFilter, config);
+    assertNoRunningOrchestrator(root);
+    return { once, json, forMs, branchArg, roleFilter, config, mainBranch };
+}
+/** Boot the supervised generation: the stop closure and SIGINT/SIGTERM handlers, the --for
+ * deadline timer and scheduled-stop watch, the parent-death watch, the baseline/redeploy/
+ * launch-services imports, the banner, the event subscription, runOrchestrator, and the
+ * once/window summaries and exit codes. */
+async function runSupervisedGeneration(input) {
+    const { root, once, json, forMs, branchArg, roleFilter, config, mainBranch } = input;
+    const { RUN_WINDOW_START_ENV, ONCE_FAILED_EXIT_CODE, startParentDeathWatch, expectedSupervisorPid } = await import("../process/supervisor.js");
     const controller = new AbortController();
     let stopping = false;
     const stop = () => {
@@ -179,8 +201,9 @@ export async function cmdStart(root, args) {
     const enabled = runnerIds(config);
     // A scoped round's role list is exactly the filter; otherwise every enabled role runs.
     const roles = roleFilter ?? enabled;
-    // Main's green verdicts outlive this generation: the redeployer and the roles' red-main gate
-    // start from the ones the previous generation verified instead of re-running the suite.
+    // Main's green verdicts outlive this generation: the redeployer and baseline's surviving readers
+    // (`mainTipVerdict`, the ci hand-off's `mainRedHealNote`) start from the ones the previous
+    // generation verified instead of re-running the suite.
     (await import("../baseline/main-baseline.js")).persistBaselineVerdicts(root);
     // A once round never self-redeploys: it runs one round on the build it booted and exits,
     // so the hand-off machinery (and its build stamp) stays daemon-only.
@@ -265,6 +288,50 @@ export async function cmdStart(root, args) {
     // which respawns this same script — now the new code — as the next generation.
     if (exit.restart)
         process.exit(RESTART_EXIT_CODE);
+    // A windowed (--for) run that did not self-redeploy is done the moment its summary is out:
+    // exit deterministically instead of trusting the event loop to drain. This supervised
+    // generation runs a whole team, and any ref'd handle a shutdown misses (a watcher, marker,
+    // or notifier handle a join missed) would otherwise pin this process's loop open, so the
+    // supervisor — which waits on this child's exit — never exits and the run reads as a hang:
+    // summary printed, exit code null (BUGS.md 2026-10-26). The summary above was the last
+    // output and nothing after depends on this loop, so an explicit exit is equivalent to a
+    // natural one with code 0, just guaranteed.
+    if (forMs !== null)
+        process.exit(0);
+}
+/** `tumwater start`: boot the team and stream its event feed to this terminal until it stops.
+ * Three layers cooperate here: without SUPERVISED_ENV this process becomes the supervisor
+ * (superviseStartCommand below), spawning the real orchestrator as a child generation; the child
+ * runs runOrchestrator to completion, handing the terminal back via RESTART_EXIT_CODE after a
+ * self-redeploy so the supervisor respawns on the new build; --once collapses the whole thing
+ * into one round of runs and a summary line (onceSummary below), for cron-style invocations.
+ * `--for <duration>` keeps the daemon shape (redeployer, LaunchServicesWatch, supervisor hand-off
+ * all stay) but arms a deadline: at the deadline the same graceful stop a Ctrl+C runs fires, and
+ * the process exits after printing the summary. A mid-run self-redeploy hands the same args
+ * (including `--for`) to the supervisor's next child, and the supervisor hands every generation
+ * the same window start (RUN_WINDOW_START_ENV), so the deadline and the summary span the whole
+ * window; only the final exit prints the summary. */
+export async function cmdStart(root, args) {
+    // The one function the self-redeploy asks before swapping onto a successor and the supervisor
+    // asks when a generation dies, so the three cannot disagree about what boots. The supervisor
+    // half runs it too, so a start that cannot boot fails before any child spawns. The flag
+    // vocabulary is validated by the dispatcher (cli.ts, from the same START_FLAG_SPECS).
+    const { once, json, forMs, branchArg, roleFilter, config, mainBranch } = await parseStartInvocation(root, args);
+    // The team-booting machinery loads only once a run actually boots: the orchestrator's
+    // module graph (with its merge pipeline, review gate, and scheduler) is the CLI's heaviest
+    // compile, and the supervisor/redeploy/launch-services pieces ride beside it. Loading them
+    // dynamically, after the fail-fast gates above, keeps every other command's spawn — and
+    // `run`'s fail-fast paths — off that cost (see cli.ts's matching lazy dispatch).
+    const supervisor = await import("../process/supervisor.js");
+    if (!process.env[supervisor.SUPERVISED_ENV]) {
+        // `args` are the flags after the command token — forward them so the child generation
+        // targets the same branch (or whatever else the invocation named).
+        // A stop marker left by a team that died before its deadline must not stop this run.
+        cancelScheduledStop(root);
+        await superviseStartCommand(root, args, branchArg, forMs);
+        return;
+    }
+    await runSupervisedGeneration({ root, config, mainBranch, branchArg, once, json, forMs, roleFilter });
 }
 /** Arm the windowed run's deadline timer: the one home of the arming `cmdStart` does for
  * `run --for <duration>`. A duration over setTimeout's own 32-bit signed ceiling
@@ -360,6 +427,20 @@ export function guiChildPlan(runArgs) {
         childStdio: runArgs.includes("--tui") ? ["ignore", "ignore", "ignore"] : "inherit",
     };
 }
+/** The env a supervised dashboard child is spawned with: it marks the child as owned by this
+ * supervisor (`childMarkerEnv`, DASHBOARD_CHILD_ENV, names the host pid so the child's reload
+ * watch at src/redeploy/self-reload.ts exits RESTART_EXIT_CODE / dies with the supervisor) and,
+ * when the operator gave a gate token, carries it under GUI_TOKEN_ENV. The token deliberately
+ * never reaches the child's argv: /proc/<pid>/cmdline is world-readable, and the child's own
+ * self-reload (reexecSelf, which propagates env via childEnv) would re-run a command-line secret
+ * onto each fresh generation. Kept out of superviseDashboard so this env wiring is unit-testable
+ * without spawning a live dashboard child (BUGS-FIXED.md's dashboard gate-token fix). */
+export function dashboardChildEnv(childMarkerEnv, guiToken, hostPid) {
+    const env = { [childMarkerEnv]: String(hostPid) };
+    if (guiToken !== undefined)
+        env[GUI_TOKEN_ENV] = guiToken;
+    return env;
+}
 /** The dashboard half of `run --gui`: keep a `tumwater gui` child alive across its own
  * self-reloads. The child is marked with DASHBOARD_CHILD_ENV naming this supervisor, so its
  * reload watch (src/redeploy/self-reload.ts) exits RESTART_EXIT_CODE for a fresh sibling on a
@@ -369,12 +450,7 @@ export function guiChildPlan(runArgs) {
 async function superviseDashboard(signal, guiToken, stdio = "inherit", guiArgs = []) {
     const { DASHBOARD_CHILD_ENV } = await import("../redeploy/self-reload.js");
     const { spawnGuiChild } = await import("../process/supervisor.js");
-    const env = { [DASHBOARD_CHILD_ENV]: String(process.pid) };
-    // The gate token rides in the child's env, not its argv: /proc/<pid>/cmdline is world-readable,
-    // and the child's self-reload (reexecSelf, which propagates env via childEnv) would otherwise
-    // re-run the secret onto each fresh generation.
-    if (guiToken !== undefined)
-        env[GUI_TOKEN_ENV] = guiToken;
+    const env = dashboardChildEnv(DASHBOARD_CHILD_ENV, guiToken, process.pid);
     for (;;) {
         const exit = await spawnGuiChild(signal, env, stdio, guiArgs);
         if (signal.aborted || exit.code !== RESTART_EXIT_CODE)

package/dist/src/cli/follow-view.js

@@ -3,7 +3,7 @@
  * Ctrl+C or the process that started the command exits. Lifted out of
  * cli-query-commands.ts when `report -f` landed so the follow views have one leaf
  * home instead of a per-command copy. */
-import { startParentDeathWatch } from "../process/supervisor.js";
+import { expectedSupervisorPid, startParentDeathWatch } from "../process/supervisor.js";
 import { stripTerminalControls } from "../text/text.js";
 /** The default repaint interval for a follow view — a fixed cadence, no knob. */
 const FOLLOW_VIEW_INTERVAL_MS = 2000;
@@ -47,6 +47,7 @@ export async function followView(frameText, seams) {
     // would also leave that read's rejections unhandled. Sync callers never set `painting`, so
     // the check is a no-op for them: each of their ticks still paints exactly one frame.
     let painting = false;
+    const expectedSupervisor = expectedSupervisorPid();
     await new Promise((resolve) => {
         const timer = setInterval(() => {
             if (painting)
@@ -68,6 +69,7 @@ export async function followView(frameText, seams) {
             clearInterval(timer);
             resolve();
         }, {
+            ...(expectedSupervisor !== undefined ? { expectedPpid: expectedSupervisor } : {}),
             ...(seams.ppid ? { ppid: seams.ppid } : {}),
             ...(seams.intervalMs !== undefined ? { intervalMs: seams.intervalMs } : {}),
         });