tumwater 0.1.2 → 0.2.0

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

@@ -0,0 +1,58 @@
+// vocabulary: plain
+import path from "node:path";
+import { readBrief, renderBrief } from "../brief/brief.js";
+import { editInitialPrompt } from "../brief/brief-edit.js";
+import { editInEditor } from "./cli-editor.js";
+import { readPromptFileArg } from "./cli-command-args.js";
+import { JSON_FLAG, rejectUnknownArgs } from "./cli-flag-specs.js";
+import { fail, say, sayJson } from "./cli-output.js";
+import { requireReadyRepo } from "./cli-repo-gate.js";
+/** `brief`'s `--file <path>` flag: the replacement prompt (`-` for stdin). */
+const FILE_SPEC = { names: ["--file"], value: true, valueName: "<path>" };
+/** `brief`'s `--edit` flag: open the prompt in `$VISUAL`/`$EDITOR`. */
+const EDIT_SPEC = { names: ["--edit"] };
+/** `tumwater brief`: show the initial prompt and the file holding it, or with `--file <path>` to
+ * replace it (or with `--edit`, open it in the editor) under the checks init applies and commit
+ * that one file on main. */
+export async function cmdBrief(root, args) {
+    rejectUnknownArgs("brief", args, [JSON_FLAG, FILE_SPEC, EDIT_SPEC]);
+    await requireReadyRepo(root);
+    const json = args.includes("--json");
+    const fileIdx = args.indexOf("--file");
+    const edit = args.includes("--edit");
+    if (edit && fileIdx >= 0)
+        fail("pass --edit or --file, not both");
+    const brief = readBrief(root);
+    if (brief === null)
+        fail("no project brief with a prompt block found — run `tumwater init` first");
+    if (fileIdx < 0 && !edit) {
+        if (json)
+            sayJson({ file: brief.file, prompt: brief.prompt });
+        else
+            say(renderBrief(brief));
+        return;
+    }
+    let text;
+    if (edit) {
+        text = editInEditor(brief.prompt, "brief.md", "pass --file <path>");
+        if (text.trim() === brief.prompt.trim()) {
+            if (json)
+                sayJson({ file: path.basename(brief.file), changed: false, committed: false });
+            else
+                say("brief unchanged");
+            return;
+        }
+    }
+    else
+        text = readPromptFileArg(args[fileIdx + 1]);
+    const outcome = await editInitialPrompt(root, text);
+    if (!outcome.ok)
+        fail(outcome.error);
+    const { file: name, changed, committed } = outcome;
+    if (json)
+        sayJson({ file: name, changed, committed });
+    else if (!changed)
+        say("brief unchanged");
+    else
+        say(`brief updated in ${name}${committed ? " (committed to main)" : ""}`);
+}

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

@@ -3,6 +3,7 @@ import { BRANCH_VALUE_ERROR, ROLE_VALUE_ERROR } from "./cli-flag-specs.js";
 import { knownRoleIdsCached } from "../config/config.js";
 import { allRoleIds, unknownRoleMessage } from "../roles/roles.js";
 import { gotSuffix, parsePositiveInt } from "../text/text.js";
+import { canonicalRoleId } from "../roles/legacy-role-ids.js";
 /** CLI argument parsing and validation, shared by every command in cli.ts. The execution
  * layer calls these before running a command, so a bad flag fails fast with an actionable
  * message instead of the command silently running with default behavior. The plain-decimal
@@ -32,7 +33,7 @@ export function flagValue(args, flag) {
  * the shared wording (`<flag> may only be given once`), `seen` being the caller's accumulator
  * for that flag. One home for the wording the spec-driven gate (cli-flag-specs.ts), the
  * free-form parsers' pre-scan (cli-command-args.ts), and the bespoke command shells
- * (backlog-write.ts, cli-query-commands.ts) all apply, so a repeat cannot be reported as a
+ * (backlog-cli.ts, cli-query-commands.ts) all apply, so a repeat cannot be reported as a
  * different error on one surface. Called per occurrence rather than pre-scanned at every site,
  * so a malformed invocation still reports whichever error its token order reaches first. */
 export function rejectRepeatFlag(seen, flag) {
@@ -59,6 +60,24 @@ export function parseGrepFlag(args, missingValueError) {
         fail(missingValueError);
     return { rest, pattern: raw };
 }
+/** Parse an optional `--type <eventType>` exact-type filter flag for the event feed view
+ * (logs): the exact type id, or null when absent, returned alongside `rest` — the args with
+ * the flag's value token removed, exactly like parseGrepFlag. It mirrors that parser and not
+ * a bare flagValue read because the value token must leave the list: `logs --type --since`
+ * treats "--since" as the type text, not the flag, so the rival-flag and --since scans run
+ * over `rest` and cannot misfire on the pattern. A valueless or empty type fails with the
+ * caller's wording (each view names its own command) — the same error the `--type` gate spec
+ * (typeFlagSpec) reports earlier for the trailing-no-value case. */
+export function parseTypeFlag(args, missingValueError) {
+    const i = args.indexOf("--type");
+    const rest = i >= 0 ? args.filter((_, j) => j !== i + 1) : args;
+    const raw = flagValue(args, "--type");
+    if (raw === null)
+        return { rest, type: null };
+    if (raw === undefined || raw === "")
+        fail(missingValueError);
+    return { rest, type: raw };
+}
 /** Parse a `-n`-style count flag value: a positive integer, or fail with a clear message.
  * Unvalidated, NaN/0/negative limits make readEvents' `slice(-limit)` dump the whole log
  * (or drop leading lines) instead of showing the requested tail. With `max`, the count is
@@ -81,7 +100,7 @@ export function parseCountFlag(flag, raw, max) {
  * `(e.g. …)` example because a bare count flag's `needs a value` reads thin next to the `<n>`
  * the operator typed; `example` is the spelling shown back to them. One home for the two
  * failure messages and the plain-decimal rule, shared by the prompt queue's parser
- * (cli-command-args.ts) and the bug/plan backlog shells (backlog-write.ts), so the rule cannot
+ * (cli-command-args.ts) and the bug/plan backlog shells (backlog-cli.ts), so the rule cannot
  * drift to Number() at one site. */
 export function parsePositionFlag(flag, raw, example) {
     if (raw === undefined)
@@ -238,11 +257,12 @@ export function parseSinceFlag(args, label, maxMs) {
  * catalog alone, which keeps in-process callers (and tests) that have no config working.
  */
 export function parseRoleFlag(args, validIds) {
-    const role = flagValue(args, "--role");
-    if (role === null)
+    const typed = flagValue(args, "--role");
+    if (typed === null)
         return null;
-    if (!role)
+    if (!typed)
         fail(ROLE_VALUE_ERROR);
+    const role = canonicalRoleId(typed);
     const ids = validIds ?? allRoleIds();
     if (!ids.includes(role))
         fail(unknownRoleMessage(role, ids));

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

@@ -1,3 +1,4 @@
+// vocabulary: plain
 /** The free-form-prompt commands' bespoke argument parsers: `tumwater init` and
  * `tumwater prompt`, whose positionals are prompt TEXT rather than a token list. Every
  * shared helper in cli/cli-args.ts assumes flags claim their tokens and rejects whatever is
@@ -20,7 +21,7 @@ import { errorMessage } from "../text/text.js";
  * prefix test — a negative tick number (`tick bugfix -3`) arrives flag-shaped and fails the
  * unknown-arg gate, which is the right answer for a non-positive n anyway. Lives here with
  * the CLI's other argument helpers, shared by cli.ts's tick case and
- * backlog-write.ts's fileAndAnnounce. */
+ * backlog-cli.ts's fileAndAnnounce. */
 export function peelPositionals(args) {
     const positionals = [];
     const rest = [];
@@ -28,6 +29,21 @@ export function peelPositionals(args) {
         (arg.startsWith("-") ? rest : positionals).push(arg);
     return { positionals, rest };
 }
+/** The `history` listing flags that take a separate value token. */
+const HISTORY_LISTING_VALUED_FLAGS = ["-n", "--since", "--grep", "--result", "--role"];
+/** True when `history`'s args are the one-run trail form (`history <role> <n>`, `history
+ * <role> --last`): a token that is neither a flag nor the value of a listing-form valued flag.
+ * A valued flag's value is skipped by position, so `--grep -x` stays a listing. */
+export function historyTrailForm(args) {
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (HISTORY_LISTING_VALUED_FLAGS.includes(arg))
+            i++;
+        else if (!arg.startsWith("-"))
+            return true;
+    }
+    return false;
+}
 /** Fail when any token is not at one of the `claimed` positions — the shared "no extra tokens"
  * check for commands whose positionals are free-form prompt text (init, prompt): with their
  * flags present, every other token would be silently baked into the prompt. Names the first
@@ -206,17 +222,19 @@ const PROMPT_FLAG_SPECS = [
     JSON_FLAG,
     { names: ["--cancel"], value: true, valueName: "<n>" },
     { names: ["--edit"], value: true, valueName: "<n>" },
+    { names: ["--top"], value: true, valueName: "<n>" },
     { names: ["--file"], value: true, valueName: "<path>" },
     { names: ["--at"], value: true, valueName: "<duration>" },
     { names: ["--attach"], value: true, valueName: "<path>" },
 ];
 /** `tumwater prompt` argument handling, following parseInitArgs' pattern. Like init's,
  * positionals are free-form prompt content — but a double-dash token must be a real flag
- * (`--role <id>`, `--list`, `--json`, `--cancel <n>`, `--file <path>`, `--at <duration>`), or
+ * (`--role <id>`, `--list`, `--json`, `--cancel <n>`, `--edit <n>`, `--top <n>`, `--file <path>`,
+ * `--at <duration>`), or
  * it would be baked into the queued prompt (the same class of bug parseInitArgs fixed: today
  * `tumwater prompt --foo text` enqueues "--foo text"). Single-dash positionals remain prompt
- * content. `--list` and `--cancel` are mutually exclusive and may not combine with positional
- * text; `--role` is accepted in every mode and is never
+ * content. `--list`, `--cancel`, `--edit` and `--top` are mutually exclusive and may
+ * not combine with positional text; `--role` is accepted in every mode and is never
  * prompt content. `--at <duration>` (PLANS.md "tumwater prompt --at <duration>") only queues
  * a prompt: it defers delivery — parsed here with parseDurationFlag, riding the enqueue as
  * the queue file's not-before marker — so the read-only and destructive modes refuse it
@@ -231,6 +249,7 @@ export function parsePromptArgs(args) {
     const listFlag = args.indexOf("--list");
     const cancelFlag = args.indexOf("--cancel");
     const editFlag = args.indexOf("--edit");
+    const topFlag = args.indexOf("--top");
     const fileFlag = args.indexOf("--file");
     const atFlag = args.indexOf("--at");
     // --attach is repeatable: every occurrence claims itself and its value token, like --role's
@@ -244,6 +263,12 @@ export function parsePromptArgs(args) {
         fail("--list and --edit are mutually exclusive");
     if (cancelFlag >= 0 && editFlag >= 0)
         fail("--cancel and --edit are mutually exclusive");
+    if (listFlag >= 0 && topFlag >= 0)
+        fail("--list and --top are mutually exclusive");
+    if (cancelFlag >= 0 && topFlag >= 0)
+        fail("--cancel and --top are mutually exclusive");
+    if (editFlag >= 0 && topFlag >= 0)
+        fail("--edit and --top are mutually exclusive");
     const roleFlag = args.indexOf("--role");
     const roleRaw = roleFlag >= 0 ? args[roleFlag + 1] : undefined;
     if (roleFlag >= 0 && (!roleRaw || roleRaw.startsWith("--")))
@@ -259,12 +284,13 @@ export function parsePromptArgs(args) {
     // The queue-only flags --file and --at have nothing to mean in the read-only and destructive
     // modes (--list and --cancel): --file is the file-shaped twin of free-form text (--edit
     // accepts it as its replacement text, so the editFlag test below exempts that one mode), and
-    // a delivery deferral has nothing to mean to a listing or a cancel. --attach is queue/edit-only: --list and --cancel refuse it
-    // by name, while --edit accepts it to append images to the prompt it rewrites (the editFlag
-    // test below exempts that one mode). One home for the mode predicate and the
-    // `<flag> only queues a prompt` wording, so a new mode or queue-only flag is added here.
+    // a delivery deferral has nothing to mean to a listing or a cancel. --attach is queue/edit-only:
+    // --list and --cancel refuse it by name, while --edit accepts it to append images to the
+    // prompt it rewrites (the editFlag test below exempts that one mode). One home for the mode
+    // predicate and the `<flag> only queues a prompt` wording, so a new mode or queue-only flag
+    // is added here.
     const refuseQueueOnlyFlag = (flag, present) => {
-        if (present && (listFlag >= 0 || cancelFlag >= 0 || editFlag >= 0))
+        if (present && (listFlag >= 0 || cancelFlag >= 0 || editFlag >= 0 || topFlag >= 0))
             fail(`${flag} only queues a prompt`);
     };
     refuseQueueOnlyFlag("--file", fileFlag >= 0 && editFlag < 0);
@@ -307,7 +333,7 @@ export function parsePromptArgs(args) {
         // claims. Tokens preceding --edit (other than a claimed flag) would be silently dropped —
         // a mistyped command would edit prompt N with only the trailing fragment — so they are
         // refused here by the same stray-argument wording the sibling modes use; tokens after the
-        // position are the replacement text, minus any claimed attach pair.
+        // position are the replacement text, minus any claimed attach pair (none: edit in $EDITOR).
         const fileClaim = fileFlag >= 0 ? [fileFlag, fileFlag + 1] : [];
         for (let i = 0; i < editFlag; i++) {
             if (roleClaim.includes(i) || attachClaims.includes(i) || fileClaim.includes(i))
@@ -328,9 +354,15 @@ export function parsePromptArgs(args) {
             textTokens.push(args[i]);
         }
         const text = textTokens.join(" ").trim();
-        if (!text)
-            fail('edit text required — usage: tumwater prompt --edit <n> "<new text>" (add --role <id> to aim it at one loop)');
-        return { mode: "edit", role, position: n, text, attachPaths };
+        // No text and no --file: the caller opens the prompt's current body in the editor.
+        return { mode: "edit", role, position: n, text: text === "" ? null : text, attachPaths };
+    }
+    if (topFlag >= 0) {
+        const n = parsePositionFlag("--top", args[topFlag + 1], "--top 2");
+        // The position is the only token --top may carry; anything else alongside it would be
+        // prompt text, and this mode has none.
+        failStrayArg(args, "with --top there is no prompt text", topFlag, topFlag + 1, ...roleClaim);
+        return { mode: "top", role, position: n };
     }
     if (fileFlag >= 0) {
         // The file is the prompt: read it whole (a path of `-` reads stdin, so a pipe or heredoc
@@ -353,6 +385,6 @@ export function parsePromptArgs(args) {
     // Name the fix, like the sibling operator commands' usage errors (bug/plan carry their
     // BUG_USAGE/PLAN_USAGE lines): "prompt text required" alone never said what to type.
     if (!text)
-        fail('prompt text required — usage: tumwater prompt "<text>" (add --role <id> to aim it at one loop)');
+        fail('prompt text required — usage: tumwater prompt "<text>" (add --role <id> to aim it at one role)');
     return { mode: "enqueue", role, text, atDelayMs, attachPaths: attachPaths };
 }

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

@@ -0,0 +1,64 @@
+// Open text in the operator's editor, the way `git commit` and `crontab -e` do.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fail } from "./cli-output.js";
+/** Signal number → name, for the shell's 128+n convention: a shell that does not re-raise a
+ * signal-killed child (dash on Linux) exits with 128+signo, so node sees an exit status where
+ * bash on macOS lets it see the signal. Keyed by number, so a later alias (SIGABRT over SIGIOT)
+ * wins; any name is fine for the message. */
+const SIGNAL_NAMES = Object.fromEntries(Object.entries(os.constants.signals).map(([name, n]) => [n, name]));
+/** How an editor run ended, naming a signal even when the shell folded it into 128+n. A null
+ * status (spawn error, signal) and a plain non-zero status fall through unchanged. */
+function exitReason(r) {
+    if (r.error)
+        return r.error.message;
+    if (r.signal)
+        return `signal ${r.signal}`;
+    // The editor value runs through `sh -c`, and sh reports a command it could not launch as
+    // 127 (not found) or 126 (found but not executable) — most often the $EDITOR/$VISUAL value
+    // itself is a typo or a path to a binary that is not installed. A bare "status 127" tells
+    // the user only that sh refused, so name the likely cause and the env var to fix, the way
+    // the no-editor arm does. Occasionally the 127/126 came from inside the editor's own shell
+    // script rather than the editor command; an occasionally-missed guess still beats a bare
+    // status code that never suggests anything.
+    if (r.status === 127)
+        return "the editor command was not found (exit 127) — check $EDITOR/$VISUAL";
+    if (r.status === 126)
+        return "the editor command was found but not executable (exit 126) — check $EDITOR/$VISUAL";
+    const signalled = r.status !== null && r.status > 128 ? SIGNAL_NAMES[r.status - 128] : undefined;
+    return signalled ? `signal ${signalled}` : `status ${r.status}`;
+}
+/** Write `initial` to a temp file named `fileName`, run `$VISUAL` (else `$EDITOR`) on it, and
+ * return the saved text. The editor value runs through `sh -c` (git's convention) so one with
+ * arguments, like `code -w`, works. There is no `vi` fallback: a script without a TTY must fail
+ * rather than hang. A missing editor, a spawn error, a non-zero exit, or a signal fails the
+ * command (`fallback` ends the no-editor message); the temp dir is removed before the failure
+ * exits. */
+export function editInEditor(initial, fileName, fallback = "pass the new text or --file <path>") {
+    const editor = (process.env.VISUAL || process.env.EDITOR || "").trim();
+    if (editor === "")
+        fail(`no editor: set $VISUAL or $EDITOR, or ${fallback}`);
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "tumwater-edit-"));
+    let saved;
+    let failure;
+    try {
+        const file = path.join(dir, fileName);
+        fs.writeFileSync(file, `${initial}\n`);
+        const r = spawnSync("sh", ["-c", `${editor} "$1"`, "sh", file], { stdio: "inherit" });
+        if (r.error || r.status !== 0) {
+            failure = `editor exited with ${exitReason(r)}; nothing changed`;
+        }
+        else {
+            saved = fs.readFileSync(file, "utf8");
+        }
+    }
+    finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+    // fail() exits the process, which would skip the finally above, so it runs after cleanup.
+    if (failure !== undefined)
+        fail(failure);
+    return saved;
+}

package/dist/src/cli/cli-flag-specs.js

@@ -127,15 +127,22 @@ export const PAUSE_FOR_OVERFLOW_HINT = "for a longer or standing pause run bare
  * `pause --for` honors, the same not-initialized-masking rationale durationFlagSpec records).
  * missingValue names the command for a trailing `--in` (`wake --in needs a value`), the same
  * command-named pattern durationFlagSpec and sinceFlagSpec follow. */
-export const WAKE_IN_FLAG = {
-    names: ["--in"],
-    value: true,
-    valueName: "<duration>",
-    missingValue: "wake --in needs a value",
-    validate: (value) => {
-        failOverDurationCap("wake --in", parseDurationFlag("wake --in", value), PAUSE_FOR_MAX_MS);
-    },
-};
+function inFlagSpec(command) {
+    return {
+        names: ["--in"],
+        value: true,
+        valueName: "<duration>",
+        missingValue: `${command} --in needs a value`,
+        validate: (value) => {
+            failOverDurationCap(`${command} --in`, parseDurationFlag(`${command} --in`, value), PAUSE_FOR_MAX_MS);
+        },
+    };
+}
+export const WAKE_IN_FLAG = inFlagSpec("wake");
+/** `tumwater stop --in <duration>`: the scheduled graceful stop, same shape and cap as wake's. */
+export const STOP_IN_FLAG = inFlagSpec("stop");
+/** `tumwater stop --cancel`: drop the scheduled stop. */
+export const STOP_CANCEL_FLAG = { names: ["--cancel"] };
 /** The `--cancel` flag spec for `tumwater wake --cancel`: drop pending scheduled wakes. */
 export const WAKE_CANCEL_FLAG = { names: ["--cancel"] };
 /** `wake --list`: print the pending scheduled wakes instead of writing one. Takes no value. */
@@ -144,7 +151,7 @@ export const WAKE_LIST_FLAG = { names: ["--list"] };
  * one definition of the flag's spelling and value shape, beside ROLE_FLAG and durationFlagSpec,
  * so the gate's accepted vocabulary cannot drift from cmdPause's parse. The missing-value
  * wording names its only command (the GREP_VALUE_ERROR idiom — each command's parser names
- * itself); the 200-char cap stays in pauseFleet beside the marker it bounds, and per-role
+ * itself); the 200-char cap stays in pauseTeam beside the marker it bounds, and per-role
  * pauses carry no reason, so cmdPause rejects the `--role` + `--reason` combination. Exported
  * so the gate and the command body share one definition of what `pause` accepts. Its
  * missing-value wording is REASON_VALUE_ERROR, exported so cmdPause's own guard reads it too. */
@@ -195,11 +202,29 @@ export const N_FLAG = {
  * siblings it needs neither a factory nor a missing-value error — so the constant is the
  * whole spec, and the render-vs-JSON switch stays in each command body beside its render. */
 export const JSON_FLAG = { names: ["--json"] };
+/** The `--ready` flag spec, accepted by `backlog`: keep only the entries no hold keeps from
+ * being picked. Value-less, like STAT_FLAG. */
+export const READY_FLAG = { names: ["--ready"] };
+/** Force re-probing of every claimed image-input model in `tumwater doctor` (part 2/5),
+ * bypassing the 7-day cache: `--reprobe` (a value-less flag like JSON_FLAG). */
+export const REPROBE_FLAG = { names: ["--reprobe"] };
+/** The `--problems` flag spec, accepted by `doctor`: print only the warn and fail rows. Value-less,
+ * like REPROBE_FLAG. */
+export const PROBLEMS_FLAG = { names: ["--problems"] };
+/** The `--stat` flag spec, accepted by `diff --role`: print each patch as its `git diff --stat`
+ * summary. Value-less, like JSON_FLAG. */
+export const STAT_FLAG = { names: ["--stat"] };
+/** The `--summary` flag spec, accepted by `history`: tally each loop's tick outcomes instead of
+ * printing the rows. Value-less, like STAT_FLAG. */
+export const SUMMARY_FLAG = { names: ["--summary"] };
+/** The `--count` flag spec, accepted by `logs`: tally the selected window's event types
+ * instead of printing the rows. Value-less, like SUMMARY_FLAG. */
+export const COUNT_FLAG = { names: ["--count"] };
 /** The `--force` flag spec, accepted by `retire` (the only override-the-rails command): one
  * definition of the flag's spelling beside ROLE_FLAG and JSON_FLAG, so the gate's accepted
  * vocabulary cannot drift from the command body's `args.includes("--force")`. */
 export const FORCE_FLAG = { names: ["--force"] };
-/** The `--dry-run` flag spec: preview a reclaim pass without deleting anything. Beside
+/** The `--dry-run` flag spec: preview a reclaim pass or a retire without changing anything. Beside
  * FORCE_FLAG so its spelling lives with the other boolean flags the gate admits. */
 export const DRY_RUN_FLAG = { names: ["--dry-run"] };
 /** The `--last` flag spec for `tumwater tick <role> --last`: one definition of the flag's
@@ -216,6 +241,13 @@ export const LAST_FLAG = { names: ["--last"] };
 export function grepFlagSpec(missingValue) {
     return { names: ["--grep"], value: true, valueName: "<text>", missingValue };
 }
+/** The `--type <event type>` flag spec of `logs`' exact-type filter, beside grepFlagSpec: one
+ * definition of the flag's spelling and value shape, so the gate's accepted vocabulary cannot
+ * drift. The missing-value wording names the command (each names its own command), so the
+ * spec is a factory taking it — the same string parseTypeFlag fails with in the command body. */
+export function typeFlagSpec(missingValue) {
+    return { names: ["--type"], value: true, valueName: "<event type>", missingValue };
+}
 /** The `--result <class>` flag spec of `history`'s outcome filter, beside grepFlagSpec: one
  * definition of the flag's spelling and value shape, so the gate's accepted vocabulary cannot
  * drift. The missing-value wording names the command, so the spec is a factory taking it — the
@@ -228,23 +260,29 @@ export function resultFlagSpec(missingValue) {
  * parseBranchFlag), `--once` (one full round of ticks, then exit), `--role <id>`
  * (scope a --once round to one loop, parsed by parseRoleFlag), and `--gui` (also serve the
  * browser dashboard on its defaults; port/token selection stays on `tumwater gui`). Exported
- * so the caller's rejectUnknownArgs check and its tests share one definition of what `run`
- * accepts — before this vocabulary existed, run parsed --branch and silently ignored
- * every other flag, so a typo'd option ran the daemon with default behavior. */
+ * so the caller's rejectUnknownArgs check and its tests share one definition of what `start`
+ * (and its hidden alias `run`) accepts — before this vocabulary existed, run parsed --branch
+ * and silently ignored every other flag, so a typo'd option ran the daemon with default
+ * behavior. */
 export const RUN_FLAG_SPECS = [
     { names: ["--branch"], value: true, valueName: "<name>", missingValue: BRANCH_VALUE_ERROR },
     { names: ["--once"] },
-    // `run --gui` is the one-command form of the dashboard: it boots the fleet and serves the
+    // `run --gui` is the one-command form of the dashboard: it boots the team and serves the
     // browser dashboard at its defaults, loopback on port 7180. The dashboard's own --port,
     // --all-interfaces, and --token stay on `tumwater gui`; widening them here would mean two
     // flag vocabularies to keep in step. `run --gui --once` is refused in cmdRun beside the
     // timer it arms.
     { names: ["--gui"] },
+    // `run --tui` is the one-command form of the observer TUI: it boots the team and hosts the
+    // same in-terminal TUI `tumwater tui` attaches from another terminal. Its flag vocabulary
+    // stays at run's (`tumwater tui` takes no flags); `run --tui --once` is refused in cmdRun
+    // beside the `--gui` rival.
+    { names: ["--tui"] },
     // `run --for <duration>` (the windowed run): the same spec `pause --for` passes, so the
     // gate's accepted vocabulary and parseDurationFlag's error wording cannot drift; the
     // 90-day cap is the spec's own validate (shared with pause), and the --once rival rule
     // stays in cmdRun beside the timer it arms.
-    durationFlagSpec("run --for"),
+    durationFlagSpec("start --for"),
     ROLE_FLAG,
 ];
 /** The one refusal for a trailing `gui --token` with no value, phrased for what the

package/dist/src/cli/cli-marker-commands.js

@@ -1,6 +1,6 @@
 import { DRY_RUN_FLAG, JSON_FLAG, durationFlagSpec, PAUSE_FOR_OVERFLOW_HINT, REASON_FLAG, WAKE_CANCEL_FLAG, WAKE_LIST_FLAG, WAKE_IN_FLAG, rejectUnknownArgs, ROLE_FLAG, } from "./cli-flag-specs.js";
 import { requireReadyRepo } from "./cli-repo-gate.js";
-import { cmdAbort, cmdPause, cmdReclaim, cmdResetCounters, cmdResume, cmdWake } from "../operator/operator-commands.js";
+import { cmdAbort, cmdPause, cmdReclaim, cmdResetCounters, cmdRestart, cmdResume, cmdWake } from "../operator/operator-commands.js";
 /** The CLI command layer of each marker command, keyed by its CLI name (the command bodies
  * live in operator/operator-commands.ts, the shared marker-writing cores in
  * operator/operator-intent.ts). One map so a new marker command registers its core beside its
@@ -12,20 +12,22 @@ const markerCommandCores = {
     pause: cmdPause,
     resume: cmdResume,
     reclaim: cmdReclaim,
+    restart: cmdRestart,
 };
-/** The shared shape of the six marker commands (reset-counters, wake, abort, pause, resume,
- * reclaim): reject unknown args against each command's flag set, gate on a ready repo, then
- * dispatch to its operator-commands core. One copy of the guard sequence so the six cannot
- * drift on validation order or gating. Lives beside operator/operator-commands.ts's importers
+/** The shared shape of the seven marker commands (reset-counters, wake, abort, pause,
+ * resume, reclaim, restart): reject unknown args against each command's flag set, gate on a
+ * ready repo, then dispatch to its operator-commands core. One copy of the guard sequence so
+ * the seven cannot drift on validation order or gating. Lives beside
+ * operator/operator-commands.ts's importers
  * as the marker commands' CLI layer, with cli.ts's main() dispatch casting to MarkerCommand
  * here. */
 export async function runMarkerCommand(root, command, args) {
     // `pause` alone accepts `--for <duration>` (the timed pause) and `--reason <text>` (the
-    // operator pause's why); `wake` alone accepts `--in <duration>` (the scheduled wake) and `--cancel` (drop the pending
-    // scheduled wakes), `--list` (show them), and `--json` (with --list);
-    // `reclaim` alone accepts `--dry-run`; the other marker commands keep the plain --role
-    // vocabulary, so a stray --for, --reason, --in, --cancel, or --dry-run fails fast instead of being
-    // silently ignored.
+    // operator pause's why); `wake` alone accepts `--in <duration>` (the scheduled wake) and
+    // `--cancel` (drop the pending scheduled wakes), `--list` (show them), and `--json`
+    // (with --list); `reclaim` alone accepts `--dry-run`; the other marker commands keep the
+    // plain --role vocabulary, so a stray --for, --reason, --in, --cancel, or --dry-run fails
+    // fast instead of being silently ignored.
     const perCommandFlags = {
         "reset-counters": [ROLE_FLAG],
         wake: [ROLE_FLAG, WAKE_IN_FLAG, WAKE_CANCEL_FLAG, WAKE_LIST_FLAG, JSON_FLAG],
@@ -37,6 +39,7 @@ export async function runMarkerCommand(root, command, args) {
         ],
         resume: [ROLE_FLAG],
         reclaim: [DRY_RUN_FLAG],
+        restart: [],
     };
     rejectUnknownArgs(command, args, perCommandFlags[command] ?? [ROLE_FLAG]);
     await requireReadyRepo(root);

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

@@ -20,6 +20,15 @@ function writeLine(text) {
 export function say(text) {
     writeLine(stripTerminalControls(text));
 }
+/** Tell the operator, on stderr, that an operator backlog write landed in the working tree but
+ * was not committed to main (commitOperatorBacklogEdit returned false: the primary is off the
+ * base branch, or git failed). The write itself succeeded, so this warns instead of failing;
+ * a no-op when the commit landed. */
+export function warnIfUncommitted(committed, file) {
+    if (committed)
+        return;
+    process.stderr.write(`warning: ${file} was written but not committed to main — commit it before the next fast-forward\n`);
+}
 /** Print a value as pretty-printed (2-space) JSON — the `--json` output every CLI query
  * command (status, history, report, config) renders through: the pretty-print spelling
  * (indent 2) decided once so the machine-readable surface cannot drift per command. Writes