tumwater 0.4.2 → 0.4.3

package/dist/src/cli.js

@@ -125,77 +125,88 @@ async function cmdReportCase(root, args) {
     // trailing window vs a series over whole days), not a modifier of either.
     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);
+/** 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("");
-        }
     }
-    let backlogCommit;
-    if (args.includes("--commit-backlog")) {
+    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
-        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")) {
+        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");
-        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")) {
+        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");
-        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")) {
+        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
-        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("");
-        }
-    }
+        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;
+}
+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");
+    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
@@ -204,15 +215,10 @@ async function cmdDoctorCase(root, args) {
     // --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);
+        sayJsonOrRender(args, args.includes("--json") ? doctorPayload(problemsOnly(report), parts) : report, renderDoctorProblems);
     else
-        sayJsonOrRender(args, args.includes("--json") ? withLeftoverRetire(report) : report, renderDoctor);
+        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.
 }
@@ -267,69 +273,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,31 +382,38 @@ 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;
-    }
+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
@@ -399,7 +424,28 @@ async function cmdCompletionCase(root, args) {
         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));
+    return shell;
+}
+async function cmdCompletionCase(root, args) {
+    // Works outside a repo: no requireReadyRepo.
+    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)));
 }
 async function cmdVersionCase(args) {
     // A stray flag fails like every other command's: `tumwater version --json` (a plausible

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,26 @@ 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), and the report
+ * scope fold (report/report-fold.ts's scopeBases), 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,7 +65,7 @@ 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
  * (doctor/doctor-project-checks.ts), and the multi-runner base tally
@@ -125,11 +140,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 +158,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 };
@@ -200,7 +215,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);
+}

package/dist/src/concurrency/lock.js

@@ -93,6 +93,10 @@ function releaseOwnedLock(dir) {
         return;
     rmLockDir(dir);
 }
+/** The ledger-facing release primitive: the same releaseOwnedLock every mutex exits with, but
+ * exported so src/concurrency/check-slots.ts can hand a suite's slot back without re-implementing
+ * the owned-pid guard (a holder whose lock was stolen must not delete its successor's dir). */
+export const releaseOwnedLockDir = releaseOwnedLock;
 function acquireStep(dir, timeoutMs, waitedMs) {
     // An existing path is a held lock to wait on (and maybe break); publishLockDir is only for
     // an absent path, so a read-only parent that already holds a stale lock reports contention
@@ -149,6 +153,24 @@ function publishLockDir(dir) {
         throw err;
     }
 }
+/** The one-shot claim step of the lock protocol, exported for a caller that wants a single
+ * best-effort claim rather than withLock's retry loop: claim `dir` by atomic publish, returning
+ * true on success and false when `dir` already exists (a live holder) or contention — never
+ * throwing, unlike publishLockDir. The suite-slot ledger (check-slots.ts) calls it per index as
+ * it walks a ledger, so it must not throw on a held slot to inspect the others. A genuine
+ * filesystem failure (ENOSPC, a read-only parent) also returns false; the ledger degrades to
+ * "run unpermitted" on an unable-to-create ledger, which suits a best-effort scheduling cap. */
+export function tryClaimLockDir(dir) {
+    try {
+        if (fs.existsSync(dir))
+            return false; // A held slot (live or stale) — the caller walks on.
+        publishLockDir(dir);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /** Remove `.acquiring-*` temp dirs left beside a lock by a creator that crashed before its
  * rename — the one remnant atomic publication can leave. Only dirs older than STALE_MS are
  * touched, far beyond any scheduling stall, so a live creator's in-flight temp is never

package/dist/src/concurrency/run-permit.js

@@ -0,0 +1,49 @@
+/** The AsyncLocalStorage store that carries a run's lease across its work: a lease rides here
+ * for the length of a run, so an idle stretch inside it (a failed review's in-place retry
+ * pause, called via idleWithoutPermit) can hand the team permit back and re-take it, letting a
+ * parked run use the slot meanwhile. The check-permit.ts `holdingPermit` store is the pattern:
+ * nothing here is a separate permit, only the single lease the run path already holds. */
+import { AsyncLocalStorage } from "node:async_hooks";
+const runPermitStore = new AsyncLocalStorage();
+/** Run `run` with `lease` in the run-permit store, so an idle wait inside it can pause and
+ * resume the same team permit. The same lease object is released by the caller after the store
+ * is unwrapped. */
+export function withRunPermit(lease, run) {
+    return runPermitStore.run({ lease }, run);
+}
+/** Run `wait`, an idle stretch inside the calling lease's work, with the lease's team permit
+ * handed back (SemaphoreLease.pause), so a parked run can use it meanwhile, then take it back
+ * (resume) before returning. A failed review's in-place retry pause is the caller: with one
+ * team permit, a reviewer that kept failing held it through two 30 s pauses and starved every
+ * other role. Once `signal` has fired, nothing is taken back and the caller's release() settles
+ * a still-paused lease. No-op without a lease in context. */
+export async function idleWithoutPermit(wait, signal) {
+    const ctx = runPermitStore.getStore();
+    if (!ctx)
+        return wait();
+    ctx.lease.pause();
+    try {
+        await wait();
+    }
+    finally {
+        if (!signal?.aborted)
+            await untilAborted(ctx.lease.resume(), signal);
+    }
+}
+/** `p`, or an earlier return once `signal` fires: a resume parked on a full team must not keep an
+ * aborted verification waiting for a permit it no longer needs. */
+async function untilAborted(p, signal) {
+    if (!signal)
+        return p;
+    let onAbort = () => { };
+    const aborted = new Promise((resolve) => {
+        onAbort = resolve;
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+    try {
+        await Promise.race([p, aborted]);
+    }
+    finally {
+        signal.removeEventListener("abort", onAbort);
+    }
+}