@agentguard-run/burn 0.2.3 → 0.2.6

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

@@ -0,0 +1,164 @@
+/** Content-free transcript usage. No prompt, output text, path, or tool input. */
+export type InsightHost = 'claude' | 'codex' | 'unknown';
+export type TokenCategory = 'input' | 'cacheCreation' | 'cacheRead' | 'output';
+export type InsightBucket = 'instruction_stack' | 'history_resent' | 'reread_files' | 'subagent_fanout' | 'tool_output' | 'conversation' | 'full_prefix_rewrites' | 'output' | 'unattributed';
+export declare const INSIGHT_BUCKETS: InsightBucket[];
+export interface ExplicitTokenAttribution {
+    bucket: InsightBucket;
+    category: TokenCategory;
+    tokens: number;
+}
+/** Bytes divide a measured usage increment; they are never converted to tokens. */
+export interface InsightInterval {
+    toolOutputBytes: number;
+    reReadBytes: number;
+    conversationBytes: number;
+    toolResults: number;
+    reReadResults?: number;
+    userMessages: number;
+    shared: boolean;
+}
+export interface InsightTurn {
+    id: string;
+    sessionId: string;
+    host: InsightHost;
+    subagent?: boolean;
+    at?: number;
+    model?: string;
+    /** Fresh input only. Codex cached input is subtracted from its inclusive input. */
+    inputTokens: number;
+    cacheWriteTokens: number;
+    cacheReadTokens: number;
+    outputTokens: number;
+    cacheWrite5mTokens?: number;
+    cacheWrite1hTokens?: number;
+    cacheTtlSeconds?: 300 | 3600;
+    cacheTtlSource?: 'usage_split' | 'explicit_metadata';
+    /** Actual input context, never the model's advertised maximum window. */
+    contextTokens: number;
+    signals: {
+        idleMs?: number;
+        afterCompaction: boolean;
+        firstSpawnedTurn: boolean;
+        prefixChanged?: boolean;
+    };
+    explicitAttribution: ExplicitTokenAttribution[];
+    uncertainties: string[];
+    /** Input events received since the previous distinct assistant response. */
+    interval?: InsightInterval;
+}
+export interface InsightDiagnostics {
+    lines: number;
+    malformedLines: number;
+    duplicateUsageRecords: number;
+    unsupportedUsageRecords: number;
+    inheritedUsageRecords?: number;
+}
+export interface InsightParserState {
+    host: InsightHost;
+    sessionId: string;
+    model?: string;
+    lastAt?: number;
+    compactionPending: boolean;
+    spawnedSession: boolean;
+    seen: Record<string, InsightTurn>;
+    /** Codex token_count reports both cumulative totals and last response usage. */
+    codexTotals?: {
+        input: number;
+        cached: number;
+        output: number;
+    };
+    prefixDigest?: string;
+    prefixChangedPending?: boolean;
+    recordsSeen?: number;
+    codexEpoch?: number;
+    observedCalls?: Record<string, {
+        kind: 'read' | 'spawn' | 'tool_result';
+        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;
+    codexTurnIdDigest?: string;
+    forkThreadIdDigest?: string;
+    awaitingForkBoundary?: boolean;
+    intervalStateVersion?: 1;
+    pendingInterval?: InsightInterval;
+    inputEventsSeen?: Record<string, true>;
+    readPathsSeen?: Record<string, true>;
+    readToolCalls?: Record<string, {
+        fileKey: string;
+        repeated: boolean;
+    }>;
+    conversationEcho?: {
+        digest: string;
+        source: 'response' | 'event';
+    };
+}
+export interface InsightObservations {
+    readCalls: number;
+    repeatedReadCalls: number;
+    uniqueReadFiles: number;
+    spawnCalls: number;
+    toolResultRecords: number;
+}
+export interface InsightTranscript {
+    host: InsightHost;
+    sessionId: string;
+    turns: InsightTurn[];
+    /** New or amended turns, suitable for an incremental observer keyed by id. */
+    updatedTurns: InsightTurn[];
+    diagnostics: InsightDiagnostics;
+    state: InsightParserState;
+    observations: InsightObservations;
+    /** Zero-based line indexes in this parsed chunk, after fork ownership checks. */
+    acceptedQuotaLineNumbers?: number[];
+}
+export interface InsightParseOptions {
+    host?: InsightHost;
+    sessionId?: string;
+    state?: InsightParserState;
+    spawnedSession?: boolean;
+}
+export type RewriteCause = 'idle_ttl_expired' | 'compaction' | 'first_spawned_turn' | 'prefix_change' | 'unknown_ttl';
+export interface RewriteEvidence {
+    turnId: string;
+    cause: RewriteCause;
+    cacheWriteTokens: number;
+    contextTokens: number;
+    idleMs?: number;
+    idleOver60Minutes: boolean;
+    ttlSeconds?: 300 | 3600;
+    ttlUnknown: boolean;
+    explanation: string;
+}
+export interface BucketAttribution {
+    bucket: InsightBucket;
+    tokens: number;
+    categories: Record<TokenCategory, number>;
+}
+export interface AttributionSummary {
+    buckets: BucketAttribution[];
+    totalTokens: number;
+    rewrites: RewriteEvidence[];
+    rewriteCounts: Record<RewriteCause, number>;
+    idleOver60MinuteRewrites: number;
+    uncertainties: string[];
+    turnAttributions: Array<{
+        turnId: string;
+        sessionId: string;
+        buckets: BucketAttribution[];
+        totalTokens: number;
+    }>;
+    sharedTurns: number;
+    prefixRebaselines: number;
+    previousOutputTokensReserved: number;
+}

package/dist/src/insights/types.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INSIGHT_BUCKETS = void 0;
+exports.INSIGHT_BUCKETS = ['instruction_stack', 'history_resent', 'reread_files', 'subagent_fanout', 'tool_output', 'conversation', 'full_prefix_rewrites', 'output', 'unattributed'];

package/dist/src/install.js

@@ -48,7 +48,16 @@ function mergeMatcherStyle(cfg, event, matcher, command, timeout) {
     const list = (hooks[event] ??= []);
     let changed = false;
     let found = false;
-    for (const m of list) {
+    for (const m of [...list]) {
+        if (m.matcher !== matcher && m.hooks?.some(h => typeof h.command === 'string' && MARK.test(h.command)) &&
+            m.hooks.some(h => typeof h.command !== 'string' || !MARK.test(h.command))) {
+            const mine = m.hooks.filter(h => typeof h.command === 'string' && MARK.test(h.command));
+            m.hooks = m.hooks.filter(h => !mine.includes(h));
+            list.push({ matcher, hooks: mine.map(h => ({ ...h, command, timeout })) });
+            found = true;
+            changed = true;
+            continue;
+        }
         for (const h of m.hooks ?? []) {
             if (typeof h.command === 'string' && MARK.test(h.command)) {
                 found = true;
@@ -76,8 +85,8 @@ function mergeCursor(cfg, command) {
     }
     const hooks = (cfg.hooks ??= {});
     const want = {
-        subagentStart: { command, timeout: 5, failClosed: true },
-        subagentStop: { command, timeout: 5 },
+        subagentStart: { command, timeout: 15, failClosed: true },
+        subagentStop: { command, timeout: 15 },
         sessionEnd: { command, timeout: 3 },
     };
     for (const [event, entry] of Object.entries(want)) {
@@ -101,11 +110,11 @@ function install(host, cliPath, home = (0, node_os_1.homedir)()) {
     let changed;
     if (host === 'claude') {
         command = `node ${cliPath} hook`;
-        changed = mergeMatcherStyle(cfg, 'PreToolUse', '^(Agent|Task)$', command, 5);
+        changed = mergeMatcherStyle(cfg, 'PreToolUse', '.*', command, 15);
     }
     else if (host === 'codex') {
         command = `node ${cliPath} codex-hook`;
-        changed = mergeMatcherStyle(cfg, 'PreToolUse', '^(Agent|spawn_agent)$', command, 5);
+        changed = mergeMatcherStyle(cfg, 'PreToolUse', '.*', command, 15);
     }
     else {
         command = `node ${cliPath} cursor-hook`;

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

@@ -83,11 +83,11 @@ export declare class ReservationStore {
     /** The holder's own instance is still the one on the path. */
     private fence;
     /**
-     * Take the lock directory off its path atomically, then verify it is the
-     * instance we meant. rmSync on the live path is readdir + unlink + rmdir,
-     * and a sibling can mkdir the same path between those steps, so removal
-     * is always rename-then-delete. If the instance we grabbed is not the one
-     * we judged (`expect`), it is a live sibling's: put it back.
+     * Serialize retirement inside the existing lock before checking its owner.
+     * A delayed observer must never temporarily rename a newer live lock: even
+     * restoring it can trip that holder's final fence after audit rows were
+     * appended. Every release/recovery uses this claim, so the nonce is stable
+     * from this check through the atomic rename. Delete only the retired path.
      */
     private discard;
     private trace;
@@ -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

@@ -25,9 +25,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Transaction = exports.ReservationStore = exports.RESERVATION_TTL_MS = void 0;
 const node_fs_1 = require("node:fs");
+const node_crypto_1 = require("node:crypto");
 const node_path_1 = require("node:path");
-const LOCK_STALE_MS = 10_000;
-const LOCK_WAIT_MS = 3_000;
+const LOCK_WAIT_MS = 8_000;
 const LOCK_SPIN_MS = 15;
 exports.RESERVATION_TTL_MS = 90_000;
 function pidAlive(pid) {
@@ -118,42 +118,63 @@ class ReservationStore {
         }
     }
     /**
-     * Take the lock directory off its path atomically, then verify it is the
-     * instance we meant. rmSync on the live path is readdir + unlink + rmdir,
-     * and a sibling can mkdir the same path between those steps, so removal
-     * is always rename-then-delete. If the instance we grabbed is not the one
-     * we judged (`expect`), it is a live sibling's: put it back.
+     * Serialize retirement inside the existing lock before checking its owner.
+     * A delayed observer must never temporarily rename a newer live lock: even
+     * restoring it can trip that holder's final fence after audit rows were
+     * appended. Every release/recovery uses this claim, so the nonce is stable
+     * from this check through the atomic rename. Delete only the retired path.
      */
     discard(reason, expect) {
-        const quarantine = `${this.lockDir}.${reason}.${process.pid}.${Date.now().toString(36)}`;
-        try {
-            (0, node_fs_1.renameSync)(this.lockDir, quarantine);
-        }
-        catch {
-            return false; // somebody else already took it off the path
-        }
-        const got = this.readOwnerAt(quarantine);
-        if ((got?.nonce ?? null) !== expect) {
-            // Not the instance we judged. Give it back; if a waiter slipped into
-            // the freed path in between, the displaced holder's fence throws and
-            // its transaction is discarded, so nothing double-commits.
+        const claim = (0, node_path_1.join)(this.lockDir, 'retiring');
+        const deadline = Date.now() + LOCK_WAIT_MS;
+        for (;;) {
             try {
-                (0, node_fs_1.renameSync)(quarantine, this.lockDir);
-                this.trace(`discard ${reason}: wrong instance, returned`);
-                return false;
+                (0, node_fs_1.mkdirSync)(claim, { mode: 0o700 });
+                break;
             }
-            catch {
-                this.trace(`discard ${reason}: wrong instance, could not return`);
+            catch (error) {
+                if (error.code !== 'EEXIST' || reason !== 'released' || Date.now() >= deadline)
+                    return false;
+                // A stale observer may briefly claim a newer live instance, notice the
+                // nonce mismatch, and leave it untouched. Let its owner release next.
+                sleepSync(LOCK_SPIN_MS);
             }
         }
+        let retired = false;
         try {
-            (0, node_fs_1.rmSync)(quarantine, { recursive: true, force: true });
+            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(claim, 'owner'), JSON.stringify({ pid: process.pid, since: Date.now(), nonce: (0, node_crypto_1.randomUUID)(), lockNonce: expect }), { mode: 0o600 });
+            const got = this.readOwnerAt(this.lockDir);
+            if ((got?.nonce ?? null) !== expect) {
+                this.trace(`discard ${reason}: wrong instance, untouched`);
+                return false;
+            }
+            if (reason === 'stale' && got && pidAlive(got.pid))
+                return false;
+            const quarantine = `${this.lockDir}.${reason}.${process.pid}.${(0, node_crypto_1.randomUUID)()}`;
+            (0, node_fs_1.renameSync)(this.lockDir, quarantine);
+            retired = true;
+            try {
+                (0, node_fs_1.rmSync)(quarantine, { recursive: true, force: true });
+            }
+            catch { /* Never remove a replacement live lock. */ }
+            this.trace(`discard ${reason} ok`);
+            return true;
         }
-        catch {
-            /* late write by the old holder; unique name, harmless */
+        finally {
+            // If the process dies while holding this tiny retirement claim, later
+            // contenders fail closed. Never guess that a claim is abandoned and
+            // risk removing another process's active coordination primitive.
+            if (!retired) {
+                try {
+                    (0, node_fs_1.unlinkSync)((0, node_path_1.join)(claim, 'owner'));
+                }
+                catch { /* A missing owner record is harmless while this process holds the claim. */ }
+                try {
+                    (0, node_fs_1.rmdirSync)(claim);
+                }
+                catch { /* Conservative failure; future callers fail closed. */ }
+            }
         }
-        this.trace(`discard ${reason} ok`);
-        return true;
     }
     trace(line) {
         if (!process.env.AGENTGUARD_DEBUG_LOCK)
@@ -168,27 +189,17 @@ class ReservationStore {
     recoverIfStale() {
         const owner = this.readOwnerAt(this.lockDir);
         if (owner) {
-            const stale = !pidAlive(owner.pid) || Date.now() - owner.since > LOCK_STALE_MS;
+            const stale = !pidAlive(owner.pid);
             if (stale) {
                 this.trace(`reclaim: owner ${owner.pid} alive=${pidAlive(owner.pid)} age=${Date.now() - owner.since}ms`);
                 this.discard('stale', owner.nonce);
             }
             return;
         }
-        // No trustworthy owner record: the holder is between mkdir and rename, or
-        // it died in that gap. Only the directory's age can tell those apart.
-        // Reclaiming immediately here was the race that let a 41st spawn through
-        // under 60 concurrent processes.
-        try {
-            const age = Date.now() - (0, node_fs_1.statSync)(this.lockDir).mtimeMs;
-            if (age > LOCK_STALE_MS) {
-                this.trace(`reclaim ownerless dir age=${age}ms`);
-                this.discard('orphan', null);
-            }
-        }
-        catch {
-            /* directory vanished between checks: the next mkdir attempt decides */
-        }
+        // An ownerless directory may belong to a creator paused between mkdir and
+        // publishing its owner record. Age cannot prove that creator is dead, and
+        // publication does not take the retirement claim. Never reclaim this gap
+        // automatically: an abandoned ownerless lock requires manual recovery.
     }
     release() {
         // Only our own instance is released. If it was reclaimed and a sibling
@@ -299,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;
@@ -307,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;
@@ -132,6 +133,12 @@ export type Mode = 'shadow' | 'enforce';
 export interface Policy {
     mode: Mode;
     thresholds: Thresholds;
+    /** Additive local usage advisories. Older policy files use these defaults. */
+    insights?: {
+        rewriteWarnDollarsPerHour?: number;
+        heavyTurnTokens?: number;
+        pricingFile?: string;
+    };
     /** Calibration provenance, so a report can say where its numbers came from. */
     calibration?: {
         sessionsSampled: number;