@agentguard-run/burn 0.1.0

package/dist/src/index.d.ts

@@ -0,0 +1,10 @@
+export * from './types';
+export { DEFAULT_POLICY, DEFAULT_THRESHOLDS } from './defaults';
+export { evaluate, fmt } from './detectors/evaluate';
+export { readIncremental, readAll, newCursor, normaliseLine, type ReaderCursor } from './history/claude-transcript';
+export { applyEvent, newSessionState, windowSum, medianCompletedMinute, cacheReadRatio } from './state/session';
+export { ReservationStore, RESERVATION_TTL_MS } from './state/reservations';
+export { replayAll, replaySession, replayEvents, discoverTranscripts, type ReplaySummary, type SessionReplay } from './replay/simulate';
+export { renderReplay } from './replay/render';
+export { calibrate, type CalibrationResult } from './calibrate';
+export { handlePreToolUse, refreshSession, loadPolicy, settingsSnippet, type HookInput, type HookOutput } from './hook/pre-tool-use';

package/dist/src/index.js

@@ -0,0 +1,52 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.settingsSnippet = exports.loadPolicy = exports.refreshSession = exports.handlePreToolUse = exports.calibrate = exports.renderReplay = exports.discoverTranscripts = exports.replayEvents = exports.replaySession = exports.replayAll = exports.RESERVATION_TTL_MS = exports.ReservationStore = exports.cacheReadRatio = exports.medianCompletedMinute = exports.windowSum = exports.newSessionState = exports.applyEvent = exports.normaliseLine = exports.newCursor = exports.readAll = exports.readIncremental = exports.fmt = exports.evaluate = exports.DEFAULT_THRESHOLDS = exports.DEFAULT_POLICY = void 0;
+__exportStar(require("./types"), exports);
+var defaults_1 = require("./defaults");
+Object.defineProperty(exports, "DEFAULT_POLICY", { enumerable: true, get: function () { return defaults_1.DEFAULT_POLICY; } });
+Object.defineProperty(exports, "DEFAULT_THRESHOLDS", { enumerable: true, get: function () { return defaults_1.DEFAULT_THRESHOLDS; } });
+var evaluate_1 = require("./detectors/evaluate");
+Object.defineProperty(exports, "evaluate", { enumerable: true, get: function () { return evaluate_1.evaluate; } });
+Object.defineProperty(exports, "fmt", { enumerable: true, get: function () { return evaluate_1.fmt; } });
+var claude_transcript_1 = require("./history/claude-transcript");
+Object.defineProperty(exports, "readIncremental", { enumerable: true, get: function () { return claude_transcript_1.readIncremental; } });
+Object.defineProperty(exports, "readAll", { enumerable: true, get: function () { return claude_transcript_1.readAll; } });
+Object.defineProperty(exports, "newCursor", { enumerable: true, get: function () { return claude_transcript_1.newCursor; } });
+Object.defineProperty(exports, "normaliseLine", { enumerable: true, get: function () { return claude_transcript_1.normaliseLine; } });
+var session_1 = require("./state/session");
+Object.defineProperty(exports, "applyEvent", { enumerable: true, get: function () { return session_1.applyEvent; } });
+Object.defineProperty(exports, "newSessionState", { enumerable: true, get: function () { return session_1.newSessionState; } });
+Object.defineProperty(exports, "windowSum", { enumerable: true, get: function () { return session_1.windowSum; } });
+Object.defineProperty(exports, "medianCompletedMinute", { enumerable: true, get: function () { return session_1.medianCompletedMinute; } });
+Object.defineProperty(exports, "cacheReadRatio", { enumerable: true, get: function () { return session_1.cacheReadRatio; } });
+var reservations_1 = require("./state/reservations");
+Object.defineProperty(exports, "ReservationStore", { enumerable: true, get: function () { return reservations_1.ReservationStore; } });
+Object.defineProperty(exports, "RESERVATION_TTL_MS", { enumerable: true, get: function () { return reservations_1.RESERVATION_TTL_MS; } });
+var simulate_1 = require("./replay/simulate");
+Object.defineProperty(exports, "replayAll", { enumerable: true, get: function () { return simulate_1.replayAll; } });
+Object.defineProperty(exports, "replaySession", { enumerable: true, get: function () { return simulate_1.replaySession; } });
+Object.defineProperty(exports, "replayEvents", { enumerable: true, get: function () { return simulate_1.replayEvents; } });
+Object.defineProperty(exports, "discoverTranscripts", { enumerable: true, get: function () { return simulate_1.discoverTranscripts; } });
+var render_1 = require("./replay/render");
+Object.defineProperty(exports, "renderReplay", { enumerable: true, get: function () { return render_1.renderReplay; } });
+var calibrate_1 = require("./calibrate");
+Object.defineProperty(exports, "calibrate", { enumerable: true, get: function () { return calibrate_1.calibrate; } });
+var pre_tool_use_1 = require("./hook/pre-tool-use");
+Object.defineProperty(exports, "handlePreToolUse", { enumerable: true, get: function () { return pre_tool_use_1.handlePreToolUse; } });
+Object.defineProperty(exports, "refreshSession", { enumerable: true, get: function () { return pre_tool_use_1.refreshSession; } });
+Object.defineProperty(exports, "loadPolicy", { enumerable: true, get: function () { return pre_tool_use_1.loadPolicy; } });
+Object.defineProperty(exports, "settingsSnippet", { enumerable: true, get: function () { return pre_tool_use_1.settingsSnippet; } });

package/dist/src/replay/render.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Terminal rendering for replay. This output is the marketing artifact, so it
+ * has to survive a screenshot: pure ASCII box drawing, ANSI colour that
+ * degrades cleanly, nothing that depends on a font.
+ */
+import type { ReplaySummary, SessionReplay } from './simulate';
+export declare function renderReplay(summary: ReplaySummary, opts?: {
+    colour?: boolean;
+    top?: number;
+}): string;
+export declare function renderSessionRow(s: SessionReplay): string;

package/dist/src/replay/render.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Terminal rendering for replay. This output is the marketing artifact, so it
+ * has to survive a screenshot: pure ASCII box drawing, ANSI colour that
+ * degrades cleanly, nothing that depends on a font.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderReplay = renderReplay;
+exports.renderSessionRow = renderSessionRow;
+const evaluate_1 = require("../detectors/evaluate");
+const C = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    red: '\x1b[31m',
+    yellow: '\x1b[33m',
+    green: '\x1b[32m',
+    cyan: '\x1b[36m',
+};
+function colour(enabled, code, text) {
+    return enabled ? `${code}${text}${C.reset}` : text;
+}
+const W = 70;
+function line(text = '') {
+    const clean = text.replace(/\x1b\[[0-9;]*m/g, '');
+    const pad = Math.max(0, W - 2 - clean.length);
+    return `│ ${text}${' '.repeat(pad)} │`;
+}
+const TOP = `╭${'─'.repeat(W)}╮`;
+const MID = `├${'─'.repeat(W)}┤`;
+const BOT = `╰${'─'.repeat(W)}╯`;
+/** API-list equivalent. Labelled as a scenario, never as the user's bill. */
+function scenarioUsd(tokens, cacheShare) {
+    const cached = tokens * cacheShare;
+    return (cached * 0.3 + (tokens - cached) * 5) / 1e6;
+}
+function renderReplay(summary, opts = {}) {
+    const on = opts.colour ?? Boolean(process.stdout.isTTY);
+    const top = opts.top ?? 8;
+    const out = [];
+    const cacheShare = summary.sessions.length
+        ? summary.sessions.reduce((s, r) => s + r.cacheReadRatio * r.totalTokens, 0) / Math.max(summary.totalTokens, 1)
+        : 0;
+    out.push(TOP);
+    out.push(line(colour(on, C.bold, 'AGENTGUARD REPLAY')));
+    out.push(line(colour(on, C.dim, 'Your agent history, before enforcement was installed')));
+    out.push(MID);
+    out.push(line(`${summary.sessions.length} sessions   ${summary.totalSpawns} spawns   ${(0, evaluate_1.fmt)(summary.totalTokens)} tokens observed`));
+    out.push(line(colour(on, C.dim, `${Math.round(cacheShare * 100)}% cache-read. Shown as explanation; it decided nothing.`)));
+    out.push(MID);
+    out.push(line(colour(on, C.bold, 'WHAT ENFORCEMENT WOULD HAVE INTERCEPTED')));
+    out.push(line(''));
+    const share = Math.round(summary.catchableShare * 100);
+    out.push(line(`${colour(on, C.bold, (0, evaluate_1.fmt)(summary.catchableTail))} tokens observed after the first STOP boundary`));
+    out.push(line(`${share}% of everything you burned   ≈ $${Math.round(scenarioUsd(summary.catchableTail, cacheShare)).toLocaleString()} at API list, as a scenario`));
+    out.push(line(''));
+    out.push(line(colour(on, C.dim, 'Upper bound. It assumes you would not have overridden or restarted.')));
+    out.push(MID);
+    out.push(line(`${colour(on, C.red, `${summary.stops} STOP`)}   ${colour(on, C.yellow, `${summary.warns} WARN`)}   ${colour(on, C.green, `${summary.clean} clean`)}`));
+    out.push(MID);
+    for (const s of summary.sessions.slice(0, top)) {
+        out.push(line(colour(on, C.bold, `session ${s.sessionId.slice(0, 8)}`) + `   ${(0, evaluate_1.fmt)(s.totalTokens)} tokens · ${s.spawns} spawns · depth ${s.maxDepth}`));
+        if (s.fanoutStop) {
+            out.push(line(`  ${colour(on, C.red, 'FAN-OUT STOP')} before spawn ${s.fanoutStop.atSpawn} at ${(0, evaluate_1.fmt)(s.fanoutStop.tokensAtStop)}`));
+        }
+        if (s.sustainedStop) {
+            out.push(line(`  ${colour(on, C.red, 'SUSTAINED STOP')} near ${(0, evaluate_1.fmt)(s.sustainedStop.tokensAtStop)}`));
+        }
+        if (!s.fanoutStop && !s.sustainedStop) {
+            if (s.firstWarn)
+                out.push(line(`  ${colour(on, C.yellow, 'WARN')} (${s.firstWarn.detector}) at ${(0, evaluate_1.fmt)(s.firstWarn.tokensAt)} · no stop`));
+            else
+                out.push(line(`  ${colour(on, C.green, 'clean')}`));
+        }
+        if (s.catchableTail > 0) {
+            out.push(line(`  observed tail after stop: ${colour(on, C.bold, (0, evaluate_1.fmt)(s.catchableTail))}`));
+        }
+    }
+    if (summary.sessions.length > top) {
+        out.push(line(colour(on, C.dim, `… ${summary.sessions.length - top} more sessions below the warning line`)));
+    }
+    out.push(MID);
+    out.push(line(colour(on, C.cyan, 'Next: agentguard-burn init   (shadow mode; blocks nothing yet)')));
+    out.push(BOT);
+    return out.join('\n');
+}
+function renderSessionRow(s) {
+    return `${s.sessionId.slice(0, 8)}  ${(0, evaluate_1.fmt)(s.totalTokens).padStart(8)}  ${String(s.spawns).padStart(4)} spawns  ${s.finalVerdict}`;
+}

package/dist/src/replay/simulate.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Replay: run the detectors over recorded history.
+ *
+ * This is the front door. Nobody installs a blocker cold. They install it after
+ * seeing, on their own history, what it would have stopped and when. It is
+ * also the honest validation surface: the thresholds shipped in defaults.ts
+ * were fitted by exactly this code against 412 real sessions.
+ *
+ * What replay measures is the *observed tail* after the first enforceable
+ * boundary. That is an upper bound on what enforcement would have prevented,
+ * because the user might have overridden, restarted, or continued in another
+ * session. It is reported as "retrospectively catchable", never as "saved".
+ */
+import type { BurnEvent, Thresholds, Verdict } from '../types';
+export interface SessionReplay {
+    sessionId: string;
+    path: string;
+    totalTokens: number;
+    spawns: number;
+    maxDepth: number;
+    activeMinutes: number;
+    cacheReadRatio: number;
+    finalVerdict: Verdict;
+    /** First boundary at which each plane reached STOP, if it did. */
+    fanoutStop: {
+        atSpawn: number;
+        tokensAtStop: number;
+    } | null;
+    sustainedStop: {
+        atSpawn: number;
+        tokensAtStop: number;
+    } | null;
+    /** Tokens observed after the earliest STOP boundary. */
+    catchableTail: number;
+    firstWarn: {
+        detector: string;
+        tokensAt: number;
+        spawnsAt: number;
+    } | null;
+}
+export declare function discoverTranscripts(root?: string): string[];
+export declare function replaySession(path: string, thresholds: Thresholds): SessionReplay | null;
+export declare function replayEvents(sessionId: string, path: string, events: BurnEvent[], thresholds: Thresholds): SessionReplay;
+export interface ReplaySummary {
+    sessions: SessionReplay[];
+    totalTokens: number;
+    totalSpawns: number;
+    catchableTail: number;
+    catchableShare: number;
+    stops: number;
+    warns: number;
+    clean: number;
+}
+export declare function replayAll(paths: string[], thresholds: Thresholds, minTokens?: number): ReplaySummary;

package/dist/src/replay/simulate.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * Replay: run the detectors over recorded history.
+ *
+ * This is the front door. Nobody installs a blocker cold. They install it after
+ * seeing, on their own history, what it would have stopped and when. It is
+ * also the honest validation surface: the thresholds shipped in defaults.ts
+ * were fitted by exactly this code against 412 real sessions.
+ *
+ * What replay measures is the *observed tail* after the first enforceable
+ * boundary. That is an upper bound on what enforcement would have prevented,
+ * because the user might have overridden, restarted, or continued in another
+ * session. It is reported as "retrospectively catchable", never as "saved".
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoverTranscripts = discoverTranscripts;
+exports.replaySession = replaySession;
+exports.replayEvents = replayEvents;
+exports.replayAll = replayAll;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const evaluate_1 = require("../detectors/evaluate");
+const claude_transcript_1 = require("../history/claude-transcript");
+const session_1 = require("../state/session");
+function discoverTranscripts(root = (0, node_path_1.join)((0, node_os_1.homedir)(), '.claude', 'projects')) {
+    const out = [];
+    let projects = [];
+    try {
+        projects = (0, node_fs_1.readdirSync)(root);
+    }
+    catch {
+        return out;
+    }
+    for (const project of projects) {
+        const dir = (0, node_path_1.join)(root, project);
+        try {
+            for (const file of (0, node_fs_1.readdirSync)(dir)) {
+                if (file.endsWith('.jsonl'))
+                    out.push((0, node_path_1.join)(dir, file));
+            }
+        }
+        catch {
+            /* not a directory, skip */
+        }
+    }
+    return out;
+}
+function replaySession(path, thresholds) {
+    const { events } = (0, claude_transcript_1.readAll)(path);
+    if (events.length === 0)
+        return null;
+    events.sort((a, b) => a.at - b.at);
+    return replayEvents((0, node_path_1.basename)(path, '.jsonl'), path, events, thresholds);
+}
+function replayEvents(sessionId, path, events, thresholds) {
+    const first = events[0];
+    const state = (0, session_1.newSessionState)(sessionId, first.at);
+    let fanoutStop = null;
+    let sustainedStop = null;
+    let firstWarn = null;
+    let tokensAtEarliestStop = null;
+    for (const event of events) {
+        // A hook boundary exists only where a spawn was attempted. Evaluate the
+        // *proposal* before applying the event, then apply it.
+        for (const spawn of event.spawns) {
+            const report = (0, evaluate_1.evaluate)(state, thresholds, spawn.issuerDepth + 1);
+            if (!firstWarn && report.verdict !== 'OK') {
+                firstWarn = { detector: report.findings[0]?.detector ?? 'unknown', tokensAt: state.totalTokens, spawnsAt: state.spawnCount + 1 };
+            }
+            for (const finding of report.findings) {
+                if (finding.verdict !== 'STOP')
+                    continue;
+                if (finding.detector === 'fanout' && !fanoutStop) {
+                    fanoutStop = { atSpawn: state.spawnCount + 1, tokensAtStop: state.totalTokens };
+                }
+                if ((finding.detector === 'sustained_burn' || finding.detector === 'burn_debt') && !sustainedStop) {
+                    sustainedStop = { atSpawn: state.spawnCount + 1, tokensAtStop: state.totalTokens };
+                }
+            }
+            if ((fanoutStop || sustainedStop) && tokensAtEarliestStop === null) {
+                tokensAtEarliestStop = state.totalTokens;
+            }
+        }
+        // The sustained plane also has a boundary at every tool call, not just
+        // spawns. Approximate: any event with surfaces is a tool boundary.
+        if (!sustainedStop && event.surfaces.length > 0) {
+            const report = (0, evaluate_1.evaluate)(state, thresholds, null);
+            if (!firstWarn && report.verdict !== 'OK') {
+                firstWarn = { detector: report.findings[0]?.detector ?? 'unknown', tokensAt: state.totalTokens, spawnsAt: state.spawnCount };
+            }
+            const hit = report.findings.find((f) => f.verdict === 'STOP' && (f.detector === 'sustained_burn' || f.detector === 'burn_debt'));
+            if (hit) {
+                sustainedStop = { atSpawn: state.spawnCount, tokensAtStop: state.totalTokens };
+                if (tokensAtEarliestStop === null)
+                    tokensAtEarliestStop = state.totalTokens;
+            }
+        }
+        (0, session_1.applyEvent)(state, event);
+    }
+    const final = (0, evaluate_1.evaluate)(state, thresholds, null);
+    return {
+        sessionId,
+        path,
+        totalTokens: state.totalTokens,
+        spawns: state.spawnCount,
+        maxDepth: state.maxDepth,
+        activeMinutes: state.activeMinutes,
+        cacheReadRatio: final.cacheReadRatio,
+        finalVerdict: final.verdict,
+        fanoutStop,
+        sustainedStop,
+        catchableTail: tokensAtEarliestStop === null ? 0 : Math.max(0, state.totalTokens - tokensAtEarliestStop),
+        firstWarn,
+    };
+}
+function replayAll(paths, thresholds, minTokens = 0) {
+    const sessions = [];
+    for (const path of paths) {
+        try {
+            if ((0, node_fs_1.statSync)(path).size === 0)
+                continue;
+            const result = replaySession(path, thresholds);
+            if (result && result.totalTokens >= minTokens)
+                sessions.push(result);
+        }
+        catch {
+            /* unreadable transcript: skip, never crash the report */
+        }
+    }
+    sessions.sort((a, b) => b.totalTokens - a.totalTokens);
+    const totalTokens = sessions.reduce((s, r) => s + r.totalTokens, 0);
+    const catchableTail = sessions.reduce((s, r) => s + r.catchableTail, 0);
+    return {
+        sessions,
+        totalTokens,
+        totalSpawns: sessions.reduce((s, r) => s + r.spawns, 0),
+        catchableTail,
+        catchableShare: totalTokens > 0 ? catchableTail / totalTokens : 0,
+        stops: sessions.filter((r) => r.fanoutStop || r.sustainedStop).length,
+        warns: sessions.filter((r) => !r.fanoutStop && !r.sustainedStop && r.firstWarn).length,
+        clean: sessions.filter((r) => !r.fanoutStop && !r.sustainedStop && !r.firstWarn).length,
+    };
+}

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

@@ -0,0 +1,64 @@
+/**
+ * Atomic spawn reservations.
+ *
+ * The naive design is broken in exactly the case it exists for. When Claude
+ * Code launches ten Agent calls in one batch, ten hook processes start at the
+ * same moment, each reads the transcript, and each sees the same count, say 39.
+ * Every one of them concludes "40 is fine" and allows. The cap was cosmetic
+ * precisely during the burst it was meant to stop.
+ *
+ * Fix: before a spawn is allowed, the hook takes a machine-wide lock and writes
+ * a reservation. The effective count is
+ *
+ *     observed transcript spawns + unexpired reservations
+ *
+ * so the second hook process sees the first one's reservation immediately.
+ * Reservations expire in case a hook allowed a spawn that never happened, and
+ * are reconciled away as the transcript catches up.
+ *
+ * The lock is a directory created with O_EXCL semantics (mkdir is atomic on
+ * every filesystem we care about). A stale lock whose owner PID is dead is
+ * recovered. This is a single-machine primitive by design; two laptops on one
+ * account do not share it, and that is stated rather than papered over.
+ */
+export interface Reservation {
+    sessionId: string;
+    toolUseId: string;
+    at: number;
+    expiresAt: number;
+}
+export declare const RESERVATION_TTL_MS = 90000;
+export declare class ReservationStore {
+    private readonly home;
+    private readonly lockDir;
+    private readonly file;
+    constructor(home: string);
+    /** Acquire the lock or throw. Callers must fail closed on throw. */
+    private acquire;
+    private recoverIfStale;
+    private release;
+    private load;
+    private save;
+    /**
+     * 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: {
+        sessionId: string;
+        toolUseId: string;
+        observedSpawns: number;
+        ceiling: number;
+        now?: number;
+    }): {
+        allowed: boolean;
+        effectiveSpawns: number;
+        pending: number;
+    };
+    /** Drop reservations the transcript has now accounted for. */
+    reconcile(sessionId: string, observedSpawns: number, previouslyObserved: number): void;
+    pendingFor(sessionId: string, now?: number): number;
+    clear(): void;
+}

package/dist/src/state/reservations.js

@@ -0,0 +1,176 @@
+"use strict";
+/**
+ * Atomic spawn reservations.
+ *
+ * The naive design is broken in exactly the case it exists for. When Claude
+ * Code launches ten Agent calls in one batch, ten hook processes start at the
+ * same moment, each reads the transcript, and each sees the same count, say 39.
+ * Every one of them concludes "40 is fine" and allows. The cap was cosmetic
+ * precisely during the burst it was meant to stop.
+ *
+ * Fix: before a spawn is allowed, the hook takes a machine-wide lock and writes
+ * a reservation. The effective count is
+ *
+ *     observed transcript spawns + unexpired reservations
+ *
+ * so the second hook process sees the first one's reservation immediately.
+ * Reservations expire in case a hook allowed a spawn that never happened, and
+ * are reconciled away as the transcript catches up.
+ *
+ * The lock is a directory created with O_EXCL semantics (mkdir is atomic on
+ * every filesystem we care about). A stale lock whose owner PID is dead is
+ * recovered. This is a single-machine primitive by design; two laptops on one
+ * 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;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const LOCK_STALE_MS = 10_000;
+const LOCK_WAIT_MS = 3_000;
+const LOCK_SPIN_MS = 15;
+exports.RESERVATION_TTL_MS = 90_000;
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+class ReservationStore {
+    home;
+    lockDir;
+    file;
+    constructor(home) {
+        this.home = home;
+        (0, node_fs_1.mkdirSync)(home, { recursive: true, mode: 0o700 });
+        this.lockDir = (0, node_path_1.join)(home, 'burn.lock');
+        this.file = (0, node_path_1.join)(home, 'reservations.json');
+    }
+    /** Acquire the lock or throw. Callers must fail closed on throw. */
+    acquire() {
+        const deadline = Date.now() + LOCK_WAIT_MS;
+        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 });
+                return;
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+                this.recoverIfStale();
+                if (Date.now() > deadline) {
+                    throw new Error('AgentGuard could not acquire the reservation lock; failing closed.');
+                }
+                sleepSync(LOCK_SPIN_MS);
+            }
+        }
+    }
+    recoverIfStale() {
+        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 });
+        }
+        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 });
+        }
+    }
+    release() {
+        (0, node_fs_1.rmSync)(this.lockDir, { recursive: true, force: true });
+    }
+    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;
+        }
+        catch {
+            /* corrupt or missing: start clean, never trust partial state */
+        }
+        return { version: 1, reservations: [] };
+    }
+    save(data) {
+        const tmp = `${this.file}.${process.pid}.tmp`;
+        (0, node_fs_1.writeFileSync)(tmp, JSON.stringify(data), { mode: 0o600 });
+        (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.
+     *
+     * Returns the effective count that was evaluated, so the caller can report
+     * exactly why a spawn was denied.
+     */
+    reserve(args) {
+        const now = args.now ?? Date.now();
+        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 };
+        }
+        finally {
+            this.release();
+        }
+    }
+    /** Drop reservations the transcript has now accounted for. */
+    reconcile(sessionId, observedSpawns, previouslyObserved) {
+        const settled = Math.max(0, observedSpawns - previouslyObserved);
+        if (settled === 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();
+        }
+    }
+    pendingFor(sessionId, now = Date.now()) {
+        return this.load().reservations.filter((r) => r.sessionId === sessionId && r.expiresAt > now).length;
+    }
+    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 });
+    }
+}
+exports.ReservationStore = ReservationStore;

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

@@ -0,0 +1,19 @@
+/**
+ * Session state: fold events into the numbers detectors need.
+ *
+ * Active time is the key idea. These sessions are resumed over days. A
+ * wall-clock rolling window dilutes real activity with hours of idleness, so a
+ * "16 spawns in 5 minutes" rule never fires on a session that spawned 143
+ * agents over an evening with coffee breaks. Active time caps every gap
+ * between events, so a burst looks like a burst regardless of when the session
+ * started.
+ */
+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;
+/** 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. */
+export declare function medianCompletedMinute(state: SessionState): number;
+export declare function cacheReadRatio(state: SessionState): number;