tumwater 0.1.2 → 0.2.0

package/dist/src/concurrency/semaphore.js

@@ -1,17 +1,37 @@
 /** 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. */
+ * 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. */
 export class Semaphore {
     capacity;
-    /** A parked waiter: its scheduling tier plus the resolver that hands it the permit. */
+    /** 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. */
     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 loop that has work to take can claim
      * one without waiting for a maintenance tick to release (plans/parallel-work-instances.md
-     * "Priority headroom", part 7/7). Tiers ≤ 0 (work, LANDING_TIER, MERGE_TIER) ignore it. */
+     * "Priority headroom", part 7/7). Tiers ≤ 0 (work, VERIFY_TIER, MERGE_TIER) ignore it. */
     reserve = 0;
     constructor(capacity) {
         this.capacity = capacity;
@@ -20,12 +40,13 @@ export class Semaphore {
     get limit() {
         return this.capacity;
     }
-    /** How many acquirers are parked for a permit right now. */
+    /** 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. */
     get waiting() {
-        return this.waiters.length;
+        return this.waiters.length + this.rekeyWaiters.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. */
+     * acquire takes), false when acquire would have to wait. Unkeyed, as before. */
     tryAcquire() {
         if (this.inUse >= this.capacity)
             return false;
@@ -36,7 +57,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. */
+     * run to completion and their release is what hands out the permit. Unkeyed, as before. */
     async acquire(tier) {
         if (this.inUse < this.capacity - this.reserveFor(tier)) {
             this.inUse += 1;
@@ -54,54 +75,255 @@ export class Semaphore {
             this.waiters.splice(i, 0, waiter);
         });
     }
-    /** Hand the next parked waiter a permit when in-use is under the cap, returning whether one
-     * was woken. The one home of the permit hand-off: release() calls it once, setCapacity()
-     * loops it to fill new headroom. It never admits past the cap, so a shrink wakes nothing
-     * until releases drain in-use under it. */
-    grantNextWaiter() {
-        // Peek before admitting: a tier ≥ 1 waiter at the head is the highest-priority one (the
-        // queue is tier-ascending), so when the reserve withholds a permit from it, it withholds
-        // one from every waiter behind it too.
-        const next = this.waiters[0];
-        if (!next)
-            return false;
-        if (this.inUse >= this.capacity - this.reserveFor(next.tier))
-            return false;
-        this.waiters.shift();
-        this.inUse += 1;
-        next.resolve();
-        return true;
+    /** 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;
+        // 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.
+        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;
+        const release = () => {
+            if (closed)
+                return;
+            closed = true;
+            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);
+            }
+            this.inUse -= 1;
+            this.drive();
+        };
+        const rekey = async (to) => {
+            if (to === currentKey || closed)
+                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 lease = { key: currentKey, release, rekey };
+        if (this.inUse < this.capacity - this.reserveFor(tier) && (key === undefined || !this.keyAtCap(key))) {
+            this.inUse += 1;
+            if (key !== undefined)
+                this.bumpKeyInUse(key, 1);
+            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);
+        });
+        return lease;
+    }
+    /** 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 permits withheld from `tier`: `reserve` for tier ≥ 1 (maintenance), 0 for every tier
-     * that ships work or lands a change (work, LANDING_TIER, MERGE_TIER). */
+    /** 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);
+        }
+        const release = () => {
+            if (currentKey !== undefined) {
+                this.bumpKeyInUse(currentKey, -1);
+            }
+            this.drive();
+        };
+        const rekey = async (to) => {
+            if (to === currentKey)
+                return;
+            if (currentKey !== undefined) {
+                this.bumpKeyInUse(currentKey, -1);
+            }
+            currentKey = to;
+            lease.key = to;
+            if (to !== undefined)
+                this.bumpKeyInUse(to, 1);
+            this.drive();
+        };
+        const lease = { key: currentKey, release, rekey };
+        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. */
+    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;
+            }
+            if (!granted)
+                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). */
     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 (grantNextWaiter): 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 until releases bring in-use under the cap. In the normal case this is exactly the
-     * classic hand-off — one release wakes one waiter, net in-use unchanged. */
+     * 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
+     * until releases bring in-use under the cap. In the normal case this is exactly the classic
+     * hand-off — one release wakes one waiter, net in-use unchanged. */
     release() {
         this.inUse -= 1;
-        this.grantNextWaiter();
+        this.drive();
     }
     /** Live-resize the cap (a mid-run tumwater.json edit). Growing admits queued waiters up to
      * the new headroom — one permit per woken waiter. Shrinking never preempts in-flight work:
      * it only caps future grants until releases bring in-use under the new cap. */
     setCapacity(n) {
         this.capacity = n;
-        while (this.grantNextWaiter()) {
-            // One permit per woken waiter, up to the new headroom.
-        }
+        this.drive();
     }
     /** Live-resize the permits withheld from tier ≥ 1 acquirers. Lowering it re-runs the hand-off
      * so a parked maintenance waiter can take a permit the reserve had held; raising it never
      * preempts an in-flight holder — it only withholds future grants. */
     setReserve(n) {
         this.reserve = Math.max(0, n);
-        while (this.grantNextWaiter()) {
-            // One permit per woken waiter, up to the headroom the new reserve leaves.
+        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(Object.entries(caps).filter(([, v]) => Number.isInteger(v) && v > 0));
+        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. */
+    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 };
     }
 }

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

@@ -0,0 +1,106 @@
+import { isJsonObject } from "../files/json-object.js";
+import { LEGACY_ROLE_IDS } from "../roles/legacy-role-ids.js";
+/** The config maps keyed by role id, whose old-id keys move to the new id. */
+const ROLE_KEYED_MAPS = ["roles", "maxDailyCostUsdPerRole", "quietHoursPerRole"];
+/** Move each retired role id keyed in `map` to its new id. Returns `map` itself when none
+ * moved. */
+function renameRoleIds(map, name, legacy, renamed, problems) {
+    let out = map;
+    for (const [old, next] of Object.entries(legacy)) {
+        if (!Object.hasOwn(map, old))
+            continue;
+        if (Object.hasOwn(map, next)) {
+            problems.push(`sets both ${name}.${old} and ${name}.${next} — keep ${name}.${next} (${old} is its old id)`);
+            continue;
+        }
+        if (out === map)
+            out = { ...map };
+        out[next] = out[old];
+        delete out[old];
+        renamed.push(`${name}.${old} → ${name}.${next}`);
+    }
+    return out;
+}
+/** The one table of renamed config keys: tumwater.json may spell either name, load reads both,
+ * and every writer writes only `to`. */
+const CONFIG_KEY_RENAMES = [
+    { from: "landBatchMax", to: "mergeBatchMax", scope: "top" },
+    { from: "maintenancePerWorkLanding", to: "maintenancePerWorkMerge", scope: "top" },
+    { from: "tickTimeoutSeconds", to: "runTimeoutSeconds", scope: "top" },
+    { 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. */
+function renameIn(obj, scope, prefix, renamed, problems) {
+    let out = obj;
+    for (const r of CONFIG_KEY_RENAMES) {
+        if (r.scope !== scope || !Object.hasOwn(obj, r.from))
+            continue;
+        if (Object.hasOwn(obj, r.to)) {
+            problems.push(`${prefix}${r.from} and ${prefix}${r.to} are both set — keep ${prefix}${r.to} (${r.from} is its old name)`);
+            continue;
+        }
+        if (out === obj)
+            out = { ...obj };
+        out[r.to] = out[r.from];
+        delete out[r.from];
+        renamed.push(`${prefix}${r.from} → ${prefix}${r.to}`);
+    }
+    return out;
+}
+/** Rewrite a parsed config (or director request) so it carries only current key names. Pure:
+ * the input is never mutated, and a non-object passes through unchanged. `renamed` lists each
+ * `<from> → <to>` applied; `problems` names each pair the file set both ways. */
+export function normalizeConfigKeys(raw, legacy = LEGACY_ROLE_IDS) {
+    const renamed = [];
+    const problems = [];
+    if (!isJsonObject(raw))
+        return { raw, renamed, problems };
+    let out = renameIn(raw, "top", "", renamed, problems);
+    for (const name of ROLE_KEYED_MAPS) {
+        const map = out[name];
+        if (!isJsonObject(map))
+            continue;
+        const next = renameRoleIds(map, name, legacy, renamed, problems);
+        if (next !== map)
+            out = { ...out, [name]: next };
+    }
+    if (isJsonObject(out.roles)) {
+        let roles = out.roles;
+        for (const [id, entry] of Object.entries(out.roles)) {
+            if (!isJsonObject(entry))
+                continue;
+            const next = renameIn(entry, "role", `roles.${id}.`, renamed, problems);
+            if (next !== entry) {
+                if (roles === out.roles)
+                    roles = { ...out.roles };
+                roles[id] = next;
+            }
+        }
+        if (roles !== out.roles)
+            out = { ...out, roles };
+    }
+    return { raw: out, renamed, problems };
+}
+/** Map a key a person typed to its current spelling: a top-level old name, a dotted key whose
+ * first segment is an old top-level name, or `roles.<id>.<old field>`. Anything else passes
+ * through unchanged. */
+export function canonicalConfigKey(key, legacy = LEGACY_ROLE_IDS) {
+    const parts = key.split(".");
+    const first = parts[0] ?? "";
+    const top = CONFIG_KEY_RENAMES.find((r) => r.scope === "top" && r.from === first);
+    if (top)
+        return [top.to, ...parts.slice(1)].join(".");
+    if (parts.length >= 2 && ROLE_KEYED_MAPS.includes(first) && Object.hasOwn(legacy, parts[1])) {
+        return canonicalConfigKey([first, legacy[parts[1]], ...parts.slice(2)].join("."), legacy);
+    }
+    if (parts.length === 3 && first === "roles") {
+        const role = CONFIG_KEY_RENAMES.find((r) => r.scope === "role" && r.from === parts[2]);
+        if (role)
+            return `roles.${parts[1]}.${role.to}`;
+    }
+    return key;
+}

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

@@ -1,6 +1,6 @@
 /**
  * The config keys the dashboard's Settings view may show and edit: the top-level settings
- * an operator changes often from the browser. Everything else — customLoops, the per-role
+ * an operator changes often from the browser. Everything else — customRoles, the per-role
  * maps — stays CLI/director territory (the plan's curation decision, 2026-10-02). One
  * constant so handleConfig (GET /api/config) and handleConfigSet (POST /api/config-set)
  * cannot drift apart on what is editable.
@@ -21,6 +21,6 @@ export const EDITABLE_CONFIG_KEYS = [
     "quietHours",
     "notify",
     // The per-backend section (plans/agent-backends.md, part 4a/7): the whole `agents` object is
-    // edited here as JSON. The CLI's dotted `agents.<id>.bin`/`.args` merge one field at a time.
-    "agents",
+    // edited here as JSON. The CLI's dotted `backends.<id>.bin`/`.args` merge one field at a time.
+    "backends",
 ];