@agentguard-run/burn 0.1.1 → 0.2.1

package/dist/src/gateway.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The gateway: one transaction boundary for every host.
+ *
+ * Adapters do not evaluate policy. They translate what they can see into
+ * AgentEvents and hand them here. The gateway folds events into per-session
+ * state, evaluates the same detectors the Claude hook uses, and returns a
+ * decision. Cursor, Codex, the Ollama proxy and raw middleware therefore
+ * cannot drift from each other, because there is nothing host-specific left
+ * to drift.
+ *
+ * Three properties are load-bearing:
+ *
+ *   1. A spawn is admitted inside the same machine-wide lock the Claude hook
+ *      uses, as one transaction: fold, evaluate, reserve, sign. Ten parallel
+ *      Cursor hooks racing a cap of 40 admit exactly 40, for exactly the
+ *      reason ten Claude hooks do.
+ *
+ *   2. Usage is committed by call ID and *replaces* what was reserved under
+ *      it. When middleware estimated 120K and the proxy later saw 87K for the
+ *      same call, the session moves by 87K, not 207K. Double counting is the
+ *      easiest way to make a cross-tool product lie, and it is ruled out here
+ *      rather than in every adapter.
+ *
+ *   3. A STOP blocks the next expansion. It never truncates a request that is
+ *      already streaming and never kills a running agent. Blocking is not
+ *      killing, and the product does not pretend otherwise.
+ *
+ * Persisted state is content-free: counts, digests, verdicts.
+ */
+import { type AgentEvent, type Attribution, type CallRequested, type Coverage, type HostCapabilities, type HostId, type SpawnRequested } from './events';
+import { type SignedReceipt } from './receipt';
+import { type ComputeSnapshot } from './state/reservations';
+import type { BurnReport, Mode, SessionState, Verdict } from './types';
+export interface Decision {
+    decisionId: string;
+    action: 'spawn' | 'model_call';
+    verdict: Verdict;
+    /** The policy would block this if enforcing. */
+    wouldBlock: boolean;
+    /** Enforcing, and blocking. */
+    blocked: boolean;
+    /** A block was due and the user's recorded override let it through. */
+    overridden: {
+        once: boolean;
+        reason: string;
+    } | null;
+    /** The finding set changed since the user was last told. Adapters speak only when true. */
+    notify: boolean;
+    mode: Mode;
+    report: BurnReport;
+    capabilities: HostCapabilities;
+    effectiveSpawns: number;
+    /** Depth the child would have. Null for model calls. */
+    proposedDepth: number | null;
+    compute: ComputeSnapshot | null;
+    receipt: SignedReceipt | null;
+    /** Set when the decision was forced by an infrastructure failure. */
+    failedClosed?: string;
+}
+export interface UsageCoverage {
+    authoritative: number;
+    estimated: number;
+    missing: number;
+}
+export interface GatewaySessionView {
+    sessionId: string;
+    hosts: HostId[];
+    capabilities: HostCapabilities;
+    state: SessionState;
+    liveSpawns: number;
+    usage: UsageCoverage;
+    decisions: number;
+    wouldBlock: number;
+    closedAt: number | null;
+}
+export interface GatewayOptions {
+    /** Sign receipts. On by default; off keeps tests and hot paths key-free. */
+    sign?: boolean;
+    now?: () => number;
+}
+export declare class Gateway {
+    private readonly home;
+    private readonly store;
+    private readonly signer;
+    private readonly now;
+    private readonly sessionsDir;
+    constructor(home: string, opts?: GatewayOptions);
+    private file;
+    private load;
+    private save;
+    /**
+     * Fold observations. Never decides, never blocks. Idempotent per eventId,
+     * so a retried hook or a replayed transcript line is a no-op.
+     */
+    observe(events: AgentEvent[]): void;
+    private fold;
+    /**
+     * Replace-not-add by call ID. An estimate reserved by middleware is
+     * superseded by the proxy's authoritative count for the same call, up or
+     * down. Without a call ID the usage is simply added.
+     */
+    private applyUsage;
+    private commitUsage;
+    /**
+     * Admit or deny a spawn. One transaction under the machine lock: fold,
+     * evaluate the proposal, reserve, sign.
+     */
+    beforeSpawn(event: SpawnRequested): Decision;
+    /**
+     * Admit or deny a model call. Reserves the caller's estimate under callId;
+     * completion replaces it. The local-compute plane is evaluated here and
+     * only here, because only calls occupy the machine.
+     */
+    beforeCall(event: CallRequested): Decision;
+    /** Real usage for a reserved call. Replaces the estimate; releases the slot. */
+    completeCall(args: {
+        host: HostId;
+        sessionId: string;
+        callId: string;
+        tokens: number;
+        cacheRead?: number;
+        usageCoverage: Coverage;
+        at?: number;
+    }): void;
+    /** The call never produced usage. Releases the estimate and the slot. */
+    failCall(args: {
+        host: HostId;
+        sessionId: string;
+        callId: string;
+        at?: number;
+    }): void;
+    private finish;
+    private failClosed;
+    peek(sessionId: string): GatewaySessionView | null;
+    /** Every gateway session on this machine, newest activity first. */
+    sessions(): GatewaySessionView[];
+    compute(sessionId?: string): ComputeSnapshot;
+}
+/** A session fed by several hosts sees the best coverage any of them provides. */
+export declare function mergeCapabilities(hosts: HostId[]): HostCapabilities;
+export type { Attribution };

package/dist/src/gateway.js

@@ -0,0 +1,536 @@
+"use strict";
+/**
+ * The gateway: one transaction boundary for every host.
+ *
+ * Adapters do not evaluate policy. They translate what they can see into
+ * AgentEvents and hand them here. The gateway folds events into per-session
+ * state, evaluates the same detectors the Claude hook uses, and returns a
+ * decision. Cursor, Codex, the Ollama proxy and raw middleware therefore
+ * cannot drift from each other, because there is nothing host-specific left
+ * to drift.
+ *
+ * Three properties are load-bearing:
+ *
+ *   1. A spawn is admitted inside the same machine-wide lock the Claude hook
+ *      uses, as one transaction: fold, evaluate, reserve, sign. Ten parallel
+ *      Cursor hooks racing a cap of 40 admit exactly 40, for exactly the
+ *      reason ten Claude hooks do.
+ *
+ *   2. Usage is committed by call ID and *replaces* what was reserved under
+ *      it. When middleware estimated 120K and the proxy later saw 87K for the
+ *      same call, the session moves by 87K, not 207K. Double counting is the
+ *      easiest way to make a cross-tool product lie, and it is ruled out here
+ *      rather than in every adapter.
+ *
+ *   3. A STOP blocks the next expansion. It never truncates a request that is
+ *      already streaming and never kills a running agent. Blocking is not
+ *      killing, and the product does not pretend otherwise.
+ *
+ * Persisted state is content-free: counts, digests, verdicts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Gateway = void 0;
+exports.mergeCapabilities = mergeCapabilities;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const defaults_1 = require("./defaults");
+const evaluate_1 = require("./detectors/evaluate");
+const local_compute_1 = require("./detectors/local-compute");
+const events_1 = require("./events");
+const pre_tool_use_1 = require("./hook/pre-tool-use");
+const override_1 = require("./override");
+const receipt_1 = require("./receipt");
+const reservations_1 = require("./state/reservations");
+const session_1 = require("./state/session");
+const MAX_SEEN_EVENTS = 4000;
+const FILE_PREFIX = 'gw-';
+function safeName(sessionId) {
+    return sessionId.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 120) + '-' + (0, receipt_1.sha256)(sessionId).slice(0, 8);
+}
+class Gateway {
+    home;
+    store;
+    signer;
+    now;
+    sessionsDir;
+    constructor(home, opts = {}) {
+        this.home = home;
+        this.sessionsDir = (0, node_path_1.join)(home, 'sessions');
+        (0, node_fs_1.mkdirSync)(this.sessionsDir, { recursive: true, mode: 0o700 });
+        this.store = new reservations_1.ReservationStore(home);
+        this.signer = opts.sign === false ? null : receipt_1.ReceiptSigner.loadOrCreate(home);
+        this.now = opts.now ?? (() => Date.now());
+    }
+    // ---- persistence ----------------------------------------------------
+    file(sessionId) {
+        return (0, node_path_1.join)(this.sessionsDir, `${FILE_PREFIX}${safeName(sessionId)}.json`);
+    }
+    load(sessionId, host, at) {
+        try {
+            const raw = JSON.parse((0, node_fs_1.readFileSync)(this.file(sessionId), 'utf8'));
+            const state = inflate(raw.state);
+            if (!raw.hosts.includes(host)) {
+                raw.hosts.push(host);
+                raw.capabilities = mergeCapabilities(raw.hosts);
+            }
+            return { state, meta: raw };
+        }
+        catch {
+            const state = (0, session_1.newSessionState)(sessionId, at);
+            return {
+                state,
+                meta: {
+                    hosts: [host],
+                    capabilities: events_1.CAPABILITIES[host],
+                    state: serialise(state),
+                    calls: [],
+                    liveSpawns: [],
+                    seenEvents: [],
+                    usage: { authoritative: 0, estimated: 0, missing: 0 },
+                    decisions: 0,
+                    wouldBlock: 0,
+                    lastReceipt: null,
+                    closedAt: null,
+                },
+            };
+        }
+    }
+    save(meta, state) {
+        // Only ever called inside a store transaction. If our lock instance was
+        // reclaimed while we worked, this throws and nothing is written.
+        this.store.assertHeld();
+        meta.state = serialise(state);
+        if (meta.seenEvents.length > MAX_SEEN_EVENTS)
+            meta.seenEvents = meta.seenEvents.slice(-MAX_SEEN_EVENTS);
+        const file = this.file(state.sessionId);
+        const tmp = `${file}.${process.pid}.tmp`;
+        (0, node_fs_1.writeFileSync)(tmp, JSON.stringify(meta), { mode: 0o600 });
+        (0, node_fs_1.renameSync)(tmp, file);
+    }
+    // ---- observations ---------------------------------------------------
+    /**
+     * Fold observations. Never decides, never blocks. Idempotent per eventId,
+     * so a retried hook or a replayed transcript line is a no-op.
+     */
+    observe(events) {
+        if (events.length === 0)
+            return;
+        this.store.withLock((tx) => {
+            // Group by session so each session file is written once.
+            const bySession = new Map();
+            for (const e of events) {
+                const list = bySession.get(e.sessionId) ?? [];
+                list.push(e);
+                bySession.set(e.sessionId, list);
+            }
+            for (const [sessionId, list] of bySession) {
+                const first = list[0];
+                const { state, meta } = this.load(sessionId, first.host, first.at);
+                for (const event of list)
+                    this.fold(event, state, meta, tx);
+                this.save(meta, state);
+            }
+        });
+    }
+    fold(event, state, meta, tx) {
+        if (meta.seenEvents.includes(event.eventId))
+            return;
+        meta.seenEvents.push(event.eventId);
+        const calls = new Map(meta.calls);
+        const live = new Map(meta.liveSpawns);
+        switch (event.kind) {
+            case 'session_opened':
+                meta.closedAt = null;
+                break;
+            case 'session_closed':
+                meta.closedAt = event.at;
+                break;
+            case 'model_usage': {
+                this.commitUsage(event, state, meta, calls);
+                if (event.callId)
+                    tx.finishCall(event.callId, windowMs(), event.at);
+                break;
+            }
+            case 'surface_read':
+                (0, session_1.applyEvent)(state, burnEvent(event.at, { surfaces: [event.surfaceDigest] }));
+                break;
+            case 'spawn_started': {
+                live.set(event.spawnId, event.depth);
+                const before = state.spawnCount;
+                (0, session_1.applyEvent)(state, burnEvent(event.at, { spawns: [{ description: '', issuerDepth: Math.max(0, event.depth - 1) }] }));
+                // The spawn is now observed; its reservation has done its job.
+                tx.reconcile(event.sessionId, state.spawnCount, before);
+                break;
+            }
+            case 'spawn_finished':
+                live.delete(event.spawnId);
+                break;
+            case 'spawn_requested':
+            case 'call_requested':
+                // Decisions go through beforeSpawn / beforeCall. Folding one here
+                // would count it without admitting it.
+                break;
+        }
+        meta.calls = [...calls];
+        meta.liveSpawns = [...live];
+    }
+    /**
+     * Replace-not-add by call ID. An estimate reserved by middleware is
+     * superseded by the proxy's authoritative count for the same call, up or
+     * down. Without a call ID the usage is simply added.
+     */
+    applyUsage(callId, tokens, cacheRead, at, state, calls) {
+        const previous = callId ? calls.get(callId) : undefined;
+        if (callId)
+            calls.set(callId, { tokens, cacheRead });
+        if (!previous) {
+            (0, session_1.applyEvent)(state, burnEvent(at, { tokens, cacheRead }));
+            return;
+        }
+        // Keep active-time accounting honest: the correction is not new activity.
+        (0, session_1.applyEvent)(state, burnEvent(at, {}));
+        (0, session_1.applyCorrection)(state, tokens - previous.tokens, cacheRead - previous.cacheRead);
+    }
+    commitUsage(event, state, meta, calls) {
+        this.applyUsage(event.callId, event.tokens, event.cacheRead, event.at, state, calls);
+        meta.usage[event.usageCoverage] += 1;
+    }
+    // ---- decisions ------------------------------------------------------
+    /**
+     * Admit or deny a spawn. One transaction under the machine lock: fold,
+     * evaluate the proposal, reserve, sign.
+     */
+    beforeSpawn(event) {
+        const policy = (0, pre_tool_use_1.loadPolicy)(this.home);
+        try {
+            return this.store.withLock((tx) => {
+                const { state, meta } = this.load(event.sessionId, event.host, event.at);
+                if (meta.seenEvents.includes(event.eventId)) {
+                    // Same request evaluated twice (host retry). Re-evaluate without
+                    // reserving again; the store is idempotent on spawnId anyway.
+                }
+                else {
+                    meta.seenEvents.push(event.eventId);
+                }
+                const live = new Map(meta.liveSpawns);
+                const proposedDepth = event.proposedDepth ?? (event.issuerId !== undefined && live.has(event.issuerId) ? live.get(event.issuerId) + 1 : 1);
+                const report = (0, evaluate_1.evaluate)(state, policy.thresholds, proposedDepth);
+                const reservation = tx.reserve({
+                    sessionId: event.sessionId,
+                    toolUseId: event.spawnId,
+                    observedSpawns: state.spawnCount,
+                    ceiling: policy.thresholds.fanout.stop,
+                    now: event.at,
+                });
+                const wouldBlock = report.verdict === 'STOP' || !reservation.allowed;
+                const verdict = wouldBlock ? 'STOP' : report.verdict;
+                // Session-scope STOPs need a session we trust. Fan-out is session scope.
+                const due = wouldBlock && policy.mode === 'enforce' && event.attribution === 'high';
+                const override = due ? (0, override_1.consumeOverride)(this.home, event.at) : null;
+                const decision = this.finish({ action: 'spawn', host: event.host, sessionId: event.sessionId, at: event.at, proposedDepth, verdict, wouldBlock, blocked: due && !override, override, report, effectiveSpawns: reservation.effectiveSpawns, compute: null }, policy, meta, state);
+                this.save(meta, state);
+                return decision;
+            });
+        }
+        catch (error) {
+            return this.failClosed('spawn', event, policy, error);
+        }
+    }
+    /**
+     * Admit or deny a model call. Reserves the caller's estimate under callId;
+     * completion replaces it. The local-compute plane is evaluated here and
+     * only here, because only calls occupy the machine.
+     */
+    beforeCall(event) {
+        const policy = (0, pre_tool_use_1.loadPolicy)(this.home);
+        try {
+            return this.store.withLock((tx) => {
+                const { state, meta } = this.load(event.sessionId, event.host, event.at);
+                if (!meta.seenEvents.includes(event.eventId))
+                    meta.seenEvents.push(event.eventId);
+                const calls = new Map(meta.calls);
+                const compute = tx.reserveCall({
+                    sessionId: event.sessionId,
+                    callId: event.callId,
+                    host: event.host,
+                    estimatedTokens: event.estimatedTokens,
+                    ttlMs: defaults_1.CALL_RESERVATION_TTL_MS,
+                    windowMs: windowMs(policy),
+                    now: event.at,
+                });
+                // The estimate counts toward the session until the real number lands.
+                // It is a reservation, not an observation, so coverage is untouched.
+                if (event.estimatedTokens > 0 && !calls.has(event.callId)) {
+                    this.applyUsage(event.callId, event.estimatedTokens, 0, event.at, state, calls);
+                }
+                meta.calls = [...calls];
+                const session = (0, evaluate_1.evaluate)(state, policy.thresholds, null);
+                const local = (0, local_compute_1.evaluateLocalCompute)(compute, policy.thresholds);
+                const report = merge(session, local.findings);
+                const wouldBlock = report.verdict === 'STOP';
+                // A low-confidence session (proxy without a session header) can be
+                // stopped only on machine-scope grounds. Its session count is a guess.
+                const machineStop = local.verdict === 'STOP';
+                const due = wouldBlock && policy.mode === 'enforce' && (event.attribution === 'high' || machineStop);
+                const override = due ? (0, override_1.consumeOverride)(this.home, event.at) : null;
+                const blocked = due && !override;
+                const decision = this.finish({ action: 'model_call', host: event.host, sessionId: event.sessionId, at: event.at, proposedDepth: null, verdict: report.verdict, wouldBlock, blocked, override, report, effectiveSpawns: state.spawnCount, compute }, policy, meta, state);
+                if (blocked) {
+                    // A denied call neither occupies the machine nor spends tokens.
+                    tx.finishCall(event.callId, windowMs(policy), event.at);
+                    const released = new Map(meta.calls);
+                    this.applyUsage(event.callId, 0, 0, event.at, state, released);
+                    meta.calls = [...released];
+                }
+                this.save(meta, state);
+                return decision;
+            });
+        }
+        catch (error) {
+            return this.failClosed('model_call', event, policy, error);
+        }
+    }
+    /** Real usage for a reserved call. Replaces the estimate; releases the slot. */
+    completeCall(args) {
+        this.observe([
+            {
+                schemaVersion: 1,
+                kind: 'model_usage',
+                // Per host: middleware and the proxy may both complete one call, and
+                // the later authoritative figure supersedes by callId.
+                eventId: `complete-${args.host}-${args.callId}`,
+                host: args.host,
+                sessionId: args.sessionId,
+                at: args.at ?? this.now(),
+                tokens: Math.max(0, args.tokens),
+                cacheRead: Math.max(0, args.cacheRead ?? 0),
+                usageCoverage: args.usageCoverage,
+                callId: args.callId,
+            },
+        ]);
+    }
+    /** The call never produced usage. Releases the estimate and the slot. */
+    failCall(args) {
+        this.observe([
+            {
+                schemaVersion: 1,
+                kind: 'model_usage',
+                eventId: `fail-${args.host}-${args.callId}`,
+                host: args.host,
+                sessionId: args.sessionId,
+                at: args.at ?? this.now(),
+                tokens: 0,
+                cacheRead: 0,
+                usageCoverage: 'missing',
+                callId: args.callId,
+            },
+        ]);
+    }
+    finish(d, policy, meta, state) {
+        meta.decisions += 1;
+        if (d.wouldBlock)
+            meta.wouldBlock += 1;
+        const decisionId = (0, events_1.eventId)();
+        // Speak once per change, not once per spawn. A block or an override is
+        // always spoken; it is the event the user needs to see.
+        const signature = d.verdict === 'OK' ? '' : (0, pre_tool_use_1.findingSignature)(d.report);
+        const notify = d.blocked || d.override !== null || (signature !== '' && signature !== (meta.notified ?? ''));
+        meta.notified = signature;
+        // Sign what matters: every spawn admission, and any call that is not OK.
+        // Signing every OK call through a busy proxy would be thousands of
+        // receipts an hour saying nothing.
+        let receipt = null;
+        if (this.signer && (d.action === 'spawn' || d.verdict !== 'OK')) {
+            const payload = {
+                schema: 'agentguard.burn.decision.v1',
+                decisionId,
+                at: d.at,
+                host: d.host,
+                sessionDigest: (0, receipt_1.sha256)(d.sessionId),
+                action: d.action,
+                policy: { mode: policy.mode, digest: (0, receipt_1.sha256)((0, receipt_1.canonical)(policy)) },
+                measured: {
+                    sessionTokens: state.totalTokens,
+                    sessionSpawns: d.effectiveSpawns,
+                    proposedDepth: d.proposedDepth,
+                    inFlight: d.compute?.inFlight ?? 0,
+                    occupiedMs: d.compute?.occupiedMs ?? 0,
+                },
+                coverage: meta.capabilities,
+                verdict: d.verdict,
+                blocked: d.blocked,
+                reasons: d.report.findings.map((f) => `${f.detector}:${f.verdict}`),
+                previous: meta.lastReceipt,
+            };
+            receipt = this.signer.sign(payload);
+            meta.lastReceipt = (0, receipt_1.receiptDigest)(receipt);
+            (0, node_fs_1.appendFileSync)((0, node_path_1.join)(this.home, 'receipts.ndjson'), `${JSON.stringify(receipt)}\n`, { mode: 0o600 });
+        }
+        // Same ledger the Claude hook writes, so `status` and shadow eligibility
+        // count every host.
+        (0, node_fs_1.appendFileSync)((0, node_path_1.join)(this.home, 'decisions.ndjson'), `${JSON.stringify({
+            at: d.at,
+            host: d.host,
+            action: d.action,
+            sessionId: d.sessionId,
+            verdict: d.verdict,
+            wouldDeny: d.wouldBlock,
+            enforced: d.blocked,
+            overridden: d.override ?? undefined,
+            mode: policy.mode,
+            findings: d.report.findings.map((f) => ({ detector: f.detector, verdict: f.verdict, observed: f.observed, threshold: f.threshold })),
+            effectiveSpawns: d.effectiveSpawns,
+            totals: d.report.totals,
+            compute: d.compute,
+            coverage: meta.capabilities,
+        })}\n`, { mode: 0o600 });
+        return {
+            decisionId,
+            action: d.action,
+            verdict: d.verdict,
+            wouldBlock: d.wouldBlock,
+            blocked: d.blocked,
+            overridden: d.override,
+            notify,
+            mode: policy.mode,
+            report: d.report,
+            capabilities: meta.capabilities,
+            effectiveSpawns: d.effectiveSpawns,
+            proposedDepth: d.proposedDepth,
+            compute: d.compute,
+            receipt,
+        };
+    }
+    failClosed(action, event, policy, error) {
+        const reason = `AgentGuard failed closed: ${error instanceof Error ? error.message : 'unknown error'}`;
+        (0, node_fs_1.mkdirSync)(this.home, { recursive: true, mode: 0o700 });
+        (0, node_fs_1.appendFileSync)((0, node_path_1.join)(this.home, 'decisions.ndjson'), `${JSON.stringify({ at: event.at, host: event.host, action, sessionId: event.sessionId, verdict: 'STOP', wouldDeny: true, enforced: policy.mode === 'enforce', mode: policy.mode, reason, failClosed: true })}\n`, { mode: 0o600 });
+        const report = {
+            sessionId: event.sessionId,
+            verdict: 'STOP',
+            findings: [{ detector: action === 'spawn' ? 'fanout' : 'local_compute', verdict: 'STOP', summary: reason, observed: 0, threshold: 0 }],
+            prescriptions: ['Another AgentGuard process holds the lock and is not releasing it. Check for a stuck hook, then retry.'],
+            cacheReadRatio: 0,
+            totals: { tokens: 0, spawns: 0, maxDepth: 0, activeMinutes: 0 },
+        };
+        return {
+            decisionId: (0, events_1.eventId)(),
+            action,
+            verdict: 'STOP',
+            wouldBlock: true,
+            blocked: policy.mode === 'enforce',
+            overridden: null,
+            notify: true,
+            mode: policy.mode,
+            report,
+            capabilities: events_1.CAPABILITIES[event.host],
+            effectiveSpawns: 0,
+            proposedDepth: event.kind === 'spawn_requested' ? event.proposedDepth ?? 1 : null,
+            compute: null,
+            receipt: null,
+            failedClosed: reason,
+        };
+    }
+    // ---- read side ------------------------------------------------------
+    peek(sessionId) {
+        try {
+            const raw = JSON.parse((0, node_fs_1.readFileSync)(this.file(sessionId), 'utf8'));
+            return view(sessionId, raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Every gateway session on this machine, newest activity first. */
+    sessions() {
+        const out = [];
+        let names = [];
+        try {
+            names = (0, node_fs_1.readdirSync)(this.sessionsDir).filter((n) => n.startsWith(FILE_PREFIX) && n.endsWith('.json'));
+        }
+        catch {
+            return out;
+        }
+        for (const name of names) {
+            try {
+                const raw = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(this.sessionsDir, name), 'utf8'));
+                out.push(view(raw.state.sessionId, raw));
+            }
+            catch {
+                /* half-written or foreign file: skip */
+            }
+        }
+        return out.sort((a, b) => b.state.lastEventAt - a.state.lastEventAt);
+    }
+    compute(sessionId = '') {
+        return this.store.computeSnapshot(sessionId, windowMs((0, pre_tool_use_1.loadPolicy)(this.home)), this.now());
+    }
+}
+exports.Gateway = Gateway;
+// ---- helpers ------------------------------------------------------------
+function windowMs(policy) {
+    return policy?.thresholds.localCompute?.windowMs ?? defaults_1.DEFAULT_LOCAL_COMPUTE.windowMs;
+}
+function burnEvent(at, partial) {
+    return { at, tokens: 0, cacheRead: 0, spawns: [], surfaces: [], sidechain: false, ...partial };
+}
+const RANK = { OK: 0, WARN: 1, STOP: 2 };
+function merge(report, extra) {
+    if (extra.length === 0)
+        return report;
+    const findings = [...report.findings, ...extra];
+    let verdict = report.verdict;
+    for (const f of extra)
+        if (RANK[f.verdict] > RANK[verdict])
+            verdict = f.verdict;
+    const prescriptions = [...report.prescriptions.filter((p) => p !== 'Nothing pathological. Carry on.')];
+    if (extra.some((f) => f.verdict === 'STOP'))
+        prescriptions.unshift('Let the model calls already in flight finish before admitting more work.');
+    else if (extra.length)
+        prescriptions.push('Queue model calls instead of firing them in parallel; the machine is shared by every agent on it.');
+    return { ...report, verdict, findings, prescriptions };
+}
+const COVERAGE_RANK = { missing: 0, estimated: 1, authoritative: 2 };
+/** A session fed by several hosts sees the best coverage any of them provides. */
+function mergeCapabilities(hosts) {
+    const best = (k) => hosts.map((h) => events_1.CAPABILITIES[h][k]).reduce((a, b) => (COVERAGE_RANK[b] > COVERAGE_RANK[a] ? b : a), 'missing');
+    return { spawns: best('spawns'), depth: best('depth'), usage: best('usage') };
+}
+function serialise(state) {
+    return {
+        sessionId: state.sessionId,
+        startedAt: state.startedAt,
+        lastEventAt: state.lastEventAt,
+        totalTokens: state.totalTokens,
+        totalCacheRead: state.totalCacheRead,
+        spawnCount: state.spawnCount,
+        maxDepth: state.maxDepth,
+        activeMinutes: state.activeMinutes,
+        tokensByActiveMinute: [...state.tokensByActiveMinute],
+        spawnsByActiveMinute: [...state.spawnsByActiveMinute],
+        surfaceReaders: [...state.surfaceReaders].map(([k, v]) => [k, [...v]]),
+        burnDebt: state.burnDebt,
+        lastDebtEventAt: state.lastDebtEventAt,
+    };
+}
+function inflate(s) {
+    return {
+        ...s,
+        tokensByActiveMinute: new Map(s.tokensByActiveMinute),
+        spawnsByActiveMinute: new Map(s.spawnsByActiveMinute),
+        surfaceReaders: new Map(s.surfaceReaders.map(([k, v]) => [k, new Set(v)])),
+    };
+}
+function view(sessionId, raw) {
+    return {
+        sessionId,
+        hosts: raw.hosts,
+        capabilities: raw.capabilities,
+        state: inflate(raw.state),
+        liveSpawns: raw.liveSpawns.length,
+        usage: raw.usage,
+        decisions: raw.decisions,
+        wouldBlock: raw.wouldBlock,
+        closedAt: raw.closedAt,
+    };
+}