tumwater 0.1.2 → 0.2.0

package/dist/src/cli/help.js

@@ -4,44 +4,54 @@
  * <command>` from it by splitting the usage block on its `  tumwater <command>` lines, so a
  * topic can never drift out of sync with the full listing. */
 import { suggestClosest } from "../text/suggest.js";
-export const HELP = `tumwater — autonomous development harness built on pi
+// vocabulary: plain
+/** Machine names HELP quotes verbatim; the scripting series renames them. */
+const SUMMARY_JSON_KEYS = "{ loops, total }"; // vocabulary-ok: --json keys until the scripting series
+export const HELP = `tumwater — an autonomous development team, built on pi
 
 Usage:
   tumwater init <prompt...>        Initialize this repo (--file <prompt.md>, --adopt: brief in
                                    TUMWATER.md, --branch <name> seeds a new repo only,
                                    --template <id> seeds a starter brief+backlog (--list-templates
                                    lists them), --dry-run: write nothing)
-  tumwater run [--branch <name>] [--once] [--for <duration>] [--role <id>] [--gui]
-                                   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);
-                                   --once --role <id> scopes that round to one loop;
-                                   --for <duration> runs for that window then drains
+  tumwater start [--branch <name>] [--once] [--for <duration>] [--role <id>] [--gui] [--tui]
+                                   Start the team: every enabled role runs in turn (headless;
+                                   Ctrl+C finishes current work, then stops);
+                                   --once does one round of runs, finishes the
+                                   merges it produced, and exits (for cron/CI);
+                                   exits 3 when a run ended in error, review failed,
+                                   a merge conflicted or was blocked, or main's check is failing;
+                                   --once --role <id> limits that round to one role;
+                                   --for <duration> runs for that window then finishes current work, prints a per-role 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
                                    http://127.0.0.1:7180 (the \`tumwater gui\`
-                                   defaults — see that command for --port and --token)
-  tumwater tui                     Dashboard + prompt input (observes a running \`tumwater run\`)
+                                   defaults — see that command for --port and --token);
+                                   --tui also hosts the TUI in this terminal
+                                   (the \`tumwater tui\` view — quitting it stops the
+                                   team like Ctrl+C)
+  tumwater tui                     Dashboard + inbox input (watches a running \`tumwater start\`)
   tumwater gui [--port N] [--all-interfaces] [--token <secret>]
                                    Same dashboard in the browser (default port 7180,
                                    localhost only; --all-interfaces serves the whole
                                    network — without --token there is no auth, anyone
-                                   reaching it can prompt the director)
+                                   reaching it can message the director)
   tumwater status [--json]         One-shot status table (--json prints machine-readable
-                                   fleet state — the GUI's /api/status payload minus the
+                                   team state — the GUI's /api/status payload minus the
                                    serving process's serverBuildSha)
   tumwater report [--days N] [--role <id>] [--json]
-                                   Markdown usage report — tokens/ticks/commits per day (default
-                                   14 days); totals also include landing runs (reviewer + conflict
-                                   resolution); --role <id> scopes the report to one loop's ticks,
-                                   tokens, cost, and commits (landing runs and backlog tallies
+                                   Markdown usage report — tokens/runs/commits per day (default
+                                   14 days); totals also include merge runs (reviewer + conflict
+                                   resolution); --role <id> scopes the report to one role's runs,
+                                   tokens, cost, and commits (merge runs and backlog tallies
                                    omitted); --json prints machine-readable usage data — the
                                    collector's own payload, not the Markdown render
   tumwater report --failures [--days N] [--since <duration>] [--role <id>] [--json]
-                                   Markdown failure digest — tick outcomes, deltas,
-                                   clustered errors, and fleet state changes (default
-                                   14 days); --role <id> scopes the digest to one loop's
+                                   Markdown failure digest — run outcomes, deltas,
+                                   clustered errors, and team state changes (default
+                                   14 days); --role <id> scopes the digest to one role's
                                    rows; --since windows the digest over a trailing
                                    span (capped at 7d)
   tumwater report --failures --since <duration> [--role <id>] [--json]
@@ -49,16 +59,21 @@ Usage:
                                    against the equal-length window before it
   tumwater report --since <duration> [--role <id>] [--json]
                                    Totals over a trailing window (capped at 7d) —
-                                   tokens/ticks/commits/cost since a point in time; totals
-                                   also include landing runs (reviewer + conflict
-                                   resolution); --role <id> scopes the totals to one loop
-                                   (landing runs and backlog tallies omitted); not
+                                   tokens/runs/commits/cost since a point in time; totals
+                                   also include merge runs (reviewer + conflict
+                                   resolution); --role <id> scopes the totals to one role
+                                   (merge runs and backlog tallies omitted); not
                                    combinable with --days
-  tumwater doctor [--json]         Pre-flight check: node, git, repo, config, fallback
-                                   model, pi, locks, build, orphans, mach ports
+  tumwater doctor [--json] [--reprobe] [--problems]
+                                   Pre-flight check: node, git, repo, config, fallback
+                                   model, pi, locks, update, orphans, macOS port leak
                                    (read-only; exit 0/1; --json prints the report object —
                                    header, the checks array with level, name, and detail,
-                                   and verdict)
+                                   and verdict; probes image-input models — --reprobe
+                                   re-probes every one, bypassing the 7-day cache; --problems prints only the warn
+                                   and fail rows (and how many ok rows it hid), the same
+                                   verdict and exit code; with --json the checks array holds
+                                   only those rows)
   tumwater config [get <key> | set <key> <value> | unset <key>]
                                    Show the effective config (defaults + tumwater.json) as
                                    JSON; get one key's resolved value as JSON; set one
@@ -74,72 +89,107 @@ Usage:
                                    roles still merges the built-in catalog per entry, so
                                    disable a role with roles.<id>.enabled false, not by
                                    omitting it
-  tumwater logs [-f/--follow] [-n N] [--since <duration>] [--grep <text>] [--json]
-                                   Show (and follow) harness events; --since shows the
+  tumwater logs [-f/--follow] [-n N] [--since <duration>] [--grep <text>] [--type <event type>] [--count] [--json]
+                                   Show (and follow) tumwater events; --since shows the
                                    events of the past window (capped at 7d); --grep shows
                                    only events whose type or rendered line matches,
                                    case-insensitively (-n bounds the scanned window, not
-                                   the printed rows); --json prints each event as one
+                                   the printed rows); --type shows only events of that
+                                   exact event type, and an older event name matches its current one (it
+                                   composes with --since); --count
+                                   prints one \`N \u00d7 <type>\` line per present event type
+                                   (most-frequent first) over the selected window instead
+                                   of the rows; --json
+                                   prints each event as one
                                    JSON object per line (NDJSON) — the raw event objects
                                    as stored in the log, instead of the rendered text
+                                   (with --count, one JSON object mapping type \u2192 count)
   tumwater logs --role <id> [-f/--follow] [-n N] [--prompt]
-                                   Show (and follow) that loop's pi transcript
+                                   Show (and follow) that role's pi transcript
                                    (--prompt also shows each run's exact prompt text)
   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]
-                                   One row per completed tick, newest first — time, loop,
-                                   tick number, result, duration, tokens/cost, and the
+                   [--result <merged|none|refused|problems>] [--summary] [--json]
+                                   One row per completed run, newest first — time, role,
+                                   run number, result, duration, tokens/cost, and the
                                    summary (or error), each row one line; --since <duration>
-                                   shows the window's ticks instead of the last N (capped at
+                                   shows the window's runs instead of the last N (capped at
                                    7d, like logs --since); --grep <text> keeps only rows whose
                                    line matches, case-insensitively (like logs --grep);
-                                   --result <class> narrows to one outcome class — changes
-                                   (changed/queued), none (no_change/skipped/user_aborted), or
+                                   --result <class> narrows to one outcome class — merged
+                                   (merged or waiting to merge), none (no_change/skipped/user_aborted),
+                                   refused (a run that deliberately declined its entry), or
                                    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]
-                                   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
-  tumwater diff [--json]           One line per loop holding pending work — the ahead-of-main
+                                   kept raw, the GUI's /api/history payload; --summary prints one line per role
+                                   counting its runs by outcome class and its run time, with the time of its newest change (and a total line)
+                                   instead of the rows; with --json, ${SUMMARY_JSON_KEYS}
+  tumwater history <role> [<n>] [--last] [--stat] [--json]
+                                   One run's full event trail — a summary header (result, or
+                                   in flight, with duration, tokens and cost, and the commit)
+                                   then every event of that run in time order; a run still in
+                                   flight shows its events so far; a run waiting to merge
+                                   shows its merge verdict once the merge finishes; --last
+                                   shows the role's newest finished run instead of numbering
+                                   one; --stat appends the commit's per-file git show --stat
+                                   summary; --json prints the collector's payload
+  tumwater diff [--json]           One line per role 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]
-                                   Show the change that loop holds: its branch's unlanded
+  tumwater diff --role <id> [--stat] [--json]
+                                   Show the change that role holds: its branch's unmerged
                                    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
+                                   patch — staged and unstaged alike); a role with no workspace
+                                   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
-                                   prints \`land queue empty\`, and any torn/foreign queue file
+  tumwater queue [--json]          List the durable merge queue in execution order (oldest
+                                   first): one line per waiting merge — position, role, run
+                                   number, short pinned sha, age, and summary — plus a bracketed
+                                   \`[merging 2m · reviewing]\` / \`[approved, waiting to merge]\`
+                                   label while a running team works on it; an empty queue
+                                   prints \`merge 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
                                    (raw sha and numeric enqueuedAt, not the render's age)
-  tumwater backlog [--json]        Show planned features, open bugs, and open questions (the
+  tumwater backlog [--ready] [--json]
+                                   Show planned features, open bugs, and open questions (the
                                    dashboards' backlog view); --json prints machine-readable
                                    backlog data — the three entry arrays as {title, body}, the
-                                   same data the Markdown view renders
+                                   same data the Markdown view renders; a series with two or more
+                                   blocked parts prints as one heading (--json still lists every
+                                   entry); an entry a role is
+                                   working on carries \`[working on it: feature #2]\` (--json:
+                                   an \`inProgress\` key parallel to the arrays); --ready keeps only the
+                                   planned plans and open bugs no hold keeps from being
+                                   picked (entries a role is working on stay)
+  tumwater archive                 Move the finished entries still under PLANS.md ## Done and
+                                   BUGS.md ## Fixed to the top of PLANS-DONE.md and BUGS-FIXED.md
+                                   and commit them on the base branch, waiting for a merge in
+                                   progress; a starting team does the same, and a role's own
+                                   finished entry moves when its change commits
   tumwater bug "<symptom>" [--json]
-                                   File a bug into BUGS.md ## Open as the operator (stamped
-                                   with today's date) and wake the bugfix loop; --json prints
+                                   File a bug into BUGS.md ## Open as you (stamped
+                                   with today's date) and wake the bugfix role; --json prints
                                    the {file, title, stamp} payload as data
   tumwater bug --file <path> [--json]
                                    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
+                                   line for line; wakes the bugfix role
+  tumwater bug --release <n> [--json]
+                                   Lift the Refused or Waiting for the next failure note from the
+                                   Nth entry in BUGS.md ## Open (as \`tumwater bug --list\`
+                                   lists it), commit it on main, and wake the bugfix role; --json
+                                   prints {file, title}
+  tumwater bug --top <n> [--json]
+                                   Move the Nth entry (as \`tumwater bug --list\` lists it) to
+                                   the head of BUGS.md ## Open, so bugfix claims it next; commit
+                                   it on main; no wake; --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,19 +202,44 @@ 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
+                                   hold, inProgress — as data; \`[working on it: …]\` marks an
+                                   entry a role is working on
+  tumwater bug --list --done [-n <count>] [--grep <text>] [--json]
+                                   List the newest entries, numbered, in BUGS.md ## Fixed, newest first
+                                   (default 10); --json prints {entries, older}, each entry
+                                   with position, title, body, completedOn
+                                   --grep keeps the entries whose heading or body contains the
+                                   text, case-insensitively, numbered as without it
+  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 bug --show <n> --done [--json]
+                                   Print the Nth entry of \`bug --list --done\` (newest first) in
+                                   full; --json prints {position, title, body, completedOn}
   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
-                                   out on pickup) and wake the feature loop; --json prints the
+                                   File a plan request into PLANS.md ## Planned as you
+                                   (stamped with today's date; the feature role fleshes the stub
+                                   out on pickup) and wake the feature role; --json prints the
                                    {file, title, stamp} payload as data
   tumwater plan --file <path> [--json]
                                    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
+                                   kept line for line; wakes the feature role
+  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 role; --json prints {file, title}
+  tumwater plan --top <n> [--json]
+                                   Move the Nth entry (as \`tumwater plan --list\` lists it) to
+                                   the head of PLANS.md ## Planned, so feature claims it next;
+                                   commit it on main; no wake; --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,95 +252,210 @@ 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
+                                   body, hold, inProgress — as data; \`[working on it: …]\`
+                                   marks an entry a role is working on; a series' blocked
+                                   parts show as one line naming their positions
+  tumwater plan --list --done [-n <count>] [--grep <text>] [--json]
+                                   List the newest entries, numbered, in PLANS.md ## Done, newest first
+                                   (default 10); --json prints {entries, older}, each entry
+                                   with position, title, body, completedOn
+                                   --grep keeps the entries whose heading or body contains the
+                                   text, case-insensitively, numbered as without it
+  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 plan --show <n> --done [--json]
+                                   Print the Nth entry of \`plan --list --done\` (newest first) in
+                                   full; --json prints {position, title, body, completedOn}
   tumwater questions [--json]      List open questions numbered (the read half of the
                                    question outbox); --json prints the {questions}
                                    array — position, title, body — as data
+  tumwater questions --answered [-n <count>] [--grep <text>] [--json]
+                                   List the newest answered questions, numbered, newest first
+                                   (default 10), each with its answer line; --json prints {questions,
+                                   older}, each with position, title, body, answeredOn
+                                   --grep keeps the questions whose heading or body contains the
+                                   text, case-insensitively, numbered as without it
+  tumwater questions --show <n> --answered [--json]
+                                   Print the Nth entry of "questions --answered" (newest
+                                   first) in full, context and recorded answer; --json
+                                   prints {position, title, body, answeredOn}
+  tumwater questions --show <n> [--json]
+                                   Print the Nth open question in full (heading, blank line,
+                                   body), the numbering "questions" lists and "questions
+                                   answer <n>" takes; --json prints {position, title, body,
+                                   since, ageDays}
   tumwater questions answer [--json] <n> "<decision>"
                                    Answer the Nth open question: stamps today's date on the
                                    entry and moves it to ## Answered with your decision.
                                    --json prints the result as data and must precede <n>:
                                    a --json after the decision is recorded as part of it;
-                                   loops read the answer at their next tick
+                                   roles read the answer at their next run
   tumwater questions answer [--json] <n> --file <path>
                                    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 role <id> [--json]      Show one loop's standing prompt and resolved settings — its
-                                   find text, the roles.<id>.instructions override, the resolved
+  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 brief and the file that holds it
+  tumwater brief --file <path> [--json]
+                                   Replace the brief 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 brief in $VISUAL/$EDITOR and save it as
+                                   --file would; an unchanged buffer writes nothing
+  tumwater role <id> [--json]      Show one role's instructions and resolved
+                                   settings — its built-in instructions, the roles.<id>.instructions override, the resolved
                                    provider/model (naming the budget fallback pair when one is
-                                   configured), the min-tick interval, enabled/paused state, and
-                                   the next tick's assembled prompt (the oldest queued prompt appears in it
-                                   and is NOT consumed — one is dequeued per tick); --json prints the collector's payload
+                                   configured), that model's declared context window and whether a run gets the compact
+                                   prompt, the min-run interval, enabled/paused state, and
+                                   the next run's assembled prompt (the oldest inbox message appears in it
+                                   and is NOT consumed — one is dequeued per run); --json prints the collector's payload
                                    as machine-readable data
-  tumwater role <id> --clear-notes Clear that loop's notebook
+  tumwater role <id> --clear-notes Clear that role's notes
   tumwater role <id> --notes-file <path>
-                                   Replace that loop's notebook from a file ("-" reads stdin;
-                                   4 KB cap); a tick running at that moment may still
-                                   overwrite it through its own role_notes call
-  tumwater prompt <text...>        Queue a prompt for the director loop
-  tumwater prompt --file <path>    Queue a prompt read from a file ("-" reads stdin)
+                                   Replace that role's notes from a file ("-" reads stdin;
+                                   4 KB cap); a run in progress at that moment may still
+                                   overwrite it through its own tumwater-notes call
+  tumwater role <id> --clear-instructions
+                                   Clear that role's instructions override
+  tumwater role <id> --instructions-file <path>
+                                   Replace that role's instructions override from a file
+                                   ("-" reads stdin; 4 KB cap), written to roles.<id>.instructions
+  tumwater role <id> --clear-quiet-hours
+                                   Clear that role's own quiet-hours window
+  tumwater role <id> --quiet-hours <window>
+                                   Set that role's own daily local-time quiet-hours
+                                   window (e.g. "23:00-07:00"; empty clears it),
+                                   written to quietHoursPerRole.<id> for the base id
+  tumwater role <id> --cap <usd>  Set that role's daily cap in USD (0 disables it),
+                                   written to maxDailyCostUsdPerRole.<id> for the base id
+  tumwater role <id> --clear-cap  Clear that role's daily cap
+  tumwater role <id> --min-run-interval <seconds>
+                                   Set that role's own minimum-run interval (0 allows
+                                   back-to-back runs), written to roles.<id>.minRunIntervalSeconds
+                                   for the base id; clearing falls back to the team-wide interval
+  tumwater role <id> --clear-min-run-interval
+                                   Clear that role's own minimum-run interval
+  tumwater role <id> --provider <id>
+                                   Set that role's model provider (e.g. openai), written to
+                                   roles.<id>.provider for the base id
+  tumwater role <id> --clear-provider
+                                   Clear that role's model provider
+  tumwater role <id> --model <id>  Set that role's model (a model id or a tier name like
+                                   strong), written to roles.<id>.model for the base id
+  tumwater role <id> --clear-model
+                                   Clear that role's model
+  tumwater role <id> --thinking <level>
+                                   Set that role's pi thinking level (off|minimal|low|
+                                   medium|high|xhigh|max), written to roles.<id>.thinking
+                                   for the base id
+  tumwater role <id> --clear-thinking
+                                   Clear that role's thinking level
+  tumwater role <id> --enable      Enable the role, written to roles.<id>.enabled
+                                   (the base id for an instance)
+  tumwater role <id> --disable     Disable it (refused for the director); clean up
+                                   leftovers with tumwater retire --role <id>
+  tumwater role <id> --instances <n>
+                                   Set how many parallel runners this role may have
+                                   (an integer from 1 to 8; only feature and bugfix split),
+                                   written to roles.<id>.instances for the base id
+  tumwater role <id> --clear-instances
+                                   Clear that role's instance count (back to 1)
+  tumwater prompt <text...>        Send a message to the director's inbox
+  tumwater prompt --file <path>    Send a message read from a file ("-" reads stdin)
   tumwater prompt --role <id> <text...>
-                                   Queue a prompt for that loop's next tick (wakes it)
+                                   Send a message to that role's inbox for its next run (wakes it)
   tumwater prompt --at <duration> <text...>
-                                   Queue a prompt that stays hidden until the duration has
+                                   Send a message that stays hidden until the duration has
                                    passed (45s, 90m, 1h30m, 1d; capped at 90d — listed and
-                                   cancellable while it waits, delivered to the tick only
+                                   cancellable while it waits, delivered to the run only
                                    once due)
   tumwater prompt --attach <path> <text...>
-                                   Queue a prompt with an image attached (repeat up to 4
+                                   Send a message with an image attached (repeat up to 4
                                    images: png, jpg, jpeg, gif, webp, bmp; each at most 5
-                                   MiB — saved beside the queue file for the loop's next
-                                   tick)
-  tumwater prompt --list [--json]  Show queued prompts, numbered, grouped by loop
+                                   MiB — saved beside the inbox file for the role's next
+                                   run)
+  tumwater prompt --list [--json]  Show inbox messages, numbered, grouped by role
                                    (--json prints the {prompts} array as
                                    machine-readable data)
-  tumwater prompt --cancel <n>     Remove the Nth queued prompt as --list shows them; when
-                                   several loops show that N, name one with --role <id>
+  tumwater prompt --cancel <n>     Remove the Nth inbox message as --list shows them; when
+                                   several roles show that N, name one with --role <id>
+  tumwater prompt --top <n>        Move the Nth inbox message as --list shows them to the
+                                   head of its role's inbox, so it dequeues next; a pending
+                                   --at deferral still holds until its time; --role <id>
+                                   disambiguates like --cancel
   tumwater prompt --edit <n> <text...> [--attach <path>]
-                                   Replace the Nth queued prompt's text in place (position,
-                                   enqueue age, and a pending --at deferral are kept; as
+                                   Replace the Nth inbox message's text in place (position,
+                                   age in the inbox, and a pending --at deferral are kept; as
                                    shown by --list); --attach (repeat up to 4) appends images
-                                   after any the prompt already carries; when several loops
+                                   after any the prompt already carries; when several roles
                                    show that N, name one with --role <id>
   tumwater prompt --edit <n> --file <path> [--attach <path>]
-                                   Replace the Nth queued prompt's text with the file's
+                                   Replace the Nth inbox message's text with the file's
                                    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 inbox message 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
+                                   Zero lifetime runs/commits/tokens/cost (fresh
                                    observation window; today's budget spend is kept — the
                                    daily cap cannot be reset past)
   tumwater wake [--role <id>] [--in <dur> | --cancel | --list [--json]]
-                                   Wake a backed-off fleet — the named roles (or all) tick
+                                   Wake sleeping roles — the named roles (or all) run
                                    within one poll; --in schedules the wake for later;
                                    --cancel drops pending scheduled wakes;
                                    --list shows every pending scheduled wake, earliest first
                                    (--json for scripts)
-  tumwater reclaim [--dry-run]     Reclaim gitignored build outputs from every harness
-                                   worktree; --dry-run lists each candidate with its idle age
+  tumwater reclaim [--dry-run]     Reclaim gitignored build outputs from every
+                                   workspace; --dry-run lists each candidate with its idle age
                                    and ignored-path count and cleans nothing
-  tumwater abort --role <id>       Abort that loop's in-flight tick (work discarded; the loop
-                                   keeps running)
+  tumwater revert <sha>          Undo one merged change on main, committing the inverse
+                                   under the primary-worktree lock; refuses off the base
+                                   branch, on an unknown or unmerged ref, and on a conflict
+  tumwater abort --role <id>       Stop that role's run in progress (work discarded; the role
+                                   keeps going)
+  tumwater restart                Apply a pending self-redeploy now, waiving the restart
+                                   cooldown (the dashboard's update-alert refresh button; a
+                                   passing check on main, a successful compile, and in-flight
+                                   runs finishing still apply)
   tumwater pause [--role <id>] [--for <dur>] [--reason <text>]
-                                   Stop role loops (or just the named loop) starting new
-                                   ticks; --reason states why the whole FLEET is paused (no
+                                   Stop roles (or just the named role) starting new
+                                   runs; --reason states why the whole team is paused (no
                                    per-role reason); --for auto-resumes (capped at 90d)
-  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)
+  tumwater resume [--role <id>]    Lift a team or per-role pause
+  tumwater retire --role <id>      Remove a disabled role's workspace, branch, and per-role
+                                   state (merge ref, pause marker); --force overrides the
+                                   safety rails; --json prints what was removed;
+                                   --dry-run lists what would be removed and any objections,
+                                   changing nothing; an id no longer configured (feature-4
+                                   after lowering instances, a removed custom role) is
+                                   accepted while its branch or merge ref remains
+  tumwater stop [--in <duration> | --cancel]
+                                   Stop a running team (finishes current work, like Ctrl+C);
+                                   --in schedules the stop, --cancel drops it
+  tumwater completion <bash|zsh|fish>   Print a shell completion script (eval "$(tumwater completion zsh)" in your rc; fish: tumwater completion fish | source)
+  tumwater completion --roles      Print the role 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
 
-The harness runs inside a git repo. Each role loop owns a persistent worktree and branch
-under .tumwater/, does one task per tick with pi, commits, and merges to main. Loops back
-off while the project is quiet and wake when main moves. Everything is local: no remotes.
+tumwater runs inside a git repo. Each role owns a persistent workspace and branch
+under .tumwater/, does one task per run with pi, commits, and merges to main. Roles
+sleep while there is nothing to do and wake when main moves. Everything is local: no remotes.
 `;
 /** The listed command closest to a mistyped one, or null when nothing is close enough to
  * suggest. Case-insensitive closest-match over the commands helpStanzas(HELP) names, capped
@@ -299,9 +489,14 @@ export function helpStanzas(help = HELP) {
     }
     return stanzas;
 }
+/** Commands that still dispatch but are not listed in help or completion: alias -> the command
+ * whose topic they print. `run` is the older name of `start`. */
+export const HIDDEN_COMMAND_ALIASES = { run: "start", tick: "history" };
 /** The usage text for one command — every stanza whose command matches, then a pointer back to
  * the full list — or null when nothing in the help names that command. */
 export function helpTopic(command, help = HELP) {
+    if (Object.hasOwn(HIDDEN_COMMAND_ALIASES, command))
+        command = HIDDEN_COMMAND_ALIASES[command];
     const matches = helpStanzas(help).filter((s) => s.command === command);
     if (matches.length === 0)
         return null;
@@ -309,13 +504,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`, `--release` and `--top`. */
 const FREEFORM_VALUED_FLAGS = {
-    prompt: ["--role", "--file", "--at", "--cancel", "--edit", "--attach"],
+    prompt: ["--role", "--file", "--at", "--cancel", "--edit", "--attach", "--top"],
     init: ["--branch", "--template", "--file"],
-    bug: ["--cancel", "--edit", "--file"],
-    plan: ["--cancel", "--edit", "--file"],
+    bug: ["--cancel", "--edit", "--file", "--release", "--top"],
+    plan: ["--cancel", "--edit", "--file", "--release", "--top"],
 };
 /** 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,