@agentguard-run/burn 0.2.7 → 0.3.1

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

@@ -7,10 +7,56 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const defaults_1 = require("./defaults");
 const noticed = new Set();
+const teamNoticed = new Set();
+const idleFields = ['idle_session_warn_hours', 'idle_browser_warn_minutes', 'orphan_workspace_warn_days'];
+function validIdle(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+function withTeamThresholds(home, policy) {
+    if (!policy.teamPolicyFile)
+        return policy;
+    try {
+        if (typeof policy.teamPolicyFile !== 'string')
+            throw new Error('invalid_team_policy_path');
+        const file = (0, node_path_1.resolve)(home, policy.teamPolicyFile);
+        if (file === (0, node_path_1.resolve)(home, 'burn-policy.json'))
+            throw new Error('recursive_team_policy_path');
+        const team = JSON.parse((0, node_fs_1.readFileSync)(file, 'utf8'));
+        if (!team || !team.thresholds || typeof team.thresholds !== 'object' || Array.isArray(team.thresholds))
+            throw new Error('invalid_team_thresholds');
+        const thresholds = { ...policy.thresholds };
+        for (const key of ['fanout', 'sustained', 'burnDebt', 'spawnRate', 'duplicate', 'account', 'localCompute']) {
+            const value = team.thresholds[key];
+            if (value !== undefined) {
+                if (!value || typeof value !== 'object' || Array.isArray(value))
+                    throw new Error('invalid_team_thresholds');
+                Object.assign(thresholds, { [key]: { ...thresholds[key], ...value } });
+            }
+        }
+        for (const key of idleFields)
+            if (team.thresholds[key] !== undefined) {
+                const value = team.thresholds[key];
+                if (typeof value !== 'number' || !Number.isFinite(value) || value < 0)
+                    throw new Error('invalid_team_thresholds');
+                thresholds[key] = value;
+            }
+        return { ...policy, thresholds };
+    }
+    catch {
+        if (!teamNoticed.has(home)) {
+            teamNoticed.add(home);
+            process.stderr.write('AgentGuard shared thresholds unavailable; local thresholds and defaults apply.\n');
+        }
+        return policy;
+    }
+}
 /** Normalize before evaluating or hashing so receipts bind the actual policy. */
 function normalizePolicy(policy) {
     const thresholds = policy.thresholds;
     const normalized = {
+        idle_session_warn_hours: validIdle(thresholds.idle_session_warn_hours, defaults_1.DEFAULT_THRESHOLDS.idle_session_warn_hours),
+        idle_browser_warn_minutes: validIdle(thresholds.idle_browser_warn_minutes, defaults_1.DEFAULT_THRESHOLDS.idle_browser_warn_minutes),
+        orphan_workspace_warn_days: validIdle(thresholds.orphan_workspace_warn_days, defaults_1.DEFAULT_THRESHOLDS.orphan_workspace_warn_days),
         fanout: { ...defaults_1.DEFAULT_THRESHOLDS.fanout, ...thresholds.fanout },
         sustained: { ...defaults_1.DEFAULT_THRESHOLDS.sustained, ...thresholds.sustained },
         burnDebt: { ...defaults_1.DEFAULT_THRESHOLDS.burnDebt, ...thresholds.burnDebt },
@@ -36,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) {
@@ -45,9 +91,9 @@ 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(parsed);
+            return normalizePolicy(withTeamThresholds(home, parsed));
         }
     }
     catch {

package/dist/src/presentation.d.ts

@@ -0,0 +1,5 @@
+import { type BurnFrame } from './frames';
+export declare function present(data: BurnFrame, plain: string, options?: {
+    colour?: boolean;
+    protocol?: boolean;
+}): void;

package/dist/src/presentation.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.present = present;
+/** Human terminal screens share the canvas; protocol and no-color bytes stay plain. */
+const canvas_1 = require("./canvas");
+const frames_1 = require("./frames");
+const recording_1 = require("./recording");
+function present(data, plain, options = {}) {
+    const colour = options.colour ?? (Boolean(process.stdout.isTTY) && process.env.NO_COLOR === undefined);
+    const screen = colour && !options.protocol;
+    const grid = new canvas_1.Canvas(screen ? {} : { width: 104, height: 35 });
+    const viewport = { width: Math.min(104, grid.width), height: Math.min(35, grid.height) };
+    const pages = screen || (0, recording_1.isRecording)() ? (0, frames_1.framePageCount)(data, viewport) : 1;
+    for (let page = 0; page < pages; page++) {
+        const frame = data.kind !== 'report' ? { ...data, page } : data;
+        const at = new Date().toISOString();
+        (0, recording_1.recordFrame)(frame, at, viewport);
+        if (screen)
+            process.stdout.write((0, frames_1.renderFrame)(frame, { at, ...viewport }).render() + '\n');
+    }
+    if (!screen)
+        process.stdout.write(plain);
+}

package/dist/src/recording.d.ts

@@ -0,0 +1,22 @@
+import type { BurnFrame } from './frames';
+export interface RecordedFrame {
+    version: 1;
+    at: string;
+    data: BurnFrame;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+}
+export declare function configureRecording(file?: string): void;
+export declare function isRecording(): boolean;
+export declare function recordedFrameCount(): number;
+export declare function recordFrame(data: BurnFrame, at?: string, viewport?: {
+    width: number;
+    height: number;
+}): void;
+export declare function readRecording(file: string): RecordedFrame[];
+export declare function recordingArguments(argv: string[]): {
+    args: string[];
+    file?: string;
+};

package/dist/src/recording.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configureRecording = configureRecording;
+exports.isRecording = isRecording;
+exports.recordedFrameCount = recordedFrameCount;
+exports.recordFrame = recordFrame;
+exports.readRecording = readRecording;
+exports.recordingArguments = recordingArguments;
+/** Explicit, local-only frame recording. Never capture rendered output. */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+let destination;
+let frames = 0;
+function configureRecording(file) { destination = file; frames = 0; }
+function isRecording() { return destination !== undefined; }
+function recordedFrameCount() { return frames; }
+function recordFrame(data, at = new Date().toISOString(), viewport) {
+    if (!destination)
+        return;
+    try {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(destination), { recursive: true, mode: 0o700 });
+        (0, node_fs_1.appendFileSync)(destination, JSON.stringify({ version: 1, at, data, ...(viewport ? { viewport } : {}) }) + '\n', { mode: 0o600 });
+        frames++;
+    }
+    catch (error) {
+        // Recording cannot affect a hook's decision or an interactive cleanup.
+        process.stderr.write(`Burn recording unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
+        destination = undefined;
+    }
+}
+function readRecording(file) {
+    if ((0, node_fs_1.statSync)(file).size > 128 * 1024 * 1024)
+        throw new Error('Recording exceeds the 128 MB render limit.');
+    const result = [];
+    for (const [index, line] of (0, node_fs_1.readFileSync)(file, 'utf8').split('\n').entries()) {
+        if (!line.trim())
+            continue;
+        let row;
+        try {
+            row = JSON.parse(line);
+        }
+        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', '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'))
+            throw new Error(`Invalid command frame at line ${index + 1}.`);
+        if (row.data.kind === 'report' && (!row.data.report?.totals || !Array.isArray(row.data.report.findings)))
+            throw new Error(`Invalid report frame at line ${index + 1}.`);
+        if (row.data.kind === 'replay' && !Array.isArray(row.data.summary?.sessions))
+            throw new Error(`Invalid replay frame at line ${index + 1}.`);
+        result.push(row);
+        if (result.length > 10000)
+            throw new Error('Recording exceeds the 10,000 frame render limit.');
+    }
+    if (!result.length)
+        throw new Error('Recording has no frames.');
+    return result;
+}
+function recordingArguments(argv) {
+    const args = [];
+    let file;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] !== '--record') {
+            args.push(argv[i]);
+            continue;
+        }
+        if (file || !argv[i + 1] || argv[i + 1].startsWith('--'))
+            throw new Error('Use --record <file.jsonl> once.');
+        file = argv[++i];
+    }
+    return { args, file };
+}

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

@@ -0,0 +1,15 @@
+import { type CanvasSnapshot } from './canvas';
+export interface RenderRecordingResult {
+    framesDir: string;
+    provenancePath: string;
+    mp4: string | null;
+    gif: string | null;
+    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;
+    ffmpeg?: string | null;
+}): Promise<RenderRecordingResult>;