@agentguard-run/burn 0.2.7 → 0.3.0

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 },
@@ -47,7 +93,7 @@ function loadPolicy(home) {
                 missing.push('spawnRate.enforce=true');
             if (missing.length)
                 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,80 @@
+"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'].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 === '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,13 @@
+export interface RenderRecordingResult {
+    framesDir: string;
+    provenancePath: string;
+    mp4: string | null;
+    gif: string | null;
+    ffmpegCommand: string;
+    frameCount: number;
+}
+export declare function renderRecording(source: string, options: {
+    mp4: string;
+    gif?: string;
+    ffmpeg?: string | null;
+}): Promise<RenderRecordingResult>;

package/dist/src/render-recording.js

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderRecording = renderRecording;
+/** Offline PNG and video rendering from validated, recorded Canvas data. */
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_crypto_1 = require("node:crypto");
+const node_child_process_1 = require("node:child_process");
+const node_util_1 = require("node:util");
+const node_path_1 = require("node:path");
+const canvas_1 = require("@napi-rs/canvas");
+const canvas_2 = require("./canvas");
+const frames_1 = require("./frames");
+const recording_1 = require("./recording");
+const run = (0, node_util_1.promisify)(node_child_process_1.execFile);
+const CELL_WIDTH = 18, CELL_HEIGHT = 28;
+const FONT_ALIAS = 'BurnRecordingMono';
+const FONT_PATHS = [
+    '/System/Library/Fonts/Menlo.ttc',
+    '/Library/Fonts/Menlo.ttc',
+    '/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf',
+    '/usr/share/fonts/dejavu-sans-mono-fonts/DejaVuSansMono.ttf',
+    '/usr/share/fonts/TTF/DejaVuSansMono.ttf',
+];
+async function font() {
+    for (const path of FONT_PATHS) {
+        try {
+            await (0, promises_1.access)(path, node_fs_1.constants.R_OK);
+            if (canvas_1.GlobalFonts.registerFromPath(path, FONT_ALIAS) && canvas_1.GlobalFonts.has(FONT_ALIAS))
+                return path;
+        }
+        catch { /* Try the next installed local font. */ }
+    }
+    throw new Error('Recording render needs an installed Menlo or DejaVu Sans Mono font; no font was downloaded.');
+}
+async function executable(requested) {
+    const paths = (0, node_path_1.isAbsolute)(requested) || requested.includes('/') || requested.includes('\\')
+        ? [(0, node_path_1.resolve)(requested)] : (process.env.PATH || '').split(node_path_1.delimiter).filter(Boolean).map(path => (0, node_path_1.resolve)(path, requested));
+    for (const path of paths) {
+        try {
+            await (0, promises_1.access)(path, node_fs_1.constants.X_OK);
+            if ((await (0, promises_1.lstat)(path)).isFile() || (await (0, promises_1.lstat)(path)).isSymbolicLink())
+                return path;
+        }
+        catch { /* Not on this PATH entry. */ }
+    }
+    return null;
+}
+async function requireUnused(path) {
+    try {
+        await (0, promises_1.lstat)(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    throw new Error(`Refusing to overwrite existing output: ${path}`);
+}
+/** For display only; execution always passes an argument array without a shell. */
+function shellWord(value) { return `'${value.replace(/'/g, "'\\''")}'`; }
+/** FFmpeg represents concat timestamps in microseconds; Date.parse truncates below milliseconds. */
+function timestampMicros(at) {
+    const milliseconds = Date.parse(at);
+    if (!Number.isFinite(milliseconds))
+        throw new Error('Recording timestamps must be valid and ordered.');
+    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);
+    const ctx = canvas.getContext('2d');
+    ctx.fillStyle = '#0B1117';
+    ctx.fillRect(0, 0, canvas.width, canvas.height);
+    ctx.font = `26px "${FONT_ALIAS}"`;
+    ctx.textBaseline = 'alphabetic';
+    for (let row = 0; row < snapshot.height; row++)
+        for (let col = 0; col < snapshot.width; col++) {
+            const cell = snapshot.cells[row][col];
+            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;
+            if (cell.char === '█')
+                ctx.fillRect(x, y, CELL_WIDTH, CELL_HEIGHT);
+            else if (cell.char === '▀')
+                ctx.fillRect(x, y, CELL_WIDTH, CELL_HEIGHT / 2);
+            else if (cell.char === '▄')
+                ctx.fillRect(x, y + CELL_HEIGHT / 2, CELL_WIDTH, CELL_HEIGHT / 2);
+            else if (cell.char === '─')
+                ctx.fillRect(x, y + CELL_HEIGHT / 2, CELL_WIDTH, 1);
+            else
+                ctx.fillText(cell.char, x + 1, y + 23, CELL_WIDTH - 2);
+        }
+    return canvas.encode('png');
+}
+async function renderRecording(source, options) {
+    const sourcePath = (0, node_path_1.resolve)(source), mp4Path = (0, node_path_1.resolve)(options.mp4);
+    const gifPath = options.gif ? (0, node_path_1.resolve)(options.gif) : null;
+    const provenancePath = `${mp4Path}.provenance.json`;
+    for (const path of [sourcePath, mp4Path, provenancePath, ...(gifPath ? [gifPath] : [])]) {
+        if (/[\x00-\x1f\x7f]/.test(path))
+            throw new Error('Recording paths must not contain control characters.');
+    }
+    if (new Set([sourcePath, mp4Path, provenancePath, ...(gifPath ? [gifPath] : [])]).size !== (gifPath ? 4 : 3)) {
+        throw new Error('Recording source and each output must use different paths.');
+    }
+    for (const path of [mp4Path, provenancePath, ...(gifPath ? [gifPath] : [])])
+        await requireUnused(path);
+    const sourceStat = await (0, promises_1.stat)(sourcePath);
+    if (!sourceStat.isFile() || sourceStat.size > 128 * 1024 * 1024)
+        throw new Error('Recording must be a regular local file no larger than 128 MB.');
+    const sourceBytes = await (0, promises_1.readFile)(sourcePath);
+    const frames = await (0, recording_1.readRecording)(sourcePath);
+    if (!frames.length)
+        throw new Error('Recording contains no frames.');
+    const times = frames.map(frame => timestampMicros(frame.at));
+    const videoIndices = [];
+    for (let index = 0; index < frames.length; index++) {
+        if (index && times[index] < times[index - 1])
+            throw new Error('Recording timestamps must be valid and ordered.');
+        // No elapsed time exists between equal timestamps. Keep the latest state in video,
+        // while retaining every observation as its own PNG and provenance entry.
+        if (index === frames.length - 1 || times[index] !== times[index + 1])
+            videoIndices.push(index);
+    }
+    if (!sourceBytes.equals(await (0, promises_1.readFile)(sourcePath)))
+        throw new Error('Recording changed while it was being read; render the saved file again.');
+    const sourceHash = (0, node_crypto_1.createHash)('sha256').update(sourceBytes).digest('hex');
+    const fontPath = await font();
+    await (0, promises_1.mkdir)((0, node_path_1.dirname)(mp4Path), { recursive: true });
+    if (gifPath)
+        await (0, promises_1.mkdir)((0, node_path_1.dirname)(gifPath), { recursive: true });
+    const framesDir = await (0, promises_1.mkdtemp)((0, node_path_1.join)((0, node_path_1.dirname)(mp4Path), `${(0, node_path_1.basename)(mp4Path)}.frames-`));
+    const concatPath = (0, node_path_1.join)(framesDir, 'frames.ffconcat');
+    const lines = ['ffconcat version 1.0'];
+    for (let index = 0; index < frames.length; index++) {
+        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 });
+    }
+    for (const [position, index] of videoIndices.entries()) {
+        const next = videoIndices[position + 1];
+        const seconds = next === undefined ? 1 : Number(times[next] - times[index]) / 1_000_000;
+        lines.push(`file 'frame-${String(index).padStart(6, '0')}.png'`, 'option framerate 1000000', `duration ${seconds.toFixed(6)}`);
+    }
+    // The concat demuxer needs a terminal file to honor the final frame hold.
+    lines.push(`file 'frame-${String(frames.length - 1).padStart(6, '0')}.png'`, 'option framerate 1000000');
+    await (0, promises_1.writeFile)(concatPath, `${lines.join('\n')}\n`, { flag: 'wx', mode: 0o600 });
+    const ffmpeg = options.ffmpeg === null ? null : await executable(options.ffmpeg || 'ffmpeg');
+    const common = ['-hide_banner', '-loglevel', 'error', '-nostdin', '-n', '-protocol_whitelist', 'file,pipe', '-f', 'concat', '-safe', '0', '-i', concatPath];
+    // 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 command = [ffmpeg || 'ffmpeg', ...mp4Args].map(shellWord).join(' ')
+        + (gifPath ? `\n${[ffmpeg || 'ffmpeg', ...gifArgs].map(shellWord).join(' ')}` : '');
+    const provenance = {
+        source_sha256: sourceHash,
+        renderer_version: require('../../package.json').version,
+        rendered_at: new Date().toISOString(),
+        font: { family: FONT_ALIAS, path: fontPath },
+        frame_count: frames.length,
+        frame_times: frames.map(frame => frame.at),
+        frame_viewports: frames.map(frame => frame.viewport ?? { width: 104, height: 35 }),
+        video_frame_indices: videoIndices,
+        video_timestamp_precision: 'microseconds; equal timestamps retain the last frame in video and every PNG',
+        final_hold_seconds: 1,
+        ffmpeg_command: command,
+        format: 'Recorded viewport (legacy 104x35), centered 18x28 pixel cells, 1920x1080 PNG',
+        video_status: ffmpeg ? 'rendering' : 'ffmpeg_unavailable_png_frames_written',
+    };
+    await (0, promises_1.writeFile)(provenancePath, `${JSON.stringify(provenance, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+    if (ffmpeg) {
+        try {
+            await run(ffmpeg, mp4Args, { timeout: 300_000, maxBuffer: 1024 * 1024 });
+            if (gifPath)
+                await run(ffmpeg, gifArgs, { timeout: 300_000, maxBuffer: 1024 * 1024 });
+            provenance.video_status = 'complete';
+        }
+        catch (error) {
+            provenance.video_status = 'failed_png_frames_written';
+            throw new Error(`Video encoding failed; PNG frames remain at ${framesDir}: ${error.message}`);
+        }
+        finally {
+            await (0, promises_1.writeFile)(provenancePath, `${JSON.stringify(provenance, null, 2)}\n`, { mode: 0o600 });
+        }
+    }
+    return { framesDir, provenancePath, mp4: ffmpeg ? mp4Path : null, gif: ffmpeg && gifPath ? gifPath : null, ffmpegCommand: command, frameCount: frames.length };
+}

package/dist/src/replay/render.js

@@ -10,6 +10,7 @@ exports.comparison = comparison;
 exports.renderReplay = renderReplay;
 exports.renderStop = renderStop;
 exports.renderSessionRow = renderSessionRow;
+const frames_1 = require("../frames");
 const evaluate_1 = require("../detectors/evaluate");
 const C = {
     reset: '\x1b[0m',
@@ -117,6 +118,8 @@ function scenarioUsd(tokens, cacheShare) {
 }
 function renderReplay(summary, opts = {}) {
     const on = opts.colour ?? Boolean(process.stdout.isTTY);
+    if (on)
+        return (0, frames_1.renderFrame)({ kind: 'replay', summary }, { colour: true }).render();
     const top = opts.top ?? 6;
     const out = [];
     const cacheShare = summary.totalTokens
@@ -175,6 +178,8 @@ function renderReplay(summary, opts = {}) {
 // ---------------------------------------------------------------------------
 function renderStop(report, opts = {}) {
     const on = opts.colour ?? false;
+    if (on)
+        return (0, frames_1.renderFrame)({ kind: 'report', report, subject: opts.subject, outcome: 'blocked' }, { colour: true }).render();
     const lead = report.findings.find((f) => f.verdict === 'STOP')?.summary ?? 'Fan-out ceiling reached.';
     const w = 64;
     const bar = '─'.repeat(w);

package/dist/src/types.d.ts

@@ -80,6 +80,10 @@ export interface BurnReport {
     };
 }
 export interface Thresholds {
+    /** Additive local idle-resource warnings; no automatic process termination. */
+    idle_session_warn_hours?: number;
+    idle_browser_warn_minutes?: number;
+    orphan_workspace_warn_days?: number;
     fanout: {
         warn: number;
         stop: number;
@@ -131,6 +135,8 @@ export interface Thresholds {
 }
 export type Mode = 'shadow' | 'enforce';
 export interface Policy {
+    /** Shared threshold file; relative paths resolve from the Burn home. */
+    teamPolicyFile?: string;
     mode: Mode;
     thresholds: Thresholds;
     /** Additive local usage advisories. Older policy files use these defaults. */

package/docs/burn-idle-audit.md

@@ -0,0 +1,71 @@
+# Local idle audit with Burn
+
+Status: docs page draft for Burn 0.3.0. No service, account or upload is involved.
+
+Agent sessions and automation can keep holding machine resources after the developer stops using them. Burn reports this cost exposure locally and offers a deliberately limited interactive close command.
+
+## See what is still alive
+
+```sh
+agentguard-burn ps
+agentguard-burn ps --json
+agentguard-burn ps --record ./idle-run.jsonl
+```
+
+The table ranks processes by resident memory, followed by candidate workspaces ranked by disk size. It covers Claude Code and Codex processes with their Node children, plugin daemons associated with temporary or abandoned paths, and automation Chrome, Chromium or Chrome for Testing processes. Normal browser profiles are excluded. Automation markers include remote-debugging arguments, enable-automation, temporary user-data directories and Playwright or Puppeteer profiles. Browser subprocess memory is grouped under its automation browser; available native window counts are shown separately.
+
+Each agent row includes PID, host, working directory, uptime, idle time, idle method and resident memory. Idle uses the controlling terminal's access timestamp when readable. Otherwise Burn uses recent transcript file-write metadata, with the scope and limitations stated in the output. A fallback is evidence for a warning, not proof that the developer stopped typing.
+
+Candidate workspaces are searched under the temporary and Claude scratchpad roots. A git worktree, .git entry or package.json identifies a candidate. Size, modification time, dirty state and open handles are metadata. Orphan status requires evidence that the workspace has no registered worktree ownership or live process use. Permission failures, scan limits, missing tools and unknown idle evidence are reported rather than converted into zero activity. The scan does not execute package scripts or inspect source content. The full command bounds collection at thirty seconds, with explicit process, directory-entry, discovery-depth and workspace-count limits. Discovered workspaces still appear with unknown evidence when collection runs out of budget. Incomplete totals are lower bounds. A directory timestamp shown after an incomplete scan is not used to trigger an idle warning.
+
+Interactive output uses the Burn fixed-grid canvas. At smaller terminal sizes side detail is dropped and rows paginate rather than wrap. The plain table remains available with --no-color; --json retains all collected rows and skipped capabilities. See [recording and rendering](burn-render.md) for local PNG and video exports.
+
+Totals show held memory for idle agent sessions and disk occupied by orphan workspaces. RSS can count shared pages more than once and is not a bill. Current swap use is reported separately. Swap is only released by the operating system on reboot. Burn does not touch it.
+
+## Close only what you select
+
+```sh
+agentguard-burn reap
+```
+
+Reap prints the numbered audit and asks for explicit row numbers. Both input and output must be interactive terminals. Blank input cancels. There is no --yes option, no piped confirmation and no automatic cleanup. Only the typed process selections can receive SIGTERM. Burn waits and reports; a surviving process remains alive. SIGKILL is never sent.
+
+All of these refusals apply:
+
+1. A session with terminal input within the last 24 hours is refused. Missing or unreadable terminal-idle evidence is also refused; transcript inactivity does not override it.
+2. A process with modified or untracked files in its working directory's repository is refused. Unknown working-directory safety is refused, including unreadable or missing directories. A verified non-repository directory has no git changes to protect.
+3. Workspaces are always information only. A workspace with open handles is explicitly marked, and no workspace can be deleted or closed by this command.
+4. Reap itself and every ancestor are protected. A group containing one of those processes is refused.
+5. The confirmed process identity, ancestry, classification and working-directory safety are checked again before signaling. Reused PIDs, changed ownership and newly discovered group members are not silently included.
+
+Permission failures are reported. Warning thresholds do not relax the fixed 24-hour session protection. Reap never deletes anything on disk.
+
+## Warning policy
+
+Add these keys to thresholds in the existing Burn policy file:
+
+```json
+{
+  "thresholds": {
+    "idle_session_warn_hours": 24,
+    "idle_browser_warn_minutes": 60,
+    "orphan_workspace_warn_days": 2
+  }
+}
+```
+
+The policy is normally ~/.agentguard/burn-policy.json. AGENTGUARD_HOME changes that root. Missing or invalid idle settings use these defaults. The optional local teamPolicyFile points to another JSON file containing thresholds, resolved relative to the Burn home unless absolute. Known team threshold fields override local fields; shared policy loading does not change enforcement mode. A missing or invalid team file produces a notice and uses the local settings. Policy files are not rewritten by an audit.
+
+Claude Code and Codex SessionStart hooks use a five-minute private metadata cache. A cache miss gets a bounded 150 ms scan attempt. A timeout skips the warning rather than slowing session start or blocking a tool. The hook prints at most one WARN line:
+
+```text
+N idle agent sessions holding X GB, run agentguard-burn ps
+```
+
+If only browsers or workspaces exceed a threshold, N can be zero and ps shows those rows. The ordinary ps command refreshes the cache. Existing installations need the updated hook snippet from agentguard-burn init claude or agentguard-burn init codex, reviewed and merged into the host configuration. The init command only writes configuration when explicitly asked to do so.
+
+## Platform and privacy boundary
+
+macOS collection uses ps, lsof, terminal device timestamps and sysctl. Browser window counts use available local window metadata and may be unavailable. Linux reads /proc and uses local git and filesystem metadata, with explicit notices when a capability is unavailable. Windows prints "not supported on this platform yet" and exits 0.
+
+No sockets, remote browser debugging connections, telemetry, cloud API or cleanup service are used. Process arguments are inspected locally for classification but are not printed or stored in the audit cache. Transcript contents, tool input, tool output and source files are not uploaded. Directory names, local PIDs and resource totals are visible in the local report and JSON export, so review that metadata before sharing it yourself.

package/docs/burn-render.md

@@ -0,0 +1,37 @@
+# Burn terminal recordings
+
+Status: docs page draft for Burn 0.3.0.
+
+Burn's interactive screens share a fixed-grid instrument panel. The default is 104 columns by 35 rows. Smaller terminals hide side detail and paginate without wrapping. Mint means good, slate is neutral, amber means risk and red is reserved for STOP. Truecolor terminals receive the palette's RGB values; other color terminals use 256-color codes. --no-color keeps existing plain command output and hook cards. Machine-readable JSON, hook replies and statusline output remain plain protocols.
+
+## Record observations
+
+```sh
+agentguard-burn ps --record ./idle-run.jsonl
+agentguard-burn status --record ./status-run.jsonl
+```
+
+--record works before or after the command. It appends one JSON object per frame. There is no implicit recording or upload. A line has this versioned envelope:
+
+```json
+{"version":1,"at":"2026-09-20T10:00:00.000Z","data":{"kind":"command","command":"status","values":{"mode":"shadow"}}}
+```
+
+Frame kinds are audit, report, replay and command. Audit frames contain resource metadata without raw process arguments or unrelated processes. Reports contain detector measurements; replay frames contain the replay summary; command frames contain named observations. Frame data is not rendered text, ANSI or a terminal capture. A page index and viewport identify each visible page when a screen needs multiple grids. No-color and JSON commands record every data page at the standard 104 by 35 size while keeping their stdout unchanged. STOP frames distinguish blocked, shadow and overridden outcomes; older frames without an outcome say that it was not recorded. Hooks record detector reports when they display one and otherwise a command outcome without copying hook input. Recording failure never changes a hook's decision.
+
+Recordings may include local paths, process identifiers, policy thresholds and resource totals. Keep them private unless you choose to share that metadata. Tool input, tool output, prompts and transcript contents are not recorded. Burn adds no network request.
+
+## Render locally
+
+```sh
+agentguard-burn render ./idle-run.jsonl --mp4 ./idle-run.mp4
+agentguard-burn render ./idle-run.jsonl --mp4 ./idle-with-gif.mp4 --gif ./idle-run.gif
+```
+
+The renderer verifies ordered timestamps and draws each frame with the same Canvas at 1920 by 1080. It uses an installed Menlo font on macOS or DejaVu Sans Mono on Linux. Windows prints "not supported on this platform yet" and exits zero before loading the renderer. Missing fonts on supported platforms produce an explicit error; none are downloaded. The title reads RECORDED RUN · 1x and the footer reads recorded run. Frame intervals follow the original wall-clock timestamps, with a one-second hold after the last frame. Equal timestamps have zero duration; video keeps the last state at that instant while retaining every PNG and recording its index in provenance. Timestamp precision in encoded video is limited by the encoder time base; GIF timing is limited by that format.
+
+The PNG renderer is bundled as a native Node dependency and loads only for render. ffmpeg is a separately installed local encoder. If ffmpeg is unavailable, Burn writes numbered PNG frames, an ffconcat timing file and a shell-quoted encoding command. Existing media or provenance outputs are refused. PNGs stay beside the requested output in a unique directory so a failed encoder never loses the rendered evidence.
+
+Provenance is written to the MP4 path plus .provenance.json. It includes source_sha256, renderer_version, rendered_at, the local font, frame timestamps, final hold duration and encoding status. The digest identifies the original JSONL bytes, not a claim that the observations are signed or independently attested. The source file is never changed. The render command reads only local paths and restricts ffmpeg input protocols to local files and pipes.
+
+Rendering rejects recordings above 128 MB or 10,000 frames. Unknown schema versions, malformed lines and backward timestamps are errors. This is a local replay renderer, not a screen recorder or billing meter. ps totals describe held memory and cost exposure.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentguard-run/burn",
-  "version": "0.2.7",
+  "version": "0.3.0",
   "description": "Local session usage and runaway-agent circuit breaker. Explain tokens, cache rewrites and API list cost, track pace, warn on heavy turns, and gate agent fan-out with signed receipts. Nothing leaves the machine.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "commonjs",
@@ -50,7 +50,9 @@
     "conformance": "tsc -p tsconfig.json && node dist/src/cli.js conformance",
     "replay": "node dist/src/cli.js replay"
   },
-  "dependencies": {},
+  "dependencies": {
+    "@napi-rs/canvas": "^1.0.9"
+  },
   "devDependencies": {
     "@types/node": "^22",
     "typescript": "^5.0.0"