tumwater 0.4.2 → 0.4.4

package/dist/src/cli/follow-view.js

@@ -52,7 +52,18 @@ export async function followView(frameText, seams) {
         const timer = setInterval(() => {
             if (painting)
                 return;
-            const result = frameText();
+            let result;
+            try {
+                result = frameText();
+            }
+            catch {
+                // A sync frame (status, backlog, report) may throw the same transient failure as an
+                // async one — a snapshot lift, a momentarily unreadable file — and a throw out of a
+                // setInterval callback is an uncaught exception that kills the whole interactive
+                // follow, while the identical failure a tick later (async path) is skipped. Skip this
+                // repaint and retry on the next tick, the same policy the async path applies.
+                return;
+            }
             if (result instanceof Promise) {
                 painting = true;
                 void result
@@ -63,7 +74,14 @@ export async function followView(frameText, seams) {
                 });
                 return;
             }
-            paint(result);
+            // A sync frame's paint is guarded like its read above: a paint that throws (a broken
+            // stdout mid-follow) is skipped and retried, never fatal.
+            try {
+                paint(result);
+            }
+            catch {
+                // Transient — retry on the next tick, like the async path.
+            }
         }, interval);
         startParentDeathWatch(() => {
             clearInterval(timer);

package/dist/src/cli/help.js

@@ -4,6 +4,7 @@
  * <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";
+import { distinctOrdered } from "../collections.js";
 /** 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 }";
@@ -313,9 +314,8 @@ 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 a
-                                   Needs-review note held past its threshold
-                                   (one per run) from the Nth entry in BUGS.md ## Open (as
+                                   Lift the Refused or the
+                                   Needs review notes 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]
@@ -370,9 +370,8 @@ 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 or a
-                                   Needs-review note held past its threshold
-                                   (one per run) from the Nth entry in PLANS.md ## Planned
+                                   Lift the Refused or the
+                                   Needs review notes 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, lifted}
   tumwater plan --top <n> [--json]
@@ -528,12 +527,6 @@ 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...>
@@ -648,7 +641,7 @@ sleep while there is nothing to do and wake when main moves. Everything is local
  * stanza; the distance mechanics are text/suggest.ts's suggestClosest, shared with the config-key
  * suggestion. */
 export function suggestCommand(input, help = HELP) {
-    return suggestClosest(input, [...new Set(helpStanzas(help).map((s) => s.command))]);
+    return suggestClosest(input, distinctOrdered(helpStanzas(help).map((s) => s.command)));
 }
 /** Split HELP's usage block into per-command stanzas. A stanza starts at a two-space-indented
  * `tumwater <command>` line; any further indented line continues it, and a column-0 line (the

package/dist/src/cli.js

@@ -13,16 +13,14 @@
  * 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, NOTABLE_FLAG, typeFlagSpec, DRY_RUN_FLAG, FORCE_FLAG, FOLLOW_FLAG, STOP_CANCEL_FLAG, STOP_IN_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 { 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, } from "./cli/cli-flag-specs.js";
+import { fail, say } from "./cli/cli-output.js";
+import { historyTrailForm, 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, 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
@@ -75,7 +73,7 @@ async function cmdGuiCase(root, args) {
     await (await import("./gui/gui-command.js")).cmdGui(root, args);
 }
 async function cmdConfigCase(root, args) {
-    const { cmdConfig, CONFIG_USAGE } = await import("./cli/config-commands.js");
+    const { cmdConfig, CONFIG_USAGE } = await import("./cli/cli-config-commands.js");
     // Subcommand arity before the ready-repo gate, so a malformed get/set fails with its
     // usage no matter the directory: bare config takes nothing, `get`/`unset` exactly one
     // key, `set` exactly a key and a value. cmdConfig dispatches on the (now well-shaped)
@@ -126,98 +124,15 @@ async function cmdReportCase(root, args) {
     await (await import("./report/report.js")).cmdReport(root, args);
 }
 async function cmdDoctorCase(root, args) {
-    // 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, 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");
-    const report = await runDoctor(root, undefined, undefined, 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") ? withLeftoverRetire(problemsOnly(report)) : report, renderDoctorProblems);
-    else
-        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.
+    // cmdDoctor lives in cli-doctor-command.ts (the doctor command body, its side-effect
+    // wrappers and payload shaping) and holds no ready-repo 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. Imported lazily like every command body, so the doctor
+    // subgraph is only compiled when `tumwater doctor` is asked for.
+    await (await import("./cli/cli-doctor-command.js")).cmdDoctor(root, args);
 }
 async function cmdLogsCase(root, args) {
-    const { cmdLogs, GREP_VALUE_ERROR, TYPE_VALUE_ERROR } = await import("./cli/log-commands.js");
+    const { cmdLogs, GREP_VALUE_ERROR, TYPE_VALUE_ERROR } = await import("./cli/cli-log-commands.js");
     rejectUnknownArgs("logs", args, [
         FOLLOW_FLAG,
         N_FLAG,
@@ -238,7 +153,7 @@ async function cmdLogsCase(root, args) {
 async function cmdNotifyCase(root, args) {
     rejectUnknownArgs("notify", args, [{ names: ["--test"] }]);
     await requireReadyRepo(root);
-    await (await import("./cli/notify-command.js")).cmdNotify(root, args);
+    await (await import("./cli/cli-notify-command.js")).cmdNotify(root, args);
 }
 async function cmdHistoryCase(root, args) {
     const { cmdHistory, HISTORY_GREP_VALUE_ERROR, HISTORY_RESULT_VALUE_ERROR, HISTORY_MODEL_VALUE_ERROR, HISTORY_BY_VALUE_ERROR } = await import("./history/history.js");
@@ -267,69 +182,81 @@ async function cmdArchiveCase(root, args) {
     await requireReadyRepo(root);
     await (await import("./backlog/backlog-cli.js")).cmdArchive(root, args);
 }
-async function cmdBugCase(root, args) {
-    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");
+/** The one dispatch `bug` and `plan` both run through (see BacklogCommandSpec): route on the
+ * leading flag token and hand off to the matching shared AndAnnounce shell, or file a text
+ * entry by default. */
+async function runBacklogCommand(root, args, s) {
+    const { cancelAndAnnounce, editAndAnnounce, fileAndAnnounce, releaseAndAnnounce, topAndAnnounce } = 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");
+        showAndAnnounce(root, args, s.command);
         return;
     }
     if (args.includes("--list")) {
-        listAndAnnounce(root, args, "bug", "BUGS.md", "Open");
+        listAndAnnounce(root, args, s.command, s.file, s.section);
         return;
     }
     if (args.includes("--edit")) {
-        await editAndAnnounce(root, args, "bug", (n, positionals) => editBug(root, n, positionals.join(" "), usage), (n, text) => editBugFromText(root, n, text, usage));
+        await editAndAnnounce(root, args, s.command, s.edit, s.editText);
         return;
     }
     if (args.includes("--cancel")) {
-        await cancelAndAnnounce(root, args, "bug", (n) => cancelBug(root, n));
+        await cancelAndAnnounce(root, args, s.command, s.cancel);
         return;
     }
     if (args.includes("--top")) {
-        await topAndAnnounce(root, args, "bug", (n) => moveEntryToTop(root, "bug", n));
+        await topAndAnnounce(root, args, s.command, s.top);
         return;
     }
     if (args.includes("--release")) {
-        await releaseAndAnnounce(root, args, "bug", (n) => releaseEntry(root, "bug", n), OPERATOR_FILE_KINDS.bug.role);
+        await releaseAndAnnounce(root, args, s.command, s.release, s.releaseRole);
         return;
     }
-    await fileAndAnnounce(root, args, "bug", (positionals) => fileBug(root, positionals.join(" "), usage), OPERATOR_FILE_KINDS.bug.role, bugWakeText, bugTitleOf, (text) => fileBugFromText(root, text, usage));
+    await fileAndAnnounce(root, args, s.command, s.fileOp, s.releaseRole, s.wakeText, s.titleOf, s.fileText);
+}
+async function cmdBugCase(root, args) {
+    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 } = await import("./backlog/backlog-cli.js");
+    const usage = 'tumwater bug "<symptom>"';
+    await runBacklogCommand(root, args, {
+        command: "bug",
+        usage,
+        file: "BUGS.md",
+        section: "Open",
+        edit: (n, positionals) => editBug(root, n, positionals.join(" "), usage),
+        editText: (n, text) => editBugFromText(root, n, text, usage),
+        cancel: (n) => cancelBug(root, n),
+        top: (n) => moveEntryToTop(root, "bug", n),
+        release: (n) => releaseEntry(root, "bug", n),
+        releaseRole: OPERATOR_FILE_KINDS.bug.role,
+        fileOp: (positionals) => fileBug(root, positionals.join(" "), usage),
+        fileText: (text) => fileBugFromText(root, text, usage),
+        wakeText: bugWakeText,
+        titleOf: bugTitleOf,
+    });
 }
 async function cmdPlanCase(root, args) {
     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 { planTitleOf } = await import("./backlog/backlog-cli.js");
     const usage = 'tumwater plan "<title>" [body...]';
-    if (args.includes("--show")) {
-        showAndAnnounce(root, args, "plan");
-        return;
-    }
-    if (args.includes("--list")) {
-        listAndAnnounce(root, args, "plan", "PLANS.md", "Planned");
-        return;
-    }
-    if (args.includes("--edit")) {
-        await editAndAnnounce(root, args, "plan", (n, positionals) => editPlan(root, n, positionals[0] ?? "", positionals.slice(1).join(" "), usage), (n, text) => editPlanFromText(root, n, text, usage));
-        return;
-    }
-    if (args.includes("--cancel")) {
-        await cancelAndAnnounce(root, args, "plan", (n) => cancelPlan(root, n));
-        return;
-    }
-    if (args.includes("--top")) {
-        await topAndAnnounce(root, args, "plan", (n) => moveEntryToTop(root, "plan", n));
-        return;
-    }
-    if (args.includes("--release")) {
-        await releaseAndAnnounce(root, args, "plan", (n) => releaseEntry(root, "plan", n), OPERATOR_FILE_KINDS.plan.role);
-        return;
-    }
-    await fileAndAnnounce(root, args, "plan", (positionals) => filePlan(root, positionals[0] ?? "", positionals.slice(1).join(" "), usage), OPERATOR_FILE_KINDS.plan.role, planWakeText, planTitleOf, (text) => filePlanFromText(root, text, usage));
+    await runBacklogCommand(root, args, {
+        command: "plan",
+        usage,
+        file: "PLANS.md",
+        section: "Planned",
+        edit: (n, positionals) => editPlan(root, n, positionals[0] ?? "", positionals.slice(1).join(" "), usage),
+        editText: (n, text) => editPlanFromText(root, n, text, usage),
+        cancel: (n) => cancelPlan(root, n),
+        top: (n) => moveEntryToTop(root, "plan", n),
+        release: (n) => releaseEntry(root, "plan", n),
+        releaseRole: OPERATOR_FILE_KINDS.plan.role,
+        fileOp: (positionals) => filePlan(root, positionals[0] ?? "", positionals.slice(1).join(" "), usage),
+        fileText: (text) => filePlanFromText(root, text, usage),
+        wakeText: planWakeText,
+        titleOf: planTitleOf,
+    });
 }
 async function cmdPromptCase(root, args) {
     // Parse before the gate: prompt's positionals are free-form, so rejectUnknownArgs
@@ -364,43 +291,6 @@ async function cmdStopCase(root, args) {
     await requireReadyRepo(root);
     await (await import("./operator/operator-commands.js")).cmdStop(root, args);
 }
-async function cmdCompletionCase(root, args) {
-    // Works outside a repo: no requireReadyRepo.
-    if (args.length === 1 && args[0] === "--roles") {
-        for (const id of completionRoleIds(root))
-            say(id);
-        return;
-    }
-    if (args.length === 1 && args[0] === "--config-keys") {
-        for (const key of completionConfigKeys(root))
-            say(key);
-        return;
-    }
-    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);
-        return;
-    }
-    if (args.length === 1 && args[0] === "--models") {
-        for (const m of completionModels(root))
-            say(m);
-        return;
-    }
-    const shell = args[0];
-    // 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));
-}
 async function cmdVersionCase(args) {
     // A stray flag fails like every other command's: `tumwater version --json` (a plausible
     // slip from `status --json`) must not print a version as if it had answered the query.
@@ -535,10 +425,10 @@ async function main() {
             break;
         }
         case "questions":
-            await (await import("./cli/question-commands.js")).cmdQuestions(root, args);
+            await (await import("./cli/cli-question-commands.js")).cmdQuestions(root, args);
             break;
         case "brief":
-            await (await import("./cli/brief-command.js")).cmdBrief(root, args);
+            await (await import("./cli/cli-brief-command.js")).cmdBrief(root, args);
             break;
         case "role":
             await (await import("./cli/cli-role-command.js")).cmdRole(root, args);
@@ -574,7 +464,11 @@ async function main() {
             break;
         }
         case "completion": {
-            await cmdCompletionCase(root, args);
+            // Works outside a repo (no requireReadyRepo): the body lives in
+            // cli-completion-command.ts, beside its data (src/cli/completion.ts), and is imported
+            // lazily like every command body so the dispatcher never compiles the completion
+            // subgraph until `tumwater completion` is asked for.
+            await (await import("./cli/cli-completion-command.js")).cmdCompletion(root, args);
             break;
         }
         case "version":

package/dist/src/collections.js

@@ -4,10 +4,10 @@
  * utilities module. */
 /** Group items by a key, preserving first-seen key order and input order within each group.
  * The single home of the "append to a Map of arrays" step, shared by the event bucketers
- * (history-queued.ts's bucketMergeEvents, failure/time-spend.ts's rejected-by-role pass) and
- * the team-hold poll's observations-by-provider grouping (team-polls.ts's pollTeamHold), so
- * those sites cannot drift on how a missing key is seeded. Returns a fresh Map; the input is
- * never mutated. */
+ * (history-queued.ts's bucketMergeEvents and failure/failure-time-spend.ts's rejected-by-role
+ * pass) and the team-hold poll's observations-by-provider grouping (team-polls.ts's
+ * pollTeamHold), so those sites cannot drift on how a missing key is seeded. Returns a fresh
+ * Map; the input is never mutated. */
 export function groupBy(items, key) {
     const groups = new Map();
     for (const item of items) {
@@ -15,11 +15,31 @@ export function groupBy(items, key) {
     }
     return groups;
 }
+/** The distinct items of an iterable, in first-seen order — the single home of the
+ * `seen.includes -> push` dedupe, shared by the pending pane's three scope lists
+ * (mergeQueueRoles, postReviewRoles, overlapHolders in ui/tui/tui-pane-pending.ts), the
+ * session pane's scope cycle (ui/tui/tui-pane-session.ts's scopeCycle), the report
+ * scope fold (report/report-fold.ts's scopeBases), and the rest of the harness's
+ * `[...new Set(...)]` dedupes (completion.ts's commands/config keys, operator-commands.ts's
+ * role lists, text.ts's splitCommaListUnique/pathTokens, startup-gates.ts's backendsInUse,
+ * failure-data.ts's delta roles, doctor-backlog.ts's watched set, doctor-orphans.ts's pid
+ * list, main-watch.ts's knownMainFailures, help.ts's suggestCommand candidates, and
+ * tui-pane-activity.ts's present types), so those sites cannot drift on how a repeat is
+ * skipped. Returns a fresh array; the input is never mutated. (The dashboard's
+ * role-scope builder in ui/gui/gui-client-report.ts keeps its own copy by design: it runs
+ * in the browser, where harness modules cannot be imported.) */
+export function distinctOrdered(items) {
+    const seen = [];
+    for (const item of items)
+        if (!seen.includes(item))
+            seen.push(item);
+    return seen;
+}
 /** Return `map`'s value for `key`, creating and storing `make()`'s result first when the key is
  * absent — the single home of the `map.get(key) ?? fresh; …; map.set(key, value)` step, shared
  * by the failure digest's per-role stats, outcome, and prompt-token accumulators (failure-data.ts),
- * its time-and-spend per-role row (time-spend.ts), the team hold's provider+kind grouping
- * (team-hold.ts), the error-storm reducer's roles-by-key set (src/team/error-storm.ts), and
+ * its time-and-spend per-role row (failure-time-spend.ts), the team hold's provider+kind grouping
+ * (team-hold.ts), the error-storm reducer's roles-by-key set (src/team/team-error-storm.ts), and
  * `groupBy` above, so those sites cannot drift on how a missing key is seeded. `make` runs only
  * when the key is absent. A stored value of `undefined` reads as absent, matching the `??` idiom
  * this replaces; the callers above never store one. */
@@ -50,9 +70,9 @@ export function filterKeepPositions(items, keep) {
 }
 /** 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
+ * (src/team/team-failure-spread.ts), the diff multiset's line tally (merge/merge-diff.ts), the
  * section-title tally (backlog/backlog-structure.ts), the logs' per-type tally
- * (cli/log-commands.ts), the flaky-check tally
+ * (cli/cli-log-commands.ts), the flaky-check tally
  * (doctor/doctor-project-checks.ts), and the multi-runner base tally
  * (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
@@ -125,11 +145,11 @@ export function trimToLast(arr, max) {
  * order the same way. These two helpers are the single home of that rule; every surface that
  * ranks counters by count calls one of them rather than re-implementing the comparator —
  * `rankCountEntries` serves the `[key, count]` entry shape (src/report/report-render.ts's
- * rankedRoleMap, src/team/failure-spread.ts's strongest-kind pick) and `rankByCount` serves
- * callers whose counts are fields or computations on other shapes
- * (src/failure/failure-cluster.ts's clusters, src/team/error-storm.ts's strongest-cause pick,
- * failure-data.ts's outcome table, and time-spend.ts's time-and-spend table). `sortByValueDesc`
- * is the deliberate sibling for the same value-descending shape that wants a code-unit tiebreak
+ * rankedRoleMap, src/team/team-failure-spread.ts's strongest-kind pick) and `rankByCount` serves
+ * callers whose counts are fields or computations on other shapes (src/failure/failure-cluster.ts's
+ * clusters and src/team/team-error-storm.ts's strongest-cause pick; failure-data.ts's outcome
+ * table and failure-time-spend.ts's time-and-spend table). `sortByValueDesc` is the deliberate
+ * sibling for the same value-descending shape that wants a code-unit tiebreak
  * instead of localeCompare, and unlike these two it sorts its input array in place. The one
  * deliberate exception to both orderings is ui/gui/gui-client-report-chart.ts's reportRoleOrder,
  * which keeps its own copy by design: it runs in the browser, where harness modules cannot be
@@ -143,9 +163,9 @@ export function rankByCount(items, count, key) {
  * aliases `items` when it already fits; `hidden` is `max(0, items.length - top)`, which the
  * slice-length arithmetic yields without the explicit clamp (a slice never returns more than
  * `top` even when the list is shorter). Shared by the merge-intent and conflict-hunk caps
- * (merge-git.ts), the failure digest's loss-cause and message-cluster tops
- * (time-spend.ts, failure-cluster.ts), and the answered-questions cap (question-answer.ts),
- * so those cuts cannot drift on how the remainder is counted. */
+ * (merge-git.ts), the failure digest's loss-cause and message-cluster tops (failure-time-spend.ts
+ * and failure-cluster.ts), and the answered-questions cap (backlog-question-answer.ts), so those
+ * cuts cannot drift on how the remainder is counted. */
 export function topAndHidden(items, top) {
     const visible = items.slice(0, top);
     return { visible, hidden: items.length - visible.length };
@@ -159,17 +179,9 @@ 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-questions
- * feed (src/ui/alert-feeds.ts's staleOpenQuestions), which builds `{index, days}`
- * rows off the same backlog scan, so its tie order cannot drift. 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/completion.ts, src/cli/log-commands.ts,
+ * src/cli/cli-start-summary.ts, src/cli/completion.ts, src/cli/cli-log-commands.ts,
  * src/history/history-data.ts, src/review/post-merge-review.ts, src/review/quarantine-render.ts,
  * src/budget/budget.ts and src/change/change-data.ts, and by `sortByValueDesc` for its tiebreak. */
 export function compareCodeUnits(a, b) {
@@ -178,7 +190,7 @@ export function compareCodeUnits(a, b) {
 /** Rank `[key, value, …]` pairs by value descending, breaking ties in code-unit order
  * (compareCodeUnits — the locale-independent order, unlike rankByCount's localeCompare), so
  * equal values always order the same way. The single home of that comparator, which
- * src/cli/log-commands.ts's per-type event-count lines and src/report/report-render.ts's
+ * src/cli/cli-log-commands.ts's per-type event-count lines and src/report/report-render.ts's
  * mergeDone sort hand-rolled before; `…rest` lets a site carry extra trailing fields
  * (report-render's third column) through the sort untouched. Mutates and returns the input
  * array, matching the `.sort()` the call sites replaced. */
@@ -200,7 +212,7 @@ export function sortEntriesByKey(entries) {
     return [...entries].sort(([a], [b]) => (a ?? "").localeCompare(b ?? ""));
 }
 /** rankByCount for `[key, count]` entry pairs (count first): src/report/report-render.ts's
- * rankedRoleMap, src/team/failure-spread.ts's strongest-kind pick, and
+ * rankedRoleMap, src/team/team-failure-spread.ts's strongest-kind pick, and
  * src/doctor/doctor-contention-checks.ts's check-wait and provider-wait rankings. */
 export function rankCountEntries(entries) {
     return rankByCount(entries, (e) => e[1], (e) => e[0]);

package/dist/src/concurrency/check-slots.js

@@ -0,0 +1,70 @@
+import path from "node:path";
+import { classifyLock, releaseOwnedLockDir, tryClaimLockDir } from "./lock.js";
+import { ensureParentDir, isDirectory, removeTree, walkUp } from "../files/files.js";
+/** The host-wide suite-slot ledger that bounds how many project check scripts (an agent's bare
+ * `npm run test:gate` and the harness's own spawned check alike) run their suite step at once,
+ * sized to the same `config.maxConcurrentChecks` the in-process check permit enforces. Where
+ * withCheckPermit is one process-wide semaphore (every suite spawned by THIS process shares it),
+ * the ledger is files on disk so suites started by DIFFERENT processes — the harness and the pi
+ * agent's bash tools, or two agents at once — still contend for the same cap. It exists to close
+ * the gap where an agent's own suite run takes no team check permit at all (BUGS.md 2026-10-28),
+ * so the two mechanisms coexist: withCheckPermit keeps its in-process tier queue, reentrancy and
+ * callers exactly as they are, and the npm check scripts additionally claim a slot here.
+ *
+ * A slot is a lock dir under `.tumwater/state/check-permits/slot-<n>` using lock.ts's directory-
+ * and-pid protocol unchanged (tryClaimLockDir / releaseOwnedLockDir / classifyLock), so a killed
+ * suite's slot is reclaimed by lock.ts's stale rules (dead pid, no-pid grace, then age) on a later
+ * claim — no separate sweep. A waiter gives up after a bounded wait and runs the suite anyway with
+ * a warning rather than hanging past the check deadline or the bash tool's 600 s cap: the ledger
+ * is a scheduling throttle, not a correctness mutex, so a full ledger must degrade to "run
+ * anyway", never to "hang forever". */
+/** How long acquireCheckSlot keeps trying for a free slot before giving up and returning null (the
+ * callers then run the suite unpermitted with a warning). Bounded well under the bash tool's 600 s
+ * cap so a full ledger never prices a run's own timeout. */
+const CHECK_SLOT_WAIT_TIMEOUT_MS = 60_000;
+/** The retry cadence between full passes over a full ledger — a slot frees quickly (a suite's
+ * release is the moment its check process exits), so a 200 ms repoll finds it almost immediately
+ * without hammering the filesystem. */
+const CHECK_SLOT_RETRY_MS = 200;
+/** The ancestor of `startDir` that holds the team's `.tumwater/state`, or null when none within the
+ * walk's bound does. The slot ledger lives under that state dir, so `scripts/check-permit.mjs`
+ * locates the root the same way the harness's own root lookup does (shared walkUp climb), and a
+ * suite run outside any team root has no ledger to contend for. Exported for tests. */
+export function findTeamRoot(startDir = process.cwd()) {
+    return walkUp(startDir, 63, (dir) => (isDirectory(path.join(dir, ".tumwater", "state")) ? dir : null));
+}
+/** The slot directory for `index` of a ledger rooted at `root` (under `root/.tumwater/state`). One
+ * function owns the path so the acquirer, the releaser and the reclaim all name the same dir. */
+export function checkSlotDir(root, index) {
+    return path.join(root, ".tumwater", "state", "check-permits", `slot-${index}`);
+}
+/** Claim one of the `cap` slots of `root`'s ledger, waiting up to `waitMs` for one to free. Walks
+ * slots `0..cap-1`, breaking any it finds lock.ts's classifyLock calls "stale" (a dead holder, a
+ * leftover no-pid dir past its grace, or an old dir), then trying to claim each by atomic publish;
+ * when none is free it sleeps and retries until the budget is spent, returning null. A stale slot
+ * is broken as encountered because a dead holder's dir would otherwise block that index forever. */
+export async function acquireCheckSlot(root, cap, waitMs = CHECK_SLOT_WAIT_TIMEOUT_MS) {
+    // The ledger's parent must exist before any slot's atomic publish can create it: lock.ts's
+    // publishLockDir never makes its own parent (withStateLock is where ensureParentDir runs), so a
+    // first claim on a root with no check-permits dir would fail its mkdirSync and never acquire.
+    ensureParentDir(checkSlotDir(root, 0));
+    const startedAt = Date.now();
+    for (;;) {
+        for (let index = 0; index < cap; index++) {
+            const dir = checkSlotDir(root, index);
+            if (classifyLock(dir) === "stale")
+                removeTree(dir);
+            if (tryClaimLockDir(dir))
+                return dir;
+        }
+        if (Date.now() - startedAt >= waitMs)
+            return null;
+        await new Promise((resolve) => setTimeout(resolve, CHECK_SLOT_RETRY_MS));
+    }
+}
+/** Return a slot claimed by THIS process. Deleting a dir that another pid now owns must not
+ * happen (releaseOwnedLockDir checks the pid first); a slot stolen from under us stays for its
+ * new owner or for the stale rules. */
+export function releaseCheckSlot(dir) {
+    releaseOwnedLockDir(dir);
+}