tumwater 0.4.2 → 0.4.4

package/dist/src/concurrency/lock.js

@@ -7,7 +7,7 @@ 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;
+const STALE_MS = 10 * 60_000;
 /** A creator publishes its lock dir with the holder's pid already inside (atomic rename), so a
  * visible lock always carries a readable pid. This grace remains for a pid-less dir an older
  * build or an interrupted hand operation left behind: past it, the dir is an orphan and safe
@@ -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);
+    }
+}

package/dist/src/concurrency/semaphore.js

@@ -1,39 +1,19 @@
 /** In-process counting semaphore bounding concurrent work (the orchestrator uses it to
  * cap simultaneous pi runs). The cross-PROCESS mutex lives in lock.ts; this one only
- * coordinates within a single harness process.
- *
- * Since 2026-10-15 it also bounds a model provider (a "key") independently, so a full
- * 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);
-}
+ * coordinates within a single harness process. A run is admitted by the one team total
+ * (`maxConcurrent`) alone — there is no per-provider cap any more (the cap, its surfaces
+ * and its keyed machinery were subtracted in parts 5b/6 and 5i/6); a lease is a team
+ * permit that can pause and resume so an idle wait (a failed review's in-place retry)
+ * hands the slot back and re-takes it before the next attempt. */
 export class Semaphore {
     capacity;
-    /** A parked WAITING (admission) waiter: its scheduling tier, optional provider key, and the
-     * resolver that hands it the permit. Keyless waiters (the legacy path) carry no key and are
-     * never held by a key cap. */
+    /** A parked WAITING (admission) waiter: its scheduling tier and the resolver that hands
+     * it the permit. */
     waiters = [];
-    /** A parked re-key waiter: it already holds a team permit, so it waits only for its key's
-     * headroom, ahead of every admission waiter (which would otherwise queue a team permit uselessly
-     * behind another provider's runs). `granted` flips when drive() hands the waiter the target key's
-     * slot, so the lease's release can tell a delivered grant (give it back) from a still-parked one
-     * (cancel it) when the two interleave. */
-    rekeyWaiters = [];
     /** Permits currently held, tracked separately from capacity (rather than as an "available"
      * count): setCapacity can shrink below the current in-use, and a free-permit count cannot
      * represent that state — it would over-admit new work after a shrink. */
     inUse = 0;
-    /** The per-key permits currently held: a lease or forced lease charges its key here, and a
-     * key at its cap withholds further grants on it. Grows and shrinks only through release and
-     * rekey — never preempted. */
-    keyInUse = new Map();
-    /** 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 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. */
@@ -45,13 +25,12 @@ export class Semaphore {
     get limit() {
         return this.capacity;
     }
-    /** How many acquirers are parked for a permit right now, admission and re-key waiters both.
-     * With no keys there are never re-key waiters, so this is exactly today's count. */
+    /** How many acquirers are parked for a permit right now. */
     get waiting() {
-        return this.waiters.length + this.rekeyWaiters.length;
+        return this.waiters.length;
     }
     /** Take a free permit without parking: true when one was granted (the same fast path
-     * acquire takes), false when acquire would have to wait. Unkeyed, as before. */
+     * acquire takes), false when acquire would have to wait. */
     tryAcquire() {
         if (this.inUse >= this.capacity)
             return false;
@@ -62,7 +41,7 @@ export class Semaphore {
      * requests only: on arrival a waiter inserts ahead of every parked waiter with a strictly
      * greater tier (the orchestrator passes roleTier so work roles beat maintenance across
      * polls), keeping stable FIFO within a tier. In-flight holders are never preempted — they
-     * run to completion and their release is what hands out the permit. Unkeyed, as before. */
+     * run to completion and their release is what hands out the permit. */
     async acquire(tier) {
         if (this.inUse < this.capacity - this.reserveFor(tier)) {
             this.inUse += 1;
@@ -72,25 +51,16 @@ export class Semaphore {
             this.enqueue({ tier, resolve });
         });
     }
-    /** Admit by both the team total and an optional provider key at once, waiting until both
-     * hold, and return a lease handle. `tier` orders the wait exactly as acquire does; `key`
-     * bounds the permit by its provider cap: granted when `inUse < capacity − reserveFor(tier)`
-     * and the key is under its cap (an absent or uncapped key always passes). FIFO holds within
-     * a key, and a full key never delays a waiter on another. */
-    async acquireLease(tier, key) {
-        let currentKey = key;
+    /** Admit by the team total alone and return a lease handle. `tier` orders the wait exactly
+     * as acquire does. FIFO holds within a tier. */
+    async acquireLease(tier) {
         // True once release() has run: a released lease owns no slot and must not undo one again —
-        // a second release (or a parked rekey's late grant) must be a no-op, never a negative
-        // count. The orchestrator releases each lease exactly once, but the rekey cancel path
-        // relies on this guard so a cancelled lease never re-decrements its target key.
+        // a second release must be a no-op, never a negative count. The orchestrator releases each
+        // lease exactly once, but a cancelled parked resume relies on this guard so a cancelled
+        // lease never re-decrements what it took.
         let closed = false;
-        // The lease's parked re-key, while it waits on a full target key. At that point the lease
-        // holds NO key slot (the old one was returned at the rekey's start), so release() must
-        // 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.
+        // True while pause() has handed the team permit back: release() then owes nothing, and
+        // resume() re-admits at this lease's tier in queue order.
         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.
@@ -109,102 +79,46 @@ export class Semaphore {
                     w.resolve();
                     return;
                 }
-                // drive granted it this microtask: its permit and key slot are taken, so give them back.
+                // drive granted it this microtask: its permit is taken, so give it 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
-                // back. The lease holds no slot either way, so the team permit is the only thing to free.
-                const w = parkedRekey;
-                const idx = this.rekeyWaiters.indexOf(w);
-                if (idx >= 0)
-                    this.rekeyWaiters.splice(idx, 1);
-                if (w.granted) {
-                    this.bumpKeyInUse(w.key, -1);
-                }
-                w.resolve();
-                parkedRekey = null;
-            }
-            else if (currentKey !== undefined) {
-                this.bumpKeyInUse(currentKey, -1);
-            }
+                return; // pause() already gave the permit back
             this.inUse -= 1;
             this.drive();
         };
-        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);
-            }
-            currentKey = to;
-            lease.key = to;
-            this.drive();
-            if (to !== undefined && this.keyAtCap(to)) {
-                // The new key is full: wait only for its headroom, ahead of every admission waiter.
-                const w = { key: to, resolve: () => { }, granted: false };
-                parkedRekey = w;
-                this.rekeyWaiters.push(w);
-                await new Promise((resolve) => {
-                    w.resolve = resolve;
-                });
-                parkedRekey = null;
-                if (w.granted)
-                    this.drive();
-                return;
-            }
-            if (to !== undefined)
-                this.bumpKeyInUse(to, 1);
-            this.drive();
-        };
         const pause = () => {
-            if (closed || paused || parkedRekey !== null)
+            if (closed || paused)
                 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)) {
+            if (this.canLeaseAtOnce(tier)) {
                 this.inUse += 1;
-                if (currentKey !== undefined)
-                    this.bumpKeyInUse(currentKey, 1);
                 paused = false;
                 return;
             }
             await new Promise((resolve) => {
-                const waiter = { tier, key: currentKey, resolve };
+                const waiter = { tier, resolve };
                 parkedResume = waiter;
                 this.enqueue(waiter);
             });
             parkedResume = null;
-            // drive granted it (the permit and key slot are taken), unless release() cancelled it.
+            // drive granted it (the permit is 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))) {
+        const lease = { release, pause, resume };
+        if (this.inUse < this.capacity - this.reserveFor(tier)) {
             this.inUse += 1;
-            if (key !== undefined)
-                this.bumpKeyInUse(key, 1);
             return lease;
         }
         await new Promise((resolve) => {
-            this.enqueue({ tier, key, resolve });
+            this.enqueue({ tier, resolve });
         });
         return lease;
     }
@@ -221,97 +135,29 @@ export class Semaphore {
         }
         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
-     * caller can decide whether to show a "waiting for a slot" state before awaiting a lease
-     * that would actually park (merge-drain.ts's resolver wrapper). */
-    canLeaseAtOnce(tier, key) {
-        return this.inUse < this.capacity - this.reserveFor(tier) && (key === undefined || !this.keyAtCap(key));
-    }
-    /** The director's bypass: take a key's slot at once, never waiting, and never counting toward
-     * the team cap. It DOES count toward the key's in-use, so a forced lease can overshoot a
-     * full key by one holder; no grant on that key happens until a release drains it back under
-     * the cap. Its re-key also never waits. */
-    forceLease(key) {
-        let currentKey = key;
-        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 && !paused) {
-                this.bumpKeyInUse(currentKey, -1);
-            }
-            this.drive();
-        };
-        const rekey = async (to) => {
-            if (to === currentKey)
-                return;
-            if (currentKey !== undefined && !paused) {
-                this.bumpKeyInUse(currentKey, -1);
-            }
-            currentKey = to;
-            lease.key = to;
-            if (to !== undefined && !paused)
-                this.bumpKeyInUse(to, 1);
-            this.drive();
-        };
-        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
-     * pass. The one home of the permit hand-off: release, setCapacity, setReserve and setKeyCaps
-     * all drive it, and growth loops it to fill new headroom. It never admits past the team cap
-     * or a key cap. Re-key waiters run first (they already hold a team permit, so they wait only
-     * on their key). Admission waiters are scanned in queue (tier, then FIFO) order: a waiter
-     * whose key is full is skipped and keeps its place, so a later waiter on a free key is never
-     * stuck behind it — but the reserve stops the scan at the first tier ≥ 1 waiter it withholds
-     * from, since the tier-ascending queue means everything behind is withheld too. */
+    /** Synchronously report whether acquireLease(tier) would return at once — the team total
+     * has headroom right now and the tier's reserve is satisfied. Mirrors the exact fast-path
+     * condition acquireLease's first branch uses, so a caller can decide whether to show a
+     * "waiting for a slot" state before awaiting a lease that would actually park
+     * (merge-drain.ts's resolver wrapper). */
+    canLeaseAtOnce(tier) {
+        return this.inUse < this.capacity - this.reserveFor(tier);
+    }
+    /** Hand every parked waiter a permit it can take in one pass. The one home of the permit
+     * hand-off: release, setCapacity, setReserve and a pause/resume all drive it, and growth
+     * loops it to fill new headroom. It never admits past the team cap. Admission waiters are
+     * scanned in queue (tier, then FIFO) order; the reserve stops the scan at the first tier ≥ 1
+     * waiter it withholds from, since the tier-ascending queue means everything behind is
+     * withheld too. */
     drive() {
         for (;;) {
-            // Re-key waiters first: no team check — they already hold a team permit.
             let granted = false;
-            for (let i = 0; i < this.rekeyWaiters.length; i++) {
-                const w = this.rekeyWaiters[i];
-                if (this.keyAtCap(w.key))
-                    continue;
-                w.granted = true;
-                this.rekeyWaiters.splice(i, 1);
-                this.bumpKeyInUse(w.key, 1);
-                w.resolve();
-                granted = true;
-                break;
-            }
-            if (granted)
-                continue;
             for (let i = 0; i < this.waiters.length; i++) {
                 const w = this.waiters[i];
                 if (this.inUse >= this.capacity - this.reserveFor(w.tier))
                     break; // reserve/full stops the scan
-                if (w.key !== undefined && this.keyAtCap(w.key))
-                    continue; // skip a full key, keep its place
                 this.waiters.splice(i, 1);
                 this.inUse += 1;
-                if (w.key !== undefined)
-                    this.bumpKeyInUse(w.key, 1);
                 w.resolve();
                 granted = true;
                 break;
@@ -320,23 +166,11 @@ export class Semaphore {
                 break;
         }
     }
-    /** The permits withheld from `tier`: `reserve` for tier ≥ 1 (maintenance), 0 for every tier that
-     * ships work or merges a change (work, VERIFY_TIER, MERGE_TIER). */
+    /** The permits withheld from `tier`: `reserve` for tier ≥ 1 (maintenance), 0 for every tier
+     * that ships work or merges a change (work, VERIFY_TIER, MERGE_TIER). */
     reserveFor(tier) {
         return tier >= 1 ? this.reserve : 0;
     }
-    /** True when `key` is at its cap — a configured cap the in-use already meets or exceeds. An
-     * uncapped key (no cap set) is never "full". */
-    keyAtCap(key) {
-        const cap = this.keyCaps.get(key);
-        return cap !== undefined && (this.keyInUse.get(key) ?? 0) >= cap;
-    }
-    /** Add `delta` to `key`'s held permits, initializing an absent key at zero first — the
-     * single home of the get-or-init bump that release, rekey, force and drive all repeated
-     * (an absent key implicitly holds zero, so the first bump must not read `undefined`). */
-    bumpKeyInUse(key, delta) {
-        this.keyInUse.set(key, (this.keyInUse.get(key) ?? 0) + delta);
-    }
     /** Release a held permit. The finishing work gives back its permit first, and a queued waiter
      * takes it over only if there is headroom (drive): after a shrink, inUse can sit at or above
      * the cap for a while (the in-flight work admitted before it), and no new grant may proceed
@@ -360,46 +194,8 @@ export class Semaphore {
         this.reserve = Math.max(0, n);
         this.drive();
     }
-    /** Live-resize the per-key caps (a mid-run `maxConcurrentPerProvider` edit). Growing admits
-     * parked waiters for that key up to the new headroom; shrinking never preempts an in-flight
-     * 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(enforcedKeyCaps(caps));
-        this.drive();
-    }
-    /** The pool's live state for observability (plans/provider-concurrency.md §8): the team
-     * in-use/cap, the reserve, and each referenced key's in-use, cap (undefined when uncapped)
-     * and waiting count. */
+    /** The pool's live state for observability: the team in-use/cap and the reserve. */
     snapshot() {
-        const byKey = {};
-        const addKey = (key) => {
-            if (key === undefined)
-                return;
-            if (byKey[key] === undefined) {
-                const cap = this.keyCaps.get(key);
-                const entry = {
-                    inUse: this.keyInUse.get(key) ?? 0,
-                    waiting: 0,
-                };
-                if (cap !== undefined)
-                    entry.limit = cap;
-                byKey[key] = entry;
-            }
-        };
-        for (const k of this.keyCaps.keys())
-            addKey(k);
-        for (const k of this.keyInUse.keys())
-            addKey(k);
-        for (const w of this.waiters) {
-            addKey(w.key);
-            if (w.key !== undefined)
-                byKey[w.key].waiting += 1;
-        }
-        for (const w of this.rekeyWaiters) {
-            addKey(w.key);
-            byKey[w.key].waiting += 1;
-        }
-        return { inUse: this.inUse, limit: this.capacity, reserve: this.reserve, byKey };
+        return { inUse: this.inUse, limit: this.capacity, reserve: this.reserve };
     }
 }

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

@@ -8,10 +8,10 @@
  * 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 four run-concurrency knobs (maxConcurrent,
- * maxConcurrentPerProvider, maxConcurrentChecks, worktreeSlots) joined the set because
+ * that first consumed it. The run-concurrency knobs (maxConcurrent,
+ * 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
+ * (checkWorktreePool, 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
@@ -23,13 +23,10 @@ export const EDITABLE_CONFIG_KEYS = [
     "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.
+    // raise (checkCheckContention) — 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