tumwater 0.2.0 → 0.3.0

package/dist/src/cli/{cli-run.js → cli-start.js}

@@ -1,87 +1,41 @@
-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 { cancelScheduledStop, isTeamPaused, pausedRoles, scheduledStopAt } from "../team/team-state.js";
+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 { cancelScheduledStop, 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 { loadRunnerState } from "../runner/runner-state-load.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. */
-export async function cmdInit(root, args) {
-    const { prompt, branch, template, listTemplates, adopt, dryRun } = parseInitArgs(args);
-    if (listTemplates) {
-        for (const { id, description } of templateCatalog())
-            say(`${id} — ${description}`);
-        return;
-    }
-    const result = await initProject(root, prompt, branch ?? undefined, {
-        adopt,
-        dryRun,
-        template: template ?? undefined,
-    });
-    if (result.template !== "blank")
-        say(`template: ${result.template}`);
-    if (result.adopted) {
-        say(`${result.dryRun ? "would adopt" : "adopting"} an existing repo: the project brief goes in TUMWATER.md and README.md is left untouched`);
-    }
-    if (result.dryRun) {
-        if (result.repoInitialized && result.branch) {
-            say(`dry run — would initialize a new git repository on branch ${result.branch}`);
-        }
-        const list = (names) => (names.length > 0 ? names.join(", ") : "nothing");
-        say(`dry run — would create: ${list(result.created)}`);
-        say(`would leave alone: ${list(result.leftAlone)}`);
-        say("nothing written; re-run without --dry-run to apply");
-        return;
-    }
-    if (result.created.length === 0) {
-        say("already initialized; nothing to do");
-        return;
-    }
-    if (result.repoInitialized && result.branch) {
-        say(`initialized a new git repository on branch ${result.branch}`);
-    }
-    say(`created ${result.created.join(", ")}${result.committed ? " (committed)" : ""}`);
-    if (result.bootstrap !== null) {
-        say(`fresh project — maintenance roles wait until ${result.bootstrap} plans are done; remove "bootstrap" from tumwater.json to end that early`);
-    }
-    say("next: `tumwater start` in one terminal, `tumwater tui` in another");
-}
-/** `tumwater run`: boot the team and stream its event feed to this terminal until it stops.
+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";
+export { ONCE_FAILURE_RESULTS, inheritedWindowStart, onceFailures, onceReport, onceSummary, parseRunWindow, renderOnceSummary, windowReport, windowSummary, };
+/** `tumwater start`: boot the team and stream its event feed to this terminal until it stops.
  * Three layers cooperate here: without SUPERVISED_ENV this process becomes the supervisor
- * (superviseRunCommand below), spawning the real orchestrator as a child generation; the child
+ * (superviseStartCommand below), spawning the real orchestrator as a child generation; the child
  * runs runOrchestrator to completion, handing the terminal back via RESTART_EXIT_CODE after a
  * self-redeploy so the supervisor respawns on the new build; --once collapses the whole thing
- * into one round of ticks and a summary line (onceSummary below), for cron-style invocations.
+ * into one round of runs and a summary line (onceSummary below), for cron-style invocations.
  * `--for <duration>` keeps the daemon shape (redeployer, LaunchServicesWatch, supervisor hand-off
  * all stay) but arms a deadline: at the deadline the same graceful stop a Ctrl+C runs fires, and
  * the process exits after printing the summary. A mid-run self-redeploy hands the same args
  * (including `--for`) to the supervisor's next child, and the supervisor hands every generation
  * the same window start (RUN_WINDOW_START_ENV), so the deadline and the summary span the whole
  * window; only the final exit prints the summary. */
-export async function cmdRun(root, args) {
+export async function cmdStart(root, args) {
     // The one function the self-redeploy asks before swapping onto a successor and the supervisor
     // asks when a generation dies, so the three cannot disagree about what boots. The supervisor
     // half runs it too, so a start that cannot boot fails before any child spawns. The flag
-    // vocabulary is validated by the dispatcher (cli.ts, from the same RUN_FLAG_SPECS).
+    // vocabulary is validated by the dispatcher (cli.ts, from the same START_FLAG_SPECS).
     const once = args.includes("--once");
+    const json = args.includes("--json");
     // 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.
@@ -92,22 +46,57 @@ export async function cmdRun(root, args) {
     // stays allowed — the dashboard serves for the window.
     if (once && args.includes("--gui"))
         failRivalShapes("--gui", "--once", "a one-round run cannot serve a dashboard it is about to kill");
+    // `--port` chooses the `--gui` dashboard's port; without `--gui` it names no port for this
+    // command, so refuse it (a valid value already passed the spec's shape gate) before any boot.
+    if (args.includes("--port") && !args.includes("--gui"))
+        fail("--port is only valid with --gui (e.g. `tumwater start --gui --port 8080`); the standalone dashboard is `tumwater gui --port <n>`");
+    // `--all-interfaces` and `--token` are dashboard-only flags too: without `--gui` each names
+    // nothing this command starts, so refuse them (valid values already passed the spec's shape
+    // gate) before any boot, with the same shape as the --port refusal above and fixing the
+    // copyable one-command form in the message.
+    if (args.includes("--all-interfaces") && !args.includes("--gui"))
+        fail("--all-interfaces is only valid with --gui (e.g. `tumwater start --gui --all-interfaces`); the standalone dashboard is `tumwater gui --all-interfaces`");
+    if (args.includes("--token") && !args.includes("--gui"))
+        fail("--token is only valid with --gui (e.g. `tumwater start --gui --token s3cret`); the standalone dashboard is `tumwater gui --token <secret>`");
+    // A malformed --token (valueless, empty, or flag-looking) must fail here before any boot, so
+    // a bad secret never leaves the team running behind a dashboard that exited. The same
+    // tokenValueProblem `tumwater gui` runs, named for the one-command form the operator typed.
+    const tokenProblem = tokenValueProblem(args, "tumwater start --gui");
+    if (tokenProblem)
+        fail(tokenProblem);
     const forMs = parseRunWindow(args, once);
     const branchArg = parseBranchFlag(args);
     const startup = await runStartupCheck(root, branchArg);
     if ("problem" in startup)
         fail(startup.problem);
     const { config, mainBranch } = startup;
-    // A scoped once round: `--role <id>` names the one loop that runs. Parsed here, where the
-    // live config is readable, and validated against the ENABLED ids — not the full catalog —
-    // so an unknown id and a disabled one fail fast with the same wording (a scoped round that
-    // booted a disabled role's runner would run nothing while claiming to serve the operator
-    // who just queued that loop a prompt). Custom loops are valid targets: knownRoleIds
-    // accepts them, and an enabled custom passes this check like any built-in. Daemon
-    // `run --role` stays an error: scoping is a once-round concept.
-    const roleFilter = parseRoleFlag(args, loopIds(config));
+    // A scoped once round: `--role <id>[,<id>...]` names the runners that run. Parsed here, where the
+    // live config is readable. The parser accepts every known id (custom roles included, enabled
+    // or not) so a typo still fails with the did-you-mean hint; an id that is known but has no
+    // runner is then named as disabled rather than read as unknown — a scoped round that booted
+    // a disabled role's runner would run nothing while claiming to serve the operator who just
+    // queued that role a prompt. Daemon `run --role` stays an error: scoping is a once-round concept.
+    const roleFilter = parseRoleListFlag(args, knownRoleIds(config));
     if (roleFilter !== null && !once)
         fail("--role is only valid with --once");
+    if (json && !once && forMs === null)
+        fail("--json is only valid with --once or --for");
+    // Both interactive modes write their own banner to the stdout a JSON document must own, so a
+    // --json round/window refuses them before any boot.
+    if (json && args.includes("--gui"))
+        failRivalShapes("--json", "--gui", "the dashboard writes its banner to the stdout a JSON document must own");
+    if (json && args.includes("--tui"))
+        failRivalShapes("--json", "--tui", "a TUI owns the terminal");
+    if (roleFilter !== null) {
+        const runners = runnerIds(config);
+        const missing = roleFilter.find((id) => !runners.includes(id));
+        if (missing !== undefined) {
+            const base = baseRoleOf(missing);
+            if (config.roles[base]?.enabled === false)
+                fail(`${missing} is disabled, so a --once round cannot run it — enable it with \`tumwater role ${base} --enable\``);
+            fail(unknownRoleMessage(missing, runners));
+        }
+    }
     // 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
@@ -126,7 +115,7 @@ export async function cmdRun(root, args) {
         // targets the same branch (or whatever else the invocation named).
         // A stop marker left by a team that died before its deadline must not stop this run.
         cancelScheduledStop(root);
-        await superviseRunCommand(root, args, branchArg, forMs);
+        await superviseStartCommand(root, args, branchArg, forMs);
         return;
     }
     const controller = new AbortController();
@@ -135,7 +124,11 @@ export async function cmdRun(root, args) {
         if (stopping)
             process.exit(130);
         stopping = true;
-        say("\nstopping — finishing current runs (Ctrl+C again to force)");
+        // A --once --json round's stdout must hold exactly its one JSON document, so a signal,
+        // parent death, or scheduled stop quietens the stop prose too; the non-zero exit below
+        // is what a cron/CI caller sees instead of the words. Non-json runs keep the prose.
+        if (!json)
+            say("\nstopping — finishing current runs (Ctrl+C again to force)");
         controller.abort();
     };
     process.on("SIGINT", stop);
@@ -145,16 +138,19 @@ export async function cmdRun(root, args) {
     // retracts it when the run ends first (an early Ctrl+C), so no stray timer outlives the run.
     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");
+        // A --for --json window's stdout must hold exactly its one JSON document, so the deadline
+        // prose is suppressed too; the document's non-zero-absent facts carry the window.
+        if (!json)
+            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.
-    });
+    }, 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 ticking the team unattended. The parent-death watch polls for the
+    // 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
@@ -162,10 +158,10 @@ export async function cmdRun(root, args) {
     // the supervised generation: an unsupervised `run` became the supervisor above and returned.
     const expectedPpid = expectedSupervisorPid();
     startParentDeathWatch(stop, expectedPpid !== undefined ? { expectedPpid } : {});
-    const enabled = loopIds(config);
-    // A scoped round's loop list is exactly the filter; otherwise every enabled loop runs.
-    const roles = roleFilter !== null ? [roleFilter] : enabled;
-    // Main's green verdicts outlive this generation: the redeployer and the loops' red-main gate
+    const enabled = runnerIds(config);
+    // A scoped round's role list is exactly the filter; otherwise every enabled role runs.
+    const roles = roleFilter ?? enabled;
+    // Main's green verdicts outlive this generation: the redeployer and the roles' red-main gate
     // start from the ones the previous generation verified instead of re-running the suite.
     (await import("../baseline/main-baseline.js")).persistBaselineVerdicts(root);
     // A once round never self-redeploys: it runs one round on the build it booted and exits,
@@ -181,16 +177,22 @@ export async function cmdRun(root, args) {
     // 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(`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
+    // A --once --json round's stdout must hold exactly its one JSON document, so its banner
+    // and event stream are suppressed: the caller parses the round's facts directly instead
+    // of the prose, and the orchestrator/merge pipeline logs events through logEvent (file
+    // plus subscription), not stdout, with nothing else printed on stdout for a once round.
+    if (!json) {
+        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(`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 ticksBefore = new Map(roles.map((role) => [role, loadLoopState(root, role).runs]));
+    const runsBefore = new Map(roles.map((role) => [role, loadRunnerState(root, role).runs]));
     let exit;
     try {
         exit = await (await import("../orchestrator/orchestrator.js")).runOrchestrator({
@@ -211,48 +213,42 @@ export async function cmdRun(root, args) {
         scheduledStopWatch.clear();
         unsubscribe();
     }
-    if (once)
-        say(onceSummary(root, roles, ticksBefore, exit.settled, exit.ticksRun));
+    if (once) {
+        if (json)
+            sayJson(onceReport(root, roles, runsBefore, exit.settled, exit.runsDone));
+        else
+            say(onceSummary(root, roles, runsBefore, exit.settled, exit.runsDone));
+    }
     else if (forMs !== null && !exit.restart) {
-        const { rows, covered } = readTickRowsSince(root, Date.now() - windowStart, null);
-        say(windowSummary(durationLabel(forMs), summarizeTickRows(rows), covered));
+        const { rows, covered } = readRunRowsSince(root, Date.now() - windowStart, null);
+        const summary = summarizeRunRows(rows);
+        if (json)
+            sayJson(windowReport(durationLabel(forMs), summary, covered));
+        else
+            say(windowSummary(durationLabel(forMs), summary, covered));
     }
     if (once) {
-        const failures = onceFailures(root, roles, ticksBefore, exit.ticksRun);
+        const failures = onceFailures(root, roles, runsBefore, exit.runsDone);
         if (failures.length > 0) {
-            say(`once: failed — ${failures.map((f) => `${f.role} ${f.result}`).join(", ")}`);
+            // 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.
+            if (!json)
+                say(`once: failed — ${failures.map((f) => `${f.role} ${f.result}`).join(", ")}`);
             process.exitCode = ONCE_FAILED_EXIT_CODE;
         }
+        // A round a signal, parent death, or scheduled stop cut short before it completed must
+        // 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)
+            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
+/** Arm the windowed run's deadline timer: the one home of the arming `cmdStart` does for
  * `run --for <duration>`. A duration over setTimeout's own 32-bit signed ceiling
  * (2_147_483_647 ms ≈ 24.8 days) is clamped by Node to 1ms with a TimeoutOverflowWarning, so
  * a raw setTimeout would fire the deadline the instant the run booted — and `run --for`
@@ -260,7 +256,7 @@ export function windowSummary(label, summary, covered) {
  * input, not an error. The timer is therefore armed in ≤32-bit chunks: each setTimeout covers
  * at most the ceiling, and a chunk that expires with time still left re-arms for the
  * remainder, so the callback runs exactly once, after the full duration, whatever its size.
- * Returns a clear() handle (the finally in cmdRun retracts the timer when the run ends first —
+ * Returns a clear() handle (the finally in cmdStart retracts the timer when the run ends first —
  * an early Ctrl+C — so no stray timer outlives the run); clear() is safe after the callback
  * has run. Exported for tests. */
 export function armDeadlineTimer(ms, onFired) {
@@ -280,133 +276,65 @@ export function armDeadlineTimer(ms, onFired) {
 }
 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
+ * stop polling, and call `onStop` (cmdStart's Ctrl+C closure) exactly once. The interval is
  * unref'd; clear() retracts it. Exported for tests. */
-export function armScheduledStopWatch(root, onStop) {
+export function armScheduledStopWatch(root, onStop, quiet = false) {
     const timer = setInterval(() => {
         const at = scheduledStopAt(root);
         if (at === undefined || at > Date.now())
             return;
         clearInterval(timer);
         cancelScheduledStop(root);
-        say("scheduled stop reached — stopping");
+        // quiet suppresses the "scheduled stop reached" prose for a --once --json round so its
+        // stdout holds exactly the one JSON document; the non-zero exit carries the interruption.
+        if (!quiet)
+            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
- * dispatcher's durationFlagSpec("run --for") gate already ran), and `--for` and `--once` are rivals
- * — a one-round run and a windowed run cannot both apply. The 90-day ceiling is `pause --for`'s
- * (PAUSE_FOR_MAX_MS), the same cap every scheduled window in the harness honors. Exported for
- * tests, exactly as onceSummary below is. */
-export function parseRunWindow(args, once) {
-    const raw = flagValue(args, "--for");
-    if (raw === null)
-        return null;
-    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
- * skipped with the reason the orchestrator settled them for (`paused`, `resume pending`,
- * `backoff`, `deferred`, `disabled`, `idle` — handed back on OrchestratorExit.settled, so a
- * deferred role reads as set aside, not as "nothing was due"); a role the map lacks (defensively
- * — the round only exits once every role is settled) falls back to deriving the reason from
- * state: a pause marker when one is held, a pending resume when one is flagged, backoff when
- * `backoffSeconds` is raised, otherwise idle — the same classification settleSkipped draws,
- * and keyed on the same signal: backoffSeconds is the backoff indicator, while nextRunAt is
- * shared with the scheduled clock a productive tick also writes (with backoffSeconds 0), so a
- * future nextRunAt alone reads as a not-yet-due role, not as backoff (BUGS.md 2026-09-25,
- * the same conflation settleSkipped itself carried).
- *
- * `ticksRun`, when the caller hands it back (the orchestrator's OnceRound snapshot deltas),
- * is the tick count's source of truth and also names roles the pre-round list never had —
- * a role enabled mid-round joins the runners array after `ticksBefore` was taken, so its
- * whole persisted history must not be counted as this round's work. Without it the old
- * `ticksBefore` delta path runs, for callers (and tests) without a round object. */
-export function onceSummary(root, roles, ticksBefore, settled, ticksRun) {
-    let ticks = 0;
-    const outcomes = new Map();
-    const skipped = [];
-    for (const { role, state, ran } of onceRoundRoles(root, roles, ticksBefore, ticksRun)) {
-        if (ran > 0) {
-            ticks += ran;
-            const key = state.lastResult ?? "no_change";
-            increment(outcomes, key);
-        }
-        else {
-            const reason = settled?.get(role) ??
-                (isTeamPaused(root) || loopPaused(new Set(pausedRoles(root)), role)
-                    ? "paused"
-                    : stateSkipReason(state));
-            skipped.push(reason);
-        }
-    }
-    // Sort by result key only. The comparator makes that explicit: a comparator-less sort
-    // 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]) => compareCodeUnits(a, b))
-        .map(([k, n]) => `${n} ${k}`)
-        .join(", ");
-    const skipNote = skipped.length === 0 ? "" : `, ${skipped.length} skipped (${skipped.join(", ")})`;
-    return `once: ${plural(ticks, "run")} — ${counts || "nothing ran"}${skipNote}`;
-}
 /** 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
+ * 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");
+    if (tokenRaw !== undefined)
+        guiArgs.push("--token", tokenRaw);
     return {
         spawnGui: runArgs.includes("--gui"),
         spawnTui: runArgs.includes("--tui"),
-        orchestratorArgs: runArgs.filter((arg) => arg !== "--gui" && arg !== "--tui"),
+        guiArgs,
+        orchestratorArgs: runArgs.filter((arg, i) => arg !== "--gui" && arg !== "--tui" && arg !== "--all-interfaces" && !skip.has(i)),
         childStdio: runArgs.includes("--tui") ? ["ignore", "ignore", "ignore"] : "inherit",
     };
 }
@@ -416,30 +344,30 @@ export function guiChildPlan(runArgs) {
  * 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, stdio = "inherit") {
+async function superviseDashboard(signal, stdio = "inherit", guiArgs = []) {
     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) }, stdio);
+        const exit = await spawnGuiChild(signal, { [DASHBOARD_CHILD_ENV]: String(process.pid) }, stdio, guiArgs);
         if (signal.aborted || exit.code !== RESTART_EXIT_CODE)
             return;
     }
 }
-/** The supervisor half of `tumwater run` (src/process/supervisor.ts): spawn the orchestrator as a
+/** 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 superviseRunCommand(root, runArgs, branchArg, forMs) {
-    // The supervisor machinery loads lazily, like cmdRun's orchestrator import above: a command
+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, spawnRunChild, superviseRun } = await import("../process/supervisor.js");
+    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 superviseRun settles and then crash the supervisor after
+    // 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");
@@ -462,8 +390,8 @@ async function superviseRunCommand(root, runArgs, branchArg, forMs) {
     });
     // 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;
+    // 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
@@ -481,16 +409,16 @@ async function superviseRunCommand(root, runArgs, branchArg, forMs) {
             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, windowEnv, plan.childStdio),
+    const gui = plan.spawnGui ? superviseDashboard(guiController.signal, 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)
+            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"),