tumwater 0.1.2 → 0.1.3

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

@@ -9,18 +9,22 @@ import { fail, say } from "./cli-output.js";
 import { durationLabel, failOverDurationCap, failRivalShapes, flagValue, parseBranchFlag, parseDurationFlag, parseRoleFlag, } from "./cli-args.js";
 import { PAUSE_FOR_MAX_MS } from "../operator/operator-intent.js";
 import { parseInitArgs } from "./cli-command-args.js";
-import { isFleetPaused, pausedRoles } from "../fleet/fleet-state.js";
+import { cancelScheduledStop, isFleetPaused, pausedRoles, scheduledStopAt } from "../fleet/fleet-state.js";
 import { orchestratorAlive, readOrchestratorInfo } from "../fleet/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 { notifyFleetDown } from "../events/notify.js";
 import { formatEvent } from "../events/event-format.js";
 import { RESTART_EXIT_CODE } from "../redeploy/redeploy-policy.js";
 import { loadLoopState, stateSkipReason } from "../loop/loop-state.js";
 import { plural } from "../text/phrases.js";
 import { shortSha } from "../text/format.js";
+import { readTickRowsSince, summarizeTickRows } from "../history/history-data.js";
+import { renderSummary } from "../history/history.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. */
@@ -73,8 +77,9 @@ export async function cmdInit(root, args) {
  * `--for <duration>` keeps the daemon shape (redeployer, LaunchServicesWatch, supervisor hand-off
  * all stay) but arms a deadline: at the deadline the same graceful stop a Ctrl+C runs fires, and
  * the process exits after printing the summary. A mid-run self-redeploy hands the same args
- * (including `--for`) to the supervisor's next child, so the deadline restarts in the new
- * generation — the window is per-generation, stated here rather than coded around. */
+ * (including `--for`) to the supervisor's next child, and the supervisor hands every generation
+ * the same window start (RUN_WINDOW_START_ENV), so the deadline and the summary span the whole
+ * window; only the final exit prints the summary. */
 export async function cmdRun(root, args) {
     // The one function the self-redeploy asks before swapping onto a successor and the supervisor
     // asks when a generation dies, so the three cannot disagree about what boots. The supervisor
@@ -114,11 +119,13 @@ export async function cmdRun(root, args) {
     // compile, and the supervisor/redeploy/launch-services pieces ride beside it. Loading them
     // dynamically, after the fail-fast gates above, keeps every other command's spawn — and
     // `run`'s fail-fast paths — off that cost (see cli.ts's matching lazy dispatch).
-    const { SUPERVISED_ENV, startParentDeathWatch, expectedSupervisorPid } = await import("../process/supervisor.js");
+    const { SUPERVISED_ENV, RUN_WINDOW_START_ENV, ONCE_FAILED_EXIT_CODE, startParentDeathWatch, expectedSupervisorPid } = await import("../process/supervisor.js");
     if (!process.env[SUPERVISED_ENV]) {
         // `args` are the flags after the command token — forward them so the child generation
         // targets the same branch (or whatever else the invocation named).
-        await superviseRunCommand(root, args, branchArg);
+        // A stop marker left by a fleet that died before its deadline must not stop this run.
+        cancelScheduledStop(root);
+        await superviseRunCommand(root, args, branchArg, forMs);
         return;
     }
     const controller = new AbortController();
@@ -135,10 +142,15 @@ export async function cmdRun(root, args) {
     // A windowed run's deadline arms the same graceful stop a Ctrl+C runs — the identical `stop`
     // closure, so the drain path is one code path either way. clearTimeout in the finally below
     // retracts it when the run ends first (an early Ctrl+C), so no stray timer outlives the run.
-    const deadlineTimer = forMs !== null ? armDeadlineTimer(forMs, () => {
+    const windowStart = inheritedWindowStart(process.env[RUN_WINDOW_START_ENV], Date.now());
+    const deadlineTimer = forMs !== null ? armDeadlineTimer(Math.max(0, windowStart + forMs - Date.now()), () => {
         say("deadline reached — stopping");
         stop();
     }) : null;
+    const scheduledStopWatch = armScheduledStopWatch(root, () => {
+        if (!stopping)
+            stop(); // A drain already under way must not be turned into a force-kill.
+    });
     // A supervisor that dies without forwarding — SIGKILL (the OOM killer, `kill -9`) cannot be
     // trapped or forwarded, and an uncaught supervisor crash forwards nothing either — leaves this
     // generation reparented and ticking the fleet unattended. The parent-death watch polls for the
@@ -188,20 +200,56 @@ export async function cmdRun(root, args) {
             launchServicesWatch,
             once,
             roleFilter: roleFilter ?? undefined,
+            stopsAt: forMs !== null ? windowStart + forMs : undefined,
         });
     }
     finally {
         if (deadlineTimer)
             deadlineTimer.clear();
+        scheduledStopWatch.clear();
         unsubscribe();
     }
-    if (once || forMs !== null)
+    if (once)
         say(onceSummary(root, roles, ticksBefore, exit.settled, exit.ticksRun));
+    else if (forMs !== null && !exit.restart) {
+        const { rows, covered } = readTickRowsSince(root, Date.now() - windowStart, null);
+        say(windowSummary(durationLabel(forMs), summarizeTickRows(rows), covered));
+    }
+    if (once) {
+        const failures = onceFailures(root, roles, ticksBefore, exit.ticksRun);
+        if (failures.length > 0) {
+            say(`once: failed — ${failures.map((f) => `${f.role} ${f.result}`).join(", ")}`);
+            process.exitCode = ONCE_FAILED_EXIT_CODE;
+        }
+    }
     // A self-redeploy swapped the new build into dist/: hand the terminal back to the supervisor,
     // which respawns this same script — now the new code — as the next generation.
     if (exit.restart)
         process.exit(RESTART_EXIT_CODE);
 }
+/** The window start a generation adopts: the supervisor's RUN_WINDOW_START_ENV mark when it is a
+ * positive integer no later than `now`, else `now` (absent, malformed, or in the future). */
+export function inheritedWindowStart(raw, now) {
+    const n = Number(raw);
+    return raw !== undefined && Number.isInteger(n) && n > 0 && n <= now ? n : now;
+}
+/** The `run --for` exit summary: a window line, then the `history --summary` table for the ticks
+ * that ended since the window opened — every tick counted once by its outcome class. Only the
+ * final exit prints it; a mid-window self-redeploy hands off silently and the next generation
+ * inherits the window start, so the table spans every generation. */
+export function windowSummary(label, summary, covered) {
+    const { total } = summary;
+    const lines = [
+        total.ticks === 0
+            ? `for ${label}: 0 ticks — nothing ran`
+            : `for ${label}: ${plural(total.ticks, "tick")} — ${total.changes} changes, ${total.none} none, ${total.problems} problems`,
+    ];
+    if (total.ticks > 0)
+        lines.push(renderSummary(summary));
+    if (!covered)
+        lines.push(SPARSE_WINDOW_NOTE);
+    return lines.join("\n");
+}
 /** Arm the windowed run's deadline timer: the one home of the arming `cmdRun` does for
  * `run --for <duration>`. A duration over setTimeout's own 32-bit signed ceiling
  * (2_147_483_647 ms ≈ 24.8 days) is clamped by Node to 1ms with a TimeoutOverflowWarning, so
@@ -228,6 +276,23 @@ export function armDeadlineTimer(ms, onFired) {
     arm(ms);
     return { clear: () => clearTimeout(timer) };
 }
+const SCHEDULED_STOP_POLL_MS = 5000;
+/** Poll for a `tumwater stop --in` marker: once its `until` has passed, consume the marker,
+ * stop polling, and call `onStop` (cmdRun's Ctrl+C closure) exactly once. The interval is
+ * unref'd; clear() retracts it. Exported for tests. */
+export function armScheduledStopWatch(root, onStop) {
+    const timer = setInterval(() => {
+        const at = scheduledStopAt(root);
+        if (at === undefined || at > Date.now())
+            return;
+        clearInterval(timer);
+        cancelScheduledStop(root);
+        say("scheduled stop reached — stopping");
+        onStop();
+    }, SCHEDULED_STOP_POLL_MS);
+    timer.unref();
+    return { clear: () => clearInterval(timer) };
+}
 /** Parse `run --for <duration>` (the windowed run): the parsed duration in milliseconds, or null
  * when the flag is absent. The two body-level rules fail fast, before any repo gate or boot: the
  * value must parse as a duration (parseDurationFlag's own wording, the same messages the
@@ -245,6 +310,32 @@ export function parseRunWindow(args, once) {
     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
+ * land: 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.ticks - (ticksBefore.get(role) ?? 0);
+}
+/** The roles that ticked this round and whose last result is in ONCE_FAILURE_RESULTS. */
+export function onceFailures(root, roles, ticksBefore, ticksRun) {
+    const out = [];
+    const extra = ticksRun ? [...ticksRun.keys()].filter((r) => !roles.includes(r)) : [];
+    for (const role of [...roles, ...extra]) {
+        const s = loadLoopState(root, role);
+        if (ticksThisRound(s, role, ticksBefore, ticksRun) > 0 && s.lastResult && ONCE_FAILURE_RESULTS.has(s.lastResult)) {
+            out.push({ role, result: s.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
@@ -271,7 +362,7 @@ export function onceSummary(root, roles, ticksBefore, settled, ticksRun) {
     const extra = ticksRun ? [...ticksRun.keys()].filter((r) => !roles.includes(r)) : [];
     for (const role of [...roles, ...extra]) {
         const s = loadLoopState(root, role);
-        const ran = ticksRun ? (ticksRun.get(role) ?? 0) : s.ticks - (ticksBefore.get(role) ?? 0);
+        const ran = ticksThisRound(s, role, ticksBefore, ticksRun);
         if (ran > 0) {
             ticks += ran;
             const key = s.lastResult ?? "no_change";
@@ -326,11 +417,12 @@ async function superviseDashboard(signal) {
  * supervisor's own exit code is whatever the last generation's was. A fleet that goes down without
  * the operator asking leaves a `supervisor_exit` event behind (BUGS.md 2026-09-23): the dead
  * generation's stderr reached only this terminal, which nobody may be watching. */
-async function superviseRunCommand(root, runArgs, branchArg) {
+async function superviseRunCommand(root, runArgs, branchArg, forMs) {
     // The supervisor machinery loads lazily, like cmdRun's orchestrator import above: a command
     // that never boots the fleet never compiles it.
-    const { fleetDownEvent, spawnRunChild, superviseRun } = await import("../process/supervisor.js");
+    const { RUN_WINDOW_START_ENV, fleetDownEvent, spawnRunChild, superviseRun } = await import("../process/supervisor.js");
     const plan = guiChildPlan(runArgs);
+    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
@@ -347,7 +439,7 @@ async function superviseRunCommand(root, runArgs, branchArg) {
     });
     const gui = plan.spawnGui ? superviseDashboard(guiController.signal) : Promise.resolve();
     const code = await superviseRun({
-        spawnChild: (signal) => spawnRunChild(signal, plan.orchestratorArgs),
+        spawnChild: (signal) => spawnRunChild(signal, plan.orchestratorArgs, windowEnv),
         stopping: () => stopping,
         onRespawn: (generation) => say(`\nrestarting on the new build (generation ${generation})\n`),
         onCrashLoop: () => process.stderr.write("tumwater: the harness restarted itself too many times in a minute — giving up\n"),
@@ -356,7 +448,8 @@ async function superviseRunCommand(root, runArgs, branchArg) {
         // tumwater.json gone). A crash loop's generations all asked for restarts, so the gate
         // has nothing to say about it.
         onFleetDown: async (down) => {
-            logEvent(root, fleetDownEvent(down, down.crashLoop ? null : await runStartupProblem(root, branchArg)));
+            const event = logEvent(root, fleetDownEvent(down, down.crashLoop ? null : await runStartupProblem(root, branchArg)));
+            notifyFleetDown(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

package/dist/src/cli/completion.js

@@ -0,0 +1,149 @@
+/** Shell completion derived from the help text. The spec is parsed from the same HELP stanzas
+ * `tumwater help <command>` and the unknown-command suggestion use, so a new command or flag
+ * completes the moment it gains a help stanza and can never drift from the listing. */
+import { customLoopNames, knownRoleIds, loadConfig } from "../config/config.js";
+import { AGENT_IDS, AGENT_KEYS, MODEL_TIERS, ROLE_ENTRY_KEYS, TOP_LEVEL_KEYS } from "../config/config-schema.js";
+import { DOTTED_MAP_KEYS } from "../config/config-write.js";
+import { HISTORY_RESULT_CLASSES } from "../history/history-data.js";
+import { templateIds } from "../init/init-templates.js";
+import { allRoleIds } from "../roles/roles.js";
+import { HELP, helpStanzas } from "./help.js";
+export const SUPPORTED_SHELLS = ["bash", "zsh"];
+/** The completable words of a stanza's usage part: the text after `tumwater <command>` up to the
+ * description column (two or more spaces). Bare lowercase words count inside `[...]` and as the
+ * leading run directly after the command; outside brackets the first other token ends the run, so
+ * a single-space description (`role <id> --clear-notes Clear that notebook`) adds nothing. */
+function usageWords(firstLine, command) {
+    const rest = firstLine.replace(new RegExp(`^ {2}tumwater ${command}`), "");
+    // Usage arguments follow the command after a single space; two or more spaces start the description.
+    const usage = /^ {2,}/.test(rest) ? "" : (rest.split(/ {2,}/)[0] ?? "");
+    const words = [];
+    let depth = 0;
+    let leading = true;
+    for (const token of usage.split(/\s+/).filter(Boolean)) {
+        const bare = token.replace(/[[\]|]/g, "");
+        const isWord = /^[a-z][a-z-]*$/.test(bare);
+        if (isWord && (depth > 0 || token.startsWith("[") || leading))
+            words.push(bare);
+        else if (depth === 0 && !token.startsWith("[") && bare !== "")
+            leading = false;
+        for (const ch of token)
+            depth += ch === "[" ? 1 : ch === "]" ? -1 : 0;
+    }
+    return words;
+}
+export function completionSpec(help = HELP) {
+    const stanzas = helpStanzas(help);
+    const commands = [...new Set(stanzas.map((s) => s.command))];
+    const subcommands = {};
+    const flags = {};
+    for (const command of commands) {
+        const own = stanzas.filter((s) => s.command === command);
+        const flagSet = new Set(["--help"]);
+        const subs = new Set();
+        for (const stanza of own) {
+            for (const match of stanza.text.matchAll(/--[a-z][a-z-]*/g))
+                flagSet.add(match[0]);
+            for (const word of usageWords(stanza.text.split("\n")[0] ?? "", command))
+                subs.add(word);
+        }
+        flags[command] = [...flagSet].sort();
+        subcommands[command] = command === "help" ? commands : [...subs];
+    }
+    return { commands, subcommands, flags };
+}
+/** The ids `--role` completes: this repo's loop ids, or the built-in catalog when tumwater.json is
+ * unreadable (a broken config must not write errors into the operator's prompt). */
+export function completionRoleIds(root) {
+    try {
+        return knownRoleIds(loadConfig(root));
+    }
+    catch {
+        return allRoleIds();
+    }
+}
+/** The keys `config get|set|unset` complete: every form parseConfigKey accepts, with the role-scoped
+ * keys of this repo's base roles and custom loops (not instance ids like `feature-2`). A broken
+ * tumwater.json falls back to the built-in catalog rather than writing errors into the prompt. */
+export function completionConfigKeys(root) {
+    let roleIds;
+    try {
+        roleIds = [...allRoleIds(), ...customLoopNames(loadConfig(root))];
+    }
+    catch {
+        roleIds = allRoleIds();
+    }
+    const keys = [
+        ...TOP_LEVEL_KEYS,
+        ...MODEL_TIERS.map((tier) => `model.${tier}`),
+        ...AGENT_IDS.flatMap((id) => AGENT_KEYS.map((field) => `agents.${id}.${field}`)),
+        ...DOTTED_MAP_KEYS.flatMap((map) => roleIds.map((id) => `${map}.${id}`)),
+        ...roleIds.flatMap((id) => ROLE_ENTRY_KEYS.map((field) => `roles.${id}.${field}`)),
+    ];
+    return [...new Set(keys)];
+}
+/** Flags whose value is a file path: completion offers file names after them. */
+const PATH_FLAGS = ["--file", "--attach", "--notes-file"];
+function bashScript(help) {
+    const spec = completionSpec(help);
+    const arms = spec.commands.map((command) => {
+        const subs = spec.subcommands[command] ?? [];
+        const flags = spec.flags[command] ?? [];
+        return [
+            `    ${command})`,
+            `      if [[ "$cur" == -* ]]; then`,
+            `        COMPREPLY=( $(compgen -W "${flags.join(" ")}" -- "$cur") )`,
+            ...(subs.length > 0
+                ? [
+                    `      elif [ "$COMP_CWORD" -eq 2 ]; then`,
+                    `        COMPREPLY=( $(compgen -W "${subs.join(" ")}" -- "$cur") )`,
+                ]
+                : []),
+            `      fi`,
+            `      ;;`,
+        ].join("\n");
+    });
+    return [
+        `# tumwater completion (generated from \`tumwater help\`)`,
+        `_tumwater() {`,
+        `  local cur="\${COMP_WORDS[COMP_CWORD]}"`,
+        `  local prev="\${COMP_WORDS[COMP_CWORD-1]}"`,
+        `  COMPREPLY=()`,
+        `  if [ "$prev" = "--role" ] || { [ "$COMP_CWORD" -eq 2 ] && [[ "\${COMP_WORDS[1]}" == role || "\${COMP_WORDS[1]}" == tick ]] && [[ "$cur" != -* ]]; }; then`,
+        `    COMPREPLY=( $(compgen -W "$(tumwater completion --roles 2>/dev/null)" -- "$cur") )`,
+        `    return 0`,
+        `  fi`,
+        `  case "$prev" in ${PATH_FLAGS.join("|")})`,
+        `    COMPREPLY=( $(compgen -f -- "$cur") )`,
+        `    return 0`,
+        `    ;;`,
+        `  esac`,
+        `  if [ "$prev" = "--template" ]; then`,
+        `    COMPREPLY=( $(compgen -W "${templateIds().join(" ")}" -- "$cur") )`,
+        `    return 0`,
+        `  fi`,
+        `  if [ "$prev" = "--result" ]; then`,
+        `    COMPREPLY=( $(compgen -W "${HISTORY_RESULT_CLASSES.join(" ")}" -- "$cur") )`,
+        `    return 0`,
+        `  fi`,
+        `  if [ "$COMP_CWORD" -eq 3 ] && [ "\${COMP_WORDS[1]}" = config ] && [[ "\${COMP_WORDS[2]}" == get || "\${COMP_WORDS[2]}" == set || "\${COMP_WORDS[2]}" == unset ]] && [[ "$cur" != -* ]]; then`,
+        `    COMPREPLY=( $(compgen -W "$(tumwater completion --config-keys 2>/dev/null)" -- "$cur") )`,
+        `    return 0`,
+        `  fi`,
+        `  if [ "$COMP_CWORD" -eq 1 ]; then`,
+        `    COMPREPLY=( $(compgen -W "${spec.commands.join(" ")}" -- "$cur") )`,
+        `    return 0`,
+        `  fi`,
+        `  case "\${COMP_WORDS[1]}" in`,
+        ...arms,
+        `  esac`,
+        `  return 0`,
+        `}`,
+        `complete -F _tumwater tumwater`,
+        ``,
+    ].join("\n");
+}
+export function completionScript(shell, help = HELP) {
+    const bash = bashScript(help);
+    return shell === "zsh" ? `autoload -U +X bashcompinit && bashcompinit\n${bash}` : bash;
+}

package/dist/src/cli/help.js

@@ -15,8 +15,11 @@ Usage:
                                    Run all enabled loops (headless; Ctrl+C stops);
                                    --once runs one full round of ticks, drains the
                                    landings it produced, and exits (for cron/CI);
+                                   exits 3 when a tick ended in error, review_error,
+                                   merge_conflict, merge_blocked, or main_red;
                                    --once --role <id> scopes that round to one loop;
-                                   --for <duration> runs for that window then drains
+                                   --for <duration> runs for that window then drains, prints a per-loop summary
+                                   (one window across self-redeploys),
                                    and exits like Ctrl+C would (for an overnight
                                    trial, a demo, a CI step);
                                    --gui also serves the browser dashboard at
@@ -88,7 +91,7 @@ Usage:
   tumwater notify --test          Run the configured notify hook once with a synthetic event
                                    so the command can be checked before a real page
   tumwater history [--role <id>] [-n N] [--since <duration>] [--grep <text>]
-                   [--result <changes|none|problems>] [--json]
+                   [--result <changes|none|problems>] [--summary] [--json]
                                    One row per completed tick, newest first — time, loop,
                                    tick number, result, duration, tokens/cost, and the
                                    summary (or error), each row one line; --since <duration>
@@ -100,30 +103,37 @@ Usage:
                                    problems (everything else) — composed with --role, --since,
                                    -n, and --grep; --json prints the rows as
                                    machine-readable history data — ts, tokens, and costUsd
-                                   kept raw, the GUI's /api/history payload
-  tumwater tick <role> [<n>] [--last] [--json]
+                                   kept raw, the GUI's /api/history payload; --summary prints one line per loop
+                                   counting its ticks by outcome class, with the time of its newest change (and a total line)
+                                   instead of the rows; with --json, { loops, total }
+  tumwater tick <role> [<n>] [--last] [--stat] [--json]
                                    One completed tick's full event trail — a summary header
                                    (result or in-flight, duration, tokens/cost, the pinned
                                    commit sha) then every event of that tick's block in time
                                    order; a still-running tick shows its events so far, marked
-                                   in flight; --last shows the newest completed tick's trail
-                                   instead of numbering one; --json prints the collector's
-                                   payload as machine-readable data
+                                   in flight; a queued tick shows its landing's verdict and
+                                   outcome line once the landing finishes; --last shows the newest completed tick's trail
+                                   instead of numbering one; --stat appends the pinned
+                                   commit's per-file git show --stat summary; --json prints
+                                   the collector's payload as machine-readable data
   tumwater diff [--json]           One line per loop holding pending work — the ahead-of-main
                                    commit count and uncommitted-file count, no patch; roles
                                    with no worktree or nothing pending are skipped, and a
                                    missing baseline prints the per-role view's degradation
                                    line; --json prints the {mainBranch, roles} roster
-  tumwater diff --role <id> [--json]
+  tumwater diff --role <id> [--stat] [--json]
                                    Show the change that loop holds: its branch's unlanded
                                    commits (one line each, plus the ahead-of-main patch) and
                                    its worktree's uncommitted edits (the file list, plus the
                                    patch — staged and unstaged alike); a loop with no worktree
-                                   yet prints \`no worktree for <id>\`; --json prints the
+                                   yet prints \`no worktree for <id>\`; --stat prints each patch's per-file
+                                   \`git diff --stat\` summary instead; --json prints the
                                    collector's payload as machine-readable data
   tumwater queue [--json]          List the durable land queue in execution order (oldest
                                    first): one line per waiting landing — position, loop, tick
-                                   number, short pinned sha, age, and summary; an empty queue
+                                   number, short pinned sha, age, and summary — plus a bracketed
+                                   \`[landing 2m · reviewing]\` / \`[vetted, awaiting merge]\`
+                                   label while a running fleet works on it; an empty queue
                                    prints \`land queue empty\`, and any torn/foreign queue file
                                    the reader skipped is counted on a trailing line; --json
                                    prints the collector's own {entries, unreadable} document
@@ -140,6 +150,10 @@ Usage:
                                    File a bug from a markdown file ("-" reads stdin): the first
                                    non-blank line is the symptom, the rest is the body kept
                                    line for line; wakes the bugfix loop
+  tumwater bug --release <n> [--json]
+                                   Lift the Refused note from the Nth entry in BUGS.md ## Open
+                                   (as \`tumwater bug --list\` lists it), commit it on main,
+                                   and wake the bugfix loop; --json prints {file, title}
   tumwater bug --cancel <n> [--json]
                                    Remove the Nth entry in BUGS.md ## Open (as \`tumwater
                                    bug --list\` lists it); no wake; --json prints {file, title}
@@ -152,10 +166,17 @@ Usage:
                                    stdin): the first non-blank line is the title (symptom), the rest
                                    the body kept line for line; position and original stamp
                                    kept; no wake; --json prints {file, title}
+  tumwater bug --edit <n> [--json]
+                                   With neither text nor --file, open the Nth entry as --show
+                                   prints it in $VISUAL or $EDITOR and write it back on save;
+                                   an unchanged buffer writes nothing
   tumwater bug --list [--json]     List the entries in BUGS.md ## Open, numbered (the read
                                    half of --edit/--cancel), each with its eligibility mark;
                                    --json prints the {entries} array — position, title, body,
                                    hold — as data
+  tumwater bug --show <n> [--json] Print the Nth entry as the markdown file --edit <n> --file
+                                   reads (title, blank line, body with indentation kept);
+                                   --json prints {position, title, body, hold}
   tumwater plan "<title>" [body...] [--json]
                                    File a plan request into PLANS.md ## Planned as the operator
                                    (stamped with today's date; the feature loop fleshes the stub
@@ -165,6 +186,10 @@ Usage:
                                    File a plan request from a markdown file ("-" reads stdin):
                                    the first non-blank line is the title, the rest is the body
                                    kept line for line; wakes the feature loop
+  tumwater plan --release <n> [--json]
+                                   Lift the Refused note from the Nth entry in PLANS.md ## Planned
+                                   (as \`tumwater plan --list\` lists it), commit it on main,
+                                   and wake the feature loop; --json prints {file, title}
   tumwater plan --cancel <n> [--json]
                                    Remove the Nth entry in PLANS.md ## Planned (as \`tumwater
                                    plan --list\` lists it); no wake; --json prints {file, title}
@@ -177,10 +202,18 @@ Usage:
                                    stdin): the first non-blank line is the title, the rest
                                    the body kept line for line; position and original stamp
                                    kept; no wake; --json prints {file, title}
+  tumwater plan --edit <n> [--json]
+                                   With neither text nor --file, open the Nth entry as --show
+                                   prints it in $VISUAL or $EDITOR and write it back on save;
+                                   an unchanged buffer writes nothing
   tumwater plan --list [--json]    List the entries in PLANS.md ## Planned, numbered (the
                                    read half of --edit/--cancel), each with its eligibility
                                    mark; --json prints the {entries} array — position, title,
                                    body, hold — as data
+  tumwater plan --show <n> [--json]
+                                   Print the Nth entry as the markdown file --edit <n> --file
+                                   reads (title, blank line, body with indentation kept);
+                                   --json prints {position, title, body, hold}
   tumwater questions [--json]      List open questions numbered (the read half of the
                                    question outbox); --json prints the {questions}
                                    array — position, title, body — as data
@@ -194,6 +227,17 @@ Usage:
                                    Read the decision from the file (- for stdin) with its
                                    lines kept; a ## or ### heading line outside a code fence,
                                    or an unclosed fence, is refused
+  tumwater questions answer [--json] <n>
+                                   With no decision, open the question in $VISUAL/$EDITOR;
+                                   only the text above the marker line is recorded
+  tumwater brief [--json]          Show the project's initial prompt and the file that holds it
+  tumwater brief --file <path> [--json]
+                                   Replace the initial prompt with the file's text (- for
+                                   stdin), refused when empty, over the length cap, or
+                                   containing a tumwater:prompt marker; commits that one
+                                   file on main; no wake
+  tumwater brief --edit [--json]   Open the initial prompt in $VISUAL/$EDITOR and save it as
+                                   --file would; an unchanged buffer writes nothing
   tumwater role <id> [--json]      Show one loop's standing prompt and resolved settings — its
                                    find text, the roles.<id>.instructions override, the resolved
                                    provider/model (naming the budget fallback pair when one is
@@ -236,6 +280,10 @@ Usage:
                                    contents ("-" reads stdin), kept line for line; position,
                                    age, and a pending --at deferral are kept, and --role <id>
                                    disambiguates like --edit
+  tumwater prompt --edit <n> [--attach <path>]
+                                   Open the Nth queued prompt in $VISUAL/$EDITOR and save it
+                                   as the text form would; an unchanged buffer writes
+                                   nothing; --role <id> disambiguates like --edit
   tumwater reset-counters [--role <id>]
                                    Zero lifetime ticks/commits/tokens/cost (fresh
                                    observation window; today's budget spend is kept — the
@@ -258,8 +306,15 @@ Usage:
   tumwater resume [--role <id>]    Lift a fleet or per-role pause
   tumwater retire --role <id>      Remove a disabled loop's worktree, branch, and per-role
                                    state (landing ref, pause marker); --force overrides the
-                                   safety rails; --json prints what was removed
-  tumwater stop                    Stop a running fleet (drains in-flight ticks, like Ctrl+C)
+                                   safety rails; --json prints what was removed;
+                                   --dry-run lists what would be removed and any objections,
+                                   changing nothing
+  tumwater stop [--in <duration> | --cancel]
+                                   Stop a running fleet (drains in-flight ticks, like Ctrl+C);
+                                   --in schedules the stop, --cancel drops it
+  tumwater completion <bash|zsh>   Print a shell completion script (eval "$(tumwater completion zsh)" in your rc)
+  tumwater completion --roles      Print the loop ids --role completes (this repo's; the catalog when tumwater.json is unreadable)
+  tumwater completion --config-keys  Print the keys config get/set/unset complete (this repo's role keys; the catalog's when tumwater.json is unreadable)
   tumwater help [<command>]        Show all commands, or one command's usage
   tumwater version                 Print the version
 
@@ -309,13 +364,13 @@ export function helpTopic(command, help = HELP) {
 }
 /** The free-form text commands and the flags that take a separate value token, for
  * helpTopicForArgs: a valued flag's value is plumbing (`prompt --role qa --help`, `bug
- * --cancel 2 --help`), never prose. bug/plan's valued flags are `--cancel`, `--edit`
- * and `--file`. */
+ * --cancel 2 --help`), never prose. bug/plan's valued flags are `--cancel`, `--edit`,
+ * `--file` and `--release`. */
 const FREEFORM_VALUED_FLAGS = {
     prompt: ["--role", "--file", "--at", "--cancel", "--edit", "--attach"],
     init: ["--branch", "--template", "--file"],
-    bug: ["--cancel", "--edit", "--file"],
-    plan: ["--cancel", "--edit", "--file"],
+    bug: ["--cancel", "--edit", "--file", "--release"],
+    plan: ["--cancel", "--edit", "--file", "--release"],
 };
 /** The `--help`/`-h` request cli.ts answers before dispatch: the topic text for `command`
  * when the invocation asks for help and names a topic, otherwise null — not a help request,

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

@@ -117,6 +117,8 @@ function answeredOrFail(n, outcome) {
         fail(`no question at position ${n} (${outcome.open} open)`);
     if (outcome.status === "fenced")
         fail(UNCLOSED_FENCE_MESSAGE);
+    if (outcome.status === "moved")
+        fail(`question ${n} is now "${outcome.title}" — the list changed while you edited; nothing changed`);
     if (outcome.status !== "answered")
         fail(`no question at position ${n}`);
     return { title: outcome.title, decision: outcome.decision };
@@ -124,14 +126,28 @@ function answeredOrFail(n, outcome) {
 /** `tumwater questions answer <n> --file <path>`: the decision's lines kept (normalizeEntryBody),
  * behind the same structural guard `plan --file` uses, so a stray `## ` line cannot grow a
  * phantom section. Refusals exit 1 through `fail`. */
-export function answerQuestionFromText(root, n, text) {
+export function answerQuestionFromText(root, n, text, expectedTitle) {
     const body = normalizeEntryBody(text);
     if (body === "")
         fail("questions answer needs a decision: the file is blank");
     const problem = bodyStructureProblem(body);
     if (problem !== null)
         fail(`questions answer --file: ${problem}`);
-    return answeredOrFail(n, tryAnswerQuestion(root, n, body, undefined, true));
+    return answeredOrFail(n, tryAnswerQuestion(root, n, body, expectedTitle, true));
+}
+/** The line that ends the decision area of the `questions answer <n>` editor buffer. */
+export const ANSWER_EDITOR_CUT = "<!-- tumwater: write your decision above this line; this line and everything below it are dropped -->";
+/** The editor buffer for bare `questions answer <n>`: an empty decision area, the cut line, then
+ * the question's heading and body for reference. */
+export function answerEditorBuffer(title, body) {
+    return ["", "", ANSWER_EDITOR_CUT, `### ${title}`, body].join("\n");
+}
+/** The decision an edited `answerEditorBuffer` holds: the text before the first cut line (all of
+ * it when the operator deleted the line). */
+export function decisionFromEditorBuffer(text) {
+    const lines = text.split("\n");
+    const cut = lines.findIndex((l) => l.trim() === ANSWER_EDITOR_CUT);
+    return (cut === -1 ? lines : lines.slice(0, cut)).join("\n");
 }
 /** The non-exiting answer core, for callers (the dashboard server) that must not end the
  * process: runs the whole read-modify-write under the cross-process primary-worktree lock