tumwater 0.2.0 → 0.3.0

package/dist/src/collections.js

@@ -4,7 +4,7 @@
  * 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 bucketMergeEvents, failure/time-spend.ts's rejected-by-loop pass) and
+ * (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. */
@@ -35,8 +35,8 @@ export function getOrCreate(map, key, make) {
  * `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
  * 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
+ * (cli/cli-start.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
  * (orchestrator/orchestrator-scheduling.ts), so those sites cannot drift on how a missing key is
  * seeded. */
 export function increment(map, key) {
@@ -46,13 +46,13 @@ export function increment(map, key) {
  * sibling of `increment`, the single home of the `record[key] = (record[key] ?? 0) + n`
  * 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
+ * usage report's window role totals (report-render.ts), and its per-day fold's run and cost
  * 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.
  *
  * The seed reads an OWN property (Object.hasOwn), not a bare `record[key] ?? 0`: the
- * custom-loop name charset admits "constructor", an Object.prototype key, whose inherited
+ * custom-role name charset admits "constructor", an Object.prototype key, whose inherited
  * function would otherwise be the seed — storing `function Object() …5` and turning every
  * later `roleSum`/report total into string concatenation (BUGS.md 2026-10-10). */
 export function addTo(record, key, amount) {
@@ -78,6 +78,20 @@ export function memoSetLru(cache, key, value, max) {
     }
     cache.set(key, value);
 }
+/** Trim `arr` in place so it holds at most `max` elements, keeping only the newest (last) `max`
+ * and dropping the whole overflow from the front in one splice — the single home of the
+ * "keep the newest capped buffer" discipline that src/ui/transcript.ts's feedEntries and
+ * src/history/history.ts's `logs --follow` buffer both hand-rolled before, so those sites
+ * cannot drift on how an over-cap buffer is drained. Batch appends may overflow by more than
+ * one at a time, so the whole excess is dropped rather than a single element; an `arr` already
+ * at or under `max` is untouched. Mutates `arr` in place and returns nothing. (Deliberately
+ * unlike the per-element ring drains of src/scheduling/backoff.ts and src/orchestrator/
+ * orchestrator-launch.ts, which shift one entry at a time as they push — each is a different
+ * shape and keeps its own copy.) */
+export function trimToLast(arr, max) {
+    if (arr.length > max)
+        arr.splice(0, arr.length - max);
+}
 /** 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 by count calls one of them rather than re-implementing the comparator —
@@ -88,15 +102,16 @@ export function memoSetLru(cache, key, value, max) {
  * 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.
+ * 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
+ * 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
+ * Shared by report-data.ts's per-day medians, doctor-project-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) {
@@ -105,7 +120,7 @@ export function lowerMedian(values) {
 }
 /** 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
+ * src/cli/cli-start-summary.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;
@@ -121,7 +136,8 @@ 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/team/failure-spread.ts's strongest-kind pick. */
+ * rankedRoleMap, src/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-permit.js

@@ -9,7 +9,7 @@ import { Semaphore } from "./semaphore.js";
  * 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
+ * semaphore: a role run 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
@@ -20,6 +20,9 @@ const checkPermits = new Semaphore(defaultConfig().maxConcurrentChecks);
  * 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 team's checks. */
 const holdingPermit = new AsyncLocalStorage();
+/** Labels of the checks holding a permit now, keyed by a per-hold token; insertion order is
+ * acquisition order. A check_wait event names them (PermitWaitHooks.waited). */
+const permitHolders = new Map();
 /** 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. */
@@ -32,23 +35,37 @@ function checkCap(config) {
     const n = config?.maxConcurrentChecks;
     return typeof n === "number" && Number.isInteger(n) && n >= 1 ? n : defaultConfig().maxConcurrentChecks;
 }
+/** The check pool's live state for observers (the orchestrator's poll publishes it): permits held,
+ * the cap, and checks queued for one. `limit` is the cap set by the most recent withCheckPermit
+ * call, or the default before any check has run. */
+export function checkPermitSnapshot() {
+    return { inUse: checkPermits.snapshot().inUse, limit: checkPermits.limit, waiting: checkPermits.waiting };
+}
 /** Run `run` under one process-wide check permit (see checkPermits), resizing the cap from the
  * live config first and releasing in a finally — a check that fails, times out, or throws still
  * gives its permit back. Reentrant (holdingPermit): called again from inside `run`, it runs the
- * inner work under the permit already held. `hooks` hear about a wait, if there is one. */
-export async function withCheckPermit(config, tier, run, hooks) {
+ * inner work under the permit already held. `hooks` hear about a wait, if there is one; `label`
+ * names this check to the waiters it holds up ("a check" when omitted). */
+export async function withCheckPermit(config, tier, run, hooks, label) {
     if (holdingPermit.getStore())
         return run();
     checkPermits.setCapacity(checkCap(config));
     if (!checkPermits.tryAcquire()) {
+        const waitStarted = Date.now();
+        // Snapshot at park time; not revised if holders change mid-wait.
+        const parked = { heldBy: [...permitHolders.values()], limit: checkPermits.limit };
         hooks?.waiting();
         await checkPermits.acquire(tier);
         hooks?.granted();
+        hooks?.waited?.(Date.now() - waitStarted, parked);
     }
+    const token = Symbol();
+    permitHolders.set(token, label ?? "a check");
     try {
         return await holdingPermit.run(true, run);
     }
     finally {
+        permitHolders.delete(token);
         checkPermits.release();
     }
 }

package/dist/src/concurrency/lock.js

@@ -1,10 +1,10 @@
-// vocabulary: plain
 import fs from "node:fs";
 import path from "node:path";
 import { pidAlive } from "../process/process.js";
 import { errorMessage, parsePositiveInt } from "../text/text.js";
-import { ensureParentDir, removeTree } from "../files/files.js";
+import { dirEntryNames, ensureParentDir, removeTree } from "../files/files.js";
 import { errCode } from "../errno.js";
+import { primaryWorktreeLockPath } from "../paths.js";
 /** How old a lock dir must be before it is stale on age alone — regardless of whether its
  * recorded pid still looks alive, so a reused pid cannot latch a dead holder as live. */
 const STALE_MS = 10 * 60 * 1000;
@@ -70,7 +70,7 @@ export function classifyLock(dir) {
     return pidAlive(pid) ? "live" : "stale";
 }
 /** Name the lock's holder for the timeout message: the pid its pid file records, or a note
- * that none was readable. The message surfaces as a tick's lastError, and the pid is the one
+ * that none was readable. The message surfaces as a run's lastError, and the pid is the one
  * handle an operator needs to tell "waiting on a slow holder" from "an orphan dir nobody can
  * break" — without it every timeout reads the same and the holder has to be found by hand. */
 function lockHolderNote(dir) {
@@ -117,7 +117,7 @@ function acquireStep(dir, timeoutMs, waitedMs) {
 }
 /** The tail every wait-step in acquireStep shares once a lock is held (or was lost in the
  * publish race): break it if stale, then hand back "retry" for another pass — or throw the one
- * timeout error once the wait budget is spent. That error surfaces as a tick's lastError, and
+ * timeout error once the wait budget is spent. That error surfaces as a run's lastError, and
  * naming the holder is what distinguishes a slow holder from a wedged one (and says which
  * process to look at). Single-homed so the held path and the lost-race path cannot drift. */
 function retryOrTimeout(dir, timeoutMs, waitedMs) {
@@ -156,14 +156,8 @@ function publishLockDir(dir) {
 function sweepStaleTemps(dir) {
     const parent = path.dirname(dir);
     const prefix = `${path.basename(dir)}.acquiring-`;
-    let entries;
-    try {
-        entries = fs.readdirSync(parent);
-    }
-    catch {
-        return; // No parent to sweep; the acquire's own mkdir reports the real cause.
-    }
-    for (const name of entries) {
+    // No parent to sweep reads empty; the acquire's own mkdir reports the real cause.
+    for (const name of dirEntryNames(parent)) {
         if (!name.startsWith(prefix))
             continue;
         const candidate = path.join(parent, name);
@@ -176,7 +170,7 @@ function sweepStaleTemps(dir) {
         }
     }
 }
-/** Directory-and-pid mutex shared by all loops (and processes) of one project: the holder
+/** Directory-and-pid mutex shared by all roles (and processes) of one project: the holder
  * publishes a dir with its pid in it by atomic rename. */
 export async function withLock(dir, fn, timeoutMs = 120_000) {
     const startedAt = Date.now();
@@ -235,3 +229,13 @@ export async function withStateLockAsync(lock, fn, timeoutMs = 10_000) {
     ensureParentDir(lock);
     return withLock(lock, fn, timeoutMs);
 }
+/** withStateLock on the primary-worktree lock: the one lock every read-modify-write of a tracked
+ * file in the primary checkout (a backlog file, the brief) takes, which a merge's working-tree
+ * fast-forward takes too. */
+export function withPrimaryWorktreeLock(root, fn) {
+    return withStateLock(primaryWorktreeLockPath(root), fn);
+}
+/** The async twin of withPrimaryWorktreeLock, for a section that awaits git. */
+export function withPrimaryWorktreeLockAsync(root, fn) {
+    return withStateLockAsync(primaryWorktreeLockPath(root), fn);
+}

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

@@ -1,8 +1,8 @@
-/** 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
+/** The AsyncLocalStorage store that lets a run's lease follow its runs across providers
+ * (plans/provider-concurrency.md §5): a lease rides here for the length of a run, a verify task,
+ * or a resolver run, and `RunnerPi.runWithTransientRetry` re-keys it to the provider each run
+ * actually uses. The one choke point every run a role makes (authoring, gate, merge and resolver)
+ * passes through, so a budget handback or a model-failure switch that moves a run in flight 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.
@@ -10,7 +10,7 @@
  * 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
+ * team's run 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";
@@ -26,7 +26,7 @@ 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
+ * the current async context carries no lease (a direct RunnerPi unit test, `tumwater history`) 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
@@ -58,7 +58,7 @@ function keyAtCap(ctx, key) {
 }
 /** 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
+ * a busy pool; it re-keys the calling lease to no key (which never waits), so a run 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() {
@@ -67,3 +67,39 @@ export async function dropProviderLeaseKey() {
         return;
     await ctx.lease.rekey(undefined);
 }
+/** Run `wait`, an idle stretch inside the calling lease's work, with the lease's team permit and
+ * key slot handed back (SemaphoreLease.pause), so a parked run can use them meanwhile, then take
+ * them 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 idleWithoutProviderLease(wait, signal) {
+    const ctx = providerLeaseStore.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);
+    }
+}

package/dist/src/concurrency/semaphore.js

@@ -6,6 +6,11 @@
  * provider never blocks a waiter on another (plans/provider-concurrency.md §3). The keyless
  * entry points — acquire/tryAcquire/release — are unchanged; only acquireLease, forceLease
  * and setKeyCaps touch the keyed path. */
+/** The entries of a `maxConcurrentPerProvider` map the semaphore enforces: positive integers
+ * only, so a non-positive or non-integer cap is dropped rather than read as a limit. */
+export function enforcedKeyCaps(caps) {
+    return Object.entries(caps ?? {}).filter(([, v]) => Number.isInteger(v) && v > 0);
+}
 export class Semaphore {
     capacity;
     /** A parked WAITING (admission) waiter: its scheduling tier, optional provider key, and the
@@ -29,8 +34,8 @@ export class Semaphore {
     /** The live per-key caps, from `maxConcurrentPerProvider` (plans/provider-concurrency.md
      * §1). An absent key is uncapped — bounded by `capacity` alone. */
     keyCaps = new Map();
-    /** Permits withheld from tier ≥ 1 acquirers so a work loop that has work to take can claim
-     * one without waiting for a maintenance tick to release (plans/parallel-work-instances.md
+    /** Permits withheld from tier ≥ 1 acquirers so a work role that has work to take can claim
+     * one without waiting for a maintenance run to release (plans/parallel-work-instances.md
      * "Priority headroom", part 7/7). Tiers ≤ 0 (work, VERIFY_TIER, MERGE_TIER) ignore it. */
     reserve = 0;
     constructor(capacity) {
@@ -64,15 +69,7 @@ export class Semaphore {
             return;
         }
         await new Promise((resolve) => {
-            const waiter = { tier, resolve };
-            let i = this.waiters.length;
-            while (i > 0) {
-                const prev = this.waiters[i - 1];
-                if (!prev || prev.tier <= tier)
-                    break; // insert before strictly-greater tiers only
-                i -= 1;
-            }
-            this.waiters.splice(i, 0, waiter);
+            this.enqueue({ tier, resolve });
         });
     }
     /** Admit by both the team total and an optional provider key at once, waiting until both
@@ -92,10 +89,31 @@ export class Semaphore {
         // CANCEL the pending grant rather than undo a slot this lease never took. Null when no
         // rekey is parked.
         let parkedRekey = null;
+        // True while pause() has handed the team permit and the key's slot back: release() then owes
+        // nothing, and resume() re-admits at this lease's tier on its current key.
+        let paused = false;
+        // resume()'s admission waiter while it is queued. release() cancels it if drive has not
+        // granted it yet, and gives the grant back if it has.
+        let parkedResume = null;
         const release = () => {
             if (closed)
                 return;
             closed = true;
+            if (parkedResume !== null) {
+                const w = parkedResume;
+                parkedResume = null;
+                const idx = this.waiters.indexOf(w);
+                if (idx >= 0) {
+                    // Still queued: it took nothing, so cancel it and owe nothing.
+                    this.waiters.splice(idx, 1);
+                    w.resolve();
+                    return;
+                }
+                // drive granted it this microtask: its permit and key slot are taken, so give them back.
+                paused = false;
+            }
+            if (paused)
+                return; // pause() already gave the permit and the key's slot back
             if (parkedRekey !== null) {
                 // A re-key is parked waiting on its new key. Cancel it: pull it off the queue (so drive
                 // can't grant it) and, if the grant already arrived this microtask, give the new key's slot
@@ -119,6 +137,12 @@ export class Semaphore {
         const rekey = async (to) => {
             if (to === currentKey || closed)
                 return;
+            if (paused) {
+                // Nothing is held while paused: the move only changes the key resume() admits on.
+                currentKey = to;
+                lease.key = to;
+                return;
+            }
             // Give the old key back first, waking that key's waiters.
             if (currentKey !== undefined) {
                 this.bumpKeyInUse(currentKey, -1);
@@ -143,7 +167,36 @@ export class Semaphore {
                 this.bumpKeyInUse(to, 1);
             this.drive();
         };
-        const lease = { key: currentKey, release, rekey };
+        const pause = () => {
+            if (closed || paused || parkedRekey !== null)
+                return;
+            paused = true;
+            if (currentKey !== undefined)
+                this.bumpKeyInUse(currentKey, -1);
+            this.inUse -= 1;
+            this.drive();
+        };
+        const resume = async () => {
+            if (closed || !paused || parkedResume !== null)
+                return;
+            if (this.canLeaseAtOnce(tier, currentKey)) {
+                this.inUse += 1;
+                if (currentKey !== undefined)
+                    this.bumpKeyInUse(currentKey, 1);
+                paused = false;
+                return;
+            }
+            await new Promise((resolve) => {
+                const waiter = { tier, key: currentKey, resolve };
+                parkedResume = waiter;
+                this.enqueue(waiter);
+            });
+            parkedResume = null;
+            // drive granted it (the permit and key slot are taken), unless release() cancelled it.
+            if (!closed)
+                paused = false;
+        };
+        const lease = { key: currentKey, release, rekey, pause, resume };
         if (this.inUse < this.capacity - this.reserveFor(tier) && (key === undefined || !this.keyAtCap(key))) {
             this.inUse += 1;
             if (key !== undefined)
@@ -151,18 +204,23 @@ export class Semaphore {
             return lease;
         }
         await new Promise((resolve) => {
-            const waiter = { tier, key, resolve };
-            let i = this.waiters.length;
-            while (i > 0) {
-                const prev = this.waiters[i - 1];
-                if (!prev || prev.tier <= tier)
-                    break;
-                i -= 1;
-            }
-            this.waiters.splice(i, 0, waiter);
+            this.enqueue({ tier, key, resolve });
         });
         return lease;
     }
+    /** Queue an admission waiter behind every waiter of its tier or a lower one, so it inserts
+     * before strictly-greater tiers only (tier order, FIFO within a tier) — the one home of the
+     * queue's ordering, shared by acquire, acquireLease and a paused lease's resume. */
+    enqueue(waiter) {
+        let i = this.waiters.length;
+        while (i > 0) {
+            const prev = this.waiters[i - 1];
+            if (!prev || prev.tier <= waiter.tier)
+                break;
+            i -= 1;
+        }
+        this.waiters.splice(i, 0, waiter);
+    }
     /** Synchronously report whether acquireLease(tier, key) would return at once — both the
      * team total and the key (when set) have headroom right now, and the tier's reserve is
      * satisfied. Mirrors the exact fast-path condition acquireLease's first branch uses, so a
@@ -180,8 +238,10 @@ export class Semaphore {
         if (currentKey !== undefined) {
             this.bumpKeyInUse(currentKey, 1);
         }
+        // True while pause() has given the key's slot back (a forced lease holds no team permit).
+        let paused = false;
         const release = () => {
-            if (currentKey !== undefined) {
+            if (currentKey !== undefined && !paused) {
                 this.bumpKeyInUse(currentKey, -1);
             }
             this.drive();
@@ -189,16 +249,32 @@ export class Semaphore {
         const rekey = async (to) => {
             if (to === currentKey)
                 return;
-            if (currentKey !== undefined) {
+            if (currentKey !== undefined && !paused) {
                 this.bumpKeyInUse(currentKey, -1);
             }
             currentKey = to;
             lease.key = to;
-            if (to !== undefined)
+            if (to !== undefined && !paused)
                 this.bumpKeyInUse(to, 1);
             this.drive();
         };
-        const lease = { key: currentKey, release, rekey };
+        const pause = () => {
+            if (paused)
+                return;
+            paused = true;
+            if (currentKey !== undefined)
+                this.bumpKeyInUse(currentKey, -1);
+            this.drive();
+        };
+        // Like the forced lease itself, taking the slot back never waits.
+        const resume = async () => {
+            if (!paused)
+                return;
+            paused = false;
+            if (currentKey !== undefined)
+                this.bumpKeyInUse(currentKey, 1);
+        };
+        const lease = { key: currentKey, release, rekey, pause, resume };
         return lease;
     }
     /** Hand every parked waiter a permit it can take — both team and key headroom — in one
@@ -289,7 +365,7 @@ export class Semaphore {
      * holder — it only withholds future grants on that key until releases drain it under the new
      * cap, the same contract as setCapacity. Non-positive and non-integer entries are dropped. */
     setKeyCaps(caps) {
-        this.keyCaps = new Map(Object.entries(caps).filter(([, v]) => Number.isInteger(v) && v > 0));
+        this.keyCaps = new Map(enforcedKeyCaps(caps));
         this.drive();
     }
     /** The pool's live state for observability (plans/provider-concurrency.md §8): the team

package/dist/src/config/config-aliases.js

@@ -30,7 +30,6 @@ const CONFIG_KEY_RENAMES = [
     { from: "minTickIntervalSeconds", to: "minRunIntervalSeconds", scope: "top" },
     { from: "minTickIntervalSeconds", to: "minRunIntervalSeconds", scope: "role" },
     { from: "customLoops", to: "customRoles", scope: "top" },
-    { from: "agent", to: "backend", scope: "top" },
     { from: "agents", to: "backends", scope: "top" },
 ];
 /** Move every old key of one object to its new name. Returns a copy when anything moved. */

package/dist/src/config/config-editable-keys.js

@@ -8,7 +8,11 @@
  * This is config vocabulary, not HTTP vocabulary — it names which tumwater.json keys are
  * browser-editable — so it lives beside the other config-key lists (config-schema.ts's
  * TOP_LEVEL_KEYS, config-write.ts's per-key validators) rather than in the endpoint module
- * that first consumed it. The browser side mirrors the set for its labels
+ * that first consumed it. The four run-concurrency knobs (maxConcurrent,
+ * maxConcurrentPerProvider, maxConcurrentChecks, worktreeSlots) joined the set because
+ * tumwater doctor's own contention checks name them for the operator to raise
+ * (checkWorktreePool, checkProviderContention, checkCheckContention); the per-role maps and
+ * customRoles still stay CLI/director territory. The browser side mirrors the set for its labels
  * (ui/gui/gui-client-settings.ts's SETTINGS_KEYS), a manual copy; the GET /api/config test
  * pins the served key set to this list, and the settings test pins the browser copy's keys
  * and order to it.
@@ -18,6 +22,14 @@ export const EDITABLE_CONFIG_KEYS = [
     "model",
     "fallback",
     "maxDailyCostUsd",
+    // The run-concurrency knobs tumwater doctor's contention checks name for the operator to
+    // raise (checkWorktreePool, checkProviderContention) — grouped so the Settings card that
+    // shows the advice can apply it.
+    "maxConcurrent",
+    "maxConcurrentPerProvider",
+    "maxConcurrentChecks",
+    "worktreeSlots",
+    "claudeWindowReserve",
     "quietHours",
     "notify",
     // The per-backend section (plans/agent-backends.md, part 4a/7): the whole `agents` object is