@agentguard-run/burn 0.2.3 → 0.2.6

package/CHANGELOG.md

@@ -1,3 +1,33 @@
+# Changelog
+
+## 0.2.6 (2026-09-19)
+
+- Fix inflated enforcement usage: repeated assistant content blocks and copied child histories now share the same provider response identity as `why`. Persist only usage deltas; rebuild old counters once without replacing their receipt chain head.
+- Fix lifetime fan-out blocking: lifetime count is WARN only, the stop ceiling uses 120 active minutes, and spawn rate defaults to enforcement at 16 proposals within 15 active minutes. Depth above 2 still stops. Atomic reservations use both active windows, including parallel proposals.
+- Fill missing policy fields from defaults with one notice. Preserve explicit settings, including older advisory spawn-rate policies, and bind the normalized policy into new receipt digests.
+- Keep sustained thresholds at WARN 3.5B and STOP 5B. They now fire later because duplicate usage no longer advances the counters. Calibration uses corrected usage and excludes bursts rather than long lifetime spawn counts.
+- Add `blocks [session|all]` with signed receipt context and measured child tokens and list-price economics, separating forks and fresh agents. Reuse the local attribution parser and existing verified pricing table; no transcript contents enter receipts.
+- Keep hook WARN and STOP card text, layout and branding unchanged.
+- Tests: 150 passing by default, one opt-in stress test skipped. The separate 240-process stress run admits exactly 40, denies 200, signs 240 receipts and has no lock failures. All 14 conformance checks pass.
+
+## 0.2.5 (2026-09-18)
+
+- Attribute session usage from measured deltas: fixed-prefix context, cached history, tool output, repeated Read results and conversation. Use bytes only to split a measured increment, with mixed intervals counted as shared.
+- Preserve every recorded token across output, rewrites, child fan-out and the residual. The Method footer explains each bucket, baseline resets and the prior-output subtraction retained in the residual.
+- Keep baseline and event state across responses for correct last-turn shares and category pricing. Repeated usage snapshots retain their original event interval; old pace caches rebuild local metadata once.
+- Validate every bucket against a constructed session, including UTF-8 weights, integer rounding, prefix changes, duplicate events and per-category conservation.
+- Tests: 120 passing by default, one opt-in stress test skipped.
+
+## 0.2.4 (2026-09-18)
+
+- Add local `why`, `rewrites`, `pace`, `statusline` and `pricing` commands. Assistant usage is reconciled by response identity, with unknown attribution kept explicit and child usage identified from transcript metadata.
+- Explain full-prefix cache writes, measured lifetimes, cause evidence and API list cost. Warn on configurable rewrite spend and heavy context crossings without blocking ordinary tools.
+- Observe every Claude Code and Codex tool call. Track cached and uncached ten-minute pace. Forecast limits only from fresh host percentage observations; provide a companion terminal line where Codex cannot run a custom footer command.
+- Bundle dated model pricing and local overrides. Keep unknown models unpriced, content out of persisted metadata, and new reporting paths free of network calls.
+- Raise reservation lock wait to eight seconds, serialize stale-lock retirement, and exclude operational lock-wait failures from enforce eligibility. Old ledgers and receipts remain readable.
+- Validate a 240-process burst: exactly 40 admitted, 200 denied, 240 signed receipts, zero lock failures and a valid chain.
+- Tests: 106 passing by default, one opt-in stress test skipped. The separate stress run also passes.
+
 ## 0.2.3 (2026-09-15)
 
 - Replay evidence refreshed from this machine: 4 STOP, 3 WARN, 431 clean across
@@ -16,8 +46,6 @@
   identifiers, and stop labelling every omitted replay session as clean.
 - Tests: 47 passing by default, one stress test skipped unless AGENTGUARD_STRESS=1.
 
-# Changelog
-
 ## 0.2.2 (2026-09-03)
 
 - Codex: `status` and `init codex --write` now say, every time, that the

package/README.md

@@ -1,28 +1,109 @@
 # @agentguard-run/burn
 
-Local runaway-agent circuit breaker for AI coding agents.
+See where a coding session's tokens went and what the next heavy turn could cost in time and limits. Burn explains recorded usage, warns about large cache rewrites and keeps its existing runaway-session circuit breaker. Everything stays on this machine.
 
-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.
+## Install in five lines
+
+```sh
+npm i -g @agentguard-run/burn
+agentguard-burn init claude
+agentguard-burn init codex
+agentguard-burn statusline
+agentguard-burn why
+```
+
+The two init commands print hook configuration for review. Merge the relevant snippet into your host configuration. They do not write it. For Codex, review and trust the hook through `/hooks`. Upgrading an existing hook requires the new snippet: it matches every tool so pace can update on ordinary tool calls, while admission still gates spawns.
+
+For Claude Code, configure its `statusLine` command as `agentguard-burn statusline`. It receives the host JSON on stdin. Codex 0.154.0 has no external status command slot. Use `agentguard-burn statusline SESSION_ID` in a companion terminal and the native Codex limit indicators. See [host fields and setup](docs/USAGE_AND_PRICING.md#what-the-hosts-expose).
+
+## Why this session
+
+```sh
+agentguard-burn why
+agentguard-burn why SESSION_ID
+agentguard-burn rewrites SESSION_ID
+agentguard-burn rewrites all
+agentguard-burn pace SESSION_ID
+agentguard-burn pricing
+```
+
+A session argument can also be a transcript path. Without one, Burn uses the session environment variable when available, then the most recently modified local transcript. Claude child transcripts are included in `why`. Token shares are shares of recorded tokens, not shares of dollars. Repeated usage records for one provider response count once. Copied Codex history is reconciled before counting new usage.
+
+The table covers instruction stack + system, history re-sent, repeated file reads, subagent fan-out, tool output, conversation, full-prefix rewrites, output and unattributed usage. The fixed-prefix baseline is the first assistant response's measured context. It includes the initial user message, so the label is an operational baseline rather than a direct measurement of instruction files. A rewrite classified as prefix change resets that baseline and is counted in the footer; the new baseline can include history already present at that point.
+
+Later cache reads up to the baseline go to instruction stack + system. Reads above it go to history re-sent. Fresh input plus cache creation is the measured arriving increment. Burn subtracts the previous response's output before assigning that increment to intervening tool results and user messages. Result byte sizes only split that measured total; bytes are never converted into tokens. A result for a previously read Read path goes to re-read files. Mixed user and tool intervals are marked shared and counted in the footer.
+
+Rewrite tokens and child transcript usage keep their own buckets. Prior output deducted from an input increment remains in the unattributed residual so every recorded input and output token is counted exactly once. Missing event evidence also remains there. Integer allocation preserves every token, and the Method footer explains each row.
+
+A full-prefix rewrite writes more than 150,000 tokens and more than half the actual input context. Burn reports the observed cache lifetime and surrounding evidence: idle beyond that lifetime, immediate compaction, first subagent response, or residual prefix change. An unknown lifetime stays unknown. Each write is priced at its measured lifetime, or a range when that lifetime is unavailable.
+
+Every tool hook updates a local pace file under the Burn home. Pace uses ten wall-clock minutes: cached means cache reads; uncached means fresh input, writes and output. The next-hour projection assumes that pace continues. A time-to-limit estimate requires rising, fresh host percentage samples from the same quota pool and reset window. No token-to-limit conversion or cache weighting is assumed. Without sufficient host data, the line says why the limit is unknown.
+
+The new warnings are advisory in both modes. Cache rewrites warn once when their last-hour API list equivalent exceeds $5. A context crossing 500,000 tokens warns about processing time and compaction, estimates a cache rewrite, and suggests a fresh session with a handoff note. These warnings do not deny a tool call.
+
+Optional settings in your existing `burn-policy.json`:
+
+```json
+{
+  "insights": {
+    "rewriteWarnDollarsPerHour": 5,
+    "heavyTurnTokens": 500000
+  }
+}
+```
+
+Merge these fields into the existing policy. All existing thresholds and modes remain supported. Prices are exact-model API list equivalents, not a subscription bill. Unknown models show tokens only. Every rate has a source and verification date. A local override file and full pricing table are documented in [Usage and pricing](docs/USAGE_AND_PRICING.md).
 
 ## Two safety planes
 
-Originally fitted against 412 real Claude Code sessions, then replayed on
-2026-09-15 against 438 sessions. The history shows two independent
-failure shapes that one detector cannot cover:
+Structural limits use active time rather than the age of the session. The
+lifetime spawn count warns at 24 but cannot stop a session on its own. The
+fan-out ceiling permits 40 spawns within the last 120 active minutes and
+stops the next proposal. The separate spawn-rate rule warns at 8 and stops
+candidate 16 within 15 active minutes. Depth above 2 still stops.
+
+Economic limits warn at 3.5B and stop at 5B measured tokens per session.
+Repeated Claude assistant content blocks share one provider response id.
+Their usage and copied child history count once, including later increases
+to a response's recorded usage. Old session counters rebuild once from the
+parent and its available child transcripts, retaining the signed chain head.
+The rebuild places events chronologically. A child usage record discovered
+late on a later hook enters the current active-minute bucket, while session
+and bucket totals remain conserved.
+The same numeric sustained thresholds now fire later because inflated usage
+has been removed. Earlier replay figures in the changelog used the old counts.
+
+Existing policy files keep explicit settings. Missing fields are filled in
+memory, with a one-time notice. In particular, an old explicit
+`spawnRate.enforce: false` remains advisory until you change it. New policies
+default to `true`; `fanout.windowActiveMinutes` defaults to 120. Run calibration
+only when you want it to write a new shadow policy, or set `AGENTGUARD_HOME`
+to a scratch directory to review fitted values first.
+
+## Price a recorded block
 
-| 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 | 59-, 190- and 226-spawn sessions; the 190-spawn session has a 4.35B post-STOP tail (92%) |
-| 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 |
+```sh
+agentguard-burn blocks
+agentguard-burn blocks SESSION_ID
+agentguard-burn blocks all
+```
 
-The 2026-09-15 replay snapshot: **4 STOP, 3 WARN, 431 clean across 438
-sessions and 616 spawns**. Replay hero: **32%** — **10.27B** of **32.58B**
-observed tokens came after a STOP boundary; API-list scenario **$4,639**.
-This is an upper bound assuming no override or restart. Replay does not label
-false positives. Active histories can change the next replay result.
+Each WARN or STOP receipt gets one row with its time, session, detector
+reasons and spawn ordinal. The row includes the session's available child
+count, median and maximum tokens, and median and maximum API list-price
+dollars per child. Forks and fresh agents are reported separately. The
+report reuses the attribution parser and excludes copied provider responses.
+It reads recorded usage only and makes no network calls.
+
+These are list-price equivalents, not a bill or a claim of money saved.
+Economics describe the currently available child transcripts of that session,
+not only the children completed before the receipt. Missing child history or
+unknown model pricing stays unavailable. Unknown cache lifetimes produce a
+price range. A fork is identified by its transcript's fork metadata. Codex child discovery
+requires an explicit parent thread id; unknown inherited-history boundaries
+stay unavailable. Use `blocks all json` for structured output. Session
+attribution uses local receipt identifiers without copying transcript content
+into the ledger.
 
 Cache-read ratio was about 98% in the original calibration, healthy and pathological alike. It
 is shown as an explanation and never used to decide.
@@ -85,7 +166,7 @@ What each host can actually see is stated, not implied:
 | Ollama proxy | none | none | authoritative | `prompt_eval_count` + `eval_count` on the final chunk |
 | vLLM / LM Studio / OpenAI-compatible proxy | none | none | authoritative when the server sends `usage`, else reported missing | non-streaming `usage`, or the final SSE usage event |
 | Cursor (beta) | authoritative | estimated | none | native `subagentStart` deny; hosted-model usage is never exposed |
-| Codex (beta) | authoritative | estimated | estimated | `PreToolUse` on `spawn_agent`; live deny, allow and override canary passed on codex-cli 0.151.0; transcript parsed best-effort |
+| Codex (beta) | authoritative | estimated | estimated | `PreToolUse` on every tool, with admission on `spawn_agent`; live deny, allow and override canary passed on codex-cli 0.151.0; transcript parsed best-effort |
 
 An `OK` from a host that cannot see usage is an OK about spawns, and `status`
 says `usage:n/a` next to it. Missing usage never becomes a guessed zero.
@@ -211,6 +292,11 @@ grabbed the instance it judged, and every write is fenced on the holder's
 own nonce still being on the path. In 0.2.3, bounded, staggered retries prevent
 lock waiters from starving the holder. The Sep 15 audit includes one successful
 240-process run after that fix; it does not establish a 192-run guarantee.
+In 0.2.4, the wait is eight seconds and retirement is serialized before
+renaming an abandoned lock. The fresh 240-process run admitted exactly 40,
+denied 200, signed 240 receipts and had zero lock failures. Operational
+lock-wait failures do not count toward enforce eligibility. See the
+[conservative recovery procedure](docs/USAGE_AND_PRICING.md#reservation-lock-recovery).
 
 Single-machine by design. Two laptops on one account do not share state, and
 that is stated rather than hidden.
@@ -228,5 +314,4 @@ a would-block decision in shadow and blocks new work only in enforce mode.
 ## 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.
+No telemetry. No provider-quota guesses. Account forecasts use only observed host percentages, never an invented allowance or cache weighting.

package/dist/src/adapters/codex.js

@@ -33,11 +33,21 @@ const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const events_1 = require("../events");
 const render_1 = require("../replay/render");
+const live_1 = require("../insights/live");
+const pre_tool_use_1 = require("../hook/pre-tool-use");
 /** Fields this renderer must never emit. Codex rejects the whole object if they appear. */
 exports.CODEX_FORBIDDEN_FIELDS = ['continue', 'stopReason', 'suppressOutput', 'decision', 'reason'];
 const HOST = 'codex';
 const SPAWN_TOOLS = new Set(['Agent', 'spawn_agent', 'Task']);
 function handleCodexHook(raw, gateway, now = Date.now()) {
+    const parsed = parse(raw);
+    if (!parsed)
+        return {};
+    const observation = (0, live_1.observeTool)(gateway.dataDirectory, { session_id: parsed.sessionId, transcript_path: parsed.transcriptPath, tool_name: parsed.toolName }, 'codex', (0, pre_tool_use_1.loadPolicy)(gateway.dataDirectory), now);
+    const output = parsed.event === 'PreToolUse' && SPAWN_TOOLS.has(parsed.toolName) ? handleCodexSpawnHook(raw, gateway, now) : {};
+    return observation.messages.length ? { ...output, systemMessage: [output.systemMessage, ...observation.messages].filter(Boolean).join('\n') } : output;
+}
+function handleCodexSpawnHook(raw, gateway, now) {
     const input = parse(raw);
     if (!input)
         return {};
@@ -190,7 +200,7 @@ function walk(value, path) {
 function codexHooksSnippet(command) {
     return {
         hooks: {
-            PreToolUse: [{ matcher: '^(Agent|spawn_agent)$', hooks: [{ type: 'command', command, timeout: 5 }] }],
+            PreToolUse: [{ matcher: '.*', hooks: [{ type: 'command', command, timeout: 15 }] }],
         },
     };
 }

package/dist/src/adapters/cursor.js

@@ -127,8 +127,8 @@ function cursorHooksSnippet(command) {
     return {
         version: 1,
         hooks: {
-            subagentStart: [{ command, timeout: 5, failClosed: true }],
-            subagentStop: [{ command, timeout: 5 }],
+            subagentStart: [{ command, timeout: 15, failClosed: true }],
+            subagentStop: [{ command, timeout: 15 }],
             sessionEnd: [{ command, timeout: 3 }],
         },
     };

package/dist/src/calibrate.js

@@ -23,7 +23,6 @@
 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.
@@ -69,10 +68,10 @@ function calibrate(sessions, base = defaults_1.DEFAULT_THRESHOLDS) {
     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 healthy = working.filter((s) => !s.fanoutStop && !s.spawnRateStop && 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.`);
+        notes.push(`${excluded} session(s) excluded as already pathological (fan-out, depth or spawn-rate STOP, 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);

package/dist/src/cli.js

@@ -33,6 +33,12 @@ const server_1 = require("./proxy/server");
 const render_1 = require("./replay/render");
 const simulate_1 = require("./replay/simulate");
 const status_1 = require("./status");
+const eligibility_1 = require("./eligibility");
+const sessions_1 = require("./insights/sessions");
+const transcript_1 = require("./insights/transcript");
+const live_1 = require("./insights/live");
+const render_2 = require("./insights/render");
+const blocks_1 = require("./insights/blocks");
 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() {
@@ -66,18 +72,7 @@ function readDecisions() {
         .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,
-    };
+    return (0, eligibility_1.computeShadowEligibility)(readDecisions());
 }
 async function main(argv) {
     const [command, ...rest] = argv;
@@ -87,6 +82,39 @@ async function main(argv) {
     };
     const has = (name) => rest.includes(name);
     switch (command) {
+        case 'blocks': {
+            const session = rest.find(value => value !== 'json' && value !== '--json');
+            const report = (0, blocks_1.blocksReport)(HOME, session, { rates: (0, live_1.readPricing)(HOME, (0, pre_tool_use_1.loadPolicy)(HOME)) });
+            process.stdout.write((rest.includes('json') || has('--json') ? JSON.stringify(report, null, 2) : (0, blocks_1.renderBlocks)(report)) + '\n');
+            return 0;
+        }
+        case 'why': {
+            const location = (0, sessions_1.selectInsightTranscript)(rest.find(value => value !== 'json'));
+            const transcript = (0, transcript_1.readInsightSession)(location.path, { host: location.host, sessionId: location.sessionId });
+            process.stdout.write(rest.includes('json') ? JSON.stringify(transcript, null, 2) + '\n' : (0, render_2.renderWhy)(transcript, (0, live_1.readPricing)(HOME, (0, pre_tool_use_1.loadPolicy)(HOME))) + '\n');
+            return 0;
+        }
+        case 'rewrites': {
+            const session = rest.find(value => value !== 'json');
+            const locations = session === 'all' ? (0, sessions_1.discoverInsightTranscripts)() : [(0, sessions_1.selectInsightTranscript)(session)];
+            const transcripts = locations.map(location => (0, transcript_1.readInsightTranscript)(location.path, { host: location.host, sessionId: location.sessionId }));
+            const rates = (0, live_1.readPricing)(HOME, (0, pre_tool_use_1.loadPolicy)(HOME));
+            process.stdout.write(rest.includes('json') ? JSON.stringify((0, render_2.rewriteReport)(transcripts, rates), null, 2) + '\n' : (0, render_2.renderRewrites)(transcripts, rates) + '\n');
+            return 0;
+        }
+        case 'pricing': {
+            process.stdout.write((0, render_2.renderPricing)((0, live_1.readPricing)(HOME, (0, pre_tool_use_1.loadPolicy)(HOME))) + '\n');
+            return 0;
+        }
+        case 'statusline':
+        case 'pace': {
+            const raw = command === 'statusline' && !process.stdin.isTTY ? readStdinJson() : null;
+            const payload = raw && typeof raw === 'object' ? raw : {};
+            const location = (0, sessions_1.selectInsightTranscript)(payload.transcript_path || rest[0] || payload.session_id);
+            const observation = (0, live_1.observeTool)(HOME, { ...payload, session_id: payload.session_id || location.sessionId, transcript_path: location.path }, location.host, (0, pre_tool_use_1.loadPolicy)(HOME));
+            process.stdout.write((observation.snapshot ? (0, live_1.renderStatusLine)(observation.snapshot) : 'AgentGuard pace unavailable: local usage metadata is not readable.') + '\n');
+            return observation.snapshot ? 0 : 1;
+        }
         case 'hook': {
             const raw = (0, node_fs_1.readFileSync)(0, 'utf8');
             let input = {};
@@ -121,7 +149,8 @@ async function main(argv) {
                 `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)`,
+                `  fan-out lifetime WARN ${t.fanout.warn}; STOP above ${t.fanout.stop} spawns in ${t.fanout.windowActiveMinutes ?? 120} active minutes; depth above ${t.fanout.maxDepth}`,
+                `  spawn-rate WARN ${t.spawnRate?.warn ?? 8}; STOP ${t.spawnRate?.stop ?? 16} in ${t.spawnRate?.windowActiveMinutes ?? 15} active minutes; ${t.spawnRate?.enforce === false ? 'shadow only' : 'enforcing in enforce mode'}`,
                 `  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.`,
@@ -136,11 +165,14 @@ async function main(argv) {
             const override = (0, override_1.readOverride)(HOME);
             process.stdout.write([
                 `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)'}`,
+                `thresholds: fan-out lifetime WARN ${policy.thresholds.fanout.warn}; STOP above ${policy.thresholds.fanout.stop} spawns in ${policy.thresholds.fanout.windowActiveMinutes ?? 120} active minutes; depth above ${policy.thresholds.fanout.maxDepth}`,
+                `spawn-rate: WARN ${policy.thresholds.spawnRate?.warn ?? 8}; STOP ${policy.thresholds.spawnRate?.stop ?? 16} in ${policy.thresholds.spawnRate?.windowActiveMinutes ?? 15} active minutes; ${policy.thresholds.spawnRate?.enforce === false ? 'shadow only' : 'enforcing in enforce mode'}`,
+                `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  (agentguard-burn enforce)' : `no (need ${defaults_1.SHADOW_MIN_DECISIONS} decisions and ${defaults_1.SHADOW_MIN_DAYS} days)`}`,
+                `lock-wait failures excluded from eligibility: ${e.excludedLockWaitFailures}`,
                 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))),
@@ -270,7 +302,13 @@ async function main(argv) {
             return 0;
         }
         default:
-            process.stdout.write('agentguard-burn <replay|calibrate|status|init|enforce|shadow|resume|proxy|conformance>\n' +
+            process.stdout.write('agentguard-burn <blocks|why|rewrites|pace|statusline|pricing|replay|calibrate|status|init|enforce|shadow|resume|proxy|conformance>\n' +
+                '  blocks [session|all]   stored WARN/STOP receipts and that session\'s child usage\n' +
+                '  why [session]       token attribution and API list-price equivalents\n' +
+                '  rewrites [session|all]   full-prefix cache writes by cause\n' +
+                '  pace [session]      ten-minute pace and next-hour projection\n' +
+                '  statusline [session]   one-line local status; accepts Claude status JSON\n' +
+                '  pricing             verified model rates and local overrides\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, hook health, every host\n' +

package/dist/src/conformance.d.ts

@@ -1,10 +1,13 @@
 /**
  * Conformance: the same failure, through every door, stops at the same step.
  *
- * Two fixtures, fitted on real sessions:
+ * 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.
+ *               must be spawn 41 with spawn-rate advisory. Every spawn-capable
+ *               adapter replays it.
+ *   rate        default policy warns at candidate 8 and stops candidate 16.
+ *               Pending proposals count even before a transcript sees them.
  *   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.

package/dist/src/conformance.js

@@ -2,10 +2,13 @@
 /**
  * Conformance: the same failure, through every door, stops at the same step.
  *
- * Two fixtures, fitted on real sessions:
+ * 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.
+ *               must be spawn 41 with spawn-rate advisory. Every spawn-capable
+ *               adapter replays it.
+ *   rate        default policy warns at candidate 8 and stops candidate 16.
+ *               Pending proposals count even before a transcript sees them.
  *   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.
@@ -35,11 +38,11 @@ const STOP_AT = defaults_1.DEFAULT_THRESHOLDS.fanout.stop + 1; // 41
 const CALL_TOKENS = 250_000_000;
 const GRIND_WARN_CALL = Math.floor(defaults_1.DEFAULT_THRESHOLDS.sustained.warnTokens / CALL_TOKENS) + 1; // 15
 const GRIND_STOP_CALL = Math.floor(defaults_1.DEFAULT_THRESHOLDS.sustained.stopTokens / CALL_TOKENS) + 1; // 21
-function freshHome() {
+function freshHome(enforceRate = false) {
     const home = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), 'agb-conf-'));
     // These fixtures share a home to inspect all receipts. Test only the
     // session boundaries here; account concurrency has its own integration tests.
-    const policy = { mode: 'enforce', thresholds: { ...defaults_1.DEFAULT_THRESHOLDS, account: { ...defaults_1.DEFAULT_THRESHOLDS.account, warnConcurrentSessions: Number.MAX_SAFE_INTEGER } } };
+    const policy = { mode: 'enforce', thresholds: { ...defaults_1.DEFAULT_THRESHOLDS, spawnRate: { ...defaults_1.DEFAULT_THRESHOLDS.spawnRate, enforce: enforceRate }, account: { ...defaults_1.DEFAULT_THRESHOLDS.account, warnConcurrentSessions: Number.MAX_SAFE_INTEGER } } };
     (0, node_fs_1.writeFileSync)((0, node_path_1.join)(home, 'burn-policy.json'), JSON.stringify(policy));
     return home;
 }
@@ -52,6 +55,7 @@ function boundaries(steps) {
 // Hook adapters only expose the first finding's summary. Fan-out is evaluated
 // first in the core, so when it fires it is the one in the message.
 const FANOUT_WARN = /agent spawns this session/;
+const RATE_WARN = /spawns in the last 15 active minutes/;
 function stepFromMessage(denied, message, warnPattern) {
     if (denied)
         return 'STOP';
@@ -60,34 +64,36 @@ function stepFromMessage(denied, message, warnPattern) {
     return warnPattern.test(message) ? 'WARN' : 'WARN:other';
 }
 // ---- storms --------------------------------------------------------------
-function stormRaw(home) {
-    const burn = (0, raw_api_1.createRawApiGuard)({ sessionId: 'storm-raw', home });
+function stormRaw(home, rate = false, startObserved = true) {
+    const burn = (0, raw_api_1.createRawApiGuard)({ sessionId: `${rate ? 'rate' : 'storm'}-raw${startObserved ? '' : '-pending'}`, home });
     const steps = [];
     for (let i = 1; i <= STORM; i++) {
         const lease = burn.beforeSpawn({ parentDepth: 0 });
         const d = lease.decision;
-        const fanout = d.report.findings.find((f) => f.detector === 'fanout');
+        const fanout = d.report.findings.find((f) => f.detector === (rate ? 'spawn_rate' : 'fanout'));
         steps.push(d.blocked ? 'STOP' : fanout?.verdict === 'WARN' ? 'WARN' : d.verdict === 'WARN' ? 'WARN:other' : 'OK');
-        if (!d.blocked)
+        if (!d.blocked && startObserved)
             lease.started();
     }
     return boundaries(steps);
 }
-function stormCursor(home) {
+function stormCursor(home, rate = false) {
+    const sessionId = rate ? 'rate-cursor' : 'storm-cursor';
     const gateway = new gateway_1.Gateway(home);
     const steps = [];
     for (let i = 1; i <= STORM; i++) {
-        const out = (0, cursor_1.handleCursorHook)({ hook_event_name: 'subagentStart', conversation_id: 'storm-cursor', subagent_id: `sub-${i}`, parent_conversation_id: 'storm-cursor' }, gateway);
-        steps.push(stepFromMessage(out.permission === 'deny', out.agent_message, FANOUT_WARN));
+        const out = (0, cursor_1.handleCursorHook)({ hook_event_name: 'subagentStart', conversation_id: sessionId, subagent_id: `sub-${i}`, parent_conversation_id: sessionId }, gateway);
+        steps.push(stepFromMessage(out.permission === 'deny', out.agent_message, rate ? RATE_WARN : FANOUT_WARN));
     }
     return boundaries(steps);
 }
-function stormCodex(home) {
+function stormCodex(home, rate = false) {
+    const sessionId = rate ? 'rate-codex' : 'storm-codex';
     const gateway = new gateway_1.Gateway(home);
     const steps = [];
     for (let i = 1; i <= STORM; i++) {
-        const out = (0, codex_1.handleCodexHook)({ hook_event_name: 'PreToolUse', session_id: 'storm-codex', tool_name: 'Agent', tool_use_id: `call-${i}` }, gateway);
-        steps.push(stepFromMessage(out.hookSpecificOutput?.permissionDecision === 'deny', out.systemMessage, FANOUT_WARN));
+        const out = (0, codex_1.handleCodexHook)({ hook_event_name: 'PreToolUse', session_id: sessionId, tool_name: 'spawn_agent', tool_use_id: `call-${i}` }, gateway);
+        steps.push(stepFromMessage(out.hookSpecificOutput?.permissionDecision === 'deny', out.systemMessage, rate ? RATE_WARN : FANOUT_WARN));
     }
     return boundaries(steps);
 }
@@ -221,17 +227,23 @@ async function composite(home) {
 // ---- runner --------------------------------------------------------------
 async function runConformance() {
     const home = freshHome();
+    const rateHome = freshHome(true);
     const checks = [];
     const expectStorm = (name, b) => checks.push({
         name,
         ok: b.firstWarn === WARN_AT && b.firstStop === STOP_AT,
         detail: `fan-out WARN at ${b.firstWarn} (want ${WARN_AT}), STOP at ${b.firstStop} (want ${STOP_AT})${b.firstAnyWarn !== null && b.firstAnyWarn < WARN_AT ? `; advisory spawn-rate WARN at ${b.firstAnyWarn}` : ''}`,
     });
+    const expectRate = (name, b) => checks.push({ name, ok: b.firstWarn === defaults_1.DEFAULT_THRESHOLDS.spawnRate.warn && b.firstStop === defaults_1.DEFAULT_THRESHOLDS.spawnRate.stop, detail: `default spawn-rate WARN at ${b.firstWarn} (want 8), STOP at ${b.firstStop} (want 16)` });
     const expectGrind = (name, b) => checks.push({ name, ok: b.firstWarn === GRIND_WARN_CALL && b.firstStop === GRIND_STOP_CALL, detail: `first WARN call ${b.firstWarn} (want ${GRIND_WARN_CALL}), first STOP call ${b.firstStop} (want ${GRIND_STOP_CALL})` });
     try {
         expectStorm('storm · raw middleware', stormRaw(home));
         expectStorm('storm · cursor subagentStart', stormCursor(home));
         expectStorm('storm · codex PreToolUse', stormCodex(home));
+        expectRate('rate · raw middleware', stormRaw(rateHome, true));
+        expectRate('rate · cursor subagentStart', stormCursor(rateHome, true));
+        expectRate('rate · codex PreToolUse', stormCodex(rateHome, true));
+        expectRate('rate · pending only, no observed spawns', stormRaw(rateHome, true, false));
         checks.push({ name: 'depth · raw middleware', ok: depthRaw(home), detail: 'depth 1 and 2 admitted, depth 3 denied' });
         expectGrind('grind · raw middleware', grindRaw(home));
         const p = await grindProxy(home);
@@ -241,17 +253,18 @@ async function runConformance() {
         const c = await composite(home);
         checks.push({ name: 'composite · middleware tree + proxy usage, one session', ok: c.ok, detail: c.detail });
         // Receipts: every spawn decision above was signed; verify the chain tail.
-        const receipts = require('node:fs')
-            .readFileSync((0, node_path_1.join)(home, 'receipts.ndjson'), 'utf8')
+        const receipts = [home, rateHome].flatMap((directory) => require('node:fs')
+            .readFileSync((0, node_path_1.join)(directory, 'receipts.ndjson'), 'utf8')
             .split('\n')
             .filter(Boolean)
-            .map((l) => JSON.parse(l));
+            .map((l) => JSON.parse(l)));
         const allValid = receipts.every((r) => (0, receipt_1.verifyReceipt)(r));
         const contentFree = !receipts.some((r) => JSON.stringify(r.payload).match(/transcript|prompt|\/Users\/|content/i));
         checks.push({ name: `receipts · ${receipts.length} signed, all verify, content-free`, ok: allValid && contentFree && receipts.length > 0, detail: `${receipts.length} receipts, verify=${allValid}, content-free=${contentFree}` });
     }
     finally {
         (0, node_fs_1.rmSync)(home, { recursive: true, force: true });
+        (0, node_fs_1.rmSync)(rateHome, { recursive: true, force: true });
     }
     const ok = checks.every((c) => c.ok);
     const text = [

package/dist/src/defaults.d.ts

@@ -3,10 +3,13 @@ import type { Policy, Thresholds } from './types';
  * Shipped thresholds.
  *
  * Originally fitted against 412 real Claude Code sessions. Replayed on the
- * author's machine on 2026-09-15: 438 sessions, 616 spawns, 32.58B tokens;
- * 4 STOP, 3 WARN, 431 clean. The observed post-STOP tail is 10.27B (32%).
- * Fan-out 24/40 stops before spawn 41 on the 59-, 190- and 226-spawn
- * sessions; sustained 3.5B/5B catches the 9.15B / 26-spawn slow grind.
+ * author's machine on 2026-09-18: 453 sessions, 662 spawns, 36.30B recorded tokens;
+ * 5 STOP, 3 WARN, 445 clean. The recorded post-STOP tail is 10.80B (30%).
+ * That historical snapshot used inflated repeated streaming usage counts and
+ * a lifetime fan-out ceiling. Version 0.2.6 deduplicates usage and limits fan-out
+ * to 120 active minutes. Lifetime 24 warns; above 40 in the window stops.
+ * Spawn rate 8/16 over 15 active minutes warns/stops by default. Sustained
+ * thresholds remain 3.5B/5B pending review of deduplicated calibration.
  * This is a dated replay snapshot and an upper bound, not labelled evidence
  * of false-positive rates or guaranteed savings.
  *

package/dist/src/defaults.js

@@ -5,10 +5,13 @@ exports.SHADOW_MIN_DAYS = exports.SHADOW_MIN_DECISIONS = exports.ACTIVE_GAP_CAP_
  * Shipped thresholds.
  *
  * Originally fitted against 412 real Claude Code sessions. Replayed on the
- * author's machine on 2026-09-15: 438 sessions, 616 spawns, 32.58B tokens;
- * 4 STOP, 3 WARN, 431 clean. The observed post-STOP tail is 10.27B (32%).
- * Fan-out 24/40 stops before spawn 41 on the 59-, 190- and 226-spawn
- * sessions; sustained 3.5B/5B catches the 9.15B / 26-spawn slow grind.
+ * author's machine on 2026-09-18: 453 sessions, 662 spawns, 36.30B recorded tokens;
+ * 5 STOP, 3 WARN, 445 clean. The recorded post-STOP tail is 10.80B (30%).
+ * That historical snapshot used inflated repeated streaming usage counts and
+ * a lifetime fan-out ceiling. Version 0.2.6 deduplicates usage and limits fan-out
+ * to 120 active minutes. Lifetime 24 warns; above 40 in the window stops.
+ * Spawn rate 8/16 over 15 active minutes warns/stops by default. Sustained
+ * thresholds remain 3.5B/5B pending review of deduplicated calibration.
  * This is a dated replay snapshot and an upper bound, not labelled evidence
  * of false-positive rates or guaranteed savings.
  *
@@ -22,7 +25,7 @@ exports.SHADOW_MIN_DAYS = exports.SHADOW_MIN_DECISIONS = exports.ACTIVE_GAP_CAP_
  * absent from these thresholds.
  */
 exports.DEFAULT_THRESHOLDS = {
-    fanout: { warn: 24, stop: 40, maxDepth: 2 },
+    fanout: { warn: 24, stop: 40, maxDepth: 2, windowActiveMinutes: 120 },
     sustained: { warnTokens: 3_500_000_000, stopTokens: 5_000_000_000 },
     burnDebt: {
         baselinePerActiveMinute: 0,
@@ -31,7 +34,7 @@ exports.DEFAULT_THRESHOLDS = {
         stopDebt: 1_500_000_000,
         enabled: false,
     },
-    spawnRate: { windowActiveMinutes: 15, warn: 8, stop: 16, enforce: false },
+    spawnRate: { windowActiveMinutes: 15, warn: 8, stop: 16, enforce: true },
     duplicate: { warnReaders: 3 },
     account: {
         stopTokens: null,

package/dist/src/detectors/evaluate.d.ts

@@ -5,15 +5,14 @@
  * failure modes:
  *
  *   structural  - fan-out. Many agents, each re-sending context. The 190-spawn
- *                 session. Caught by an absolute spawn cap.
+ *                 session. Caught by spawn windows over active time.
  *   economic    - sustained burn. Few agents, long session, enormous total. The
  *                 9.15B session with only 26 spawns, which a spawn cap cannot
  *                 see. Caught by a cumulative token ceiling and burn debt.
  *
- * Verdict is the maximum severity across findings. Advisory detectors (spawn
- * rate, duplicate work, cache ratio) can raise WARN but never STOP, because
- * each has a plausible benign explanation and a false STOP is what gets a
- * safety tool uninstalled.
+ * Verdict is the maximum severity across findings. Lifetime fan-out and
+ * duplicate work are advisory; only a recent burst, depth or economic
+ * threshold can stop new work. Spawn rate can be made advisory by policy.
  */
 import type { BurnReport, SessionState, Thresholds } from '../types';
 /**