@agentguard-run/burn 0.2.5 → 0.2.6

package/dist/src/insights/transcript.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.providerResponseIdentity = void 0;
 exports.parseInsightTranscript = parseInsightTranscript;
 exports.readInsightTranscript = readInsightTranscript;
 exports.readInsightSession = readInsightSession;
@@ -11,6 +12,9 @@ const object = (value) => value !== null && typeof value === 'object' && !Array.
 const count = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0;
 const hasCount = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
 const digest = (value) => (0, node_crypto_1.createHash)('sha256').update(JSON.stringify(value)).digest('hex');
+/** Provider response identity is shared by reporting and enforcement readers. */
+const providerResponseIdentity = (host, id) => digest(['provider-response', host, id]);
+exports.providerResponseIdentity = providerResponseIdentity;
 const identifier = (value) => typeof value === 'string' && /^[A-Za-z0-9_.:/-]{1,128}$/.test(value) ? value : undefined;
 const modelName = identifier;
 function millis(value) {
@@ -260,9 +264,18 @@ function parseInsightTranscript(text, options = {}) {
         const message = object(raw.message), payload = object(raw.payload), response = object(raw.response);
         const extracted = usageOf(raw), usage = extracted.usage;
         const at = millis(raw.timestamp ?? raw.created_at ?? payload.timestamp);
+        if (raw.type === 'fork-context-ref') {
+            state.lineage = { ...state.lineage, forkContextRef: true, forked: true,
+                ...(identifier(raw.parentSessionId) ? { parentSessionId: identifier(raw.parentSessionId) } : {}) };
+        }
         if (raw.type === 'session_meta' && !state.sessionMetadataSeen) {
             state.sessionMetadataSeen = true;
             state.host = 'codex';
+            const spawned = object(object(object(payload.source).subagent).thread_spawn);
+            state.lineage = { ...state.lineage,
+                ...(identifier(payload.id ?? payload.session_id) ? { sessionId: identifier(payload.id ?? payload.session_id) } : {}),
+                ...(identifier(payload.parent_thread_id ?? spawned.parent_thread_id) ? { parentSessionId: identifier(payload.parent_thread_id ?? spawned.parent_thread_id) } : {}),
+                ...(identifier(payload.forked_from_id) ? { forked: true } : {}) };
             if ('subagent' in object(payload.source) || identifier(payload.parent_thread_id) || identifier(payload.agent_path))
                 state.spawnedSession = true;
             if (hasCount(payload.subagent_history_start_ordinal))
@@ -371,7 +384,7 @@ function parseInsightTranscript(text, options = {}) {
         // Provider response ids remain the same when a host copies history into a
         // forked session. Preserve global identity instead of charging it twice.
         const providerId = message.id !== undefined || response.id !== undefined;
-        const id = digest([providerId ? 'provider-response' : extracted.codex && state.codexTurnIdDigest ? 'codex-turn' : state.sessionId, host, nativeId]);
+        const id = providerId ? (0, exports.providerResponseIdentity)(host, nativeId) : digest([extracted.codex && state.codexTurnIdDigest ? 'codex-turn' : state.sessionId, host, nativeId]);
         const existing = state.seen[id];
         const creation = object(usage.cache_creation);
         const split5m = creation.ephemeral_5m_input_tokens, split1h = creation.ephemeral_1h_input_tokens;

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

@@ -77,6 +77,13 @@ export interface InsightParserState {
         fileKey?: string;
     }>;
     sessionMetadataSeen?: boolean;
+    /** Host-recorded lineage identifiers only, never inherited prompt content. */
+    lineage?: {
+        sessionId?: string;
+        parentSessionId?: string;
+        forkContextRef?: boolean;
+        forked?: boolean;
+    };
     inheritedBeforeOrdinal?: number;
     forkHistoryBoundaryUnknown?: boolean;
     inheritedTotalDigest?: string;

package/dist/src/policy.d.ts

@@ -0,0 +1,4 @@
+import type { Policy } from './types';
+/** Normalize before evaluating or hashing so receipts bind the actual policy. */
+export declare function normalizePolicy(policy: Policy): Policy;
+export declare function loadPolicy(home: string): Policy;

package/dist/src/policy.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizePolicy = normalizePolicy;
+exports.loadPolicy = loadPolicy;
+/** Load additive policy defaults without rewriting the operator's policy. */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const defaults_1 = require("./defaults");
+const noticed = new Set();
+/** Normalize before evaluating or hashing so receipts bind the actual policy. */
+function normalizePolicy(policy) {
+    const thresholds = policy.thresholds;
+    const normalized = {
+        fanout: { ...defaults_1.DEFAULT_THRESHOLDS.fanout, ...thresholds.fanout },
+        sustained: { ...defaults_1.DEFAULT_THRESHOLDS.sustained, ...thresholds.sustained },
+        burnDebt: { ...defaults_1.DEFAULT_THRESHOLDS.burnDebt, ...thresholds.burnDebt },
+        spawnRate: { ...defaults_1.DEFAULT_THRESHOLDS.spawnRate, ...thresholds.spawnRate },
+        duplicate: { ...defaults_1.DEFAULT_THRESHOLDS.duplicate, ...thresholds.duplicate },
+        account: { ...defaults_1.DEFAULT_THRESHOLDS.account, ...thresholds.account },
+        localCompute: { ...defaults_1.DEFAULT_THRESHOLDS.localCompute, ...thresholds.localCompute },
+    };
+    return { ...policy, thresholds: normalized };
+}
+function noticeOnce(home, fields) {
+    if (noticed.has(home))
+        return;
+    noticed.add(home);
+    try {
+        (0, node_fs_1.mkdirSync)(home, { recursive: true, mode: 0o700 });
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(home, '.burn-policy-0.2.6-notice'), fields.join(', ') + '\n', { flag: 'wx', mode: 0o600 });
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return;
+        // A read-only home still gets the notice once in this process.
+    }
+    process.stderr.write(`AgentGuard loaded missing policy fields from defaults: ${fields.join(', ')}; existing overrides are unchanged.\n`);
+}
+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) {
+            const missing = [];
+            if (parsed.thresholds.fanout?.windowActiveMinutes === undefined)
+                missing.push('fanout.windowActiveMinutes=120');
+            if (parsed.thresholds.spawnRate?.enforce === undefined)
+                missing.push('spawnRate.enforce=true');
+            if (missing.length)
+                noticeOnce(home, missing);
+            return normalizePolicy(parsed);
+        }
+    }
+    catch {
+        /* no policy yet: shadow defaults */
+    }
+    return normalizePolicy(defaults_1.DEFAULT_POLICY);
+}

package/dist/src/replay/render.js

@@ -150,13 +150,15 @@ function renderReplay(summary, opts = {}) {
         paint(on, C.dim, `   across ${summary.sessions.length} sessions, ${summary.totalSpawns} spawns`)));
     out.push(MID);
     for (const s of summary.sessions.slice(0, top)) {
-        const tag = s.fanoutStop ? paint(on, C.red, 'FAN-OUT STOP') : s.sustainedStop ? paint(on, C.red, 'SUSTAINED STOP') : s.firstWarn ? paint(on, C.yellow, 'WARN') : paint(on, C.green, 'clean');
+        const tag = s.fanoutStop ? paint(on, C.red, 'FAN-OUT STOP') : s.sustainedStop ? paint(on, C.red, 'SUSTAINED STOP') : s.spawnRateStop ? paint(on, C.red, 'SPAWN-RATE STOP') : s.firstWarn ? paint(on, C.yellow, 'WARN') : paint(on, C.green, 'clean');
         out.push(row(`${sparkline(s.curve, s.stopAtIndex, on)}  ${tag}`));
         const detail = s.fanoutStop
             ? `before spawn ${s.fanoutStop.atSpawn}, tail ${(0, evaluate_1.fmt)(s.catchableTail)}`
             : s.sustainedStop
                 ? `near ${(0, evaluate_1.fmt)(s.sustainedStop.tokensAtStop)}, tail ${(0, evaluate_1.fmt)(s.catchableTail)}`
-                : `${(0, evaluate_1.fmt)(s.totalTokens)} · ${s.spawns} spawns`;
+                : s.spawnRateStop
+                    ? `before spawn ${s.spawnRateStop.atSpawn}, tail ${(0, evaluate_1.fmt)(s.catchableTail)}`
+                    : `${(0, evaluate_1.fmt)(s.totalTokens)} · ${s.spawns} spawns`;
         out.push(row(paint(on, C.dim, `${s.sessionId.slice(0, 8)}  ${(0, evaluate_1.fmt)(s.totalTokens).padStart(6)} · ${String(s.spawns).padStart(3)} spawns   ${detail}`)));
     }
     if (summary.sessions.length > top) {

package/dist/src/replay/simulate.d.ts

@@ -30,6 +30,11 @@ export interface SessionReplay {
         atSpawn: number;
         tokensAtStop: number;
     } | null;
+    /** Additive boundary for policies that enforce short-window spawn rate. */
+    spawnRateStop?: {
+        atSpawn: number;
+        tokensAtStop: number;
+    } | null;
     /** Tokens observed after the earliest STOP boundary. */
     catchableTail: number;
     firstWarn: {

package/dist/src/replay/simulate.js

@@ -58,6 +58,7 @@ function replayEvents(sessionId, path, events, thresholds) {
     const state = (0, session_1.newSessionState)(sessionId, first.at);
     let fanoutStop = null;
     let sustainedStop = null;
+    let spawnRateStop = null;
     let firstWarn = null;
     let tokensAtEarliestStop = null;
     // Cumulative tokens after every event, for the sparkline.
@@ -66,25 +67,38 @@ function replayEvents(sessionId, path, events, thresholds) {
     for (const event of events) {
         // A hook boundary exists only where a spawn was attempted. Evaluate the
         // *proposal* before applying the event, then apply it.
+        const candidateState = event.spawns.length > 0
+            ? { ...state, spawnsByActiveMinute: new Map(state.spawnsByActiveMinute) }
+            : state;
+        if (event.spawns.length > 0) {
+            // One assistant row can propose several agents. Advance its active-time
+            // clock once, then account for each earlier proposal in this row. Usage
+            // and the durable state are still folded only once below.
+            (0, session_1.applyEvent)(candidateState, { at: event.at, tokens: 0, cacheRead: 0, spawns: [], surfaces: [], sidechain: event.sidechain });
+        }
         for (const spawn of event.spawns) {
-            const report = (0, evaluate_1.evaluate)(state, thresholds, spawn.issuerDepth + 1);
+            const report = (0, evaluate_1.evaluate)(candidateState, thresholds, spawn.issuerDepth + 1);
             if (!firstWarn && report.verdict !== 'OK') {
-                firstWarn = { detector: report.findings[0]?.detector ?? 'unknown', tokensAt: state.totalTokens, spawnsAt: state.spawnCount + 1 };
+                firstWarn = { detector: report.findings[0]?.detector ?? 'unknown', tokensAt: state.totalTokens, spawnsAt: candidateState.spawnCount + 1 };
             }
             for (const finding of report.findings) {
                 if (finding.verdict !== 'STOP')
                     continue;
                 if (finding.detector === 'fanout' && !fanoutStop) {
-                    fanoutStop = { atSpawn: state.spawnCount + 1, tokensAtStop: state.totalTokens };
+                    fanoutStop = { atSpawn: candidateState.spawnCount + 1, tokensAtStop: state.totalTokens };
+                }
+                if (finding.detector === 'spawn_rate' && !spawnRateStop) {
+                    spawnRateStop = { atSpawn: candidateState.spawnCount + 1, tokensAtStop: state.totalTokens };
                 }
                 if ((finding.detector === 'sustained_burn' || finding.detector === 'burn_debt') && !sustainedStop) {
-                    sustainedStop = { atSpawn: state.spawnCount + 1, tokensAtStop: state.totalTokens };
+                    sustainedStop = { atSpawn: candidateState.spawnCount + 1, tokensAtStop: state.totalTokens };
                 }
             }
-            if ((fanoutStop || sustainedStop) && tokensAtEarliestStop === null) {
+            if ((fanoutStop || sustainedStop || spawnRateStop) && tokensAtEarliestStop === null) {
                 tokensAtEarliestStop = state.totalTokens;
                 stopEventIndex = timeline.length;
             }
+            (0, session_1.applyEvent)(candidateState, { at: event.at, tokens: 0, cacheRead: 0, spawns: [spawn], surfaces: [], sidechain: event.sidechain });
         }
         // The sustained plane also has a boundary at every tool call, not just
         // spawns. Approximate: any event with surfaces is a tool boundary.
@@ -118,6 +132,7 @@ function replayEvents(sessionId, path, events, thresholds) {
         finalVerdict: final.verdict,
         fanoutStop,
         sustainedStop,
+        spawnRateStop,
         catchableTail: tokensAtEarliestStop === null ? 0 : Math.max(0, state.totalTokens - tokensAtEarliestStop),
         firstWarn,
         curve,
@@ -160,8 +175,8 @@ function replayAll(paths, thresholds, minTokens = 0) {
         totalSpawns: sessions.reduce((s, r) => s + r.spawns, 0),
         catchableTail,
         catchableShare: totalTokens > 0 ? catchableTail / totalTokens : 0,
-        stops: sessions.filter((r) => r.fanoutStop || r.sustainedStop).length,
-        warns: sessions.filter((r) => !r.fanoutStop && !r.sustainedStop && r.firstWarn).length,
-        clean: sessions.filter((r) => !r.fanoutStop && !r.sustainedStop && !r.firstWarn).length,
+        stops: sessions.filter((r) => r.fanoutStop || r.sustainedStop || r.spawnRateStop).length,
+        warns: sessions.filter((r) => !r.fanoutStop && !r.sustainedStop && !r.spawnRateStop && r.firstWarn).length,
+        clean: sessions.filter((r) => !r.fanoutStop && !r.sustainedStop && !r.spawnRateStop && !r.firstWarn).length,
     };
 }

package/dist/src/state/reservations.d.ts

@@ -152,6 +152,8 @@ export declare class Transaction {
     private readonly data;
     dirty: boolean;
     constructor(data: ReservationFile);
+    /** Pending proposals participate in every spawn window under the same lock. */
+    pendingSpawns(sessionId: string, toolUseId: string, now: number): number;
     reserve(args: ReserveArgs): ReserveResult;
     reconcile(sessionId: string, observedSpawns: number, previouslyObserved: number): void;
     /**

package/dist/src/state/reservations.js

@@ -310,6 +310,10 @@ class Transaction {
         if (!this.data.calls)
             this.data.calls = [];
     }
+    /** Pending proposals participate in every spawn window under the same lock. */
+    pendingSpawns(sessionId, toolUseId, now) {
+        return this.data.reservations.filter(r => r.sessionId === sessionId && r.toolUseId !== toolUseId && r.expiresAt > now).length;
+    }
     reserve(args) {
         const now = args.now ?? Date.now();
         const data = this.data;
@@ -318,7 +322,7 @@ class Transaction {
         if (data.reservations.length !== before)
             this.dirty = true;
         // Idempotent: the same tool_use_id evaluated twice must not double-count.
-        const existing = data.reservations.find((r) => r.toolUseId === args.toolUseId);
+        const existing = data.reservations.find((r) => r.sessionId === args.sessionId && r.toolUseId === args.toolUseId);
         const pendingForSession = data.reservations.filter((r) => r.sessionId === args.sessionId && r.toolUseId !== args.toolUseId).length;
         const effective = args.observedSpawns + pendingForSession + 1;
         if (existing) {

package/dist/src/state/spawn-window.d.ts

@@ -0,0 +1,10 @@
+import type { BurnReport, SessionState, Thresholds } from '../types';
+import type { ReserveResult, Transaction } from './reservations';
+/** Evaluate and reserve together. Pending forks must not bypass either window. */
+export declare function evaluateSpawnReservation(tx: Transaction, state: SessionState, thresholds: Thresholds, proposedDepth: number, toolUseId: string, now: number, account?: {
+    sessions: SessionState[];
+    now: number;
+}): {
+    report: BurnReport;
+    reservation: ReserveResult;
+};

package/dist/src/state/spawn-window.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateSpawnReservation = evaluateSpawnReservation;
+const evaluate_1 = require("../detectors/evaluate");
+const defaults_1 = require("../defaults");
+const session_1 = require("./session");
+/** Evaluate and reserve together. Pending forks must not bypass either window. */
+function evaluateSpawnReservation(tx, state, thresholds, proposedDepth, toolUseId, now, account) {
+    const pending = tx.pendingSpawns(state.sessionId, toolUseId, now);
+    const minute = Math.floor(state.activeMinutes);
+    const spawns = new Map(state.spawnsByActiveMinute);
+    if (pending)
+        spawns.set(minute, (spawns.get(minute) ?? 0) + pending);
+    const candidateState = { ...state, spawnCount: state.spawnCount + pending, spawnsByActiveMinute: spawns };
+    const report = (0, evaluate_1.evaluate)(candidateState, thresholds, proposedDepth, account);
+    // Receipts retain the lifetime ordinal, while admission uses the active window.
+    const effectiveSpawns = state.spawnCount + pending + 1;
+    if (report.verdict === 'STOP') {
+        // A refused proposal never consumes a reservation. Its detector explains why.
+        return { report, reservation: { allowed: true, effectiveSpawns, pending } };
+    }
+    const recent = (0, session_1.windowSum)(state.spawnsByActiveMinute, state.activeMinutes, thresholds.fanout.windowActiveMinutes ?? defaults_1.DEFAULT_THRESHOLDS.fanout.windowActiveMinutes);
+    const reservation = tx.reserve({ sessionId: state.sessionId, toolUseId, observedSpawns: recent, ceiling: thresholds.fanout.stop, now });
+    return { report, reservation: { ...reservation, effectiveSpawns } };
+}

package/dist/src/types.d.ts

@@ -83,7 +83,8 @@ export interface Thresholds {
     fanout: {
         warn: number;
         stop: number;
-        maxDepth: number;
+        maxDepth: number; /** Older policies use 120 active minutes. */
+        windowActiveMinutes?: number;
     };
     sustained: {
         warnTokens: number;

package/fixtures/usage-dedup-session/subagents/agent-synthetic-first.jsonl

@@ -0,0 +1,5 @@
+{"type":"fork-context-ref"}
+{"type":"assistant","timestamp":"2026-09-01T00:00:02Z","uuid":"synthetic-root-block-3","message":{"id":"synthetic-response-a","model":"claude-sonnet-5","usage":{"input_tokens":10,"cache_creation_input_tokens":20,"cache_read_input_tokens":100,"output_tokens":9},"content":[]}}
+{"type":"assistant","timestamp":"2026-09-01T00:00:03Z","uuid":"synthetic-root-spawn","message":{"id":"synthetic-response-b","model":"claude-sonnet-5","usage":{"input_tokens":11,"cache_read_input_tokens":130,"output_tokens":2},"content":[{"type":"tool_use","id":"synthetic-spawn-1","name":"Agent","input":{"description":"synthetic task"}}]}}
+{"type":"assistant","timestamp":"2026-09-01T00:00:04Z","uuid":"synthetic-child-block-1","message":{"id":"synthetic-response-c","model":"claude-sonnet-5","usage":{"input_tokens":5,"cache_creation_input_tokens":30,"cache_read_input_tokens":150,"output_tokens":10},"content":[]}}
+{"type":"assistant","timestamp":"2026-09-01T00:00:05Z","uuid":"synthetic-child-block-2","message":{"id":"synthetic-response-c","model":"claude-sonnet-5","usage":{"input_tokens":5,"cache_creation_input_tokens":30,"cache_read_input_tokens":150,"output_tokens":12},"content":[]}}

package/fixtures/usage-dedup-session/subagents/agent-synthetic-second.jsonl

@@ -0,0 +1,4 @@
+{"type":"fork-context-ref"}
+{"type":"assistant","timestamp":"2026-09-01T00:00:02Z","uuid":"synthetic-root-block-3","message":{"id":"synthetic-response-a","model":"claude-sonnet-5","usage":{"input_tokens":10,"cache_creation_input_tokens":20,"cache_read_input_tokens":100,"output_tokens":9},"content":[]}}
+{"type":"assistant","timestamp":"2026-09-01T00:00:05Z","uuid":"synthetic-copy-c","message":{"id":"synthetic-response-c","model":"claude-sonnet-5","usage":{"input_tokens":5,"cache_creation_input_tokens":30,"cache_read_input_tokens":150,"output_tokens":12},"content":[]}}
+{"type":"assistant","timestamp":"2026-09-01T00:00:06Z","uuid":"synthetic-child-d","message":{"id":"synthetic-response-d","model":"claude-sonnet-5","usage":{"input_tokens":2,"cache_read_input_tokens":200,"output_tokens":3},"content":[]}}

package/fixtures/usage-dedup-session.jsonl

@@ -0,0 +1,4 @@
+{"type":"assistant","timestamp":"2026-09-01T00:00:00Z","uuid":"synthetic-root-block-1","message":{"id":"synthetic-response-a","model":"claude-sonnet-5","usage":{"input_tokens":10,"cache_creation_input_tokens":20,"cache_read_input_tokens":100,"output_tokens":5},"content":[]}}
+{"type":"assistant","timestamp":"2026-09-01T00:00:01Z","uuid":"synthetic-root-block-2","message":{"id":"synthetic-response-a","model":"claude-sonnet-5","usage":{"input_tokens":10,"cache_creation_input_tokens":20,"cache_read_input_tokens":100,"output_tokens":5},"content":[]}}
+{"type":"assistant","timestamp":"2026-09-01T00:00:02Z","uuid":"synthetic-root-block-3","message":{"id":"synthetic-response-a","model":"claude-sonnet-5","usage":{"input_tokens":10,"cache_creation_input_tokens":20,"cache_read_input_tokens":100,"output_tokens":9},"content":[]}}
+{"type":"assistant","timestamp":"2026-09-01T00:00:03Z","uuid":"synthetic-root-spawn","message":{"id":"synthetic-response-b","model":"claude-sonnet-5","usage":{"input_tokens":11,"cache_read_input_tokens":130,"output_tokens":2},"content":[{"type":"tool_use","id":"synthetic-spawn-1","name":"Agent","input":{"description":"synthetic task"}}]}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentguard-run/burn",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Local session usage and runaway-agent circuit breaker. Explain tokens, cache rewrites and API list cost, track pace, warn on heavy turns, and gate agent fan-out with signed receipts. Nothing leaves the machine.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "commonjs",