@agentguard-run/burn 0.2.2 → 0.2.5

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 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
+  438 sessions and 616 spawns. Hero: 32%, 32.58B observed, 10.27B after STOP,
+  $4,639 API-list scenario. Fan-out sessions have 59, 190 and 226 spawns;
+  the sustained-burn session has 9.15B tokens and 26 spawns. These are a dated
+  snapshot and an upper bound, without a false-positive classification.
+- Account concurrency warnings and optional active-window token WARN/STOP
+  budgets read both hook and gateway session files. Shadow never blocks.
+- Claude hook decisions now write the same content-free, chained Ed25519
+  receipts as gateway decisions, with host/action on ledger rows. Old rows and
+  receipts remain readable. Session refresh and receipt chaining share the lock.
+- Add an opt-in 240-hook-process stress test at cap 40. Staggered lock retries
+  reduce contention while preserving the existing fail-closed deadline.
+- Correct the license package/file enumeration, use synthetic Codex fixture
+  identifiers, and stop labelling every omitted replay session as clean.
+- Tests: 47 passing by default, one stress test skipped unless AGENTGUARD_STRESS=1.
+
 ## 0.2.2 (2026-09-03)
 
 - Codex: `status` and `init codex --write` now say, every time, that the
@@ -75,7 +111,7 @@ The cross-tool layer. One policy, one lock, one receipt across hosts.
   contention). Under 240 concurrent hook processes this admitted 41 to 46
   spawns against a cap of 40. Lock instances now carry a nonce; reclaims
   are verified against the instance judged; writes are fenced on the
-  holder's nonce. 192 runs at 240 concurrent processes admit exactly 40.
+  holder's nonce. See 0.2.3 for the reproducible 240-process audit result.
 - A lock owner record could be read half-written and parsed as "held since
   1970". The record is now written atomically and malformed records are
   never trusted.
@@ -92,7 +128,8 @@ The cross-tool layer. One policy, one lock, one receipt across hosts.
 
 ### Unchanged
 - The Claude Code hook, transcript reader, detectors and thresholds. The
-  existing 24 tests pass as they were.
+  original tests remain covered; 0.2.2 has 40 passing tests, and 0.2.3 has
+  47 default passing tests plus one opt-in stress test.
 
 ## 0.1.1 (2026-09-03)
 - The artifact: block-digit hero, per-session sparklines with the STOP marked,

package/LICENSE

@@ -2,13 +2,12 @@ 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
+This software is the npm package @agentguard-run/burn, 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
+type definitions and compiled output under dist/src/, the command-line entry
+point dist/src/cli.js, the fixtures under fixtures/, and the root files
+README.md, CHANGELOG.md, LICENSE 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.
 
@@ -40,8 +39,8 @@ Licensor. All patent rights are expressly reserved.
 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/
+  - The documentation file README.md
+  - The test fixtures under fixtures/
 
   Copyright (c) 2026 Dunecrest Ventures Inc.
 
@@ -74,8 +73,8 @@ 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
+dist/src/, and the root files CHANGELOG.md, LICENSE and package.json 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.
 

package/README.md

@@ -1,25 +1,80 @@
 # @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
 
-Fitted against 412 real Claude Code sessions, which showed two independent
+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 | 174- and 226-spawn sessions; STOP would have intercepted 91% of the runaway |
+| 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 |
 
-Across all 412 sessions: 3 STOP, 2 WARN, 407 clean. Zero false STOPs.
+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.
 
-Cache-read ratio was 98% on every session, healthy and pathological alike. It
+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.
 
 ## Start with replay, not with the hook
@@ -80,7 +135,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.
@@ -185,22 +240,47 @@ 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, through
-the Claude hook and again through the Cursor hook.
+reservation processes against a cap of 40 and asserts exactly 40 are admitted,
+and separately exercises 60 Cursor hook processes. The opt-in stress test runs
+240 actual Claude hook processes against cap 40:
+
+```sh
+npm run build
+AGENTGUARD_STRESS=1 node --test dist/tests/stress.test.js
+```
+
+It checks exactly 40 admitted and 200 denied, verifies the receipt chain for
+coordinated decisions, and reports lock failures separately. Infrastructure
+failures deny in enforce mode before a receipt can be chained, as in the gateway.
 
 0.2.0 fixed the lock itself. Under 240 concurrent hook processes the 0.1
 lock could tear down a live sibling's lock (a waiter judged "owner is dead"
 about an instance that had already been released and replaced) and admit
 41 to 46. Lock instances now carry a nonce; a reclaim only counts if it
 grabbed the instance it judged, and every write is fenced on the holder's
-own nonce still being on the path. 192 runs at 240 concurrent processes:
-exactly 40, every time.
+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.
 
+## Account thresholds
+
+`account.warnConcurrentSessions` warns when more than that many sessions have
+been active on this machine in the last 30 minutes, matching `status` liveness.
+Optional `account.warnTokens` and `account.stopTokens` sum the last
+`account.windowActiveMinutes` of token buckets from each active session.
+Both token limits default to `null`. Closed gateway sessions are excluded;
+hook and gateway session files are both read. WARN never blocks. STOP records
+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/cli.js

@@ -33,6 +33,11 @@ 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 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 +71,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 +81,33 @@ async function main(argv) {
     };
     const has = (name) => rest.includes(name);
     switch (command) {
+        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 = {};
@@ -141,6 +162,7 @@ async function main(argv) {
                 `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 +292,12 @@ 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 <why|rewrites|pace|statusline|pricing|replay|calibrate|status|init|enforce|shadow|resume|proxy|conformance>\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.js

@@ -37,7 +37,9 @@ const GRIND_WARN_CALL = Math.floor(defaults_1.DEFAULT_THRESHOLDS.sustained.warnT
 const GRIND_STOP_CALL = Math.floor(defaults_1.DEFAULT_THRESHOLDS.sustained.stopTokens / CALL_TOKENS) + 1; // 21
 function freshHome() {
     const home = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), 'agb-conf-'));
-    const policy = { mode: 'enforce', thresholds: defaults_1.DEFAULT_THRESHOLDS };
+    // 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 } } };
     (0, node_fs_1.writeFileSync)((0, node_path_1.join)(home, 'burn-policy.json'), JSON.stringify(policy));
     return home;
 }

package/dist/src/defaults.d.ts

@@ -2,14 +2,15 @@ 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.
+ * 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.
+ * This is a dated replay snapshot and an upper bound, not labelled evidence
+ * of false-positive rates or guaranteed savings.
  *
  * 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

package/dist/src/defaults.js

@@ -4,14 +4,15 @@ exports.SHADOW_MIN_DAYS = exports.SHADOW_MIN_DECISIONS = exports.ACTIVE_GAP_CAP_
 /**
  * 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.
+ * 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.
+ * This is a dated replay snapshot and an upper bound, not labelled evidence
+ * of false-positive rates or guaranteed savings.
  *
  * 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

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

@@ -4,7 +4,7 @@
  * Two independent safety planes, because the data showed two independent
  * failure modes:
  *
- *   structural  - fan-out. Many agents, each re-sending context. The 172-spawn
+ *   structural  - fan-out. Many agents, each re-sending context. The 190-spawn
  *                 session. Caught by an absolute spawn cap.
  *   economic    - sustained burn. Few agents, long session, enormous total. The
  *                 9.15B session with only 26 spawns, which a spawn cap cannot
@@ -21,5 +21,8 @@ import type { BurnReport, SessionState, Thresholds } from '../types';
  * would have if the pending spawn were allowed; the decision must be about the
  * proposal, not about a violation the transcript has already recorded.
  */
-export declare function evaluate(state: SessionState, thresholds: Thresholds, proposedSpawnDepth?: number | null): BurnReport;
+export declare function evaluate(state: SessionState, thresholds: Thresholds, proposedSpawnDepth?: number | null, account?: {
+    sessions: SessionState[];
+    now: number;
+}): BurnReport;
 export declare function fmt(n: number): string;

package/dist/src/detectors/evaluate.js

@@ -5,7 +5,7 @@
  * Two independent safety planes, because the data showed two independent
  * failure modes:
  *
- *   structural  - fan-out. Many agents, each re-sending context. The 172-spawn
+ *   structural  - fan-out. Many agents, each re-sending context. The 190-spawn
  *                 session. Caught by an absolute spawn cap.
  *   economic    - sustained burn. Few agents, long session, enormous total. The
  *                 9.15B session with only 26 spawns, which a spawn cap cannot
@@ -19,6 +19,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.evaluate = evaluate;
 exports.fmt = fmt;
+const account_1 = require("../state/account");
 const session_1 = require("../state/session");
 const RANK = { OK: 0, WARN: 1, STOP: 2 };
 function worst(a, b) {
@@ -29,7 +30,7 @@ function worst(a, b) {
  * would have if the pending spawn were allowed; the decision must be about the
  * proposal, not about a violation the transcript has already recorded.
  */
-function evaluate(state, thresholds, proposedSpawnDepth = null) {
+function evaluate(state, thresholds, proposedSpawnDepth = null, account) {
     const findings = [];
     let verdict = 'OK';
     // ---- structural plane: fan-out --------------------------------------
@@ -132,6 +133,27 @@ function evaluate(state, thresholds, proposedSpawnDepth = null) {
         });
         verdict = worst(verdict, 'WARN');
     }
+    // Machine activity uses status's 30-minute liveness window. Token budgets
+    // sum each live session's last configured number of active-minute buckets.
+    if (account && thresholds.account) {
+        const t = thresholds.account;
+        const live = account.sessions.filter((s) => account.now - s.lastEventAt <= account_1.ACTIVE_SESSION_WINDOW_MS);
+        if (live.length > t.warnConcurrentSessions) {
+            findings.push({ detector: 'account', verdict: 'WARN',
+                summary: `${live.length} concurrent active sessions on this machine; warning threshold is ${t.warnConcurrentSessions}.`,
+                observed: live.length, threshold: t.warnConcurrentSessions });
+            verdict = worst(verdict, 'WARN');
+        }
+        const tokens = live.reduce((sum, s) => sum + (0, session_1.windowSum)(s.tokensByActiveMinute, s.activeMinutes, t.windowActiveMinutes), 0);
+        const severity = t.stopTokens != null && tokens >= t.stopTokens ? 'STOP'
+            : t.warnTokens != null && tokens >= t.warnTokens ? 'WARN' : null;
+        if (severity) {
+            findings.push({ detector: 'account', verdict: severity,
+                summary: `Active sessions consumed ${fmt(tokens)} tokens over their last ${t.windowActiveMinutes} active minutes.`,
+                observed: tokens, threshold: (severity === 'STOP' ? t.stopTokens : t.warnTokens) });
+            verdict = worst(verdict, severity);
+        }
+    }
     // ---- advisory: duplicate work --------------------------------------
     let duplicated = 0;
     let worstSurfaceReaders = 0;
@@ -192,6 +214,8 @@ function prescribe(state, findings, t) {
     if (has('burn_debt')) {
         out.push('Burn is sustained above your own baseline. Narrow the task or split it into a new session.');
     }
+    if (has('account'))
+        out.push('Pause new work across active sessions on this machine until the account window clears.');
     if (has('duplicate_work')) {
         out.push('Assign one reader per file and pass a short digest down, instead of letting every agent re-read it.');
     }

package/dist/src/eligibility.d.ts

@@ -0,0 +1,17 @@
+export interface ShadowEligibility {
+    eligible: boolean;
+    decisions: number;
+    days: number;
+    wouldBlock: number;
+    warns: number;
+    excludedLockWaitFailures: number;
+}
+/** Existing lock-failure ledger rows remain readable without a schema change. */
+export declare function isLockWaitFailure(row: Readonly<Record<string, unknown>>): boolean;
+/**
+ * A reservation-lock timeout is an operational failure, not an observation of
+ * a threshold. Keep it in the audit ledger but do not let a burst of timeouts
+ * satisfy the observation count or start the enforcement waiting period.
+ * Older decision rows need no new fields and retain their existing behavior.
+ */
+export declare function computeShadowEligibility(rows: ReadonlyArray<Readonly<Record<string, unknown>>>, now?: number): ShadowEligibility;

package/dist/src/eligibility.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLockWaitFailure = isLockWaitFailure;
+exports.computeShadowEligibility = computeShadowEligibility;
+const defaults_1 = require("./defaults");
+/** Existing lock-failure ledger rows remain readable without a schema change. */
+function isLockWaitFailure(row) {
+    return row.failClosed === true && typeof row.reason === 'string'
+        && /\bcould not acquire (?:the )?reservation lock\b/i.test(row.reason);
+}
+/**
+ * A reservation-lock timeout is an operational failure, not an observation of
+ * a threshold. Keep it in the audit ledger but do not let a burst of timeouts
+ * satisfy the observation count or start the enforcement waiting period.
+ * Older decision rows need no new fields and retain their existing behavior.
+ */
+function computeShadowEligibility(rows, now = Date.now()) {
+    const decisions = rows.filter(row => !isLockWaitFailure(row));
+    const first = decisions.length ? Number(decisions[0].at) : now;
+    const days = (now - first) / 86_400_000;
+    return {
+        eligible: decisions.length >= defaults_1.SHADOW_MIN_DECISIONS && days >= defaults_1.SHADOW_MIN_DAYS,
+        decisions: decisions.length,
+        days,
+        wouldBlock: decisions.filter(row => row.wouldDeny === true).length,
+        warns: decisions.filter(row => row.verdict === 'WARN').length,
+        excludedLockWaitFailures: rows.length - decisions.length,
+    };
+}

package/dist/src/gateway.d.ts

@@ -80,6 +80,8 @@ export interface GatewayOptions {
 }
 export declare class Gateway {
     private readonly home;
+    /** Shared local storage for optional content-free usage observations. */
+    get dataDirectory(): string;
     private readonly store;
     private readonly signer;
     private readonly now;