@agentguard-run/burn 0.2.5 → 0.2.7

package/dist/src/history/claude-transcript.js

@@ -16,14 +16,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.newCursor = newCursor;
 exports.normaliseLine = normaliseLine;
 exports.readIncremental = readIncremental;
+exports.readSessionIncremental = readSessionIncremental;
 exports.readAll = readAll;
 const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const transcript_1 = require("../insights/transcript");
 const CHUNK = 64 * 1024;
 const MAX_LINE = 4 * 1024 * 1024;
 const SPAWN_TOOLS = new Set(['Agent', 'Task']);
 const SURFACE_TOOLS = new Set(['Read', 'Grep', 'Glob']);
 function newCursor() {
-    return { offset: 0, size: 0, malformedLines: 0, depthByUuid: new Map() };
+    return { offset: 0, size: 0, malformedLines: 0, depthByUuid: new Map(), usageVersion: 1, usageByMessage: new Map() };
 }
 function toMillis(value) {
     if (typeof value !== 'string' || value.length === 0)
@@ -40,11 +43,22 @@ function normaliseLine(raw, cursor) {
     if (at === null)
         return null;
     const usage = raw.message?.usage ?? {};
-    const cacheRead = nonNegative(usage.cache_read_input_tokens);
-    const tokens = nonNegative(usage.input_tokens) +
-        nonNegative(usage.output_tokens) +
-        nonNegative(usage.cache_creation_input_tokens) +
-        cacheRead;
+    const snapshot = [nonNegative(usage.input_tokens), nonNegative(usage.output_tokens),
+        nonNegative(usage.cache_creation_input_tokens), nonNegative(usage.cache_read_input_tokens)];
+    let tokens = snapshot.reduce((sum, value) => sum + value, 0);
+    let cacheRead = snapshot[3];
+    // Claude writes one row per content block, all carrying the same message.id.
+    // Fork copies preserve that id too. Match the attribution parser's global
+    // identity and per-category maxima, emitting only newly observed usage.
+    if (raw.message?.id !== undefined && tokens > 0) {
+        const id = (0, transcript_1.providerResponseIdentity)('claude', raw.message.id);
+        cursor.usageByMessage ??= new Map();
+        const previous = cursor.usageByMessage.get(id) ?? [0, 0, 0, 0];
+        const merged = snapshot.map((value, index) => Math.max(value, previous[index]));
+        tokens = merged.reduce((sum, value, index) => sum + value - previous[index], 0);
+        cacheRead = merged[3] - previous[3];
+        cursor.usageByMessage.set(id, merged);
+    }
     // Depth attribution: a line's depth is its parent's depth, plus one if the
     // host flagged it as a sidechain (subagent) line. Unknown parents are root.
     const parentDepth = raw.parentUuid ? cursor.depthByUuid.get(raw.parentUuid) ?? 0 : 0;
@@ -91,17 +105,14 @@ function normaliseLine(raw, cursor) {
         parentUuid: raw.parentUuid,
     };
 }
-/**
- * Read every complete line appended since the cursor. Returns the new events
- * and advances the cursor. O(new bytes), never O(file size) after the first
- * read.
- */
-function readIncremental(path, cursor) {
+function readIncremental(path, cursor, options = {}) {
     let fd;
     try {
         fd = (0, node_fs_1.openSync)(path, 'r');
     }
-    catch {
+    catch (error) {
+        if (options.throwOnOpenError)
+            throw error;
         return [];
     }
     try {
@@ -167,9 +178,39 @@ function readIncremental(path, cursor) {
         (0, node_fs_1.closeSync)(fd);
     }
 }
-/** Convenience for replay and tests: read a whole transcript from the start. */
+/**
+ * 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.
+ */
+function readSessionIncremental(path, cursor, options = {}) {
+    cursor.usageByMessage ??= new Map();
+    cursor.children ??= new Map();
+    const events = readIncremental(path, cursor, options);
+    const directory = (0, node_path_1.join)(path.replace(/\.jsonl$/, ''), 'subagents');
+    let names;
+    try {
+        names = (0, node_fs_1.readdirSync)(directory).filter(name => name.endsWith('.jsonl')).sort();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return events;
+        throw error;
+    }
+    for (const name of names) {
+        const child = cursor.children.get(name) ?? newCursor();
+        child.usageByMessage = cursor.usageByMessage;
+        cursor.children.set(name, child);
+        for (const event of readIncremental((0, node_path_1.join)(directory, name), child, options)) {
+            if (event.tokens > 0 || event.cacheRead > 0)
+                events.push({ ...event, spawns: [], surfaces: [], sidechain: true });
+        }
+    }
+    return events.sort((a, b) => a.at - b.at);
+}
+/** Convenience for replay and tests: read a session and its own stored children. */
 function readAll(path) {
     const cursor = newCursor();
-    const events = readIncremental(path, cursor);
+    const events = readSessionIncremental(path, cursor);
     return { events, cursor };
 }

package/dist/src/hook/pre-tool-use.d.ts

@@ -14,8 +14,8 @@
  * cannot fail closed if Claude Code times the hook out, so the hot path does
  * as little as possible.
  */
-import { type ReaderCursor } from '../history/claude-transcript';
-import type { BurnReport, Policy, SessionState } from '../types';
+import { type ReaderCursor, type UsageSnapshot } from '../history/claude-transcript';
+import type { BurnReport, SessionState } from '../types';
 export interface HookInput {
     session_id?: string;
     transcript_path?: string;
@@ -35,13 +35,17 @@ export interface HookOutput {
         permissionDecisionReason: string;
     };
 }
+export interface PersistedReaderCursor {
+    offset: number;
+    size: number;
+    malformedLines: number;
+    depthByUuid: [string, number][];
+    usageVersion?: 1;
+    usageByMessage?: [string, UsageSnapshot][];
+    children?: [string, PersistedReaderCursor][];
+}
 export interface PersistedSession {
-    cursor: {
-        offset: number;
-        size: number;
-        malformedLines: number;
-        depthByUuid: [string, number][];
-    };
+    cursor: PersistedReaderCursor;
     state: Omit<SessionState, 'tokensByActiveMinute' | 'spawnsByActiveMinute' | 'surfaceReaders'> & {
         tokensByActiveMinute: [number, number][];
         spawnsByActiveMinute: [number, number][];
@@ -60,7 +64,7 @@ export declare function inflateHookSession(raw: PersistedSession): SessionState;
  * and the one that matters is the nineteenth.
  */
 export declare function findingSignature(report: BurnReport): string;
-export declare function loadPolicy(home: string): Policy;
+export { loadPolicy } from '../policy';
 /** Refresh session state from the transcript. Cheap: only new bytes are read. */
 export declare function refreshSession(home: string, sessionId: string, transcriptPath: string): {
     cursor: ReaderCursor;

package/dist/src/hook/pre-tool-use.js

@@ -16,9 +16,9 @@
  * as little as possible.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPolicy = void 0;
 exports.inflateHookSession = inflateHookSession;
 exports.findingSignature = findingSignature;
-exports.loadPolicy = loadPolicy;
 exports.refreshSession = refreshSession;
 exports.handlePreToolUse = handlePreToolUse;
 exports.settingsSnippet = settingsSnippet;
@@ -28,11 +28,11 @@ const receipt_1 = require("../receipt");
 const account_1 = require("../state/account");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
-const evaluate_1 = require("../detectors/evaluate");
+const spawn_window_1 = require("../state/spawn-window");
 const claude_transcript_1 = require("../history/claude-transcript");
 const reservations_1 = require("../state/reservations");
 const session_1 = require("../state/session");
-const defaults_1 = require("../defaults");
+const policy_1 = require("../policy");
 const override_1 = require("../override");
 const render_1 = require("../replay/render");
 const live_1 = require("../insights/live");
@@ -49,20 +49,31 @@ function inflateHookSession(raw) {
         surfaceReaders: new Map(raw.state.surfaceReaders.map(([k, v]) => [k, new Set(v)])),
     };
 }
+function inflateCursor(raw, shared) {
+    const usageByMessage = shared ?? new Map(raw.usageByMessage ?? []);
+    return { ...raw, depthByUuid: new Map(raw.depthByUuid), usageByMessage,
+        children: new Map((raw.children ?? []).map(([name, child]) => [name, inflateCursor(child, usageByMessage)])) };
+}
+function persistCursor(cursor, child = false) {
+    return { offset: cursor.offset, size: cursor.size, malformedLines: cursor.malformedLines, depthByUuid: [...cursor.depthByUuid],
+        usageVersion: cursor.usageVersion,
+        ...(!child ? { usageByMessage: [...(cursor.usageByMessage ?? [])] } : {}),
+        ...(cursor.children?.size ? { children: [...cursor.children].map(([name, value]) => [name, persistCursor(value, true)]) } : {}) };
+}
 function loadSession(home, sessionId, firstEventAt) {
     try {
         const raw = JSON.parse((0, node_fs_1.readFileSync)(sessionFile(home, sessionId), 'utf8'));
-        const cursor = { ...raw.cursor, depthByUuid: new Map(raw.cursor.depthByUuid) };
-        return { cursor, state: inflateHookSession(raw), notified: raw.notified ?? '', lastReceipt: raw.lastReceipt ?? null };
+        return { cursor: inflateCursor(raw.cursor), state: inflateHookSession(raw), notified: raw.notified ?? '', lastReceipt: raw.lastReceipt ?? null,
+            fresh: false, needsRebuild: raw.cursor.usageVersion !== 1 || !Array.isArray(raw.cursor.usageByMessage) };
     }
     catch {
-        return { cursor: (0, claude_transcript_1.newCursor)(), state: (0, session_1.newSessionState)(sessionId, firstEventAt), notified: '', lastReceipt: null };
+        return { cursor: (0, claude_transcript_1.newCursor)(), state: (0, session_1.newSessionState)(sessionId, firstEventAt), notified: '', lastReceipt: null, fresh: true, needsRebuild: false };
     }
 }
 function saveSession(home, cursor, state, notified, lastReceipt) {
     (0, node_fs_1.mkdirSync)((0, node_path_1.join)(home, 'sessions'), { recursive: true, mode: 0o700 });
     const persisted = {
-        cursor: { offset: cursor.offset, size: cursor.size, malformedLines: cursor.malformedLines, depthByUuid: [...cursor.depthByUuid] },
+        cursor: persistCursor(cursor),
         state: {
             ...state,
             tokensByActiveMinute: [...state.tokensByActiveMinute],
@@ -88,32 +99,52 @@ function findingSignature(report) {
         .sort()
         .join('|');
 }
-function loadPolicy(home) {
-    try {
-        const parsed = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(home, 'burn-policy.json'), 'utf8'));
-        if (parsed && (parsed.mode === 'shadow' || parsed.mode === 'enforce') && parsed.thresholds)
-            return parsed;
-    }
-    catch {
-        /* no policy yet: shadow defaults */
-    }
-    return defaults_1.DEFAULT_POLICY;
-}
+var policy_2 = require("../policy");
+Object.defineProperty(exports, "loadPolicy", { enumerable: true, get: function () { return policy_2.loadPolicy; } });
 function recordDecision(home, entry) {
     (0, node_fs_1.mkdirSync)(home, { recursive: true, mode: 0o700 });
     (0, node_fs_1.appendFileSync)((0, node_path_1.join)(home, 'decisions.ndjson'), `${JSON.stringify(entry)}\n`, { mode: 0o600 });
 }
 /** Refresh session state from the transcript. Cheap: only new bytes are read. */
 function refreshSession(home, sessionId, transcriptPath) {
-    const { cursor, state, notified, lastReceipt } = loadSession(home, sessionId, Date.now());
+    const loaded = loadSession(home, sessionId, Date.now());
+    let { cursor, state, fresh } = loaded;
+    const { notified, lastReceipt } = loaded;
     const before = state.spawnCount;
-    const events = (0, claude_transcript_1.readIncremental)(transcriptPath, cursor);
+    // Old offsets cannot tell us which repeated rows inflated their totals.
+    // Rebuild once from locally recorded evidence, retaining the signed chain
+    // head and notification state. Never replace old counts with an empty read
+    // when the transcript has disappeared or cannot be opened.
+    if (loaded.needsRebuild) {
+        try {
+            (0, node_fs_1.accessSync)(transcriptPath, node_fs_1.constants.R_OK);
+        }
+        catch {
+            return { cursor, state, newSpawns: 0, notified };
+        }
+        cursor = (0, claude_transcript_1.newCursor)();
+        state = (0, session_1.newSessionState)(sessionId, Date.now());
+        fresh = true;
+    }
+    let events;
+    try {
+        events = (0, claude_transcript_1.readSessionIncremental)(transcriptPath, cursor, { throwOnOpenError: loaded.needsRebuild });
+    }
+    catch (error) {
+        if (!loaded.needsRebuild)
+            throw error;
+        // Opening can fail after the access check, including on a stored child.
+        // Retain the old cursor so the next refresh retries the complete rebuild.
+        return { cursor: loaded.cursor, state: loaded.state, newSpawns: 0, notified };
+    }
+    if (fresh && events.length > 0)
+        state = (0, session_1.newSessionState)(sessionId, events[0].at);
     for (const event of events)
         (0, session_1.applyEvent)(state, event);
     if (events.length > 0 && state.startedAt > events[0].at)
         state.startedAt = events[0].at;
     saveSession(home, cursor, state, notified, lastReceipt);
-    return { cursor, state, newSpawns: state.spawnCount - before, notified };
+    return { cursor, state, newSpawns: Math.max(0, state.spawnCount - before), notified };
 }
 function rememberNotified(home, sessionId, signature) {
     try {
@@ -128,7 +159,7 @@ function rememberNotified(home, sessionId, signature) {
     }
 }
 function handlePreToolUse(input, home, now = Date.now()) {
-    const observation = (0, live_1.observeTool)(home, input, 'claude', loadPolicy(home), now);
+    const observation = (0, live_1.observeTool)(home, input, 'claude', (0, policy_1.loadPolicy)(home), now);
     const output = handleSpawnPreToolUse(input, home, now);
     if (!observation.messages.length)
         return output;
@@ -139,7 +170,7 @@ function handleSpawnPreToolUse(input, home, now) {
     if (!SPAWN_TOOLS.has(toolName) || !input.session_id || !input.transcript_path) {
         return { continue: true, suppressOutput: true };
     }
-    const policy = loadPolicy(home);
+    const policy = (0, policy_1.loadPolicy)(home);
     const store = new reservations_1.ReservationStore(home);
     try {
         const signer = receipt_1.ReceiptSigner.loadOrCreate(home);
@@ -152,14 +183,7 @@ function handleSpawnPreToolUse(input, home, now) {
             // Depth of the proposed child: the issuing agent's depth plus one. A hook
             // fired inside a subagent carries agent_id; treat that as depth 1 issuer.
             const proposedDepth = input.agent_id ? 2 : 1;
-            const report = (0, evaluate_1.evaluate)(state, policy.thresholds, proposedDepth, { sessions: (0, account_1.readAccountSessions)(home, state, now), now });
-            const reservation = tx.reserve({
-                sessionId: input.session_id,
-                toolUseId: input.tool_use_id ?? `${input.session_id}:${now}`,
-                observedSpawns: state.spawnCount,
-                ceiling: policy.thresholds.fanout.stop,
-                now,
-            });
+            const { report, reservation } = (0, spawn_window_1.evaluateSpawnReservation)(tx, state, policy.thresholds, proposedDepth, input.tool_use_id ?? `${input.session_id}:${now}`, now, { sessions: (0, account_1.readAccountSessions)(home, state, now), now });
             const shouldDeny = report.verdict === 'STOP' || !reservation.allowed;
             const reason = shouldDeny ? buildDenyReason(report, reservation) : '';
             // The audited override: only consulted when a block is about to happen.
@@ -227,7 +251,9 @@ function handleSpawnPreToolUse(input, home, now) {
 function buildDenyReason(report, _reservation) {
     // Claude Code shows this reason to the user. A box reads as an alarm; a
     // sentence reads as a log line. Colour is off: the host decides rendering.
-    return (0, render_1.renderStop)(report, { colour: false });
+    // Claude trims leading whitespace before adding Error:. A zero-width word
+    // joiner preserves the blank first line, keeping that prefix off the frame.
+    return '\u2060\n' + (0, render_1.renderStop)(report, { colour: false });
 }
 function deny(reason) {
     return {

package/dist/src/insights/blocks.d.ts

@@ -0,0 +1,61 @@
+import { type DollarRange, type PricingTable } from './pricing';
+import { type TranscriptLocation } from './sessions';
+import type { InsightTranscript } from './types';
+export interface BlockReceipt {
+    line: number;
+    at: number | null;
+    sessionId?: string;
+    sessionDigest?: string;
+    verdict: 'STOP' | 'WARN';
+    detectors: string[];
+    spawnNumber: number | null;
+    blocked: boolean | null;
+}
+export interface ChildEconomics {
+    child: string;
+    kind: 'fork' | 'fresh';
+    forkContextRef: boolean;
+    tokens: number | null;
+    usd: DollarRange | null;
+    unknownModels: string[];
+}
+export interface ChildStatistics {
+    count: number;
+    measuredCount: number;
+    pricedCount: number;
+    medianTokens: number | null;
+    maxTokens: number | null;
+    medianUsd: DollarRange | null;
+    maxUsd: DollarRange | null;
+}
+export interface SessionEconomics {
+    available: boolean;
+    children: ChildEconomics[];
+    all: ChildStatistics;
+    forks: ChildStatistics;
+    fresh: ChildStatistics;
+    notes: string[];
+}
+export interface BlocksReport {
+    receipts: Array<BlockReceipt & {
+        session: string;
+    }>;
+    sessions: Array<{
+        session: string;
+        economics: SessionEconomics;
+    }>;
+    malformedReceiptLines: number;
+}
+/** Read signed envelopes and earlier flat rows without requiring new fields. */
+export declare function readBlockReceipts(filename: string): {
+    receipts: BlockReceipt[];
+    malformedLines: number;
+};
+export declare function childStatistics(children: ChildEconomics[]): ChildStatistics;
+/** Use the attribution parser for all hosts; only explicit lineage owns a child. */
+export declare function readSessionEconomics(location: TranscriptLocation, locations: TranscriptLocation[], rates?: PricingTable, cache?: Map<string, InsightTranscript>): SessionEconomics;
+export declare function blocksReport(home: string, session?: string, options?: {
+    locations?: TranscriptLocation[];
+    rates?: PricingTable;
+}): BlocksReport;
+export declare function renderBlocks(report: BlocksReport): string;

package/dist/src/insights/blocks.js

@@ -0,0 +1,243 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readBlockReceipts = readBlockReceipts;
+exports.childStatistics = childStatistics;
+exports.readSessionEconomics = readSessionEconomics;
+exports.blocksReport = blocksReport;
+exports.renderBlocks = renderBlocks;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const receipt_1 = require("../receipt");
+const live_1 = require("./live");
+const pricing_1 = require("./pricing");
+const render_1 = require("./render");
+const sessions_1 = require("./sessions");
+const transcript_1 = require("./transcript");
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {};
+const identifier = (value) => typeof value === 'string' && /^[A-Za-z0-9_.:/-]{1,128}$/.test(value) ? value : undefined;
+const count = (value) => Number.isSafeInteger(value) && Number(value) >= 0 ? Number(value) : null;
+/** Read signed envelopes and earlier flat rows without requiring new fields. */
+function readBlockReceipts(filename) {
+    let text;
+    try {
+        text = (0, node_fs_1.readFileSync)(filename, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { receipts: [], malformedLines: 0 };
+        throw error;
+    }
+    const receipts = [];
+    let malformedLines = 0;
+    for (const [index, line] of text.split('\n').entries()) {
+        if (!line.trim())
+            continue;
+        let row;
+        try {
+            row = record(JSON.parse(line));
+        }
+        catch {
+            malformedLines++;
+            continue;
+        }
+        const payload = Object.keys(record(row.payload)).length ? record(row.payload) : row;
+        if (payload.verdict !== 'STOP' && payload.verdict !== 'WARN')
+            continue;
+        const measured = record(payload.measured);
+        const atValue = payload.at ?? payload.timestamp;
+        const at = typeof atValue === 'string' ? Date.parse(atValue) : typeof atValue === 'number' ? atValue : NaN;
+        const findings = Array.isArray(payload.findings) ? payload.findings.map(item => record(item).detector) : [];
+        const reasons = Array.isArray(payload.reasons) ? payload.reasons : [payload.detector, ...findings];
+        const detectors = [...new Set(reasons.flatMap(reason => {
+                if (typeof reason !== 'string')
+                    return [];
+                const match = /^([a-z][a-z0-9_-]{0,63})(?::(?:WARN|STOP))?$/.exec(reason);
+                return match ? [match[1]] : [];
+            }))];
+        const sessionId = identifier(payload.sessionId ?? payload.session_id);
+        const sessionDigest = typeof payload.sessionDigest === 'string' && /^[a-f0-9]{64}$/i.test(payload.sessionDigest) ? payload.sessionDigest.toLowerCase() : undefined;
+        receipts.push({ line: index + 1, at: Number.isFinite(at) && Math.abs(at) <= 8.64e15 ? at : null,
+            ...(sessionId ? { sessionId } : {}), ...(sessionDigest ? { sessionDigest } : {}),
+            verdict: payload.verdict, detectors, spawnNumber: count(measured.sessionSpawns ?? payload.sessionSpawns ?? payload.spawns),
+            blocked: typeof payload.blocked === 'boolean' ? payload.blocked : null });
+    }
+    return { receipts, malformedLines };
+}
+const median = (values) => {
+    if (!values.length)
+        return null;
+    const sorted = [...values].sort((a, b) => a - b), middle = Math.floor(sorted.length / 2);
+    return sorted.length % 2 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2;
+};
+function childStatistics(children) {
+    const measured = children.filter(child => child.tokens !== null), priced = children.filter(child => child.usd !== null);
+    return { count: children.length, measuredCount: measured.length, pricedCount: priced.length,
+        medianTokens: median(measured.map(child => child.tokens)), maxTokens: measured.length ? Math.max(...measured.map(child => child.tokens)) : null,
+        // Dollar statistics never silently omit an unpriced child from the cohort.
+        medianUsd: children.length && priced.length === children.length ? { min: median(priced.map(child => child.usd.min)), max: median(priced.map(child => child.usd.max)) } : null,
+        maxUsd: children.length && priced.length === children.length ? { min: Math.max(...priced.map(child => child.usd.min)), max: Math.max(...priced.map(child => child.usd.max)) } : null };
+}
+const unavailable = (note) => ({ available: false, children: [], all: childStatistics([]), forks: childStatistics([]), fresh: childStatistics([]), notes: [note] });
+const locationId = (location) => location.host === 'codex'
+    ? /([a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})$/i.exec(location.sessionId)?.[1] ?? location.sessionId
+    : location.sessionId;
+/** Use the attribution parser for all hosts; only explicit lineage owns a child. */
+function readSessionEconomics(location, locations, rates = {}, cache = new Map()) {
+    const load = (item, spawnedSession = false) => {
+        let parsed = cache.get(item.path);
+        if (!parsed) {
+            parsed = (0, transcript_1.readInsightTranscript)(item.path, { host: item.host, sessionId: locationId(item), spawnedSession });
+            cache.set(item.path, parsed);
+        }
+        return parsed;
+    };
+    let parent;
+    try {
+        parent = load(location);
+    }
+    catch {
+        return unavailable('Session transcript is missing or unreadable; child usage is unavailable.');
+    }
+    const parentIds = new Set([location.sessionId, locationId(location), parent.state.lineage?.sessionId].filter((value) => Boolean(value)));
+    const children = [], notes = [];
+    if (location.host === 'claude') {
+        const directory = (0, node_path_1.join)(location.path.replace(/\.jsonl$/, ''), 'subagents');
+        let names;
+        try {
+            names = (0, node_fs_1.readdirSync)(directory).filter(name => name.endsWith('.jsonl')).sort();
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                names = [];
+                notes.push('No child transcript directory was found. This does not establish that the session spawned no agents.');
+            }
+            else
+                return unavailable('Child transcript directory is unreadable; child usage is unavailable.');
+        }
+        for (const name of names) {
+            try {
+                const child = load({ path: (0, node_path_1.join)(directory, name), host: 'claude', sessionId: (0, node_path_1.basename)(name, '.jsonl'), modifiedAt: 0 }, true);
+                if (child.state.lineage?.parentSessionId && !parentIds.has(child.state.lineage.parentSessionId)) {
+                    notes.push('A child file with a different recorded parent was excluded.');
+                    continue;
+                }
+                children.push({ id: (0, node_path_1.basename)(name, '.jsonl'), transcript: child });
+            }
+            catch {
+                notes.push('A child transcript could not be read; its usage is unavailable.');
+            }
+        }
+    }
+    else {
+        for (const item of locations.filter(candidate => candidate.host === 'codex' && candidate.path !== location.path)) {
+            try {
+                const child = load(item, true);
+                if (child.state.lineage?.parentSessionId && parentIds.has(child.state.lineage.parentSessionId))
+                    children.push({ id: locationId(item), transcript: child });
+            }
+            catch {
+                notes.push('A Codex transcript could not be read; child discovery may be incomplete.');
+            }
+        }
+        notes.push('Codex children require an explicit parent thread id. Inherited usage without a verifiable boundary is unavailable.');
+    }
+    const parentUsage = new Set(parent.turns.map(turn => turn.id));
+    // Shared provider ids collapse both streaming updates and fork history copies.
+    const own = (0, transcript_1.deduplicateTurns)(children.flatMap(child => child.transcript.turns).filter(turn => !parentUsage.has(turn.id)));
+    const ownedByChild = new Map();
+    own.forEach(turn => ownedByChild.set(turn.sessionId, [...ownedByChild.get(turn.sessionId) ?? [], turn]));
+    const rows = children.map(({ id, transcript }) => {
+        const turns = ownedByChild.get(transcript.sessionId) ?? [];
+        const unknownBoundary = transcript.state.forkHistoryBoundaryUnknown === true;
+        const prices = turns.map(turn => (0, pricing_1.priceTurn)(turn, rates));
+        return { child: id, kind: transcript.state.lineage?.forked ? 'fork' : 'fresh', forkContextRef: transcript.state.lineage?.forkContextRef === true,
+            tokens: unknownBoundary || !turns.length ? null : turns.reduce((sum, turn) => sum + (0, render_1.totalTokens)(turn), 0),
+            usd: unknownBoundary || !turns.length ? null : (0, render_1.sumPrices)(prices.map(price => price.usd)),
+            unknownModels: [...new Set(prices.filter(price => price.usd === null).map(price => price.model ?? 'missing model id'))] };
+    });
+    if (!rows.length && !notes.length)
+        notes.push('No owned child transcripts were found; child economics are unavailable, not evidence of zero spawns.');
+    return { available: true, children: rows, all: childStatistics(rows), forks: childStatistics(rows.filter(child => child.kind === 'fork')),
+        fresh: childStatistics(rows.filter(child => child.kind === 'fresh')), notes: [...new Set(notes)] };
+}
+function blocksReport(home, session, options = {}) {
+    const { receipts, malformedLines } = readBlockReceipts((0, node_path_1.join)(home, 'receipts.ndjson'));
+    const locations = options.locations ?? (0, sessions_1.discoverInsightTranscripts)();
+    const aliases = new Map(), digests = new Map();
+    for (const location of locations)
+        for (const alias of new Set([location.sessionId, locationId(location)])) {
+            if (!aliases.has(alias))
+                aliases.set(alias, location);
+            if (!digests.has((0, receipt_1.sha256)(alias)))
+                digests.set((0, receipt_1.sha256)(alias), location);
+        }
+    let selected;
+    let requested = session;
+    if (session !== 'all') {
+        requested = session || process.env.AGENTGUARD_SESSION_ID || process.env.CLAUDE_SESSION_ID || process.env.CODEX_THREAD_ID;
+        try {
+            selected = (0, sessions_1.selectInsightTranscript)(requested, locations.filter(item => !/[\\/]subagents[\\/]/.test(item.path)));
+        }
+        catch {
+            if (!requested)
+                throw new Error('No current session transcript found. Use agentguard-burn blocks all for stored receipts.');
+        }
+        if (selected) {
+            aliases.set(selected.sessionId, selected);
+            digests.set((0, receipt_1.sha256)(selected.sessionId), selected);
+        }
+    }
+    const selectedIds = new Set([requested, selected?.sessionId, selected && locationId(selected)].filter((value) => Boolean(value)));
+    const selectedDigests = new Set([...selectedIds].map(receipt_1.sha256));
+    const sessions = new Map();
+    if (selected)
+        sessions.set(locationId(selected), selected);
+    const rows = receipts.filter(row => session === 'all' || (row.sessionId && selectedIds.has(row.sessionId)) || (row.sessionDigest && selectedDigests.has(row.sessionDigest))).map(row => {
+        const location = row.sessionId ? aliases.get(row.sessionId) : row.sessionDigest ? digests.get(row.sessionDigest) : undefined;
+        const id = location ? locationId(location) : row.sessionId ?? (row.sessionDigest ? `sha256:${row.sessionDigest}` : `unknown-row-${row.line}`);
+        sessions.set(id, location);
+        return { ...row, session: id };
+    });
+    const cache = new Map();
+    return { receipts: rows, sessions: [...sessions].map(([id, location]) => ({ session: id,
+            economics: location ? readSessionEconomics(location, locations, options.rates, cache) : unavailable('No matching local transcript; child usage is unavailable.') })), malformedReceiptLines: malformedLines };
+}
+function table(headers, rows) {
+    const widths = headers.map((header, index) => Math.max(header.length, ...rows.map(row => row[index]?.length ?? 0)));
+    return [headers, ...rows].map(row => row.map((cell, index) => cell.padEnd(widths[index])).join('  ').trimEnd()).join('\n');
+}
+const shortSession = (session) => session.startsWith('sha256:') ? session.slice(0, 15) : session.slice(0, 8);
+const number = (value) => value === null ? 'unavailable' : value.toLocaleString('en-US');
+function renderBlocks(report) {
+    const sessions = new Map(report.sessions.map(session => [session.session, session.economics]));
+    const compact = (item) => !item?.count ? 'unavailable' :
+        `${item.count}${item.measuredCount !== item.count ? ` (${item.measuredCount} measured)` : ''}; ${number(item.medianTokens)}/${number(item.maxTokens)}; ${(0, live_1.dollars)(item.medianUsd)}/${(0, live_1.dollars)(item.maxUsd)}`;
+    const lines = ['AgentGuard blocks: stored WARN and STOP decisions',
+        'Each child cell: transcript count; median/max measured tokens; median/max list USD.',
+        table(['Time (UTC)', 'Session', 'Verdict', 'Detector', 'Spawn', 'Blocked', 'All children', 'Fork children', 'Fresh children'], report.receipts.map(row => {
+            const economics = sessions.get(row.session);
+            return [row.at === null ? 'unknown' : new Date(row.at).toISOString(), shortSession(row.session), row.verdict, row.detectors.join(',') || 'unknown',
+                row.spawnNumber === null ? 'unknown' : String(row.spawnNumber), row.blocked === null ? 'unknown' : row.blocked ? 'yes' : 'no',
+                compact(economics?.all), compact(economics?.forks), compact(economics?.fresh)];
+        }))];
+    if (!report.receipts.length)
+        lines.push('No stored WARN or STOP receipts match this selection.');
+    for (const { session, economics } of report.sessions) {
+        lines.push('', `Session ${shortSession(session)}: its own child transcripts`);
+        if (economics.available)
+            lines.push(table(['Children', 'Count', 'Measured', 'Median tokens', 'Max tokens', 'Median list USD', 'Max list USD'], [['All', economics.all], ['Forks', economics.forks], ['Fresh', economics.fresh]].map(([label, stats]) => {
+                const item = stats;
+                return [String(label), item.count ? String(item.count) : '0 found', String(item.measuredCount), number(item.medianTokens), number(item.maxTokens), (0, live_1.dollars)(item.medianUsd), (0, live_1.dollars)(item.maxUsd)];
+            })));
+        lines.push(...economics.notes);
+        if (economics.children.some(child => child.tokens === null))
+            lines.push('Some children have no attributable usage or an unknown inherited-history boundary; their token statistics are unavailable.');
+        const unpriced = [...new Set(economics.children.flatMap(child => child.unknownModels))];
+        if (unpriced.length)
+            lines.push(`Tokens only for unpriced models: ${unpriced.join(', ')}. Dollar statistics require every child in the cohort to have a verified rate.`);
+    }
+    if (report.malformedReceiptLines)
+        lines.push(`${report.malformedReceiptLines} malformed receipt lines could not be read.`);
+    lines.push('', 'Measured usage is deduplicated by provider response id, including message.id; inherited parent usage is excluded.', 'Claude forks are marked fork-context-ref. Codex forks require host lineage metadata; other discovered children are fresh.', 'Child totals cover the full available transcript, not a prediction at the decision time. Token and dollar medians and maxima are computed separately.', 'Dollars are API list-price equivalents, not your bill. Missing cache TTL produces a price range. Unknown models have tokens only.');
+    return lines.join('\n');
+}

package/dist/src/insights/transcript.d.ts

@@ -1,4 +1,6 @@
-import type { InsightParseOptions, InsightTranscript, InsightTurn } from './types';
+import type { InsightHost, InsightParseOptions, InsightTranscript, InsightTurn } from './types';
+/** Provider response identity is shared by reporting and enforcement readers. */
+export declare const providerResponseIdentity: (host: InsightHost, id: unknown) => string;
 /**
  * Parse complete JSONL records. Pass returned state when parsing appended lines.
  * `updatedTurns` replaces rows with the same id; it must never be blindly added