tumwater 0.1.2 → 0.2.0

package/dist/src/cli/cli-repo-gate.js

@@ -2,7 +2,7 @@
  * fast on the first unmet precondition (startup-gate.ts's repoNotReady — the repo half of
  * `tumwater run`'s startup gate). One named home beside the argument gate (cli-flag-specs.ts):
  * the dispatcher (cli.ts), the marker commands (cli-marker-commands.ts), the write commands
- * (backlog/backlog-write.ts), and the read-only command bodies (cli-query-commands.ts) all
+ * (backlog/backlog-cli.ts), and the read-only command bodies (cli-query-commands.ts) all
  * import it, so a command layer never reaches into a sibling command module for a gate. */
 import { fail } from "./cli-output.js";
 import { repoNotReady } from "../gates/startup-gate.js";

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

@@ -1,26 +1,26 @@
-/** The fleet-booting commands' implementations: `tumwater init` and `tumwater run` — the latter
- * with its supervisor half (src/process/supervisor.ts). cli.ts stays the pure dispatcher; every
- * other command it dispatches already delegates to a module (operator/operator-commands.ts,
- * prompt-commands.ts, config-commands.ts, log-commands.ts, doctor.ts, …), and these three were
- * the only implementations living in the dispatcher itself. */
-import { increment } from "../collections.js";
-import { loopIds } from "../roles/loop-ids.js";
+import { compareCodeUnits, increment } from "../collections.js";
+import { loopIds, loopPaused } from "../roles/loop-ids.js";
 import { fail, say } from "./cli-output.js";
 import { durationLabel, failOverDurationCap, failRivalShapes, flagValue, parseBranchFlag, parseDurationFlag, parseRoleFlag, } from "./cli-args.js";
 import { PAUSE_FOR_MAX_MS } from "../operator/operator-intent.js";
 import { parseInitArgs } from "./cli-command-args.js";
-import { isFleetPaused, pausedRoles } from "../fleet/fleet-state.js";
-import { orchestratorAlive, readOrchestratorInfo } from "../fleet/orchestrator-info.js";
+import { cancelScheduledStop, isTeamPaused, pausedRoles, scheduledStopAt } from "../team/team-state.js";
+import { orchestratorAlive, readOrchestratorInfo } from "../team/orchestrator-info.js";
 import { runStartupCheck, runStartupProblem } from "../gates/startup-gate.js";
 import { initProject } from "../init/init.js";
 import { templateCatalog } from "../init/init-templates.js";
 import { repairInterruptedSwap } from "../build/build-stage.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";
 import { loadLoopState, stateSkipReason } from "../loop/loop-state.js";
 import { plural } from "../text/phrases.js";
 import { shortSha } from "../text/format.js";
+import { readTickRowsSince, summarizeTickRows } from "../history/history-data.js";
+import { renderSummary } from "../history/history-render.js";
+import { SPARSE_WINDOW_NOTE } from "../events/event-window.js";
 /** `tumwater init`: seed a project directory from the operator's brief (src/init/init.ts does the
  * work; this prints the report). --dry-run prints the would-be actions without writing
  * anything; an already-initialized repo is reported as a no-op, never an error. */
@@ -60,11 +60,11 @@ export async function cmdInit(root, args) {
     }
     say(`created ${result.created.join(", ")}${result.committed ? " (committed)" : ""}`);
     if (result.bootstrap !== null) {
-        say(`fresh project — maintenance loops wait until ${result.bootstrap} plans are done; remove "bootstrap" from tumwater.json to end that early`);
+        say(`fresh project — maintenance roles wait until ${result.bootstrap} plans are done; remove "bootstrap" from tumwater.json to end that early`);
     }
-    say("next: `tumwater run` in one terminal, `tumwater tui` in another");
+    say("next: `tumwater start` in one terminal, `tumwater tui` in another");
 }
-/** `tumwater run`: boot the fleet and stream its event feed to this terminal until it stops.
+/** `tumwater run`: 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
  * (superviseRunCommand 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
@@ -73,14 +73,20 @@ export async function cmdInit(root, args) {
  * `--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, so the deadline restarts in the new
- * generation — the window is per-generation, stated here rather than coded around. */
+ * (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 cmdRun(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 RUN_FLAG_SPECS).
     const once = args.includes("--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.
+    if (once && args.includes("--tui"))
+        failRivalShapes("--tui", "--once", "a one-round run cannot hold a TUI it is about to kill");
     // The dashboard cannot serve a run that is about to stop: a --once round drains and exits
     // within the same invocation, so the two shapes are refused together before any boot. --for
     // stays allowed — the dashboard serves for the window.
@@ -102,23 +108,25 @@ export async function cmdRun(root, args) {
     const roleFilter = parseRoleFlag(args, loopIds(config));
     if (roleFilter !== null && !once)
         fail("--role is only valid with --once");
-    // The refusal an operator hits by trying to start a second fleet in one repo: name the
+    // 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
     // liveness check, like snapshot's own poll.
     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 fleet-booting machinery loads only once a run actually boots: the orchestrator's
-    // module graph (with its landing pipeline, review gate, and scheduler) is the CLI's heaviest
+    // 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, startParentDeathWatch, expectedSupervisorPid } = await import("../process/supervisor.js");
+    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).
-        await superviseRunCommand(root, args, branchArg);
+        // A stop marker left by a team that died before its deadline must not stop this run.
+        cancelScheduledStop(root);
+        await superviseRunCommand(root, args, branchArg, forMs);
         return;
     }
     const controller = new AbortController();
@@ -127,7 +135,7 @@ export async function cmdRun(root, args) {
         if (stopping)
             process.exit(130);
         stopping = true;
-        say("\nstopping — waiting for in-flight ticks (Ctrl+C again to force)");
+        say("\nstopping — finishing current runs (Ctrl+C again to force)");
         controller.abort();
     };
     process.on("SIGINT", stop);
@@ -135,15 +143,20 @@ export async function cmdRun(root, args) {
     // 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.
-    const deadlineTimer = forMs !== null ? armDeadlineTimer(forMs, () => {
+    const windowStart = inheritedWindowStart(process.env[RUN_WINDOW_START_ENV], Date.now());
+    const deadlineTimer = forMs !== null ? armDeadlineTimer(Math.max(0, windowStart + forMs - Date.now()), () => {
         say("deadline reached — stopping");
         stop();
     }) : null;
+    const scheduledStopWatch = armScheduledStopWatch(root, () => {
+        if (!stopping)
+            stop(); // A drain already under way must not be turned into a force-kill.
+    });
     // 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 ticking the fleet unattended. The parent-death watch polls for the
+    // generation reparented and ticking 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 fleet down with it (BUGS.md 2026-09-30). The spawner hands its pid
+    // 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.
@@ -161,22 +174,23 @@ export async function cmdRun(root, args) {
         ? 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 fleet watches launchservicesd's port count (a no-op off macOS); a once round
+    // 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);
-    // Name the resolved root when it differs from the cwd: an operator who started the fleet
+    // 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}` : "";
     const forNote = forMs !== null ? ` · for ${durationLabel(forMs)}` : "";
     say(once
         ? `tumwater once on branch ${mainBranch}${rootNote} — one round, then exit`
         : `tumwater running on branch ${mainBranch}${forNote}${build}${rootNote} — Ctrl+C to stop`);
-    say(`loops: ${roles.join(", ")}`);
+    say(`roles: ${roles.join(", ")}`);
     say("watch: `tumwater tui` or `tumwater logs -f` in another terminal; events stream below\n");
     const unsubscribe = subscribeEvents((e) => say(formatEvent(e)));
     // Snapshot each role's tick counter so the once summary can tell this round's ticks from
     // the persisted history (the state file accumulates across rounds).
-    const ticksBefore = new Map(roles.map((role) => [role, loadLoopState(root, role).ticks]));
+    await runStartupMigrations(root); // so the snapshot reads a migrated state/<new>.json
+    const ticksBefore = new Map(roles.map((role) => [role, loadLoopState(root, role).runs]));
     let exit;
     try {
         exit = await (await import("../orchestrator/orchestrator.js")).runOrchestrator({
@@ -188,20 +202,56 @@ export async function cmdRun(root, args) {
             launchServicesWatch,
             once,
             roleFilter: roleFilter ?? undefined,
+            stopsAt: forMs !== null ? windowStart + forMs : undefined,
         });
     }
     finally {
         if (deadlineTimer)
             deadlineTimer.clear();
+        scheduledStopWatch.clear();
         unsubscribe();
     }
-    if (once || forMs !== null)
+    if (once)
         say(onceSummary(root, roles, ticksBefore, exit.settled, exit.ticksRun));
+    else if (forMs !== null && !exit.restart) {
+        const { rows, covered } = readTickRowsSince(root, Date.now() - windowStart, null);
+        say(windowSummary(durationLabel(forMs), summarizeTickRows(rows), covered));
+    }
+    if (once) {
+        const failures = onceFailures(root, roles, ticksBefore, exit.ticksRun);
+        if (failures.length > 0) {
+            say(`once: failed — ${failures.map((f) => `${f.role} ${f.result}`).join(", ")}`);
+            process.exitCode = ONCE_FAILED_EXIT_CODE;
+        }
+    }
     // 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);
 }
+/** The window start a generation adopts: the supervisor's RUN_WINDOW_START_ENV mark when it is a
+ * positive integer no later than `now`, else `now` (absent, malformed, or in the future). */
+export function inheritedWindowStart(raw, now) {
+    const n = Number(raw);
+    return raw !== undefined && Number.isInteger(n) && n > 0 && n <= now ? n : now;
+}
+/** The `run --for` exit summary: a window line, then the `history --summary` table for the ticks
+ * that ended since the window opened — every tick counted once by its outcome class. Only the
+ * final exit prints it; a mid-window self-redeploy hands off silently and the next generation
+ * inherits the window start, so the table spans every generation. */
+export function windowSummary(label, summary, covered) {
+    const { total } = summary;
+    const lines = [
+        total.runs === 0
+            ? `for ${label}: 0 runs — nothing ran`
+            : `for ${label}: ${plural(total.runs, "run")} — ${total.changes} changes, ${total.none} none, ${total.refused} refused, ${total.problems} problems`,
+    ];
+    if (total.runs > 0)
+        lines.push(renderSummary(summary));
+    if (!covered)
+        lines.push(SPARSE_WINDOW_NOTE);
+    return lines.join("\n");
+}
 /** Arm the windowed run's deadline timer: the one home of the arming `cmdRun` does for
  * `run --for <duration>`. A duration over setTimeout's own 32-bit signed ceiling
  * (2_147_483_647 ms ≈ 24.8 days) is clamped by Node to 1ms with a TimeoutOverflowWarning, so
@@ -228,6 +278,23 @@ export function armDeadlineTimer(ms, onFired) {
     arm(ms);
     return { clear: () => clearTimeout(timer) };
 }
+const SCHEDULED_STOP_POLL_MS = 5000;
+/** Poll for a `tumwater stop --in` marker: once its `until` has passed, consume the marker,
+ * stop polling, and call `onStop` (cmdRun's Ctrl+C closure) exactly once. The interval is
+ * unref'd; clear() retracts it. Exported for tests. */
+export function armScheduledStopWatch(root, onStop) {
+    const timer = setInterval(() => {
+        const at = scheduledStopAt(root);
+        if (at === undefined || at > Date.now())
+            return;
+        clearInterval(timer);
+        cancelScheduledStop(root);
+        say("scheduled stop reached — stopping");
+        onStop();
+    }, SCHEDULED_STOP_POLL_MS);
+    timer.unref();
+    return { clear: () => clearInterval(timer) };
+}
 /** Parse `run --for <duration>` (the windowed run): the parsed duration in milliseconds, or null
  * when the flag is absent. The two body-level rules fail fast, before any repo gate or boot: the
  * value must parse as a duration (parseDurationFlag's own wording, the same messages the
@@ -239,12 +306,49 @@ export function parseRunWindow(args, once) {
     const raw = flagValue(args, "--for");
     if (raw === null)
         return null;
-    const ms = parseDurationFlag("run --for", raw);
+    const ms = parseDurationFlag("start --for", raw);
     if (once)
         failRivalShapes("--for", "--once", "a one-round run and a windowed run cannot both apply");
     failOverDurationCap("--for", ms, PAUSE_FOR_MAX_MS);
     return ms;
 }
+/** Results that mean the harness or the project's check failed and the round's work did not
+ * merge: a `--once` round with a role ending in one exits ONCE_FAILED_EXIT_CODE. `rejected` and
+ * `refused` are the review gate and the agent working as designed; `aborted`, `quiet_killed`, and
+ * `user_aborted` only reach a once round on a shutdown or operator abort, which exit
+ * their own way. */
+export const ONCE_FAILURE_RESULTS = new Set([
+    "error",
+    "review_error",
+    "merge_conflict",
+    "merge_blocked",
+    "main_red",
+]);
+function ticksThisRound(s, role, ticksBefore, ticksRun) {
+    return ticksRun ? (ticksRun.get(role) ?? 0) : s.runs - (ticksBefore.get(role) ?? 0);
+}
+/** Every role that could have ticked in this once round — `roles` in order plus any role that
+ * appears only in `ticksRun` (enabled mid-round after `ticksBefore` was taken) — paired with
+ * its loaded loop state and the number of ticks it ran this round. The same per-role setup
+ * onceFailures and onceSummary both repeat, folded here so the two summary passes cannot
+ * drift on which roles they visit or how they count a round's work. */
+function onceRoundRoles(root, roles, ticksBefore, ticksRun) {
+    const extra = ticksRun ? [...ticksRun.keys()].filter((r) => !roles.includes(r)) : [];
+    return [...roles, ...extra].map((role) => {
+        const state = loadLoopState(root, role);
+        return { role, state, ran: ticksThisRound(state, role, ticksBefore, ticksRun) };
+    });
+}
+/** The roles that ticked this round and whose last result is in ONCE_FAILURE_RESULTS. */
+export function onceFailures(root, roles, ticksBefore, ticksRun) {
+    const out = [];
+    for (const { role, state, ran } of onceRoundRoles(root, roles, ticksBefore, ticksRun)) {
+        if (ran > 0 && state.lastResult && ONCE_FAILURE_RESULTS.has(state.lastResult)) {
+            out.push({ role, result: state.lastResult });
+        }
+    }
+    return out;
+}
 /** The once round's one-line summary, read from the runners' persisted loop state plus the
  * orchestrator's own settle reasons — a cron job's log shows what the round did without parsing
  * events. Roles whose tick counter advanced bucket by their last completed result; the rest are
@@ -268,20 +372,17 @@ export function onceSummary(root, roles, ticksBefore, settled, ticksRun) {
     let ticks = 0;
     const outcomes = new Map();
     const skipped = [];
-    const extra = ticksRun ? [...ticksRun.keys()].filter((r) => !roles.includes(r)) : [];
-    for (const role of [...roles, ...extra]) {
-        const s = loadLoopState(root, role);
-        const ran = ticksRun ? (ticksRun.get(role) ?? 0) : s.ticks - (ticksBefore.get(role) ?? 0);
+    for (const { role, state, ran } of onceRoundRoles(root, roles, ticksBefore, ticksRun)) {
         if (ran > 0) {
             ticks += ran;
-            const key = s.lastResult ?? "no_change";
+            const key = state.lastResult ?? "no_change";
             increment(outcomes, key);
         }
         else {
             const reason = settled?.get(role) ??
-                (isFleetPaused(root) || pausedRoles(root).includes(role)
+                (isTeamPaused(root) || loopPaused(new Set(pausedRoles(root)), role)
                     ? "paused"
-                    : stateSkipReason(s));
+                    : stateSkipReason(state));
             skipped.push(reason);
         }
     }
@@ -289,20 +390,24 @@ export function onceSummary(root, roles, ticksBefore, settled, ticksRun) {
     // would order `[key, count]` tuples by their "key,count" string form, which happens to
     // agree only while each key is unique.
     const counts = [...outcomes.entries()]
-        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .sort(([a], [b]) => compareCodeUnits(a, b))
         .map(([k, n]) => `${n} ${k}`)
         .join(", ");
     const skipNote = skipped.length === 0 ? "" : `, ${skipped.length} skipped (${skipped.join(", ")})`;
-    return `once: ${plural(ticks, "tick")} — ${counts || "nothing ran"}${skipNote}`;
+    return `once: ${plural(ticks, "run")} — ${counts || "nothing ran"}${skipNote}`;
 }
-/** Split `run`'s args for `run --gui`: whether the supervisor should also start the dashboard,
- * and the args the supervised orchestrator generation gets with `--gui` stripped so the
- * generation's own cmdRun never tries to supervise a second dashboard. Exported so the unit
- * tests pin the stripping that removing the spawn wiring would otherwise silently drop. */
+/** 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 cmdRun 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) {
     return {
         spawnGui: runArgs.includes("--gui"),
-        orchestratorArgs: runArgs.filter((arg) => arg !== "--gui"),
+        spawnTui: runArgs.includes("--tui"),
+        orchestratorArgs: runArgs.filter((arg) => arg !== "--gui" && arg !== "--tui"),
+        childStdio: runArgs.includes("--tui") ? ["ignore", "ignore", "ignore"] : "inherit",
     };
 }
 /** The dashboard half of `run --gui`: keep a `tumwater gui` child alive across its own
@@ -310,12 +415,12 @@ export function guiChildPlan(runArgs) {
  * 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 fleet running. */
-async function superviseDashboard(signal) {
+ * prints its own message and exits) ends this loop and leaves the team running. */
+async function superviseDashboard(signal, stdio = "inherit") {
     const { DASHBOARD_CHILD_ENV } = await import("../redeploy/self-reload.js");
     const { spawnGuiChild } = await import("../process/supervisor.js");
     for (;;) {
-        const exit = await spawnGuiChild(signal, { [DASHBOARD_CHILD_ENV]: String(process.pid) });
+        const exit = await spawnGuiChild(signal, { [DASHBOARD_CHILD_ENV]: String(process.pid) }, stdio);
         if (signal.aborted || exit.code !== RESTART_EXIT_CODE)
             return;
     }
@@ -323,14 +428,24 @@ async function superviseDashboard(signal) {
 /** The supervisor half of `tumwater run` (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 fleet that goes down without
+ * 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 superviseRunCommand(root, runArgs, branchArg) {
+async function superviseRunCommand(root, runArgs, branchArg, forMs) {
     // The supervisor machinery loads lazily, like cmdRun's orchestrator import above: a command
-    // that never boots the fleet never compiles it.
-    const { fleetDownEvent, spawnRunChild, superviseRun } = await import("../process/supervisor.js");
+    // that never boots the team never compiles it.
+    const { RUN_WINDOW_START_ENV, teamDownEvent, spawnRunChild, superviseRun } = 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 superviseRun 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
@@ -345,18 +460,47 @@ async function superviseRunCommand(root, runArgs, branchArg) {
         controller.abort(); // Not delivered to the child by the kernel — forward it.
         guiController.abort();
     });
-    const gui = plan.spawnGui ? superviseDashboard(guiController.signal) : Promise.resolve();
+    // 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 superviseRun
+    // drains in-flight ticks 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.childStdio) : Promise.resolve();
     const code = await superviseRun({
-        spawnChild: (signal) => spawnRunChild(signal, plan.orchestratorArgs),
+        spawnChild: (signal) => spawnRunChild(signal, plan.orchestratorArgs, windowEnv, plan.childStdio),
         stopping: () => stopping,
-        onRespawn: (generation) => say(`\nrestarting on the new build (generation ${generation})\n`),
-        onCrashLoop: () => process.stderr.write("tumwater: the harness restarted itself too many times in a minute — giving up\n"),
+        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)
+                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.
-        onFleetDown: async (down) => {
-            logEvent(root, fleetDownEvent(down, down.crashLoop ? null : await runStartupProblem(root, branchArg)));
+        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
@@ -367,9 +511,14 @@ async function superviseRunCommand(root, runArgs, branchArg) {
         // reports its own outcome, so it can never change the exit code.
         onDone: () => repairInterruptedSwap(root),
     }, controller.signal);
-    // The orchestrator is gone; take the dashboard with it so a stopped fleet never leaves a
-    // dashboard holding its port. abort() SIGTERMs the current gui child; await lets the spawn
-    // loop observe the abort before this process exits.
+    // 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);