tumwater 0.4.2 → 0.4.4

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/orchestrator-info.js";
-import { runStartupCheck, runStartupProblem } from "../gates/startup-gate.js";
-import { repairInterruptedSwap } from "../build/build-stage.js";
+import { orchestratorAlive, readOrchestratorInfo } from "../team/team-orchestrator-info.js";
+import { runStartupCheck, runStartupProblem } from "../gates/startup-gates.js";
 import { logEvent, subscribeEvents } from "../events/events.js";
-import { notifyTeamDown } from "../events/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. */
@@ -151,13 +143,11 @@ async function parseStartInvocation(root, args) {
     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");
+/** Create the abort handle and the graceful-stop closure a supervised generation passes to
+ * every watchdog, and register the SIGINT/SIGTERM handlers that trigger it. Returns an
+ * `isStopping` query so the later once-exit check reads the live flag instead of a captured
+ * boolean. */
+function installStopHandlers(json) {
     const controller = new AbortController();
     let stopping = false;
     const stop = () => {
@@ -173,6 +163,12 @@ async function runSupervisedGeneration(input) {
     };
     process.on("SIGINT", stop);
     process.on("SIGTERM", stop);
+    return { controller, stop, isStopping: () => stopping };
+}
+/** Arm the windowed run's deadline timer and the scheduled-stop watch, both of which run the
+ * same graceful `stop` a Ctrl+C runs. Returns the window start and the two clearable handles. */
+async function armRunWatchdogs(root, json, forMs, stop, isStopping) {
+    const { RUN_WINDOW_START_ENV } = await import("../process/supervisor.js");
     // A windowed run's deadline arms the same graceful stop a Ctrl+C runs — the identical `stop`
     // closure, so the drain path is one code path either way. clearTimeout in the finally below
     // retracts it when the run ends first (an early Ctrl+C), so no stray timer outlives the run.
@@ -185,22 +181,13 @@ async function runSupervisedGeneration(input) {
         stop();
     }) : null;
     const scheduledStopWatch = armScheduledStopWatch(root, () => {
-        if (!stopping)
+        if (!isStopping())
             stop(); // A drain already under way must not be turned into a force-kill.
     }, json);
-    // A supervisor that dies without forwarding — SIGKILL (the OOM killer, `kill -9`) cannot be
-    // trapped or forwarded, and an uncaught supervisor crash forwards nothing either — leaves this
-    // generation reparented and running the team unattended. The parent-death watch polls for the
-    // reparent and runs the same graceful stop a forwarded SIGTERM would have run, so a killed
-    // supervisor takes its team down with it (BUGS.md 2026-09-30). The spawner hands its pid
-    // down (SUPERVISOR_PID_ENV), so a supervisor killed during this child's startup — before the
-    // watch's first ppid read — still counts as gone. Everything below runs only in
-    // the supervised generation: an unsupervised `run` became the supervisor above and returned.
-    const expectedPpid = expectedSupervisorPid();
-    startParentDeathWatch(stop, expectedPpid !== undefined ? { expectedPpid } : {});
-    const enabled = runnerIds(config);
-    // A scoped round's role list is exactly the filter; otherwise every enabled role runs.
-    const roles = roleFilter ?? enabled;
+    return { windowStart, deadlineTimer, scheduledStopWatch };
+}
+/** Persist the baseline verdicts and boot the once-gated redeployer and launch-services watch. */
+async function bootGenerationParts(root, branchArg, once) {
     // 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.
@@ -210,10 +197,13 @@ async function runSupervisedGeneration(input) {
     const redeploy = once
         ? null
         : await (await import("../redeploy/redeploy.js")).createRedeployer(root, (e) => logEvent(root, e), () => runStartupProblem(root, branchArg));
-    const build = redeploy ? ` · build ${shortSha(redeploy.build.sha)}` : "";
     // A long-running team watches launchservicesd's port count (a no-op off macOS); a once round
     // is over long before a leak could matter.
     const launchServicesWatch = once ? null : new (await import("../process/launch-services.js")).LaunchServicesWatch(root);
+    return { redeploy, launchServicesWatch };
+}
+/** Print the supervised generation's banner and subscribe to its event stream on non-json runs. */
+function announceGeneration(roles, mainBranch, once, json, forMs, root, build) {
     // Name the resolved root when it differs from the cwd: an operator who started the team
     // from a subdirectory must see where .tumwater/ actually lives.
     const rootNote = root !== process.cwd() ? ` · root ${root}` : "";
@@ -229,38 +219,17 @@ async function runSupervisedGeneration(input) {
         say(`roles: ${roles.join(", ")}`);
         say("watch: `tumwater tui` or `tumwater logs -f` in another terminal; events stream below\n");
     }
-    const unsubscribe = json ? () => { } : subscribeEvents((e) => say(formatEvent(e)));
-    // Snapshot each role's run counter so the once summary can tell this round's runs from
-    // the persisted history (the state file accumulates across rounds).
-    await runStartupMigrations(root); // so the snapshot reads a migrated state/<new>.json
-    const runsBefore = new Map(roles.map((role) => [role, loadRunnerState(root, role).runs]));
-    let exit;
-    try {
-        exit = await (await import("../orchestrator/orchestrator.js")).runOrchestrator({
-            root,
-            config,
-            mainBranch,
-            signal: controller.signal,
-            redeploy,
-            launchServicesWatch,
-            once,
-            roleFilter: roleFilter ?? undefined,
-            stopsAt: forMs !== null ? windowStart + forMs : undefined,
-        });
-    }
-    finally {
-        if (deadlineTimer)
-            deadlineTimer.clear();
-        scheduledStopWatch.clear();
-        unsubscribe();
-    }
+    return json ? () => { } : subscribeEvents((e) => say(formatEvent(e)));
+}
+/** Print the round summary: the once report/summary, or a windowed run's window report. */
+function printRoundSummary(root, roles, runsBefore, once, json, forMs, windowStart, settled, runsDone, restart) {
     if (once) {
         if (json)
-            sayJson(onceReport(root, roles, runsBefore, exit.settled, exit.runsDone));
+            sayJson(onceReport(root, roles, runsBefore, settled, runsDone));
         else
-            say(onceSummary(root, roles, runsBefore, exit.settled, exit.runsDone));
+            say(onceSummary(root, roles, runsBefore, settled, runsDone));
     }
-    else if (forMs !== null && !exit.restart) {
+    else if (forMs !== null && !restart) {
         const { rows, covered } = readRunRowsSince(root, Date.now() - windowStart, null);
         const summary = summarizeRunRows(rows);
         if (json)
@@ -268,8 +237,12 @@ async function runSupervisedGeneration(input) {
         else
             say(windowSummary(durationLabel(forMs), summary, covered));
     }
+}
+/** Set the process exit code for a once round that failed or was cut short before completion. */
+async function applyOnceExitCode(root, roles, runsBefore, runsDone, once, json, isStopping) {
+    const { ONCE_FAILED_EXIT_CODE } = await import("../process/supervisor.js");
     if (once) {
-        const failures = onceFailures(root, roles, runsBefore, exit.runsDone);
+        const failures = onceFailures(root, roles, runsBefore, runsDone);
         if (failures.length > 0) {
             // In --json mode the failure facts already ride in the report's `failures`; the exit
             // code is the contract a CI caller needs, so only the prose line is suppressed.
@@ -281,27 +254,80 @@ async function runSupervisedGeneration(input) {
         // not read as success (0) to the CI caller parsing the JSON: the document still carries
         // the round's partial facts, but the truncated round exits non-zero. Non-json once keeps
         // its historical behavior (prose + 0 unless a role failed).
-        if (json && stopping)
+        if (json && isStopping())
             process.exitCode = ONCE_FAILED_EXIT_CODE;
     }
+}
+/** 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 { startParentDeathWatch, expectedSupervisorPid } = await import("../process/supervisor.js");
+    const { controller, stop, isStopping } = installStopHandlers(json);
+    const { windowStart, deadlineTimer, scheduledStopWatch } = await armRunWatchdogs(root, json, forMs, stop, isStopping);
+    // A supervisor that dies without forwarding — SIGKILL (the OOM killer, `kill -9`) cannot be
+    // trapped or forwarded, and an uncaught supervisor crash forwards nothing either — leaves this
+    // generation reparented and running the team unattended. The parent-death watch polls for the
+    // reparent and runs the same graceful stop a forwarded SIGTERM would have run, so a killed
+    // supervisor takes its team down with it (BUGS.md 2026-09-30). The spawner hands its pid
+    // down (SUPERVISOR_PID_ENV), so a supervisor killed during this child's startup — before the
+    // watch's first ppid read — still counts as gone. Everything below runs only in
+    // the supervised generation: an unsupervised `run` became the supervisor above and returned.
+    const expectedPpid = expectedSupervisorPid();
+    startParentDeathWatch(stop, expectedPpid !== undefined ? { expectedPpid } : {});
+    const enabled = runnerIds(config);
+    // A scoped round's role list is exactly the filter; otherwise every enabled role runs.
+    const roles = roleFilter ?? enabled;
+    const { redeploy, launchServicesWatch } = await bootGenerationParts(root, branchArg, once);
+    const build = redeploy ? ` · build ${shortSha(redeploy.build.sha)}` : "";
+    const unsubscribe = announceGeneration(roles, mainBranch, once, json, forMs, root, build);
+    // Snapshot each role's run counter so the once summary can tell this round's runs from
+    // the persisted history (the state file accumulates across rounds).
+    await runStartupMigrations(root); // so the snapshot reads a migrated state/<new>.json
+    const runsBefore = new Map(roles.map((role) => [role, loadRunnerState(root, role).runs]));
+    let exit;
+    try {
+        exit = await (await import("../orchestrator/orchestrator.js")).runOrchestrator({
+            root,
+            config,
+            mainBranch,
+            signal: controller.signal,
+            redeploy,
+            launchServicesWatch,
+            once,
+            roleFilter: roleFilter ?? undefined,
+            stopsAt: forMs !== null ? windowStart + forMs : undefined,
+        });
+    }
+    finally {
+        if (deadlineTimer)
+            deadlineTimer.clear();
+        scheduledStopWatch.clear();
+        unsubscribe();
+    }
+    printRoundSummary(root, roles, runsBefore, once, json, forMs, windowStart, exit.settled, exit.runsDone, exit.restart);
+    await applyOnceExitCode(root, roles, runsBefore, exit.runsDone, once, json, isStopping);
     // A self-redeploy swapped the new build into dist/: hand the terminal back to the supervisor,
     // 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,
+    // generation runs a whole team, and any ref'd handle a shutdown missed (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.
+    // output and nothing after depends on this loop, so an explicit exit is equivalent to the
+    // natural exit 0 this replaces, 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
+ * (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.
@@ -379,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";
@@ -13,44 +13,71 @@ import { EVENT_TYPE_LABELS } from "../events/event-labels.js";
 import { POST_REVIEW_STATES } from "../review/post-merge-review-render.js";
 import { HELP, helpStanzas } from "./help.js";
 export const SUPPORTED_SHELLS = ["bash", "zsh", "fish"];
-/** The completable words of a stanza's usage part: the text after `tumwater <command>` up to the
- * description column (two or more spaces). Bare lowercase words count inside `[...]` and as the
- * leading run directly after the command; outside brackets the first other token ends the run, so
- * a single-space description (`role <id> --clear-notes Clear that notes`) adds nothing. */
-function usageWords(firstLine, command) {
+/** The usage text of a stanza first line: the part after `tumwater <command>` up to the
+ * description column (two or more spaces). */
+function usagePortion(firstLine, command) {
     const rest = firstLine.replace(new RegExp(`^ {2}tumwater ${command}`), "");
     // Usage arguments follow the command after a single space; two or more spaces start the
     // description.
-    const usage = /^ {2,}/.test(rest) ? "" : (rest.split(/ {2,}/)[0] ?? "");
+    return /^ {2,}/.test(rest) ? "" : (rest.split(/ {2,}/)[0] ?? "");
+}
+/** An angle-bracket alternation of plain words — `<bash|zsh|fish>`, the completion command's
+ * shell positional — expands to each alternative as a subcommand word, so `tumwater completion
+ * <TAB>` lists exactly the shells the command accepts. A bare placeholder like `<id>` or `<k>`
+ * carries no `|` and so stays a placeholder, skipped as before (its `<`/`>` never leave the
+ * token, so it never looked like a word). The expansion only fires while the leading run is
+ * open; the returned words contribute as the leading words of the usage part. */
+function alternationWords(token, leading) {
+    const alternation = /^<([a-z][a-z-]*(?:\|[a-z][a-z-]*)+)>$/.exec(token);
+    return alternation && leading ? alternation[1].split("|") : null;
+}
+/** Whether a token counts as a completable bare word: it is a plain lowercase word and either
+ * sits inside brackets, opens a bracket itself, or is still within the leading run. */
+function isCompletableWord(bare, token, depth, leading) {
+    return /^[a-z][a-z-]*$/.test(bare) && (depth > 0 || token.startsWith("[") || leading);
+}
+/** Whether a token ends the leading run: outside brackets, not opening a bracket, and not
+ * blank once its brackets and bars are stripped (so an angle-bracket placeholder closes it). */
+function endsLeadingRun(bare, token, depth) {
+    return depth === 0 && !token.startsWith("[") && bare !== "";
+}
+/** The bracket-depth delta of a token: `[` +1 and `]` -1 per character, everything else 0. */
+function bracketDelta(token) {
+    let delta = 0;
+    for (const ch of token)
+        delta += ch === "[" ? 1 : ch === "]" ? -1 : 0;
+    return delta;
+}
+/** The completable words of a usage text: the angle-bracket alternation expands, bare lowercase
+ * words count inside `[...]` and as the leading run directly after the command, and outside
+ * brackets the first other token ends the run. */
+function usageWordsIn(usage) {
     const words = [];
     let depth = 0;
     let leading = true;
     for (const token of usage.split(/\s+/).filter(Boolean)) {
-        // An angle-bracket alternation of plain words — `<bash|zsh|fish>`, the completion
-        // command's shell positional — expands to each alternative as a subcommand word, so
-        // `tumwater completion <TAB>` lists exactly the shells the command accepts. A bare
-        // placeholder like `<id>` or `<k>` carries no `|` and so stays a placeholder, skipped
-        // as before (its `<`/`>` never leave the token, so it never looked like a word).
-        const alternation = /^<([a-z][a-z-]*(?:\|[a-z][a-z-]*)+)>$/.exec(token);
-        if (alternation && leading) {
-            for (const alt of alternation[1].split("|"))
-                words.push(alt);
+        const alternates = alternationWords(token, leading);
+        if (alternates) {
+            words.push(...alternates);
             continue;
         }
         const bare = token.replace(/[[\]|]/g, "");
-        const isWord = /^[a-z][a-z-]*$/.test(bare);
-        if (isWord && (depth > 0 || token.startsWith("[") || leading))
+        if (isCompletableWord(bare, token, depth, leading))
             words.push(bare);
-        else if (depth === 0 && !token.startsWith("[") && bare !== "")
+        else if (endsLeadingRun(bare, token, depth))
             leading = false;
-        for (const ch of token)
-            depth += ch === "[" ? 1 : ch === "]" ? -1 : 0;
+        depth += bracketDelta(token);
     }
     return words;
 }
+/** The completable words of a stanza's usage part: the text after `tumwater <command>` up to the
+ * description column (two or more spaces). */
+function usageWords(firstLine, command) {
+    return usageWordsIn(usagePortion(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) {
@@ -113,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
@@ -152,6 +179,15 @@ export function configValueWords(key) {
 const ROLE_POSITIONAL_COMMANDS = ["role", "history", "revert"];
 /** Flags whose value is a file path: completion offers file names after them. */
 const PATH_FLAGS = ["--file", "--attach", "--notes-file", "--instructions-file", "--path"];
+/** The constant fish value suffix for the flags whose candidates are a fixed `__tumwater_*` list:
+ * `--role`, `--result`, `--type` and `--status` take comma lists, so they complete per item through
+ * `__fish_complete_list`, skipping the items already listed. */
+const FISH_LIST_FLAG_SUFFIXES = {
+    "--role": ` -x -a "(__fish_complete_list , __tumwater_roles)"`,
+    "--result": ` -x -a "(__fish_complete_list , __tumwater_results)"`,
+    "--type": ` -x -a "(__fish_complete_list , __tumwater_types)"`,
+    "--status": ` -x -a "(__fish_complete_list , __tumwater_review_states)"`,
+};
 /** The event-type codes `logs --type` filters by: the keys of the labels map, so a new event
  * type completes the moment it gains a label. Sorted for a stable, alphabetical offer of a
  * vocabulary too large to recall offhand — the same reason `--role`, `--template`, and
@@ -289,37 +325,37 @@ function bashScript(help) {
         ``,
     ].join("\n");
 }
-/** The value suffix a fish flag line carries: what completes after the flag. `--role`, `--result`
- * `--type` and `--status` take comma lists, so they complete per item through
- * `__fish_complete_list`,
- * skipping the items already listed. */
-function fishFlagValue(command, flag) {
-    if (flag === "--role")
-        return ` -x -a "(__fish_complete_list , __tumwater_roles)"`;
+/** The fish value suffix for the flags whose value depends on the command: `--transcript` has role
+ * ids only under `logs`, and `--model` completes the closed tier set under `role` but the log's
+ * selectors under `history`. Undefined for a flag this helper does not own. */
+function fishScopedFlagSuffix(command, flag) {
     if (flag === "--transcript" && command === "logs")
-        return ` -x -a "(__fish_complete_list , __tumwater_roles)"`;
-    if (PATH_FLAGS.includes(flag))
-        return ` -r -F`;
-    if (flag === "--template")
-        return ` -x -a "${templateIds().join(" ")}"`;
-    if (flag === "--result")
-        return ` -x -a "(__fish_complete_list , __tumwater_results)"`;
-    if (flag === "--type")
-        return ` -x -a "(__fish_complete_list , __tumwater_types)"`;
-    if (flag === "--status")
-        return ` -x -a "(__fish_complete_list , __tumwater_review_states)"`;
-    if (flag === "--thinking")
-        return ` -x -a "${THINKING_LEVEL_WORDS.join(" ")}"`;
-    if (flag === "--backend")
-        return ` -x -a "${BACKEND_IDS.join(" ")}"`;
-    if (flag === "--by")
-        return ` -x -a "${HISTORY_SUMMARY_GROUPS.join(" ")}"`;
-    // `role --model` completes the closed tier set; `history --model` completes the log's selectors.
+        return FISH_LIST_FLAG_SUFFIXES["--role"];
     if (flag === "--model" && command === "role")
         return ` -x -a "${MODEL_TIERS.join(" ")}"`;
     if (flag === "--model" && command === "history")
         return ` -x -a "(__fish_complete_list , __tumwater_models)"`;
-    return "";
+    return undefined;
+}
+/** The fish value suffix for the flags whose candidates are a joined literal list. Undefined for a
+ * flag this helper does not own. */
+function fishWordSuffix(flag) {
+    switch (flag) {
+        case "--template": return ` -x -a "${templateIds().join(" ")}"`;
+        case "--thinking": return ` -x -a "${THINKING_LEVEL_WORDS.join(" ")}"`;
+        case "--backend": return ` -x -a "${BACKEND_IDS.join(" ")}"`;
+        case "--by": return ` -x -a "${HISTORY_SUMMARY_GROUPS.join(" ")}"`;
+        default: return undefined;
+    }
+}
+/** The value suffix a fish flag line carries: what completes after the flag. `--role`, `--result`
+ * `--type` and `--status` take comma lists, so they complete per item through
+ * `__fish_complete_list`,
+ * skipping the items already listed. Tries the command-scoped flags, then the fixed
+ * `__tumwater_*` list table, then the joined literal-word flags, and finally the path flags, in
+ * the same order the ladder did. */
+function fishFlagValue(command, flag) {
+    return fishScopedFlagSuffix(command, flag) ?? FISH_LIST_FLAG_SUFFIXES[flag] ?? fishWordSuffix(flag) ?? (PATH_FLAGS.includes(flag) ? " -r -F" : "");
 }
 function fishScript(help) {
     const spec = completionSpec(help);