@agentguard-run/burn 0.2.2 → 0.2.5

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

@@ -0,0 +1,157 @@
+/** 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;
+    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/replay/render.js

@@ -160,7 +160,7 @@ function renderReplay(summary, opts = {}) {
         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) {
-        out.push(row(paint(on, C.dim, `… ${summary.sessions.length - top} more, all clean`)));
+        out.push(row(paint(on, C.dim, `… ${summary.sessions.length - top} more sessions (included in totals)`)));
     }
     out.push(MID);
     out.push(row(paint(on, C.dim, 'Upper bound; assumes no override or restart. Nothing left this machine.')));

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

@@ -0,0 +1,3 @@
+import type { SessionState } from '../types';
+export declare const ACTIVE_SESSION_WINDOW_MS: number;
+export declare function readAccountSessions(home: string, current: SessionState, now: number): SessionState[];

package/dist/src/state/account.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACTIVE_SESSION_WINDOW_MS = void 0;
+exports.readAccountSessions = readAccountSessions;
+/** Read the same hook and gateway session files used by machine status. */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+exports.ACTIVE_SESSION_WINDOW_MS = 30 * 60 * 1000;
+function readAccountSessions(home, current, now) {
+    const sessions = new Map();
+    let names;
+    try {
+        names = (0, node_fs_1.readdirSync)((0, node_path_1.join)(home, 'sessions'));
+    }
+    catch {
+        names = [];
+    }
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        try {
+            const raw = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(home, 'sessions', name), 'utf8'));
+            if (!raw.state || (raw.closedAt !== undefined && raw.closedAt !== null))
+                continue;
+            const state = raw.state;
+            if (typeof state.sessionId !== 'string' || !Number.isFinite(state.lastEventAt))
+                continue;
+            const prior = sessions.get(state.sessionId);
+            if (!prior || state.lastEventAt > prior.lastEventAt) {
+                sessions.set(state.sessionId, { ...state, tokensByActiveMinute: new Map(state.tokensByActiveMinute) });
+            }
+        }
+        catch { /* Ignore malformed or foreign session files, as status does. */ }
+    }
+    // Include this admission, even when its transcript has no new usage yet.
+    // Replacing by ID prevents double counting the caller's persisted snapshot.
+    sessions.set(current.sessionId, { ...current, lastEventAt: now });
+    return [...sessions.values()];
+}

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;

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) {
@@ -69,6 +69,7 @@ class ReservationStore {
     /** Acquire the lock or throw. Callers must fail closed on throw. */
     acquire() {
         const deadline = Date.now() + LOCK_WAIT_MS;
+        let attempt = 0;
         for (;;) {
             try {
                 (0, node_fs_1.mkdirSync)(this.lockDir, { mode: 0o700 });
@@ -90,7 +91,10 @@ class ReservationStore {
                 if (Date.now() > deadline) {
                     throw new Error('AgentGuard could not acquire the reservation lock; failing closed.');
                 }
-                sleepSync(LOCK_SPIN_MS);
+                // Hundreds of waiters polling together can starve the holder. Spread
+                // retries with bounded backoff while retaining the existing deadline.
+                const backoff = Math.min(250, LOCK_SPIN_MS * 2 ** Math.min(attempt++, 4));
+                sleepSync(Math.min(Math.max(1, deadline - Date.now()), backoff * (0.5 + Math.random() / 2)));
             }
         }
     }
@@ -114,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)
@@ -164,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

package/dist/src/types.d.ts

@@ -132,6 +132,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;

package/docs/USAGE_AND_PRICING.md

@@ -0,0 +1,132 @@
+# Understand local usage
+
+Burn reads the usage metadata already saved by your coding agent. It separates fresh input, cache writes, cache reads and output. The dollar estimate is the equivalent cost at the recorded API list rates. It is not a subscription bill, an account allowance or a conversion from tokens into your plan's limits.
+
+The observer and reports run locally without network requests. Reports contain usage counts, model identifiers, timestamps and explanations supported by metadata. They do not copy prompt text, file contents, tool arguments or model output into the usage report.
+
+## Commands
+
+```sh
+agentguard-burn why
+agentguard-burn why SESSION_ID json
+agentguard-burn rewrites all
+agentguard-burn pace SESSION_ID
+agentguard-burn statusline SESSION_ID
+agentguard-burn pricing
+```
+
+`why` breaks down a session's recorded usage. `rewrites` lists large prefix writes and the evidence available for their causes. `pace` and `statusline` show a short local summary. The optional final `json` argument on `why` and `rewrites` makes the report suitable for another local program.
+
+## Attribution method in 0.2.5
+
+The first distinct assistant response establishes its session's fixed-prefix baseline from input, cache creation and cache read tokens. The instruction stack + system row uses that initial measured context and the corresponding prefix portion of later cache reads. This baseline includes the initial user message. A rewrite classified as prefix change resets it to that response's context, which can include existing history. The label is a baseline attribution rule, not a claim that instruction files alone contain that many tokens.
+
+History re-sent is each response's cache reads above the fixed prefix, floored at zero. The arriving increment is fresh input plus cache creation after subtracting the previous response's output. Intervening user messages receive conversation tokens. Tool results receive tool output tokens, except a recorded Read result for a previously read path receives re-read file tokens. When several results or user messages share an increment, their recorded UTF-8 byte sizes determine proportions of the measured token total. Integer rounding uses largest remainders so no token disappears. Mixed user and tool intervals are marked shared and counted in the footer.
+
+A qualifying full-prefix rewrite retains its measured cache-creation tokens and is excluded from event-increment attribution. Explicit child transcripts retain their existing fan-out attribution after rewrites. Generated output is counted once. To conserve all recorded usage, the input tokens reserved by previous-output subtraction remain in the unattributed residual, together with intervals without usable event evidence. A single event category can own an increment even when its payload is empty; mixed empty payloads have no measurable byte proportions and remain residual.
+
+Repeated usage snapshots for one provider response keep the original interval rather than consuming later events again. Read paths, tool IDs and event identities are hashed in local state. Only byte counts and metadata survive parsing, never text. Shell commands that happen to read a file remain tool output unless the host records a Read call. Existing explicit host token-category instrumentation takes precedence where available.
+
+The table's Method footer has one sentence per bucket. Zero now means a computed zero rather than a missing measurement. Old pace caches without interval metadata are rebuilt once from the local transcript. When auditing a date range, establish baselines from complete session histories before selecting the responses in that range.
+
+## Cache writes and long sessions
+
+For Claude, `cache_creation_input_tokens` is the total written. When the transcript also includes `cache_creation.ephemeral_5m_input_tokens` and `cache_creation.ephemeral_1h_input_tokens`, Burn uses that split. If the lifetime is unavailable, Burn returns a range between the two published write rates. A long pause alone does not establish the requested cache lifetime. See the [provider's cache usage fields](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration).
+
+A large rewrite after a recorded compaction, a first subagent turn, a recorded prefix change or an idle interval can explain expensive turns. These are evidence labels, not proof that one cause was solely responsible. When metadata does not identify a cause or lifetime, the report says so.
+
+For `claude-fable-5-1`, 500,000 cache-read tokens have a $0.125 API equivalent. Writing that many tokens costs $6.25 with a five-minute lifetime or $10 with a one-hour lifetime. At the same verified cache-read rate, 1.69 billion reads cost $422.50. Multiplying all token categories by the fresh-input rate would give the wrong result.
+
+## Pricing sources and overrides
+
+Every bundled row includes its exact model identifier, `sourceUrl` and `verifiedAt`. The rates were checked on 2026-09-17. The runtime never downloads pricing. Run `agentguard-burn pricing` to inspect the installed table.
+
+The Claude rows use the [official model price list](https://platform.claude.com/docs/en/about-claude/pricing). Amounts below are USD per million tokens in the order fresh input, cache read, five-minute write, one-hour write, output:
+
+* `claude-fable-5-1`: 10, 0.25, 12.5, 20, 50.
+* `claude-fable-5`: 10, 1, 12.5, 20, 50.
+* `claude-opus-5` and `claude-opus-4-8`: 5, 0.5, 6.25, 10, 25.
+* `claude-sonnet-5`: 2, 0.2, 2.5, 4, 10.
+* `claude-haiku-4-5-20251001`: 1, 0.1, 1.25, 2, 5.
+
+The [OpenAI API price list](https://developers.openai.com/api/docs/pricing) supplies these standard rates in the order fresh input, cache read, cache write, output:
+
+* `gpt-6-astra`: 10, 1, 12.5, 50.
+* `gpt-5.6-sol`: 4, 0.4, 5, 20. These are the published promotional rates on the verification date.
+* `gpt-5.6-luna`: 0.2, 0.02, 0.25, 1.2.
+
+These OpenAI rows have one published cache-write price rather than separate lifetime prices. For requests with more than 272,000 input tokens, Burn applies the documented API multiplier of two to fresh input, reads and writes, and 1.5 to output. It uses the request's reported input counts, not the model's advertised context capacity.
+
+The [GPT-5.4 Mini model page](https://developers.openai.com/api/docs/models/gpt-5.4-mini) supplies 0.75 input, 0.075 cached input and 4.5 output. Its separate cache-write rate is unverified and remains `null`. Unknown model identifiers, including unlisted aliases, keep their token counts but have no dollar estimate. Burn does not infer prices from a model family name.
+
+**Codex charges can differ from the API equivalent.** OpenAI's [Enterprise rate card](https://help.openai.com/en/articles/20001415) says that Codex does not charge for cache writes and that Astra in Codex does not incur the API long-context surcharge. Its other billing rules and included subscription allowances also differ. Burn's default table intentionally describes API list prices, not what a Codex subscriber owes. Fast processing, regional premiums, batch discounts, tools, taxes and negotiated rates are outside this standard estimate.
+
+To use different rates, create a local JSON file and set `AGENTGUARD_BURN_PRICING_FILE` to its path. You can also set `insights.pricingFile` in the Burn policy. Otherwise Burn checks `burn-pricing.json` under `AGENTGUARD_HOME`, or the normal Burn home when that variable is absent. Listed models replace the matching bundled row; other bundled rows remain available.
+
+```json
+{
+  "models": {
+    "example-model": {
+      "input": 2,
+      "cacheRead": 0.2,
+      "cacheWrite5m": null,
+      "cacheWrite1h": null,
+      "output": 8,
+      "sourceUrl": "https://example.com/your-agreed-rates",
+      "verifiedAt": "2026-09-17"
+    }
+  }
+}
+```
+
+These example prices are placeholders. Use a source that establishes your actual rates. Every category must be a nonnegative number or `null`; `null` means unknown, and zero means a verified zero price. If a turn has tokens in an unknown category, its full dollar estimate remains unavailable. Partial known categories remain visible in the pricing result.
+
+For a single write rate, set equal `cacheWrite5m` and `cacheWrite1h` values and add `"cacheWriteTtl": "not_tiered"`. An optional `longContext` object takes `aboveInputTokens`, `inputMultiplier` and `outputMultiplier`. An override without that object has no automatic context surcharge. This lets an operator express a verified contract without inheriting an incompatible API rule.
+
+## What the hosts expose
+
+Claude Code supplies `session_id` and `transcript_path` to hooks. Its transcript is written asynchronously, so a hook may observe usage a little after the corresponding response. The hook schema does not promise account rate-limit percentages. See [Claude Code hook input](https://code.claude.com/docs/en/hooks#common-input-fields).
+
+The [Claude Code statusline contract](https://code.claude.com/docs/en/statusline) separately exposes `rate_limits.five_hour.used_percentage`, `rate_limits.seven_day.used_percentage` and each window's `resets_at` in Unix seconds. A window may be absent, and expired windows are removed. `context_window.used_percentage` measures current context occupancy; it is not an account-limit percentage. A custom statusline can invoke Burn with the JSON supplied on stdin:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "agentguard-burn statusline"
+  }
+}
+```
+
+This is an example for operator review. Running the reporting commands does not install this setting. If another statusline is already configured, combine its output with Burn in your existing script instead of replacing it.
+
+In Codex 0.154.0, transcript `token_count` records can contain `rate_limits.primary` and `rate_limits.secondary`. Each window uses `used_percent`, optional `window_minutes` and optional `resets_at` in Unix seconds. Primary and secondary names alone do not establish a five-hour or weekly duration. The released [protocol definitions](https://github.com/openai/codex/blob/rust-v0.154.0/codex-rs/protocol/src/protocol.rs#L2318) establish these fields. The hook contract supplies a transcript path, not a separate promise of quota fields.
+
+Codex input totals include cache reads and writes. Burn separates them before pricing fresh input. Reasoning output is already part of total output and is not added again. The released [usage decoder test](https://github.com/openai/codex/blob/rust-v0.154.0/codex-rs/codex-api/src/sse/responses.rs#L898) demonstrates an input total of 100 consisting of 40 reads and 60 writes, plus 10 output tokens that include five reasoning tokens.
+
+Codex 0.154.0 supports a fixed list of built-in footer items, not an external status command. Its [released statusline implementation](https://github.com/openai/codex/blob/rust-v0.154.0/codex-rs/tui/src/bottom_pane/status_line_setup.rs#L56) and [configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference#tuistatus_line) document that boundary. Use its native limit indicators and run the one-line Burn companion in a terminal:
+
+```toml
+[tui]
+status_line = ["model", "context-remaining", "five-hour-limit", "weekly-limit"]
+```
+
+```sh
+agentguard-burn statusline SESSION_ID
+```
+
+## Forecast limits without inventing a quota
+
+The last ten minutes of recorded usage establish cached and uncached token pace and a next-hour projection. An account-limit forecast requires multiple explicit percentage observations from the same unexpired host window. It follows the observed change in percentage over time. Neither a token maximum nor a cache discount is inferred from subscription price, context size or API cost.
+
+When snapshots are missing, stale, unchanged, reset or otherwise insufficient, the line reports an unknown limit with a reason. A forecast reflects recent activity only; other sessions or a change in workload can change the result. The host's own usage screen remains the authority for the remaining allowance.
+
+## Unknown inherited history
+
+Some older Codex fork transcripts copy a parent's usage without an authoritative boundary. Burn excludes that inherited history and reports usage unavailable rather than charging the copy again. Reports across sessions identify how many histories were excluded. Those totals are incomplete. Newer transcripts with an explicit inherited-history ordinal or a child-owned thread settings event can separate the copied prefix from new usage.
+
+## Reservation lock recovery
+
+The reservation lock waits up to eight seconds. A process that fails closed because it could not acquire that lock does not contribute to the decision count or the seven-day age required for enforcement eligibility. Other old ledger rows keep their existing interpretation.
+
+Retiring an abandoned lock is serialized before renaming it, so a stale observer cannot temporarily move a live replacement lock. If a process crashes during the retirement claim itself, the conservative result can be continued fail-closed lock waits. A directory without a valid owner record also requires manual recovery: its creator might be paused before publishing ownership, and directory age cannot prove that process is dead. Recovery requires stopping all clients using that Burn home, confirming that every PID recorded in `burn.lock/owner` and `burn.lock/retiring/owner` is dead, moving that abandoned lock directory aside, then restarting the clients. If either owner record is absent or unreadable, keep every client stopped during recovery. Do not remove a lock while any of those clients is running.

package/fixtures/codex-0.151.0-pretooluse.json

@@ -1,9 +1,9 @@
 {
-  "captured_from": "codex-cli 0.151.0, 2026-09-03, codex exec with -c hooks.PreToolUse inline; --dangerously-bypass-hook-trust",
+  "captured_from": "Synthetic identifiers; payload shape based on codex-cli 0.151.0 PreToolUse, 2026-09-03",
   "payloads": [
     {
-      "session_id": "01a069d3-5fc8-7470-8c95-1b42e7206746",
-      "turn_id": "01a069d3-6018-7523-a26e-eea10123676c",
+      "session_id": "00000000-0000-7000-8000-000000000001",
+      "turn_id": "00000000-0000-7000-8000-000000000011",
       "transcript_path": "/Users/example/.codex/sessions/2026/09/03/rollout-example.jsonl",
       "cwd": "/Users/example/project",
       "hook_event_name": "PreToolUse",
@@ -13,11 +13,11 @@
       "tool_input": {
         "command": "echo CANARY_OK"
       },
-      "tool_use_id": "call_NmxrZob0I2KFC8ChNe2PduGX"
+      "tool_use_id": "call_SYNTHETIC000000000000001"
     },
     {
-      "session_id": "01a069d4-d356-73b3-9440-1c4440319de8",
-      "turn_id": "01a069d4-d3b2-7593-85ec-8a0281f51bf1",
+      "session_id": "00000000-0000-7000-8000-000000000002",
+      "turn_id": "00000000-0000-7000-8000-000000000012",
       "transcript_path": "/Users/example/.codex/sessions/2026/09/03/rollout-example.jsonl",
       "cwd": "/Users/example/project",
       "hook_event_name": "PreToolUse",
@@ -28,11 +28,11 @@
         "message": "<redacted>",
         "fork_context": "<redacted>"
       },
-      "tool_use_id": "call_oktUPQ5jcosNPOcGnEaWqRcv"
+      "tool_use_id": "call_SYNTHETIC000000000000002"
     },
     {
-      "session_id": "01a069d4-d356-73b3-9440-1c4440319de8",
-      "turn_id": "01a069d4-d3b2-7593-85ec-8a0281f51bf1",
+      "session_id": "00000000-0000-7000-8000-000000000002",
+      "turn_id": "00000000-0000-7000-8000-000000000012",
       "transcript_path": "/Users/example/.codex/sessions/2026/09/03/rollout-example.jsonl",
       "cwd": "/Users/example/project",
       "hook_event_name": "PreToolUse",
@@ -43,7 +43,7 @@
         "targets": "<redacted>",
         "timeout_ms": "<redacted>"
       },
-      "tool_use_id": "call_RK95A6i4UUhTigIGXF24gMMO"
+      "tool_use_id": "call_SYNTHETIC000000000000003"
     }
   ]
-}
+}