@agentguard-run/burn 0.1.1 → 0.2.1

package/dist/src/state/reservations.d.ts

@@ -27,18 +27,88 @@ export interface Reservation {
     at: number;
     expiresAt: number;
 }
+/**
+ * A model call in flight or recently finished. Lives in the same file, under
+ * the same lock, as spawn reservations: the cross-tool claim collapses the
+ * moment there are two lock domains. Finished calls are kept only as long as
+ * the local-compute window needs them for occupied-time accounting.
+ */
+export interface CallReservation {
+    sessionId: string;
+    callId: string;
+    host: string;
+    estimatedTokens: number;
+    startedAt: number;
+    finishedAt: number | null;
+    expiresAt: number;
+}
+interface ReservationFile {
+    version: 1 | 2;
+    reservations: Reservation[];
+    calls?: CallReservation[];
+}
+export interface ComputeSnapshot {
+    /** Calls started and not yet finished, across every host on this machine. */
+    inFlight: number;
+    inFlightForSession: number;
+    /** Sum of request durations overlapping the window. Not GPU utilisation. */
+    occupiedMs: number;
+    /** Estimates reserved by calls still in flight. */
+    pendingEstimatedTokens: number;
+    windowMs: number;
+}
 export declare const RESERVATION_TTL_MS = 90000;
+/**
+ * Lock instances are identified by nonce, not by path. This is what makes
+ * the lock survive contention from hundreds of processes:
+ *
+ * A waiter that reads the owner record, then gets descheduled, then judges
+ * "owner is dead" is telling the truth about an instance that has since
+ * been released and replaced. Under 240 concurrent hook processes that
+ * exact stall happened, the waiter tore down a live sibling's lock, two
+ * processes ran the transaction at once, and 43 spawns were admitted
+ * against a cap of 40. Every teardown below is therefore checked against
+ * the nonce it was judged on, and every write is fenced on the holder's own
+ * nonce still being on the path.
+ */
 export declare class ReservationStore {
     private readonly home;
     private readonly lockDir;
     private readonly file;
+    private held;
     constructor(home: string);
     /** Acquire the lock or throw. Callers must fail closed on throw. */
     private acquire;
+    private readOwnerAt;
+    /** The holder's own instance is still the one on the path. */
+    private fence;
+    /**
+     * Take the lock directory off its path atomically, then verify it is the
+     * instance we meant. rmSync on the live path is readdir + unlink + rmdir,
+     * and a sibling can mkdir the same path between those steps, so removal
+     * is always rename-then-delete. If the instance we grabbed is not the one
+     * we judged (`expect`), it is a live sibling's: put it back.
+     */
+    private discard;
+    private trace;
     private recoverIfStale;
     private release;
     private load;
     private save;
+    /**
+     * Run `fn` with the machine-wide lock held. Everything inside sees one
+     * consistent reservation file and writes it back once. The gateway uses
+     * this to make "fold state, evaluate, reserve, sign" a single transaction,
+     * so two hosts racing the same session cannot interleave halfway.
+     *
+     * Throws if the lock cannot be taken. Callers must fail closed on throw.
+     */
+    withLock<T>(fn: (tx: Transaction) => T): T;
+    /**
+     * Callers that write their own files inside a transaction (the gateway's
+     * session file) call this right before writing, for the same reason.
+     */
+    assertHeld(): void;
     /**
      * Try to reserve one spawn slot. `observedSpawns` is what the transcript
      * shows; the decision is made against observed + pending, under the lock.
@@ -46,19 +116,53 @@ export declare class ReservationStore {
      * Returns the effective count that was evaluated, so the caller can report
      * exactly why a spawn was denied.
      */
-    reserve(args: {
-        sessionId: string;
-        toolUseId: string;
-        observedSpawns: number;
-        ceiling: number;
-        now?: number;
-    }): {
-        allowed: boolean;
-        effectiveSpawns: number;
-        pending: number;
-    };
+    reserve(args: ReserveArgs): ReserveResult;
     /** Drop reservations the transcript has now accounted for. */
     reconcile(sessionId: string, observedSpawns: number, previouslyObserved: number): void;
     pendingFor(sessionId: string, now?: number): number;
+    reserveCall(args: ReserveCallArgs): ComputeSnapshot;
+    finishCall(callId: string, windowMs: number, now?: number): number | null;
+    /** Lock-free read for status. May be a few milliseconds stale; never used to decide. */
+    computeSnapshot(sessionId: string, windowMs: number, now?: number): ComputeSnapshot;
     clear(): void;
 }
+export interface ReserveArgs {
+    sessionId: string;
+    toolUseId: string;
+    observedSpawns: number;
+    ceiling: number;
+    now?: number;
+}
+export interface ReserveResult {
+    allowed: boolean;
+    effectiveSpawns: number;
+    pending: number;
+}
+export interface ReserveCallArgs {
+    sessionId: string;
+    callId: string;
+    host: string;
+    estimatedTokens: number;
+    ttlMs: number;
+    windowMs: number;
+    now?: number;
+}
+/** Operations on the loaded reservation file while the lock is held. */
+export declare class Transaction {
+    private readonly data;
+    dirty: boolean;
+    constructor(data: ReservationFile);
+    reserve(args: ReserveArgs): ReserveResult;
+    reconcile(sessionId: string, observedSpawns: number, previouslyObserved: number): void;
+    /**
+     * Open a model-call reservation and return the compute snapshot it was
+     * admitted against. Idempotent on callId: middleware and a proxy that both
+     * see the same call converge on one record. The caller decides the verdict;
+     * the store only guarantees the count is atomic across processes.
+     */
+    reserveCall(args: ReserveCallArgs): ComputeSnapshot;
+    /** Mark a call finished. Returns its duration, or null if unknown to us. */
+    finishCall(callId: string, windowMs: number, now?: number): number | null;
+    computeSnapshot(sessionId: string, windowMs: number, now?: number): ComputeSnapshot;
+}
+export {};

package/dist/src/state/reservations.js

@@ -23,7 +23,7 @@
  * account do not share it, and that is stated rather than papered over.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ReservationStore = exports.RESERVATION_TTL_MS = void 0;
+exports.Transaction = exports.ReservationStore = exports.RESERVATION_TTL_MS = void 0;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const LOCK_STALE_MS = 10_000;
@@ -42,10 +42,24 @@ function pidAlive(pid) {
 function sleepSync(ms) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
+/**
+ * Lock instances are identified by nonce, not by path. This is what makes
+ * the lock survive contention from hundreds of processes:
+ *
+ * A waiter that reads the owner record, then gets descheduled, then judges
+ * "owner is dead" is telling the truth about an instance that has since
+ * been released and replaced. Under 240 concurrent hook processes that
+ * exact stall happened, the waiter tore down a live sibling's lock, two
+ * processes ran the transaction at once, and 43 spawns were admitted
+ * against a cap of 40. Every teardown below is therefore checked against
+ * the nonce it was judged on, and every write is fenced on the holder's own
+ * nonce still being on the path.
+ */
 class ReservationStore {
     home;
     lockDir;
     file;
+    held = null;
     constructor(home) {
         this.home = home;
         (0, node_fs_1.mkdirSync)(home, { recursive: true, mode: 0o700 });
@@ -58,7 +72,15 @@ class ReservationStore {
         for (;;) {
             try {
                 (0, node_fs_1.mkdirSync)(this.lockDir, { mode: 0o700 });
-                (0, node_fs_1.writeFileSync)((0, node_path_1.join)(this.lockDir, 'owner'), `${process.pid}\n${Date.now()}\n`, { mode: 0o600 });
+                // The owner record must appear whole or not at all. A sibling that
+                // read a half-written timestamp once parsed it as "held since 1970",
+                // reclaimed a live lock, and admitted a 41st spawn.
+                const owner = { pid: process.pid, since: Date.now(), nonce: `${process.pid}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}` };
+                const tmp = (0, node_path_1.join)(this.lockDir, `owner.${process.pid}`);
+                (0, node_fs_1.writeFileSync)(tmp, JSON.stringify(owner), { mode: 0o600 });
+                (0, node_fs_1.renameSync)(tmp, (0, node_path_1.join)(this.lockDir, 'owner'));
+                this.held = owner;
+                this.trace('acquired');
                 return;
             }
             catch (error) {
@@ -72,34 +94,124 @@ class ReservationStore {
             }
         }
     }
+    readOwnerAt(dir) {
+        try {
+            const parsed = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, 'owner'), 'utf8'));
+            if (Number.isInteger(parsed.pid) && typeof parsed.since === 'number' && parsed.since > 1_000_000_000_000 && typeof parsed.nonce === 'string') {
+                return { pid: parsed.pid, since: parsed.since, nonce: parsed.nonce };
+            }
+        }
+        catch {
+            /* missing or unreadable */
+        }
+        return null;
+    }
+    /** The holder's own instance is still the one on the path. */
+    fence() {
+        const current = this.readOwnerAt(this.lockDir);
+        if (!this.held || !current || current.nonce !== this.held.nonce) {
+            throw new Error('AgentGuard lost the reservation lock mid-transaction; failing closed.');
+        }
+    }
+    /**
+     * Take the lock directory off its path atomically, then verify it is the
+     * instance we meant. rmSync on the live path is readdir + unlink + rmdir,
+     * and a sibling can mkdir the same path between those steps, so removal
+     * is always rename-then-delete. If the instance we grabbed is not the one
+     * we judged (`expect`), it is a live sibling's: put it back.
+     */
+    discard(reason, expect) {
+        const quarantine = `${this.lockDir}.${reason}.${process.pid}.${Date.now().toString(36)}`;
+        try {
+            (0, node_fs_1.renameSync)(this.lockDir, quarantine);
+        }
+        catch {
+            return false; // somebody else already took it off the path
+        }
+        const got = this.readOwnerAt(quarantine);
+        if ((got?.nonce ?? null) !== expect) {
+            // Not the instance we judged. Give it back; if a waiter slipped into
+            // the freed path in between, the displaced holder's fence throws and
+            // its transaction is discarded, so nothing double-commits.
+            try {
+                (0, node_fs_1.renameSync)(quarantine, this.lockDir);
+                this.trace(`discard ${reason}: wrong instance, returned`);
+                return false;
+            }
+            catch {
+                this.trace(`discard ${reason}: wrong instance, could not return`);
+            }
+        }
+        try {
+            (0, node_fs_1.rmSync)(quarantine, { recursive: true, force: true });
+        }
+        catch {
+            /* late write by the old holder; unique name, harmless */
+        }
+        this.trace(`discard ${reason} ok`);
+        return true;
+    }
+    trace(line) {
+        if (!process.env.AGENTGUARD_DEBUG_LOCK)
+            return;
+        try {
+            (0, node_fs_1.appendFileSync)((0, node_path_1.join)(this.home, 'lock.log'), `${Date.now()} ${process.pid} ${line}\n`);
+        }
+        catch {
+            /* debug only */
+        }
+    }
     recoverIfStale() {
+        const owner = this.readOwnerAt(this.lockDir);
+        if (owner) {
+            const stale = !pidAlive(owner.pid) || Date.now() - owner.since > LOCK_STALE_MS;
+            if (stale) {
+                this.trace(`reclaim: owner ${owner.pid} alive=${pidAlive(owner.pid)} age=${Date.now() - owner.since}ms`);
+                this.discard('stale', owner.nonce);
+            }
+            return;
+        }
+        // No trustworthy owner record: the holder is between mkdir and rename, or
+        // it died in that gap. Only the directory's age can tell those apart.
+        // Reclaiming immediately here was the race that let a 41st spawn through
+        // under 60 concurrent processes.
         try {
-            const raw = (0, node_fs_1.readFileSync)((0, node_path_1.join)(this.lockDir, 'owner'), 'utf8').split('\n');
-            const pid = Number(raw[0]);
-            const since = Number(raw[1]);
-            const stale = !Number.isFinite(pid) || !pidAlive(pid) || Date.now() - since > LOCK_STALE_MS;
-            if (stale)
-                (0, node_fs_1.rmSync)(this.lockDir, { recursive: true, force: true });
+            const age = Date.now() - (0, node_fs_1.statSync)(this.lockDir).mtimeMs;
+            if (age > LOCK_STALE_MS) {
+                this.trace(`reclaim ownerless dir age=${age}ms`);
+                this.discard('orphan', null);
+            }
         }
         catch {
-            // Owner file missing: the lock holder is mid-write or gone. If the
-            // directory is older than the stale window, reclaim it.
-            (0, node_fs_1.rmSync)(this.lockDir, { recursive: true, force: true });
+            /* directory vanished between checks: the next mkdir attempt decides */
         }
     }
     release() {
-        (0, node_fs_1.rmSync)(this.lockDir, { recursive: true, force: true });
+        // Only our own instance is released. If it was reclaimed and a sibling
+        // now holds the path, discard() sees the nonce mismatch and returns it.
+        // Release never throws: a crash here is how a lock goes ownerless.
+        const mine = this.held;
+        this.held = null;
+        if (!mine)
+            return;
+        try {
+            this.discard('released', mine.nonce);
+        }
+        catch (error) {
+            this.trace(`release threw ${error.message}`);
+        }
     }
     load() {
         try {
             const parsed = JSON.parse((0, node_fs_1.readFileSync)(this.file, 'utf8'));
-            if (parsed && parsed.version === 1 && Array.isArray(parsed.reservations))
-                return parsed;
+            if (parsed && (parsed.version === 1 || parsed.version === 2) && Array.isArray(parsed.reservations)) {
+                return { version: 2, reservations: parsed.reservations, calls: Array.isArray(parsed.calls) ? parsed.calls : [] };
+            }
         }
         catch {
             /* corrupt or missing: start clean, never trust partial state */
         }
-        return { version: 1, reservations: [] };
+        return { version: 2, reservations: [], calls: [] };
     }
     save(data) {
         const tmp = `${this.file}.${process.pid}.tmp`;
@@ -107,70 +219,192 @@ class ReservationStore {
         (0, node_fs_1.renameSync)(tmp, this.file);
     }
     /**
-     * Try to reserve one spawn slot. `observedSpawns` is what the transcript
-     * shows; the decision is made against observed + pending, under the lock.
+     * Run `fn` with the machine-wide lock held. Everything inside sees one
+     * consistent reservation file and writes it back once. The gateway uses
+     * this to make "fold state, evaluate, reserve, sign" a single transaction,
+     * so two hosts racing the same session cannot interleave halfway.
      *
-     * Returns the effective count that was evaluated, so the caller can report
-     * exactly why a spawn was denied.
+     * Throws if the lock cannot be taken. Callers must fail closed on throw.
      */
-    reserve(args) {
-        const now = args.now ?? Date.now();
+    withLock(fn) {
         this.acquire();
         try {
             const data = this.load();
-            data.reservations = data.reservations.filter((r) => r.expiresAt > now);
-            // Idempotent: the same tool_use_id evaluated twice must not double-count.
-            const existing = data.reservations.find((r) => r.toolUseId === args.toolUseId);
-            const pendingForSession = data.reservations.filter((r) => r.sessionId === args.sessionId && r.toolUseId !== args.toolUseId).length;
-            const effective = args.observedSpawns + pendingForSession + 1;
-            if (existing) {
-                return { allowed: true, effectiveSpawns: effective, pending: pendingForSession };
-            }
-            if (effective > args.ceiling) {
-                return { allowed: false, effectiveSpawns: effective, pending: pendingForSession };
-            }
-            data.reservations.push({
-                sessionId: args.sessionId,
-                toolUseId: args.toolUseId,
-                at: now,
-                expiresAt: now + exports.RESERVATION_TTL_MS,
-            });
-            this.save(data);
-            return { allowed: true, effectiveSpawns: effective, pending: pendingForSession };
+            const tx = new Transaction(data);
+            const result = fn(tx);
+            // Fence before anything is written: if our instance was reclaimed
+            // while fn ran, the whole transaction is discarded, not half-applied.
+            this.fence();
+            if (tx.dirty)
+                this.save(data);
+            return result;
         }
         finally {
             this.release();
         }
     }
+    /**
+     * Callers that write their own files inside a transaction (the gateway's
+     * session file) call this right before writing, for the same reason.
+     */
+    assertHeld() {
+        this.fence();
+    }
+    /**
+     * Try to reserve one spawn slot. `observedSpawns` is what the transcript
+     * shows; the decision is made against observed + pending, under the lock.
+     *
+     * Returns the effective count that was evaluated, so the caller can report
+     * exactly why a spawn was denied.
+     */
+    reserve(args) {
+        return this.withLock((tx) => tx.reserve(args));
+    }
     /** Drop reservations the transcript has now accounted for. */
     reconcile(sessionId, observedSpawns, previouslyObserved) {
-        const settled = Math.max(0, observedSpawns - previouslyObserved);
-        if (settled === 0)
+        if (Math.max(0, observedSpawns - previouslyObserved) === 0)
             return;
-        this.acquire();
-        try {
-            const data = this.load();
-            let remaining = settled;
-            data.reservations = data.reservations.filter((r) => {
-                if (r.sessionId === sessionId && remaining > 0) {
-                    remaining -= 1;
-                    return false;
-                }
-                return true;
-            });
-            this.save(data);
-        }
-        finally {
-            this.release();
-        }
+        this.withLock((tx) => tx.reconcile(sessionId, observedSpawns, previouslyObserved));
     }
     pendingFor(sessionId, now = Date.now()) {
         return this.load().reservations.filter((r) => r.sessionId === sessionId && r.expiresAt > now).length;
     }
+    reserveCall(args) {
+        return this.withLock((tx) => tx.reserveCall(args));
+    }
+    finishCall(callId, windowMs, now = Date.now()) {
+        return this.withLock((tx) => tx.finishCall(callId, windowMs, now));
+    }
+    /** Lock-free read for status. May be a few milliseconds stale; never used to decide. */
+    computeSnapshot(sessionId, windowMs, now = Date.now()) {
+        return computeSnapshot(pruneCalls(this.load().calls ?? [], now, windowMs), sessionId, now, windowMs);
+    }
     clear() {
         if ((0, node_fs_1.existsSync)(this.file))
             (0, node_fs_1.rmSync)(this.file, { force: true });
-        (0, node_fs_1.rmSync)(this.lockDir, { recursive: true, force: true });
+        this.discard('cleared', this.readOwnerAt(this.lockDir)?.nonce ?? null);
     }
 }
 exports.ReservationStore = ReservationStore;
+/** Operations on the loaded reservation file while the lock is held. */
+class Transaction {
+    data;
+    dirty = false;
+    constructor(data) {
+        this.data = data;
+        if (!this.data.calls)
+            this.data.calls = [];
+    }
+    reserve(args) {
+        const now = args.now ?? Date.now();
+        const data = this.data;
+        const before = data.reservations.length;
+        data.reservations = data.reservations.filter((r) => r.expiresAt > now);
+        if (data.reservations.length !== before)
+            this.dirty = true;
+        // Idempotent: the same tool_use_id evaluated twice must not double-count.
+        const existing = data.reservations.find((r) => r.toolUseId === args.toolUseId);
+        const pendingForSession = data.reservations.filter((r) => r.sessionId === args.sessionId && r.toolUseId !== args.toolUseId).length;
+        const effective = args.observedSpawns + pendingForSession + 1;
+        if (existing) {
+            return { allowed: true, effectiveSpawns: effective, pending: pendingForSession };
+        }
+        if (effective > args.ceiling) {
+            return { allowed: false, effectiveSpawns: effective, pending: pendingForSession };
+        }
+        data.reservations.push({
+            sessionId: args.sessionId,
+            toolUseId: args.toolUseId,
+            at: now,
+            expiresAt: now + exports.RESERVATION_TTL_MS,
+        });
+        this.dirty = true;
+        return { allowed: true, effectiveSpawns: effective, pending: pendingForSession };
+    }
+    reconcile(sessionId, observedSpawns, previouslyObserved) {
+        let remaining = Math.max(0, observedSpawns - previouslyObserved);
+        if (remaining === 0)
+            return;
+        const before = this.data.reservations.length;
+        this.data.reservations = this.data.reservations.filter((r) => {
+            if (r.sessionId === sessionId && remaining > 0) {
+                remaining -= 1;
+                return false;
+            }
+            return true;
+        });
+        if (this.data.reservations.length !== before)
+            this.dirty = true;
+    }
+    /**
+     * Open a model-call reservation and return the compute snapshot it was
+     * admitted against. Idempotent on callId: middleware and a proxy that both
+     * see the same call converge on one record. The caller decides the verdict;
+     * the store only guarantees the count is atomic across processes.
+     */
+    reserveCall(args) {
+        const now = args.now ?? Date.now();
+        const calls = pruneCalls(this.data.calls, now, args.windowMs);
+        if (calls.length !== this.data.calls.length)
+            this.dirty = true;
+        this.data.calls = calls;
+        if (!calls.some((c) => c.callId === args.callId)) {
+            calls.push({
+                sessionId: args.sessionId,
+                callId: args.callId,
+                host: args.host,
+                estimatedTokens: Math.max(0, args.estimatedTokens),
+                startedAt: now,
+                finishedAt: null,
+                expiresAt: now + args.ttlMs,
+            });
+            this.dirty = true;
+        }
+        return computeSnapshot(calls, args.sessionId, now, args.windowMs);
+    }
+    /** Mark a call finished. Returns its duration, or null if unknown to us. */
+    finishCall(callId, windowMs, now = Date.now()) {
+        const call = this.data.calls.find((c) => c.callId === callId);
+        if (!call)
+            return null;
+        if (call.finishedAt === null) {
+            call.finishedAt = now;
+            call.estimatedTokens = 0;
+            // Keep it exactly as long as the occupied-time window can see it.
+            call.expiresAt = now + windowMs;
+            this.dirty = true;
+        }
+        return call.finishedAt - call.startedAt;
+    }
+    computeSnapshot(sessionId, windowMs, now = Date.now()) {
+        return computeSnapshot(pruneCalls(this.data.calls, now, windowMs), sessionId, now, windowMs);
+    }
+}
+exports.Transaction = Transaction;
+function pruneCalls(calls, now, windowMs) {
+    const horizon = now - windowMs;
+    return calls.filter((c) => {
+        if (c.finishedAt === null)
+            return c.expiresAt > now;
+        return c.finishedAt > horizon;
+    });
+}
+function computeSnapshot(calls, sessionId, now, windowMs) {
+    const horizon = now - windowMs;
+    let inFlight = 0;
+    let inFlightForSession = 0;
+    let occupiedMs = 0;
+    let pendingEstimatedTokens = 0;
+    for (const c of calls) {
+        const end = c.finishedAt ?? now;
+        if (c.finishedAt === null) {
+            inFlight += 1;
+            if (c.sessionId === sessionId)
+                inFlightForSession += 1;
+            pendingEstimatedTokens += c.estimatedTokens;
+        }
+        // Only the part of the request inside the window counts.
+        occupiedMs += Math.max(0, end - Math.max(c.startedAt, horizon));
+    }
+    return { inFlight, inFlightForSession, occupiedMs, pendingEstimatedTokens, windowMs };
+}

package/dist/src/state/session.d.ts

@@ -12,6 +12,12 @@ import type { BurnEvent, SessionState } from '../types';
 export declare function newSessionState(sessionId: string, firstEventAt: number): SessionState;
 /** Apply one event. Returns the active minutes that elapsed for debt accounting. */
 export declare function applyEvent(state: SessionState, event: BurnEvent): number;
+/**
+ * Correct a count already applied, in either direction, without touching
+ * active time. Used when a real usage figure replaces an estimate that was
+ * reserved under the same call ID. Buckets never go below zero.
+ */
+export declare function applyCorrection(state: SessionState, deltaTokens: number, deltaCacheRead: number): void;
 /** Sum of a rolling window over the last N active minutes. */
 export declare function windowSum(byMinute: Map<number, number>, activeMinutes: number, windowMinutes: number): number;
 /** Median of completed, nonzero active minutes. The current partial minute is excluded. */

package/dist/src/state/session.js

@@ -12,6 +12,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.newSessionState = newSessionState;
 exports.applyEvent = applyEvent;
+exports.applyCorrection = applyCorrection;
 exports.windowSum = windowSum;
 exports.medianCompletedMinute = medianCompletedMinute;
 exports.cacheReadRatio = cacheReadRatio;
@@ -62,6 +63,22 @@ function applyEvent(state, event) {
     }
     return activeGapMinutes;
 }
+/**
+ * Correct a count already applied, in either direction, without touching
+ * active time. Used when a real usage figure replaces an estimate that was
+ * reserved under the same call ID. Buckets never go below zero.
+ */
+function applyCorrection(state, deltaTokens, deltaCacheRead) {
+    state.totalTokens = Math.max(0, state.totalTokens + deltaTokens);
+    state.totalCacheRead = Math.max(0, state.totalCacheRead + deltaCacheRead);
+    const bucket = Math.floor(state.activeMinutes);
+    const current = state.tokensByActiveMinute.get(bucket) ?? 0;
+    const next = Math.max(0, current + deltaTokens);
+    if (next > 0)
+        state.tokensByActiveMinute.set(bucket, next);
+    else
+        state.tokensByActiveMinute.delete(bucket);
+}
 /** Sum of a rolling window over the last N active minutes. */
 function windowSum(byMinute, activeMinutes, windowMinutes) {
     const from = Math.max(0, Math.floor(activeMinutes) - windowMinutes);

package/dist/src/status.d.ts

@@ -0,0 +1,19 @@
+/**
+ * One status for the whole machine.
+ *
+ * Every host's sessions in one table, with coverage stated per plane, so an
+ * OK never masquerades as full visibility. A Cursor session shows
+ * `usage:n/a`; a proxy session shows `spawns:n/a`; a session fed by both
+ * middleware and the proxy shows full coverage, because it has it.
+ */
+import type { GatewaySessionView } from './gateway';
+import type { HostHealth } from './install';
+import type { ComputeSnapshot } from './state/reservations';
+/**
+ * Claude Code sessions live in the hook's own files (they carry a transcript
+ * cursor the gateway sessions do not). Read them into the same view so the
+ * table shows every host, not just the new ones.
+ */
+export declare function readHookSessions(home: string): GatewaySessionView[];
+export declare function renderHostHealth(hosts: HostHealth[]): string;
+export declare function renderMachineStatus(sessions: GatewaySessionView[], compute: ComputeSnapshot, now?: number): string;