@agentguard-run/burn 0.1.0 → 0.2.0

package/dist/src/replay/render.js

@@ -1,11 +1,14 @@
 "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.
+ * Terminal rendering. This output is the distribution artifact, so it is
+ * designed to be screenshotted: one giant number, a curve you can see the
+ * runaway in, one line worth quoting. Pure ASCII/ANSI, degrades cleanly.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.sparkline = sparkline;
+exports.comparison = comparison;
 exports.renderReplay = renderReplay;
+exports.renderStop = renderStop;
 exports.renderSessionRow = renderSessionRow;
 const evaluate_1 = require("../detectors/evaluate");
 const C = {
@@ -16,74 +19,202 @@ const C = {
     yellow: '\x1b[33m',
     green: '\x1b[32m',
     cyan: '\x1b[36m',
+    magenta: '\x1b[35m',
+    bgRed: '\x1b[41m',
+    white: '\x1b[97m',
 };
-function colour(enabled, code, text) {
-    return enabled ? `${code}${text}${C.reset}` : text;
+const W = 72;
+function paint(on, code, text) {
+    return on ? `${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);
+function strip(text) {
+    return text.replace(/\x1b\[[0-9;]*m/g, '');
+}
+function row(text = '') {
+    const pad = Math.max(0, W - 2 - strip(text).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. */
+// ---------------------------------------------------------------------------
+// Block digits. Five rows, three columns each, for 0-9 . % B K M and space.
+// ---------------------------------------------------------------------------
+const GLYPHS = {
+    '0': ['█▀▀█', '█  █', '█  █', '█  █', '▀▀▀▀'],
+    '1': ['  ▀█', '   █', '   █', '   █', '   ▀'],
+    '2': ['▀▀▀█', '   █', '█▀▀▀', '█   ', '▀▀▀▀'],
+    '3': ['▀▀▀█', '   █', ' ▀▀█', '   █', '▀▀▀▀'],
+    '4': ['█  █', '█  █', '▀▀▀█', '   █', '   ▀'],
+    '5': ['█▀▀▀', '█   ', '▀▀▀█', '   █', '▀▀▀▀'],
+    '6': ['█▀▀▀', '█   ', '█▀▀█', '█  █', '▀▀▀▀'],
+    '7': ['▀▀▀█', '   █', '   █', '   █', '   ▀'],
+    '8': ['█▀▀█', '█  █', '█▀▀█', '█  █', '▀▀▀▀'],
+    '9': ['█▀▀█', '█  █', '▀▀▀█', '   █', '▀▀▀▀'],
+    '.': ['    ', '    ', '    ', '    ', ' ▀  '],
+    '%': ['▀▀  █', '   █ ', '  █  ', ' █   ', '█  ▀▀'],
+    B: ['█▀▀▄', '█  █', '█▀▀▄', '█  █', '▀▀▀ '],
+    M: ['█▄ ▄█', '█ ▀ █', '█   █', '█   █', '▀   ▀'],
+    K: ['█  █', '█ █ ', '██  ', '█ █ ', '▀  ▀'],
+    ' ': ['  ', '  ', '  ', '  ', '  '],
+};
+function blockDigits(text) {
+    const rows = ['', '', '', '', ''];
+    for (const ch of text) {
+        const g = GLYPHS[ch] ?? GLYPHS[' '];
+        for (let r = 0; r < 5; r++)
+            rows[r] += g[r] + ' ';
+    }
+    return rows.map((r) => r.trimEnd());
+}
+// ---------------------------------------------------------------------------
+// Sparkline with the STOP point marked.
+// ---------------------------------------------------------------------------
+const BARS = '▁▂▃▄▅▆▇█';
+function sparkline(curve, stopAt, on) {
+    if (curve.length === 0)
+        return '';
+    let out = '';
+    for (let i = 0; i < curve.length; i++) {
+        const level = Math.min(BARS.length - 1, Math.max(0, Math.round(curve[i] * (BARS.length - 1))));
+        const bar = BARS[level];
+        if (stopAt !== null && i >= stopAt) {
+            // Everything after the stop is the tail enforcement would have cut.
+            out += paint(on, C.red, i === stopAt ? '┃' : bar);
+        }
+        else {
+            out += paint(on, C.green, bar);
+        }
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// The quotable comparison. Tokens to something a human can picture.
+// ---------------------------------------------------------------------------
+const COMPARISONS = [
+    { tokens: 7_000_000_000, label: 'all of English Wikipedia' },
+    { tokens: 1_200_000_000, label: 'the entire Harry Potter series, 1,000 times' },
+    { tokens: 200_000_000, label: 'the complete works of Shakespeare, 200 times' },
+    { tokens: 40_000_000, label: 'the King James Bible, 50 times' },
+    { tokens: 130_000, label: 'Slaughterhouse-Five' },
+];
+function comparison(tokens) {
+    for (const c of COMPARISONS) {
+        const times = tokens / c.tokens;
+        if (times >= 1) {
+            const n = times >= 10 ? Math.round(times) : Math.round(times * 10) / 10;
+            return `≈ ${c.label}${n > 1 ? `, ${n}×` : ''}`;
+        }
+    }
+    return '';
+}
+// ---------------------------------------------------------------------------
+// Replay
+// ---------------------------------------------------------------------------
 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 top = opts.top ?? 6;
     const out = [];
-    const cacheShare = summary.sessions.length
-        ? summary.sessions.reduce((s, r) => s + r.cacheReadRatio * r.totalTokens, 0) / Math.max(summary.totalTokens, 1)
+    const cacheShare = summary.totalTokens
+        ? summary.sessions.reduce((s, r) => s + r.cacheReadRatio * r.totalTokens, 0) / summary.totalTokens
         : 0;
+    const share = Math.round(summary.catchableShare * 100);
     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(row(paint(on, C.bold + C.magenta, 'AGENTGUARD') + '  ' + paint(on, C.dim, 'replay · your agent history, before enforcement')));
     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.`)));
+    // Hero: the one number. Rendered huge.
+    out.push(row(''));
+    for (const line of blockDigits(`${share}%`))
+        out.push(row('  ' + paint(on, C.bold + C.green, line)));
+    out.push(row(''));
+    out.push(row('  ' + paint(on, C.bold, 'of everything you burned came after a point it would have blocked')));
+    out.push(row(''));
+    // Three supporting numbers, card-style.
+    const cards = [
+        { n: (0, evaluate_1.fmt)(summary.totalTokens), l: 'observed', c: C.white },
+        { n: (0, evaluate_1.fmt)(summary.catchableTail), l: 'after STOP', c: C.red },
+        { n: `$${Math.round(scenarioUsd(summary.catchableTail, cacheShare)).toLocaleString()}`, l: 'API-list, scenario', c: C.yellow },
+    ];
+    const COL = 20;
+    out.push(row('  ' + cards.map((k) => paint(on, C.bold + k.c, k.n.padEnd(COL))).join('')));
+    out.push(row('  ' + cards.map((k) => paint(on, C.dim, k.l.padEnd(COL))).join('')));
+    const comp = comparison(summary.catchableTail);
+    if (comp)
+        out.push(row('  ' + paint(on, C.dim, comp)));
     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(row(`${paint(on, C.bold + C.red, `${summary.stops} STOP`)}   ${paint(on, C.bold + C.yellow, `${summary.warns} WARN`)}   ${paint(on, C.bold + C.green, `${summary.clean} clean`)}` +
+        paint(on, C.dim, `   across ${summary.sessions.length} sessions, ${summary.totalSpawns} spawns`)));
     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))}`));
-        }
+        const tag = s.fanoutStop ? paint(on, C.red, 'FAN-OUT STOP') : s.sustainedStop ? paint(on, C.red, 'SUSTAINED STOP') : s.firstWarn ? paint(on, C.yellow, 'WARN') : paint(on, C.green, 'clean');
+        out.push(row(`${sparkline(s.curve, s.stopAtIndex, on)}  ${tag}`));
+        const detail = s.fanoutStop
+            ? `before spawn ${s.fanoutStop.atSpawn}, tail ${(0, evaluate_1.fmt)(s.catchableTail)}`
+            : s.sustainedStop
+                ? `near ${(0, evaluate_1.fmt)(s.sustainedStop.tokensAtStop)}, tail ${(0, evaluate_1.fmt)(s.catchableTail)}`
+                : `${(0, evaluate_1.fmt)(s.totalTokens)} · ${s.spawns} spawns`;
+        out.push(row(paint(on, C.dim, `${s.sessionId.slice(0, 8)}  ${(0, evaluate_1.fmt)(s.totalTokens).padStart(6)} · ${String(s.spawns).padStart(3)} spawns   ${detail}`)));
     }
     if (summary.sessions.length > top) {
-        out.push(line(colour(on, C.dim, `… ${summary.sessions.length - top} more sessions below the warning line`)));
+        out.push(row(paint(on, C.dim, `… ${summary.sessions.length - top} more, all clean`)));
     }
     out.push(MID);
-    out.push(line(colour(on, C.cyan, 'Next: agentguard-burn init   (shadow mode; blocks nothing yet)')));
+    out.push(row(paint(on, C.dim, 'Upper bound; assumes no override or restart. Nothing left this machine.')));
+    out.push(row(paint(on, C.cyan, 'next  agentguard-burn init') + paint(on, C.dim, '   shadow mode; blocks nothing until you say so')));
     out.push(BOT);
     return out.join('\n');
 }
+// ---------------------------------------------------------------------------
+// The mid-session STOP box. What Claude shows the user when a spawn is denied.
+// ---------------------------------------------------------------------------
+function renderStop(report, opts = {}) {
+    const on = opts.colour ?? false;
+    const lead = report.findings.find((f) => f.verdict === 'STOP')?.summary ?? 'Fan-out ceiling reached.';
+    const w = 64;
+    const bar = '━'.repeat(w);
+    const title = opts.subject === 'call' ? '  model call blocked' : '  agent spawn blocked';
+    const lines = [];
+    lines.push(paint(on, C.red, `┏${bar}┓`));
+    lines.push(paint(on, C.red, '┃ ') + paint(on, C.bold + C.bgRed + C.white, ' AGENTGUARD STOP ') + paint(on, C.bold, title) + paint(on, C.red, ' '.repeat(w - 19 - title.length) + '┃'));
+    lines.push(paint(on, C.red, `┣${bar}┫`));
+    lines.push(paint(on, C.red, '┃ ') + lead.padEnd(w - 1).slice(0, w - 1) + paint(on, C.red, '┃'));
+    lines.push(paint(on, C.red, '┃ ') + paint(on, C.dim, `${(0, evaluate_1.fmt)(report.totals.tokens)} tokens · ${report.totals.spawns} spawns · depth ${report.totals.maxDepth}`.padEnd(w - 1)) + paint(on, C.red, '┃'));
+    lines.push(paint(on, C.red, `┣${bar}┫`));
+    lines.push(paint(on, C.red, '┃ ') + paint(on, C.bold, 'DO NOW'.padEnd(w - 1)) + paint(on, C.red, '┃'));
+    report.prescriptions.slice(0, 3).forEach((p, i) => {
+        const wrapped = wrap(`${i + 1}. ${p}`, w - 2, '   ');
+        for (const line of wrapped) {
+            lines.push(paint(on, C.red, '┃ ') + line.padEnd(w - 1) + paint(on, C.red, '┃'));
+        }
+    });
+    lines.push(paint(on, C.red, `┣${bar}┫`));
+    lines.push(paint(on, C.red, '┃ ') + paint(on, C.dim, 'override once:  agentguard-burn resume --once --reason "..."'.padEnd(w - 1)) + paint(on, C.red, '┃'));
+    lines.push(paint(on, C.red, `┗${bar}┛`));
+    return lines.join('\n');
+}
+/** Word-aware wrap. Continuation lines are indented. */
+function wrap(text, width, indent) {
+    const words = text.split(' ');
+    const lines = [];
+    let current = '';
+    for (const word of words) {
+        const prefix = lines.length ? indent : '';
+        if ((current + ' ' + word).trim().length + prefix.length > width && current) {
+            lines.push((lines.length ? indent : '') + current);
+            current = word;
+        }
+        else {
+            current = current ? `${current} ${word}` : word;
+        }
+    }
+    if (current)
+        lines.push((lines.length ? indent : '') + current);
+    return lines;
+}
 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

@@ -37,6 +37,10 @@ export interface SessionReplay {
         tokensAt: number;
         spawnsAt: number;
     } | null;
+    /** Cumulative tokens sampled over active time, for a sparkline. 0..1 normalised. */
+    curve: number[];
+    /** Index into curve where the earliest STOP fired, or null. */
+    stopAtIndex: number | null;
 }
 export declare function discoverTranscripts(root?: string): string[];
 export declare function replaySession(path: string, thresholds: Thresholds): SessionReplay | null;

package/dist/src/replay/simulate.js

@@ -60,6 +60,9 @@ function replayEvents(sessionId, path, events, thresholds) {
     let sustainedStop = null;
     let firstWarn = null;
     let tokensAtEarliestStop = null;
+    // Cumulative tokens after every event, for the sparkline.
+    const timeline = [];
+    let stopEventIndex = 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.
@@ -80,6 +83,7 @@ function replayEvents(sessionId, path, events, thresholds) {
             }
             if ((fanoutStop || sustainedStop) && tokensAtEarliestStop === null) {
                 tokensAtEarliestStop = state.totalTokens;
+                stopEventIndex = timeline.length;
             }
         }
         // The sustained plane also has a boundary at every tool call, not just
@@ -92,12 +96,16 @@ function replayEvents(sessionId, path, events, thresholds) {
             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)
+                if (tokensAtEarliestStop === null) {
                     tokensAtEarliestStop = state.totalTokens;
+                    stopEventIndex = timeline.length;
+                }
             }
         }
         (0, session_1.applyEvent)(state, event);
+        timeline.push(state.totalTokens);
     }
+    const { curve, stopAtIndex } = downsample(timeline, stopEventIndex, 32);
     const final = (0, evaluate_1.evaluate)(state, thresholds, null);
     return {
         sessionId,
@@ -112,8 +120,23 @@ function replayEvents(sessionId, path, events, thresholds) {
         sustainedStop,
         catchableTail: tokensAtEarliestStop === null ? 0 : Math.max(0, state.totalTokens - tokensAtEarliestStop),
         firstWarn,
+        curve,
+        stopAtIndex,
     };
 }
+/** Compress a cumulative timeline into N normalised buckets, carrying the stop index across. */
+function downsample(timeline, stopIndex, buckets) {
+    if (timeline.length === 0)
+        return { curve: [], stopAtIndex: null };
+    const max = timeline[timeline.length - 1] || 1;
+    const curve = [];
+    for (let b = 0; b < buckets; b++) {
+        const i = Math.min(timeline.length - 1, Math.floor(((b + 1) / buckets) * timeline.length) - 1);
+        curve.push(Math.max(0, timeline[Math.max(0, i)]) / max);
+    }
+    const stopAtIndex = stopIndex === null ? null : Math.min(buckets - 1, Math.floor((stopIndex / timeline.length) * buckets));
+    return { curve, stopAtIndex };
+}
 function replayAll(paths, thresholds, minTokens = 0) {
     const sessions = [];
     for (const path of paths) {

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 {};