@agentguard-run/burn 0.2.5 → 0.2.6

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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.

package/README.md

@@ -56,23 +56,54 @@ Merge these fields into the existing policy. All existing thresholds and modes r
 
 ## Two safety planes
 
-Originally fitted against 412 real Claude Code sessions, then replayed on
-2026-09-18 against 453 sessions. The history shows 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 | 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 |
-
-The 2026-09-18 replay snapshot: **5 STOP, 3 WARN, 445 clean across 453
-sessions and 662 spawns**. Replay hero: **30%**. **10.80B** of **36.30B**
-recorded tokens came after a STOP boundary; API-list scenario **$4,832**.
-This is an upper bound assuming no override or restart. Replay does not label
-false positives. Active histories can change the next replay result. The existing replay
-counters retain their published behavior and can include repeated streaming
-usage records. The new `why` report reconciles provider responses, so its
-totals can differ. Do not treat replay as a reconciled invoice.
+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
+
+```sh
+agentguard-burn blocks
+agentguard-burn blocks SESSION_ID
+agentguard-burn blocks all
+```
+
+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.

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

@@ -38,6 +38,7 @@ 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() {
@@ -81,6 +82,12 @@ 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 });
@@ -142,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.`,
@@ -157,7 +165,9 @@ 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}`,
@@ -292,7 +302,8 @@ async function main(argv) {
             return 0;
         }
         default:
-            process.stdout.write('agentguard-burn <why|rewrites|pace|statusline|pricing|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' +

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

@@ -5,10 +5,11 @@ import type { Policy, Thresholds } from './types';
  * Originally fitted against 412 real Claude Code sessions. Replayed on the
  * 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%).
- * Legacy replay counters can include repeated streaming usage records. The
- * new insights report reconciles provider responses instead.
- * 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.
+ * 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

@@ -7,10 +7,11 @@ exports.SHADOW_MIN_DAYS = exports.SHADOW_MIN_DECISIONS = exports.ACTIVE_GAP_CAP_
  * Originally fitted against 412 real Claude Code sessions. Replayed on the
  * 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%).
- * Legacy replay counters can include repeated streaming usage records. The
- * new insights report reconciles provider responses instead.
- * 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.
+ * 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.
  *
@@ -24,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,
@@ -33,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';
 /**

package/dist/src/detectors/evaluate.js

@@ -6,20 +6,20 @@
  * 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.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.evaluate = evaluate;
 exports.fmt = fmt;
 const account_1 = require("../state/account");
+const defaults_1 = require("../defaults");
 const session_1 = require("../state/session");
 const RANK = { OK: 0, WARN: 1, STOP: 2 };
 function worst(a, b) {
@@ -36,12 +36,14 @@ function evaluate(state, thresholds, proposedSpawnDepth = null, account) {
     // ---- structural plane: fan-out --------------------------------------
     // Count the proposal itself. "Allow through 40, deny candidate 41."
     const effectiveSpawns = state.spawnCount + (proposedSpawnDepth !== null ? 1 : 0);
-    if (effectiveSpawns > thresholds.fanout.stop) {
+    const fanoutWindow = thresholds.fanout.windowActiveMinutes ?? defaults_1.DEFAULT_THRESHOLDS.fanout.windowActiveMinutes;
+    const recentFanout = (0, session_1.windowSum)(state.spawnsByActiveMinute, state.activeMinutes, fanoutWindow) + (proposedSpawnDepth !== null ? 1 : 0);
+    if (recentFanout > thresholds.fanout.stop) {
         findings.push({
             detector: 'fanout',
             verdict: 'STOP',
-            summary: `Spawn ${effectiveSpawns} would exceed the fan-out ceiling of ${thresholds.fanout.stop}.`,
-            observed: effectiveSpawns,
+            summary: `Spawn ${recentFanout} would exceed the fan-out ceiling of ${thresholds.fanout.stop}.`,
+            observed: recentFanout,
             threshold: thresholds.fanout.stop,
         });
         verdict = worst(verdict, 'STOP');
@@ -110,8 +112,8 @@ function evaluate(state, thresholds, proposedSpawnDepth = null, account) {
             verdict = worst(verdict, 'WARN');
         }
     }
-    // ---- advisory: spawn rate over active time -------------------------
-    const recentSpawns = (0, session_1.windowSum)(state.spawnsByActiveMinute, state.activeMinutes, thresholds.spawnRate.windowActiveMinutes);
+    // ---- structural plane: spawn rate over active time -----------------
+    const recentSpawns = (0, session_1.windowSum)(state.spawnsByActiveMinute, state.activeMinutes, thresholds.spawnRate.windowActiveMinutes) + (proposedSpawnDepth !== null ? 1 : 0);
     if (recentSpawns >= thresholds.spawnRate.stop) {
         const severity = thresholds.spawnRate.enforce ? 'STOP' : 'WARN';
         findings.push({
@@ -199,7 +201,7 @@ function prescribe(state, findings, t) {
         out.push(`Let the ${Math.min(state.spawnCount, 4)} most useful running agents finish; do not replace them.`);
     }
     else if (has('fanout')) {
-        out.push(`You are at ${state.spawnCount} spawns; ${t.fanout.stop - state.spawnCount} remain before the ceiling. Plan for it.`);
+        out.push(`You are at ${state.spawnCount} spawns; ${Math.max(0, t.fanout.stop - (0, session_1.windowSum)(state.spawnsByActiveMinute, state.activeMinutes, t.fanout.windowActiveMinutes ?? defaults_1.DEFAULT_THRESHOLDS.fanout.windowActiveMinutes))} remain before the ceiling. Plan for it.`);
     }
     if (state.maxDepth >= 2) {
         out.push('Agents are spawning agents. Make the root orchestrator the only process allowed to spawn.');

package/dist/src/gateway.js

@@ -41,6 +41,7 @@ const pre_tool_use_1 = require("./hook/pre-tool-use");
 const override_1 = require("./override");
 const receipt_1 = require("./receipt");
 const reservations_1 = require("./state/reservations");
+const spawn_window_1 = require("./state/spawn-window");
 const account_1 = require("./state/account");
 const session_1 = require("./state/session");
 const MAX_SEEN_EVENTS = 4000;
@@ -217,14 +218,7 @@ class Gateway {
                 }
                 const live = new Map(meta.liveSpawns);
                 const proposedDepth = event.proposedDepth ?? (event.issuerId !== undefined && live.has(event.issuerId) ? live.get(event.issuerId) + 1 : 1);
-                const report = (0, evaluate_1.evaluate)(state, policy.thresholds, proposedDepth, { sessions: (0, account_1.readAccountSessions)(this.home, state, event.at), now: event.at });
-                const reservation = tx.reserve({
-                    sessionId: event.sessionId,
-                    toolUseId: event.spawnId,
-                    observedSpawns: state.spawnCount,
-                    ceiling: policy.thresholds.fanout.stop,
-                    now: event.at,
-                });
+                const { report, reservation } = (0, spawn_window_1.evaluateSpawnReservation)(tx, state, policy.thresholds, proposedDepth, event.spawnId, event.at, { sessions: (0, account_1.readAccountSessions)(this.home, state, event.at), now: event.at });
                 const wouldBlock = report.verdict === 'STOP' || !reservation.allowed;
                 const verdict = wouldBlock ? 'STOP' : report.verdict;
                 // Session-scope STOPs need a session we trust. Fan-out is session scope.

package/dist/src/history/claude-transcript.d.ts

@@ -12,6 +12,8 @@
  * truncated or replaced file resets the cursor rather than reading garbage.
  */
 import type { BurnEvent } from '../types';
+/** Component maxima for one provider response, never transcript contents. */
+export type UsageSnapshot = [input: number, output: number, cacheCreation: number, cacheRead: number];
 export interface ReaderCursor {
     /** Byte just after the last complete newline we processed. */
     offset: number;
@@ -20,6 +22,11 @@ export interface ReaderCursor {
     malformedLines: number;
     /** Resolved depth per line uuid, for spawn-depth attribution. */
     depthByUuid: Map<string, number>;
+    /** Optional and additive so callers with pre-0.2.6 cursors still load. */
+    usageVersion?: 1;
+    usageByMessage?: Map<string, UsageSnapshot>;
+    /** Child file cursors share usageByMessage with their parent. */
+    children?: Map<string, ReaderCursor>;
 }
 export declare function newCursor(): ReaderCursor;
 interface RawLine {
@@ -28,6 +35,7 @@ interface RawLine {
     parentUuid?: string;
     isSidechain?: boolean;
     message?: {
+        id?: unknown;
         usage?: Record<string, number | undefined>;
         content?: unknown;
     };
@@ -39,8 +47,18 @@ export declare function normaliseLine(raw: RawLine, cursor: ReaderCursor): BurnE
  * and advances the cursor. O(new bytes), never O(file size) after the first
  * read.
  */
-export declare function readIncremental(path: string, cursor: ReaderCursor): BurnEvent[];
-/** Convenience for replay and tests: read a whole transcript from the start. */
+export interface ReadOptions {
+    /** Legacy-state rebuilds must not replace totals after an unreadable file. */
+    throwOnOpenError?: boolean;
+}
+export declare function readIncremental(path: string, cursor: ReaderCursor, options?: ReadOptions): BurnEvent[];
+/**
+ * Fold the parent's tool events and its stored children's usage into one
+ * session. Child histories can contain copied parent tool calls, so only their
+ * usage deltas contribute here. The parent's observed spawn count stays intact.
+ */
+export declare function readSessionIncremental(path: string, cursor: ReaderCursor, options?: ReadOptions): BurnEvent[];
+/** Convenience for replay and tests: read a session and its own stored children. */
 export declare function readAll(path: string): {
     events: BurnEvent[];
     cursor: ReaderCursor;