tumwater 0.4.3 → 0.4.4

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

@@ -1,9 +1,10 @@
 /** `tumwater start`'s exit-summary half: the machinery that turns a finished round or window
  * into its summary — the `--once` one-line report and its `--json` document, and the `--for`
  * window summary table and report. `src/cli/cli-start.ts` keeps `cmdStart` (the boot and the
- * run loop), the window's deadline and scheduled-stop watchdogs, the `--gui` child plan, and
- * the supervisor half; this module holds only the reporting that a `start`'s exit prints, so
- * the largest command module is no longer also the home of every way a run's tally is shaped.
+ * run loop), the window's deadline and scheduled-stop watchdogs, and the invocation guards;
+ * the supervisor half lives in `src/cli/cli-start-supervisor.ts`; this module holds only the
+ * reporting that a `start`'s exit prints, so the largest command module is no longer also the
+ * home of every way a run's tally is shaped.
  * `parseRunWindow` keeps `--for`'s shape and ceiling rules together with the window summary
  * they feed. */
 import { compareCodeUnits } from "../collections.js";

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

@@ -0,0 +1,190 @@
+import { fail, say } from "./cli-output.js";
+import { parsePortFlag } from "./cli-args.js";
+import { runStartupProblem } from "../gates/startup-gates.js";
+import { repairInterruptedSwap } from "../build/build-stage.js";
+import { logEvent } from "../events/events.js";
+import { notifyTeamDown } from "../events/event-notify.js";
+import { RESTART_EXIT_CODE } from "../redeploy/redeploy-policy.js";
+/** The env var that carries the dashboard gate token between a supervisor and its dashboard
+ * child (and across a re-exec'd dashboard generation), for the `run --gui`/`start --gui`
+ * supervisor's own use. Defined here rather than imported from gui-command.js so this module
+ * (and every `start`/`run` invocation) never pulls the GUI server graph onto the page; it
+ * must stay the same literal as gui-command's GUI_TOKEN_ENV, and a merge that renames one
+ * renames the other. */
+export const GUI_TOKEN_ENV = "TUMWATER_GUI_TOKEN";
+/** Split `run`'s args for `run --gui` and `run --tui`: whether the supervisor should also start
+ * the dashboard and/or host the observer TUI, and the args the supervised orchestrator
+ * generation gets with both stripped so the generation's own cmdStart never tries to supervise a
+ * second dashboard or re-attach a TUI in a terminal the parent owns (a self-redeploy spawns a
+ * fresh generation each time). Exported so the unit tests pin the stripping that removing the
+ * spawn wiring would otherwise silently drop. */
+export function guiChildPlan(runArgs) {
+    const portIdx = runArgs.indexOf("--port");
+    const portRaw = portIdx >= 0 ? runArgs[portIdx + 1] : undefined;
+    const port = portRaw !== undefined ? parsePortFlag(portRaw) : null;
+    const tokenIdx = runArgs.indexOf("--token");
+    const tokenRaw = tokenIdx >= 0 ? runArgs[tokenIdx + 1] : undefined;
+    // Drop --port/--token and their value tokens from the supervized orchestrator generation
+    // along with --gui/--tui (and --all-interfaces by name): the child's own cmdStart would
+    // otherwise hit the dashboard-only-flag refusals (its args no longer carry --gui) or supervise
+    // a second dashboard, and a self-redeploy hand-off must never forward a dashboard flag it is
+    // not serving itself. --all-interfaces and --token have no value token to skip, so the name
+    // filter below drops them; the valued pair is skipped by index like --port's.
+    const skip = new Set();
+    if (portIdx >= 0) {
+        skip.add(portIdx);
+        if (portIdx + 1 < runArgs.length)
+            skip.add(portIdx + 1);
+    }
+    if (tokenIdx >= 0) {
+        skip.add(tokenIdx);
+        if (tokenIdx + 1 < runArgs.length)
+            skip.add(tokenIdx + 1);
+    }
+    const guiArgs = [];
+    if (port !== null)
+        guiArgs.push("--port", String(port));
+    if (runArgs.includes("--all-interfaces"))
+        guiArgs.push("--all-interfaces");
+    // The token is returned separately (guiToken) and reaches the child through its env, never
+    // guiArgs/argv: a secret on the command line is world-readable (/proc/<pid>/cmdline) and is
+    // re-run verbatim by a self-reload onto each new generation. The skip set still drops the
+    // operator's --token pair from the orchestrator generation (its cmdStart would refuse a
+    // dashboard flag without --gui, and a self-redeploy hand-off must never forward it).
+    return {
+        spawnGui: runArgs.includes("--gui"),
+        spawnTui: runArgs.includes("--tui"),
+        guiArgs,
+        guiToken: tokenRaw,
+        orchestratorArgs: runArgs.filter((arg, i) => arg !== "--gui" && arg !== "--tui" && arg !== "--all-interfaces" && !skip.has(i)),
+        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
+ * redeploy and exits on its own if this supervisor dies outright (SIGKILL, a crash) — a killed
+ * supervisor never leaves a dashboard holding its port. Any other dashboard exit (a failed bind
+ * prints its own message and exits) ends this loop and leaves the team running. */
+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 = dashboardChildEnv(DASHBOARD_CHILD_ENV, guiToken, process.pid);
+    for (;;) {
+        const exit = await spawnGuiChild(signal, env, stdio, guiArgs);
+        if (signal.aborted || exit.code !== RESTART_EXIT_CODE)
+            return;
+    }
+}
+/** The supervisor half of `tumwater start` (src/process/supervisor.ts): spawn the orchestrator as a
+ * child generation and respawn it whenever it exits RESTART_EXIT_CODE after redeploying itself.
+ * Ctrl+C reaches the child directly from the terminal, so only SIGTERM is forwarded; the
+ * supervisor's own exit code is whatever the last generation's was. A team that goes down without
+ * the operator asking leaves a `supervisor_exit` event behind (BUGS.md 2026-09-23): the dead
+ * generation's stderr reached only this terminal, which nobody may be watching. */
+export async function superviseStartCommand(root, runArgs, branchArg, forMs) {
+    // The supervisor machinery loads lazily, like cmdStart's orchestrator import above: a command
+    // that never boots the team never compiles it.
+    const { RUN_WINDOW_START_ENV, teamDownEvent, spawnStartChild, superviseStart } = await import("../process/supervisor.js");
+    const plan = guiChildPlan(runArgs);
+    // A TUI owns the terminal, so it can only be hosted when this supervisor's own stdin and
+    // stdout are a TTY — the same guard runTui enforces. Check before booting a team a TUI
+    // could never drive, surfacing the actionable tuiTerminalError instead of letting runTui's
+    // rejection sit unhandled until superviseStart settles and then crash the supervisor after
+    // the team has (pointlessly) started.
+    if (plan.spawnTui && (!process.stdin.isTTY || !process.stdout.isTTY)) {
+        const { tuiTerminalError } = await import("../ui/tui/tui-input.js");
+        fail(tuiTerminalError(Boolean(process.stdin.isTTY), Boolean(process.stdout.isTTY)));
+    }
+    const windowEnv = forMs !== null ? { [RUN_WINDOW_START_ENV]: String(Date.now()) } : {};
+    const controller = new AbortController();
+    // The dashboard lives beside the orchestrator generations rather than inside one: it must
+    // outlive every generation a redeploy swaps out. Its own abort stops the current dashboard
+    // child, which spawnGuiChild's abort wiring SIGTERMs.
+    const guiController = new AbortController();
+    let stopping = false;
+    process.on("SIGINT", () => {
+        stopping = true; // The child got the same SIGINT from the terminal and stops on its own.
+    });
+    process.on("SIGTERM", () => {
+        stopping = true;
+        controller.abort(); // Not delivered to the child by the kernel — forward it.
+        guiController.abort();
+    });
+    // The TUI is hosted in the supervisor process, beside the orchestrator generations it must
+    // outlive. Quitting it (q or Ctrl+C handled by ink's key handler) is the run's Ctrl+C:
+    // runTui resolves and the .then sets `stopping` and aborts the controller, so superviseStart
+    // drains in-flight runs and the team shuts down exactly as Ctrl+C on a plain `run` does;
+    // the team-down teardown (dashboard abort, onDone, terminal restore) is unchanged.
+    // reloadDisabled keeps the hosted TUI off its self-reload watch: the team's own first
+    // self-redeploy dist swap must not resolve runTui (which would read as a quit and abort
+    // this run's controller) or spawn a re-exec replacement; the host supervisor survives a
+    // redeploy by respawning its team children, and the hosted TUI — like the supervisor
+    // itself — stays on the build it started, getting fresh code on the next run. The abort
+    // signal is how this process ends the TUI when the run ends on its own (a `--for` window
+    // closes, or the team stops): runTui resolves on abort and takes its quit teardown, so the
+    // `await tui` below cannot hang on a TUI nothing else would ever close.
+    const tuiController = new AbortController();
+    const tui = plan.spawnTui
+        ? (await import("../ui/tui/tui.js")).runTui(root, { abortSignal: tuiController.signal, reloadDisabled: true }).then(() => {
+            stopping = true; // the TUI quit = the run's Ctrl+C
+            controller.abort();
+            guiController.abort();
+        })
+        : Promise.resolve();
+    const gui = plan.spawnGui ? superviseDashboard(guiController.signal, plan.guiToken, plan.childStdio, plan.guiArgs) : Promise.resolve();
+    const code = await superviseStart({
+        spawnChild: (signal) => spawnStartChild(signal, plan.orchestratorArgs, windowEnv, plan.childStdio),
+        stopping: () => stopping,
+        onRespawn: (generation) => {
+            // With a hosted TUI the supervisor owns no free stdout: its own say() would paint the
+            // restart line over the ink full-screen render and corrupt it — the same interleaving
+            // childStdio silences for the children. The TUI renders status from on-disk state, so
+            // the redeploy is visible there as the team coming back.
+            if (!plan.spawnTui && !runArgs.includes("--json"))
+                say(`\nrestarting onto the update (restart ${generation})\n`);
+        },
+        onCrashLoop: () => process.stderr.write("tumwater restarted itself too many times in a minute — giving up\n"),
+        // Re-ask the startup gate for the reason: a generation that dies right after a respawn
+        // most likely met an environment that no longer boots (the 2026-09-22 child found
+        // tumwater.json gone). A crash loop's generations all asked for restarts, so the gate
+        // has nothing to say about it.
+        onTeamDown: async (down) => {
+            const event = logEvent(root, teamDownEvent(down, down.crashLoop ? null : await runStartupProblem(root, branchArg)));
+            notifyTeamDown(root, event);
+        },
+        // The end-of-supervision build repair (see build-stage.repairInterruptedSwap): a swap
+        // killed between its two renames leaves dist/ missing, and this process is the only one
+        // still able to rename the preserved old build back before it exits — the next `tumwater
+        // run` would otherwise fail to load its own dist/src/cli.js. repairInterruptedSwap is a
+        // static import, so its code is in memory before any swap can move dist/ away: an import
+        // at call time would fail ERR_MODULE_NOT_FOUND exactly when it is needed. The repair
+        // reports its own outcome, so it can never change the exit code.
+        onDone: () => repairInterruptedSwap(root),
+    }, controller.signal);
+    // The orchestrator is gone; take the dashboard and the TUI with it so a stopped team never
+    // leaves a dashboard holding its port or a TUI holding the terminal. abort() SIGTERMs the
+    // current gui child; await lets the spawn loop observe the abort before this process exits.
+    // On a plain run the user's own Ctrl+C already resolved the TUI; on a windowed (--for) run
+    // the window just closed with the TUI still up, so it is aborted here and its teardown /
+    // terminal restore settle before this process exits.
+    tuiController.abort();
+    await tui; // let the TUI's promise settle / terminal restore
+    guiController.abort();
+    await gui;
+    process.exit(code);
+}

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

@@ -2,13 +2,11 @@ import { baseRoleOf, runnerIds } from "../roles/runner-ids.js";
 import { knownRoleIds } from "../config/config.js";
 import { unknownRoleMessage } from "../roles/roles.js";
 import { fail, say, sayJson } from "./cli-output.js";
-import { durationLabel, failRivalShapes, parseBranchFlag, parsePortFlag, parseRoleListFlag, tokenValueProblem, } from "./cli-args.js";
+import { durationLabel, failRivalShapes, parseBranchFlag, parseRoleListFlag, tokenValueProblem, } from "./cli-args.js";
 import { cancelScheduledStop, scheduledStopAt } from "../team/team-state.js";
 import { orchestratorAlive, readOrchestratorInfo } from "../team/team-orchestrator-info.js";
 import { runStartupCheck, runStartupProblem } from "../gates/startup-gates.js";
-import { repairInterruptedSwap } from "../build/build-stage.js";
 import { logEvent, subscribeEvents } from "../events/events.js";
-import { notifyTeamDown } from "../events/event-notify.js";
 import { formatEvent } from "../events/event-format.js";
 import { RESTART_EXIT_CODE } from "../redeploy/redeploy-policy.js";
 import { runStartupMigrations } from "../orchestrator/startup-migration-steps.js";
@@ -16,14 +14,8 @@ import { loadRunnerState } from "../runner/runner-state-load.js";
 import { shortSha } from "../text/format.js";
 import { readRunRowsSince, summarizeRunRows } from "../history/history-data.js";
 import { ONCE_FAILURE_RESULTS, inheritedWindowStart, onceFailures, onceReport, onceSummary, parseRunWindow, renderOnceSummary, windowReport, windowSummary, } from "./cli-start-summary.js";
-/** The env var that carries the dashboard gate token between a supervisor and its dashboard
- * child (and across a re-exec'd dashboard generation), for the `run --gui`/`start --gui`
- * supervisor's own use. Defined here rather than imported from gui-command.js so this module
- * (and every `start`/`run` invocation) never pulls the GUI server graph onto the page; it
- * must stay the same literal as gui-command's GUI_TOKEN_ENV, and a merge that renames one
- * renames the other. */
-const GUI_TOKEN_ENV = "TUMWATER_GUI_TOKEN";
 export { ONCE_FAILURE_RESULTS, inheritedWindowStart, onceFailures, onceReport, onceSummary, parseRunWindow, renderOnceSummary, windowReport, windowSummary, };
+import { GUI_TOKEN_ENV, superviseStartCommand } from "./cli-start-supervisor.js";
 /** 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. */
@@ -334,7 +326,8 @@ async function runSupervisedGeneration(input) {
 }
 /** `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
+ * (src/cli/cli-start-supervisor.ts's superviseStartCommand), 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.
@@ -412,179 +405,3 @@ export function armScheduledStopWatch(root, onStop, quiet = false) {
     timer.unref();
     return { clear: () => clearInterval(timer) };
 }
-/** Split `run`'s args for `run --gui` and `run --tui`: whether the supervisor should also start
- * the dashboard and/or host the observer TUI, and the args the supervised orchestrator
- * generation gets with both stripped so the generation's own cmdStart never tries to supervise a
- * second dashboard or re-attach a TUI in a terminal the parent owns (a self-redeploy spawns a
- * fresh generation each time). Exported so the unit tests pin the stripping that removing the
- * spawn wiring would otherwise silently drop. */
-export function guiChildPlan(runArgs) {
-    const portIdx = runArgs.indexOf("--port");
-    const portRaw = portIdx >= 0 ? runArgs[portIdx + 1] : undefined;
-    const port = portRaw !== undefined ? parsePortFlag(portRaw) : null;
-    const tokenIdx = runArgs.indexOf("--token");
-    const tokenRaw = tokenIdx >= 0 ? runArgs[tokenIdx + 1] : undefined;
-    // Drop --port/--token and their value tokens from the supervized orchestrator generation
-    // along with --gui/--tui (and --all-interfaces by name): the child's own cmdStart would
-    // otherwise hit the dashboard-only-flag refusals (its args no longer carry --gui) or supervise
-    // a second dashboard, and a self-redeploy hand-off must never forward a dashboard flag it is
-    // not serving itself. --all-interfaces and --token have no value token to skip, so the name
-    // filter below drops them; the valued pair is skipped by index like --port's.
-    const skip = new Set();
-    if (portIdx >= 0) {
-        skip.add(portIdx);
-        if (portIdx + 1 < runArgs.length)
-            skip.add(portIdx + 1);
-    }
-    if (tokenIdx >= 0) {
-        skip.add(tokenIdx);
-        if (tokenIdx + 1 < runArgs.length)
-            skip.add(tokenIdx + 1);
-    }
-    const guiArgs = [];
-    if (port !== null)
-        guiArgs.push("--port", String(port));
-    if (runArgs.includes("--all-interfaces"))
-        guiArgs.push("--all-interfaces");
-    // The token is returned separately (guiToken) and reaches the child through its env, never
-    // guiArgs/argv: a secret on the command line is world-readable (/proc/<pid>/cmdline) and is
-    // re-run verbatim by a self-reload onto each new generation. The skip set still drops the
-    // operator's --token pair from the orchestrator generation (its cmdStart would refuse a
-    // dashboard flag without --gui, and a self-redeploy hand-off must never forward it).
-    return {
-        spawnGui: runArgs.includes("--gui"),
-        spawnTui: runArgs.includes("--tui"),
-        guiArgs,
-        guiToken: tokenRaw,
-        orchestratorArgs: runArgs.filter((arg, i) => arg !== "--gui" && arg !== "--tui" && arg !== "--all-interfaces" && !skip.has(i)),
-        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
- * redeploy and exits on its own if this supervisor dies outright (SIGKILL, a crash) — a killed
- * supervisor never leaves a dashboard holding its port. Any other dashboard exit (a failed bind
- * prints its own message and exits) ends this loop and leaves the team running. */
-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 = dashboardChildEnv(DASHBOARD_CHILD_ENV, guiToken, process.pid);
-    for (;;) {
-        const exit = await spawnGuiChild(signal, env, stdio, guiArgs);
-        if (signal.aborted || exit.code !== RESTART_EXIT_CODE)
-            return;
-    }
-}
-/** The supervisor half of `tumwater start` (src/process/supervisor.ts): spawn the orchestrator as a
- * child generation and respawn it whenever it exits RESTART_EXIT_CODE after redeploying itself.
- * Ctrl+C reaches the child directly from the terminal, so only SIGTERM is forwarded; the
- * supervisor's own exit code is whatever the last generation's was. A team that goes down without
- * the operator asking leaves a `supervisor_exit` event behind (BUGS.md 2026-09-23): the dead
- * generation's stderr reached only this terminal, which nobody may be watching. */
-async function superviseStartCommand(root, runArgs, branchArg, forMs) {
-    // The supervisor machinery loads lazily, like cmdStart's orchestrator import above: a command
-    // that never boots the team never compiles it.
-    const { RUN_WINDOW_START_ENV, teamDownEvent, spawnStartChild, superviseStart } = await import("../process/supervisor.js");
-    const plan = guiChildPlan(runArgs);
-    // A TUI owns the terminal, so it can only be hosted when this supervisor's own stdin and
-    // stdout are a TTY — the same guard runTui enforces. Check before booting a team a TUI
-    // could never drive, surfacing the actionable tuiTerminalError instead of letting runTui's
-    // rejection sit unhandled until superviseStart settles and then crash the supervisor after
-    // the team has (pointlessly) started.
-    if (plan.spawnTui && (!process.stdin.isTTY || !process.stdout.isTTY)) {
-        const { tuiTerminalError } = await import("../ui/tui/tui-input.js");
-        fail(tuiTerminalError(Boolean(process.stdin.isTTY), Boolean(process.stdout.isTTY)));
-    }
-    const windowEnv = forMs !== null ? { [RUN_WINDOW_START_ENV]: String(Date.now()) } : {};
-    const controller = new AbortController();
-    // The dashboard lives beside the orchestrator generations rather than inside one: it must
-    // outlive every generation a redeploy swaps out. Its own abort stops the current dashboard
-    // child, which spawnGuiChild's abort wiring SIGTERMs.
-    const guiController = new AbortController();
-    let stopping = false;
-    process.on("SIGINT", () => {
-        stopping = true; // The child got the same SIGINT from the terminal and stops on its own.
-    });
-    process.on("SIGTERM", () => {
-        stopping = true;
-        controller.abort(); // Not delivered to the child by the kernel — forward it.
-        guiController.abort();
-    });
-    // The TUI is hosted in the supervisor process, beside the orchestrator generations it must
-    // outlive. Quitting it (q or Ctrl+C handled by ink's key handler) is the run's Ctrl+C:
-    // runTui resolves and the .then sets `stopping` and aborts the controller, so superviseStart
-    // drains in-flight runs and the team shuts down exactly as Ctrl+C on a plain `run` does;
-    // the team-down teardown (dashboard abort, onDone, terminal restore) is unchanged.
-    // reloadDisabled keeps the hosted TUI off its self-reload watch: the team's own first
-    // self-redeploy dist swap must not resolve runTui (which would read as a quit and abort
-    // this run's controller) or spawn a re-exec replacement; the host supervisor survives a
-    // redeploy by respawning its team children, and the hosted TUI — like the supervisor
-    // itself — stays on the build it started, getting fresh code on the next run. The abort
-    // signal is how this process ends the TUI when the run ends on its own (a `--for` window
-    // closes, or the team stops): runTui resolves on abort and takes its quit teardown, so the
-    // `await tui` below cannot hang on a TUI nothing else would ever close.
-    const tuiController = new AbortController();
-    const tui = plan.spawnTui
-        ? (await import("../ui/tui/tui.js")).runTui(root, { abortSignal: tuiController.signal, reloadDisabled: true }).then(() => {
-            stopping = true; // the TUI quit = the run's Ctrl+C
-            controller.abort();
-            guiController.abort();
-        })
-        : Promise.resolve();
-    const gui = plan.spawnGui ? superviseDashboard(guiController.signal, plan.guiToken, plan.childStdio, plan.guiArgs) : Promise.resolve();
-    const code = await superviseStart({
-        spawnChild: (signal) => spawnStartChild(signal, plan.orchestratorArgs, windowEnv, plan.childStdio),
-        stopping: () => stopping,
-        onRespawn: (generation) => {
-            // With a hosted TUI the supervisor owns no free stdout: its own say() would paint the
-            // restart line over the ink full-screen render and corrupt it — the same interleaving
-            // childStdio silences for the children. The TUI renders status from on-disk state, so
-            // the redeploy is visible there as the team coming back.
-            if (!plan.spawnTui && !runArgs.includes("--json"))
-                say(`\nrestarting onto the update (restart ${generation})\n`);
-        },
-        onCrashLoop: () => process.stderr.write("tumwater restarted itself too many times in a minute — giving up\n"),
-        // Re-ask the startup gate for the reason: a generation that dies right after a respawn
-        // most likely met an environment that no longer boots (the 2026-09-22 child found
-        // tumwater.json gone). A crash loop's generations all asked for restarts, so the gate
-        // has nothing to say about it.
-        onTeamDown: async (down) => {
-            const event = logEvent(root, teamDownEvent(down, down.crashLoop ? null : await runStartupProblem(root, branchArg)));
-            notifyTeamDown(root, event);
-        },
-        // The end-of-supervision build repair (see build-stage.repairInterruptedSwap): a swap
-        // killed between its two renames leaves dist/ missing, and this process is the only one
-        // still able to rename the preserved old build back before it exits — the next `tumwater
-        // run` would otherwise fail to load its own dist/src/cli.js. repairInterruptedSwap is a
-        // static import, so its code is in memory before any swap can move dist/ away: an import
-        // at call time would fail ERR_MODULE_NOT_FOUND exactly when it is needed. The repair
-        // reports its own outcome, so it can never change the exit code.
-        onDone: () => repairInterruptedSwap(root),
-    }, controller.signal);
-    // The orchestrator is gone; take the dashboard and the TUI with it so a stopped team never
-    // leaves a dashboard holding its port or a TUI holding the terminal. abort() SIGTERMs the
-    // current gui child; await lets the spawn loop observe the abort before this process exits.
-    // On a plain run the user's own Ctrl+C already resolved the TUI; on a windowed (--for) run
-    // the window just closed with the TUI still up, so it is aborted here and its teardown /
-    // terminal restore settle before this process exits.
-    tuiController.abort();
-    await tui; // let the TUI's promise settle / terminal restore
-    guiController.abort();
-    await gui;
-    process.exit(code);
-}

package/dist/src/cli/completion.js

@@ -4,7 +4,7 @@
 import { customRoleNames, knownRoleIds, loadConfig } from "../config/config.js";
 import { BACKEND_IDS, BACKEND_KEYS, CLAUDE_AGENT_KEYS, CODEX_BACKEND_KEYS, MODEL_TIERS, ROLE_ENTRY_KEYS, THINKING_LEVELS, TOP_LEVEL_KEYS } from "../config/config-schema.js";
 import { DOTTED_MAP_KEYS, DOTTED_SECTION_FIELDS } from "../config/config-keys.js";
-import { compareCodeUnits } from "../collections.js";
+import { compareCodeUnits, distinctOrdered } from "../collections.js";
 import { HISTORY_MAX_RUNS, HISTORY_RESULT_FLAG_NAMES, HISTORY_SUMMARY_GROUPS, readRunRows } from "../history/history-data.js";
 import { templateIds } from "../init/init-templates.js";
 import { DOCTOR_CHECK_NAMES } from "../doctor/doctor-check-names.js";
@@ -77,7 +77,7 @@ function usageWords(firstLine, command) {
 }
 export function completionSpec(help = HELP) {
     const stanzas = helpStanzas(help);
-    const commands = [...new Set(stanzas.map((s) => s.command))];
+    const commands = distinctOrdered(stanzas.map((s) => s.command));
     const subcommands = {};
     const flags = {};
     for (const command of commands) {
@@ -140,7 +140,7 @@ export function completionConfigKeys(root) {
         ...Object.entries(DOTTED_SECTION_FIELDS).flatMap(([section, fields]) => fields.map((field) => `${section}.${field}`)),
         ...roleIds.flatMap((id) => ROLE_ENTRY_KEYS.map((field) => `roles.${id}.${field}`)),
     ];
-    return [...new Set(keys)];
+    return distinctOrdered(keys);
 }
 /** The value vocabulary `config set <key> <value>` completes for one key, or [] when the
  * field is free-form. The discrete-valued keys source the SAME closed constants the config

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

@@ -52,7 +52,18 @@ export async function followView(frameText, seams) {
         const timer = setInterval(() => {
             if (painting)
                 return;
-            const result = frameText();
+            let result;
+            try {
+                result = frameText();
+            }
+            catch {
+                // A sync frame (status, backlog, report) may throw the same transient failure as an
+                // async one — a snapshot lift, a momentarily unreadable file — and a throw out of a
+                // setInterval callback is an uncaught exception that kills the whole interactive
+                // follow, while the identical failure a tick later (async path) is skipped. Skip this
+                // repaint and retry on the next tick, the same policy the async path applies.
+                return;
+            }
             if (result instanceof Promise) {
                 painting = true;
                 void result
@@ -63,7 +74,14 @@ export async function followView(frameText, seams) {
                 });
                 return;
             }
-            paint(result);
+            // A sync frame's paint is guarded like its read above: a paint that throws (a broken
+            // stdout mid-follow) is skipped and retried, never fatal.
+            try {
+                paint(result);
+            }
+            catch {
+                // Transient — retry on the next tick, like the async path.
+            }
         }, interval);
         startParentDeathWatch(() => {
             clearInterval(timer);

package/dist/src/cli/help.js

@@ -4,6 +4,7 @@
  * <command>` from it by splitting the usage block on its `  tumwater <command>` lines, so a
  * topic can never drift out of sync with the full listing. */
 import { suggestClosest } from "../text/suggest.js";
+import { distinctOrdered } from "../collections.js";
 /** The role-grouped summary's JSON keys, quoted verbatim in `history --summary --json` help
  * (its `--by model` twin is the hardcoded `{ models, total }` beside it). */
 const SUMMARY_JSON_KEYS = "{ roles, total }";
@@ -526,12 +527,6 @@ Usage:
                                    written to roles.<id>.instances for the base id
   tumwater role <id> --clear-instances
                                    Clear that role's instance count (back to 1)
-  tumwater role <id> --review-after-merge
-                                   Review that role's commits after they merge, written
-                                   to review.afterMerge (the base id for an instance)
-  tumwater role <id> --clear-review-after-merge
-                                   Review it before merge again, removing it from
-                                   review.afterMerge
   tumwater prompt <text...>        Send a message to the director's inbox
   tumwater prompt --file <path>    Send a message read from a file ("-" reads stdin)
   tumwater prompt --role <id> <text...>
@@ -646,7 +641,7 @@ sleep while there is nothing to do and wake when main moves. Everything is local
  * stanza; the distance mechanics are text/suggest.ts's suggestClosest, shared with the config-key
  * suggestion. */
 export function suggestCommand(input, help = HELP) {
-    return suggestClosest(input, [...new Set(helpStanzas(help).map((s) => s.command))]);
+    return suggestClosest(input, distinctOrdered(helpStanzas(help).map((s) => s.command)));
 }
 /** Split HELP's usage block into per-command stanzas. A stanza starts at a two-space-indented
  * `tumwater <command>` line; any further indented line continues it, and a column-0 line (the