@agentguard-run/burn 0.3.0 → 0.3.2

package/dist/src/live-panel.js

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StopHold = exports.SessionFollow = void 0;
+exports.panelDecisions = panelDecisions;
+exports.collectLivePanel = collectLivePanel;
+exports.spawnBarColor = spawnBarColor;
+exports.renderLivePanel = renderLivePanel;
+exports.panelFromReport = panelFromReport;
+exports.runLivePanel = runLivePanel;
+/** Local, content-free instrument panel. It observes; it never changes admission. */
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const canvas_1 = require("./canvas");
+const ledger_panel_1 = require("./ledger-panel");
+const recording_1 = require("./recording");
+const digest = (text) => (0, node_crypto_1.createHash)('sha256').update(text).digest('hex');
+/** The ledger is the single source for decisions, counters and session selection. */
+function panelDecisions(home, sessionId, at = Date.now()) {
+    return (0, ledger_panel_1.projectLedgerPanel)((0, ledger_panel_1.readPanelLedger)(home), sessionId, at).decisions;
+}
+function collectLivePanel(home, session, now = Date.now()) {
+    return (0, ledger_panel_1.projectLedgerPanel)((0, ledger_panel_1.readPanelLedger)(home), session, now);
+}
+/** Record changes of identity, including switches between sessions with the same short prefix. */
+class SessionFollow {
+    previous;
+    update(snapshot, now) {
+        const identity = snapshot.sessionDigest ?? snapshot.session;
+        const sessionSwitch = this.previous !== undefined && this.previous !== identity
+            ? { from: this.previous, to: identity, at: now } : undefined;
+        this.previous = identity;
+        return { ...snapshot, ...(sessionSwitch ? { sessionSwitch } : {}) };
+    }
+}
+exports.SessionFollow = SessionFollow;
+const compact = (v) => v === null ? { digits: '-', unit: 'unknown' } : v >= 1e9 ? { digits: (v / 1e9).toFixed(2), unit: 'B tokens' } : v >= 1e6 ? { digits: (v / 1e6).toFixed(2), unit: 'M tokens' } : v >= 1e3 ? { digits: (v / 1e3).toFixed(1), unit: 'K tokens' } : { digits: String(Math.round(v)), unit: 'tokens' };
+function spawnBarColor(spawns, ceiling) {
+    return spawns === null || ceiling === null ? 'slate' : spawns >= ceiling ? 'red' : spawns >= ceiling * .8 ? 'amber' : 'mint';
+}
+function elapsed(ms) {
+    const seconds = Math.max(0, Math.floor(ms / 1000));
+    return `${String(Math.floor(seconds / 3600)).padStart(2, '0')}:${String(Math.floor(seconds / 60) % 60).padStart(2, '0')}:${String(seconds % 60).padStart(2, '0')}`;
+}
+function renderLivePanel(snapshot, options = {}) {
+    const c = new canvas_1.Canvas(options), w = c.width, h = c.height, narrow = w < 80, split = narrow ? w : Math.floor(w * .45), right = narrow ? 0 : split + 3, room = w - right;
+    const at = options.at ?? new Date(snapshot.observedAt).toISOString(), color = spawnBarColor(snapshot.spawns, snapshot.spawnCeiling);
+    c.header('AGENTGUARD / BURN', options.recorded ? 'RECORDED RUN · 1x' : 'LIVE');
+    c.footer(snapshot.controls === false ? 'local observation only' : narrow ? 'q quit · p pause' : 'q quit · p pause · local only', `${narrow ? '' : 'elapsed '}${snapshot.elapsedMs === null ? 'unknown' : elapsed(snapshot.elapsedMs ?? snapshot.observedAt - snapshot.startedAt)}`);
+    c.put(2, 0, `session ${snapshot.session} · ${at.slice(11, 19)} UTC`, 'slate');
+    if (!narrow)
+        for (let y = 3; y < h - 3; y++)
+            c.put(y, split + 1, '│', 'slate');
+    const leftWidth = split, first = h >= 30 ? 4 : 3, second = h >= 30 ? 11 : 8, third = h >= 30 ? 18 : 13;
+    c.put(first, 0, 'SPAWNS', 'slate').digits(first + 1, 0, snapshot.spawns === null ? '-' : snapshot.spawns, color);
+    c.put(first + 4, 0, `${snapshot.windowActiveMinutes ?? '?'} active min · ceiling ${snapshot.spawnCeiling ?? '?'}`.slice(0, leftWidth), 'slate');
+    c.put(second, 0, 'TOKENS IN WINDOW', 'slate');
+    const tokens = compact(snapshot.tokens);
+    c.digits(second + 1, 0, tokens.digits, 'mint');
+    c.put(second + 4, 0, `${tokens.unit} · ${snapshot.windowActiveMinutes ?? '?'} active min`.slice(0, leftWidth), 'slate');
+    c.put(third, 0, 'REPLAY SHARE %', 'slate').digits(third + 1, 0, snapshot.replayShare === null ? '-' : Math.round(snapshot.replayShare * 100), 'mint');
+    c.put(third + 4, 0, 'session cache-read / tokens'.slice(0, leftWidth), 'slate');
+    const barRow = h - 6;
+    c.put(barRow, 0, `SPAWN RATE ${snapshot.spawns ?? '?'} / ${snapshot.spawnCeiling ?? '?'}`.slice(0, leftWidth), color);
+    c.bar(barRow + 1, 0, leftWidth, snapshot.spawns === null || snapshot.spawnCeiling === null ? 0 : snapshot.spawns / snapshot.spawnCeiling, color);
+    if (!narrow)
+        c.put(first, right, 'LAST 8 DECISIONS', 'slate');
+    (narrow ? [] : snapshot.decisions.slice(-8)).forEach((d, index) => {
+        const y = first + 1 + index * 2, chip = d.verdict === 'OK' ? 'clean' : d.verdict, tint = d.verdict === 'STOP' ? 'red' : d.verdict === 'WARN' ? 'amber' : 'mint';
+        c.put(y, right, `${new Date(d.at).toISOString().slice(11, 19)} ${d.tool}`.slice(0, Math.max(0, room - 8)), 'white');
+        c.put(y, Math.max(right, w - 7), `[${chip}]`, tint);
+        c.put(y + 1, right, d.reason.slice(0, room), 'slate');
+    });
+    if (!narrow && !snapshot.decisions.length)
+        c.put(6, right, 'No recorded decisions yet.', 'slate');
+    if (snapshot.stop) {
+        const y = h >= 30 ? h - 11 : 16;
+        for (let i = 0; i < 5; i++)
+            c.put(y + i, right, ' '.repeat(room), 'none');
+        c.put(y, right, 'STOP · ' + (snapshot.stop.blocked === true ? 'blocked' : snapshot.stop.blocked === false ? 'shadow / allowed' : 'outcome unknown'), 'red');
+        c.put(y + 1, right, snapshot.stop.reason.slice(0, room), 'red');
+        c.put(y + 2, right, snapshot.stopHold === false ? 'Latest STOP reason.' : 'Reason held for 2 seconds.', 'slate');
+    }
+    c.put(h - 3, 0, snapshot.note.slice(0, w), 'slate');
+    return c;
+}
+/** STOP report adaptation uses only already-computed metadata, never local I/O. */
+function panelFromReport(report, at, outcome, subject) {
+    const rate = report.findings.find(f => f.detector === 'spawn_rate');
+    const decision = { id: digest(`${report.sessionId}:${at}`), at, tool: subject === 'call' ? 'model_call' : 'spawn', verdict: report.verdict,
+        reason: report.findings.map(f => `${f.detector}:${f.verdict} ${f.observed}/${f.threshold}`).join(' + ') || 'Reason not recorded.', blocked: outcome === undefined ? null : outcome === 'blocked' };
+    const note = outcome === 'blocked' ? (subject === 'call' ? 'model call blocked' : 'agent spawn blocked')
+        : outcome === 'shadow' ? 'shadow: would have blocked, call allowed' : outcome === 'overridden' ? 'override: call allowed'
+            : outcome === 'allowed' ? 'call allowed' : 'STOP boundary · enforcement outcome not recorded';
+    return { session: (/^[A-Za-z0-9_-]+$/.test(report.sessionId) ? report.sessionId : digest(report.sessionId)).slice(0, 8), startedAt: at, observedAt: at, elapsedMs: null, controls: false, stopHold: false,
+        spawns: rate?.observed ?? null, tokens: null, replayShare: Number.isFinite(report.cacheReadRatio) ? report.cacheReadRatio : null,
+        windowActiveMinutes: null, spawnCeiling: rate?.verdict === 'STOP' ? rate.threshold : null,
+        decisions: [decision], stop: decision, note: `${note}. Unknown window metrics remain unknown.` };
+}
+/** Display-only hold. Intake continues and the latest observation follows the card. */
+class StopHold {
+    held;
+    until = 0;
+    seen = new Set();
+    latest;
+    update(snapshot, now) {
+        if (this.latest && (this.latest.sessionDigest ?? this.latest.session) !== (snapshot.sessionDigest ?? snapshot.session)) {
+            this.held = undefined;
+            this.until = 0;
+            this.seen.clear();
+        }
+        this.latest = snapshot;
+        // A historical STOP in the right column must not borrow a later decision's counters.
+        const latestDecision = snapshot.decisions.at(-1);
+        const stop = latestDecision?.verdict === 'STOP' && !this.seen.has(latestDecision.id) ? latestDecision : undefined;
+        for (const decision of snapshot.decisions)
+            this.seen.add(decision.id);
+        if (stop) {
+            this.held = { ...snapshot, stop };
+            this.until = now + 2000;
+        }
+        if (this.held && now < this.until)
+            return this.held;
+        this.held = undefined;
+        return this.latest;
+    }
+}
+exports.StopHold = StopHold;
+async function runLivePanel(home, args) {
+    const flag = (key) => {
+        const i = args.indexOf(key);
+        if (i < 0)
+            return undefined;
+        if (!args[i + 1] || args[i + 1].startsWith('--'))
+            throw new Error(`Use ${key} with a value.`);
+        return args[i + 1];
+    };
+    const replayFile = flag('--replay'), selected = flag('--session');
+    const once = args.includes('--once') || !process.stdout.isTTY;
+    const colour = !args.includes('--no-color') && process.env.NO_COLOR === undefined && Boolean(process.stdout.isTTY);
+    const viewport = { width: Math.min(104, process.stdout.columns || 104), height: Math.min(35, process.stdout.rows || 35) };
+    let paused = false, stopped = false;
+    const key = (bytes) => { const text = String(bytes); if (text.includes('q') || text.includes('\x03'))
+        stopped = true; if (text.includes('p'))
+        paused = !paused; };
+    const stop = () => { stopped = true; };
+    const display = (snapshot, recorded, at) => {
+        (0, recording_1.recordFrame)({ kind: 'live', snapshot }, at, viewport);
+        process.stdout.write((process.stdout.isTTY ? '\x1b[H\x1b[2J' : '') + renderLivePanel(snapshot, { ...viewport, at, recorded, colour }).render() + '\n');
+    };
+    const wait = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+    const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    if (interactive) {
+        process.stdin.setRawMode(true);
+        process.stdin.resume();
+        process.stdin.on('data', key);
+    }
+    process.on('SIGINT', stop);
+    try {
+        if (replayFile) {
+            if (!(0, node_fs_1.existsSync)(replayFile))
+                throw new Error('Local recording is unavailable.');
+            const frames = (0, recording_1.readRecording)(replayFile).filter(frame => frame.data.kind === 'live');
+            if (!frames.length)
+                throw new Error('Recording has no live instrument frames.');
+            for (let i = 0; i < frames.length && !stopped; i++) {
+                const frame = frames[i];
+                if (frame.data.kind !== 'live')
+                    continue;
+                display(frame.data.snapshot, true, frame.at);
+                if (!once) {
+                    const delay = i + 1 < frames.length ? Date.parse(frames[i + 1].at) - Date.parse(frame.at) : 2000;
+                    let remaining = delay;
+                    while (remaining > 0 && !stopped) {
+                        const step = Math.min(100, remaining);
+                        await wait(step);
+                        if (!paused)
+                            remaining -= step;
+                    }
+                }
+            }
+        }
+        else {
+            const hold = new StopHold(), follow = new SessionFollow();
+            do {
+                if (!paused) {
+                    const now = Date.now(), snapshot = follow.update(hold.update(collectLivePanel(home, selected, now), now), now);
+                    display(snapshot, false, new Date(now).toISOString());
+                }
+                if (!once)
+                    await wait(500);
+            } while (!once && !stopped);
+        }
+    }
+    finally {
+        process.off('SIGINT', stop);
+        if (interactive) {
+            process.stdin.off('data', key);
+            process.stdin.setRawMode(false);
+            process.stdin.pause();
+        }
+    }
+    return 0;
+}

package/dist/src/policy.d.ts

@@ -1,4 +1,6 @@
 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;
+export declare function loadPolicy(home: string, options?: {
+    notice?: boolean;
+}): Policy;

package/dist/src/policy.js

@@ -82,7 +82,7 @@ function noticeOnce(home, fields) {
     }
     process.stderr.write(`AgentGuard loaded missing policy fields from defaults: ${fields.join(', ')}; existing overrides are unchanged.\n`);
 }
-function loadPolicy(home) {
+function loadPolicy(home, options = {}) {
     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) {
@@ -91,7 +91,7 @@ function loadPolicy(home) {
                 missing.push('fanout.windowActiveMinutes=120');
             if (parsed.thresholds.spawnRate?.enforce === undefined)
                 missing.push('spawnRate.enforce=true');
-            if (missing.length)
+            if (missing.length && options.notice !== false)
                 noticeOnce(home, missing);
             return normalizePolicy(withTeamThresholds(home, parsed));
         }

package/dist/src/record-ledger.d.ts

@@ -0,0 +1,30 @@
+import { type LedgerDecision } from './ledger-panel';
+import type { RecordedFrame } from './recording';
+export interface RecordLedgerOptions {
+    session: string;
+    from?: string;
+    to?: string;
+    out: string;
+}
+export interface RecordLedgerResult {
+    output: string;
+    session: string;
+    from: string;
+    to: string;
+    frameCount: number;
+    decisionCount: number;
+    clippedStopHold: boolean;
+}
+/** Require an explicit timezone and reject dates Date.parse would normalize. */
+export declare function ledgerTimestamp(value: string): number;
+export declare function validateCompanionRecording(home: string, output: string, recording: string): void;
+export declare function recordLedgerArguments(args: string[]): RecordLedgerOptions;
+export declare function reconstructLedgerFrames(rows: LedgerDecision[], options: Omit<RecordLedgerOptions, 'out'>): {
+    frames: RecordedFrame[];
+    session: string;
+    from: number;
+    to: number;
+    decisionCount: number;
+    clippedStopHold: boolean;
+};
+export declare function recordLedger(home: string, options: RecordLedgerOptions): RecordLedgerResult;

package/dist/src/record-ledger.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ledgerTimestamp = ledgerTimestamp;
+exports.validateCompanionRecording = validateCompanionRecording;
+exports.recordLedgerArguments = recordLedgerArguments;
+exports.reconstructLedgerFrames = reconstructLedgerFrames;
+exports.recordLedger = recordLedger;
+/** Reconstruct local instrument-panel observations from immutable ledger history. */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const ledger_panel_1 = require("./ledger-panel");
+const live_panel_1 = require("./live-panel");
+const USAGE = 'Usage: agentguard-burn record --session <id> [--from <iso>] [--to <iso>] --out <run.jsonl>';
+const MAX_FRAMES = 10000;
+/** Require an explicit timezone and reject dates Date.parse would normalize. */
+function ledgerTimestamp(value) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,3}))?(Z|[+-]\d{2}:\d{2})$/.exec(value);
+    if (!match)
+        throw new Error('Record timestamps must be ISO dates with a timezone and at most millisecond precision.');
+    const year = Number(match[1]), month = Number(match[2]), day = Number(match[3]);
+    const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+    const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+    const offset = match[8];
+    const at = Date.parse(value);
+    if (month < 1 || month > 12 || day < 1 || day > days[month - 1] || Number(match[4]) > 23
+        || Number(match[5]) > 59 || Number(match[6]) > 59 || !Number.isFinite(at) || at < 0
+        || offset !== 'Z' && (Number(offset.slice(1, 3)) > 23 || Number(offset.slice(4)) > 59)) {
+        throw new Error('Record timestamps must contain a valid date, time and timezone.');
+    }
+    return at;
+}
+/** Compare aliases before writing, including a new file below a symlinked directory. */
+function samePath(left, right) {
+    try {
+        const a = (0, node_fs_1.statSync)(left), b = (0, node_fs_1.statSync)(right);
+        if (a.dev === b.dev && a.ino === b.ino)
+            return true;
+    }
+    catch { /* A fresh output has no inode yet. */ }
+    const physical = (file) => {
+        let path = (0, node_path_1.resolve)(file);
+        const suffix = [];
+        for (;;) {
+            try {
+                return (0, node_path_1.resolve)((0, node_fs_1.realpathSync)(path), ...suffix);
+            }
+            catch {
+                const parent = (0, node_path_1.dirname)(path);
+                if (parent === path)
+                    return (0, node_path_1.resolve)(file);
+                suffix.unshift((0, node_path_1.basename)(path));
+                path = parent;
+            }
+        }
+    };
+    return physical(left) === physical(right);
+}
+function validateCompanionRecording(home, output, recording) {
+    if (samePath(output, recording))
+        throw new Error('Use different paths for --out and --record.');
+    if (['decisions.ndjson', 'receipts.ndjson'].some(name => samePath(recording, (0, node_path_1.join)(home, name)))) {
+        throw new Error('Recording must not append to a source ledger.');
+    }
+}
+function recordLedgerArguments(args) {
+    const fields = {};
+    for (let i = 0; i < args.length; i++) {
+        const flag = args[i];
+        if (!['--session', '--from', '--to', '--out'].includes(flag))
+            throw new Error(USAGE);
+        const key = flag.slice(2), value = args[++i];
+        if (!value || value.startsWith('--') || fields[key] !== undefined)
+            throw new Error(USAGE);
+        fields[key] = value;
+    }
+    if (!fields.session || !fields.out)
+        throw new Error(USAGE);
+    return fields;
+}
+function reconstructLedgerFrames(rows, options) {
+    if (!options.session || /[\x00-\x20\x7f]/.test(options.session))
+        throw new Error('Record requires a session id or an unambiguous prefix.');
+    const selected = (0, ledger_panel_1.resolveLedgerSession)(rows, options.session);
+    if (!selected)
+        throw new Error(`No ledger decisions match session ${options.session}.`);
+    const history = rows.filter(row => row.sessionDigest === selected.sessionDigest);
+    if (!history.length)
+        throw new Error(`No ledger decisions match session ${options.session}.`);
+    const first = history[0], last = history.at(-1);
+    const from = options.from === undefined ? first.at : ledgerTimestamp(options.from);
+    const to = options.to === undefined ? last.at : ledgerTimestamp(options.to);
+    if (from > to)
+        throw new Error('Record --from must be at or before --to.');
+    if ((to - from) / 1000 + 1 > MAX_FRAMES)
+        throw new Error('Recording exceeds the 10,000 frame render limit; select a shorter time range.');
+    const within = history.filter(row => row.at >= from && row.at <= to);
+    if (!within.length)
+        throw new Error('No ledger decisions fall inside the requested time range.');
+    const session = selected.sessionId?.slice(0, 8) ?? selected.sessionDigest.slice(0, 8);
+    const project = (index, at) => {
+        const snapshot = (0, ledger_panel_1.projectLedgerPanel)(history.slice(0, index + 1), selected.sessionDigest, at);
+        return { ...snapshot, session, sessionDigest: selected.sessionDigest, startedAt: first.at, observedAt: at, elapsedMs: Math.max(0, at - first.at), controls: false };
+    };
+    // Seed the hold with prior history without treating an old STOP as a new event.
+    const hold = new live_panel_1.StopHold();
+    let priorIndex = -1;
+    while (priorIndex + 1 < history.length && history[priorIndex + 1].at < from - 2000)
+        priorIndex++;
+    if (priorIndex >= 0)
+        hold.update(project(priorIndex, from - 2000), from - 2000);
+    while (priorIndex + 1 < history.length && history[priorIndex + 1].at < from) {
+        priorIndex++;
+        hold.update(project(priorIndex, history[priorIndex].at), history[priorIndex].at);
+    }
+    const events = [];
+    const decisionTimes = new Set();
+    history.forEach((row, index) => {
+        if (row.at >= from && row.at <= to) {
+            events.push({ at: row.at, index });
+            decisionTimes.add(row.at);
+        }
+    });
+    for (let at = from; at <= to; at += 1000)
+        if (!decisionTimes.has(at))
+            events.push({ at });
+    if ((to - from) % 1000 !== 0 && !decisionTimes.has(to))
+        events.push({ at: to });
+    events.sort((a, b) => a.at - b.at || (a.index ?? -1) - (b.index ?? -1));
+    if (events.length > MAX_FRAMES)
+        throw new Error('Recording exceeds the 10,000 frame render limit; select a shorter time range.');
+    const frames = events.map(event => {
+        if (event.index !== undefined)
+            priorIndex = event.index;
+        else
+            while (priorIndex + 1 < history.length && history[priorIndex + 1].at <= event.at)
+                priorIndex++;
+        const snapshot = hold.update(project(priorIndex, event.at), event.at);
+        return { version: 1, at: new Date(event.at).toISOString(), data: { kind: 'live', snapshot }, viewport: { width: 104, height: 35 } };
+    });
+    const lastStop = history.filter(row => row.at <= to && row.verdict === 'STOP').at(-1);
+    return { frames, session, from, to, decisionCount: within.length, clippedStopHold: Boolean(lastStop && lastStop.at + 2000 > to) };
+}
+function recordLedger(home, options) {
+    if (!options.out || /[\x00-\x1f\x7f]/.test(options.out))
+        throw new Error('Recording output must be a local path without control characters.');
+    const output = (0, node_path_1.resolve)(options.out);
+    if (['decisions.ndjson', 'receipts.ndjson'].some(name => output === (0, node_path_1.resolve)((0, node_path_1.join)(home, name)))) {
+        throw new Error('Recording output must not replace a source ledger.');
+    }
+    const result = reconstructLedgerFrames((0, ledger_panel_1.readPanelLedger)(home), options);
+    const bytes = result.frames.map(frame => JSON.stringify(frame)).join('\n') + '\n';
+    if (Buffer.byteLength(bytes) > 128 * 1024 * 1024)
+        throw new Error('Recording exceeds the 128 MB render limit; select a shorter time range.');
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(output), { recursive: true, mode: 0o700 });
+    try {
+        (0, node_fs_1.writeFileSync)(output, bytes, { flag: 'wx', mode: 0o600 });
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            throw new Error(`Refusing to overwrite existing output: ${output}`);
+        throw error;
+    }
+    return { output, session: result.session, from: new Date(result.from).toISOString(), to: new Date(result.to).toISOString(),
+        frameCount: result.frames.length, decisionCount: result.decisionCount, clippedStopHold: result.clippedStopHold };
+}

package/dist/src/recording.js

@@ -42,12 +42,37 @@ function readRecording(file) {
         catch {
             throw new Error(`Invalid recording JSON at line ${index + 1}.`);
         }
-        if (row?.version !== 1 || typeof row.at !== 'string' || !Number.isFinite(Date.parse(row.at)) || !row.data || !['audit', 'report', 'replay', 'command'].includes(row.data.kind))
+        if (row?.version !== 1 || typeof row.at !== 'string' || !Number.isFinite(Date.parse(row.at)) || !row.data || !['audit', 'report', 'replay', 'command', 'live'].includes(row.data.kind))
             throw new Error(`Invalid frame at line ${index + 1}.`);
         if (row.viewport && (!Number.isInteger(row.viewport.width) || row.viewport.width < 1 || row.viewport.width > 104 || !Number.isInteger(row.viewport.height) || row.viewport.height < 1 || row.viewport.height > 35))
             throw new Error(`Invalid viewport at line ${index + 1}.`);
         if (result.length && Date.parse(row.at) < Date.parse(result.at(-1).at))
             throw new Error(`Recording timestamps go backwards at line ${index + 1}.`);
+        if (row.data.kind === 'live') {
+            const snapshot = row.data.snapshot;
+            const count = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0;
+            const timestamp = (value) => count(value) && Number(value) <= 8.64e15;
+            const decision = (value) => {
+                if (!value || typeof value !== 'object')
+                    return false;
+                const d = value;
+                return typeof d.id === 'string' && timestamp(d.at) && typeof d.tool === 'string' && typeof d.reason === 'string'
+                    && ['OK', 'WARN', 'STOP'].includes(String(d.verdict)) && (typeof d.blocked === 'boolean' || d.blocked === null);
+            };
+            const sessionSwitch = snapshot?.sessionSwitch;
+            if (!snapshot || typeof snapshot.session !== 'string'
+                || !(snapshot.sessionDigest === undefined || typeof snapshot.sessionDigest === 'string' && /^[a-f0-9]{64}$/.test(snapshot.sessionDigest))
+                || !(sessionSwitch === undefined || sessionSwitch && typeof sessionSwitch.from === 'string' && typeof sessionSwitch.to === 'string' && timestamp(sessionSwitch.at)) || typeof snapshot.note !== 'string'
+                || !timestamp(snapshot.observedAt) || !timestamp(snapshot.startedAt)
+                || !(snapshot.windowActiveMinutes === null || count(snapshot.windowActiveMinutes) && snapshot.windowActiveMinutes > 0)
+                || !(snapshot.spawnCeiling === null || count(snapshot.spawnCeiling) && snapshot.spawnCeiling > 0)
+                || !(snapshot.elapsedMs === undefined || snapshot.elapsedMs === null || count(snapshot.elapsedMs))
+                || ![snapshot.spawns, snapshot.tokens].every(value => value === null || count(value))
+                || !(snapshot.replayShare === null || count(snapshot.replayShare) && snapshot.replayShare <= 1)
+                || !Array.isArray(snapshot.decisions) || snapshot.decisions.length > 8 || !snapshot.decisions.every(decision)
+                || snapshot.stop !== undefined && !decision(snapshot.stop))
+                throw new Error(`Invalid live frame at line ${index + 1}.`);
+        }
         if (row.data.kind === 'audit' && (!Array.isArray(row.data.report?.rows) || !row.data.report?.totals))
             throw new Error(`Invalid audit frame at line ${index + 1}.`);
         if (row.data.kind === 'command' && (!row.data.values || typeof row.data.values !== 'object'))

package/dist/src/render-recording.d.ts

@@ -1,3 +1,4 @@
+import { type CanvasSnapshot } from './canvas';
 export interface RenderRecordingResult {
     framesDir: string;
     provenancePath: string;
@@ -6,6 +7,7 @@ export interface RenderRecordingResult {
     ffmpegCommand: string;
     frameCount: number;
 }
+export declare function renderCanvasPng(snapshot: CanvasSnapshot, width?: number, height?: number): Promise<Buffer>;
 export declare function renderRecording(source: string, options: {
     mp4: string;
     gif?: string;

package/dist/src/render-recording.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderCanvasPng = renderCanvasPng;
 exports.renderRecording = renderRecording;
 /** Offline PNG and video rendering from validated, recorded Canvas data. */
 const node_fs_1 = require("node:fs");
@@ -67,14 +68,19 @@ function timestampMicros(at) {
     const fraction = /\.(\d+)(?:Z|[+-]\d{2}:?\d{2})$/i.exec(at)?.[1] ?? '';
     return BigInt(milliseconds) * 1000n + BigInt(fraction.slice(3, 6).padEnd(3, '0'));
 }
-async function png(snapshot) {
-    const canvas = (0, canvas_1.createCanvas)(1920, 1080);
-    const paddingX = Math.floor((canvas.width - snapshot.width * CELL_WIDTH) / 2);
-    const paddingY = Math.floor((canvas.height - snapshot.height * CELL_HEIGHT) / 2);
+async function renderCanvasPng(snapshot, width = 1920, height = 1080) {
+    await font();
+    if (!Number.isInteger(width) || !Number.isInteger(height) || width < 64 || height < 64 || width > 4096 || height > 4096)
+        throw new Error('Canvas raster dimensions must be integers between 64 and 4096.');
+    const canvas = (0, canvas_1.createCanvas)(width, height);
+    const cellWidth = Math.min(CELL_WIDTH, Math.max(1, Math.floor((width - 32) / snapshot.width)));
+    const cellHeight = Math.min(CELL_HEIGHT, Math.max(1, Math.floor((height - 32) / snapshot.height)), Math.round(cellWidth * CELL_HEIGHT / CELL_WIDTH));
+    const paddingX = Math.floor((canvas.width - snapshot.width * cellWidth) / 2);
+    const paddingY = Math.floor((canvas.height - snapshot.height * cellHeight) / 2);
     const ctx = canvas.getContext('2d');
     ctx.fillStyle = '#0B1117';
     ctx.fillRect(0, 0, canvas.width, canvas.height);
-    ctx.font = `26px "${FONT_ALIAS}"`;
+    ctx.font = `${26 * cellWidth / CELL_WIDTH}px "${FONT_ALIAS}"`;
     ctx.textBaseline = 'alphabetic';
     for (let row = 0; row < snapshot.height; row++)
         for (let col = 0; col < snapshot.width; col++) {
@@ -82,17 +88,17 @@ async function png(snapshot) {
             if (cell.char === ' ')
                 continue;
             ctx.fillStyle = canvas_2.CANVAS_PALETTE[cell.color === 'none' ? 'white' : cell.color].hex;
-            const x = paddingX + col * CELL_WIDTH, y = paddingY + row * CELL_HEIGHT;
+            const x = paddingX + col * cellWidth, y = paddingY + row * cellHeight;
             if (cell.char === '█')
-                ctx.fillRect(x, y, CELL_WIDTH, CELL_HEIGHT);
+                ctx.fillRect(x, y, cellWidth, cellHeight);
             else if (cell.char === '▀')
-                ctx.fillRect(x, y, CELL_WIDTH, CELL_HEIGHT / 2);
+                ctx.fillRect(x, y, cellWidth, cellHeight / 2);
             else if (cell.char === '▄')
-                ctx.fillRect(x, y + CELL_HEIGHT / 2, CELL_WIDTH, CELL_HEIGHT / 2);
+                ctx.fillRect(x, y + cellHeight / 2, cellWidth, cellHeight / 2);
             else if (cell.char === '─')
-                ctx.fillRect(x, y + CELL_HEIGHT / 2, CELL_WIDTH, 1);
+                ctx.fillRect(x, y + cellHeight / 2, cellWidth, 1);
             else
-                ctx.fillText(cell.char, x + 1, y + 23, CELL_WIDTH - 2);
+                ctx.fillText(cell.char, x + 1, y + 23 * cellHeight / CELL_HEIGHT, Math.max(1, cellWidth - 2));
         }
     return canvas.encode('png');
 }
@@ -140,7 +146,7 @@ async function renderRecording(source, options) {
         const frame = frames[index];
         const name = `frame-${String(index).padStart(6, '0')}.png`;
         const image = (0, frames_1.renderFrame)(frame.data, { recorded: true, at: frame.at, width: frame.viewport?.width ?? 104, height: frame.viewport?.height ?? 35, colour: true });
-        await (0, promises_1.writeFile)((0, node_path_1.join)(framesDir, name), await png(image.toJSON()), { flag: 'wx', mode: 0o600 });
+        await (0, promises_1.writeFile)((0, node_path_1.join)(framesDir, name), await renderCanvasPng(image.toJSON()), { flag: 'wx', mode: 0o600 });
     }
     for (const [position, index] of videoIndices.entries()) {
         const next = videoIndices[position + 1];
@@ -155,7 +161,7 @@ async function renderRecording(source, options) {
     // B-frame reordering can collapse the MP4 track duration to rapid DTS steps even
     // when the final presentation timestamp correctly includes the one-second hold.
     const mp4Args = [...common, '-fps_mode', 'vfr', '-c:v', 'libx264', '-bf', '0', '-enc_time_base', '1:1000000', '-video_track_timescale', '1000000', '-pix_fmt', 'yuv420p', '-movflags', '+faststart', mp4Path];
-    const gifArgs = [...common, '-fps_mode', 'vfr', '-vf', 'split[a][b];[a]palettegen[p];[b][p]paletteuse', '-loop', '0', ...(gifPath ? [gifPath] : [])];
+    const gifArgs = [...common, '-fps_mode', 'vfr', '-frames:v', String(videoIndices.length), '-final_delay', '100', '-vf', 'split[a][b];[a]palettegen[p];[b][p]paletteuse', '-loop', '0', ...(gifPath ? [gifPath] : [])];
     const command = [ffmpeg || 'ffmpeg', ...mp4Args].map(shellWord).join(' ')
         + (gifPath ? `\n${[ffmpeg || 'ffmpeg', ...gifArgs].map(shellWord).join(' ')}` : '');
     const provenance = {
@@ -169,6 +175,7 @@ async function renderRecording(source, options) {
         video_frame_indices: videoIndices,
         video_timestamp_precision: 'microseconds; equal timestamps retain the last frame in video and every PNG',
         final_hold_seconds: 1,
+        gif_timestamp_precision: 'centiseconds; terminal concat sentinel excluded; final displayed frame holds one second',
         ffmpeg_command: command,
         format: 'Recorded viewport (legacy 104x35), centered 18x28 pixel cells, 1920x1080 PNG',
         video_status: ffmpeg ? 'rendering' : 'ffmpeg_unavailable_png_frames_written',

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

@@ -1,10 +1,22 @@
+import type { HostCapabilities } from '../events';
 import type { BurnReport, SessionState, Thresholds } from '../types';
 import type { ReserveResult, Transaction } from './reservations';
+/** The exact decision-time measurements retained for local live and replay views. */
+export interface DecisionWindow {
+    activeMinutes: number;
+    windowActiveMinutes: number;
+    spawns: number | null;
+    tokens: number | null;
+    spawnCeiling: number;
+    replayShare: number | null;
+}
+export declare function decisionWindow(state: SessionState, thresholds: Thresholds, proposedSpawn?: boolean, coverage?: Pick<HostCapabilities, 'spawns' | 'usage'>): DecisionWindow;
 /** 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;
-}): {
+}, coverage?: Pick<HostCapabilities, 'spawns' | 'usage'>): {
     report: BurnReport;
     reservation: ReserveResult;
+    window: DecisionWindow;
 };

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

@@ -1,11 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.decisionWindow = decisionWindow;
 exports.evaluateSpawnReservation = evaluateSpawnReservation;
 const evaluate_1 = require("../detectors/evaluate");
 const defaults_1 = require("../defaults");
 const session_1 = require("./session");
+function decisionWindow(state, thresholds, proposedSpawn = false, coverage) {
+    const windowActiveMinutes = thresholds.spawnRate.windowActiveMinutes;
+    const spawnKnown = !coverage || coverage.spawns !== 'missing';
+    const usageKnown = !coverage || coverage.usage !== 'missing';
+    return {
+        activeMinutes: state.activeMinutes,
+        windowActiveMinutes,
+        spawns: spawnKnown ? (0, session_1.windowSum)(state.spawnsByActiveMinute, state.activeMinutes, windowActiveMinutes) + (proposedSpawn ? 1 : 0) : null,
+        tokens: usageKnown ? (0, session_1.windowSum)(state.tokensByActiveMinute, state.activeMinutes, windowActiveMinutes) : null,
+        spawnCeiling: thresholds.spawnRate.stop,
+        replayShare: usageKnown && state.totalTokens > 0 ? Math.min(1, state.totalCacheRead / state.totalTokens) : null,
+    };
+}
 /** Evaluate and reserve together. Pending forks must not bypass either window. */
-function evaluateSpawnReservation(tx, state, thresholds, proposedDepth, toolUseId, now, account) {
+function evaluateSpawnReservation(tx, state, thresholds, proposedDepth, toolUseId, now, account, coverage) {
     const pending = tx.pendingSpawns(state.sessionId, toolUseId, now);
     const minute = Math.floor(state.activeMinutes);
     const spawns = new Map(state.spawnsByActiveMinute);
@@ -13,13 +27,14 @@ function evaluateSpawnReservation(tx, state, thresholds, proposedDepth, toolUseI
         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);
+    const window = decisionWindow(candidateState, thresholds, true, coverage);
     // 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 } };
+        return { report, reservation: { allowed: true, effectiveSpawns, pending }, window };
     }
     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 } };
+    return { report, reservation: { ...reservation, effectiveSpawns }, window };
 }