tumwater 0.2.0 → 0.4.0

package/dist/src/cli/help.js

@@ -4,9 +4,9 @@
  * <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";
-// 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
+/** The role-grouped summary's JSON keys, quoted verbatim in `history --summary --json` help
+ * (its `--by model` twin is the hardcoded `{ models, total }` beside it). */
+const SUMMARY_JSON_KEYS = "{ roles, total }";
 export const HELP = `tumwater — an autonomous development team, built on pi
 
 Usage:
@@ -14,21 +14,26 @@ Usage:
                                    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 start [--branch <name>] [--once] [--for <duration>] [--role <id>] [--gui] [--tui]
+  tumwater start [--branch <name>] [--once] [--json] [--for <duration>] [--role <id>[,<id>...]] [--gui [--port <n>]] [--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;
+                                   --once --role <id>[,<id>...] limits that round to the listed roles;
+                                   --once --json prints the round's totals, per-result counts, skipped roles and failures as one JSON object on stdout (no banner or event stream) (the --once report; --json is refused without --once or --for);
                                    --for <duration> runs for that window then finishes current work, prints a per-role summary
                                    (one window across self-redeploys),
+                                   --for --json prints the window's per-role summary as one JSON object on stdout at exit (no banner or event stream); --json with --gui or --tui is refused;
                                    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);
+                                   http://127.0.0.1:7180 and forwards to it the
+                                   dashboard flags \`--port <n>\` (pick another
+                                   port), \`--all-interfaces\` (serve the LAN) and
+                                   \`--token <secret>\` (the auth gate), exactly as
+                                   \`tumwater gui\` takes them);
                                    --tui also hosts the TUI in this terminal
                                    (the \`tumwater tui\` view — quitting it stops the
                                    team like Ctrl+C)
@@ -37,43 +42,72 @@ Usage:
                                    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 message the director)
-  tumwater status [--json]         One-shot status table (--json prints machine-readable
+                                   reaching it can message the director); booting with
+                                   \`tumwater start --gui\` serves it the same way from
+                                   the one-command start, forwarding \`--port N\`,
+                                   \`--all-interfaces\` and \`--token <secret>\`
+  tumwater status [--role <id>[,<id>...]] [-f/--follow] [--json]
+                                   One-shot status table (--json prints machine-readable
                                    team state — the GUI's /api/status payload minus the
-                                   serving process's serverBuildSha)
-  tumwater report [--days N] [--role <id>] [--json]
+                                   serving process's serverBuildSha); --role keeps only the
+                                   listed roles' rows (a base id includes its instances);
+                                   -f/--follow repaints the table until Ctrl+C or the
+                                   process that started it exits, so a backgrounded follow
+                                   does not outlive its parent; the header and budget stay
+                                   team-wide
+  tumwater report [--days N] [--role <id>[,<id>...]] [-f/--follow] [--json]
                                    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]
+                                   resolution); --role <id>[,<id>...] scopes the report to the
+                                   listed roles' 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;
+                                   -f/--follow repaints the report, or with --failures the
+                                   failure digest, every couple of seconds until Ctrl+C or the
+                                   process that started it exits, so a backgrounded follow does
+                                   not outlive its parent; it refuses --json and --since;
+  tumwater report --failures [--days N] [--since <duration>] [--role <id>[,<id>...]] [--json]
                                    Markdown failure digest — run outcomes, deltas,
                                    clustered errors, and team state changes (default
-                                   14 days); --role <id> scopes the digest to one role's
+                                   14 days); --role <id>[,<id>...] scopes the digest to the listed roles'
                                    rows; --since windows the digest over a trailing
                                    span (capped at 7d)
-  tumwater report --failures --since <duration> [--role <id>] [--json]
+  tumwater report --failures --since <duration> [--until <duration>] [--role <id>[,<id>...]] [--json]
                                    The failure digest over a trailing window, compared
-                                   against the equal-length window before it
-  tumwater report --since <duration> [--role <id>] [--json]
+                                   against the equal-length window before it; --until
+                                   <duration> ends both windows' span that long ago
+  tumwater report --since <duration> [--until <duration>] [--role <id>[,<id>...]] [--json]
                                    Totals over a trailing window (capped at 7d) —
                                    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] [--reprobe] [--problems]
+                                   resolution); --role <id>[,<id>...] scopes the totals to the listed roles
+                                   (merge runs and backlog tallies omitted); --until <duration>
+                                   ends that window the given duration ago (requires --since);
+                                   not combinable with --days
+  tumwater doctor [<check>...] [--json] [--reprobe] [--problems] [--kill-orphans] [--commit-backlog] [--resync-install] [--drop-broken-pins] [--retire-leftovers]
                                    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 —
+                                   (read-only unless --kill-orphans, --commit-backlog
+                                   or --resync-install or --drop-broken-pins or --retire-leftovers:
+                                   --kill-orphans first kills the orphaned processes the orphans
+                                   check lists, each with its descendants; --commit-backlog first commits each uncommitted tracked
+                                   backlog or brief file (PLANS.md, BUGS.md, QUESTIONS.md, their archives, the
+                                   brief) on the base branch under the primary-worktree lock, so a merge the
+                                   dirty file blocks can proceed; --resync-install re-syncs the root checkout's
+                                   install on demand under the merge lock, so the always-on install alert's
+                                   advice is one command; --drop-broken-pins first drops each refs/tumwater/
+                                   pin whose commit is gone — the manual git update-ref -d the tumwater pins
+                                   row names; --retire-leftovers first retires each disabled role's leftover
+                                   worktree, branch and merge ref, like tumwater retire --role <id> per role,
+                                   never --force; exit 0/1; --json prints the report object —
                                    header, the checks array with level, name, and detail,
                                    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)
+                                   only those rows; naming checks (as the report prints them, any case; quote names
+                                   with spaces) runs only those, and the verdict and exit code cover only them)
   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
@@ -89,66 +123,114 @@ 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>] [--type <event type>] [--count] [--json]
+  tumwater logs [-f/--follow] [-n N] [--since <duration>] [--until <duration>] [--role <id>[,<id>...]] [--grep <text>] [--type <event type>[,<event type>...]] [--count] [--notable] [--json]
                                    Show (and follow) tumwater events; --since shows the
-                                   events of the past window (capped at 7d); --grep shows
+                                   events of the past window (capped at 7d); --until ends that
+                                   window the given duration ago (requires --since); --grep shows
                                    only events whose type or rendered line matches,
                                    case-insensitively (-n bounds the scanned window, not
-                                   the printed rows); --type shows only events of that
-                                   exact event type, and an older event name matches its current one (it
+                                   the printed rows; it composes with --since); --type shows only events of the listed
+                                   exact event types (comma-separated), 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
+                                   of the rows; --notable
+                                   keeps only non-routine events, the dashboard feed's Notable
+                                   choice (it composes with --since, --grep, --type, --role,
+                                   -n, -f and --json); --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]
+  tumwater logs --transcript <id> [-f/--follow] [-n N] [--prompt] [--grep <text>]
                                    Show (and follow) that role's pi transcript
                                    (--prompt also shows each run's exact prompt text)
+                                   (--grep keeps only the entries containing the text, under their run's separator)
   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 <merged|none|refused|problems>] [--summary] [--json]
+  tumwater history [--role <id>[,<id>...]] [-n N] [-f/--follow] [--since <duration>]
+                   [--until <duration>] [--grep <text>]
+                   [--result <merged|none|refused|problems>[,...]] [--model <selector>[,...]]
+                   [--summary] [--by role|model] [--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 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 — merged
+                                   7d, like logs --since); --until <duration> ends that
+                                   window the given duration ago (requires --since);
+                                   --grep <text> keeps only rows whose line matches,
+                                   case-insensitively (like logs --grep);
+                                   -f prints the last N rows oldest first, then one row
+                                   per run as it ends, until Ctrl+C or its parent exits (not
+                                   with --since or --summary); with --json, one compact
+                                   JSON row per line (the --json row shape), like logs -f --json;
+                                   --role takes a comma list, keeping the rows of any listed role;
+                                   --result <class>[,<class>...] narrows to the listed outcome classes — 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
+                                   -n, and --grep; --model <selector>[,...] keeps only the
+                                   runs that started on the listed models (the exact selectors --by model prints); --json prints the rows as
                                    machine-readable history data — ts, tokens, and costUsd
                                    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]
+                                   --by model groups the summary by the model each run started on instead
+                                   of by role; with --json, { models, total }
+  tumwater history <role> [<n>] [--last [--result <class>[,...]] [--model <selector>[,...]]] [--stat] [--patch] [--transcript [--prompt] [--grep <text>]] [--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
+                                   one (with no <role>, the newest finished run of any
+                                   role); --result <class>[,...] (with --last) picks the newest
+                                   run in the listed outcome classes instead (the listing's
+                                   --result classes; scans the role's last 200 runs);
+                                   --model <selector>[,...] (with --last) picks the newest
+                                   run that started on a listed model (the listing's --model
+                                   match; composes with --result);
+                                   --stat appends the commit's per-file git show --stat
+                                   summary; --patch appends the commit's full git show patch
+                                   (after --stat's summary when both are given);
+                                   --transcript appends the agent transcript of the
+                                   runs that started in that run's window;
+                                   --prompt (with --transcript) also shows each run's exact
+                                   prompt text;
+                                   --grep <text> (with --transcript) keeps only the transcript
+                                   entries containing the text, case-insensitively, under their
+                                   run's separator (like logs --transcript --grep);
+                                   --json prints the collector's payload
+  tumwater diff [-f/--follow] [--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> [--stat] [--json]
+                                   line; --json prints the {mainBranch, roles} roster;
+                                   -f/--follow repaints the same view every couple of seconds
+                                   until Ctrl+C or the process that started it exits, so a
+                                   backgrounded follow does not outlive its parent; it refuses --json
+  tumwater diff --role <id>[,<id>...] [--stat] [--path <path>] [-f/--follow] [--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 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 merge queue in execution order (oldest
+                                   \`git diff --stat\` summary instead; --path keeps only the commits, patch and
+                                   uncommitted edits under that repo-relative file or directory
+                                   (composes with --stat, --json and a comma list); --json prints the
+                                   collector's payload as machine-readable data; a comma list prints each listed
+                                   role's view in that order, separated by a blank line (--json: {mainBranch, roles})
+  tumwater diff --overlaps [--role <id>[,<id>...]] [--path <path>] [-f/--follow] [--json]
+                                   List each file two or more roles' pending changes touch
+                                   (committed ahead of main or uncommitted), one line per path
+                                   naming those roles; --role keeps only the files a listed
+                                   role holds, each still naming every holder; --path keeps only the files
+                                   at or under that repo-relative file or directory;
+                                   --json prints {mainBranch, state, overlaps}
+  tumwater queue [--role <id>[,<id>...]] [-f/--follow] [--json] [--cancel <n>] [--top <n>]
+                                   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]\`
@@ -156,8 +238,41 @@ Usage:
                                    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 [--ready] [--json]
+                                   (raw sha and numeric enqueuedAt, not the render's age); --role
+                                   keeps only the listed roles' merges (a base role id taking
+                                   its instances too), each under its position in the whole
+                                   queue; --json then lists only those entries;
+                                   -f/--follow repaints the queue every couple of seconds
+                                   until Ctrl+C or the process that started it exits, so a
+                                   backgrounded follow does not outlive its parent; it refuses --json;
+                                   --cancel <n> removes the Nth queued merge before it lands (and
+                                   its role's merge pin, so next-run recovery cannot re-enqueue it),
+                                   refusing an entry a live merge is merging and --role/-f;
+                                   --top <n> moves the Nth queued merge to the front of the
+                                   execution order (so it merges next when ready), preserving any
+                                   notBefore deferral, refusing an entry a live merge is merging and
+                                   --role/-f, and answering already-first for position 1
+  tumwater reviews [--accept <n>] [--role <id>[,<id>...]] [--status <state>[,<state>...]] [--json]
+                                   List the post-merge review queue (\.tumwater/state
+                                   /post-review.json) in FIFO order: one line per merged commit
+                                   waiting for its review — position, role, short sha, summary,
+                                   and either its rejected reasons
+                                   (\`[rejected — <reasons>]\`) or its
+                                   failed-review-run count (\`[N failed review runs]\`); an empty
+                                   queue prints \`post-merge review queue empty\`; --json prints
+                                   the normalized { pending: [...] } list for scripts; --role
+                                   keeps only the listed roles' entries (a base role id taking
+                                   its instances too), each under its position in the whole
+                                   queue; --status keeps only the entries in the listed states
+                                   (waiting, failing, rejected; an entry turned back is rejected
+                                   first), each under its position in the whole queue, and
+                                   composes with --role; --accept <n>
+                                   removes the Nth queued entry (the position \`tumwater reviews\`
+                                   prints) as deliberately accepted unreviewed, logging a warning;
+                                   it refuses an entry whose repair already merged (\`fixed\`);
+                                   no ready-repo gate for the read, a missing or torn file degrades
+                                   to the empty or well-formed list
+  tumwater backlog [--ready] [--grep <text>] [-f/--follow] [--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
@@ -167,12 +282,25 @@ Usage:
                                    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
+                                   picked (entries a role is working on stay); --grep keeps the
+                                   entries whose heading or body contains the text, case-insensitively;
+                                   -f/--follow repaints the backlog every couple of seconds until
+                                   Ctrl+C or the process that started it exits, so a backgrounded
+                                   follow does not outlive its parent; it refuses --json
+  tumwater quarantine [--json]    List the flake quarantine — the tests the review gate recorded
+                                   as failing then passing on the same tree
+                                   (.tumwater/state/quarantine.json), oldest first, each naming
+                                   its first-seen and last-seen age, flake count, and the BUGS.md
+                                   entry filed for it (or "not filed"); empty prints
+                                   "flake quarantine is empty"; --json prints the same rows as
+                                   { tests: [...] }; it is read-only — a test leaves the list only
+                                   when its filed bug leaves BUGS.md ## Open
+  tumwater archive [--json]        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
+                                   finished entry moves when its change commits;
+                                   --json prints what moved and the commit as data
   tumwater bug "<symptom>" [--json]
                                    File a bug into BUGS.md ## Open as you (stamped
                                    with today's date) and wake the bugfix role; --json prints
@@ -182,10 +310,11 @@ Usage:
                                    non-blank line is the symptom, the rest is the body kept
                                    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}
+                                   Lift the Refused, Waiting for the next failure, or a
+                                   Needs-review/Needs-replan note held past its threshold
+                                   (one per run) 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, lifted}
   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
@@ -206,11 +335,16 @@ Usage:
                                    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
+  tumwater bug --list [--ready] [--grep <text>] [--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, inProgress — as data; \`[working on it: …]\` marks an
-                                   entry a role is working on
+                                   entry a role is working on; --ready keeps only the entries
+                                   no hold keeps from being picked (entries a role is working
+                                   on stay), under their unfiltered numbers; --grep keeps the
+                                   entries whose heading or body contains the text,
+                                   case-insensitively
   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
@@ -233,9 +367,11 @@ Usage:
                                    the first non-blank line is the title, the rest is the body
                                    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
+                                   Lift the Refused, Waiting for the next failure, or a
+                                   Needs-review/Needs-replan note held past its threshold
+                                   (one per run) 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}
+                                   and wake the feature role; --json prints {file, title, lifted}
   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;
@@ -256,12 +392,17 @@ Usage:
                                    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
+  tumwater plan --list [--ready] [--grep <text>] [--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, 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
+                                   parts show as one line naming their positions; --ready keeps
+                                   only the entries no hold keeps from being picked (entries a
+                                   role is working on stay), under their unfiltered numbers;
+                                   --grep keeps the entries whose heading or body contains the
+                                   text, case-insensitively
   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
@@ -275,8 +416,11 @@ Usage:
   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}
+  tumwater questions [--grep <text>] [--json]
+                                   List open questions numbered (the read half of the
+                                   question outbox); --grep keeps the questions whose
+                                   heading or body contains the text, case-insensitively,
+                                   numbered as without it; --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
@@ -317,8 +461,8 @@ Usage:
   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), that model's declared context window and whether a run gets the compact
-                                   prompt, the min-run interval, enabled/paused state, and
+                                   configured), that model's declared context window, 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
@@ -362,6 +506,15 @@ Usage:
                                    for the base id
   tumwater role <id> --clear-thinking
                                    Clear that role's thinking level
+  tumwater role <id> --backend <id>
+                                   Set that role's backend (pi|claude|opencode|codex — the
+                                   agent that runs the model); a model that cannot pair with
+                                   the backend is refused (e.g. a claude backend with a
+                                   provider/model id, or a pi backend with a bare model id),
+                                   written to roles.<id>.backend for the base id
+  tumwater role <id> --clear-backend
+                                   Clear that role's backend (back to the team/tier
+                                   default backend)
   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
@@ -372,6 +525,12 @@ Usage:
                                    written to roles.<id>.instances for the base id
   tumwater role <id> --clear-instances
                                    Clear that role's instance count (back to 1)
+  tumwater role <id> --review-after-merge
+                                   Review that role's commits after they merge, written
+                                   to review.afterMerge (the base id for an instance)
+  tumwater role <id> --clear-review-after-merge
+                                   Review it before merge again, removing it from
+                                   review.afterMerge
   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...>
@@ -386,7 +545,11 @@ Usage:
                                    images: png, jpg, jpeg, gif, webp, bmp; each at most 5
                                    MiB — saved beside the inbox file for the role's next
                                    run)
-  tumwater prompt --list [--json]  Show inbox messages, numbered, grouped by role
+  tumwater prompt --list [--role <id>[,<id>...]] [--grep <text>] [--json]
+                                   Show inbox messages, numbered, grouped by role;
+                                   --role keeps only the listed roles' sections;
+                                   --grep <text> keeps only the messages containing the
+                                   text, case-insensitively, under the same numbers
                                    (--json prints the {prompts} array as
                                    machine-readable data)
   tumwater prompt --cancel <n>     Remove the Nth inbox message as --list shows them; when
@@ -410,33 +573,44 @@ Usage:
                                    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>]
+  tumwater reset-counters [--role <id>[,<id>...]]
                                    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]]
+  tumwater wake [--role <id>[,<id>...]] [--in <dur> | --cancel | --list [--json]]
                                    Wake sleeping roles — the named roles (or all) run
                                    within one poll; --in schedules the wake for later;
-                                   --cancel drops pending scheduled wakes;
+                                   --cancel drops pending scheduled wakes (the named roles' share);
                                    --list shows every pending scheduled wake, earliest first
                                    (--json for scripts)
-  tumwater reclaim [--dry-run]     Reclaim gitignored build outputs from every
+  tumwater reclaim [--dry-run [--json]]
+                                   Reclaim gitignored build outputs from every
                                    workspace; --dry-run lists each candidate with its idle age
-                                   and ignored-path count and cleans nothing
-  tumwater revert <sha>          Undo one merged change on main, committing the inverse
+                                   and ignored-path count and cleans nothing (--json for scripts)
+  tumwater revert <sha>|<role> <n>|<role> --last [--dry-run] [--json]
+                                   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)
+                                   branch, on an unknown or unmerged ref, and on a conflict;
+                                   --dry-run names the commit and the paths its inverse touches
+                                   and says whether it applies cleanly on main, writing nothing
+                                   (exit 1 when the revert would conflict or refuse); the run
+                                   forms revert the commit the run merged as, the sha
+                                   'history <role> <n>' names;
+                                   --json prints the preview or the new head as data
+  tumwater abort --role <id>[,<id>...]
+                                   Stop each named 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 roles (or just the named role) starting new
-                                   runs; --reason states why the whole team is paused (no
+  tumwater pause [--role <id>[,<id>...]] [--for <dur>] [--reason <text>]
+                                   Stop roles (or just the named roles) starting new
+                                   runs; --role takes a comma list, pausing each listed
+                                   role; --reason states why the whole team is paused (no
                                    per-role reason); --for auto-resumes (capped at 90d)
-  tumwater resume [--role <id>]    Lift a team or per-role pause
+  tumwater resume [--role <id>[,<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;
@@ -450,6 +624,8 @@ Usage:
   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 completion --config-value <key>  Print what config set <key> <value> completes for a discrete-valued key (boolean/backend/model/thinking); nothing for a free-form value
+  tumwater completion --models     Print the model selectors history --model completes (those the recent runs started on; nothing when the log is unreadable)
   tumwater help [<command>]        Show all commands, or one command's usage
   tumwater version                 Print the version
 
@@ -461,7 +637,7 @@ sleep while there is nothing to do and wake when main moves. Everything is local
  * suggest. Case-insensitive closest-match over the commands helpStanzas(HELP) names, capped
  * at two edits — a typo's distance, not a different word's — so only a near miss gets a hint
  * and the suggestion can never fire as an auto-correction. Deriving the candidates from the
- * help text (not a hand-kept list) means a new command is suggestible the tick it gains a
+ * help text (not a hand-kept list) means a new command is suggestible the run it gains a
  * stanza; the distance mechanics are text/suggest.ts's suggestClosest, shared with the config-key
  * suggestion. */
 export function suggestCommand(input, help = HELP) {
@@ -491,7 +667,7 @@ export function helpStanzas(help = HELP) {
 }
 /** 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" };
+export const HIDDEN_COMMAND_ALIASES = { run: "start", tick: "history" }; // retired-name-ok: legacy name
 /** 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) {