@agentguard-run/burn 0.2.3 → 0.2.6

package/dist/src/insights/attribution.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyRewrite = classifyRewrite;
+exports.attributeTurns = attributeTurns;
+const types_1 = require("./types");
+const transcript_1 = require("./transcript");
+function classifyRewrite(turn) {
+    if (!(turn.cacheWriteTokens > 150_000 && turn.cacheWriteTokens > turn.contextTokens / 2))
+        return null;
+    const idleMs = turn.signals.idleMs;
+    const ttl = turn.cacheTtlSeconds;
+    const evidence = { turnId: turn.id, cacheWriteTokens: turn.cacheWriteTokens, contextTokens: turn.contextTokens,
+        ...(idleMs !== undefined ? { idleMs } : {}), idleOver60Minutes: idleMs !== undefined && idleMs > 3_600_000,
+        ...(ttl ? { ttlSeconds: ttl } : {}), ttlUnknown: !ttl };
+    if (ttl && idleMs !== undefined && idleMs > ttl * 1000)
+        return { ...evidence, cause: 'idle_ttl_expired', explanation: 'Idle gap exceeds the TTL reported for this cache-write class; timing is consistent with expiration.' };
+    if (turn.signals.afterCompaction)
+        return { ...evidence, cause: 'compaction', explanation: 'A compaction boundary immediately precedes this usage turn.' };
+    if (turn.signals.firstSpawnedTurn)
+        return { ...evidence, cause: 'first_spawned_turn', explanation: 'This is the first recorded usage turn in an explicitly identified subagent session.' };
+    if (!ttl)
+        return { ...evidence, cause: 'unknown_ttl', explanation: 'Cache TTL is absent or mixed; expiration cannot be distinguished from a prefix change.' };
+    return { ...evidence, cause: 'prefix_change', explanation: turn.signals.prefixChanged
+            ? 'The host reports a changed prefix identifier without an expired-TTL or compaction signal.'
+            : 'No expiration, compaction, or first-subagent-turn signal explains the rewrite; prefix change is a residual hypothesis, not an observed cause.' };
+}
+const tokenCategories = ['input', 'cacheCreation', 'cacheRead', 'output'];
+const emptyBuckets = () => types_1.INSIGHT_BUCKETS.map(bucket => ({ bucket, tokens: 0,
+    categories: { input: 0, cacheCreation: 0, cacheRead: 0, output: 0 } }));
+/** Largest remainders split an already measured token total without inventing tokens from bytes. */
+function integerShares(total, weights) {
+    const weight = weights.reduce((sum, value) => sum + value, 0);
+    if (!weight || !total)
+        return weights.map(() => 0);
+    const exact = weights.map(value => total * (value / weight));
+    const shares = exact.map(Math.floor);
+    const order = exact.map((value, index) => ({ index, remainder: value - shares[index] }))
+        .sort((a, b) => b.remainder - a.remainder || a.index - b.index);
+    for (let left = total - shares.reduce((sum, value) => sum + value, 0), i = 0; left > 0; left--, i++)
+        shares[order[i % order.length].index]++;
+    return shares;
+}
+/** Partition measured usage; byte lengths only divide a measured increment among its recorded events. */
+function attributeTurns(turns) {
+    const buckets = emptyBuckets();
+    const byBucket = new Map(buckets.map(bucket => [bucket.bucket, bucket]));
+    const result = { buckets, totalTokens: 0, rewrites: [],
+        rewriteCounts: { idle_ttl_expired: 0, compaction: 0, first_spawned_turn: 0, prefix_change: 0, unknown_ttl: 0 },
+        idleOver60MinuteRewrites: 0, uncertainties: [], turnAttributions: [], sharedTurns: 0,
+        prefixRebaselines: 0, previousOutputTokensReserved: 0 };
+    const uncertainties = new Set();
+    const sessions = new Map();
+    const ordered = (0, transcript_1.deduplicateTurns)(turns).sort((a, b) => (a.at ?? 0) - (b.at ?? 0));
+    for (const turn of ordered) {
+        const remaining = { input: turn.inputTokens, cacheCreation: turn.cacheWriteTokens, cacheRead: turn.cacheReadTokens, output: turn.outputTokens };
+        const turnBuckets = emptyBuckets();
+        const turnByBucket = new Map(turnBuckets.map(bucket => [bucket.bucket, bucket]));
+        const totalTokens = Object.values(remaining).reduce((sum, value) => sum + value, 0);
+        result.totalTokens += totalTokens;
+        const allocate = (bucket, category, tokens) => {
+            const amount = Math.min(remaining[category], Math.max(0, tokens));
+            if (amount < tokens)
+                uncertainties.add('attribution_evidence_exceeds_category_total');
+            for (const target of [byBucket.get(bucket), turnByBucket.get(bucket)]) {
+                target.tokens += amount;
+                target.categories[category] += amount;
+            }
+            remaining[category] -= amount;
+        };
+        const previous = sessions.get(turn.sessionId);
+        let prefix = previous?.prefix ?? turn.contextTokens;
+        allocate('output', 'output', remaining.output);
+        const rewrite = classifyRewrite(turn);
+        if (rewrite) {
+            result.rewrites.push(rewrite);
+            result.rewriteCounts[rewrite.cause]++;
+            if (rewrite.idleOver60Minutes)
+                result.idleOver60MinuteRewrites++;
+            allocate('full_prefix_rewrites', 'cacheCreation', remaining.cacheCreation);
+            if (rewrite.ttlUnknown)
+                uncertainties.add('rewrite_ttl_unknown');
+            if (rewrite.cause === 'prefix_change') {
+                prefix = turn.contextTokens;
+                if (previous)
+                    result.prefixRebaselines++;
+                if (!turn.signals.prefixChanged)
+                    uncertainties.add('prefix_change_is_residual_hypothesis');
+            }
+        }
+        for (const item of turn.explicitAttribution) {
+            if (item.bucket !== 'output' && item.bucket !== 'full_prefix_rewrites' && item.bucket !== 'unattributed' && Number.isSafeInteger(item.tokens) && item.tokens > 0)
+                allocate(item.bucket, item.category, item.tokens);
+        }
+        if (turn.subagent) {
+            for (const category of ['input', 'cacheCreation', 'cacheRead'])
+                allocate('subagent_fanout', category, remaining[category]);
+        }
+        else if (!turn.explicitAttribution.length) {
+            if (!previous || rewrite?.cause === 'prefix_change') {
+                // Rewrites retain their measured write tokens; the rest establishes the new fixed prefix.
+                for (const category of ['input', 'cacheCreation', 'cacheRead'])
+                    allocate('instruction_stack', category, remaining[category]);
+            }
+            else {
+                const history = Math.max(0, turn.cacheReadTokens - prefix);
+                allocate('instruction_stack', 'cacheRead', Math.min(remaining.cacheRead, prefix));
+                allocate('history_resent', 'cacheRead', Math.min(remaining.cacheRead, history));
+                if (!rewrite) {
+                    // Prior assistant output reappears in input usage but is not newly arrived content.
+                    // Keep that measured input in the residual rather than count it as generated output twice.
+                    let reserved = Math.min(previous.previousOutput, remaining.input + remaining.cacheCreation);
+                    result.previousOutputTokensReserved += reserved;
+                    for (const category of ['input', 'cacheCreation']) {
+                        const amount = Math.min(reserved, remaining[category]);
+                        allocate('unattributed', category, amount);
+                        reserved -= amount;
+                    }
+                    const interval = turn.interval;
+                    const eventBuckets = ['tool_output', 'reread_files', 'conversation'];
+                    let weights = interval ? [interval.toolOutputBytes, interval.reReadBytes, interval.conversationBytes] : [0, 0, 0];
+                    if (interval && !weights.some(value => value > 0)) {
+                        // A sole event class owns the whole measured increment even for an
+                        // empty result; mixed empty payloads have no byte-based split.
+                        const present = [interval.toolResults > (interval.reReadResults ?? 0), (interval.reReadResults ?? 0) > 0, interval.userMessages > 0];
+                        if (present.filter(Boolean).length === 1)
+                            weights = present.map(value => value ? 1 : 0);
+                    }
+                    if (weights.some(value => value > 0)) {
+                        const shares = integerShares(remaining.input + remaining.cacheCreation, weights);
+                        const inputs = integerShares(remaining.input, shares);
+                        if (interval.shared && shares.some(value => value > 0))
+                            result.sharedTurns++;
+                        eventBuckets.forEach((bucket, i) => {
+                            allocate(bucket, 'input', inputs[i]);
+                            allocate(bucket, 'cacheCreation', shares[i] - inputs[i]);
+                        });
+                    }
+                }
+            }
+        }
+        for (const category of tokenCategories)
+            allocate('unattributed', category, remaining[category]);
+        turn.uncertainties.forEach(value => uncertainties.add(value));
+        sessions.set(turn.sessionId, { prefix, previousOutput: turn.outputTokens });
+        result.turnAttributions.push({ turnId: turn.id, sessionId: turn.sessionId, buckets: turnBuckets, totalTokens });
+    }
+    if (byBucket.get('unattributed').tokens)
+        uncertainties.add('unattributed_usage_includes_prior_output_and_missing_event_evidence');
+    result.uncertainties = [...uncertainties].sort();
+    return result;
+}

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/live.d.ts

@@ -0,0 +1,53 @@
+import type { Policy } from '../types';
+import type { InsightHost, InsightParserState, InsightTurn } from './types';
+import { type PricingTable } from './pricing';
+import { type Pace, type UsageWindow, type LimitForecast } from './pace';
+export interface InsightSettings {
+    rewriteWarnDollarsPerHour?: number;
+    heavyTurnTokens?: number;
+    pricingFile?: string;
+}
+export interface LiveSnapshot {
+    schema: 1;
+    host: InsightHost;
+    sessionId: string;
+    updatedAt: number;
+    toolEvents: number;
+    cursor: {
+        offset: number;
+        inode: number;
+        pathDigest: string;
+    };
+    parser?: InsightParserState;
+    pace: Pace;
+    windows: UsageWindow[];
+    forecast: LimitForecast;
+    lastTurnTokens: number;
+    rewriteDollarsToday: {
+        min: number;
+        max: number;
+    } | null;
+    unpricedRewritesToday: number;
+    heavyAbove: boolean;
+    rewriteAbove: boolean;
+}
+export interface LiveInput {
+    session_id?: string;
+    transcript_path?: string;
+    tool_name?: string;
+    rate_limits?: unknown;
+}
+export declare function pacePath(home: string, sessionId: string): string;
+export declare function readPricing(home: string, policy?: Policy): PricingTable;
+export declare function dollars(value: {
+    min: number;
+    max: number;
+} | null): string;
+export declare function hostWindows(value: unknown, source: UsageWindow['source'], at: number): UsageWindow[];
+export declare function heavyTurnMessage(turn: InsightTurn, rates: PricingTable): string;
+/** Local advisory observer. No tool input or output content enters this API. */
+export declare function observeTool(home: string, input: LiveInput, host: InsightHost, policy: Policy, now?: number): {
+    snapshot?: LiveSnapshot;
+    messages: string[];
+};
+export declare function renderStatusLine(snapshot: LiveSnapshot): string;