@ashlr/hub 3.2.6 → 3.3.0

package/dist/core/fleet/quota.js

@@ -6,25 +6,51 @@
  * ledger records each dispatch and answers "how many in the last window?" and
  * "are we still under the configured cap?".
  *
- * Persistence discipline mirrors daemon/state.ts EXACTLY:
- *  - Atomic writes (tmp file + POSIX rename).
- *  - NEVER throws — load returns a fresh empty ledger on missing/corrupt file;
- *    record swallows any persistence error.
+ * Observation compatibility remains deliberately tolerant: load returns a fresh
+ * empty ledger on missing/corrupt state and recordUse remains best-effort. The
+ * authority-bearing reservation API is stricter:
+ *  - One local-store lock serializes read/check/append publication.
+ *  - Configured limits fail closed on ambiguous or unavailable persistence.
+ *  - Reservation identities are hashed and idempotent across retries.
+ *  - The replacement file and containing directory are fsynced before success.
  *  - mkdir -p the parent dir.
- *  - Bounded history (last ~2000 events).
+ *  - Bounded authority history (last 2000 events per known backend, max 30d).
  *  - Homedir re-resolved at call time so tests can relocate HOME.
  *
  * No new runtime deps; node builtins only. evalQuota mirrors evalBudget's
  * three-level (ok/warn/over) semantics with a null-cap-disabled path.
  */
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
+import { closeSync, constants as fsConstants, existsSync, fchmodSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readSync, readFileSync, renameSync, unlinkSync, writeFileSync, writeSync, } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { acquireLocalStoreLockWithOutcome, releaseLocalStoreLock, } from './local-store-lock.js';
+import { fsyncDirectory } from '../util/durability.js';
+import { assurePrivateStoragePath } from '../util/private-storage.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 /** Maximum number of dispatch events retained in quota.json. */
 const MAX_EVENTS = 2000;
+const MAX_LEDGER_BYTES = 1024 * 1024;
+const MAX_AUTHORITY_LEDGER_BYTES = 8 * 1024 * 1024;
+const MAX_DISPATCH_ID_BYTES = 4_096;
+const MAX_BATCH_RESERVATIONS = 64;
+const RESERVATION_DOMAIN = 'ashlr:fleet-quota-reservation:v1';
+const SHA256_RE = /^[a-f0-9]{64}$/;
+const O_NOFOLLOW = typeof fsConstants.O_NOFOLLOW === 'number' ? fsConstants.O_NOFOLLOW : 0;
+const ENGINE_IDS = new Set([
+    'builtin', 'local-coder', 'ashlrcode', 'aw', 'claude', 'codex', 'hermes',
+    'kimi', 'nim', 'opencode', 'grok',
+]);
+const MAX_AUTHORITY_EVENTS = MAX_EVENTS * ENGINE_IDS.size;
+let fleetQuotaTestHooks;
+/** Test-only fault injection; production callers must never configure this. */
+export function setFleetQuotaTestHooksForTests(hooks) {
+    if (process.env.NODE_ENV !== 'test')
+        throw new Error('fleet quota test hooks are test-only');
+    fleetQuotaTestHooks = hooks;
+}
 // ---------------------------------------------------------------------------
 // windowToMs — EXTENDS rollup's vocabulary with sub-day windows (local copy)
 // ---------------------------------------------------------------------------
@@ -39,12 +65,26 @@ export function windowToMs(window) {
         case '5m': return 5 * 60_000;
         case '15m': return 15 * 60_000;
         case '1h': return 3_600_000;
+        case '5h': return 5 * 3_600_000;
         case '1d': return 86_400_000;
         case '7d': return 7 * 86_400_000;
         case '30d': return 30 * 86_400_000;
         default: return 3_600_000;
     }
 }
+function reservationWindowMs(window) {
+    switch (window) {
+        case '1m': return 60_000;
+        case '5m': return 5 * 60_000;
+        case '15m': return 15 * 60_000;
+        case '1h': return 3_600_000;
+        case '5h': return 5 * 3_600_000;
+        case '1d': return 86_400_000;
+        case '7d': return 7 * 86_400_000;
+        case '30d': return 30 * 86_400_000;
+        default: return null;
+    }
+}
 // ---------------------------------------------------------------------------
 // Path helpers (re-resolved at call time so tests can relocate HOME)
 // ---------------------------------------------------------------------------
@@ -55,12 +95,368 @@ function fleetDir() {
 export function fleetQuotaPath() {
     return join(fleetDir(), 'quota.json');
 }
+/**
+ * Private authority ledger. It is deliberately separate from quota.json:
+ * quota.json remains backwards-compatible, best-effort operator telemetry,
+ * while this file is the fail-closed idempotency/capacity boundary.
+ */
+export function fleetQuotaReservationPath() {
+    return join(fleetDir(), 'quota-reservations.json');
+}
+/** Lock path used by the authority-bearing quota reservation transaction. */
+export function fleetQuotaReservationLockPath() {
+    return join(fleetDir(), '.quota-reservation.lock');
+}
 // ---------------------------------------------------------------------------
 // Fresh default
 // ---------------------------------------------------------------------------
 function freshQuota() {
     return { events: [] };
 }
+function ownedByCurrentUser(stat) {
+    return typeof process.getuid !== 'function' || stat.uid === BigInt(process.getuid());
+}
+function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function safeQuotaDirectory(stat) {
+    return stat.isDirectory() && !stat.isSymbolicLink() && ownedByCurrentUser(stat) &&
+        (process.platform === 'win32' || (stat.mode & 511n) === 448n);
+}
+function safeQuotaFile(stat) {
+    return stat.isFile() && !stat.isSymbolicLink() && stat.nlink === 1n &&
+        ownedByCurrentUser(stat) &&
+        (process.platform === 'win32' || (stat.mode & 511n) === 384n);
+}
+// Pre-reservation releases wrote best-effort telemetry with the caller's
+// normal umask (commonly 0755/0644). Accept that owned, non-writable-by-others
+// shape only for a read-only first-use migration; new authority state remains
+// exact-private 0700/0600.
+function safeLegacyQuotaDirectory(stat) {
+    return stat.isDirectory() && !stat.isSymbolicLink() && ownedByCurrentUser(stat) &&
+        (process.platform === 'win32' || (stat.mode & 18n) === 0n);
+}
+function safeLegacyQuotaFile(stat) {
+    return stat.isFile() && !stat.isSymbolicLink() && stat.nlink === 1n &&
+        ownedByCurrentUser(stat) &&
+        (process.platform === 'win32' || (stat.mode & 18n) === 0n);
+}
+function pinQuotaDirectory() {
+    try {
+        const path = fleetDir();
+        const stat = lstatSync(path, { bigint: true });
+        return safeQuotaDirectory(stat) ? { path, dev: stat.dev, ino: stat.ino } : null;
+    }
+    catch {
+        return null;
+    }
+}
+function stableQuotaDirectory(authority) {
+    try {
+        const stat = lstatSync(authority.path, { bigint: true });
+        return safeQuotaDirectory(stat) && sameIdentity(authority, stat);
+    }
+    catch {
+        return false;
+    }
+}
+function pinLegacyQuotaDirectory() {
+    try {
+        const path = fleetDir();
+        const stat = lstatSync(path, { bigint: true });
+        return safeLegacyQuotaDirectory(stat) ? { path, dev: stat.dev, ino: stat.ino } : null;
+    }
+    catch {
+        return null;
+    }
+}
+function stableLegacyQuotaDirectory(authority) {
+    try {
+        const stat = lstatSync(authority.path, { bigint: true });
+        return safeLegacyQuotaDirectory(stat) && sameIdentity(authority, stat);
+    }
+    catch {
+        return false;
+    }
+}
+function prospectiveQuotaDirectoryAvailable() {
+    try {
+        const dir = fleetDir();
+        if (existsSync(dir)) {
+            const stat = lstatSync(dir, { bigint: true });
+            return stat.isDirectory() && !stat.isSymbolicLink() && ownedByCurrentUser(stat);
+        }
+        const parent = join(homedir(), '.ashlr');
+        if (!existsSync(parent))
+            return true;
+        const stat = lstatSync(parent, { bigint: true });
+        return stat.isDirectory() && !stat.isSymbolicLink() && ownedByCurrentUser(stat);
+    }
+    catch {
+        return false;
+    }
+}
+function strictQuotaEvent(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    const row = value;
+    const keys = Object.keys(row).sort().join(',');
+    if (keys !== 'backend,ts' && keys !== 'backend,reservationIdHash,ts')
+        return null;
+    const backend = row['backend'];
+    const ts = row['ts'];
+    const reservationIdHash = row['reservationIdHash'];
+    if (typeof backend !== 'string' || !ENGINE_IDS.has(backend) ||
+        typeof ts !== 'string' || !Number.isFinite(Date.parse(ts)) ||
+        new Date(Date.parse(ts)).toISOString() !== ts ||
+        (reservationIdHash !== undefined &&
+            (typeof reservationIdHash !== 'string' || !SHA256_RE.test(reservationIdHash))))
+        return null;
+    return {
+        backend: backend,
+        ts,
+        ...(typeof reservationIdHash === 'string' ? { reservationIdHash } : {}),
+    };
+}
+function parseStrictQuota(bytes, maxEvents = MAX_EVENTS, maxBytes = MAX_LEDGER_BYTES) {
+    if (bytes.length > maxBytes)
+        return null;
+    try {
+        const parsed = JSON.parse(bytes.toString('utf8'));
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return null;
+        const row = parsed;
+        if (Object.keys(row).join(',') !== 'events' || !Array.isArray(row['events']) ||
+            row['events'].length > maxEvents)
+            return null;
+        const events = [];
+        for (const value of row['events']) {
+            const event = strictQuotaEvent(value);
+            if (!event)
+                return null;
+            events.push(event);
+        }
+        return { events };
+    }
+    catch {
+        return null;
+    }
+}
+function readBoundQuotaFile(authority) {
+    if (!stableQuotaDirectory(authority))
+        return null;
+    const path = fleetQuotaReservationPath();
+    let fd;
+    try {
+        fd = openSync(path, fsConstants.O_RDONLY | O_NOFOLLOW);
+        const opened = fstatSync(fd, { bigint: true });
+        if (!safeQuotaFile(opened) || opened.size > BigInt(MAX_AUTHORITY_LEDGER_BYTES) ||
+            !assurePrivateStoragePath(path, 'file', 'inspect-existing', { anchorPath: homedir() }).ok)
+            return null;
+        const named = lstatSync(path, { bigint: true });
+        if (!safeQuotaFile(named) || !sameIdentity(opened, named))
+            return null;
+        const bytes = Buffer.alloc(Number(opened.size));
+        let offset = 0;
+        while (offset < bytes.length) {
+            const count = readSync(fd, bytes, offset, bytes.length - offset, offset);
+            if (count <= 0)
+                return null;
+            offset += count;
+        }
+        const openedAfter = fstatSync(fd, { bigint: true });
+        const namedAfter = lstatSync(path, { bigint: true });
+        if (!safeQuotaFile(openedAfter) || !safeQuotaFile(namedAfter) ||
+            !sameIdentity(opened, openedAfter) || !sameIdentity(openedAfter, namedAfter) ||
+            openedAfter.size !== opened.size || openedAfter.mtimeNs !== opened.mtimeNs ||
+            openedAfter.ctimeNs !== opened.ctimeNs || !stableQuotaDirectory(authority))
+            return null;
+        return {
+            found: true,
+            bytes,
+            dev: openedAfter.dev,
+            ino: openedAfter.ino,
+            size: openedAfter.size,
+            mtimeNs: openedAfter.mtimeNs,
+            ctimeNs: openedAfter.ctimeNs,
+        };
+    }
+    catch (error) {
+        return fd === undefined && error.code === 'ENOENT' &&
+            stableQuotaDirectory(authority)
+            ? { found: false }
+            : null;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch { /* best effort */ }
+        }
+    }
+}
+function readBoundLegacyQuotaFile(authority) {
+    if (!stableLegacyQuotaDirectory(authority))
+        return null;
+    const path = fleetQuotaPath();
+    let fd;
+    try {
+        fd = openSync(path, fsConstants.O_RDONLY | O_NOFOLLOW);
+        const opened = fstatSync(fd, { bigint: true });
+        if (!safeLegacyQuotaFile(opened) || opened.size > BigInt(MAX_LEDGER_BYTES) ||
+            !assurePrivateStoragePath(path, 'file', 'inspect-owned', { anchorPath: homedir() }).ok)
+            return null;
+        const named = lstatSync(path, { bigint: true });
+        if (!safeLegacyQuotaFile(named) || !sameIdentity(opened, named))
+            return null;
+        const bytes = Buffer.alloc(Number(opened.size));
+        let offset = 0;
+        while (offset < bytes.length) {
+            const count = readSync(fd, bytes, offset, bytes.length - offset, offset);
+            if (count <= 0)
+                return null;
+            offset += count;
+        }
+        const openedAfter = fstatSync(fd, { bigint: true });
+        const namedAfter = lstatSync(path, { bigint: true });
+        if (!safeLegacyQuotaFile(openedAfter) || !safeLegacyQuotaFile(namedAfter) ||
+            !sameIdentity(opened, openedAfter) || !sameIdentity(openedAfter, namedAfter) ||
+            openedAfter.size !== opened.size || openedAfter.mtimeNs !== opened.mtimeNs ||
+            openedAfter.ctimeNs !== opened.ctimeNs || !stableLegacyQuotaDirectory(authority))
+            return null;
+        return {
+            found: true,
+            bytes,
+            dev: openedAfter.dev,
+            ino: openedAfter.ino,
+            size: openedAfter.size,
+            mtimeNs: openedAfter.mtimeNs,
+            ctimeNs: openedAfter.ctimeNs,
+        };
+    }
+    catch (error) {
+        return fd === undefined && error.code === 'ENOENT' &&
+            stableLegacyQuotaDirectory(authority)
+            ? { found: false }
+            : null;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch { /* best effort */ }
+        }
+    }
+}
+function loadStrictQuota(authority) {
+    const destination = readBoundQuotaFile(authority);
+    if (destination === null)
+        return null;
+    if (!destination.found) {
+        // Upgrade compatibility: seed the first authority transaction from the
+        // existing attempt ledger so active-window usage cannot be forgotten.
+        const legacy = readBoundLegacyQuotaFile(authority);
+        if (legacy === null)
+            return null;
+        if (!legacy.found)
+            return { ledger: freshQuota(), destination };
+        const ledger = parseStrictQuota(legacy.bytes);
+        return ledger ? { ledger, destination } : null;
+    }
+    const ledger = parseStrictQuota(destination.bytes, MAX_AUTHORITY_EVENTS, MAX_AUTHORITY_LEDGER_BYTES);
+    return ledger ? { ledger, destination } : null;
+}
+function loadQuotaForAuthorityInspection() {
+    if (existsSync(fleetQuotaReservationPath())) {
+        const authority = pinQuotaDirectory();
+        return authority ? loadStrictQuota(authority)?.ledger ?? null : null;
+    }
+    if (!existsSync(fleetDir()))
+        return prospectiveQuotaDirectoryAvailable() ? freshQuota() : null;
+    const authority = pinLegacyQuotaDirectory();
+    if (!authority)
+        return null;
+    const legacy = readBoundLegacyQuotaFile(authority);
+    if (legacy === null)
+        return null;
+    if (!legacy.found)
+        return freshQuota();
+    return parseStrictQuota(legacy.bytes);
+}
+function sameDestination(left, right) {
+    if (right === null || left.found !== right.found)
+        return false;
+    if (!left.found || !right.found)
+        return true;
+    return left.dev === right.dev && left.ino === right.ino && left.size === right.size &&
+        left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs &&
+        left.bytes.equals(right.bytes);
+}
+function saveQuotaReservation(ledger, authority, expected) {
+    const bytes = Buffer.from(`${JSON.stringify(ledger, null, 2)}\n`, 'utf8');
+    if (ledger.events.length > MAX_AUTHORITY_EVENTS ||
+        bytes.length > MAX_AUTHORITY_LEDGER_BYTES)
+        return false;
+    const tmp = join(authority.path, `.quota-${process.pid}-${randomUUID()}.tmp`);
+    let fd;
+    let tmpIdentity;
+    let published = false;
+    try {
+        if (!stableQuotaDirectory(authority))
+            return false;
+        fd = openSync(tmp, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | O_NOFOLLOW, 0o600);
+        tmpIdentity = fstatSync(fd, { bigint: true });
+        if (!safeQuotaFile(tmpIdentity) || tmpIdentity.size !== 0n ||
+            !assurePrivateStoragePath(tmp, 'file', 'secure-created', { anchorPath: homedir() }).ok)
+            return false;
+        let offset = 0;
+        while (offset < bytes.length) {
+            const count = writeSync(fd, bytes, offset, bytes.length - offset, offset);
+            if (count <= 0)
+                return false;
+            offset += count;
+        }
+        fchmodSync(fd, 0o600);
+        fsyncSync(fd);
+        const flushed = fstatSync(fd, { bigint: true });
+        const named = lstatSync(tmp, { bigint: true });
+        if (!safeQuotaFile(flushed) || !safeQuotaFile(named) ||
+            !sameIdentity(tmpIdentity, flushed) || !sameIdentity(flushed, named) ||
+            flushed.size !== BigInt(bytes.length) || !stableQuotaDirectory(authority) ||
+            !sameDestination(expected, readBoundQuotaFile(authority)))
+            return false;
+        closeSync(fd);
+        fd = undefined;
+        renameSync(tmp, fleetQuotaReservationPath());
+        published = true;
+        fsyncDirectory(authority.path, { expectedIdentity: authority });
+        const installed = readBoundQuotaFile(authority);
+        return installed !== null && installed.found && sameIdentity(tmpIdentity, installed) &&
+            installed.size === BigInt(bytes.length) && installed.bytes.equals(bytes) &&
+            stableQuotaDirectory(authority);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch { /* best effort */ }
+        }
+        if (!published && tmpIdentity && stableQuotaDirectory(authority)) {
+            try {
+                const named = lstatSync(tmp, { bigint: true });
+                if (safeQuotaFile(named) && sameIdentity(named, tmpIdentity))
+                    unlinkSync(tmp);
+            }
+            catch { /* best effort exact-temp cleanup */ }
+        }
+    }
+}
 // ---------------------------------------------------------------------------
 // Load
 // ---------------------------------------------------------------------------
@@ -94,46 +490,294 @@ export function loadFleetQuota() {
     }
 }
 // ---------------------------------------------------------------------------
-// Save (atomic) — internal
+// Record a dispatch (compatibility/operator telemetry only)
 // ---------------------------------------------------------------------------
 /**
- * Atomically write the ledger via tmp-file + rename (POSIX-atomic).
- * Creates ~/.ashlr/fleet recursively. Bounds events. Never throws.
+ * Append an actual dispatch-attempt event for `backend` (ts = now) and
+ * persist. Never throws. This is intentionally not launch authority; the
+ * strict reservation ledger above is separate so legacy 0644 telemetry files
+ * cannot block or overwrite authority state.
  */
-function saveFleetQuota(q) {
+export function recordUse(backend) {
+    let acquired;
     try {
+        if (!ENGINE_IDS.has(backend))
+            return;
         const dir = fleetDir();
-        if (!existsSync(dir)) {
+        if (!existsSync(dir))
             mkdirSync(dir, { recursive: true });
+        acquired = acquireLocalStoreLockWithOutcome(fleetQuotaReservationLockPath(), 250, {
+            anchorPath: homedir(),
+            exactPrivateStorage: true,
+        });
+        if (acquired.state !== 'acquired')
+            return;
+        const ledger = loadFleetQuota();
+        ledger.events.push({ backend, ts: new Date().toISOString() });
+        const bounded = { events: ledger.events.slice(-MAX_EVENTS) };
+        const destination = fleetQuotaPath();
+        const temporary = `${destination}.tmp`;
+        writeFileSync(temporary, `${JSON.stringify(bounded, null, 2)}\n`, 'utf8');
+        renameSync(temporary, destination);
+    }
+    catch {
+        // Never throws.
+    }
+    finally {
+        if (acquired?.state === 'acquired') {
+            try {
+                releaseLocalStoreLock(acquired.lock);
+            }
+            catch { /* telemetry only */ }
         }
-        const bounded = {
-            events: q.events.slice(-MAX_EVENTS),
-        };
-        const dest = fleetQuotaPath();
-        const tmp = dest + '.tmp';
-        writeFileSync(tmp, JSON.stringify(bounded, null, 2) + '\n', 'utf8');
-        renameSync(tmp, dest);
+    }
+}
+function reservationIdHash(dispatchId) {
+    return createHash('sha256')
+        .update(JSON.stringify([RESERVATION_DOMAIN, dispatchId]))
+        .digest('hex');
+}
+function validReservationIdentity(backend, dispatchId) {
+    return ENGINE_IDS.has(backend) && typeof dispatchId === 'string' && dispatchId.length > 0 &&
+        Buffer.byteLength(dispatchId, 'utf8') <= MAX_DISPATCH_ID_BYTES;
+}
+function configuredReservationLimit(cfg, backend) {
+    const configured = cfg?.foundry?.limits?.[backend];
+    if (!configured)
+        return null;
+    const windowMs = typeof configured.window === 'string'
+        ? reservationWindowMs(configured.window)
+        : null;
+    if (windowMs === null || !Number.isSafeInteger(configured.max) ||
+        configured.max <= 0 || configured.max > MAX_EVENTS)
+        return 'invalid';
+    return { max: configured.max, windowMs };
+}
+function compactReservationEvents(events, _cfg, nowMs) {
+    const maximumWindowMs = reservationWindowMs('30d');
+    const retained = events.filter((event) => {
+        const ts = Date.parse(event.ts);
+        if (!Number.isFinite(ts))
+            return false;
+        return ts >= nowMs - maximumWindowMs;
+    });
+    retained.sort((left, right) => Date.parse(left.ts) - Date.parse(right.ts));
+    const byBackend = new Map();
+    for (const event of retained) {
+        const rows = byBackend.get(event.backend) ?? [];
+        rows.push(event);
+        if (rows.length > MAX_EVENTS)
+            rows.shift();
+        byBackend.set(event.backend, rows);
+    }
+    return [...byBackend.values()].flat().sort((left, right) => Date.parse(left.ts) - Date.parse(right.ts));
+}
+function reserveLimitedQuotaUsesLocked(normalized, limited, cfg, authority, loaded) {
+    try {
+        fsyncDirectory(authority.path, { expectedIdentity: authority });
     }
     catch {
-        // Persistence failure must not crash the fleet — swallow silently.
+        return { kind: 'unavailable', launchAuthorized: false };
+    }
+    if (!stableQuotaDirectory(authority))
+        return { kind: 'unavailable', launchAuthorized: false };
+    const nowMs = fleetQuotaTestHooks?.now?.() ?? Date.now();
+    const compactedEvents = compactReservationEvents(loaded.ledger.events, cfg, nowMs);
+    const byHash = new Map(compactedEvents.flatMap((event) => event.reservationIdHash ? [[event.reservationIdHash, event.backend]] : []));
+    for (const request of normalized) {
+        const existingBackend = byHash.get(request.hash);
+        if (existingBackend !== undefined) {
+            return {
+                kind: existingBackend === request.backend ? 'duplicate' : 'conflict',
+                launchAuthorized: false,
+                backend: request.backend,
+            };
+        }
     }
+    const usage = new Map();
+    const requestedByBackend = new Map();
+    for (const request of limited) {
+        requestedByBackend.set(request.backend, (requestedByBackend.get(request.backend) ?? 0) + 1);
+    }
+    for (const request of limited) {
+        if (usage.has(request.backend))
+            continue;
+        const limit = request.limit;
+        const cutoff = nowMs - limit.windowMs;
+        const used = compactedEvents.reduce((count, event) => event.backend === request.backend && Date.parse(event.ts) >= cutoff ? count + 1 : count, 0);
+        usage.set(request.backend, used);
+        if (used + (requestedByBackend.get(request.backend) ?? 0) > limit.max) {
+            return {
+                kind: 'exhausted', launchAuthorized: false, backend: request.backend,
+                used, limit: limit.max,
+            };
+        }
+    }
+    const ts = new Date(nowMs).toISOString();
+    const next = {
+        events: compactReservationEvents([
+            ...compactedEvents,
+            ...limited.map(({ backend, hash }) => ({ backend, ts, reservationIdHash: hash })),
+        ], cfg, nowMs),
+    };
+    if (!saveQuotaReservation(next, authority, loaded.destination)) {
+        return { kind: 'unavailable', launchAuthorized: false };
+    }
+    return {
+        kind: 'reserved',
+        launchAuthorized: true,
+        reservations: normalized.map(({ backend, limit }) => {
+            if (!limit)
+                return { backend, status: 'unlimited', used: 0, limit: null };
+            return {
+                backend,
+                status: 'reserved',
+                used: (usage.get(backend) ?? 0) + (requestedByBackend.get(backend) ?? 0),
+                limit: limit.max,
+            };
+        }),
+    };
 }
-// ---------------------------------------------------------------------------
-// Record a dispatch
-// ---------------------------------------------------------------------------
 /**
- * Append a dispatch event for `backend` (ts = now) and persist. Never throws.
+ * Atomically reserve a complete set of configured backend dispatches before
+ * any provider contact. The set is all-or-nothing.
+ *
+ * An absent limit remains truly unlimited and does not touch local storage;
+ * this quota boundary therefore makes no replay/idempotency claim for that
+ * backend. Execution ownership remains a separate authority.
+ * Configured limits require an unambiguous private ledger, exclusive mutation
+ * lock, and durable publication. Duplicate and cross-backend identity reuse are
+ * explicit no-launch results: replay safety belongs to the execution authority,
+ * not to this quota ledger.
+ * This function never throws.
  */
-export function recordUse(backend) {
+function reserveFleetQuotaUsesInternal(requests, cfg, options = {}) {
+    if (!Array.isArray(requests) || requests.length === 0 || requests.length > MAX_BATCH_RESERVATIONS) {
+        return { kind: 'invalid', launchAuthorized: false };
+    }
+    if (options.lockWaitMs !== undefined && !Number.isFinite(options.lockWaitMs)) {
+        return { kind: 'invalid', launchAuthorized: false };
+    }
+    const inputHashes = new Map();
+    const normalized = [];
+    for (const request of requests) {
+        if (!request || !validReservationIdentity(request.backend, request.dispatchId)) {
+            return { kind: 'invalid', launchAuthorized: false };
+        }
+        const hash = reservationIdHash(request.dispatchId);
+        const priorBackend = inputHashes.get(hash);
+        if (priorBackend !== undefined) {
+            return {
+                kind: priorBackend === request.backend ? 'duplicate' : 'conflict',
+                launchAuthorized: false,
+                backend: request.backend,
+            };
+        }
+        inputHashes.set(hash, request.backend);
+        const limit = configuredReservationLimit(cfg, request.backend);
+        if (limit === null) {
+            normalized.push({ backend: request.backend, hash, limit: null });
+            continue;
+        }
+        if (limit === 'invalid') {
+            return { kind: 'invalid', launchAuthorized: false, backend: request.backend };
+        }
+        normalized.push({ backend: request.backend, hash, limit });
+    }
+    const limited = normalized.filter((request) => request.limit !== null);
+    if (limited.length === 0) {
+        return {
+            kind: 'unlimited',
+            launchAuthorized: true,
+            reservations: normalized.map(({ backend }) => ({
+                backend, status: 'unlimited', used: 0, limit: null,
+            })),
+        };
+    }
+    const waitMs = options.lockWaitMs === undefined
+        ? 250
+        : Math.max(0, Math.min(2_000, Math.floor(options.lockWaitMs)));
+    const acquired = acquireLocalStoreLockWithOutcome(fleetQuotaReservationLockPath(), waitMs, {
+        anchorPath: homedir(),
+        exactPrivateStorage: true,
+    });
+    if (acquired.state !== 'acquired')
+        return { kind: 'unavailable', launchAuthorized: false };
+    let result;
     try {
-        const q = loadFleetQuota();
-        q.events.push({ backend, ts: new Date().toISOString() });
-        saveFleetQuota(q);
+        const authority = pinQuotaDirectory();
+        if (!authority)
+            result = { kind: 'unavailable', launchAuthorized: false };
+        else {
+            const loaded = loadStrictQuota(authority);
+            result = loaded
+                ? reserveLimitedQuotaUsesLocked(normalized, limited, cfg, authority, loaded)
+                : { kind: 'unavailable', launchAuthorized: false };
+        }
     }
     catch {
-        // Never throws.
+        result = { kind: 'unavailable', launchAuthorized: false };
+    }
+    const released = (fleetQuotaTestHooks?.releaseLock ?? releaseLocalStoreLock)(acquired.lock);
+    if (!released) {
+        return {
+            kind: 'unavailable',
+            launchAuthorized: false,
+            ...(result.kind === 'reserved' ? { reservationConsumed: true } : {}),
+        };
+    }
+    return result;
+}
+export function reserveFleetQuotaUses(requests, cfg, options = {}) {
+    try {
+        return reserveFleetQuotaUsesInternal(requests, cfg, options);
+    }
+    catch {
+        return { kind: 'invalid', launchAuthorized: false };
+    }
+}
+/** Single-dispatch convenience wrapper over the atomic batch transaction. */
+export function reserveFleetQuotaUse(backend, cfg, dispatchId, options = {}) {
+    return reserveFleetQuotaUses([{ backend, dispatchId }], cfg, options);
+}
+function evaluateFleetQuotaAuthority(backend, cfg, now) {
+    try {
+        const limit = configuredReservationLimit(cfg, backend);
+        if (limit === null)
+            return { health: 'unlimited', standing: 'unlimited' };
+        if (limit === 'invalid')
+            return { health: 'invalid', standing: 'over' };
+        const ledger = loadQuotaForAuthorityInspection();
+        if (!ledger)
+            return { health: 'unavailable', standing: 'over' };
+        const nowMs = now ?? fleetQuotaTestHooks?.now?.() ?? Date.now();
+        const compacted = compactReservationEvents(ledger.events, cfg, nowMs);
+        if (compacted.length > MAX_AUTHORITY_EVENTS) {
+            return { health: 'capacity', standing: 'over' };
+        }
+        const cutoff = nowMs - limit.windowMs;
+        const used = compacted.reduce((count, event) => event.backend === backend && Date.parse(event.ts) >= cutoff ? count + 1 : count, 0);
+        return {
+            health: 'healthy',
+            standing: used >= limit.max ? 'over' : used >= limit.max * 0.8 ? 'warn' : 'ok',
+        };
+    }
+    catch {
+        return { health: 'unavailable', standing: 'over' };
     }
 }
+/** Read-only conservative health projection for operator/status surfaces. */
+export function inspectFleetQuotaAuthority(backend, cfg, now) {
+    return evaluateFleetQuotaAuthority(backend, cfg, now).health;
+}
+/**
+ * Quota standing derived from reserved authority slots, not attempt telemetry.
+ * This intentionally counts conservative pre-effect reservations that may not
+ * have reached a provider: those slots still consume the configured window.
+ */
+export function evalFleetQuotaAuthority(backend, cfg, now) {
+    return evaluateFleetQuotaAuthority(backend, cfg, now).standing;
+}
 // ---------------------------------------------------------------------------
 // Window counting
 // ---------------------------------------------------------------------------
@@ -166,15 +810,21 @@ export function usesInWindow(backend, windowMs, now) {
  *
  * Mirrors evalBudget's null-cap-disabled logic: when no
  * cfg.foundry.limits[backend] is configured, the backend is unlimited ⇒ always
- * within limit. Otherwise true iff usesInWindow(...) < limit.max. `now` is
+ * within limit. Healthy configured state follows reservation standing so a
+ * consumed slot can route to an eligible peer. Invalid, unavailable, or
+ * capacity-ambiguous authority deliberately remains advisory-eligible here so
+ * the final provider-effect reservation returns the structured fail-closed
+ * refusal instead of silently capability-downgrading to builtin. `now` is
  * injectable for tests.
  */
 export function withinLimit(backend, cfg, now) {
     const limit = cfg.foundry?.limits?.[backend];
     if (!limit)
         return true; // no cap configured ⇒ unlimited
-    const used = usesInWindow(backend, windowToMs(limit.window), now);
-    return used < limit.max;
+    const evaluation = evaluateFleetQuotaAuthority(backend, cfg, now);
+    if (evaluation.health !== 'healthy')
+        return true;
+    return evaluation.standing !== 'over';
 }
 // ---------------------------------------------------------------------------
 // Three-level quota evaluation (mirrors evalBudget)
@@ -186,9 +836,13 @@ export function withinLimit(backend, cfg, now) {
  */
 export function evalQuota(backend, cfg, now) {
     const limit = cfg.foundry?.limits?.[backend];
-    if (!limit || limit.max <= 0)
-        return 'ok'; // unlimited (or nonsensical cap)
-    const used = usesInWindow(backend, windowToMs(limit.window), now);
+    if (!limit)
+        return 'ok';
+    const windowMs = reservationWindowMs(limit.window);
+    if (windowMs === null || !Number.isSafeInteger(limit.max) ||
+        limit.max <= 0 || limit.max > MAX_EVENTS)
+        return 'over';
+    const used = usesInWindow(backend, windowMs, now);
     if (used >= limit.max)
         return 'over';
     if (used >= limit.max * 0.8)