tumwater 0.3.0 → 0.4.0

package/dist/src/cli/completion.js

@@ -10,6 +10,7 @@ import { templateIds } from "../init/init-templates.js";
 import { DOCTOR_CHECK_NAMES } from "../doctor/doctor-check-names.js";
 import { allRoleIds } from "../roles/roles.js";
 import { EVENT_TYPE_LABELS } from "../events/event-labels.js";
+import { POST_REVIEW_STATES } from "../review/post-merge-review-render.js";
 import { HELP, helpStanzas } from "./help.js";
 export const SUPPORTED_SHELLS = ["bash", "zsh", "fish"];
 /** The completable words of a stanza's usage part: the text after `tumwater <command>` up to the
@@ -162,6 +163,11 @@ const EVENT_TYPE_CODES = Object.keys(EVENT_TYPE_LABELS).sort();
  * vocabulary the way `--type` and `--result` complete theirs. One source, so a new level
  * completes the moment THINKING_LEVELS grows. */
 const THINKING_LEVEL_WORDS = [...THINKING_LEVELS];
+/** The review states `reviews --status` filters by: the canonical POST_REVIEW_STATES set,
+ * spread preserving its insertion order, so `--status` completes the same vocabulary
+ * `parseReviewStatusList` accepts. One source, so a new state completes the moment
+ * POST_REVIEW_STATES grows. */
+const REVIEW_STATE_WORDS = [...POST_REVIEW_STATES];
 /** The doctor check names, each in plain double quotes, for the scripts to loop over. The names
  * hold no `"`, `$`, backtick or `\`, so plain double quotes are exact; a test pins this. */
 const DOCTOR_CHECK_WORDS = DOCTOR_CHECK_NAMES.map((n) => `"${n}"`).join(" ");
@@ -231,10 +237,18 @@ function bashScript(help) {
         `    _tumwater_list "${EVENT_TYPE_CODES.join(" ")}" "$cur"`,
         `    return 0`,
         `  fi`,
+        `  if [ "$prev" = "--status" ]; then`,
+        `    _tumwater_list "${REVIEW_STATE_WORDS.join(" ")}" "$cur"`,
+        `    return 0`,
+        `  fi`,
         `  if [ "$prev" = "--thinking" ]; then`,
         `    COMPREPLY=( $(compgen -W "${THINKING_LEVEL_WORDS.join(" ")}" -- "$cur") )`,
         `    return 0`,
         `  fi`,
+        `  if [ "$prev" = "--backend" ]; then`,
+        `    COMPREPLY=( $(compgen -W "${BACKEND_IDS.join(" ")}" -- "$cur") )`,
+        `    return 0`,
+        `  fi`,
         `  if [ "$prev" = "--by" ]; then`,
         `    COMPREPLY=( $(compgen -W "${HISTORY_SUMMARY_GROUPS.join(" ")}" -- "$cur") )`,
         `    return 0`,
@@ -276,7 +290,8 @@ function bashScript(help) {
     ].join("\n");
 }
 /** The value suffix a fish flag line carries: what completes after the flag. `--role`, `--result`
- * and `--type` take comma lists, so they complete per item through `__fish_complete_list`,
+ * `--type` and `--status` take comma lists, so they complete per item through
+ * `__fish_complete_list`,
  * skipping the items already listed. */
 function fishFlagValue(command, flag) {
     if (flag === "--role")
@@ -291,8 +306,12 @@ function fishFlagValue(command, flag) {
         return ` -x -a "(__fish_complete_list , __tumwater_results)"`;
     if (flag === "--type")
         return ` -x -a "(__fish_complete_list , __tumwater_types)"`;
+    if (flag === "--status")
+        return ` -x -a "(__fish_complete_list , __tumwater_review_states)"`;
     if (flag === "--thinking")
         return ` -x -a "${THINKING_LEVEL_WORDS.join(" ")}"`;
+    if (flag === "--backend")
+        return ` -x -a "${BACKEND_IDS.join(" ")}"`;
     if (flag === "--by")
         return ` -x -a "${HISTORY_SUMMARY_GROUPS.join(" ")}"`;
     // `role --model` completes the closed tier set; `history --model` completes the log's selectors.
@@ -314,6 +333,7 @@ function fishScript(help) {
         `function __tumwater_results; printf '%s\\n' ${Object.values(HISTORY_RESULT_FLAG_NAMES).join(" ")} | __tumwater_unlisted; end`,
         `function __tumwater_models; tumwater completion --models 2>/dev/null | __tumwater_unlisted; end`,
         `function __tumwater_types; printf '%s\\n' ${EVENT_TYPE_CODES.join(" ")} | __tumwater_unlisted; end`,
+        `function __tumwater_review_states; printf '%s\\n' ${REVIEW_STATE_WORDS.join(" ")} | __tumwater_unlisted; end`,
         `complete -c tumwater -n __fish_use_subcommand -a "${spec.commands.join(" ")}"`,
     ];
     for (const command of spec.commands) {

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

@@ -50,15 +50,24 @@ function screenOperableKey(root, key) {
     const { config, error } = loadConfigSafe(root);
     if (config === undefined)
         fail(error); // validateConfig's message, via the standard fail()
-    if (parsed.kind === "map" || parsed.kind === "role") {
-        const id = parsed.kind === "map" ? parsed.role : parsed.id;
+    if (parsed.kind === "role") {
         const ids = knownRoleIds(config);
-        if (!ids.includes(id))
-            fail(unknownRoleMessage(id, ids));
-        if (parsed.kind === "role") {
-            const fieldError = unknownRoleFieldError(parsed.id, parsed.field);
-            if (fieldError)
-                fail(fieldError);
+        if (!ids.includes(parsed.id))
+            fail(unknownRoleMessage(parsed.id, ids));
+        const fieldError = unknownRoleFieldError(parsed.id, parsed.field);
+        if (fieldError)
+            fail(fieldError);
+    }
+    else if (parsed.kind === "map") {
+        // Only role-keyed maps check the role catalog. `maxConcurrentPerProvider.<provider>` is
+        // keyed by provider, not a role id, and `config set` writes it without the role check —
+        // so get/unset must agree, or set would succeed while get/unset refused the provider as
+        // an "unknown role". A typo'd role id in the other two maps is refused the same way set's
+        // validator treats it.
+        if (parsed.map !== "maxConcurrentPerProvider") {
+            const ids = knownRoleIds(config);
+            if (!ids.includes(parsed.role))
+                fail(unknownRoleMessage(parsed.role, ids));
         }
     }
     return { parsed, config };

package/dist/src/cli/help.js

@@ -4,8 +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";
-/** 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:
@@ -84,12 +85,22 @@ Usage:
                                    (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]
+  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 unless --kill-orphans, which first kills the
-                                   orphaned processes the orphans check lists, each with
-                                   its descendants; 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
@@ -112,7 +123,7 @@ 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>] [--until <duration>] [--role <id>[,<id>...]] [--grep <text>] [--type <event 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); --until ends that
                                    window the given duration ago (requires --since); --grep shows
@@ -123,7 +134,10 @@ Usage:
                                    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
@@ -238,6 +252,26 @@ Usage:
                                    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
@@ -253,6 +287,14 @@ Usage:
                                    -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
@@ -268,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
@@ -324,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;
@@ -461,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
@@ -471,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...>

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

@@ -1,11 +1,11 @@
 import { fail, say, sayJsonLine } from "./cli-output.js";
 import { hasFollowFlag, LOGS_TRANSCRIPT_VALUE_ERROR } from "./cli-flag-specs.js";
-import { durationLabel, failRivalShapes, flagValue, parseCountFlag, parseGrepFlag, parseRoleListScope, parseRoleScope, parseSinceFlag, parseTypeFlag } from "./cli-args.js";
+import { durationLabel, failRivalShapes, failUntilShorterThanSince, flagValue, parseCountFlag, parseGrepFlag, parseRoleListScope, parseRoleScope, parseSinceFlag, parseTypeFlag } from "./cli-args.js";
 import { LOGS_SINCE_MAX_MS, readEventsSince, SPARSE_WINDOW_NOTE, } from "../events/event-window.js";
 import { compareCodeUnits, increment } from "../collections.js";
 import { eventTypeTally } from "../events/event-tally.js";
 import { eventRole, parseEventLine, readEventsTailWithEnd } from "../events/event-read.js";
-import { eventMatchesGrep, formatEvent } from "../events/event-format.js";
+import { eventMatchesGrep, eventResult, formatEvent } from "../events/event-format.js";
 import { canonicalEventType } from "../events/event-legacy.js";
 import { EVENT_TYPE_LABELS, eventTypeLabel } from "../events/event-labels.js";
 import { followFile } from "../files/tail.js";
@@ -15,6 +15,7 @@ import { typoSuffix } from "../text/suggest.js";
 import { splitCommaList } from "../text/text.js";
 import { createTranscriptFilter, createTranscriptRenderer } from "../ui/transcript.js";
 import { readTranscriptTail } from "../ui/transcript-tail.js";
+import { isNotableEvent } from "../ui/tone.js";
 import { eventsLogPath, piLogPath } from "../paths.js";
 /** The read-only observing half of the CLI's non-dispatch commands: `tumwater logs` and its
  * `--transcript` view, split out of cli.ts so the entry point stays a dispatch table. Unlike
@@ -147,9 +148,18 @@ export async function cmdLogs(root, args, seams = {}) {
         : (e) => roleInScope(eventRole(e), roles);
     if (roles !== null)
         rejectTranscriptViewRival(rest, "--role", true);
+    // `--notable` culls routine bookkeeping events the way the dashboard Activity feed's Notable
+    // choice does (src/ui/tone.ts eventKind): only non-routine rows pass the feed. One harness-side
+    // rule (isNotableEvent) shared with the TUI Activity pane, so the CLI feed and the pane cannot
+    // disagree about what a notable filter hides. It composes with --since, --grep, --type, --role,
+    // -n, -f, --count and --json, and — like --json/--count/--type/--since — is a rival only of the
+    // --transcript transcript view.
+    const notable = rest.includes("--notable");
+    rejectTranscriptViewRival(rest, "--notable", notable);
     const feedFilter = (e) => (grepLower === null || eventMatchesGrep(e, grepLower)) &&
         (typeFilter === null || typeFilter(e)) &&
-        (roleFilter === null || roleFilter(e));
+        (roleFilter === null || roleFilter(e)) &&
+        (!notable || isNotableEvent(e.type, eventResult(e)));
     // Empty-match prose: grep/type keep their wording when given; a role-only filter names the roles.
     const roleEmpty = roles === null ? "" : `no events from ${roles.join(", ")}`;
     const filtersGrepOrType = grepPattern !== null || type !== null;
@@ -180,10 +190,7 @@ export async function cmdLogs(root, args, seams = {}) {
     // both flags. (--prompt requires --transcript, so it is excluded with it.)
     const ms = parseSinceFlag(rest, "logs --since", LOGS_SINCE_MAX_MS);
     const untilMs = parseSinceFlag(rest, "logs --until", LOGS_SINCE_MAX_MS, "--until");
-    if (untilMs !== null && ms === null)
-        fail("logs --until requires --since");
-    if (untilMs !== null && ms !== null && untilMs >= ms)
-        fail(`logs --until (${durationLabel(untilMs)}) must be shorter than --since (${durationLabel(ms)})`);
+    failUntilShorterThanSince("logs", untilMs, ms);
     if (ms !== null) {
         if (follow)
             failRivalShapes("logs --since", "-f/--follow", 'follow means "from now on"; --since shows a bounded past window');
@@ -204,7 +211,9 @@ export async function cmdLogs(root, args, seams = {}) {
             // In JSON mode an empty result answers silently — an empty output IS the machine-readable
             // answer, and prose would corrupt a consumer's NDJSON stream.
             if (!json) {
-                if (grepPattern !== null && type !== null)
+                if (notable && grepPattern === null && type === null && roles === null)
+                    say(`no notable events ${windowPhrase}`);
+                else if (grepPattern !== null && type !== null)
                     say(`no events matching "${grepPattern}" or ${typeEmpty(type, typePieces)}`);
                 else if (type !== null)
                     say(typeEmpty(type, typePieces));
@@ -251,7 +260,7 @@ export async function cmdLogs(root, args, seams = {}) {
     // the tail-with-end shape (not the per-poll cached readEvents) so the follow below can seed
     // from the byte end this very read covered instead of a later stat of the file.
     const tail = readEventsTailWithEnd(root, limit);
-    const shown = grepLower !== null || type !== null || roleFilter !== null ? tail.events.filter(feedFilter) : tail.events;
+    const shown = grepLower !== null || type !== null || roleFilter !== null || notable ? tail.events.filter(feedFilter) : tail.events;
     // `--count` over the -n view answers with the tally of exactly the filtered rows the plain
     // view would print, and carries over the plain view's empty-match prose below (a `--type`
     // or `--grep` that matches nothing names its value; an empty unfiltered -n view prints
@@ -259,8 +268,10 @@ export async function cmdLogs(root, args, seams = {}) {
     if (count) {
         if (shown.length !== 0)
             sayTally(shown, json);
-        else if (!json && (filtersGrepOrType || roles !== null)) {
-            if (grepPattern !== null && type !== null)
+        else if (!json && (filtersGrepOrType || roles !== null || notable)) {
+            if (notable && grepPattern === null && type === null && roles === null)
+                say("no notable events");
+            else if (grepPattern !== null && type !== null)
                 say(`no events matching "${grepPattern}" or ${typeEmpty(type, typePieces)}`);
             // Type-empty gets the hint (only the type branch); a grep-only empty stays the bare
             // no-match line, because a free-text pattern is not an event type to suggest against.
@@ -277,8 +288,10 @@ export async function cmdLogs(root, args, seams = {}) {
         // The empty-match line is prose: in JSON mode the empty output is the answer. It fires
         // for either filter, naming the flag's value(s) whose match came up empty so the operator
         // knows what to loosen.
-        if (shown.length === 0 && !json && (filtersGrepOrType || roles !== null)) {
-            if (grepPattern !== null && type !== null)
+        if (shown.length === 0 && !json && (filtersGrepOrType || roles !== null || notable)) {
+            if (notable && grepPattern === null && type === null && roles === null)
+                say("no notable events");
+            else if (grepPattern !== null && type !== null)
                 say(`no events matching "${grepPattern}" or ${typeEmpty(type, typePieces)}`);
             // Type-empty gets the hint (only the type branch); a grep-only empty stays the bare
             // no-match line, because a free-text pattern is not an event type to suggest against.

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

@@ -148,7 +148,13 @@ export async function cmdQuestions(root, args) {
         }
         if (arg.startsWith("--") && arg !== "--json") {
             rejectEqualsForm(arg, [JSON_FLAG, FILE_SPEC, { names: ["--show"], value: true, valueName: "<n>" }, { names: ["--grep"], value: true, valueName: "<text>" }]);
-            fail(`unknown argument: ${arg} (valid flags for tumwater questions: --json, --file, --answered, --show, --grep)`);
+            // The complete flag set (this gate only sees `--`-flags, but `-n` is a real flag the
+            // list should not omit) plus the same did-you-mean hint the sibling commands'
+            // unknown-argument gate (cli-flag-specs's failUnknownArgument) attaches, so a mistyped
+            // `--ansered` names `--answered` instead of only printing the valid list — the missing
+            // treatment the questions gate was the one unknown-argument caller without.
+            const spellings = ["--json", "--file", "--answered", "--show", "--grep", "-n"];
+            fail(`unknown argument: ${arg} (valid flags for tumwater questions: ${spellings.join(", ")})${typoSuffix(arg, spellings)}`);
         }
         if (!numbered) {
             // The position is a plain-decimal positive integer (parsePositiveInt's rule, the same

package/dist/src/cli.js

@@ -13,10 +13,11 @@
  * ready-repo gate. An error escaping main() funnels through its catch to fail(errorMessage(err)),
  * the CLI's one error path. */
 import { parseCountFlag, parseGrepFlag, parseModelFlag, parseResultFlag } from "./cli/cli-args.js";
-import { grepFlagSpec, GUI_FLAG_SPECS, JSON_FLAG, LAST_FLAG, N_FLAG, rejectUnknownArgs, resultFlagSpec, modelFlagSpec, byFlagSpec, LOGS_TRANSCRIPT_FLAG, ROLE_FLAG, START_FLAG_SPECS, sinceFlagSpec, untilFlagSpec, STAT_FLAG, PATCH_FLAG, PROMPT_FLAG, TRANSCRIPT_FLAG, SUMMARY_FLAG, COUNT_FLAG, typeFlagSpec, DRY_RUN_FLAG, FORCE_FLAG, FOLLOW_FLAG, STOP_CANCEL_FLAG, STOP_IN_FLAG, REPROBE_FLAG, PROBLEMS_FLAG, KILL_ORPHANS_FLAG, } from "./cli/cli-flag-specs.js";
+import { grepFlagSpec, GUI_FLAG_SPECS, JSON_FLAG, LAST_FLAG, N_FLAG, rejectUnknownArgs, resultFlagSpec, modelFlagSpec, byFlagSpec, LOGS_TRANSCRIPT_FLAG, ROLE_FLAG, START_FLAG_SPECS, sinceFlagSpec, untilFlagSpec, STAT_FLAG, PATCH_FLAG, PROMPT_FLAG, TRANSCRIPT_FLAG, SUMMARY_FLAG, COUNT_FLAG, NOTABLE_FLAG, typeFlagSpec, DRY_RUN_FLAG, FORCE_FLAG, FOLLOW_FLAG, STOP_CANCEL_FLAG, STOP_IN_FLAG, REPROBE_FLAG, PROBLEMS_FLAG, KILL_ORPHANS_FLAG, COMMIT_BACKLOG_FLAG, RESYNC_INSTALL_FLAG, DROP_BROKEN_PINS_FLAG, RETIRE_LEFTOVERS_FLAG, } from "./cli/cli-flag-specs.js";
 import { fail, say, sayJsonOrRender } from "./cli/cli-output.js";
 import { historyTrailForm, parseDoctorChecks, parsePromptArgs, peelPositionals } from "./cli/cli-command-args.js";
 import { refuseTeamWorkspace, requireReadyRepo } from "./cli/cli-repo-gate.js";
+import { loadConfigSafe } from "./config/config.js";
 import { repoToplevel } from "./git/git.js";
 import { didYouMean } from "./text/suggest.js";
 import { errorMessage, gotSuffix, stripTerminalControls } from "./text/text.js";
@@ -171,7 +172,7 @@ async function main() {
             // No requireReadyRepo gate: doctor's job is to report WHY the environment isn't ready,
             // so it must run outside a git repo and print fail lines rather than throwing.
             const { positionals: checkNames, rest: doctorFlags } = peelPositionals(args);
-            rejectUnknownArgs("doctor", doctorFlags, [JSON_FLAG, REPROBE_FLAG, PROBLEMS_FLAG, KILL_ORPHANS_FLAG]);
+            rejectUnknownArgs("doctor", doctorFlags, [JSON_FLAG, REPROBE_FLAG, PROBLEMS_FLAG, KILL_ORPHANS_FLAG, COMMIT_BACKLOG_FLAG, RESYNC_INSTALL_FLAG, DROP_BROKEN_PINS_FLAG, RETIRE_LEFTOVERS_FLAG]);
             const only = parseDoctorChecks(checkNames);
             const { runDoctor } = await import("./doctor/doctor.js");
             let orphanKill;
@@ -185,6 +186,59 @@ async function main() {
                     say("");
                 }
             }
+            let backlogCommit;
+            if (args.includes("--commit-backlog")) {
+                const { commitUncommittedBacklog, backlogCommitLines } = await import("./doctor/doctor-backlog.js");
+                const { config } = loadConfigSafe(root); // the report's own config, so base resolution and the off-base skip match the `uncommitted backlog` row's
+                backlogCommit = await commitUncommittedBacklog(root, config);
+                // The text form prints the commits before the report; --json keeps stdout one document.
+                if (!args.includes("--json")) {
+                    for (const line of backlogCommitLines(backlogCommit))
+                        say(line);
+                    say("");
+                }
+            }
+            let resyncInstall;
+            if (args.includes("--resync-install")) {
+                const { resyncRootInstall, rootInstallResyncLines } = await import("./build/dep-install.js");
+                resyncInstall = await resyncRootInstall(root);
+                // The text form prints the re-sync outcome before the report; --json keeps stdout one
+                // document, carrying the result as `resyncInstall` on the payload.
+                if (!args.includes("--json")) {
+                    for (const line of rootInstallResyncLines(resyncInstall))
+                        say(line);
+                    say("");
+                }
+            }
+            let brokenPinDrop;
+            if (args.includes("--drop-broken-pins")) {
+                const { dropBrokenPins, brokenPinDropLines } = await import("./doctor/doctor-contention-checks.js");
+                brokenPinDrop = await dropBrokenPins(root);
+                // The text form prints the drop before the report; --json keeps stdout one document,
+                // carrying the result as `brokenPinDrop` on the payload.
+                if (!args.includes("--json")) {
+                    const lines = brokenPinDropLines(brokenPinDrop);
+                    for (const line of lines)
+                        say(line);
+                    if (lines.length > 0)
+                        say("");
+                }
+            }
+            let leftoverRetire;
+            if (args.includes("--retire-leftovers")) {
+                const { retireLeftovers, leftoverRetireLines } = await import("./doctor/doctor-contention-checks.js");
+                const { config } = loadConfigSafe(root); // the row's own config, so the reap and the report agree on what is retirable
+                leftoverRetire = await retireLeftovers(root, config);
+                // The text form prints the retire lines before the report; --json keeps stdout one
+                // document, carrying the result as `leftoverRetire` on the payload.
+                if (!args.includes("--json")) {
+                    const lines = leftoverRetireLines(leftoverRetire);
+                    for (const line of lines)
+                        say(line);
+                    if (lines.length > 0)
+                        say("");
+                }
+            }
             const { renderDoctor, renderDoctorProblems, problemsOnly } = await import("./doctor/doctor-render.js");
             // The terminal probes unclaimed-verified models by default (7-day cache); --reprobe
             // forces every claimed model. The TUI/GUI call runDoctor with the default "never", so a
@@ -198,10 +252,14 @@ async function main() {
             // hands --json the filtered one; the exit code below reads the full report either way.
             // --kill-orphans adds the kill result to the JSON object as `orphanKill`.
             const withKill = (payload) => (orphanKill === undefined ? payload : { ...payload, orphanKill });
+            const withBacklogCommit = (payload) => backlogCommit === undefined ? withKill(payload) : withKill({ ...payload, backlogCommit });
+            const withResyncInstall = (payload) => resyncInstall === undefined ? withBacklogCommit(payload) : withBacklogCommit({ ...payload, resyncInstall });
+            const withBrokenPinDrop = (payload) => brokenPinDrop === undefined ? withResyncInstall(payload) : withResyncInstall({ ...payload, brokenPinDrop });
+            const withLeftoverRetire = (payload) => leftoverRetire === undefined ? withBrokenPinDrop(payload) : withBrokenPinDrop({ ...payload, leftoverRetire });
             if (args.includes("--problems"))
-                sayJsonOrRender(args, args.includes("--json") ? withKill(problemsOnly(report)) : report, renderDoctorProblems);
+                sayJsonOrRender(args, args.includes("--json") ? withLeftoverRetire(problemsOnly(report)) : report, renderDoctorProblems);
             else
-                sayJsonOrRender(args, args.includes("--json") ? withKill(report) : report, renderDoctor);
+                sayJsonOrRender(args, args.includes("--json") ? withLeftoverRetire(report) : report, renderDoctor);
             if (report.checks.some((c) => c.level === "fail"))
                 process.exitCode = 1; // Warnings never fail the exit.
             break;
@@ -217,6 +275,7 @@ async function main() {
                 typeFlagSpec(TYPE_VALUE_ERROR),
                 JSON_FLAG,
                 COUNT_FLAG,
+                NOTABLE_FLAG,
                 ROLE_FLAG,
                 LOGS_TRANSCRIPT_FLAG,
                 PROMPT_FLAG,
@@ -262,9 +321,15 @@ async function main() {
         case "queue":
             await (await import("./cli/cli-query-commands.js")).cmdQueue(root, args);
             break;
+        case "reviews":
+            await (await import("./cli/cli-review-commands.js")).cmdReviews(root, args);
+            break;
         case "backlog":
             await (await import("./cli/cli-query-commands.js")).cmdBacklog(root, args);
             break;
+        case "quarantine":
+            await (await import("./cli/cli-query-commands.js")).cmdQuarantine(root, args);
+            break;
         case "archive":
             rejectUnknownArgs("archive", args, [JSON_FLAG]);
             await requireReadyRepo(root);
@@ -463,7 +528,7 @@ async function main() {
                 const topic = helpTopic(name);
                 if (topic === null) {
                     const suggestion = suggestCommand(name);
-                    fail(`no help topic: ${name}${didYouMean(suggestion)} (try \`tumwater help\` for the full command list)`);
+                    fail(`no help topic: ${JSON.stringify(name)}${didYouMean(suggestion)} (try \`tumwater help\` for the full command list)`);
                 }
                 say(topic);
             }
@@ -474,7 +539,7 @@ async function main() {
         }
         default: {
             const suggestion = suggestCommand(command);
-            fail(`unknown command: ${command}${didYouMean(suggestion)} (try \`tumwater help\`)`);
+            fail(`unknown command: ${JSON.stringify(command)}${didYouMean(suggestion)} (try \`tumwater help\`)`);
         }
     }
 }

package/dist/src/collections.js

@@ -31,14 +31,32 @@ export function getOrCreate(map, key, make) {
     map.set(key, created);
     return created;
 }
+/** Filter a list by a keep predicate, returning the kept items and each kept item's 1-based
+ * position in the original list — the single home of the "keep some, but number by the whole
+ * list" step, shared by the two queue-scope twins `scopeMergeQueue` (src/merge/
+ * merge-queue-render.ts) and `scopePostReviews` (src/review/post-merge-review-render.ts), so
+ * `tumwater queue --role` and `tumwater reviews --role` keep the same whole-queue positions
+ * a later position-addressed verb (`--cancel`, `--accept`) still addresses. The predicate runs
+ * once per item, in input order; positions run 1..length, not a kept-only renumbering. */
+export function filterKeepPositions(items, keep) {
+    const positions = [];
+    const kept = items.filter((item, i) => {
+        const isKept = keep(item);
+        if (isKept)
+            positions.push(i + 1);
+        return isKept;
+    });
+    return { kept, positions };
+}
 /** Increment a Map counter, seeding a missing key at 1 — the single home of the
  * `map.set(k, (map.get(k) ?? 0) + 1)` step, shared by the failure-spread kind tally
  * (src/team/failure-spread.ts), the diff multiset's line tally (merge/merge-diff.ts), the
- * section-title tally (backlog/backlog-structure.ts), the once-summary outcome tally
- * (cli/cli-start.ts), the logs' per-type tally (cli/log-commands.ts), the flaky-check tally
+ * section-title tally (backlog/backlog-structure.ts), the logs' per-type tally
+ * (cli/log-commands.ts), the flaky-check tally
  * (doctor/doctor-project-checks.ts), and the multi-runner base tally
- * (orchestrator/orchestrator-scheduling.ts), so those sites cannot drift on how a missing key is
- * seeded. */
+ * (orchestrator/orchestrator-scheduling.ts) — the exit-summary round's outcome tally
+ * (cli/cli-start-summary.ts) seeds its own copy of this step inline — so those sites cannot
+ * drift on how a missing key is seeded. */
 export function increment(map, key) {
     map.set(key, (map.get(key) ?? 0) + 1);
 }
@@ -118,6 +136,15 @@ export function lowerMedian(values) {
     const sorted = [...values].sort((a, b) => a - b);
     return sorted[Math.floor((sorted.length - 1) / 2)];
 }
+/** Most-days-waited-first comparator, ties in ascending index (file order) — `b.days - a.days ||
+ * a.index - b.index`, the single home of that one-line ordering. Shared by the stale-bug
+ * alert (src/ui/status-payload.ts's staleOpenBugs) and the stale-waiting-bug doctor row
+ * (src/doctor/doctor-backlog-bugs.ts's staleWaitingBugRows), which both build `{index, days}`
+ * rows off the same backlog scan, so the two cannot drift on how ties order. The generic holds
+ * any row type carrying both fields; a row without a natural index passes its first-seen order. */
+export function byDaysThenIndex(a, b) {
+    return b.days - a.days || a.index - b.index;
+}
 /** Ascending string comparator by UTF-16 code unit — the locale-independent order a bare `.sort()`
  * uses, unlike `localeCompare` (which `rankByCount` uses for its tiebreak). Used directly by
  * src/cli/cli-start-summary.ts, src/cli/log-commands.ts and src/history/history-data.ts, and by

package/dist/src/config/config-editable-keys.js

@@ -35,4 +35,7 @@ export const EDITABLE_CONFIG_KEYS = [
     // The per-backend section (plans/agent-backends.md, part 4a/7): the whole `agents` object is
     // edited here as JSON. The CLI's dotted `backends.<id>.bin`/`.args` merge one field at a time.
     "backends",
+    // The declared check (plans/portability.md §6/7, the no-check row): its Settings row is the
+    // surfaced remedy for the amber `no-check` alert — set `check.command` and the alert clears.
+    "check",
 ];

package/dist/src/config/config-fallbacks.js

@@ -19,8 +19,9 @@ import { FALLBACK_REVIEW_TIMEOUT_S, REVIEW_TIMEOUT_S, configForRole, isTierName,
  * claude + pi fleets, part 2/4"): the backend is the step's own, else its tier primary's
  * resolved backend (the tier entry's, else the top level's, else pi). A pair routed to a
  * non-pi backend carries that backend as `backend` and its name as `provider` — the key the
- * budget gate's handback (gate-polls.ts's runOnPair against the run's seamHoldKey capture,
- * runner-run.ts's setRunPair) matches on — and the id passes to it as written (routeModel); a
+ * budget gate's handback (src/budget/budget-wiring.ts's runOnPair against the run's
+ * seamHoldKey capture, runner-run.ts's setRunPair) matches on — and the id passes to it as
+ * written (routeModel); a
  * pi pair keeps its own provider (a bare pi selector keeps undefined). */
 function seamKeyedPairFields(config, tier, provider, model, thinking, stepBackend) {
     const backend = stepBackend ?? topTierBackend(config, tier) ?? config.backend ?? "pi";