tumwater 0.4.3 → 0.4.4

package/dist/src/baseline/main-watch.js

@@ -1,3 +1,4 @@
+import { distinctOrdered } from "../collections.js";
 import { checkMainBaseline } from "./main-baseline.js";
 import { baselineCheckLogger, clearHealKeyOnGreen, withMainTipWorktree } from "./main-red.js";
 import { CHECK_TIER } from "../concurrency/check-permit.js";
@@ -13,6 +14,22 @@ import { treeDiffFiles } from "../git/git-diff.js";
 import { mergingRoleOf } from "../events/event-read.js";
 import { isExemptDiff } from "../review/exemptions.js";
 import { diffRuleReasons } from "../review/diff-rules.js";
+/** The main_check event payload for a settled verdict: the baseline sha and status, the run
+ * duration (0 when nothing ran), the covered-commit count, and, on a red, the failing tests and
+ * the quarantined-only marker. */
+function mainCheckEvent(baseline, red, quarantined, covered, durationMs) {
+    return {
+        source: TUMWATER_SOURCE,
+        type: "main_check",
+        sha: baseline.sha,
+        status: red ? "failed" : "passed",
+        durationMs,
+        covered,
+        ...(red ? { failingTests: baseline.failingTests ?? [] } : {}),
+        ...(quarantined ? { quarantined } : {}),
+        ...(baseline.inheritedFrom !== undefined ? { inherited: true } : {}),
+    };
+}
 /** The failing tests of each root's newest watch verdict, keyed by root. */
 const knownFailures = new Map();
 /** Main's known failures: the failing tests of the watch's newest verdict — main's tip, or the
@@ -20,7 +37,7 @@ const knownFailures = new Map();
  * (review/known-flakes.ts). Empty when the verdict is green, red with no parsed test, or none has
  * been recorded yet in this process, and nothing is quarantined. */
 export function knownMainFailures(root) {
-    return [...new Set([...(knownFailures.get(root) ?? []), ...quarantinedTests(root)])];
+    return distinctOrdered([...(knownFailures.get(root) ?? []), ...quarantinedTests(root)]);
 }
 /** The failing tests of a failed check when every one of them is a known main failure; null when
  * the output names no test, any test is outside the known set, or none is known. A list at
@@ -76,8 +93,9 @@ export function createMainWatch(root, mainBranch, onCulprit) {
         }
     }
     async function watchOnce(mainHead, config) {
-        // The deterministic diff rules ("Every commit is verified on main, part 1/3"): run the same
-        // five checks the gate runs on a change, against main's new tip. A rule failure is a
+        // The deterministic diff rules ("Every commit is verified on main, part 1/3"): run the full
+        // five-check set the watch and gate share — the gate now runs only the three a later commit
+        // cannot repair — against main's new tip. A rule failure is a
         // deterministic red — it takes no confirming re-run and never quarantines — reported as a
         // warning naming the rule and the head (and each committing role, when a recent merged event
         // names one). It runs on every tip the watch covers in a poll — a build green, a build
@@ -106,7 +124,7 @@ export function createMainWatch(root, mainBranch, onCulprit) {
                 await git(wt, "checkout", "-q", "--detach", "--force", commit);
                 const parent = `${commit}^`;
                 const files = (await treeDiffFiles(wt, parent, commit)) ?? [];
-                const [ruleReason] = await diffRuleReasons(wt, parent, files, mergingRoleOf(root, commit) ?? "", isExemptDiff(files, config.review.exemptPaths));
+                const [ruleReason] = await diffRuleReasons(wt, parent, files, mergingRoleOf(root, commit) ?? "", isExemptDiff(files, config.review.exemptPaths), "watch");
                 if (ruleReason !== undefined) {
                     logEventBestEffort(root, {
                         source: TUMWATER_SOURCE,
@@ -120,17 +138,11 @@ export function createMainWatch(root, mainBranch, onCulprit) {
                 }
             }
         };
-        if (!detectBuildCheck(root, config)) {
-            // No declared build check: nothing to watch for a build red, but the diff rules still run on
-            // the tip. The build-red path below is what never runs here.
-            await withMainTipWorktree(root, mainBranch, async (wt) => {
-                await watchRules(wt, lastWatched, await headOf(wt));
-            });
-            lastWatched = mainHead; // no declared check: nothing else to watch until main moves
-            return;
-        }
-        await withMainTipWorktree(root, mainBranch, async (wt) => {
-            const started = Date.now();
+        /** Run the declared build check on main's tip, re-running a red once and quarantining a flake
+         * whose re-run turns green. Returns the check's result and whether any run actually executed
+         * (false for a cache hit, a skip, or a sleep-spanned run). `config` and `root` are captured
+         * from `watchOnce`. */
+        async function runBaselineCheck(wt) {
             let ran = false;
             const onRun = baselineCheckLogger(root, TUMWATER_SOURCE);
             const hook = (run) => {
@@ -145,45 +157,31 @@ export function createMainWatch(root, mainBranch, onCulprit) {
                 if (check.baseline?.status === "green")
                     quarantineTests(root, first.failingTests, (first.failingTests ?? []).join("\n"));
             }
-            const baseline = check.baseline;
-            const previous = lastWatched;
-            // A skipped or sleep-spanned run made no verdict: the head still counts as watched, so the
-            // next poll does not start another run for it — but the diff rules still run on this tip.
-            if (!baseline) {
-                const tip = await headOf(wt);
-                await watchRules(wt, previous, tip);
-                return void (lastWatched = tip);
-            }
-            lastWatched = baseline.sha;
+            return { check, ran };
+        }
+        /** The covered-commit count for a main_check event: the first-parent commits between the
+         * previous and new watched heads, or 1 when there is no previous head. */
+        async function countCovered(wt, previous, sha) {
+            if (previous === undefined)
+                return 1;
+            const counted = Number(((await gitTry(wt, "rev-list", "--first-parent", "--count", `${previous}..${sha}`)) ?? "").trim());
+            return Number.isFinite(counted) && counted > 0 ? counted : 1;
+        }
+        /** Settle the verdict for a checked baseline: distinguish quarantined-only reds, record
+         * main's known failures, count the covered commits, and log the main_check event. Returns
+         * whether the tip settled red (a red naming tests that are not all quarantined). */
+        async function recordMainCheck(wt, baseline, previous, ran, started) {
             // A red naming only quarantined tests counts as green: no redeploy hold.
             const quarantined = baseline.status === "red" ? onlyQuarantined(root, baseline.failingTests) : null;
             const red = baseline.status === "red" && !quarantined;
             knownFailures.set(root, red ? (baseline.failingTests ?? []) : []);
-            const counted = previous === undefined
-                ? 1
-                : Number(((await gitTry(wt, "rev-list", "--first-parent", "--count", `${previous}..${baseline.sha}`)) ?? "").trim());
-            logEventBestEffort(root, {
-                source: TUMWATER_SOURCE,
-                type: "main_check",
-                sha: baseline.sha,
-                status: red ? "failed" : "passed",
-                durationMs: ran ? Date.now() - started : 0,
-                covered: Number.isFinite(counted) && counted > 0 ? counted : 1,
-                ...(red ? { failingTests: baseline.failingTests ?? [] } : {}),
-                ...(quarantined ? { quarantined } : {}),
-                ...(baseline.inheritedFrom !== undefined ? { inherited: true } : {}),
-            });
-            // The diff rules judge the tip whether the build is green or red; the build-red path below
-            // names the whole tip as the culprit, so the two red kinds are judged independently.
-            await watchRules(wt, previous, baseline.sha);
-            // A settled non-red verdict (a green, or a red naming only quarantined tests) clears the
-            // heal-dedup key, so a failing set that returns after a green main is healed again. A
-            // settled red verdict below does NOT clear it: the heal-dedup key stays set while main
-            // is red.
-            if (!red) {
-                clearHealKeyOnGreen();
-                return;
-            }
+            const covered = await countCovered(wt, previous, baseline.sha);
+            logEventBestEffort(root, mainCheckEvent(baseline, red, quarantined, covered, ran ? Date.now() - started : 0));
+            return red;
+        }
+        /** Name a settled red tip as the culprit: its merging runner, the main_culprit event, and
+         * the onCulprit callback with the tip and its failing tests. */
+        function reportCulprit(baseline) {
             // The newest head is the culprit ("Every commit is verified on main, part 2/3"): the watch
             // checks each new red tip, so whatever it found belongs to the head it checked. Once per red
             // head — lastWatched already holds it, so a later poll does not attribute it again — name
@@ -201,6 +199,42 @@ export function createMainWatch(root, mainBranch, onCulprit) {
                 failingTests: baseline.failingTests ?? [],
                 tip: baseline.sha,
             });
+        }
+        if (!detectBuildCheck(root, config)) {
+            // No declared build check: nothing to watch for a build red, but the diff rules still run on
+            // the tip. The build-red path below is what never runs here.
+            await withMainTipWorktree(root, mainBranch, async (wt) => {
+                await watchRules(wt, lastWatched, await headOf(wt));
+            });
+            lastWatched = mainHead; // no declared check: nothing else to watch until main moves
+            return;
+        }
+        await withMainTipWorktree(root, mainBranch, async (wt) => {
+            const started = Date.now();
+            const { check, ran } = await runBaselineCheck(wt);
+            const baseline = check.baseline;
+            const previous = lastWatched;
+            // A skipped or sleep-spanned run made no verdict: the head still counts as watched, so the
+            // next poll does not start another run for it — but the diff rules still run on this tip.
+            if (!baseline) {
+                const tip = await headOf(wt);
+                await watchRules(wt, previous, tip);
+                return void (lastWatched = tip);
+            }
+            lastWatched = baseline.sha;
+            const red = await recordMainCheck(wt, baseline, previous, ran, started);
+            // The diff rules judge the tip whether the build is green or red; the build-red path below
+            // names the whole tip as the culprit, so the two red kinds are judged independently.
+            await watchRules(wt, previous, baseline.sha);
+            // A settled non-red verdict (a green, or a red naming only quarantined tests) clears the
+            // heal-dedup key, so a failing set that returns after a green main is healed again. A
+            // settled red verdict below does NOT clear it: the heal-dedup key stays set while main
+            // is red.
+            if (!red) {
+                clearHealKeyOnGreen();
+                return;
+            }
+            reportCulprit(baseline);
         });
     }
     return {

package/dist/src/brief/brief.js

@@ -106,16 +106,10 @@ export function briefFile(root) {
  * on-purpose bare repo. An unreadable candidate counts: a brief that cannot be read is one
  * the roles cannot use, and the underlying firstBriefText throw is caught and reported as
  * true here — same subset doctor's `brief` warn covers, minus the bare-repo state that
- * doctor deems fine. Consumer: src/status/status-data.ts's snapshot. */
+ * doctor deems fine. Thin accessor over briefStatus, so this predicate and the snapshot's
+ * shared flags share one implementation. */
 export function briefBlockMissing(root) {
-    if (briefCandidates(root).every((candidate) => !fs.existsSync(candidate)))
-        return false;
-    try {
-        return (readBrief(root)?.prompt ?? "") === "";
-    }
-    catch {
-        return true;
-    }
+    return briefStatus(root).missing;
 }
 /** True when the resolved brief block exceeds the read cap (BRIEF_TEXT_MAX_CHARS) — the
  * always-on amber twin of the doctor `brief` row's over-cap warn. extractPrompt truncates
@@ -127,15 +121,34 @@ export function briefBlockMissing(root) {
  * a surrogate pair, while an at-cap block stays equal to it. A repo with no candidate
  * resolves null (0, false), and an unreadable candidate's readBrief throw is caught to false,
  * because briefBlockMissing already raises `no-brief` for that state; an empty block stays
- * briefBlockMissing's (its resolved length is 0). Consumer: src/status/status-data.ts's
- * snapshot. */
+ * briefBlockMissing's (its resolved length is 0). Thin accessor over briefStatus, so this
+ * predicate and the snapshot's shared flags share one implementation. */
 export function briefBlockOverCap(root) {
+    return briefStatus(root).overCap;
+}
+/** The always-on brief degraded-state flags, derived from ONE candidate scan and ONE file
+ * read — the per-second status snapshot's `noBrief`/`briefTruncated` fields, and the single
+ * implementation of both predicates: the standalone briefBlockMissing/briefBlockOverCap
+ * accessors delegate here, so the shared and standalone paths cannot disagree. The snapshot
+ * used to call those two accessors, each calling readBrief — which re-lists both candidates
+ * and re-reads the whole brief file — twice per poll, on a file that changes only when a role
+ * edits it. briefStatus is the degraded-state twin of readBrief's promise (briefFile +
+ * readBriefText derive from one scan): the two flags share one read, and each flag applies the
+ * value's own predicate. `missing` is true when a candidate exists but none resolves a
+ * non-empty block (or the resolving read threw); `overCap` true when the resolved block
+ * exceeds the cap. A repo with no candidate at all is neither (both false). */
+export function briefStatus(root) {
+    if (briefCandidates(root).every((candidate) => !fs.existsSync(candidate))) {
+        return { missing: false, overCap: false };
+    }
+    let prompt = "";
     try {
-        return (readBrief(root)?.prompt.length ?? 0) > BRIEF_TEXT_MAX_CHARS;
+        prompt = readBrief(root)?.prompt ?? "";
     }
     catch {
-        return false;
+        return { missing: true, overCap: false }; // Unreadable — the briefBlockMissing subset.
     }
+    return { missing: prompt === "", overCap: prompt.length > BRIEF_TEXT_MAX_CHARS };
 }
 /** The project's brief text, extracted from the resolved brief file's managed section —
  * TUMWATER.md when it exists with markers, else README.md (plans/portability.md §7a/7). The

package/dist/src/budget/budget.js

@@ -152,11 +152,10 @@ export function modelPairName(p) {
  * `strong` tiers resolved to a usable free pair (resolveTierFallbacks over the full usable
  * predicate — price AND breaker serving) — plus whether the review gate is on. The gate is
  * `paused` when `default` resolves to pause (nothing for the team's bulk to run on), or when
- * review is on and `strong` does (nothing could merge for the roles a pre-merge review gates, so
- * their authoring runs are wasted work — a `review.afterMerge` role's is not);
- * `fallback` otherwise, with the tiers that did resolve running their pairs and the rest held
- * per role. The single definition of the gate: the orchestrator enforces it and both dashboards
- * display it, so what an operator sees is what the scheduler is doing. */
+ * review is on and `strong` does; `fallback` otherwise, with the tiers that did resolve running
+ * their pairs and the rest held per role. This is the value the dashboards display; the
+ * orchestrator's role holds come from the per-tier set `budgetPausedRoles` (a tier whose own
+ * pair did not resolve), not from a reviewer-derived team-wide pause. */
 export function budgetGate(reached, tiers, reviewOn) {
     if (!reached)
         return "open";

package/dist/src/build/build-check-report.js

@@ -125,6 +125,16 @@ export function failureHeadline(tail) {
 export function describeCheck(check) {
     return check.kind === "npm" ? `\`npm run ${check.script}\`` : `\`${check.command}\``;
 }
+/** The single-line headline of a red check — the failureHeadline when the tail has one to
+ * offer (a test name or marker plus a non-framing message), else the check's describeCheck
+ * command name — the name the gate, merge, and review warnings print for a failed check.
+ * One definition for every red that names itself to a human: review-precheck's two
+ * flake/failure warnings, merge-to-main's merge-retry quarantine warning, and
+ * merge-check-failures's kept-pin headline record and attributeRedCheck absent-tail headline.
+ */
+export function redCheckHeadline(check, tail) {
+    return failureHeadline(tail) ?? describeCheck(check);
+}
 /** The machine-generated reasons a red check hands its author: the headline joined to the rest of
  * the clipped tail, so the compiler error sits right after it in the injected next-run note. The
  * headline is failureHeadline's — the first line that is not a stack frame — not outputTail[0]: a

package/dist/src/build/build-check-scoped.js

@@ -33,8 +33,6 @@ function resolveScopedCheck(wt, scope, config, timeoutMs, sampleLoad) {
  * the one-permit-two-attempt rule. Prices the first attempt as its own build_check event and
  * returns the final outcome and its run duration. */
 async function runScopedCheckWithRetry(root, role, scope, wt, runCheck, timeoutMs, config, sampleSleep, install, permitWait, cheaper, signal) {
-    // One permit covers both attempts (the killed-check retry re-runs under the permit it
-    // holds); durationMs prices the run itself, not the wait for a permit.
     let durationMs = 0;
     const raw = await withCheckPermit(config, MERGE_SCOPES.has(scope) ? CHECK_TIER.merge : CHECK_TIER.other, async () => {
         // One permit covers both attempts (the killed-check retry re-runs under the permit it

package/dist/src/build/build-stage.js

@@ -213,7 +213,8 @@ export function swapDist(root, dist, mainHead) {
  * swap can close the window, because the survivor is the supervisor and it exits on the dead
  * generation; the next `tumwater start` then cannot even load `dist/src/cli.js` and fails with
  * MODULE_NOT_FOUND, so the repo is wedged until someone renames `dist.prev` back by hand. The
- * supervisor calls this before it exits (src/cli/cli-start.ts, via superviseStart's onDone): while
+ * supervisor calls this before it exits (src/cli/cli-start-supervisor.ts, via superviseStart's
+ * onDone): while
  * it is still up, it renames the preserved old build back into place so the next boot works.
  *
  * Only acts when `dist` is missing and a `dist.prev` exists — both conditions together are the
@@ -228,11 +229,12 @@ export function recoverInterruptedSwap(root, dist) {
     fs.renameSync(prev, dist); // Atomic: dist is either the restored old build or still missing.
     return true;
 }
-/** The supervisor's end-of-supervision repair (src/cli/cli-start.ts wires this into
+/** The supervisor's end-of-supervision repair (src/cli/cli-start-supervisor.ts wires this into
  * superviseStart's onDone): recover dist/ after an interrupted swap and, either way, put the
  * outcome on the event feed. Kept beside recoverInterruptedSwap so the CLI wiring is one call.
- * cli-start.ts imports this module statically, so the code is in memory before a swap can move
- * dist/ away — recovering via an import at call time would fail ERR_MODULE_NOT_FOUND exactly
+ * cli-start-supervisor.ts imports this module statically, so the code is in memory before a
+ * swap can move dist/ away — recovering via an import at call time would fail
+ * ERR_MODULE_NOT_FOUND exactly
  * when it is needed, the window this closes. `dist` defaults to this process's own dist
  * (build-info.distDir, a pure path computation captured at load), overridable so a test can
  * point it at a temp root. A failed restore is reported, never thrown: the hook runs on the

package/dist/src/change/change-data.js

@@ -9,7 +9,7 @@
 import { knownRoleIdsCached, loadConfigSafe } from "../config/config.js";
 import { aheadOfMain, branchExists, countCommitsInRange, currentBranch, targetBranch } from "../git/git.js";
 import { gitTry } from "../git/git-run.js";
-import { aheadOfMainDiff, aheadOfMainFiles, changedFiles } from "../git/git-diff.js";
+import { aheadOfMainDiff, aheadOfMainFiles, changedFiles, DIFF_MAX_BYTES } from "../git/git-diff.js";
 import { compareCodeUnits } from "../collections.js";
 import { isAbsolute } from "node:path";
 import { branchName } from "../paths.js";
@@ -44,9 +44,6 @@ export async function collectRoleChanges(root, roles, opts = {}) {
     const views = await Promise.all(roles.map((role) => collectRoleChangeAt(root, role, scope, opts)));
     return { mainBranch: scope.mainBranch, roles: views };
 }
-/** The uncommitted patch's cap, matching aheadOfMainDiff's — one shared bound so neither
- * half of the view can print unbounded text. */
-const DIFF_MAX_BYTES = 200_000;
 /** Collect the change the role holds: both halves of the view, or a degraded state
  * when the worktree or the base branch is missing. Never throws on a degraded team — a
  * query about a role that has not run yet must answer, not fail (report's rationale). */

package/dist/src/cli/cli-completion-command.js

@@ -0,0 +1,75 @@
+import { completionConfigKeys, completionModels, completionRoleIds, completionScript, configValueWords, SUPPORTED_SHELLS, } from "./completion.js";
+import { say, fail } from "./cli-output.js";
+import { gotSuffix } from "../text/text.js";
+import { typoSuffix } from "../text/suggest.js";
+/** `tumwater completion`'s command body — the shell-completion script and its --roles/
+ * --config-keys/--config-value/--models listing shapes. The completion data lives in
+ * src/cli/completion.ts (the spec parser, the completionScript emitter and the read-only
+ * listing helpers); this module answers a `completion` invocation, split out of cli.ts so the
+ * dispatcher stays the pure shared sequence and this command body sits beside its data the
+ * way every other command body does. Imported lazily by cli.ts like each command body. */
+function printCompletionRoles(root) {
+    for (const id of completionRoleIds(root))
+        say(id);
+}
+function printCompletionConfigKeys(root) {
+    for (const key of completionConfigKeys(root))
+        say(key);
+}
+function printCompletionConfigValue(key) {
+    // 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(key))
+        say(word);
+}
+function printCompletionModels(root) {
+    for (const m of completionModels(root))
+        say(m);
+}
+const COMPLETION_LISTING_SHAPES = {
+    "--roles": "roles",
+    "--config-keys": "config-keys",
+    "--models": "models",
+};
+function completionListShape(args) {
+    if (args.length === 1 && args[0] in COMPLETION_LISTING_SHAPES)
+        return COMPLETION_LISTING_SHAPES[args[0]];
+    if (args.length === 2 && args[0] === "--config-value")
+        return "config-value";
+    return null;
+}
+function completionShell(args) {
+    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)}`);
+    return shell;
+}
+/** Answer a `tumwater completion` invocation. Works outside a repo (no requireReadyRepo). */
+export async function cmdCompletion(root, args) {
+    const shape = completionListShape(args);
+    if (shape === "roles") {
+        printCompletionRoles(root);
+        return;
+    }
+    if (shape === "config-keys") {
+        printCompletionConfigKeys(root);
+        return;
+    }
+    if (shape === "config-value") {
+        printCompletionConfigValue(args[1]);
+        return;
+    }
+    if (shape === "models") {
+        printCompletionModels(root);
+        return;
+    }
+    say(completionScript(completionShell(args)));
+}

package/dist/src/cli/cli-doctor-command.js

@@ -0,0 +1,103 @@
+import { rejectUnknownArgs, JSON_FLAG, PROBLEMS_FLAG, KILL_ORPHANS_FLAG, COMMIT_BACKLOG_FLAG, RESYNC_INSTALL_FLAG, DROP_BROKEN_PINS_FLAG, RETIRE_LEFTOVERS_FLAG, } from "./cli-flag-specs.js";
+import { say, sayJsonOrRender } from "./cli-output.js";
+import { parseDoctorChecks, peelPositionals } from "./cli-command-args.js";
+import { loadConfigSafe } from "../config/config.js";
+/** Run one doctor side-effect (`--kill-orphans`, `--commit-backlog`, `--resync-install`,
+ * `--drop-broken-pins`, `--retire-leftovers`) and return its report payload for the optional
+ * `--json` run — the shape every doctor*Case side-effect wrapper follows: import the effect's
+ * module and run it only when its flag is present, then (text form only) print the effect's
+ * own lines before the report with a separating blank line when there is anything to print;
+ * `--json` keeps stdout one document, carrying the result on the payload instead. The lazy
+ * per-effect `load` keeps each module imported only when its flag is asked for. */
+async function doctorSideEffect(args, flag, load) {
+    if (!args.includes(flag))
+        return undefined;
+    const { run, lines } = await load();
+    const payload = await run();
+    // The text form prints the effect before the report; --json keeps stdout one document.
+    if (!args.includes("--json")) {
+        const out = lines(payload);
+        for (const line of out)
+            say(line);
+        if (out.length > 0)
+            say("");
+    }
+    return payload;
+}
+async function doctorKillOrphans(root, args) {
+    return doctorSideEffect(args, "--kill-orphans", async () => {
+        const { killOrphans, orphanKillLines } = await import("../doctor/doctor-orphans.js");
+        return { run: () => killOrphans(root), lines: orphanKillLines };
+    });
+}
+async function doctorCommitBacklog(root, args) {
+    return doctorSideEffect(args, "--commit-backlog", async () => {
+        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
+        return { run: () => commitUncommittedBacklog(root, config), lines: backlogCommitLines };
+    });
+}
+async function doctorResyncInstall(root, args) {
+    return doctorSideEffect(args, "--resync-install", async () => {
+        const { resyncRootInstall, rootInstallResyncLines } = await import("../build/dep-install.js");
+        return { run: () => resyncRootInstall(root), lines: rootInstallResyncLines };
+    });
+}
+async function doctorDropBrokenPins(root, args) {
+    return doctorSideEffect(args, "--drop-broken-pins", async () => {
+        const { dropBrokenPins, brokenPinDropLines } = await import("../doctor/doctor-contention-checks.js");
+        return { run: () => dropBrokenPins(root), lines: brokenPinDropLines };
+    });
+}
+async function doctorRetireLeftovers(root, args) {
+    return doctorSideEffect(args, "--retire-leftovers", async () => {
+        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
+        return { run: () => retireLeftovers(root, config), lines: leftoverRetireLines };
+    });
+}
+function doctorPayload(payload, parts) {
+    const out = { ...payload };
+    if (parts.leftoverRetire !== undefined)
+        out.leftoverRetire = parts.leftoverRetire;
+    if (parts.brokenPinDrop !== undefined)
+        out.brokenPinDrop = parts.brokenPinDrop;
+    if (parts.resyncInstall !== undefined)
+        out.resyncInstall = parts.resyncInstall;
+    if (parts.backlogCommit !== undefined)
+        out.backlogCommit = parts.backlogCommit;
+    if (parts.orphanKill !== undefined)
+        out.orphanKill = parts.orphanKill;
+    return out;
+}
+/** `tumwater doctor`: report what in the environment is keeping the team from running, and
+ * run the optional repair side-effects. 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. */
+export async function cmdDoctor(root, args) {
+    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");
+    const parts = {
+        orphanKill: await doctorKillOrphans(root, args),
+        backlogCommit: await doctorCommitBacklog(root, args),
+        resyncInstall: await doctorResyncInstall(root, args),
+        brokenPinDrop: await doctorDropBrokenPins(root, args),
+        leftoverRetire: await doctorRetireLeftovers(root, args),
+    };
+    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`.
+    if (args.includes("--problems"))
+        sayJsonOrRender(args, args.includes("--json") ? doctorPayload(problemsOnly(report), parts) : report, renderDoctorProblems);
+    else
+        sayJsonOrRender(args, args.includes("--json") ? doctorPayload(report, parts) : report, renderDoctor);
+    if (report.checks.some((c) => c.level === "fail"))
+        process.exitCode = 1; // Warnings never fail the exit.
+}

package/dist/src/cli/cli-init.js

@@ -1,7 +1,7 @@
 /** `tumwater init`'s implementation (src/init/init.ts does the work; this prints the report).
  * Split out of cli/cli-start.ts, whose name is for start alone: every command it dispatches
- * delegates to its own module (operator/operator-commands.ts, config-commands.ts, log-commands.ts,
- * doctor.ts, …), and init is no exception. cli.ts stays the pure dispatcher. */
+ * delegates to its own module (cli-config-commands.ts, cli-log-commands.ts, doctor.ts, …), and init
+ * is no exception. cli.ts stays the pure dispatcher. */
 import { say } from "./cli-output.js";
 import { parseInitArgs } from "./cli-command-args.js";
 import { initProject } from "../init/init.js";

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

@@ -1,6 +1,6 @@
 /** The read-only query commands' bodies (status, diff, queue, backlog), split out of
  * cli.ts's dispatcher: main() routes to a cmd* here exactly as it routes to operator-commands's
- * cmdAbort or config-commands's cmdConfig, and cli.ts keeps only routing and the help/version
+ * cmdAbort or cli-config-commands's cmdConfig, and cli.ts keeps only routing and the help/version
  * surfaces. Each command owns its argument gate, ready-repo gating decision, and output shape,
  * with the wording and gating order moved verbatim from main()'s cases. */
 import { fail, say, sayJson, sayJsonOrRender } from "./cli-output.js";

package/dist/src/cli/cli-role-command.js

@@ -1,7 +1,7 @@
 /** `tumwater role <id>`'s command body, split out of cli-query-commands.ts so that module
  * keeps only the read-only query commands (status, diff, queue, backlog). cli.ts's dispatcher
  * routes to cmdRole here exactly as it routes cmdStatus to cli-query-commands or cmdConfig to
- * config-commands. cmdRole is the one query-named command that also writes: it renders a
+ * cli-config-commands. cmdRole is the one query-named command that also writes: it renders a
  * role's standing and next-run prompts and carries eleven per-role write flags (notes,
  * instructions, quiet-hours, daily cap, min-run-interval, instances, enable/disable, and the
  * provider/model/thinking/backend), each through the same setConfigKey/unsetConfigKey core
@@ -56,10 +56,6 @@ const INSTANCES_SPEC = { names: ["--instances"], value: true, valueName: "<n>" }
  * roles.<base>.enabled. */
 const ENABLE_SPEC = { names: ["--enable"] };
 const DISABLE_SPEC = { names: ["--disable"] };
-/** `role`'s review-after-merge write flags: add the role to, or remove it from,
- * review.afterMerge (written for the base id). */
-const REVIEW_AFTER_MERGE_SPEC = { names: ["--review-after-merge"] };
-const CLEAR_REVIEW_AFTER_MERGE_SPEC = { names: ["--clear-review-after-merge"] };
 /** `role`'s model-triple write flags: clear the field, or set it, written to
  * roles.<base>.provider/.model/.thinking. model and provider take an id; thinking takes a
  * pi `--thinking` level (off|minimal|low|medium|high|xhigh|max). */
@@ -175,7 +171,7 @@ export async function cmdRole(root, args) {
         if (next?.startsWith("--"))
             fail(`${flag} needs a value (the next token ${JSON.stringify(next)} is a flag, not a value)`);
     }
-    rejectUnknownArgs("role", rest, [ROLE_FLAG, JSON_FLAG, CLEAR_NOTES_SPEC, NOTES_FILE_SPEC, CLEAR_INSTRUCTIONS_SPEC, INSTRUCTIONS_FILE_SPEC, CLEAR_QUIET_HOURS_SPEC, QUIET_HOURS_SPEC, ENABLE_SPEC, DISABLE_SPEC, CLEAR_CAP_SPEC, CAP_SPEC, CLEAR_MIN_RUN_INTERVAL_SPEC, MIN_RUN_INTERVAL_SPEC, CLEAR_INSTANCES_SPEC, INSTANCES_SPEC, CLEAR_PROVIDER_SPEC, PROVIDER_SPEC, CLEAR_MODEL_SPEC, MODEL_SPEC, CLEAR_THINKING_SPEC, THINKING_SPEC, CLEAR_BACKEND_SPEC, BACKEND_SPEC, REVIEW_AFTER_MERGE_SPEC, CLEAR_REVIEW_AFTER_MERGE_SPEC]);
+    rejectUnknownArgs("role", rest, [ROLE_FLAG, JSON_FLAG, CLEAR_NOTES_SPEC, NOTES_FILE_SPEC, CLEAR_INSTRUCTIONS_SPEC, INSTRUCTIONS_FILE_SPEC, CLEAR_QUIET_HOURS_SPEC, QUIET_HOURS_SPEC, ENABLE_SPEC, DISABLE_SPEC, CLEAR_CAP_SPEC, CAP_SPEC, CLEAR_MIN_RUN_INTERVAL_SPEC, MIN_RUN_INTERVAL_SPEC, CLEAR_INSTANCES_SPEC, INSTANCES_SPEC, CLEAR_PROVIDER_SPEC, PROVIDER_SPEC, CLEAR_MODEL_SPEC, MODEL_SPEC, CLEAR_THINKING_SPEC, THINKING_SPEC, CLEAR_BACKEND_SPEC, BACKEND_SPEC]);
     refuseTeamWorkspace(root);
     // The id is required: positional (`tumwater role <id>`) or --role <id> (the flag
     // spelling every other role-targeting command shares). Both at once is a mistake, not
@@ -211,9 +207,6 @@ export async function cmdRole(root, args) {
     const backendWrite = clearBackend || rest.includes("--backend");
     const enable = rest.includes("--enable");
     const disable = rest.includes("--disable");
-    const reviewAfterMerge = rest.includes("--review-after-merge");
-    const clearReviewAfterMerge = rest.includes("--clear-review-after-merge");
-    const reviewAfterMergeWrite = reviewAfterMerge || clearReviewAfterMerge;
     const writes = [];
     if (notesWrite)
         writes.push("notes");
@@ -239,8 +232,6 @@ export async function cmdRole(root, args) {
         writes.push("enable");
     if (disable)
         writes.push("disable");
-    if (reviewAfterMergeWrite)
-        writes.push("review-after-merge");
     if (writes.length > 1)
         fail(`${writes.join(" and ")} writes cannot share one invocation`);
     if (notesWrite) {
@@ -443,36 +434,6 @@ export async function cmdRole(root, args) {
         say(`${base}: ${state}`);
         return;
     }
-    // The review-after-merge write: the one command the post-merge churn row's remedy
-    // needs — add the role to, or remove it from, review.afterMerge for the base id, the
-    // membership test reviewedAfterMerge shares. The whole-list value lands through the same
-    // setConfigKey core `config set review.afterMerge <json>` uses, so validateConfig owns the
-    // string-array shape, the known-role-id check and the `review.afterMerge must not be
-    // "director"` refusal, and the write is atomic. A role already in the asked-for state is
-    // reported as such and the file is left alone (the section branch compares the value
-    // against the resolved list, so a no-op reports unchanged and writes nothing).
-    if (reviewAfterMergeWrite) {
-        if (reviewAfterMerge && clearReviewAfterMerge)
-            fail("give --review-after-merge or --clear-review-after-merge, not both");
-        if (rest.includes("--json"))
-            fail("--json does not apply to a review-after-merge write");
-        requireKnownRole(root, id);
-        const base = baseRoleOf(id);
-        const list = loadConfigSafe(root).config?.review.afterMerge ?? [];
-        const has = list.includes(base);
-        const next = has === reviewAfterMerge ? list : reviewAfterMerge ? [...list, base] : list.filter((r) => r !== base);
-        const result = setConfigKey(root, "review.afterMerge", JSON.stringify(next));
-        if (!result.ok)
-            fail(result.error);
-        say(result.unchanged
-            ? reviewAfterMerge
-                ? `${base}: already in review.afterMerge, so tumwater.json was not written`
-                : `${base}: not in review.afterMerge, so nothing was cleared`
-            : reviewAfterMerge
-                ? `${base}: added to review.afterMerge`
-                : `${base}: removed from review.afterMerge`);
-        return;
-    }
     // The unknown-role answer (exit 1, unknownRoleMessage's wording) lives in the
     // collector; here the id just has to be non-null for the thunk's types.
     sayJsonOrRender(rest, () => rolePayload(root, id), renderRoleMarkdown);