tumwater 0.2.0 → 0.4.0

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

@@ -3,11 +3,21 @@
  * `## Open` to `## Answered` with a dated operator answer. The markdown surgery itself — the
  * fence-aware `### ` block cut and the `## Answered` skeleton — lives in src/backlog/
  * question-answer.ts (the shared QUESTIONS.md core the TUI and dashboard also call); this module
- * is only the command's say/fail/editor jacket over that core, imported by src/cli/
- * cli-query-commands.ts.
+ * is the command's argument scan, say/fail/editor jacket and commit-and-wake tail over that core,
+ * routed to by src/cli.ts.
  */
-import { fail, say, sayJson } from "./cli-output.js";
-import { openQuestionList, questionListPayload, UNCLOSED_FENCE_MESSAGE, tryAnswerQuestion } from "../backlog/question-answer.js";
+import { fail, say, sayJson, warnIfUncommitted } from "./cli-output.js";
+import { parseCountFlag, parsePositionFlag, rejectRepeatFlag } from "./cli-args.js";
+import { JSON_FLAG, rejectEqualsForm } from "./cli-flag-specs.js";
+import { refuseTeamWorkspace } from "./cli-repo-gate.js";
+import { promptFileValue, readPromptFileArg } from "./cli-command-args.js";
+import { editInEditor } from "./cli-editor.js";
+import { gotSuffix, parsePositiveInt } from "../text/text.js";
+import { typoSuffix } from "../text/suggest.js";
+import { commitOperatorBacklogEdit } from "../backlog/backlog-commit.js";
+import { stampedSubject } from "../git/commit-message.js";
+import { wakeQuestionAsker } from "../operator/operator-intent.js";
+import { answeredQuestionAt, answeredQuestionCount, answeredQuestionList, answeredQuestionPayload, openQuestionAt, openQuestionList, questionListPayload, renderShownQuestion, UNCLOSED_FENCE_MESSAGE, tryAnswerQuestion } from "../backlog/question-answer.js";
 import { bodyStructureProblem, normalizeEntryBody } from "../backlog/backlog-write.js";
 /** The `tumwater questions answer` entry point: `tryAnswerQuestion` without a title check, its
  * refusals mapped to `fail` (exit 1) with the CLI's wording. Returns the answered question's
@@ -32,7 +42,7 @@ function answeredOrFail(n, outcome) {
 /** `tumwater questions answer <n> --file <path>`: the decision's lines kept (normalizeEntryBody),
  * behind the same structural guard `plan --file` uses, so a stray `## ` line cannot grow a
  * phantom section. Refusals exit 1 through `fail`. */
-export function answerQuestionFromText(root, n, text, expectedTitle) {
+function answerQuestionFromText(root, n, text, expectedTitle) {
     const body = normalizeEntryBody(text);
     if (body === "")
         fail("questions answer needs a decision: the file is blank");
@@ -45,12 +55,12 @@ export function answerQuestionFromText(root, n, text, expectedTitle) {
 export const ANSWER_EDITOR_CUT = "<!-- tumwater: write your decision above this line; this line and everything below it are dropped -->";
 /** The editor buffer for bare `questions answer <n>`: an empty decision area, the cut line, then
  * the question's heading and body for reference. */
-export function answerEditorBuffer(title, body) {
+function answerEditorBuffer(title, body) {
     return ["", "", ANSWER_EDITOR_CUT, `### ${title}`, body].join("\n");
 }
 /** The decision an edited `answerEditorBuffer` holds: the text before the first cut line (all of
  * it when the operator deleted the line). */
-export function decisionFromEditorBuffer(text) {
+function decisionFromEditorBuffer(text) {
     const lines = text.split("\n");
     const cut = lines.findIndex((l) => l.trim() === ANSWER_EDITOR_CUT);
     return (cut === -1 ? lines : lines.slice(0, cut)).join("\n");
@@ -66,9 +76,200 @@ export function sayAnswered(position, title, json, decision) {
 /** One entry point for the list modes so cli.ts stays a dispatcher: --json prints the payload
  * document (an empty outbox still prints it), prose prints the numbered lines or the empty
  * line. */
-export function sayQuestionList(root, json) {
+function sayQuestionList(root, json, pattern) {
     if (json)
-        sayJson(questionListPayload(root));
+        sayJson(questionListPayload(root, pattern));
     else
-        say(openQuestionList(root));
+        say(openQuestionList(root, pattern));
+}
+/** `questions answer`'s `--file <path>` flag: the decision comes from the file, lines kept. */
+const FILE_SPEC = { names: ["--file"], value: true, valueName: "<path>" };
+/** `tumwater questions`: list open questions, or answer one with `answer <n> <decision>`. */
+export async function cmdQuestions(root, args) {
+    // No requireReadyRepo gate, like backlog: the reader degrades to an empty list on a
+    // missing QUESTIONS.md, so the command inspects any directory instead of refusing (a team
+    // workspace still refuses).
+    // The answer form's decision is free-form prose, so peelPositionals cannot route the
+    // tokens: a decision word may begin with a single dash (`questions answer 1 "-50% spend
+    // cap"`), and peelPositionals would hand it to the flag gate as an unknown flag — the
+    // same masking parsePromptArgs avoids for prompt text by owning only `--`-prefixed
+    // tokens. So the questions parse scans args itself: a `--json` token before the
+    // question's number positional is the one flag (repeats refused, equals form named by
+    // rejectEqualsForm), any other `--`-prefixed token before it is refused as unknown, and
+    // every remaining token in order is prose — subcommand, position number, then the
+    // decision words. Past the number positional, tokens are decision words even when one
+    // is spelled `--json`: unquoted decision prose (`questions answer 1 keep --json output`)
+    // reaches the command as separate argv tokens, and a flag scan that matched `--json`
+    // anywhere silently ate the token out of the recorded decision and flipped the command
+    // into JSON mode. Unknown `--`-prefixed tokens stay refused even there, so a misspelled
+    // flag is still an error rather than silent decision text.
+    const words = [];
+    let jsonFlag = false;
+    let numbered = false;
+    let file;
+    let answeredFlag = false;
+    let limit;
+    let grep;
+    let show;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!numbered && arg === "--show") {
+            rejectRepeatFlag(show !== undefined, "--show");
+            show = parsePositionFlag("--show", args[++i], "--show 2");
+            continue;
+        }
+        if (!numbered && arg === "--answered") {
+            rejectRepeatFlag(answeredFlag, "--answered");
+            answeredFlag = true;
+            continue;
+        }
+        if (!numbered && arg === "-n") {
+            rejectRepeatFlag(limit !== undefined, "-n");
+            limit = parseCountFlag("-n", args[++i]);
+            continue;
+        }
+        if (!numbered && arg === "--grep") {
+            rejectRepeatFlag(grep !== undefined, "--grep");
+            const text = args[++i];
+            if (text === undefined || text === "")
+                fail("--grep needs text (usage: tumwater questions [--answered] --grep <text>)");
+            grep = text;
+            continue;
+        }
+        if (arg === "--file") {
+            rejectRepeatFlag(file !== undefined, "--file");
+            file = promptFileValue(args[++i]);
+            continue;
+        }
+        if (!numbered && arg === "--json") {
+            rejectRepeatFlag(jsonFlag, "--json");
+            jsonFlag = true;
+            continue;
+        }
+        if (arg.startsWith("--") && arg !== "--json") {
+            rejectEqualsForm(arg, [JSON_FLAG, FILE_SPEC, { names: ["--show"], value: true, valueName: "<n>" }, { names: ["--grep"], value: true, valueName: "<text>" }]);
+            // 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
+            // one --cancel's position honors): bare Number() admitted hex ("0x2"), exponent
+            // ("1e2"), and whitespace-padded spellings as a valid question number, answering a
+            // question the operator never named.
+            if (parsePositiveInt(arg) !== null)
+                numbered = true;
+        }
+        words.push(arg);
+    }
+    if (limit !== undefined && !answeredFlag)
+        fail("-n needs --answered (it limits the answered questions listed)");
+    refuseTeamWorkspace(root);
+    if (show !== undefined) {
+        if (grep !== undefined)
+            fail("--grep does not apply to --show");
+        if (words.length > 0)
+            fail("--show prints one open question; it takes no subcommand");
+        if (file !== undefined)
+            fail("--file only applies to questions answer <n>");
+        if (answeredFlag) {
+            if (limit !== undefined)
+                fail("-n does not apply to --show");
+            const a = answeredQuestionAt(root, show);
+            if (a === null) {
+                const count = answeredQuestionCount(root);
+                const range = count > 0 ? ` — valid: 1-${count}` : "";
+                fail(`no answered question at position ${show} (${count} in QUESTIONS.md)${range}`);
+            }
+            if (jsonFlag)
+                sayJson(a);
+            else
+                say(renderShownQuestion(a));
+            return;
+        }
+        const q = openQuestionAt(root, show);
+        if (q === null) {
+            const count = questionListPayload(root).questions.length;
+            const range = count > 0 ? ` — valid: 1-${count}` : "";
+            fail(`no open question at position ${show} (${count} in QUESTIONS.md)${range}`);
+        }
+        if (jsonFlag)
+            sayJson(q);
+        else
+            say(renderShownQuestion(q));
+        return;
+    }
+    if (answeredFlag) {
+        if (words.length > 0)
+            fail("--answered lists answered questions; it takes no subcommand");
+        if (file !== undefined)
+            fail("--file only applies to questions answer <n>");
+        if (jsonFlag)
+            sayJson(answeredQuestionPayload(root, limit ?? 10, grep));
+        else
+            say(answeredQuestionList(root, limit ?? 10, grep));
+        return;
+    }
+    if (words.length === 0 && file !== undefined)
+        fail("--file only applies to questions answer <n>");
+    if (words.length === 0) {
+        sayQuestionList(root, jsonFlag, grep);
+        return;
+    }
+    if (grep !== undefined)
+        fail("--grep only applies to listing questions");
+    if (words[0] !== "answer")
+        fail(`unknown questions subcommand: ${words[0]} (use "answer <n> <decision>", or run \`tumwater questions\` with no subcommand to list them)${typoSuffix(words[0], ["answer"])}`);
+    // The offending token carries the same ` (got "...")` suffix every sibling number parser
+    // adds (parsePositiveInt's flag callers, --cancel); the bare `answer` form names none.
+    const raw = words.length > 1 ? words[1] : undefined;
+    const n = raw === undefined ? null : parsePositiveInt(raw);
+    if (n === null)
+        fail(`questions answer needs a positive question number: questions answer <n> "<decision>"${gotSuffix(raw)}`);
+    if (file !== undefined) {
+        if (words.length > 2)
+            fail(`unexpected argument ${JSON.stringify(words[2])} — with --file the decision comes from the file`);
+        const answered = answerQuestionFromText(root, n, readPromptFileArg(file));
+        await commitAndReportAnswer(root, n, jsonFlag, answered.title, answered.decision);
+        return;
+    }
+    const decision = words.slice(2).join(" ").trim();
+    if (words.length === 2) {
+        const open = questionListPayload(root).questions;
+        const question = open[n - 1];
+        if (question === undefined) {
+            const range = open.length > 0 ? ` — valid: 1-${open.length}` : "";
+            fail(`no question at position ${n} (${open.length} open)${range}`);
+        }
+        const edited = decisionFromEditorBuffer(editInEditor(answerEditorBuffer(question.title, question.body), `answer-${n}.md`, "pass a decision or --file <path>"));
+        if (edited.trim() === "")
+            fail("questions answer needs a decision: the editor left it blank; nothing changed");
+        const answered = answerQuestionFromText(root, n, edited, question.title);
+        await commitAndReportAnswer(root, n, jsonFlag, answered.title, answered.decision);
+        return;
+    }
+    if (decision === "")
+        fail('questions answer needs a decision: questions answer <n> "<decision>"');
+    // answerQuestion collapses the free-form decision to one line before writing it; report
+    // that written text in the --json payload so it matches the file, not the caller's spacing.
+    const { title, decision: writtenDecision } = answerQuestion(root, n, decision);
+    await commitAndReportAnswer(root, n, jsonFlag, title, writtenDecision);
+}
+/** Commit the answered question, report it in the requested output mode, and wake the
+ * asking role in prose mode — the tail every `questions answer` branch ends with. */
+async function commitAndReportAnswer(root, n, jsonFlag, title, decision) {
+    warnIfUncommitted(await commitOperatorBacklogEdit(root, "QUESTIONS.md", stampedSubject("operator", `Answer question: ${title}`)), "QUESTIONS.md"); // vocabulary-ok: commit prefix stays
+    sayAnswered(n, title, jsonFlag, decision);
+    if (!jsonFlag)
+        sayAskerWake(root, title);
+}
+/** Prose-mode follow-up to `questions answer`: wake the asking role and print the confirmation. */
+function sayAskerWake(root, title) {
+    const wake = wakeQuestionAsker(root, title);
+    if (wake !== null)
+        say(wake);
 }

package/dist/src/cli.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-// vocabulary: plain
 /** The CLI's entry point and command dispatcher — the `bin` target package.json points at
  * (dist/src/cli.js). main() runs the Node-floor gate from package.json's `engines.node`, answers a
  * `--help` topic before any command parses arguments or gates on a ready repo, resolves the repo
@@ -13,33 +12,49 @@
  * modules; this file owns the shared sequence, including each case's flag rejection and its
  * ready-repo gate. An error escaping main() funnels through its catch to fail(errorMessage(err)),
  * the CLI's one error path. */
-import { parseCountFlag, } from "./cli/cli-args.js";
-import { grepFlagSpec, GUI_FLAG_SPECS, JSON_FLAG, LAST_FLAG, N_FLAG, rejectUnknownArgs, resultFlagSpec, ROLE_FLAG, RUN_FLAG_SPECS, sinceFlagSpec, STAT_FLAG, SUMMARY_FLAG, COUNT_FLAG, typeFlagSpec, DRY_RUN_FLAG, FORCE_FLAG, STOP_CANCEL_FLAG, STOP_IN_FLAG, REPROBE_FLAG, PROBLEMS_FLAG, } from "./cli/cli-flag-specs.js";
+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, 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, parsePromptArgs, peelPositionals } from "./cli/cli-command-args.js";
-import { requireReadyRepo } from "./cli/cli-repo-gate.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";
 import { typoSuffix } from "./text/suggest.js";
-import { completionConfigKeys, completionRoleIds, completionScript, SUPPORTED_SHELLS } from "./cli/completion.js";
+import { completionConfigKeys, completionModels, completionRoleIds, completionScript, configValueWords, SUPPORTED_SHELLS } from "./cli/completion.js";
 import { HELP, helpTopic, helpTopicForArgs, suggestCommand } from "./cli/help.js";
 import { PACKAGE_JSON, nodeFloorProblem, packageEnginesNode, packageVersion } from "./version.js";
 // The CLI's help text and its per-command topic parser live in help.ts — importing cli.ts
 // would run main(), so tests pin the topics against help.ts directly.
 /** One run's trail, shared by `history <role> <n>` and its hidden alias `tick` so the two cannot
  * drift. Positional-first: the <role> <n> tokens peel off and the remaining flags go through
- * rejectUnknownArgs (only --json, --last, --stat), so a listing flag such as --role is refused.
+ * rejectUnknownArgs (only --json, --last, --stat, --patch, --transcript, --prompt, --grep,
+ * --result, --model), so a listing flag such as --role is refused.
  * Arity is gated before the ready-repo check so a malformed call fails with its usage in any
- * directory; cmdTick owns the value validation and the --last/numbered rivals. */
+ * directory; cmdRunDetail owns the value validation and the --last/numbered rivals. */
 async function runTrailCommand(root, args) {
-    const { cmdTick, TICK_USAGE } = await import("./tick/tick-detail.js");
-    const { positionals, rest } = peelPositionals(args);
-    rejectUnknownArgs("history", rest, [JSON_FLAG, LAST_FLAG, STAT_FLAG]);
-    if (positionals.length < 1 || positionals.length > 2)
-        fail(`usage: ${TICK_USAGE}`);
+    const { cmdRunDetail, RUN_DETAIL_USAGE } = await import("./run/run-detail.js");
+    const { HISTORY_GREP_VALUE_ERROR, HISTORY_RESULT_VALUE_ERROR, HISTORY_MODEL_VALUE_ERROR } = await import("./history/history.js");
+    // parseGrepFlag removes the pattern token, so `--grep two` cannot read "two" as a positional.
+    const { rest: ungrepped, pattern: grep } = parseGrepFlag(args, HISTORY_GREP_VALUE_ERROR);
+    const { rest: unresulted, raw: result } = parseResultFlag(ungrepped, HISTORY_RESULT_VALUE_ERROR);
+    const { rest: unmodeled, raw: model } = parseModelFlag(unresulted, HISTORY_MODEL_VALUE_ERROR);
+    const { positionals, rest } = peelPositionals(unmodeled);
+    rejectUnknownArgs("history", rest, [JSON_FLAG, LAST_FLAG, STAT_FLAG, PATCH_FLAG, TRANSCRIPT_FLAG, PROMPT_FLAG, { names: ["--grep"] }, { names: ["--result"] }, { names: ["--model"] }]);
+    if ((positionals.length < 1 && !rest.includes("--last")) || positionals.length > 2)
+        fail(`usage: ${RUN_DETAIL_USAGE}`);
     await requireReadyRepo(root);
-    await cmdTick(root, positionals, rest.includes("--json"), rest.includes("--last"), rest.includes("--stat"));
+    await cmdRunDetail(root, positionals, rest.includes("--json"), {
+        last: rest.includes("--last"),
+        stat: rest.includes("--stat"),
+        patch: rest.includes("--patch"),
+        transcript: rest.includes("--transcript"),
+        prompt: rest.includes("--prompt"),
+        grep,
+        result,
+        model,
+    });
 }
 async function main() {
     const [, , command, ...args] = process.argv;
@@ -72,16 +87,16 @@ async function main() {
     const root = (await repoToplevel(process.cwd())) ?? process.cwd();
     switch (command) {
         case "init":
-            // Imported lazily: cli/cli-run.ts pulls the whole team-booting subgraph (orchestrator,
+            // Imported lazily: cli/cli-start.ts pulls the whole team-booting subgraph (orchestrator,
             // supervisor, redeploy, launch-services — the run path's machinery), and every other
             // command's spawn pays module compilation for it unless the dispatch defers that load
-            // to the commands that actually boot or serve a team.
-            await (await import("./cli/cli-run.js")).cmdInit(root, args);
+            // to the commands that actually boot or serve a team. cli-init.ts stays light for init.
+            await (await import("./cli/cli-init.js")).cmdInit(root, args);
             break;
         case "start":
         case "run":
-            rejectUnknownArgs("start", args, RUN_FLAG_SPECS);
-            await (await import("./cli/cli-run.js")).cmdRun(root, args);
+            rejectUnknownArgs("start", args, START_FLAG_SPECS);
+            await (await import("./cli/cli-start.js")).cmdStart(root, args);
             break;
         case "tui":
             rejectUnknownArgs("tui", args, []);
@@ -108,7 +123,10 @@ async function main() {
             // args.
             if (args.length > 0) {
                 if (args[0] !== "get" && args[0] !== "set" && args[0] !== "unset")
-                    fail(CONFIG_USAGE);
+                    // A near-miss subcommand word gets the same typoSuffix `completion <shell>` and
+                    // `logs --type` give, so `config gte` reads "did you mean `get`?" while a far-off
+                    // word (`show`) and a flag (`--anything`) stay hint-free.
+                    fail(`${CONFIG_USAGE}${typoSuffix(args[0] ?? "", ["get", "set", "unset"])}`);
                 if (args[0] === "get" && args.length !== 2)
                     fail("usage: tumwater config get <key>");
                 if (args[0] === "set" && args.length !== 3)
@@ -124,7 +142,8 @@ async function main() {
         }
         case "report": {
             // No requireReadyRepo gate: the report aggregates files that degrade to zeros when
-            // missing, so it runs (and prints an all-zero window) in any directory.
+            // missing, so it runs (and prints an all-zero window) in any directory; the team-workspace
+            // refusal still applies.
             rejectUnknownArgs("report", args, [
                 {
                     names: ["--days"],
@@ -138,9 +157,12 @@ async function main() {
                 },
                 { names: ["--failures"] },
                 sinceFlagSpec("report --since"),
+                untilFlagSpec("report --until"),
                 JSON_FLAG,
                 ROLE_FLAG,
+                FOLLOW_FLAG,
             ]);
+            refuseTeamWorkspace(root);
             // --since is handled before the day-shape reads: it is a rival shape (totals over a
             // trailing window vs a series over whole days), not a modifier of either.
             await (await import("./report/report.js")).cmdReport(root, args);
@@ -149,23 +171,95 @@ async function main() {
         case "doctor": {
             // 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.
-            rejectUnknownArgs("doctor", args, [JSON_FLAG, REPROBE_FLAG, PROBLEMS_FLAG]);
+            const { positionals: checkNames, rest: doctorFlags } = peelPositionals(args);
+            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;
+            if (args.includes("--kill-orphans")) {
+                const { killOrphans, orphanKillLines } = await import("./doctor/doctor-orphans.js");
+                orphanKill = await killOrphans(root);
+                // The text form prints the kill before the report; --json keeps stdout one document.
+                if (!args.includes("--json")) {
+                    for (const line of orphanKillLines(orphanKill))
+                        say(line);
+                    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
             // refresh never spends a model call.
             const probeImages = args.includes("--reprobe") ? "all" : "missing";
-            const report = await runDoctor(root, undefined, undefined, probeImages);
+            const report = await runDoctor(root, undefined, undefined, probeImages, only);
             // --json prints the collector's own payload (the DoctorReport object), not a re-parse of
             // the render — the `report --json` precedent. The exit-code contract below holds in both
             // forms: 1 when any check fails, 0 otherwise; warnings never fail the exit.
             // --problems keeps the full report for the render (it counts the hidden ok rows) and
             // 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") ? problemsOnly(report) : report, renderDoctorProblems);
+                sayJsonOrRender(args, args.includes("--json") ? withLeftoverRetire(problemsOnly(report)) : report, renderDoctorProblems);
             else
-                sayJsonOrRender(args, 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;
@@ -173,15 +267,18 @@ async function main() {
         case "logs": {
             const { cmdLogs, GREP_VALUE_ERROR, TYPE_VALUE_ERROR } = await import("./cli/log-commands.js");
             rejectUnknownArgs("logs", args, [
-                { names: ["-f", "--follow"] },
+                FOLLOW_FLAG,
                 N_FLAG,
                 sinceFlagSpec("logs --since"),
+                untilFlagSpec("logs --until"),
                 grepFlagSpec(GREP_VALUE_ERROR),
                 typeFlagSpec(TYPE_VALUE_ERROR),
                 JSON_FLAG,
                 COUNT_FLAG,
+                NOTABLE_FLAG,
                 ROLE_FLAG,
-                { names: ["--prompt"] },
+                LOGS_TRANSCRIPT_FLAG,
+                PROMPT_FLAG,
             ]);
             await requireReadyRepo(root);
             await cmdLogs(root, args);
@@ -193,16 +290,20 @@ async function main() {
             await (await import("./cli/notify-command.js")).cmdNotify(root, args);
             break;
         case "history": {
-            const { cmdHistory, HISTORY_GREP_VALUE_ERROR, HISTORY_RESULT_VALUE_ERROR } = await import("./history/history.js");
+            const { cmdHistory, HISTORY_GREP_VALUE_ERROR, HISTORY_RESULT_VALUE_ERROR, HISTORY_MODEL_VALUE_ERROR, HISTORY_BY_VALUE_ERROR } = await import("./history/history.js");
             if (historyTrailForm(args)) {
                 await runTrailCommand(root, args);
                 break;
             }
             rejectUnknownArgs("history", args, [
                 N_FLAG,
+                FOLLOW_FLAG,
                 sinceFlagSpec("history --since"),
+                untilFlagSpec("history --until"),
                 grepFlagSpec(HISTORY_GREP_VALUE_ERROR),
                 resultFlagSpec(HISTORY_RESULT_VALUE_ERROR),
+                modelFlagSpec(HISTORY_MODEL_VALUE_ERROR),
+                byFlagSpec(HISTORY_BY_VALUE_ERROR),
                 JSON_FLAG,
                 ROLE_FLAG,
                 SUMMARY_FLAG,
@@ -220,17 +321,25 @@ 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, []);
+            rejectUnknownArgs("archive", args, [JSON_FLAG]);
             await requireReadyRepo(root);
-            await (await import("./backlog/backlog-cli.js")).cmdArchive(root);
+            await (await import("./backlog/backlog-cli.js")).cmdArchive(root, args);
             break;
         case "bug": {
-            const { OPERATOR_FILE_KINDS, bugWakeText, cancelBug, moveEntryToTop, releaseEntry, editBug, editBugFromText, fileBug, fileBugFromText } = await import("./backlog/backlog-write.js");
-            const { bugTitleOf, cancelAndAnnounce, releaseAndAnnounce, topAndAnnounce, editAndAnnounce, fileAndAnnounce, listAndAnnounce, showAndAnnounce } = await import("./backlog/backlog-cli.js");
+            const { OPERATOR_FILE_KINDS, bugWakeText, cancelBug, editBug, editBugFromText, fileBug, fileBugFromText } = await import("./backlog/backlog-write.js");
+            const { moveEntryToTop, releaseEntry } = await import("./backlog/backlog-release.js");
+            const { bugTitleOf, cancelAndAnnounce, releaseAndAnnounce, topAndAnnounce, editAndAnnounce, fileAndAnnounce } = await import("./backlog/backlog-cli.js");
+            const { listAndAnnounce, showAndAnnounce } = await import("./backlog/backlog-cli-view.js");
             const usage = 'tumwater bug "<symptom>"';
             if (args.includes("--show")) {
                 showAndAnnounce(root, args, "bug");
@@ -260,8 +369,10 @@ async function main() {
             break;
         }
         case "plan": {
-            const { OPERATOR_FILE_KINDS, cancelPlan, moveEntryToTop, releaseEntry, editPlan, editPlanFromText, filePlan, filePlanFromText, planWakeText } = await import("./backlog/backlog-write.js");
-            const { cancelAndAnnounce, releaseAndAnnounce, topAndAnnounce, editAndAnnounce, fileAndAnnounce, listAndAnnounce, showAndAnnounce, planTitleOf } = await import("./backlog/backlog-cli.js");
+            const { OPERATOR_FILE_KINDS, cancelPlan, editPlan, editPlanFromText, filePlan, filePlanFromText, planWakeText } = await import("./backlog/backlog-write.js");
+            const { moveEntryToTop, releaseEntry } = await import("./backlog/backlog-release.js");
+            const { cancelAndAnnounce, releaseAndAnnounce, topAndAnnounce, editAndAnnounce, fileAndAnnounce, planTitleOf } = await import("./backlog/backlog-cli.js");
+            const { listAndAnnounce, showAndAnnounce } = await import("./backlog/backlog-cli-view.js");
             const usage = 'tumwater plan "<title>" [body...]';
             if (args.includes("--show")) {
                 showAndAnnounce(root, args, "plan");
@@ -291,13 +402,13 @@ async function main() {
             break;
         }
         case "questions":
-            await (await import("./cli/cli-query-commands.js")).cmdQuestions(root, args);
+            await (await import("./cli/question-commands.js")).cmdQuestions(root, args);
             break;
         case "brief":
             await (await import("./cli/brief-command.js")).cmdBrief(root, args);
             break;
         case "role":
-            await (await import("./cli/cli-query-commands.js")).cmdRole(root, args);
+            await (await import("./cli/cli-role-command.js")).cmdRole(root, args);
             break;
         case "prompt":
             // Parse before the gate: prompt's positionals are free-form, so rejectUnknownArgs
@@ -336,8 +447,8 @@ async function main() {
             break;
         }
         case "revert": {
-            // Acts immediately on the primary checkout under the primary-worktree lock; the single
-            // positional (the commit to undo) is validated inside cmdRevert.
+            // Acts immediately on the primary checkout under the primary-worktree lock; the
+            // positionals (a sha, or a run) are validated inside cmdRevert.
             await requireReadyRepo(root);
             await (await import("./operator/operator-commands.js")).cmdRevert(root, args);
             break;
@@ -362,12 +473,29 @@ async function main() {
                     say(key);
                 break;
             }
+            if (args.length === 2 && args[0] === "--config-value") {
+                // The vocabulary `config set <key> <value>` completes for a discrete-valued key
+                // (boolean/backend/model/thinking); free-form keys print nothing, so a `set` on one
+                // completes nothing instead of offering a wrong vocabulary.
+                for (const word of configValueWords(args[1]))
+                    say(word);
+                break;
+            }
+            if (args.length === 1 && args[0] === "--models") {
+                for (const m of completionModels(root))
+                    say(m);
+                break;
+            }
             const shell = args[0];
-            if (args.length !== 1 || !SUPPORTED_SHELLS.includes(shell))
-                // A single near-miss shell word gets the same typoSuffix `logs --type`/`history --result`
-                // give, so `completion zs` reads "did you mean `zsh`?" while a far-off value (`tcsh`) and
-                // a wrong arity (none or several words, typed shown by gotSuffix) stay hint-free.
-                fail(`completion takes one shell: bash, zsh, or fish${gotSuffix(args.length > 1 ? args[1] : shell)}${args.length === 1 ? typoSuffix(shell ?? "", SUPPORTED_SHELLS) : ""}`);
+            // A wrong word count names the count, not a bad shell. A single near-miss shell word gets
+            // the same typoSuffix `logs --type`/`history --result` give, so `completion zs` reads
+            // "did you mean `zsh`?" while a far-off value (`tcsh`) stays hint-free.
+            if (args.length === 0)
+                fail("completion needs a shell: bash, zsh, or fish");
+            if (args.length > 1)
+                fail(`completion takes one shell: bash, zsh, or fish (got ${args.length} words: ${args.join(" ")})`);
+            if (!SUPPORTED_SHELLS.includes(shell))
+                fail(`completion takes one shell: bash, zsh, or fish${gotSuffix(shell)}${typoSuffix(shell ?? "", SUPPORTED_SHELLS)}`);
             say(completionScript(shell));
             break;
         }
@@ -400,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);
             }
@@ -411,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\`)`);
         }
     }
 }