@agentguard-run/burn 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.3.1 (2026-09-20)
+
+- Add the live session screen: block-digit counters for spawns, tokens in window and replay share, a spawn-rate bar against the policy ceiling, the last decisions with verdict chips, and a two-second STOP hold, all through the canvas. The same screen renders recorded runs.
+- Ship the September 19 recorded run as docs/assets/burn-live-sep19 with an mp4, gif, evidence and provenance files.
+
 ## 0.3.0 (2026-09-20)
 
 - Add local ps and JSON audits for Claude Code and Codex processes, leftover plugin daemons, automation browsers, workspace disk and current swap. Report held memory and cost exposure with explicit unknown evidence.

package/README.md

@@ -384,3 +384,12 @@ A provenance JSON beside the requested MP4 records the source recording's SHA256
 
 No prompts, responses, file contents, or tool inputs are persisted or rendered.
 No telemetry. No provider-quota guesses. Account forecasts use only observed host percentages, never an invented allowance or cache weighting.
+
+### Local live panel
+
+`agentguard-burn live` displays spawn and token counts within the active window,
+session cache-read share, the policy rate bar and the last eight local decisions.
+Use `--session ID`, `--once`, `--record run.jsonl`, or `--replay run.jsonl`.
+STOP reasons hold for two seconds while observations continue. The display is
+local and does not affect admission. Missing observations remain unknown.
+See [the live panel and recorded September 19 evidence](docs/LIVE_PANEL_2026_09.md).

package/dist/src/cli.js

@@ -126,6 +126,10 @@ async function main(argv) {
     };
     const has = (name) => rawRest.includes(name);
     switch (command) {
+        case 'live': {
+            const { runLivePanel } = await Promise.resolve().then(() => __importStar(require('./live-panel')));
+            return runLivePanel(HOME, rawRest);
+        }
         case 'ps':
         case 'reap':
             return (0, cli_1.runIdleCommand)(command, rawRest, HOME);
@@ -370,9 +374,10 @@ async function main(argv) {
             return 0;
         }
         default:
-            show({ kind: 'command', command: 'help', values: { commands: ['ps', 'reap', 'render', 'blocks', 'why', 'rewrites', 'pace', 'statusline', 'pricing', 'replay', 'calibrate', 'status', 'init', 'enforce', 'shadow', 'resume', 'proxy', 'conformance'] } }, 'agentguard-burn <ps|reap|render|blocks|why|rewrites|pace|statusline|pricing|replay|calibrate|status|init|enforce|shadow|resume|proxy|conformance>\n' +
+            show({ kind: 'command', command: 'help', values: { commands: ['ps', 'reap', 'live', 'render', 'blocks', 'why', 'rewrites', 'pace', 'statusline', 'pricing', 'replay', 'calibrate', 'status', 'init', 'enforce', 'shadow', 'resume', 'proxy', 'conformance'] } }, 'agentguard-burn <ps|reap|live|render|blocks|why|rewrites|pace|statusline|pricing|replay|calibrate|status|init|enforce|shadow|resume|proxy|conformance>\n' +
                 '  ps [--json]          local agent processes, held memory and workspace disk\n' +
                 '  render <run.jsonl> --mp4 <out.mp4> [--gif <out.gif>]   local recorded-run export\n' +
+                '  live [--session ID] [--once] [--replay run.jsonl]  local instrument panel\n' +
                 '  --record <file.jsonl> append structured frames for any command; --no-color keeps plain output\n' +
                 '  reap                 numbered interactive SIGTERM, never delete or force-kill\n' +
                 '  blocks [session|all]   stored WARN/STOP receipts and that session\'s child usage\n' +

package/dist/src/frames.d.ts

@@ -1,5 +1,6 @@
 /** Recorded frames carry observations, not ANSI, screen text or process arguments. */
 import { Canvas } from './canvas';
+import { type LivePanelSnapshot } from './live-panel';
 import type { AuditReport, AuditRow } from './idle/types';
 import type { BurnReport } from './types';
 import type { ReplaySummary } from './replay/simulate';
@@ -7,6 +8,9 @@ export type AuditFrameReport = Omit<AuditReport, 'processes' | 'rows'> & {
     rows: Array<Omit<AuditRow, 'processes'>>;
 };
 export type BurnFrame = {
+    kind: 'live';
+    snapshot: LivePanelSnapshot;
+} | {
     kind: 'audit';
     command: 'ps' | 'reap';
     report: AuditFrameReport;

package/dist/src/frames.js

@@ -5,6 +5,7 @@ exports.framePageCount = framePageCount;
 exports.renderFrame = renderFrame;
 /** Recorded frames carry observations, not ANSI, screen text or process arguments. */
 const canvas_1 = require("./canvas");
+const live_panel_1 = require("./live-panel");
 function auditFrame(command, report) {
     const { processes: ignored, rows, ...metadata } = report;
     return { kind: 'audit', command, report: { ...metadata, rows: rows.map(({ processes: omitted, ...row }) => row) } };
@@ -32,6 +33,15 @@ function valueRows(values, prefix = '', depth = 0) {
     });
 }
 function renderFrame(data, options = {}) {
+    if (data.kind === 'live')
+        return (0, live_panel_1.renderLivePanel)(data.snapshot, options);
+    if (data.kind === 'report' && data.report.verdict === 'STOP') {
+        const at = options.at ?? new Date().toISOString();
+        const snapshot = (0, live_panel_1.panelFromReport)(data.report, Date.parse(at), data.outcome, data.subject), panel = (0, live_panel_1.renderLivePanel)(snapshot, options);
+        panel.put(2, 0, `AGENTGUARD STOP · session ${snapshot.session} · ${at.slice(11, 19)} UTC`.padEnd(panel.width), 'red');
+        panel.put(panel.height - 4, 0, 'override once:  agentguard-burn resume --once --reason "..."', 'slate');
+        return panel;
+    }
     const canvas = new canvas_1.Canvas(options), w = canvas.width, h = canvas.height;
     const replay = options.recorded || data.kind === 'replay';
     const at = options.at ?? new Date().toISOString();

package/dist/src/live-panel.d.ts

@@ -0,0 +1,42 @@
+import { Canvas, type CanvasColor } from './canvas';
+import type { FrameOptions } from './frames';
+import type { BurnReport, Verdict } from './types';
+export interface PanelDecision {
+    id: string;
+    at: number;
+    tool: string;
+    verdict: Verdict;
+    reason: string;
+    blocked: boolean | null;
+}
+export interface LivePanelSnapshot {
+    session: string;
+    startedAt: number;
+    observedAt: number;
+    spawns: number | null;
+    tokens: number | null;
+    replayShare: number | null;
+    windowActiveMinutes: number | null;
+    spawnCeiling: number | null;
+    decisions: PanelDecision[];
+    elapsedMs?: number | null;
+    controls?: boolean;
+    stopHold?: boolean;
+    note: string;
+    stop?: PanelDecision;
+}
+export declare function panelDecisions(home: string, sessionId: string, at?: number): PanelDecision[];
+export declare function collectLivePanel(home: string, session?: string, now?: number): LivePanelSnapshot;
+export declare function spawnBarColor(spawns: number | null, ceiling: number | null): CanvasColor;
+export declare function renderLivePanel(snapshot: LivePanelSnapshot, options?: FrameOptions): Canvas;
+/** STOP report adaptation uses only already-computed metadata, never local I/O. */
+export declare function panelFromReport(report: BurnReport, at: number, outcome?: 'blocked' | 'shadow' | 'overridden' | 'allowed', subject?: 'spawn' | 'call'): LivePanelSnapshot;
+/** Display-only hold. Intake continues and the latest observation follows the card. */
+export declare class StopHold {
+    private held?;
+    private until;
+    private seen;
+    private latest?;
+    update(snapshot: LivePanelSnapshot, now: number): LivePanelSnapshot;
+}
+export declare function runLivePanel(home: string, args: string[]): Promise<number>;

package/dist/src/live-panel.js

@@ -0,0 +1,283 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StopHold = 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 node_path_1 = require("node:path");
+const canvas_1 = require("./canvas");
+const policy_1 = require("./policy");
+const recording_1 = require("./recording");
+const session_1 = require("./state/session");
+const digest = (text) => (0, node_crypto_1.createHash)('sha256').update(text).digest('hex');
+const number = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : null;
+const row = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+const safe = (v, fallback) => typeof v === 'string' && /^[A-Za-z0-9_.:-]{1,80}$/.test(v) ? v : fallback;
+const verdict = (v) => v === 'OK' || v === 'WARN' || v === 'STOP' ? v : null;
+function buckets(value) {
+    if (!Array.isArray(value) || !value.every(v => Array.isArray(v) && v.length === 2 && number(v[0]) !== null && number(v[1]) !== null))
+        return null;
+    return new Map(value);
+}
+/** Read a bounded tail and discard an incomplete first/last JSON row. */
+function ledger(file) {
+    try {
+        const size = (0, node_fs_1.statSync)(file).size, offset = Math.max(0, size - 4 * 1024 * 1024), fd = (0, node_fs_1.openSync)(file, 'r');
+        const bytes = Buffer.alloc(size - offset);
+        try {
+            (0, node_fs_1.readSync)(fd, bytes, 0, bytes.length, offset);
+        }
+        finally {
+            (0, node_fs_1.closeSync)(fd);
+        }
+        const text = bytes.toString('utf8'), lines = text.slice(offset ? text.indexOf('\n') + 1 : 0, text.lastIndexOf('\n') + 1).split('\n');
+        return lines.flatMap(line => { try {
+            return [row(JSON.parse(line))];
+        }
+        catch {
+            return [];
+        } });
+    }
+    catch {
+        return [];
+    }
+}
+function panelDecisions(home, sessionId, at = Date.now()) {
+    const sessionDigest = digest(sessionId);
+    const receiptRows = ledger((0, node_path_1.join)(home, 'receipts.ndjson')).flatMap(raw => {
+        const p = row(raw.payload);
+        if (p.sessionDigest !== sessionDigest || number(p.at) === null || Number(p.at) > at || !verdict(p.verdict))
+            return [];
+        return [{ id: safe(p.decisionId, digest(JSON.stringify(p))), at: Number(p.at), tool: safe(p.action, 'unknown'), verdict: verdict(p.verdict),
+                reason: Array.isArray(p.reasons) ? [...new Set(p.reasons.map(v => safe(v, 'unknown')))].join(' + ') : 'reason unavailable', blocked: p.blocked === true }];
+    });
+    const decisions = ledger((0, node_path_1.join)(home, 'decisions.ndjson')).flatMap(p => {
+        if (p.sessionId !== sessionId || number(p.at) === null || Number(p.at) > at || !verdict(p.verdict))
+            return [];
+        const findings = Array.isArray(p.findings) ? p.findings.map(row) : [];
+        return [{ id: safe(p.toolUseId, digest(JSON.stringify(p))), at: Number(p.at), tool: safe(p.action ?? p.tool, 'spawn'), verdict: verdict(p.verdict),
+                reason: findings.map(f => `${safe(f.detector, 'unknown')}:${verdict(f.verdict) ?? 'OK'}`).join(' + ') || (p.failClosed === true ? 'local fail-closed condition' : p.verdict === 'OK' ? 'within policy' : 'reason unavailable'), blocked: p.enforced === true }];
+    });
+    const merged = [...decisions], joined = new Set();
+    for (const d of receiptRows) {
+        const index = merged.findIndex((candidate, i) => !joined.has(i) && candidate.at === d.at && candidate.tool === d.tool && candidate.verdict === d.verdict && candidate.blocked === d.blocked);
+        if (index >= 0) {
+            merged[index] = d;
+            joined.add(index);
+        }
+        else {
+            joined.add(merged.length);
+            merged.push(d);
+        }
+    }
+    return merged.sort((a, b) => a.at - b.at).slice(-8);
+}
+function collectLivePanel(home, session, now = Date.now()) {
+    const policy = (0, policy_1.loadPolicy)(home, { notice: false });
+    const configured = policy.thresholds.spawnRate;
+    const windowActiveMinutes = number(configured?.windowActiveMinutes) || 15, spawnCeiling = number(configured?.stop) || 16;
+    const base = { session: 'unavailable', startedAt: now, observedAt: now, spawns: null, tokens: null, replayShare: null,
+        windowActiveMinutes, spawnCeiling, decisions: [], note: 'No readable session state. Waiting for local observations.' };
+    let names;
+    try {
+        names = (0, node_fs_1.readdirSync)((0, node_path_1.join)(home, 'sessions')).filter(name => name.endsWith('.json'));
+    }
+    catch {
+        return base;
+    }
+    const candidates = names.flatMap(name => {
+        try {
+            const path = (0, node_path_1.join)(home, 'sessions', name);
+            if ((0, node_fs_1.statSync)(path).size > 16 * 1024 * 1024)
+                return [];
+            const raw = row(JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'))), state = row(raw.state);
+            if (typeof state.sessionId !== 'string' || number(state.lastEventAt) === null || number(state.startedAt) === null)
+                return [];
+            if (session && state.sessionId !== session && !state.sessionId.startsWith(session) && !digest(state.sessionId).startsWith(session))
+                return [];
+            return [{ raw, state }];
+        }
+        catch {
+            return [];
+        }
+    }).sort((a, b) => Number(b.state.lastEventAt) - Number(a.state.lastEventAt));
+    if (!candidates.length)
+        return base;
+    const { raw, state } = candidates[0], active = number(state.activeMinutes), spawned = buckets(state.spawnsByActiveMinute), tokens = buckets(state.tokensByActiveMinute);
+    const total = number(state.totalTokens), cached = number(state.totalCacheRead), decisions = panelDecisions(home, String(state.sessionId), now);
+    const coverage = row(raw.capabilities), gateway = Array.isArray(raw.hosts);
+    const spawnKnown = !gateway || ['authoritative', 'estimated'].includes(String(coverage.spawns));
+    const usageKnown = !gateway || ['authoritative', 'estimated'].includes(String(coverage.usage));
+    return { ...base, session: digest(String(state.sessionId)).slice(0, 8), startedAt: Number(state.startedAt),
+        spawns: spawnKnown && spawned && active !== null ? (0, session_1.windowSum)(spawned, active, windowActiveMinutes) : null,
+        tokens: usageKnown && tokens && active !== null ? (0, session_1.windowSum)(tokens, active, windowActiveMinutes) : null,
+        replayShare: usageKnown && total !== null && cached !== null && total > 0 ? Math.min(1, cached / total) : null, decisions,
+        note: row(raw.cursor).usageVersion === undefined && raw.cursor ? 'Legacy stored usage counts; no recount applied.' : gateway ? `Local observations. Coverage: spawns ${safe(coverage.spawns, 'unknown')}, usage ${safe(coverage.usage, 'unknown')}.` : 'Local observations only. Replay share is session cache-read / tokens.' };
+}
+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: 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) {
+        this.latest = snapshot;
+        const stop = snapshot.decisions.filter(d => d.verdict === 'STOP' && !this.seen.has(d.id)).at(-1);
+        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();
+            do {
+                if (!paused) {
+                    const now = Date.now(), snapshot = hold.update(collectLivePanel(home, selected, 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/recording.js

@@ -42,12 +42,34 @@ 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);
+            };
+            if (!snapshot || typeof snapshot.session !== 'string' || 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',