tumwater 0.4.2 → 0.4.4

package/dist/src/cli/{question-commands.js → cli-question-commands.js}

@@ -1,8 +1,9 @@
 /** The CLI layer of `tumwater questions` — the `tumwater questions` command body: list the open
  * questions in QUESTIONS.md numbered, or `answer <n> <decision>` one, which moves its entry from
  * `## Open` to `## Answered` with a dated operator answer. The markdown surgery itself — the
- * fence-aware `### ` block cut and the `## Answered` skeleton — lives in src/backlog/
- * question-answer.ts (the shared QUESTIONS.md core the TUI and dashboard also call); this module
+ * fence-aware `### ` block cut and the `## Answered` skeleton — lives in
+ * src/backlog/backlog-question-answer.ts (the shared QUESTIONS.md core the TUI and dashboard also
+ * call); this module
  * is the command's argument scan, say/fail/editor jacket and commit-and-wake tail over that core,
  * routed to by src/cli.ts.
  */
@@ -17,8 +18,14 @@ import { typoSuffix } from "../text/suggest.js";
 import { commitOperatorBacklogEdit } from "../backlog/backlog-commit.js";
 import { stampedSubject } from "../git/commit-message.js";
 import { wakeQuestionAsker } from "../operator/operator-intent.js";
-import { answeredQuestionAt, answeredQuestionCount, answeredQuestionList, answeredQuestionPayload, openQuestionAt, openQuestionList, questionListPayload, renderShownQuestion, UNCLOSED_FENCE_MESSAGE, tryAnswerQuestion } from "../backlog/question-answer.js";
+import { answeredQuestionAt, answeredQuestionCount, answeredQuestionList, answeredQuestionPayload, openQuestionAt, openQuestionList, questionListPayload, renderShownQuestion, UNCLOSED_FENCE_MESSAGE, tryAnswerQuestion } from "../backlog/backlog-question-answer.js";
 import { bodyStructureProblem, normalizeEntryBody } from "../backlog/backlog-write.js";
+/** `questions --answered -n`'s ceiling: bounds how many answered questions one list shows,
+ * so a typo'd huge count fails fast with the shared `must be between 1 and <max>` wording
+ * (the logs/history/report pattern) instead of silently meaning "everything". The list data
+ * is small (QUESTIONS.md), so the cap never meaningfully binds — it exists for the uniform
+ * count-flag contract and the clear over-range rebuke, not for memory. */
+const QUESTIONS_MAX_LISTED = 100_000;
 /** The `tumwater questions answer` entry point: `tryAnswerQuestion` without a title check, its
  * refusals mapped to `fail` (exit 1) with the CLI's wording. Returns the answered question's
  * title plus the collapsed decision that landed in the file. */
@@ -84,6 +91,72 @@ function sayQuestionList(root, json, pattern) {
 }
 /** `questions answer`'s `--file <path>` flag: the decision comes from the file, lines kept. */
 const FILE_SPEC = { names: ["--file"], value: true, valueName: "<path>" };
+/** The `--show`/`--answered`/`-n`/`--grep` arms — the flags only valid before the question's
+ * number positional. Each performs its read and writes its `scan.<field>` exactly as the
+ * inline scan did; returns `i` (the index of the last token consumed, after any `args[++i]`);
+ * every other token returns `undefined`. */
+function readPreNumberFlag(scan, args, i) {
+    if (scan.numbered)
+        return undefined;
+    const arg = args[i];
+    if (arg === "--show") {
+        rejectRepeatFlag(scan.show !== undefined, "--show");
+        scan.show = parsePositionFlag("--show", args[++i], "--show 2");
+        return i;
+    }
+    if (arg === "--answered") {
+        rejectRepeatFlag(scan.answeredFlag, "--answered");
+        scan.answeredFlag = true;
+        return i;
+    }
+    if (arg === "-n") {
+        rejectRepeatFlag(scan.limit !== undefined, "-n");
+        scan.limit = parseCountFlag("-n", args[++i], QUESTIONS_MAX_LISTED);
+        return i;
+    }
+    if (arg === "--grep") {
+        rejectRepeatFlag(scan.grep !== undefined, "--grep");
+        const text = args[++i];
+        if (text === undefined || text === "")
+            fail("--grep needs text (usage: tumwater questions [--answered] --grep <text>)");
+        scan.grep = text;
+        return i;
+    }
+    return undefined;
+}
+/** The `--file` arm (valid anywhere), the `!numbered && --json` arm, and the unknown
+ * `--`-flag gate — in that order. Returns `i` when `--file`/`--json` consumed the token; the
+ * unknown-flag arm never returns (it `fail`s). */
+function readAnywhereFlag(scan, args, i) {
+    const arg = args[i];
+    if (arg === "--file") {
+        rejectRepeatFlag(scan.file !== undefined, "--file");
+        scan.file = promptFileValue(args[++i]);
+        return i;
+    }
+    if (!scan.numbered && arg === "--json") {
+        rejectRepeatFlag(scan.jsonFlag, "--json");
+        scan.jsonFlag = true;
+        return i;
+    }
+    if (arg.startsWith("--") && arg !== "--json") {
+        rejectEqualsForm(arg, [JSON_FLAG, FILE_SPEC, { names: ["--show"], value: true, valueName: "<n>" }, { names: ["--grep"], value: true, valueName: "<text>" }]);
+        // The complete flag set (this gate only sees `--`-flags, but `-n` is a real flag the
+        // list should not omit) plus the same did-you-mean hint the sibling commands'
+        // unknown-argument gate (cli-flag-specs's failUnknownArgument) attaches, so a mistyped
+        // `--ansered` names `--answered` instead of only printing the valid list — the missing
+        // treatment the questions gate was the one unknown-argument caller without.
+        const spellings = ["--json", "--file", "--answered", "--show", "--grep", "-n"];
+        fail(`unknown argument: ${arg} (valid flags for tumwater questions: ${spellings.join(", ")})${typoSuffix(arg, spellings)}`);
+    }
+    return undefined;
+}
+/** The trailing `-n needs --answered` guard: `-n` limits the answered list, so without
+ * `--answered` it means nothing. */
+function assertQuestionsFlags(scan) {
+    if (scan.limit !== undefined && !scan.answeredFlag)
+        fail("-n needs --answered (it limits the answered questions listed)");
+}
 /** No requireReadyRepo gate, like backlog: the reader degrades to an empty list on a
  * missing QUESTIONS.md, so the command inspects any directory instead of refusing (a team
  * workspace still refuses).
@@ -102,72 +175,25 @@ const FILE_SPEC = { names: ["--file"], value: true, valueName: "<path>" };
  * into JSON mode. Unknown `--`-prefixed tokens stay refused even there, so a misspelled
  * flag is still an error rather than silent decision text. */
 function parseQuestionsInvocation(args) {
-    const words = [];
-    let jsonFlag = false;
-    let numbered = false;
-    let file;
-    let answeredFlag = false;
-    let limit;
-    let grep;
-    let show;
+    const scan = { words: [], jsonFlag: false, numbered: false, file: undefined, answeredFlag: false, limit: undefined, grep: undefined, show: undefined };
     for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-        if (!numbered && arg === "--show") {
-            rejectRepeatFlag(show !== undefined, "--show");
-            show = parsePositionFlag("--show", args[++i], "--show 2");
+        const consumed = readPreNumberFlag(scan, args, i) ?? readAnywhereFlag(scan, args, i);
+        if (consumed !== undefined) {
+            i = consumed;
             continue;
         }
-        if (!numbered && arg === "--answered") {
-            rejectRepeatFlag(answeredFlag, "--answered");
-            answeredFlag = true;
-            continue;
-        }
-        if (!numbered && arg === "-n") {
-            rejectRepeatFlag(limit !== undefined, "-n");
-            limit = parseCountFlag("-n", args[++i]);
-            continue;
-        }
-        if (!numbered && arg === "--grep") {
-            rejectRepeatFlag(grep !== undefined, "--grep");
-            const text = args[++i];
-            if (text === undefined || text === "")
-                fail("--grep needs text (usage: tumwater questions [--answered] --grep <text>)");
-            grep = text;
-            continue;
-        }
-        if (arg === "--file") {
-            rejectRepeatFlag(file !== undefined, "--file");
-            file = promptFileValue(args[++i]);
-            continue;
-        }
-        if (!numbered && arg === "--json") {
-            rejectRepeatFlag(jsonFlag, "--json");
-            jsonFlag = true;
-            continue;
-        }
-        if (arg.startsWith("--") && arg !== "--json") {
-            rejectEqualsForm(arg, [JSON_FLAG, FILE_SPEC, { names: ["--show"], value: true, valueName: "<n>" }, { names: ["--grep"], value: true, valueName: "<text>" }]);
-            // The complete flag set (this gate only sees `--`-flags, but `-n` is a real flag the
-            // list should not omit) plus the same did-you-mean hint the sibling commands'
-            // unknown-argument gate (cli-flag-specs's failUnknownArgument) attaches, so a mistyped
-            // `--ansered` names `--answered` instead of only printing the valid list — the missing
-            // treatment the questions gate was the one unknown-argument caller without.
-            const spellings = ["--json", "--file", "--answered", "--show", "--grep", "-n"];
-            fail(`unknown argument: ${arg} (valid flags for tumwater questions: ${spellings.join(", ")})${typoSuffix(arg, spellings)}`);
-        }
-        if (!numbered) {
+        if (!scan.numbered) {
             // The position is a plain-decimal positive integer (parsePositiveInt's rule, the same
             // one --cancel's position honors): bare Number() admitted hex ("0x2"), exponent
             // ("1e2"), and whitespace-padded spellings as a valid question number, answering a
             // question the operator never named.
-            if (parsePositiveInt(arg) !== null)
-                numbered = true;
+            if (parsePositiveInt(args[i]) !== null)
+                scan.numbered = true;
         }
-        words.push(arg);
+        scan.words.push(args[i]);
     }
-    if (limit !== undefined && !answeredFlag)
-        fail("-n needs --answered (it limits the answered questions listed)");
-    return { words, jsonFlag, file, answeredFlag, limit, grep, show };
+    assertQuestionsFlags(scan);
+    return { words: scan.words, jsonFlag: scan.jsonFlag, file: scan.file, answeredFlag: scan.answeredFlag, limit: scan.limit, grep: scan.grep, show: scan.show };
 }
 /** The `--show` output branch: one open (or, with `--answered`, answered) question in full. */
 function sayShownQuestion(root, inv) {

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

@@ -1,12 +1,12 @@
 /** The repo-readiness gate every repo-bound command runs before its body reads state: fail
- * fast on the first unmet precondition (startup-gate.ts's repoNotReady — the repo half of
+ * fast on the first unmet precondition (startup-gates.ts's repoNotReady — the repo half of
  * `tumwater start`'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-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 { teamWorkspaceMessage } from "../gates/readiness.js";
-import { repoNotReady } from "../gates/startup-gate.js";
+import { repoNotReady } from "../gates/startup-gates.js";
 import { owningTeamRoot } from "../paths.js";
 /** Fail (exit 1) on the first unmet repo precondition, naming the fix; return once the repo is
  * ready. */

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

@@ -1,7 +1,7 @@
 /** `tumwater role <id>`'s command body, split out of cli-query-commands.ts so that module
  * keeps only the read-only query commands (status, diff, queue, backlog). cli.ts's dispatcher
  * routes to cmdRole here exactly as it routes cmdStatus to cli-query-commands or cmdConfig to
- * config-commands. cmdRole is the one query-named command that also writes: it renders a
+ * cli-config-commands. cmdRole is the one query-named command that also writes: it renders a
  * role's standing and next-run prompts and carries eleven per-role write flags (notes,
  * instructions, quiet-hours, daily cap, min-run-interval, instances, enable/disable, and the
  * provider/model/thinking/backend), each through the same setConfigKey/unsetConfigKey core
@@ -56,10 +56,6 @@ const INSTANCES_SPEC = { names: ["--instances"], value: true, valueName: "<n>" }
  * roles.<base>.enabled. */
 const ENABLE_SPEC = { names: ["--enable"] };
 const DISABLE_SPEC = { names: ["--disable"] };
-/** `role`'s review-after-merge write flags: add the role to, or remove it from,
- * review.afterMerge (written for the base id). */
-const REVIEW_AFTER_MERGE_SPEC = { names: ["--review-after-merge"] };
-const CLEAR_REVIEW_AFTER_MERGE_SPEC = { names: ["--clear-review-after-merge"] };
 /** `role`'s model-triple write flags: clear the field, or set it, written to
  * roles.<base>.provider/.model/.thinking. model and provider take an id; thinking takes a
  * pi `--thinking` level (off|minimal|low|medium|high|xhigh|max). */
@@ -175,7 +171,7 @@ export async function cmdRole(root, args) {
         if (next?.startsWith("--"))
             fail(`${flag} needs a value (the next token ${JSON.stringify(next)} is a flag, not a value)`);
     }
-    rejectUnknownArgs("role", rest, [ROLE_FLAG, JSON_FLAG, CLEAR_NOTES_SPEC, NOTES_FILE_SPEC, CLEAR_INSTRUCTIONS_SPEC, INSTRUCTIONS_FILE_SPEC, CLEAR_QUIET_HOURS_SPEC, QUIET_HOURS_SPEC, ENABLE_SPEC, DISABLE_SPEC, CLEAR_CAP_SPEC, CAP_SPEC, CLEAR_MIN_RUN_INTERVAL_SPEC, MIN_RUN_INTERVAL_SPEC, CLEAR_INSTANCES_SPEC, INSTANCES_SPEC, CLEAR_PROVIDER_SPEC, PROVIDER_SPEC, CLEAR_MODEL_SPEC, MODEL_SPEC, CLEAR_THINKING_SPEC, THINKING_SPEC, CLEAR_BACKEND_SPEC, BACKEND_SPEC, REVIEW_AFTER_MERGE_SPEC, CLEAR_REVIEW_AFTER_MERGE_SPEC]);
+    rejectUnknownArgs("role", rest, [ROLE_FLAG, JSON_FLAG, CLEAR_NOTES_SPEC, NOTES_FILE_SPEC, CLEAR_INSTRUCTIONS_SPEC, INSTRUCTIONS_FILE_SPEC, CLEAR_QUIET_HOURS_SPEC, QUIET_HOURS_SPEC, ENABLE_SPEC, DISABLE_SPEC, CLEAR_CAP_SPEC, CAP_SPEC, CLEAR_MIN_RUN_INTERVAL_SPEC, MIN_RUN_INTERVAL_SPEC, CLEAR_INSTANCES_SPEC, INSTANCES_SPEC, CLEAR_PROVIDER_SPEC, PROVIDER_SPEC, CLEAR_MODEL_SPEC, MODEL_SPEC, CLEAR_THINKING_SPEC, THINKING_SPEC, CLEAR_BACKEND_SPEC, BACKEND_SPEC]);
     refuseTeamWorkspace(root);
     // The id is required: positional (`tumwater role <id>`) or --role <id> (the flag
     // spelling every other role-targeting command shares). Both at once is a mistake, not
@@ -211,9 +207,6 @@ export async function cmdRole(root, args) {
     const backendWrite = clearBackend || rest.includes("--backend");
     const enable = rest.includes("--enable");
     const disable = rest.includes("--disable");
-    const reviewAfterMerge = rest.includes("--review-after-merge");
-    const clearReviewAfterMerge = rest.includes("--clear-review-after-merge");
-    const reviewAfterMergeWrite = reviewAfterMerge || clearReviewAfterMerge;
     const writes = [];
     if (notesWrite)
         writes.push("notes");
@@ -239,8 +232,6 @@ export async function cmdRole(root, args) {
         writes.push("enable");
     if (disable)
         writes.push("disable");
-    if (reviewAfterMergeWrite)
-        writes.push("review-after-merge");
     if (writes.length > 1)
         fail(`${writes.join(" and ")} writes cannot share one invocation`);
     if (notesWrite) {
@@ -443,36 +434,6 @@ export async function cmdRole(root, args) {
         say(`${base}: ${state}`);
         return;
     }
-    // The review-after-merge write: the one command the post-merge churn row's remedy
-    // needs — add the role to, or remove it from, review.afterMerge for the base id, the
-    // membership test reviewedAfterMerge shares. The whole-list value lands through the same
-    // setConfigKey core `config set review.afterMerge <json>` uses, so validateConfig owns the
-    // string-array shape, the known-role-id check and the `review.afterMerge must not be
-    // "director"` refusal, and the write is atomic. A role already in the asked-for state is
-    // reported as such and the file is left alone (the section branch compares the value
-    // against the resolved list, so a no-op reports unchanged and writes nothing).
-    if (reviewAfterMergeWrite) {
-        if (reviewAfterMerge && clearReviewAfterMerge)
-            fail("give --review-after-merge or --clear-review-after-merge, not both");
-        if (rest.includes("--json"))
-            fail("--json does not apply to a review-after-merge write");
-        requireKnownRole(root, id);
-        const base = baseRoleOf(id);
-        const list = loadConfigSafe(root).config?.review.afterMerge ?? [];
-        const has = list.includes(base);
-        const next = has === reviewAfterMerge ? list : reviewAfterMerge ? [...list, base] : list.filter((r) => r !== base);
-        const result = setConfigKey(root, "review.afterMerge", JSON.stringify(next));
-        if (!result.ok)
-            fail(result.error);
-        say(result.unchanged
-            ? reviewAfterMerge
-                ? `${base}: already in review.afterMerge, so tumwater.json was not written`
-                : `${base}: not in review.afterMerge, so nothing was cleared`
-            : reviewAfterMerge
-                ? `${base}: added to review.afterMerge`
-                : `${base}: removed from review.afterMerge`);
-        return;
-    }
     // The unknown-role answer (exit 1, unknownRoleMessage's wording) lives in the
     // collector; here the id just has to be non-null for the thunk's types.
     sayJsonOrRender(rest, () => rolePayload(root, id), renderRoleMarkdown);

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);
+}