tumwater 0.1.2 → 0.2.0

package/dist/src/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// vocabulary: plain
 /** The CLI's entry point and command dispatcher — the `bin` target package.json points at
  * (dist/src/cli.js). main() runs the Node-floor gate from package.json's `engines.node`, answers a
  * `--help` topic before any command parses arguments or gates on a ready repo, resolves the repo
@@ -7,23 +8,39 @@
  * statically loads only the argument parsing, output, repo gate and help it shares, so
  * `tumwater report` never pays for the orchestrator or ink, and `tumwater logs` never pays for
  * the status collectors. A process that starts, runs one command and exits (the CLI as the
- * fleet's agents and the test suite call it, ~700 spawns a suite run) otherwise compiled all
+ * team's agents and the test suite call it, ~700 spawns a suite run) otherwise compiled all
  * 169 modules every time. The work itself lives in the command
  * modules; this file owns the shared sequence, including each case's flag rejection and its
  * ready-repo gate. An error escaping main() funnels through its catch to fail(errorMessage(err)),
  * the CLI's one error path. */
 import { parseCountFlag, } from "./cli/cli-args.js";
-import { grepFlagSpec, GUI_FLAG_SPECS, JSON_FLAG, LAST_FLAG, N_FLAG, rejectUnknownArgs, resultFlagSpec, ROLE_FLAG, RUN_FLAG_SPECS, sinceFlagSpec, FORCE_FLAG, } from "./cli/cli-flag-specs.js";
+import { grepFlagSpec, GUI_FLAG_SPECS, JSON_FLAG, LAST_FLAG, N_FLAG, rejectUnknownArgs, resultFlagSpec, ROLE_FLAG, RUN_FLAG_SPECS, sinceFlagSpec, STAT_FLAG, SUMMARY_FLAG, COUNT_FLAG, typeFlagSpec, DRY_RUN_FLAG, FORCE_FLAG, STOP_CANCEL_FLAG, STOP_IN_FLAG, REPROBE_FLAG, PROBLEMS_FLAG, } from "./cli/cli-flag-specs.js";
 import { fail, say, sayJsonOrRender } from "./cli/cli-output.js";
-import { parsePromptArgs, peelPositionals } from "./cli/cli-command-args.js";
+import { historyTrailForm, parsePromptArgs, peelPositionals } from "./cli/cli-command-args.js";
 import { requireReadyRepo } from "./cli/cli-repo-gate.js";
 import { repoToplevel } from "./git/git.js";
 import { didYouMean } from "./text/suggest.js";
 import { errorMessage, gotSuffix, stripTerminalControls } from "./text/text.js";
+import { typoSuffix } from "./text/suggest.js";
+import { completionConfigKeys, completionRoleIds, completionScript, SUPPORTED_SHELLS } from "./cli/completion.js";
 import { HELP, helpTopic, helpTopicForArgs, suggestCommand } from "./cli/help.js";
 import { PACKAGE_JSON, nodeFloorProblem, packageEnginesNode, packageVersion } from "./version.js";
 // The CLI's help text and its per-command topic parser live in help.ts — importing cli.ts
 // would run main(), so tests pin the topics against help.ts directly.
+/** One run's trail, shared by `history <role> <n>` and its hidden alias `tick` so the two cannot
+ * drift. Positional-first: the <role> <n> tokens peel off and the remaining flags go through
+ * rejectUnknownArgs (only --json, --last, --stat), so a listing flag such as --role is refused.
+ * Arity is gated before the ready-repo check so a malformed call fails with its usage in any
+ * directory; cmdTick owns the value validation and the --last/numbered rivals. */
+async function runTrailCommand(root, args) {
+    const { cmdTick, TICK_USAGE } = await import("./tick/tick-detail.js");
+    const { positionals, rest } = peelPositionals(args);
+    rejectUnknownArgs("history", rest, [JSON_FLAG, LAST_FLAG, STAT_FLAG]);
+    if (positionals.length < 1 || positionals.length > 2)
+        fail(`usage: ${TICK_USAGE}`);
+    await requireReadyRepo(root);
+    await cmdTick(root, positionals, rest.includes("--json"), rest.includes("--last"), rest.includes("--stat"));
+}
 async function main() {
     const [, , command, ...args] = process.argv;
     // The Node-floor gate, before any command does work: package.json's engines spec is the
@@ -55,14 +72,15 @@ async function main() {
     const root = (await repoToplevel(process.cwd())) ?? process.cwd();
     switch (command) {
         case "init":
-            // Imported lazily: cli/cli-run.ts pulls the whole fleet-booting subgraph (orchestrator,
+            // Imported lazily: cli/cli-run.ts pulls the whole team-booting subgraph (orchestrator,
             // supervisor, redeploy, launch-services — the run path's machinery), and every other
             // command's spawn pays module compilation for it unless the dispatch defers that load
-            // to the commands that actually boot or serve a fleet.
+            // to the commands that actually boot or serve a team.
             await (await import("./cli/cli-run.js")).cmdInit(root, args);
             break;
+        case "start":
         case "run":
-            rejectUnknownArgs("run", args, RUN_FLAG_SPECS);
+            rejectUnknownArgs("start", args, RUN_FLAG_SPECS);
             await (await import("./cli/cli-run.js")).cmdRun(root, args);
             break;
         case "tui":
@@ -131,26 +149,37 @@ async function main() {
         case "doctor": {
             // No requireReadyRepo gate: doctor's job is to report WHY the environment isn't ready,
             // so it must run outside a git repo and print fail lines rather than throwing.
-            rejectUnknownArgs("doctor", args, [JSON_FLAG]);
+            rejectUnknownArgs("doctor", args, [JSON_FLAG, REPROBE_FLAG, PROBLEMS_FLAG]);
             const { runDoctor } = await import("./doctor/doctor.js");
-            const { renderDoctor } = await import("./doctor/doctor-render.js");
-            const report = await runDoctor(root);
+            const { renderDoctor, renderDoctorProblems, problemsOnly } = await import("./doctor/doctor-render.js");
+            // The terminal probes unclaimed-verified models by default (7-day cache); --reprobe
+            // forces every claimed model. The TUI/GUI call runDoctor with the default "never", so a
+            // refresh never spends a model call.
+            const probeImages = args.includes("--reprobe") ? "all" : "missing";
+            const report = await runDoctor(root, undefined, undefined, probeImages);
             // --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.
-            sayJsonOrRender(args, report, renderDoctor);
+            // --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.
+            if (args.includes("--problems"))
+                sayJsonOrRender(args, args.includes("--json") ? problemsOnly(report) : report, renderDoctorProblems);
+            else
+                sayJsonOrRender(args, report, renderDoctor);
             if (report.checks.some((c) => c.level === "fail"))
                 process.exitCode = 1; // Warnings never fail the exit.
             break;
         }
         case "logs": {
-            const { cmdLogs, GREP_VALUE_ERROR } = await import("./cli/log-commands.js");
+            const { cmdLogs, GREP_VALUE_ERROR, TYPE_VALUE_ERROR } = await import("./cli/log-commands.js");
             rejectUnknownArgs("logs", args, [
                 { names: ["-f", "--follow"] },
                 N_FLAG,
                 sinceFlagSpec("logs --since"),
                 grepFlagSpec(GREP_VALUE_ERROR),
+                typeFlagSpec(TYPE_VALUE_ERROR),
                 JSON_FLAG,
+                COUNT_FLAG,
                 ROLE_FLAG,
                 { names: ["--prompt"] },
             ]);
@@ -165,6 +194,10 @@ async function main() {
             break;
         case "history": {
             const { cmdHistory, HISTORY_GREP_VALUE_ERROR, HISTORY_RESULT_VALUE_ERROR } = await import("./history/history.js");
+            if (historyTrailForm(args)) {
+                await runTrailCommand(root, args);
+                break;
+            }
             rejectUnknownArgs("history", args, [
                 N_FLAG,
                 sinceFlagSpec("history --since"),
@@ -172,30 +205,15 @@ async function main() {
                 resultFlagSpec(HISTORY_RESULT_VALUE_ERROR),
                 JSON_FLAG,
                 ROLE_FLAG,
+                SUMMARY_FLAG,
             ]);
             await requireReadyRepo(root);
             await cmdHistory(root, args);
             break;
         }
-        case "tick": {
-            const { cmdTick, TICK_USAGE } = await import("./tick/tick-detail.js");
-            // Positional-first command (the role command's pattern): the <role> <n> tokens peel off,
-            // the flags that remain go through rejectUnknownArgs (only --json is admitted), and
-            // cmdTick owns the arity and value validation — a missing role, an unknown id, a
-            // non-positive or non-numeric n, or a stray extra positional fails there with the usage.
-            const { positionals, rest } = peelPositionals(args);
-            rejectUnknownArgs("tick", rest, [JSON_FLAG, LAST_FLAG]);
-            // Arity before the ready-repo gate (the config subcommands' precedent): a malformed
-            // invocation fails with its usage no matter the directory. cmdTick keeps the guard too —
-            // in-process callers reach it without this dispatcher. One positional is the --last
-            // form (<role>), two is the numbered pair (<role> <n>); cmdTick picks the arity by the
-            // flag, so the gate stays loose here and the rivals check lives there.
-            if (positionals.length < 1 || positionals.length > 2)
-                fail(`usage: ${TICK_USAGE}`);
-            await requireReadyRepo(root);
-            await cmdTick(root, positionals, rest.includes("--json"), rest.includes("--last"));
+        case "tick": // vocabulary-ok: command name stays
+            await runTrailCommand(root, args);
             break;
-        }
         case "diff":
             await (await import("./cli/cli-query-commands.js")).cmdDiff(root, args);
             break;
@@ -205,9 +223,19 @@ async function main() {
         case "backlog":
             await (await import("./cli/cli-query-commands.js")).cmdBacklog(root, args);
             break;
+        case "archive":
+            rejectUnknownArgs("archive", args, []);
+            await requireReadyRepo(root);
+            await (await import("./backlog/backlog-cli.js")).cmdArchive(root);
+            break;
         case "bug": {
-            const { OPERATOR_FILE_KINDS, bugTitleOf, bugWakeText, cancelAndAnnounce, cancelBug, editAndAnnounce, editBug, editBugFromText, fileBug, fileBugFromText, fileAndAnnounce, listAndAnnounce } = await import("./backlog/backlog-write.js");
+            const { OPERATOR_FILE_KINDS, bugWakeText, cancelBug, moveEntryToTop, releaseEntry, editBug, editBugFromText, fileBug, fileBugFromText } = await import("./backlog/backlog-write.js");
+            const { bugTitleOf, cancelAndAnnounce, releaseAndAnnounce, topAndAnnounce, editAndAnnounce, fileAndAnnounce, listAndAnnounce, showAndAnnounce } = await import("./backlog/backlog-cli.js");
             const usage = 'tumwater bug "<symptom>"';
+            if (args.includes("--show")) {
+                showAndAnnounce(root, args, "bug");
+                break;
+            }
             if (args.includes("--list")) {
                 listAndAnnounce(root, args, "bug", "BUGS.md", "Open");
                 break;
@@ -220,12 +248,25 @@ async function main() {
                 await cancelAndAnnounce(root, args, "bug", (n) => cancelBug(root, n));
                 break;
             }
+            if (args.includes("--top")) {
+                await topAndAnnounce(root, args, "bug", (n) => moveEntryToTop(root, "bug", n));
+                break;
+            }
+            if (args.includes("--release")) {
+                await releaseAndAnnounce(root, args, "bug", (n) => releaseEntry(root, "bug", n), OPERATOR_FILE_KINDS.bug.role);
+                break;
+            }
             await fileAndAnnounce(root, args, "bug", (positionals) => fileBug(root, positionals.join(" "), usage), OPERATOR_FILE_KINDS.bug.role, bugWakeText, bugTitleOf, (text) => fileBugFromText(root, text, usage));
             break;
         }
         case "plan": {
-            const { OPERATOR_FILE_KINDS, cancelAndAnnounce, cancelPlan, editAndAnnounce, editPlan, editPlanFromText, filePlan, filePlanFromText, fileAndAnnounce, listAndAnnounce, planTitleOf, planWakeText } = await import("./backlog/backlog-write.js");
+            const { OPERATOR_FILE_KINDS, cancelPlan, moveEntryToTop, releaseEntry, editPlan, editPlanFromText, filePlan, filePlanFromText, planWakeText } = await import("./backlog/backlog-write.js");
+            const { cancelAndAnnounce, releaseAndAnnounce, topAndAnnounce, editAndAnnounce, fileAndAnnounce, listAndAnnounce, showAndAnnounce, planTitleOf } = await import("./backlog/backlog-cli.js");
             const usage = 'tumwater plan "<title>" [body...]';
+            if (args.includes("--show")) {
+                showAndAnnounce(root, args, "plan");
+                break;
+            }
             if (args.includes("--list")) {
                 listAndAnnounce(root, args, "plan", "PLANS.md", "Planned");
                 break;
@@ -238,12 +279,23 @@ async function main() {
                 await cancelAndAnnounce(root, args, "plan", (n) => cancelPlan(root, n));
                 break;
             }
+            if (args.includes("--top")) {
+                await topAndAnnounce(root, args, "plan", (n) => moveEntryToTop(root, "plan", n));
+                break;
+            }
+            if (args.includes("--release")) {
+                await releaseAndAnnounce(root, args, "plan", (n) => releaseEntry(root, "plan", n), OPERATOR_FILE_KINDS.plan.role);
+                break;
+            }
             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));
             break;
         }
         case "questions":
             await (await import("./cli/cli-query-commands.js")).cmdQuestions(root, args);
             break;
+        case "brief":
+            await (await import("./cli/brief-command.js")).cmdBrief(root, args);
+            break;
         case "role":
             await (await import("./cli/cli-query-commands.js")).cmdRole(root, args);
             break;
@@ -261,33 +313,62 @@ async function main() {
             await (await import("./inbox/prompt-commands.js")).cmdPrompt(root, args);
             break;
         case "reset-counters":
-        // Fall through: the six marker commands share one guard+dispatch shape — unknown-args
+        // Fall through: the seven marker commands share one guard+dispatch shape — unknown-args
         // rejection against the command's flag set, the ready-repo gate, then the
-        // operator-commands core — so runMarkerCommand holds it once instead of six copies
+        // operator-commands core — so runMarkerCommand holds it once instead of seven copies
         // drifting. The case labels here are exactly MarkerCommand's members, which is what
         // makes the cast below exhaustive.
         case "wake":
         case "abort":
         case "pause":
         case "resume":
-        case "reclaim": {
+        case "reclaim":
+        case "restart": {
             await (await import("./cli/cli-marker-commands.js")).runMarkerCommand(root, command, args);
             break;
         }
         case "retire": {
             // Not a marker command (it acts immediately, not via a request file), but it shares the
             // marker commands' gate shape: unknown-args rejection, then the ready-repo gate.
-            rejectUnknownArgs("retire", args, [ROLE_FLAG, FORCE_FLAG, JSON_FLAG]);
+            rejectUnknownArgs("retire", args, [ROLE_FLAG, FORCE_FLAG, DRY_RUN_FLAG, JSON_FLAG]);
             await requireReadyRepo(root);
             await (await import("./operator/operator-commands.js")).cmdRetire(root, args);
             break;
         }
+        case "revert": {
+            // Acts immediately on the primary checkout under the primary-worktree lock; the single
+            // positional (the commit to undo) is validated inside cmdRevert.
+            await requireReadyRepo(root);
+            await (await import("./operator/operator-commands.js")).cmdRevert(root, args);
+            break;
+        }
         case "stop": {
-            // No flags: stop is a bare signal to the recorded orchestrator pid, so any argument is
-            // a mistake and fails before a signal is ever sent.
-            rejectUnknownArgs("stop", args, []);
+            // Bare stop signals the recorded orchestrator pid; `--in`/`--cancel` schedule or drop a
+            // deferred stop. Anything else is a mistake and fails before a signal is ever sent.
+            rejectUnknownArgs("stop", args, [STOP_IN_FLAG, STOP_CANCEL_FLAG]);
             await requireReadyRepo(root);
-            await (await import("./operator/operator-commands.js")).cmdStop(root);
+            await (await import("./operator/operator-commands.js")).cmdStop(root, args);
+            break;
+        }
+        case "completion": {
+            // Works outside a repo: no requireReadyRepo.
+            if (args.length === 1 && args[0] === "--roles") {
+                for (const id of completionRoleIds(root))
+                    say(id);
+                break;
+            }
+            if (args.length === 1 && args[0] === "--config-keys") {
+                for (const key of completionConfigKeys(root))
+                    say(key);
+                break;
+            }
+            const shell = args[0];
+            if (args.length !== 1 || !SUPPORTED_SHELLS.includes(shell))
+                // A single near-miss shell word gets the same typoSuffix `logs --type`/`history --result`
+                // give, so `completion zs` reads "did you mean `zsh`?" while a far-off value (`tcsh`) and
+                // a wrong arity (none or several words, typed shown by gotSuffix) stay hint-free.
+                fail(`completion takes one shell: bash, zsh, or fish${gotSuffix(args.length > 1 ? args[1] : shell)}${args.length === 1 ? typoSuffix(shell ?? "", SUPPORTED_SHELLS) : ""}`);
+            say(completionScript(shell));
             break;
         }
         case "version":
@@ -301,7 +382,7 @@ async function main() {
             // raw stack trace, and a non-string version fails instead of printing "undefined".
             const { version, problem } = packageVersion(PACKAGE_JSON);
             if (problem !== undefined || version === undefined)
-                fail(problem ?? "package.json carries no version field (the running harness's install looks broken)");
+                fail(problem ?? "package.json carries no version field (the running tumwater install looks broken)");
             say(version);
             break;
         }

package/dist/src/collections.js

@@ -4,8 +4,8 @@
  * 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-data.ts's bucketLandingEvents, failure/time-spend.ts's rejected-by-loop pass) and
- * the fleet-hold poll's observations-by-provider grouping (fleet-polls.ts's pollFleetHold), so
+ * (history-data.ts's bucketMergeEvents, failure/time-spend.ts's rejected-by-loop 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) {
@@ -18,8 +18,8 @@ export function groupBy(items, key) {
 /** 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 fleet hold's provider+kind grouping
- * (fleet-hold.ts), the error-storm reducer's roles-by-key set (src/fleet/error-storm.ts), and
+ * 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
  * `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. */
@@ -33,9 +33,12 @@ export function getOrCreate(map, key, make) {
 }
 /** 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/fleet/failure-spread.ts), the diff multiset's line tally (landing/landing-diff.ts), the
- * section-title tally (backlog/backlog-structure.ts), and the once-summary outcome tally
- * (cli/cli-run.ts), so those sites cannot drift on how a missing key is seeded. */
+ * (src/team/failure-spread.ts), the diff multiset's line tally (merge/merge-diff.ts), the
+ * section-title tally (backlog/backlog-structure.ts), the once-summary outcome tally
+ * (cli/cli-run.ts), the logs' per-type tally (cli/log-commands.ts), the flaky-check tally
+ * (doctor/doctor-checks.ts), and the multi-runner base tally
+ * (orchestrator/orchestrator-scheduling.ts), so those sites cannot drift on how a missing key is
+ * seeded. */
 export function increment(map, key) {
     map.set(key, (map.get(key) ?? 0) + 1);
 }
@@ -44,7 +47,7 @@ export function increment(map, key) {
  * step (the seed matters because `noUncheckedIndexedAccess` reads every entry as possibly
  * undefined), shared by the failure digest's outcome tally per role (failure-data.ts), the
  * usage report's window role totals (report-render.ts), and its per-day fold's tick and cost
- * tallies (report-data.ts), so those sites cannot drift on how a missing key is seeded. The
+ * tallies (report-fold.ts), so those sites cannot drift on how a missing key is seeded. The
  * test duration reporter (test/test-durations-reporter.ts) keeps its own copy: it imports no
  * tumwater module by design, since node --test loads it into its own parent process.
  *
@@ -56,22 +59,69 @@ export function addTo(record, key, amount) {
     const current = Object.hasOwn(record, key) ? record[key] : 0;
     record[key] = (current ?? 0) + amount;
 }
+/** Set `key` to `value` in a bounded memo `cache`, moving an existing key to the LRU tail
+ * (delete + re-set, so a re-read at the cap does not evict itself) and, when the map would
+ * exceed `max` entries, dropping the oldest (first-inserted) one. The single home of the
+ * bounded-memo discipline — the `delete(key); set(key, …)` refresh and the
+ * `keys().next().value` oldest-eviction — shared by the report fold (report-fold.ts's
+ * reportFoldCache), the failure digest (failure-data.ts's failureDigestCache), and the
+ * baseline verdict cache (main-baseline.ts's baselineCache), so those sites cannot drift on
+ * how a hit is refreshed or an over-cap cache drained. After any call the map holds at most
+ * `max` entries. */
+export function memoSetLru(cache, key, value, max) {
+    if (cache.has(key))
+        cache.delete(key);
+    if (cache.size >= max) {
+        const oldest = cache.keys().next().value;
+        if (oldest !== undefined)
+            cache.delete(oldest);
+    }
+    cache.set(key, value);
+}
 /** One deterministic ranking rule: count descending, then key ascending, so equal counts always
  * order the same way. These two helpers are the single home of that rule; every surface that
- * ranks counters calls one of them rather than re-implementing the comparator —
+ * 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/fleet/failure-spread.ts's strongest-kind pick) and `rankByCount` serves
+ * 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/fleet/error-storm.ts's strongest-cause pick,
- * failure-data.ts's outcome table, and time-spend.ts's time-and-spend table). The one deliberate
- * exception is ui/gui/gui-client-report.ts's reportRoleOrder, which keeps its own copy by design:
- * it runs in the browser, where harness modules cannot be imported. Both helpers return a fresh
- * sorted array; the input is never mutated. */
+ * (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
+ * 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.ts's reportRoleOrder, which
+ * keeps its own copy by design: it runs in the browser, where harness modules cannot be imported.
+ * These two helpers return a fresh sorted array; their input is never mutated. */
 export function rankByCount(items, count, key) {
     return [...items].sort((a, b) => count(b) - count(a) || key(a).localeCompare(key(b)));
 }
+/** The lower median of a non-empty numeric list: the middle value, or the smaller of the
+ * middle two for an even count. Returns a fresh sorted copy; the input is never mutated.
+ * Shared by report-data.ts's per-day medians, doctor-checks.ts's and doctor-backlog.ts's
+ * 24 h phrase medians. (failure-data.ts's `median` is deliberately different: the mean of
+ * the middle two for an even count.) */
+export function lowerMedian(values) {
+    const sorted = [...values].sort((a, b) => a - b);
+    return sorted[Math.floor((sorted.length - 1) / 2)];
+}
+/** 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-run.ts, src/cli/log-commands.ts and src/history/history-data.ts, and by
+ * `sortByValueDesc` for its tiebreak. */
+export function compareCodeUnits(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** 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
+ * 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. */
+export function sortByValueDesc(entries) {
+    return entries.sort((a, b) => b[1] - a[1] || compareCodeUnits(a[0], b[0]));
+}
 /** rankByCount for `[key, count]` entry pairs (count first): src/report/report-render.ts's
- * rankedRoleMap and src/fleet/failure-spread.ts's strongest-kind pick. */
+ * rankedRoleMap and src/team/failure-spread.ts's strongest-kind pick. */
 export function rankCountEntries(entries) {
     return rankByCount(entries, (e) => e[1], (e) => e[0]);
 }

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

@@ -2,28 +2,27 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { defaultConfig } from "../config/config.js";
 import { Semaphore } from "./semaphore.js";
 /** One process-wide bound on concurrent runs of the declared check (config.maxConcurrentChecks):
- * every full suite the harness runs — runScopedBuildCheck's
- * gate/landing/batch scopes and main-baseline.ts's checkMainBaseline, which runs the suite directly
- * — takes a permit here first, so a burst of landings cannot stack suites on the host beside the
- * authors' own test runs (the suite has load-sensitive tests). Split out of build/build-check.ts
- * — which keeps the deterministic execution and classification (detect → spawn → classify)
- * — because permit accounting is scheduling policy, not check semantics: it changes when the
- * concurrency or fairness policy changes, not when the check's execution does. Separate from the
- * orchestrator's maxConcurrent semaphore: a role tick holds one of those while it waits here, but a
- * check permit is held only around the check process itself — never across a pi run, the merge
- * lock, or another check — so no permit holder waits on anything a waiter holds. Sized at each
- * acquire from the caller's live config (checkCap), so a tumwater.json edit applies to the next
- * check; Semaphore.setCapacity never preempts a running check on a shrink. */
+ * every full suite the harness runs — runScopedBuildCheck's gate/merge/batch scopes and
+ * main-baseline.ts's checkMainBaseline, which runs the suite directly — takes a permit here first,
+ * so a burst of merges cannot stack suites on the host beside the authors' own test runs (the suite
+ * has load-sensitive tests). Split out of build/build-check.ts — which keeps the deterministic
+ * execution and classification (detect → spawn → classify) — because permit accounting is
+ * scheduling policy, not check semantics: it changes when the concurrency or fairness policy
+ * changes, not when the check's execution does. Separate from the orchestrator's maxConcurrent
+ * semaphore: a role tick holds one of those while it waits here, but a check permit is held only
+ * around the check process itself — never across a pi run, the merge lock, or another check — so no
+ * permit holder waits on anything a waiter holds. Sized at each acquire from the caller's live
+ * config (checkCap), so a tumwater.json edit applies to the next check; Semaphore.setCapacity never
+ * preempts a running check on a shrink. */
 const checkPermits = new Semaphore(defaultConfig().maxConcurrentChecks);
 /** Set while the current async context holds a check permit: a nested withCheckPermit runs
  * inside the permit it already has instead of queueing for a second one — at a cap of 1 that
  * second wait could never be granted (its own holder is the one blocking it). No call path
- * nests today; this keeps a future one from deadlocking the fleet's checks. */
+ * nests today; this keeps a future one from deadlocking the team's checks. */
 const holdingPermit = new AsyncLocalStorage();
-/** Waiting-queue tiers (Semaphore.acquire): a merge-scope check runs inside the merge lock, so
- * it is granted the next free permit ahead of queued gate and baseline checks — every check it
- * waited behind would be lock-hold time for every other landing. A running check is never
- * preempted. */
+/** Waiting-queue tiers (Semaphore.acquire): a merge-scope check runs inside the merge lock, so it
+ * is granted the next free permit ahead of queued gate and baseline checks — every check it waited
+ * behind would be lock-hold time for every other merge. A running check is never preempted. */
 export const CHECK_TIER = { merge: 0, other: 1 };
 /** The live cap: config.maxConcurrentChecks when it is a positive integer (validateConfig
  * enforces that for tumwater.json), the default otherwise — a caller passing a partial config

package/dist/src/concurrency/lock.js

@@ -1,3 +1,4 @@
+// vocabulary: plain
 import fs from "node:fs";
 import path from "node:path";
 import { pidAlive } from "../process/process.js";
@@ -225,11 +226,11 @@ export function withStateLock(lock, fn, timeoutMs = 10_000) {
     ensureParentDir(lock);
     return withSyncLock(lock, fn, timeoutMs);
 }
-/** The async twin of withStateLock, for a critical section that must await (the landing's
- * working-tree fast-forward runs git). Same lock directory and protocol as withStateLock, so a
- * sync writer and an async one on the same path exclude each other; ensureParentDir runs first
- * for the same reason. The default timeout is withStateLock's, not withLock's longer merge-lock
- * budget: these sections are one file read-modify-write or one fast-forward. */
+/** The async twin of withStateLock, for a critical section that must await (the merge's
+ * working-tree fast-forward runs git). Same lock directory and protocol as withStateLock, so a sync
+ * writer and an async one on the same path exclude each other; ensureParentDir runs first for the
+ * same reason. The default timeout is withStateLock's, not withLock's longer merge-lock budget:
+ * these sections are one file read-modify-write or one fast-forward. */
 export async function withStateLockAsync(lock, fn, timeoutMs = 10_000) {
     ensureParentDir(lock);
     return withLock(lock, fn, timeoutMs);

package/dist/src/concurrency/provider-lease.js

@@ -0,0 +1,69 @@
+/** The AsyncLocalStorage store that lets a tick's lease follow its runs across providers
+ * (plans/provider-concurrency.md §5): a lease rides here for the length of a tick, a verify task,
+ * or a resolver run, and `LoopPi.runWithTransientRetry` re-keys it to the provider each run
+ * actually uses. The one choke point every run a loop makes (authoring, gate, merge and resolver)
+ * passes through, so a budget handback or a model-failure switch that moves a mid-tick run to
+ * another provider moves the lease with it instead of leaving it parked on the key it was admitted
+ * on. The check-permit.ts `holdingPermit` store is the pattern: nothing here is a separate permit,
+ * only the single lease the run path already holds.
+ *
+ * The store carries the `piDefault` (the caller's cached readPiDefaultModel result) beside the
+ * lease so `ensureProviderLease` can resolve a bare no-model pi seam's key exactly as the
+ * admission/review seam did — a run whose key were computed without it would re-key a default
+ * team's tick off pi's own provider. It also carries the semaphore and, optionally, wait
+ * hooks, so a re-key that has to park on a full target key reports its wait the way a parked
+ * resolver does (merge-verify.ts's providerWaitStage). */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { seamConcurrencyKey } from "../config/config-views.js";
+const providerLeaseStore = new AsyncLocalStorage();
+/** Run `run` with `lease` in the provider-lease store, so any run it makes re-keys that lease to
+ * the provider it actually uses (ensureProviderLease). `opts.piDefault` is the caller's cached pi
+ * default model, so a bare no-model seam resolves to the same key the admission or review seam
+ * used; `opts.hooks` (the verify: providerWaitStage) hears a re-key wait, if there is one. The same
+ * lease object is released by the caller after the store is unwrapped — a re-key mutates it in
+ * place, so release() frees whatever key the run path ended on. */
+export function withProviderLease(lease, semaphore, run, opts = {}) {
+    return providerLeaseStore.run({ lease, semaphore, piDefault: opts.piDefault, hooks: opts.hooks }, run);
+}
+/** Re-key the calling lease to the provider `cfg` runs on, if it is not there yet. No-op when
+ * the current async context carries no lease (a direct LoopPi unit test, `tumwater tick`) or
+ * when the run is already on the lease's key. When it does re-key and `hooks` are present and
+ * the target key is at its cap, the hooks hear `waiting` before the lease parks and `granted`
+ * once the key frees — a re-key never waits on the team total (it already holds a team
+ * permit), only on the target key's headroom. */
+export async function ensureProviderLease(cfg) {
+    const ctx = providerLeaseStore.getStore();
+    if (!ctx)
+        return;
+    const key = seamConcurrencyKey(cfg, ctx.piDefault);
+    if (ctx.lease.key === key)
+        return;
+    // The leased currently holds `old` (or nothing); the target key's in-use does not include it,
+    // so the key being at its cap is exactly whether rekey() will park.
+    const parks = ctx.hooks !== undefined && keyAtCap(ctx, key);
+    if (parks)
+        ctx.hooks.waiting();
+    await ctx.lease.rekey(key);
+    if (parks)
+        ctx.hooks.granted();
+}
+/** Whether `key` is at its configured cap right now (an absent or uncapped key is not) — the
+ * same test semaphore.drive uses to withhold a re-key grant, decided from the live snapshot so
+ * a re-key wait can be announced before the lease parks (providerWaitStage). */
+function keyAtCap(ctx, key) {
+    if (key === undefined)
+        return false;
+    const entry = ctx.semaphore.snapshot().byKey[key];
+    return entry?.limit !== undefined && entry.inUse >= entry.limit;
+}
+/** The pool-slot wait rule (plans/provider-concurrency.md §5 "No deadlock"): a lease never holds a
+ * provider key while it waits for a worktree pool slot. Called by leaseSlot just before it parks on
+ * a busy pool; it re-keys the calling lease to no key (which never waits), so a tick or verify
+ * waiting for a slot does not hold — and cannot deadlock — a provider slot whose in-use a re-key
+ * waiter is waiting to drain. No-op without a lease in context. */
+export async function dropProviderLeaseKey() {
+    const ctx = providerLeaseStore.getStore();
+    if (!ctx)
+        return;
+    await ctx.lease.rekey(undefined);
+}