@agentguard-run/burn 0.1.0

package/LICENSE

@@ -0,0 +1,166 @@
+AgentGuard(R) Burn - Alpha License
+Copyright (c) 2026 Dunecrest Ventures Inc.
+
+1. SCOPE.
+This software is the npm package @agentguard-run/spend, comprising every file
+present in an installed copy of that package. That includes the TypeScript
+sources under src/, the compiled output under dist/, the command-line entry
+point under bin/, the documentation under docs/, the fixtures under tests/, and
+the root files README.md, README.es-419.md, README.pt-BR.md, CHANGELOG.md,
+PATENTS.md and package.json. Any file the package ships that Section 3 does not
+expressly name is licensed under this Section 1; the enumeration above is
+illustrative, and adding a file to the package does not place it outside these
+terms.
+
+This software is licensed by Dunecrest Ventures Inc. ("Licensor") subject to the
+following thresholds:
+
+  (a) Evaluation Use. Internal evaluation, prototyping, and non-commercial
+      development at any call volume.
+
+  (b) Free Production Threshold. Production deployments processing 10,000
+      or fewer enforcement calls per calendar month, in aggregate across
+      all instances operated by the licensee, are permitted under this
+      License without additional fee.
+
+  (c) Commercial License Required. Production deployments processing more
+      than 10,000 enforcement calls per calendar month, deployments
+      operated for the benefit of third parties as a service, redistribution,
+      sublicensing, public hosting, and republication each require a
+      separate commercial license agreement with Licensor.
+
+Commercial-license inquiries: invest@agentguard.run
+
+2. NO PATENT LICENSE GRANTED.
+Nothing in this License grants, expressly or by implication, any patent license
+to any patent, patent application, or other intellectual property right of
+Licensor. All patent rights are expressly reserved.
+
+3. SEPARATE GRANT FOR DEMONSTRATION ASSETS.
+The following assets, and ONLY these assets, are released under the BSD
+2-Clause License, reproduced in full below:
+
+  - The documentation files README.md, README.es-419.md and README.pt-BR.md
+  - The test fixture under tests/
+
+  Copyright (c) 2026 Dunecrest Ventures Inc.
+
+  Redistribution and use in source and binary forms, with or without
+  modification, are permitted provided that the following conditions are met:
+
+  1. Redistributions of source code must retain the above copyright notice,
+     this list of conditions and the following disclaimer.
+
+  2. Redistributions in binary form must reproduce the above copyright notice,
+     this list of conditions and the following disclaimer in the documentation
+     and/or other materials provided with the distribution.
+
+  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+  POSSIBILITY OF SUCH DAMAGE.
+
+This grant conveys copyright permission only. It grants no patent license,
+express or implied, no covenant not to sue, and no exhaustion, estoppel, or
+implied-license rights under any patent or patent application of Licensor,
+consistent with Section 2 above. The BSD 2-Clause License is used for these
+assets precisely because it is silent as to patents.
+
+Nothing else the package ships is included in the grant above. The code under
+src/, dist/ and bin/, the documentation under docs/, and the root files
+CHANGELOG.md and PATENTS.md remain licensed only under the alpha evaluation
+terms of Section 1. The TypeScript type definitions, policy engine, decision
+log, store implementation, cost table, and wrapper code are in that group.
+
+
+4. WARRANTY DISCLAIMER.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
+DUNECREST VENTURES INC. BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY
+ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+
+5. SUCCESSORS AND ASSIGNS.
+This License binds and benefits the parties' respective successors and assigns.
+In the event of an asset sale, merger, change of control, or other transfer of
+the Licensor's rights in this software, all rights and obligations under this
+License inure to the benefit of and are binding upon Licensor's successor or
+assignee. Outstanding evaluation grants survive change-of-control, but the
+successor or assignee may, upon thirty (30) days' written notice, terminate
+ongoing evaluation grants in favor of a commercial-license requirement.
+
+6. TERMINATION.
+Licensor may terminate this License with thirty (30) days' written notice for
+any reason or no reason. Upon termination, Licensee shall cease all use of the
+software under src/, dist/ and bin/ and shall destroy all copies in Licensee's possession.
+
+7. PATENT NOTICE (35 U.S.C. § 287).
+Certain AgentGuard technologies are patent pending. All patent rights are
+expressly reserved per Section 2 above.
+
+AgentGuard(R) is a registered trademark of Dunecrest Ventures Inc.
+(U.S. Reg. No. 8281464). MerchantGuard(TM) is a trademark of Dunecrest
+Ventures Inc. (USPTO Serial No. 99051215, pending).
+
+For commercial licensing: invest@agentguard.run
+
+FUNCTIONAL-USE DISCLAIMER ADDENDUM
+
+DISCLAIMER: All terminology and labels used in AgentGuard’s materials are descriptive of
+software functionality only, not legal definitions or guarantees of compliance. For example, the
+terms “receipt,” “audit log,” “evidence,” “audit trail,” and “attestation” refer solely to
+cryptographically-signed records produced by AgentGuard’s software. These terms do not mean
+that any record is legally binding evidence, certified by any authority, or equivalent to records
+maintained by banks, auditors, or courts. Similarly, references to “signed,” “verified,” or “attested”
+pertain to digital signature processes, not to notarization or governmental attestation. Any use of
+the word “compliance,” “compliant,” “outcome,” or “settlement” describes the software’s features in
+a non-regulatory sense. In particular, “capability tier” is merely an internal category of agent
+permission levels, and does not correspond to any government or industry regulatory classification.
+Likewise, any statement that an operation “settles” or an outcome is “settled” refers only to the
+software’s final state, not to any legal settlement. No AgentGuard tool or document should be
+interpreted as providing legal, financial, or regulatory advice, or as a certified compliance
+certificate. AgentGuard is not a law firm or auditor and does not guarantee adherence to laws or
+standards. All use of AgentGuard software is at the user’s risk, and users must ensure
+independently that their use of AI agents complies with all applicable laws and
+regulations.* (CONTINUED IN NEXT PARAGRAPH)
+Throughout this documentation, package metadata, CLI banners, and related materials, any word
+drawn from compliance or legal contexts (such as “audit,” “evidence,” “settlement,” “credit,” “debt,”
+“market,” “liquidity,” “maturity,” or similar) is used only in a functional, descriptive sense. For
+instance, “audit log” simply means a sequence of recorded events; it does not imply an official
+financial or regulatory audit. The phrase “satisfies” is used to indicate that one software condition
+meets a programmed check (e.g. satisfying a budget cap), and is not intended to suggest that any
+legal requirement has been fulfilled. Under no circumstances should AgentGuard’s terminology be
+taken to indicate that our software is executing regulated financial or legal processes.*
+No term in our code, documentation, or marketing is meant to designate or characterize any
+AgentGuard feature as a service subject to banking, securities, derivatives, insurance, real estate, or
+other regulated activities. For example, “trade,” “trading,” “liquidity,” “maturity,” and similar terms
+(if ever used) describe algorithmic budget or token flows, not financial transactions. AgentGuard
+does not act as a broker-dealer, clearinghouse, insurance issuer, or government agency. References
+to “market” or “liquidation” are metaphorical descriptions of how the software handles tokens or
+budgets. No AgentGuard action should be construed as offering financial services or operating a
+regulated marketplace.*
+Likewise, words like “offer,” “obligation,” “credit,” “debt,” “payment,” or “settle” in our text refer only
+to hypothetical or illustrative actions of a user’s AI agent or simulated transaction flows. They do
+not mean that AgentGuard is engaging in any money-handling, offering financial instruments, or
+guaranteeing any settlement of obligations. If AgentGuard generates an invoice or cost-of-service
+figure, it is purely illustrative of resource usage, not a binding financial bill. The term “maker/taker”
+(if used in examples) is purely a naming convention and has no relation to exchange regulation.
+
+The software’s “payment execution” tier is only a capability checkbox, not an actual payment
+processor. AgentGuard does not transmit money or credit.*
+Finally, any references to “certify,” “verify,” or “attest” should be read in context of cryptography and
+computing. For example, when we say a receipt is “signed” or “verified,” we mean via public-key
+cryptography. AgentGuard does not claim that receipts are admissible legal evidence by default.
+Users remain responsible for any legal implications of presenting AgentGuard logs or receipts in
+regulatory audits or court. This disclaimer is intended to ensure AgentGuard’s terms (in this
+README, license, package descriptions, CLI banner, customer agreements, and /llms.txt) make clear
+we provide a technical audit tool only. The functionality is delivered “as-is” with no implied
+regulatory endorsement.

package/README.md

@@ -0,0 +1,60 @@
+# @agentguard-run/burn
+
+Local runaway-agent circuit breaker for AI coding agents.
+
+Raw token counters did not help. You see "360k tokens" and keep going. This
+tool does the three things a counter does not: it decides whether a session is
+pathological, it blocks the next agent spawn when it is, and it tells you what
+to do about it. Nothing leaves the machine.
+
+## Two safety planes
+
+Fitted against 412 real Claude Code sessions, which showed two independent
+failure shapes that one detector cannot cover:
+
+| Plane | Catches | Rule | Validated on |
+|---|---|---|---|
+| Structural | fan-out storms: many agents re-sending context | WARN 24 spawns, STOP before spawn 41, no agents-spawning-agents past depth 2 | 174- and 226-spawn sessions; STOP would have intercepted 91% of the runaway |
+| Economic | slow grinds: few agents, enormous total | WARN 3.5B, STOP 5B tokens per session | the 9.15B / 26-spawn session the spawn cap could not see |
+
+Across all 412 sessions: 3 STOP, 2 WARN, 407 clean. Zero false STOPs.
+
+Cache-read ratio was 98% on every session, healthy and pathological alike. It
+is shown as an explanation and never used to decide.
+
+## Start with replay, not with the hook
+
+```
+npx @agentguard-run/burn replay
+```
+
+Runs the detectors over your existing history and shows what enforcement would
+have intercepted, when, and the observed tail after each stop. It is an upper
+bound, labelled as such. Nobody installs a blocker cold.
+
+```
+npx @agentguard-run/burn calibrate    # fit thresholds to your own usage
+npx @agentguard-run/burn init         # print the settings.json hook snippet
+npx @agentguard-run/burn status       # shadow observations, eligibility
+npx @agentguard-run/burn enforce      # after 7 days and 50 decisions
+```
+
+The hook installs in **shadow mode**: every decision is recorded, nothing is
+blocked, until you have seen it be right.
+
+## The concurrency guarantee
+
+Ten parallel `Agent` calls launch ten hook processes that all read the same
+transcript and all see the same count. A naive cap is cosmetic during exactly
+the burst it exists for. Spawns are admitted through an atomic, cross-process
+reservation under a machine-wide lock; the test suite launches 60 real OS
+processes against a cap of 40 and asserts exactly 40 are admitted.
+
+Single-machine by design. Two laptops on one account do not share state, and
+that is stated rather than hidden.
+
+## What it never does
+
+No prompts, responses, file contents, or tool inputs are persisted or rendered.
+No telemetry. No provider-quota guesses: it projects against your configured
+policy, never against a subscription allowance it cannot see.

package/dist/src/calibrate.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Calibration: derive thresholds from the user's own history.
+ *
+ * Shipped defaults solve scale mismatch for one machine. Calibration solves it
+ * for everyone else. The statistics are chosen to survive the one input that
+ * would otherwise poison them: a user whose history is *already* pathological.
+ *
+ * Procedure:
+ *   1. Exclude sessions that breach immutable safety boundaries (they are the
+ *      thing we are trying to catch, so they must not define "normal").
+ *   2. Winsorise the healthy set with median/MAD so one huge session cannot
+ *      drag the percentile.
+ *   3. WARN at p90, STOP at p99 of the healthy set (type-7 quantiles).
+ *   4. Shrink toward the shipped defaults when the sample is small.
+ *   5. Clamp into a safe band, and keep WARN and STOP apart.
+ *
+ * What this does and does not solve, honestly: it removes the two-orders-of-
+ * magnitude scale error that a global default carries. It does not remove the
+ * policy choice. p90, p99, the band, and the exclusion boundary are decisions,
+ * and the report says so.
+ */
+import type { Policy, Thresholds } from './types';
+import type { SessionReplay } from './replay/simulate';
+export interface CalibrationResult {
+    policy: Policy;
+    sessionsTotal: number;
+    sessionsExcluded: number;
+    sessionsUsed: number;
+    rawWarnP90: number;
+    rawStopP99: number;
+    notes: string[];
+}
+export declare function calibrate(sessions: SessionReplay[], base?: Thresholds): CalibrationResult;

package/dist/src/calibrate.js

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * Calibration: derive thresholds from the user's own history.
+ *
+ * Shipped defaults solve scale mismatch for one machine. Calibration solves it
+ * for everyone else. The statistics are chosen to survive the one input that
+ * would otherwise poison them: a user whose history is *already* pathological.
+ *
+ * Procedure:
+ *   1. Exclude sessions that breach immutable safety boundaries (they are the
+ *      thing we are trying to catch, so they must not define "normal").
+ *   2. Winsorise the healthy set with median/MAD so one huge session cannot
+ *      drag the percentile.
+ *   3. WARN at p90, STOP at p99 of the healthy set (type-7 quantiles).
+ *   4. Shrink toward the shipped defaults when the sample is small.
+ *   5. Clamp into a safe band, and keep WARN and STOP apart.
+ *
+ * What this does and does not solve, honestly: it removes the two-orders-of-
+ * magnitude scale error that a global default carries. It does not remove the
+ * policy choice. p90, p99, the band, and the exclusion boundary are decisions,
+ * and the report says so.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calibrate = calibrate;
+const defaults_1 = require("./defaults");
+const IMMUTABLE_MAX_SPAWNS = 40;
+const IMMUTABLE_MAX_TOKENS = 6_000_000_000;
+/**
+ * Sessions below this are not evidence about what a working session costs.
+ * On the author's machine 391 of 394 sessions were open-ask-close and sat
+ * around 10M tokens; percentiles over that distribution described nothing and
+ * produced a STOP that would have fired on every routine working session.
+ * Calibration must be fitted to the sessions the alarm is actually for.
+ */
+const MIN_WORKING_SESSION_TOKENS = 50_000_000;
+const BAND = {
+    warn: { lo: 1_500_000_000, hi: 3_500_000_000 },
+    stop: { lo: 3_000_000_000, hi: 5_000_000_000 },
+    separation: 500_000_000,
+};
+const MIN_SESSIONS_FOR_FULL_TRUST = 20;
+function quantile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const h = (sorted.length - 1) * p;
+    const lo = Math.floor(h);
+    const hi = Math.ceil(h);
+    return sorted[lo] + (sorted[hi] - sorted[lo]) * (h - lo);
+}
+function median(values) {
+    const s = [...values].sort((a, b) => a - b);
+    return quantile(s, 0.5);
+}
+function winsorise(values) {
+    if (values.length < 4)
+        return values;
+    const m = median(values);
+    const mad = median(values.map((v) => Math.abs(v - m))) || 1;
+    const cap = m + 5 * 1.4826 * mad;
+    return values.map((v) => Math.min(v, cap));
+}
+function clamp(v, lo, hi) {
+    return Math.max(lo, Math.min(hi, v));
+}
+function calibrate(sessions, base = defaults_1.DEFAULT_THRESHOLDS) {
+    const notes = [];
+    const working = sessions.filter((s) => s.totalTokens >= MIN_WORKING_SESSION_TOKENS);
+    const trivial = sessions.length - working.length;
+    if (trivial > 0) {
+        notes.push(`${trivial} short session(s) under ${MIN_WORKING_SESSION_TOKENS / 1e6}M tokens ignored; they are not evidence about working-session cost.`);
+    }
+    const healthy = working.filter((s) => s.spawns <= IMMUTABLE_MAX_SPAWNS && s.totalTokens <= IMMUTABLE_MAX_TOKENS);
+    const excluded = working.length - healthy.length;
+    if (excluded > 0) {
+        notes.push(`${excluded} session(s) excluded as already pathological (>${IMMUTABLE_MAX_SPAWNS} spawns or >6B tokens). They must not define normal.`);
+    }
+    const tokens = winsorise(healthy.map((s) => s.totalTokens)).sort((a, b) => a - b);
+    const rawWarn = quantile(tokens, 0.9);
+    const rawStop = quantile(tokens, 0.99);
+    // Shrink toward defaults when the sample is thin.
+    const trust = Math.min(1, healthy.length / MIN_SESSIONS_FOR_FULL_TRUST);
+    const blendedWarn = trust * rawWarn + (1 - trust) * base.sustained.warnTokens;
+    const blendedStop = trust * rawStop + (1 - trust) * base.sustained.stopTokens;
+    if (trust < 1)
+        notes.push(`Only ${healthy.length} usable sessions; thresholds shrunk ${Math.round((1 - trust) * 100)}% toward shipped defaults.`);
+    let warn = clamp(blendedWarn, BAND.warn.lo, BAND.warn.hi);
+    let stop = clamp(blendedStop, BAND.stop.lo, BAND.stop.hi);
+    if (stop - warn < BAND.separation) {
+        stop = Math.min(BAND.stop.hi, warn + BAND.separation);
+        warn = Math.min(warn, stop - BAND.separation);
+    }
+    // Burn-debt baseline: tokens per active minute across healthy sessions.
+    const perMinute = healthy
+        .filter((s) => s.activeMinutes > 5)
+        .map((s) => s.totalTokens / s.activeMinutes);
+    const debtEnabled = perMinute.length >= MIN_SESSIONS_FOR_FULL_TRUST;
+    const baseline = debtEnabled ? median(perMinute) : 0;
+    if (!debtEnabled) {
+        notes.push(`Burn-debt detector stays off: needs ${MIN_SESSIONS_FOR_FULL_TRUST}+ sessions with >5 active minutes, have ${perMinute.length}.`);
+    }
+    const thresholds = {
+        ...base,
+        sustained: { warnTokens: Math.round(warn), stopTokens: Math.round(stop) },
+        burnDebt: {
+            ...base.burnDebt,
+            baselinePerActiveMinute: Math.round(baseline),
+            enabled: debtEnabled,
+        },
+    };
+    notes.push('Calibration fixes the scale of the alarm. Policy still decides how much unusual is allowed: p90/p99, the safety band, and the exclusion boundary are choices, not measurements.');
+    return {
+        policy: {
+            mode: 'shadow',
+            thresholds,
+            calibration: { sessionsSampled: healthy.length, generatedAt: Date.now(), method: 'winsorised p90/p99 with shrinkage and safety band' },
+        },
+        sessionsTotal: sessions.length,
+        sessionsExcluded: excluded,
+        sessionsUsed: healthy.length,
+        rawWarnP90: rawWarn,
+        rawStopP99: rawStop,
+        notes,
+    };
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * agentguard-burn
+ *
+ *   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)
+ *   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
+ */
+export {};

package/dist/src/cli.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * agentguard-burn
+ *
+ *   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)
+ *   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
+ */
+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 calibrate_1 = require("./calibrate");
+const defaults_1 = require("./defaults");
+const pre_tool_use_1 = require("./hook/pre-tool-use");
+const render_1 = require("./replay/render");
+const simulate_1 = require("./replay/simulate");
+const HOME = process.env.AGENTGUARD_HOME ?? (0, node_path_1.join)((0, node_os_1.homedir)(), '.agentguard');
+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 });
+}
+function readDecisions() {
+    const file = (0, node_path_1.join)(HOME, 'decisions.ndjson');
+    if (!(0, node_fs_1.existsSync)(file))
+        return [];
+    return (0, node_fs_1.readFileSync)(file, 'utf8')
+        .split('\n')
+        .filter(Boolean)
+        .map((l) => {
+        try {
+            return JSON.parse(l);
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((x) => x !== null);
+}
+function shadowEligibility() {
+    const decisions = readDecisions();
+    const first = decisions.length ? Number(decisions[0].at) : Date.now();
+    const days = (Date.now() - first) / 86_400_000;
+    const wouldBlock = decisions.filter((d) => d.wouldDeny === true).length;
+    const warns = decisions.filter((d) => d.verdict === 'WARN').length;
+    return {
+        eligible: decisions.length >= defaults_1.SHADOW_MIN_DECISIONS && days >= defaults_1.SHADOW_MIN_DAYS,
+        decisions: decisions.length,
+        days,
+        wouldBlock,
+        warns,
+    };
+}
+async function main(argv) {
+    const [command, ...rest] = argv;
+    const flag = (name) => {
+        const i = rest.indexOf(name);
+        return i >= 0 ? rest[i + 1] : undefined;
+    };
+    const has = (name) => rest.includes(name);
+    switch (command) {
+        case 'hook': {
+            const raw = (0, node_fs_1.readFileSync)(0, 'utf8');
+            let input = {};
+            try {
+                input = JSON.parse(raw);
+            }
+            catch {
+                // Unparseable payload: allow. We never break the host over our own bug.
+            }
+            process.stdout.write(JSON.stringify((0, pre_tool_use_1.handlePreToolUse)(input, HOME)));
+            return 0;
+        }
+        case 'replay': {
+            const policy = (0, pre_tool_use_1.loadPolicy)(HOME);
+            const paths = rest.filter((a) => a.endsWith('.jsonl'));
+            const targets = paths.length ? paths : (0, simulate_1.discoverTranscripts)();
+            const summary = (0, simulate_1.replayAll)(targets, policy.thresholds, Number(flag('--min-tokens') ?? 0));
+            if (has('--json')) {
+                process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+            }
+            else {
+                process.stdout.write(`${(0, render_1.renderReplay)(summary, { colour: !has('--no-color'), top: Number(flag('--top') ?? 8) })}\n`);
+            }
+            return 0;
+        }
+        case 'calibrate': {
+            const summary = (0, simulate_1.replayAll)((0, simulate_1.discoverTranscripts)(), defaults_1.DEFAULT_POLICY.thresholds);
+            const result = (0, calibrate_1.calibrate)(summary.sessions);
+            savePolicy(result.policy);
+            const t = result.policy.thresholds;
+            process.stdout.write([
+                `Calibrated from ${result.sessionsUsed} of ${result.sessionsTotal} sessions (${result.sessionsExcluded} excluded as pathological).`,
+                `  raw p90 ${(result.rawWarnP90 / 1e9).toFixed(2)}B  raw p99 ${(result.rawStopP99 / 1e9).toFixed(2)}B`,
+                `  sustained WARN ${(t.sustained.warnTokens / 1e9).toFixed(2)}B   STOP ${(t.sustained.stopTokens / 1e9).toFixed(2)}B`,
+                `  fan-out WARN ${t.fanout.warn}  STOP ${t.fanout.stop}  (not calibrated; validated on real runaway)`,
+                `  burn-debt ${t.burnDebt.enabled ? `ON, baseline ${Math.round(t.burnDebt.baselinePerActiveMinute / 1e6)}M/active-min` : 'off'}`,
+                ...result.notes.map((n) => `  note: ${n}`),
+                `Policy written to ${(0, node_path_1.join)(HOME, 'burn-policy.json')} in SHADOW mode.`,
+            ].join('\n') + '\n');
+            return 0;
+        }
+        case 'status': {
+            const policy = (0, pre_tool_use_1.loadPolicy)(HOME);
+            const e = shadowEligibility();
+            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`,
+                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');
+            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`);
+            return 0;
+        }
+        case 'enforce': {
+            const policy = (0, pre_tool_use_1.loadPolicy)(HOME);
+            const e = shadowEligibility();
+            if (!e.eligible && !has('--force')) {
+                process.stderr.write(`Not eligible yet: ${e.decisions}/${defaults_1.SHADOW_MIN_DECISIONS} decisions, ${e.days.toFixed(1)}/${defaults_1.SHADOW_MIN_DAYS} days. Use --force to override.\n`);
+                return 2;
+            }
+            savePolicy({ ...policy, mode: 'enforce' });
+            process.stdout.write('Enforcement ON. The next STOP will block the spawn.\n');
+            return 0;
+        }
+        case 'shadow': {
+            savePolicy({ ...(0, pre_tool_use_1.loadPolicy)(HOME), mode: 'shadow' });
+            process.stdout.write('Back to shadow mode. Decisions are recorded, nothing is blocked.\n');
+            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`);
+            return 0;
+        }
+        default:
+            process.stdout.write('agentguard-burn <replay|calibrate|status|init|enforce|shadow|resume|hook>\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' +
+                '  enforce [--force]    shadow -> enforce\n' +
+                '  resume --once --reason "..."\n');
+            return command ? 64 : 0;
+    }
+}
+main(process.argv.slice(2)).then((code) => process.exit(code), (error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(4);
+});

package/dist/src/defaults.d.ts

@@ -0,0 +1,30 @@
+import type { Policy, Thresholds } from './types';
+/**
+ * Shipped thresholds.
+ *
+ * These are not intuition. They were fitted against 412 real Claude Code
+ * sessions on the author's machine on 2026-09-03:
+ *
+ *   fan-out 24/40  : on the 172-spawn runaway, STOP at spawn 40 would have
+ *                    prevented 91% of that session's tokens.
+ *   sustained 3.5B/5B : across all 412 sessions this produced exactly 1 STOP,
+ *                    the 9.15B slow grind the fan-out cap missed, 2 WARNs, and
+ *                    409 clean sessions. Zero false STOPs.
+ *
+ * A previous draft shipped a 50M session budget. Routine sessions on the same
+ * machine run 1.4B to 3.5B, so that default would have fired within minutes on
+ * everything and trained the user to ignore the tool. Wrong defaults that get
+ * disabled are worse than no defaults.
+ *
+ * Cache-read ratio was 98% on every one of the 412 sessions, healthy and
+ * pathological alike. It carries no discriminating signal and is deliberately
+ * absent from these thresholds.
+ */
+export declare const DEFAULT_THRESHOLDS: Thresholds;
+/** First-run policy. Shadow: evaluate and record, never block. */
+export declare const DEFAULT_POLICY: Policy;
+/** Idle gaps longer than this do not count as active time. */
+export declare const ACTIVE_GAP_CAP_MS: number;
+/** Shadow must observe this much before enforcement is allowed. */
+export declare const SHADOW_MIN_DECISIONS = 50;
+export declare const SHADOW_MIN_DAYS = 7;

package/dist/src/defaults.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SHADOW_MIN_DAYS = exports.SHADOW_MIN_DECISIONS = exports.ACTIVE_GAP_CAP_MS = exports.DEFAULT_POLICY = exports.DEFAULT_THRESHOLDS = void 0;
+/**
+ * Shipped thresholds.
+ *
+ * These are not intuition. They were fitted against 412 real Claude Code
+ * sessions on the author's machine on 2026-09-03:
+ *
+ *   fan-out 24/40  : on the 172-spawn runaway, STOP at spawn 40 would have
+ *                    prevented 91% of that session's tokens.
+ *   sustained 3.5B/5B : across all 412 sessions this produced exactly 1 STOP,
+ *                    the 9.15B slow grind the fan-out cap missed, 2 WARNs, and
+ *                    409 clean sessions. Zero false STOPs.
+ *
+ * A previous draft shipped a 50M session budget. Routine sessions on the same
+ * machine run 1.4B to 3.5B, so that default would have fired within minutes on
+ * everything and trained the user to ignore the tool. Wrong defaults that get
+ * disabled are worse than no defaults.
+ *
+ * Cache-read ratio was 98% on every one of the 412 sessions, healthy and
+ * pathological alike. It carries no discriminating signal and is deliberately
+ * absent from these thresholds.
+ */
+exports.DEFAULT_THRESHOLDS = {
+    fanout: { warn: 24, stop: 40, maxDepth: 2 },
+    sustained: { warnTokens: 3_500_000_000, stopTokens: 5_000_000_000 },
+    burnDebt: {
+        baselinePerActiveMinute: 0,
+        tolerance: 1.25,
+        warnDebt: 750_000_000,
+        stopDebt: 1_500_000_000,
+        enabled: false,
+    },
+    spawnRate: { windowActiveMinutes: 15, warn: 8, stop: 16, enforce: false },
+    duplicate: { warnReaders: 3 },
+    account: {
+        stopTokens: null,
+        warnTokens: null,
+        windowActiveMinutes: 300,
+        warnConcurrentSessions: 4,
+    },
+};
+/** First-run policy. Shadow: evaluate and record, never block. */
+exports.DEFAULT_POLICY = {
+    mode: 'shadow',
+    thresholds: exports.DEFAULT_THRESHOLDS,
+};
+/** Idle gaps longer than this do not count as active time. */
+exports.ACTIVE_GAP_CAP_MS = 5 * 60 * 1000;
+/** Shadow must observe this much before enforcement is allowed. */
+exports.SHADOW_MIN_DECISIONS = 50;
+exports.SHADOW_MIN_DAYS = 7;