@agentguard-run/burn 0.1.1 → 0.2.1

package/dist/src/adapters/cursor.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * Cursor hooks adapter.
+ *
+ * Cursor exposes `subagentStart` as a native, prospective admission point and
+ * `subagentStop` for reconciliation. That is a stronger spawn signal than a
+ * transcript: the host names the subagent and its parent conversation. What
+ * Cursor never exposes is hosted-model token usage, so usage coverage for a
+ * pure Cursor session is `missing` and status says so.
+ *
+ * Verified against cursor.com/docs/agent/hooks (2026-09-03):
+ *   input   conversation_id, hook_event_name, subagent_id, subagent_type,
+ *           parent_conversation_id, tool_call_id, is_parallel_worker
+ *   output  { "permission": "allow" | "deny", "user_message", "agent_message" }
+ *   config  ~/.cursor/hooks.json  { version: 1, hooks: { subagentStart: [...] } }
+ *           "failClosed": true makes a crashed or timed-out hook deny.
+ *
+ * Cursor's own hooks can deny a subagent. The value here is not the deny; it
+ * is that the deny follows the same policy, writes the same receipt and
+ * shares the same machine-wide reservation as every other host.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleCursorHook = handleCursorHook;
+exports.cursorHooksSnippet = cursorHooksSnippet;
+const events_1 = require("../events");
+const render_1 = require("../replay/render");
+const HOST = 'cursor';
+/**
+ * Handle one hook invocation. Unknown events allow. Returns the object to
+ * print on stdout; the CLI wraps it. Never throws: Cursor treats invalid
+ * output as fail-open unless failClosed is set, so a crash here would be a
+ * silent allow with no receipt.
+ */
+function handleCursorHook(raw, gateway, now = Date.now()) {
+    const input = parse(raw);
+    if (!input)
+        return {};
+    const at = input.at ?? now;
+    if (input.event === 'subagentStart') {
+        const spawnId = input.subagentId ?? input.toolCallId ?? `${input.sessionId}:${at}`;
+        const decision = gateway.beforeSpawn({
+            schemaVersion: 1,
+            kind: 'spawn_requested',
+            eventId: `cursor:${spawnId}`,
+            host: HOST,
+            sessionId: input.sessionId,
+            at,
+            spawnId,
+            // If the issuing conversation is itself a subagent we admitted, the
+            // child sits one level below it. Otherwise it is a root child.
+            issuerId: input.parentConversationId,
+            attribution: 'high',
+        });
+        if (decision.blocked) {
+            return {
+                permission: 'deny',
+                user_message: (0, render_1.renderStop)(decision.report, { colour: false }),
+                agent_message: `AgentGuard STOP: ${decision.report.findings[0]?.summary ?? 'policy ceiling reached'} Do not start another subagent.`,
+            };
+        }
+        // Admitted: the subagent will run. Record it so depth and count are live.
+        // If the record cannot be taken (lock contention), the reservation simply
+        // stays pending until its TTL: the conservative direction. Never crash a
+        // hook after it has decided; a crash is a fail-open on most hosts.
+        const depth = decision.proposedDepth ?? 1;
+        quietly(() => gateway.observe([{ schemaVersion: 1, kind: 'spawn_started', eventId: `cursor:start:${spawnId}`, host: HOST, sessionId: input.sessionId, at, spawnId, depth }]));
+        if (decision.overridden) {
+            return { permission: 'allow', agent_message: `AgentGuard STOP overridden${decision.overridden.once ? ' once' : ''} ("${decision.overridden.reason}"): ${decision.report.findings[0]?.summary ?? ''}` };
+        }
+        if (decision.notify && decision.verdict !== 'OK') {
+            return {
+                permission: 'allow',
+                agent_message: `AgentGuard ${decision.verdict}${decision.mode === 'shadow' && decision.wouldBlock ? ' (shadow: would have blocked)' : ''}: ${decision.report.findings[0]?.summary ?? ''}`,
+            };
+        }
+        return { permission: 'allow' };
+    }
+    if (input.event === 'subagentStop') {
+        const spawnId = input.subagentId ?? input.toolCallId;
+        if (spawnId) {
+            quietly(() => gateway.observe([{ schemaVersion: 1, kind: 'spawn_finished', eventId: `cursor:stop:${spawnId}`, host: HOST, sessionId: input.sessionId, at, spawnId }]));
+        }
+        return {};
+    }
+    if (input.event === 'sessionEnd') {
+        quietly(() => gateway.observe([{ schemaVersion: 1, kind: 'session_closed', eventId: `cursor:end:${input.sessionId}:${at}`, host: HOST, sessionId: input.sessionId, at }]));
+        return {};
+    }
+    return {};
+}
+function quietly(fn) {
+    try {
+        fn();
+    }
+    catch (error) {
+        process.stderr.write(`agentguard-burn: could not record observation: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+}
+function parse(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const v = value;
+    const str = (...keys) => {
+        for (const k of keys) {
+            const x = v[k];
+            if (typeof x === 'string' && x.length > 0)
+                return x;
+        }
+        return undefined;
+    };
+    const name = (str('hook_event_name') ?? '').toLowerCase();
+    const event = name === 'subagentstart' ? 'subagentStart' : name === 'subagentstop' ? 'subagentStop' : name === 'sessionend' ? 'sessionEnd' : 'other';
+    const conversation = str('conversation_id');
+    const sessionId = conversation && (0, events_1.isValidSessionId)(conversation) ? conversation : 'cursor:unknown';
+    const ts = v.timestamp_ms ?? v.occurred_at_ms;
+    return {
+        event,
+        sessionId,
+        subagentId: str('subagent_id'),
+        parentConversationId: str('parent_conversation_id'),
+        toolCallId: str('tool_call_id'),
+        at: typeof ts === 'number' && Number.isFinite(ts) ? ts : undefined,
+    };
+}
+/** The ~/.cursor/hooks.json fragment. failClosed is on: a dead hook denies. */
+function cursorHooksSnippet(command) {
+    return {
+        version: 1,
+        hooks: {
+            subagentStart: [{ command, timeout: 5, failClosed: true }],
+            subagentStop: [{ command, timeout: 5 }],
+            sessionEnd: [{ command, timeout: 3 }],
+        },
+    };
+}

package/dist/src/adapters/raw-api.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Raw orchestrator middleware.
+ *
+ * The strongest position of the adapter shapes, because the orchestrator
+ * knows things no host exposes: stable spawn IDs, the parent of each child,
+ * and the request before it leaves the process. That is why this adapter is
+ * the one that makes the full "40 spawns, depth 2, 5B tokens" claim true for
+ * an open-weights agent. A proxy alone sees tokens and no tree; a hook alone
+ * sees the tree and no tokens; this sees both.
+ *
+ *   const burn = createRawApiGuard({ sessionId: 'nightly-refactor-17' });
+ *
+ *   const spawn = burn.beforeSpawn({ parentDepth: 0 });
+ *   spawn.throwIfBlocked();
+ *   spawn.started();
+ *   try { await worker() } finally { spawn.finished() }
+ *
+ *   const call = burn.beforeCall({ estimatedTokens: 120_000 });
+ *   call.throwIfBlocked();
+ *   try {
+ *     const res = await client.chat({ ..., headers: call.headers });
+ *     call.complete({ tokens: res.usage.total_tokens });
+ *   } catch (e) { call.fail(); throw e }
+ *
+ * A model call reserves an estimate and then commits the real number under
+ * the same call ID, so a proxy observing the same request (via call.headers)
+ * supersedes rather than duplicates it.
+ */
+import { Gateway, type Decision } from '../gateway';
+export declare class BurnStopError extends Error {
+    readonly decision: Decision;
+    constructor(decision: Decision);
+}
+export interface RawGuardOptions {
+    sessionId: string;
+    /** Defaults to $AGENTGUARD_HOME or ~/.agentguard. */
+    home?: string;
+    /** Skip receipt signing (tests, throwaway scripts). */
+    sign?: boolean;
+    now?: () => number;
+}
+export declare function createRawApiGuard(opts: RawGuardOptions): {
+    sessionId: string;
+    gateway: Gateway;
+    beforeSpawn(args?: {
+        parentDepth: number;
+        spawnId?: string;
+    }): {
+        spawnId: string;
+        depth: number;
+        decision: Decision;
+        readonly blocked: boolean;
+        throwIfBlocked(): void;
+        started(): void;
+        finished(): void;
+    };
+    beforeCall(args?: {
+        estimatedTokens?: number;
+        callId?: string;
+    }): {
+        callId: string;
+        decision: Decision;
+        /** Attach to the outbound request so a local proxy correlates it. */
+        headers: Record<string, string>;
+        readonly blocked: boolean;
+        throwIfBlocked(): void;
+        complete(usage: {
+            tokens: number;
+            cacheRead?: number;
+        }): void;
+        fail(): void;
+    };
+    /** Current state without deciding anything. */
+    status(): import("../gateway").GatewaySessionView | null;
+};
+export type RawApiGuard = ReturnType<typeof createRawApiGuard>;

package/dist/src/adapters/raw-api.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * Raw orchestrator middleware.
+ *
+ * The strongest position of the adapter shapes, because the orchestrator
+ * knows things no host exposes: stable spawn IDs, the parent of each child,
+ * and the request before it leaves the process. That is why this adapter is
+ * the one that makes the full "40 spawns, depth 2, 5B tokens" claim true for
+ * an open-weights agent. A proxy alone sees tokens and no tree; a hook alone
+ * sees the tree and no tokens; this sees both.
+ *
+ *   const burn = createRawApiGuard({ sessionId: 'nightly-refactor-17' });
+ *
+ *   const spawn = burn.beforeSpawn({ parentDepth: 0 });
+ *   spawn.throwIfBlocked();
+ *   spawn.started();
+ *   try { await worker() } finally { spawn.finished() }
+ *
+ *   const call = burn.beforeCall({ estimatedTokens: 120_000 });
+ *   call.throwIfBlocked();
+ *   try {
+ *     const res = await client.chat({ ..., headers: call.headers });
+ *     call.complete({ tokens: res.usage.total_tokens });
+ *   } catch (e) { call.fail(); throw e }
+ *
+ * A model call reserves an estimate and then commits the real number under
+ * the same call ID, so a proxy observing the same request (via call.headers)
+ * supersedes rather than duplicates it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BurnStopError = void 0;
+exports.createRawApiGuard = createRawApiGuard;
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const events_1 = require("../events");
+const gateway_1 = require("../gateway");
+const render_1 = require("../replay/render");
+class BurnStopError extends Error {
+    decision;
+    constructor(decision) {
+        super((0, render_1.renderStop)(decision.report, { colour: false, subject: decision.action === 'spawn' ? 'spawn' : 'call' }));
+        this.decision = decision;
+        this.name = 'BurnStopError';
+    }
+}
+exports.BurnStopError = BurnStopError;
+const HOST = 'raw-api';
+function createRawApiGuard(opts) {
+    const home = opts.home ?? process.env.AGENTGUARD_HOME ?? (0, node_path_1.join)((0, node_os_1.homedir)(), '.agentguard');
+    const gateway = new gateway_1.Gateway(home, { sign: opts.sign, now: opts.now });
+    const now = opts.now ?? (() => Date.now());
+    const { sessionId } = opts;
+    gateway.observe([
+        { schemaVersion: 1, kind: 'session_opened', eventId: (0, events_1.eventId)(), host: HOST, sessionId, at: now(), capabilities: { spawns: 'authoritative', depth: 'authoritative', usage: 'authoritative' } },
+    ]);
+    return {
+        sessionId,
+        gateway,
+        beforeSpawn(args = { parentDepth: 0 }) {
+            const spawnId = args.spawnId ?? (0, events_1.eventId)();
+            const depth = args.parentDepth + 1;
+            const decision = gateway.beforeSpawn({
+                schemaVersion: 1,
+                kind: 'spawn_requested',
+                eventId: (0, events_1.eventId)(),
+                host: HOST,
+                sessionId,
+                at: now(),
+                spawnId,
+                proposedDepth: depth,
+                attribution: 'high',
+            });
+            return {
+                spawnId,
+                depth,
+                decision,
+                get blocked() {
+                    return decision.blocked;
+                },
+                throwIfBlocked() {
+                    if (decision.blocked)
+                        throw new BurnStopError(decision);
+                },
+                started() {
+                    gateway.observe([{ schemaVersion: 1, kind: 'spawn_started', eventId: (0, events_1.eventId)(), host: HOST, sessionId, at: now(), spawnId, depth }]);
+                },
+                finished() {
+                    gateway.observe([{ schemaVersion: 1, kind: 'spawn_finished', eventId: (0, events_1.eventId)(), host: HOST, sessionId, at: now(), spawnId }]);
+                },
+            };
+        },
+        beforeCall(args = {}) {
+            const callId = args.callId ?? (0, events_1.eventId)();
+            const decision = gateway.beforeCall({
+                schemaVersion: 1,
+                kind: 'call_requested',
+                eventId: (0, events_1.eventId)(),
+                host: HOST,
+                sessionId,
+                at: now(),
+                callId,
+                estimatedTokens: Math.max(0, args.estimatedTokens ?? 0),
+                attribution: 'high',
+            });
+            return {
+                callId,
+                decision,
+                /** Attach to the outbound request so a local proxy correlates it. */
+                headers: { [events_1.SESSION_HEADER]: sessionId, [events_1.CALL_HEADER]: callId },
+                get blocked() {
+                    return decision.blocked;
+                },
+                throwIfBlocked() {
+                    if (decision.blocked)
+                        throw new BurnStopError(decision);
+                },
+                complete(usage) {
+                    gateway.completeCall({ host: HOST, sessionId, callId, tokens: usage.tokens, cacheRead: usage.cacheRead, usageCoverage: 'authoritative', at: now() });
+                },
+                fail() {
+                    gateway.failCall({ host: HOST, sessionId, callId, at: now() });
+                },
+            };
+        },
+        /** Current state without deciding anything. */
+        status() {
+            return gateway.peek(sessionId);
+        },
+    };
+}

package/dist/src/cli.d.ts

@@ -4,11 +4,15 @@
  *
  *   replay            what enforcement would have stopped, on your history
  *   calibrate         fit thresholds to your own usage, write shadow policy
- *   status            current mode, shadow decisions, promotion eligibility
- *   init              install the PreToolUse hook (shadow mode)
+ *   status            mode, shadow decisions, eligibility, every host's sessions
+ *   init [host]       hook snippet for claude (default), cursor or codex
  *   enforce           promote shadow -> enforce, once eligible
  *   shadow            demote back to shadow
  *   resume --once     one audited override of the next STOP
- *   hook              (internal) stdin -> stdout hook entry point
+ *   proxy             loopback proxy in front of Ollama / vLLM / LM Studio
+ *   conformance       prove the storm and the grind stop identically per host
+ *   hook              (internal) Claude Code stdin -> stdout hook entry point
+ *   cursor-hook       (internal) Cursor hook entry point
+ *   codex-hook        (internal) Codex hook entry point
  */
 export {};

package/dist/src/cli.js

@@ -5,23 +5,45 @@
  *
  *   replay            what enforcement would have stopped, on your history
  *   calibrate         fit thresholds to your own usage, write shadow policy
- *   status            current mode, shadow decisions, promotion eligibility
- *   init              install the PreToolUse hook (shadow mode)
+ *   status            mode, shadow decisions, eligibility, every host's sessions
+ *   init [host]       hook snippet for claude (default), cursor or codex
  *   enforce           promote shadow -> enforce, once eligible
  *   shadow            demote back to shadow
  *   resume --once     one audited override of the next STOP
- *   hook              (internal) stdin -> stdout hook entry point
+ *   proxy             loopback proxy in front of Ollama / vLLM / LM Studio
+ *   conformance       prove the storm and the grind stop identically per host
+ *   hook              (internal) Claude Code stdin -> stdout hook entry point
+ *   cursor-hook       (internal) Cursor hook entry point
+ *   codex-hook        (internal) Codex hook entry point
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
+const cursor_1 = require("./adapters/cursor");
+const codex_1 = require("./adapters/codex");
 const calibrate_1 = require("./calibrate");
+const conformance_1 = require("./conformance");
 const defaults_1 = require("./defaults");
+const gateway_1 = require("./gateway");
 const pre_tool_use_1 = require("./hook/pre-tool-use");
+const install_1 = require("./install");
+const override_1 = require("./override");
+const server_1 = require("./proxy/server");
 const render_1 = require("./replay/render");
 const simulate_1 = require("./replay/simulate");
+const status_1 = require("./status");
 const HOME = process.env.AGENTGUARD_HOME ?? (0, node_path_1.join)((0, node_os_1.homedir)(), '.agentguard');
+const PROXY_HOSTS = ['ollama', 'vllm', 'lm-studio', 'openai-compatible'];
+function readStdinJson() {
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(0, 'utf8'));
+    }
+    catch {
+        // Unparseable payload: allow. We never break the host over our own bug.
+        return null;
+    }
+}
 function savePolicy(policy) {
     (0, node_fs_1.mkdirSync)(HOME, { recursive: true, mode: 0o700 });
     (0, node_fs_1.writeFileSync)((0, node_path_1.join)(HOME, 'burn-policy.json'), JSON.stringify(policy, null, 2), { mode: 0o600 });
@@ -109,23 +131,109 @@ async function main(argv) {
         case 'status': {
             const policy = (0, pre_tool_use_1.loadPolicy)(HOME);
             const e = shadowEligibility();
+            const gateway = new gateway_1.Gateway(HOME, { sign: false });
+            const lc = policy.thresholds.localCompute;
+            const override = (0, override_1.readOverride)(HOME);
             process.stdout.write([
-                `mode: ${policy.mode}`,
-                `thresholds: fan-out ${policy.thresholds.fanout.warn}/${policy.thresholds.fanout.stop}  sustained ${(policy.thresholds.sustained.warnTokens / 1e9).toFixed(1)}B/${(policy.thresholds.sustained.stopTokens / 1e9).toFixed(1)}B`,
+                `mode: ${policy.mode}${policy.mode === 'enforce' ? '  (the next STOP blocks)' : '  (recording only; nothing is blocked)'}`,
+                `thresholds: fan-out ${policy.thresholds.fanout.warn}/${policy.thresholds.fanout.stop}  sustained ${(policy.thresholds.sustained.warnTokens / 1e9).toFixed(1)}B/${(policy.thresholds.sustained.stopTokens / 1e9).toFixed(1)}B  local-compute warn at ${lc?.warnConcurrent ?? 4} concurrent${lc?.stopConcurrent ? `, stop at ${lc.stopConcurrent}` : ' (no stop set)'}`,
                 policy.calibration ? `calibrated from ${policy.calibration.sessionsSampled} sessions` : 'using shipped defaults (run: agentguard-burn calibrate)',
                 `shadow observation: ${e.decisions} decisions over ${e.days.toFixed(1)} days`,
                 `  would have warned: ${e.warns}   would have blocked: ${e.wouldBlock}`,
-                `eligible for enforcement: ${e.eligible ? 'yes' : `no (need ${defaults_1.SHADOW_MIN_DECISIONS} decisions and ${defaults_1.SHADOW_MIN_DAYS} days)`}`,
-            ].join('\n') + '\n');
+                `eligible for enforcement: ${e.eligible ? 'yes  (agentguard-burn enforce)' : `no (need ${defaults_1.SHADOW_MIN_DECISIONS} decisions and ${defaults_1.SHADOW_MIN_DAYS} days)`}`,
+                override ? `override ACTIVE: ${override.once ? 'the next STOP' : `every STOP until ${new Date(override.until).toLocaleTimeString()}`} passes ("${override.reason}")` : '',
+                '',
+                (0, status_1.renderHostHealth)(['claude', 'cursor', 'codex'].map((h) => (0, install_1.health)(h))),
+                '',
+                (0, status_1.renderMachineStatus)([...(0, status_1.readHookSessions)(HOME), ...gateway.sessions()], gateway.compute()),
+                '',
+                'content logging: off · telemetry: none · state: this machine only',
+            ]
+                .filter((l) => l !== '' || true)
+                .join('\n')
+                .replace(/\n\n\n/g, '\n\n') + '\n');
             return 0;
         }
         case 'init': {
             const policy = (0, pre_tool_use_1.loadPolicy)(HOME);
             savePolicy(policy);
-            const command = `node ${(0, node_path_1.join)(__dirname, 'cli.js')} hook`;
-            process.stdout.write(`Add this to ~/.claude/settings.json (merge into existing "hooks"):\n\n${JSON.stringify((0, pre_tool_use_1.settingsSnippet)(command), null, 2)}\n\nInstalled in ${policy.mode} mode. Nothing is blocked until you run: agentguard-burn enforce\n`);
+            const cli = (0, node_path_1.join)(__dirname, 'cli.js');
+            const target = (rest.find((a) => !a.startsWith('--')) ?? 'claude');
+            if (!['claude', 'cursor', 'codex'].includes(target)) {
+                process.stderr.write(`init: host must be claude, cursor or codex\n`);
+                return 64;
+            }
+            const label = { claude: '', cursor: 'Cursor support is BETA: verified against the documented hook schema, not yet against every installed build. "failClosed": true means a crashed hook denies the subagent.', codex: 'Codex support is BETA: a live deny, allow and override canary passed on codex-cli 0.151.0; transcript usage is best-effort and marked estimated. Trust the hook once with /hooks inside Codex.' }[target];
+            const tail = `Installed in ${policy.mode} mode. Nothing is blocked until you run: agentguard-burn enforce\n`;
+            if (has('--write')) {
+                let result;
+                try {
+                    result = (0, install_1.install)(target, cli);
+                }
+                catch (error) {
+                    process.stderr.write(`init: refusing to touch ${(0, install_1.configPath)(target)}: ${error instanceof Error ? error.message : String(error)}\n`);
+                    return 1;
+                }
+                process.stdout.write((result.changed ? `Wrote ${result.file}${result.backup ? `  (backup: ${result.backup})` : ''}\n` : `${result.file} already has the current hook; nothing changed.\n`) +
+                    `  ${result.command}\n` +
+                    (label ? `${label}\n` : '') +
+                    tail +
+                    `Check it: agentguard-burn status\n`);
+                return 0;
+            }
+            const snippet = target === 'cursor' ? (0, cursor_1.cursorHooksSnippet)(`node ${cli} cursor-hook`) : target === 'codex' ? (0, codex_1.codexHooksSnippet)(`node ${cli} codex-hook`) : (0, pre_tool_use_1.settingsSnippet)(`node ${cli} hook`);
+            process.stdout.write(`Add this to ${(0, install_1.configPath)(target).replace(process.env.HOME ?? '', '~')} (merge into existing "hooks"), or run: agentguard-burn init ${target} --write\n\n${JSON.stringify(snippet, null, 2)}\n\n` +
+                (label ? `${label}\n` : '') +
+                tail +
+                (target === 'claude' ? `Other hosts: agentguard-burn init cursor | init codex | proxy --upstream http://127.0.0.1:11434 --host ollama\n` : ''));
+            return 0;
+        }
+        case 'cursor-hook': {
+            const gateway = new gateway_1.Gateway(HOME);
+            process.stdout.write(JSON.stringify((0, cursor_1.handleCursorHook)(readStdinJson(), gateway)));
             return 0;
         }
+        case 'codex-hook': {
+            const gateway = new gateway_1.Gateway(HOME);
+            process.stdout.write(JSON.stringify((0, codex_1.handleCodexHook)(readStdinJson(), gateway)));
+            return 0;
+        }
+        case 'proxy': {
+            const upstreamRaw = flag('--upstream') ?? 'http://127.0.0.1:11434';
+            const host = (flag('--host') ?? 'ollama');
+            if (!PROXY_HOSTS.includes(host)) {
+                process.stderr.write(`--host must be one of ${PROXY_HOSTS.join(', ')}\n`);
+                return 64;
+            }
+            const listen = flag('--listen') ?? '127.0.0.1:18080';
+            const [listenHost, listenPortRaw] = listen.includes(':') ? [listen.slice(0, listen.lastIndexOf(':')), listen.slice(listen.lastIndexOf(':') + 1)] : ['127.0.0.1', listen];
+            const gateway = new gateway_1.Gateway(HOME);
+            const running = await (0, server_1.startProxy)({
+                upstream: new URL(upstreamRaw),
+                gateway,
+                host,
+                listenHost,
+                listenPort: Number(listenPortRaw),
+                defaultSession: flag('--session') ?? process.env.AGENTGUARD_SESSION_ID,
+                allowRemoteUpstream: has('--allow-remote-upstream'),
+                log: (l) => process.stderr.write(`${l}\n`),
+            });
+            const policy = (0, pre_tool_use_1.loadPolicy)(HOME);
+            process.stderr.write(`agentguard-burn proxy  ${running.address.origin}  ->  ${upstreamRaw}  (${host}, ${policy.mode} mode)\n` +
+                `Point your agent at ${running.address.origin}. Send x-agentguard-session: <id> so calls join a session; without it each client port is its own low-confidence session.\n` +
+                `Ctrl-C to stop.\n`);
+            await new Promise((resolve) => {
+                const stop = () => running.close().then(resolve, resolve);
+                process.once('SIGINT', stop);
+                process.once('SIGTERM', stop);
+            });
+            return 0;
+        }
+        case 'conformance': {
+            const result = await (0, conformance_1.runConformance)();
+            process.stdout.write(result.text + '\n');
+            return result.ok ? 0 : 1;
+        }
         case 'enforce': {
             const policy = (0, pre_tool_use_1.loadPolicy)(HOME);
             const e = shadowEligibility();
@@ -143,20 +251,36 @@ async function main(argv) {
             return 0;
         }
         case 'resume': {
-            const reason = flag('--reason') ?? 'no reason given';
-            (0, node_fs_1.mkdirSync)(HOME, { recursive: true, mode: 0o700 });
-            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(HOME, 'override.json'), JSON.stringify({ at: Date.now(), once: has('--once'), reason }), { mode: 0o600 });
-            process.stdout.write(`Override recorded${has('--once') ? ' for the next STOP only' : ''}: ${reason}\n`);
+            if (has('--clear')) {
+                (0, override_1.clearOverride)(HOME);
+                process.stdout.write('Override cleared. The next STOP blocks.\n');
+                return 0;
+            }
+            const reason = flag('--reason');
+            if (!reason) {
+                process.stderr.write('resume: --reason "..." is required; every override is written to the decisions ledger with it.\n');
+                return 64;
+            }
+            const once = has('--once');
+            const now = Date.now();
+            (0, override_1.writeOverride)(HOME, once ? { at: now, once: true, reason } : { at: now, once: false, reason, until: now + override_1.OVERRIDE_WINDOW_MS });
+            process.stdout.write(once
+                ? `Override recorded for the next STOP only, on any host: "${reason}"\n`
+                : `Override recorded for the next ${override_1.OVERRIDE_WINDOW_MS / 60000} minutes, on any host: "${reason}"\n  (agentguard-burn resume --clear to end it early)\n`);
             return 0;
         }
         default:
-            process.stdout.write('agentguard-burn <replay|calibrate|status|init|enforce|shadow|resume|hook>\n' +
+            process.stdout.write('agentguard-burn <replay|calibrate|status|init|enforce|shadow|resume|proxy|conformance>\n' +
                 '  replay [files...] [--json] [--top N] [--min-tokens N]\n' +
                 '  calibrate            fit thresholds to your history (writes shadow policy)\n' +
-                '  status               mode, shadow observations, eligibility\n' +
-                '  init                 print the settings.json hook snippet\n' +
+                '  status               mode, shadow observations, eligibility, hook health, every host\n' +
+                '  init [claude|cursor|codex] [--write]   print the hook snippet, or merge it into the config (with a backup)\n' +
                 '  enforce [--force]    shadow -> enforce\n' +
-                '  resume --once --reason "..."\n');
+                '  shadow               enforce -> shadow\n' +
+                '  resume --once --reason "..."   let the next STOP through, once, on any host\n' +
+                '  resume --reason "..."          let STOPs through for 15 minutes; --clear ends it\n' +
+                '  proxy --upstream http://127.0.0.1:11434 --host ollama|vllm|lm-studio|openai-compatible [--listen 127.0.0.1:18080] [--session ID]\n' +
+                '  conformance          replay the storm and the grind through every adapter shape\n');
             return command ? 64 : 0;
     }
 }

package/dist/src/conformance.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Conformance: the same failure, through every door, stops at the same step.
+ *
+ * Two fixtures, fitted on real sessions:
+ *
+ *   the storm   42 candidate spawns. First WARN must be spawn 24, first STOP
+ *               must be spawn 41. Every spawn-capable adapter replays it.
+ *   the grind   model calls of 250M tokens each. First WARN must be the call
+ *               after 3.5B, first STOP the call after 5B. Every usage-capable
+ *               adapter replays it.
+ *   composite   raw middleware supplies the spawns, the proxy supplies the
+ *               usage, one session ID. Candidate spawn 41 must see BOTH
+ *               planes in its findings. That is the claim on the box.
+ *
+ * Runs in a throwaway home in enforce mode. Nothing here touches ~/.agentguard.
+ */
+export interface ConformanceResult {
+    ok: boolean;
+    text: string;
+    checks: {
+        name: string;
+        ok: boolean;
+        detail: string;
+    }[];
+}
+export declare function runConformance(): Promise<ConformanceResult>;