@agentguard-run/burn 0.2.7 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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.
+- Add interactive reap with typed row selection, SIGTERM only, a bounded wait and a result for each selection. Never delete workspaces, force-kill processes or close reap itself or its ancestors. Refuse recent terminal activity, dirty or unverified working directories and changed process identities.
+- Add configurable idle-session, browser and orphan-workspace WARN thresholds, including team threshold files. SessionStart uses a five-minute metadata cache and a bounded advisory check that skips on timeout and never blocks.
+- Keep existing plain STOP and WARN hook cards and no-color command bytes unchanged. Add a fixed-grid colored Canvas for terminal screens, with clipped cells, three-row block digits, bars and smaller-terminal layouts.
+- Add opt-in timestamped structured frame recording for commands and offline recorded-run MP4/GIF rendering, local system fonts, numbered PNG fallback and SHA256 provenance. No audit or rendering data leaves the machine.
+- Validation: 248 tests pass with no skips, including the 240-process stress test: 40 admitted, 200 denied, 240 signed receipts and zero lock failures.
+
 ## 0.2.7 (2026-09-19)
 
 - Fix the STOP badge padding so every card row is 66 visible characters wide. Preserve the card wording.

package/README.md

@@ -16,6 +16,56 @@ The two init commands print hook configuration for review. Merge the relevant sn
 
 For Claude Code, configure its `statusLine` command as `agentguard-burn statusline`. It receives the host JSON on stdin. Codex 0.154.0 has no external status command slot. Use `agentguard-burn statusline SESSION_ID` in a companion terminal and the native Codex limit indicators. See [host fields and setup](docs/USAGE_AND_PRICING.md#what-the-hosts-expose).
 
+## Local idle audit
+
+Burn 0.3.0 reports held memory and disk cost exposure on this machine:
+
+```sh
+agentguard-burn ps
+agentguard-burn ps --json
+agentguard-burn reap
+```
+
+`ps` lists Claude Code and Codex sessions with their Node children, leftover plugin daemons, automation-owned Chrome browsers, and candidate workspaces. Process rows are ranked by resident memory, then workspace rows by disk size. Normal Chrome profiles are excluded. Browser rows show their process count, total resident memory and available window count. Unknown values are explicit. RSS can count shared memory more than once; it is not a bill.
+
+Session idle time uses the controlling terminal's access time when readable, otherwise transcript file-write metadata. The table labels the method. A transcript fallback can warn but cannot prove that a terminal has been inactive for 24 hours. Workspace rows show size, last modification, dirty status and open-handle evidence. No transcript content or process arguments are printed or uploaded. Swap is reported only: swap is only released by the operating system on reboot. Burn does not touch it.
+
+`reap` prints the same numbered audit, then requires an interactive terminal and numbers typed at the prompt. There is no `--yes` flag and piped confirmation is refused. It sends only SIGTERM to the selected eligible processes, waits, and reports whether they exited. It never sends SIGKILL and never deletes files or directories.
+
+Reap refuses:
+
+- Any session with terminal input in the last 24 hours, or unavailable terminal-idle evidence. Changing a warning threshold does not change this safety limit.
+- Any process whose working directory has modified or untracked files, or whose directory safety cannot be verified.
+- Every workspace, including any workspace with open file handles. Workspace rows are information only.
+- The process running reap and all its ancestors, including a selected group containing one of them.
+- A process whose identity, ownership or safety evidence changed while confirmation was pending. New or replaced PIDs are never added to the confirmed selection.
+
+It rechecks the selected processes before signaling. Permission errors and processes that ignore SIGTERM are reported. They are not force-closed.
+
+Add these fields under `thresholds` in the existing `~/.agentguard/burn-policy.json` (or `AGENTGUARD_HOME/burn-policy.json`):
+
+```json
+{
+  "thresholds": {
+    "idle_session_warn_hours": 24,
+    "idle_browser_warn_minutes": 60,
+    "orphan_workspace_warn_days": 2
+  }
+}
+```
+
+Merge the fields into your existing policy. Missing or invalid values use the shipped defaults. A local `teamPolicyFile` can point to a JSON file containing `thresholds`; relative paths resolve from the Burn home. Team threshold values take precedence over local threshold values, including these three audit settings. Neither policy loading nor the audit rewrites your policy.
+
+The Claude Code and Codex hook snippets now include SessionStart. Review the new `agentguard-burn init claude` or `agentguard-burn init codex` output to update existing installations. At session start, a fresh five-minute local audit cache is checked. A cache miss gets a bounded scan with a 150 ms budget; timeout or unavailable evidence skips the advisory. A warning is one line, never a table and never a deny:
+
+```text
+N idle agent sessions holding X GB, run agentguard-burn ps
+```
+
+The line is WARN-only in both shadow and enforce modes. If only browser or workspace rows cross their thresholds, the session count can be zero; run `ps` for those details. The full `ps` command refreshes the cache. All collection and caching stays local.
+
+macOS uses local process, file-handle and swap metadata. Linux uses `/proc` and available local tools, and says what could not be read. Windows prints `not supported on this platform yet` and exits successfully. See the [docs page draft](docs/burn-idle-audit.md) for the audit boundary and limitations.
+
 ## Why this session
 
 ```sh
@@ -311,7 +361,35 @@ Both token limits default to `null`. Closed gateway sessions are excluded;
 hook and gateway session files are both read. WARN never blocks. STOP records
 a would-block decision in shadow and blocks new work only in enforce mode.
 
+## Terminal canvas and local recordings
+
+Interactive screens use a fixed 104 by 35 cell canvas, with mint for good, slate for neutral, amber for WARN and red for STOP. Smaller terminals drop side detail and paginate rows without wrapping. Use --no-color for the existing plain-text commands and hook cards. Hook JSON and the one-line statusline remain host protocols, with no canvas control sequences inserted.
+
+Any command accepts an explicit local recording path:
+
+```sh
+agentguard-burn ps --record ./idle-run.jsonl
+agentguard-burn status --no-color --record ./status-run.jsonl
+agentguard-burn replay --record ./history-run.jsonl
+agentguard-burn render ./idle-run.jsonl --mp4 ./idle-run.mp4 --gif ./idle-run.gif
+```
+
+Each JSONL frame contains a wall-clock timestamp and structured observations, never rendered terminal text. Audit recordings omit raw process arguments and the full process table. They can contain local paths, PIDs, identifiers and resource measurements, so review them before sharing. Recording is opt-in and stays on disk. A recording failure prints a notice without changing a hook decision or cleanup result. Appended recordings must have nondecreasing timestamps.
+
+The render command draws recorded Canvas cells at 1920 by 1080 using installed Menlo on macOS or DejaVu Sans Mono on Linux. The title says RECORDED RUN and the footer says recorded run. It preserves frame timestamp intervals and holds the final frame for one second. ffmpeg encodes the MP4 and optional GIF; without it, numbered PNG files and a reproducible ffmpeg command remain. No fonts or assets are fetched. The native PNG dependency loads only for render, never during session-start checks.
+
+A provenance JSON beside the requested MP4 records the source recording's SHA256, renderer version, render time, font and frame times. Existing outputs are refused. The source recording stays unchanged. See [the render draft](docs/burn-render.md) for the format and limits.
+
 ## What it never does
 
 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/adapters/codex.js

@@ -34,6 +34,7 @@ const node_fs_1 = require("node:fs");
 const events_1 = require("../events");
 const render_1 = require("../replay/render");
 const live_1 = require("../insights/live");
+const hook_1 = require("../idle/hook");
 const pre_tool_use_1 = require("../hook/pre-tool-use");
 /** Fields this renderer must never emit. Codex rejects the whole object if they appear. */
 exports.CODEX_FORBIDDEN_FIELDS = ['continue', 'stopReason', 'suppressOutput', 'decision', 'reason'];
@@ -43,6 +44,10 @@ function handleCodexHook(raw, gateway, now = Date.now()) {
     const parsed = parse(raw);
     if (!parsed)
         return {};
+    if (parsed.event === 'SessionStart') {
+        const warning = (0, hook_1.sessionStartWarning)(gateway.dataDirectory, (0, pre_tool_use_1.loadPolicy)(gateway.dataDirectory), now);
+        return warning ? { systemMessage: warning } : {};
+    }
     const observation = (0, live_1.observeTool)(gateway.dataDirectory, { session_id: parsed.sessionId, transcript_path: parsed.transcriptPath, tool_name: parsed.toolName }, 'codex', (0, pre_tool_use_1.loadPolicy)(gateway.dataDirectory), now);
     const output = parsed.event === 'PreToolUse' && SPAWN_TOOLS.has(parsed.toolName) ? handleCodexSpawnHook(raw, gateway, now) : {};
     return observation.messages.length ? { ...output, systemMessage: [output.systemMessage, ...observation.messages].filter(Boolean).join('\n') } : output;
@@ -200,6 +205,7 @@ function walk(value, path) {
 function codexHooksSnippet(command) {
     return {
         hooks: {
+            SessionStart: [{ matcher: '.*', hooks: [{ type: 'command', command, timeout: 1 }] }],
             PreToolUse: [{ matcher: '.*', hooks: [{ type: 'command', command, timeout: 15 }] }],
         },
     };

package/dist/src/canvas.d.ts

@@ -0,0 +1,36 @@
+export type CanvasColor = 'mint' | 'slate' | 'amber' | 'red' | 'white' | 'none';
+export type CanvasColorMode = 'truecolor' | '256' | 'none';
+export interface CanvasCell {
+    char: string;
+    color: CanvasColor;
+}
+export interface CanvasSnapshot {
+    width: number;
+    height: number;
+    cells: CanvasCell[][];
+}
+export declare const CANVAS_PALETTE: Record<Exclude<CanvasColor, 'none'>, {
+    hex: string;
+    rgb: [number, number, number];
+    ansi256: number;
+}>;
+export declare class Canvas {
+    readonly width: number;
+    readonly height: number;
+    readonly colorMode: CanvasColorMode;
+    private readonly cells;
+    constructor(options?: {
+        width?: number;
+        height?: number;
+        colour?: boolean;
+        colorMode?: CanvasColorMode;
+    });
+    put(row: number, col: number, text: string, color?: CanvasColor): this;
+    digits(row: number, col: number, value: string | number, color?: CanvasColor): this;
+    bar(row: number, col: number, width: number, fraction: number, color?: CanvasColor): this;
+    rule(row: number, col: number, width?: number): this;
+    header(left?: string, right?: string): this;
+    footer(hints: string, clock: string): this;
+    toJSON(): CanvasSnapshot;
+    render(): string;
+}

package/dist/src/canvas.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Canvas = exports.CANVAS_PALETTE = void 0;
+/** A clipped grid of terminal cells. Rendering adds only palette-owned ANSI. */
+const node_util_1 = require("node:util");
+exports.CANVAS_PALETTE = {
+    mint: { hex: '#2ABCB4', rgb: [42, 188, 180], ansi256: 37 },
+    slate: { hex: '#64748B', rgb: [100, 116, 139], ansi256: 66 },
+    amber: { hex: '#F59E0B', rgb: [245, 158, 11], ansi256: 208 },
+    red: { hex: '#EF4444', rgb: [239, 68, 68], ansi256: 203 },
+    white: { hex: '#E2E8F0', rgb: [226, 232, 240], ansi256: 254 },
+};
+const GLYPHS = {
+    '0': ['█▀█', '█ █', '█▄█'], '1': [' ▀█', '  █', '  █'],
+    '2': ['▀▀█', '▄▀▀', '█▄▄'], '3': ['▀▀█', ' ▀█', '▄▄█'],
+    '4': ['█ █', '▀▀█', '  █'], '5': ['█▀▀', '▀▀█', '▄▄█'],
+    '6': ['█▀▀', '█▀█', '█▄█'], '7': ['▀▀█', '  █', '  █'],
+    '8': ['█▀█', '█▀█', '█▄█'], '9': ['█▀█', '▀▀█', '▄▄█'],
+    '.': [' ', ' ', '▄'], '-': ['   ', '▀▀▀', '   '],
+};
+const colors = new Set(['mint', 'slate', 'amber', 'red', 'white', 'none']);
+function dimension(value, fallback, limit) {
+    return Math.max(1, Math.min(limit, Math.floor(typeof value === 'number' && Number.isFinite(value) ? value : fallback)));
+}
+function wide(code) {
+    return code >= 0x1100 && (code <= 0x115f || code === 0x2329 || code === 0x232a
+        || (code >= 0x2e80 && code <= 0xa4cf && code !== 0x303f) || (code >= 0xac00 && code <= 0xd7a3)
+        || (code >= 0xf900 && code <= 0xfaff) || (code >= 0xfe10 && code <= 0xfe19)
+        || (code >= 0xfe30 && code <= 0xfe6f) || (code >= 0xff00 && code <= 0xff60)
+        || (code >= 0xffe0 && code <= 0xffe6) || (code >= 0x1f000 && code <= 0x1faff)
+        || (code >= 0x20000 && code <= 0x3fffd));
+}
+/** Keep one printable column per cell; preserve bullets and box-drawing rules. */
+function characters(text) {
+    return Array.from((0, node_util_1.stripVTControlCharacters)(String(text)).replace(/[\r\n\t]/g, ' ').replace(/[\p{Cc}\p{Cf}\p{M}]/gu, ''))
+        .map(char => wide(char.codePointAt(0)) ? '?' : char);
+}
+class Canvas {
+    width;
+    height;
+    colorMode;
+    cells;
+    constructor(options = {}) {
+        this.width = dimension(options.width, Math.min(104, process.stdout.columns || 104), 500);
+        this.height = dimension(options.height, Math.min(35, process.stdout.rows || 35), 200);
+        this.colorMode = options.colour === false ? 'none' : options.colorMode
+            ?? (options.colour !== true && process.env.NO_COLOR !== undefined ? 'none' : /^(truecolor|24bit)$/i.test(process.env.COLORTERM || '') ? 'truecolor' : '256');
+        this.cells = Array.from({ length: this.height }, () => Array.from({ length: this.width }, () => ({ char: ' ', color: 'none' })));
+    }
+    put(row, col, text, color = 'white') {
+        if (!Number.isFinite(row) || !Number.isFinite(col))
+            return this;
+        row = Math.floor(row);
+        col = Math.floor(col);
+        if (row < 0 || row >= this.height || col >= this.width)
+            return this;
+        const selected = colors.has(color) ? color : 'none';
+        for (const [index, char] of characters(text).entries()) {
+            const x = col + index;
+            if (x >= this.width)
+                break;
+            if (x >= 0)
+                this.cells[row][x] = { char, color: selected };
+        }
+        return this;
+    }
+    digits(row, col, value, color = 'mint') {
+        let x = col;
+        for (const char of characters(String(value))) {
+            const glyph = GLYPHS[char] ?? ['   ', '   ', '   '];
+            for (let y = 0; y < 3; y++)
+                this.put(row + y, x, glyph[y], color);
+            x += glyph[0].length + 1;
+            if (x >= this.width)
+                break;
+        }
+        return this;
+    }
+    bar(row, col, width, fraction, color = 'mint') {
+        if (!Number.isFinite(width) || width <= 0)
+            return this;
+        const length = Math.min(500, Math.floor(width));
+        const ratio = Number.isFinite(fraction) ? Math.max(0, Math.min(1, fraction)) : 0;
+        const filled = Math.round(length * ratio);
+        return this.put(row, col, '█'.repeat(filled) + '░'.repeat(length - filled), color);
+    }
+    rule(row, col, width = this.width - col) {
+        if (!Number.isFinite(width) || width <= 0)
+            return this;
+        return this.put(row, col, '─'.repeat(Math.min(500, Math.floor(width))), 'slate');
+    }
+    header(left = 'AGENTGUARD / BURN', right = 'LIVE') {
+        const rightChars = characters(right).slice(0, this.width);
+        const start = this.width - rightChars.length;
+        this.put(0, 0, characters(left).slice(0, Math.max(0, start - (rightChars.length ? 2 : 0))).join(''), 'mint');
+        this.put(0, start, rightChars.join(''), 'slate');
+        if (this.height > 1)
+            this.rule(1, 0);
+        return this;
+    }
+    footer(hints, clock) {
+        if (this.height > 1)
+            this.rule(this.height - 2, 0);
+        const clockChars = characters(clock).slice(0, this.width), start = this.width - clockChars.length;
+        this.put(this.height - 1, 0, characters(hints).slice(0, Math.max(0, start - (clockChars.length ? 2 : 0))).join(''), 'slate');
+        return this.put(this.height - 1, start, clockChars.join(''), 'white');
+    }
+    toJSON() {
+        return { width: this.width, height: this.height, cells: this.cells.map(row => row.map(cell => ({ ...cell }))) };
+    }
+    render() {
+        return this.cells.map(row => {
+            if (this.colorMode === 'none')
+                return row.map(cell => cell.char).join('');
+            let current = 'none', text = '';
+            for (const cell of row) {
+                if (cell.color !== current) {
+                    current = cell.color;
+                    if (current === 'none')
+                        text += '\x1b[0m';
+                    else {
+                        const color = exports.CANVAS_PALETTE[current];
+                        text += this.colorMode === 'truecolor' ? `\x1b[38;2;${color.rgb.join(';')}m` : `\x1b[38;5;${color.ansi256}m`;
+                    }
+                }
+                text += cell.char;
+            }
+            return text + (current !== 'none' ? '\x1b[0m' : '');
+        }).join('\n');
+    }
+}
+exports.Canvas = Canvas;

package/dist/src/cli.d.ts

@@ -2,6 +2,8 @@
 /**
  * agentguard-burn
  *
+ *   ps                local agent processes, held memory and orphan workspace disk
+ *   reap              interactively SIGTERM selected safe processes, never delete
  *   replay            what enforcement would have stopped, on your history
  *   calibrate         fit thresholds to your own usage, write shadow policy
  *   status            mode, shadow decisions, eligibility, every host's sessions

package/dist/src/cli.js

@@ -3,6 +3,8 @@
 /**
  * agentguard-burn
  *
+ *   ps                local agent processes, held memory and orphan workspace disk
+ *   reap              interactively SIGTERM selected safe processes, never delete
  *   replay            what enforcement would have stopped, on your history
  *   calibrate         fit thresholds to your own usage, write shadow policy
  *   status            mode, shadow decisions, eligibility, every host's sessions
@@ -16,7 +18,42 @@
  *   cursor-hook       (internal) Cursor hook entry point
  *   codex-hook        (internal) Codex hook entry point
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
+const presentation_1 = require("./presentation");
+const recording_1 = require("./recording");
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
@@ -37,8 +74,12 @@ const eligibility_1 = require("./eligibility");
 const sessions_1 = require("./insights/sessions");
 const transcript_1 = require("./insights/transcript");
 const live_1 = require("./insights/live");
+const attribution_1 = require("./insights/attribution");
+const pricing_1 = require("./insights/pricing");
+const transcript_2 = require("./insights/transcript");
 const render_2 = require("./insights/render");
 const blocks_1 = require("./insights/blocks");
+const cli_1 = require("./idle/cli");
 const HOME = process.env.AGENTGUARD_HOME ?? (0, node_path_1.join)((0, node_os_1.homedir)(), '.agentguard');
 const PROXY_HOSTS = ['ollama', 'vllm', 'lm-studio', 'openai-compatible'];
 function readStdinJson() {
@@ -75,23 +116,46 @@ function shadowEligibility() {
     return (0, eligibility_1.computeShadowEligibility)(readDecisions());
 }
 async function main(argv) {
-    const [command, ...rest] = argv;
+    const [command, ...rawRest] = argv;
+    const noColor = rawRest.includes('--no-color');
+    const rest = rawRest.filter(value => value !== '--no-color');
+    const show = (data, plain, protocol = false) => (0, presentation_1.present)(data, plain, { colour: Boolean(process.stdout.isTTY) && !noColor && process.env.NO_COLOR === undefined, protocol });
     const flag = (name) => {
         const i = rest.indexOf(name);
         return i >= 0 ? rest[i + 1] : undefined;
     };
-    const has = (name) => rest.includes(name);
+    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);
+        case 'render': {
+            if (process.platform === 'win32') {
+                process.stdout.write('not supported on this platform yet\n');
+                return 0;
+            }
+            const source = rest[0], mp4 = flag('--mp4'), gif = flag('--gif');
+            if (!source || source.startsWith('--') || !mp4 || mp4.startsWith('--') || (has('--gif') && (!gif || gif.startsWith('--'))))
+                throw new Error('Usage: agentguard-burn render <run.jsonl> --mp4 <out.mp4> [--gif <out.gif>]');
+            const { renderRecording } = await Promise.resolve().then(() => __importStar(require('./render-recording')));
+            const result = await renderRecording(source, { mp4, gif });
+            show({ kind: 'command', command: 'render', values: { ...result } }, `PNG frames: ${result.framesDir}\n${result.mp4 ? `MP4: ${result.mp4}\n` : `ffmpeg unavailable. Run: ${result.ffmpegCommand}\n`}${result.gif ? `GIF: ${result.gif}\n` : ''}Provenance: ${result.provenancePath}\n`);
+            return 0;
+        }
         case 'blocks': {
             const session = rest.find(value => value !== 'json' && value !== '--json');
             const report = (0, blocks_1.blocksReport)(HOME, session, { rates: (0, live_1.readPricing)(HOME, (0, pre_tool_use_1.loadPolicy)(HOME)) });
-            process.stdout.write((rest.includes('json') || has('--json') ? JSON.stringify(report, null, 2) : (0, blocks_1.renderBlocks)(report)) + '\n');
+            show({ kind: 'command', command, values: { ...report } }, (rest.includes('json') || has('--json') ? JSON.stringify(report, null, 2) : (0, blocks_1.renderBlocks)(report)) + '\n', rest.includes('json') || has('--json'));
             return 0;
         }
         case 'why': {
             const location = (0, sessions_1.selectInsightTranscript)(rest.find(value => value !== 'json'));
             const transcript = (0, transcript_1.readInsightSession)(location.path, { host: location.host, sessionId: location.sessionId });
-            process.stdout.write(rest.includes('json') ? JSON.stringify(transcript, null, 2) + '\n' : (0, render_2.renderWhy)(transcript, (0, live_1.readPricing)(HOME, (0, pre_tool_use_1.loadPolicy)(HOME))) + '\n');
+            show({ kind: 'command', command, values: { session: transcript.sessionId, observations: transcript.observations, diagnostics: transcript.diagnostics, attribution: (0, attribution_1.attributeTurns)((0, transcript_2.deduplicateTurns)(transcript.turns)).buckets, prices: (0, transcript_2.deduplicateTurns)(transcript.turns).map(turn => (0, pricing_1.priceTurn)(turn, (0, live_1.readPricing)(HOME, (0, pre_tool_use_1.loadPolicy)(HOME)))) } }, rest.includes('json') ? JSON.stringify(transcript, null, 2) + '\n' : (0, render_2.renderWhy)(transcript, (0, live_1.readPricing)(HOME, (0, pre_tool_use_1.loadPolicy)(HOME))) + '\n', rest.includes('json'));
             return 0;
         }
         case 'rewrites': {
@@ -99,11 +163,12 @@ async function main(argv) {
             const locations = session === 'all' ? (0, sessions_1.discoverInsightTranscripts)() : [(0, sessions_1.selectInsightTranscript)(session)];
             const transcripts = locations.map(location => (0, transcript_1.readInsightTranscript)(location.path, { host: location.host, sessionId: location.sessionId }));
             const rates = (0, live_1.readPricing)(HOME, (0, pre_tool_use_1.loadPolicy)(HOME));
-            process.stdout.write(rest.includes('json') ? JSON.stringify((0, render_2.rewriteReport)(transcripts, rates), null, 2) + '\n' : (0, render_2.renderRewrites)(transcripts, rates) + '\n');
+            show({ kind: 'command', command, values: (0, render_2.rewriteReport)(transcripts, rates) }, rest.includes('json') ? JSON.stringify((0, render_2.rewriteReport)(transcripts, rates), null, 2) + '\n' : (0, render_2.renderRewrites)(transcripts, rates) + '\n', rest.includes('json'));
             return 0;
         }
         case 'pricing': {
-            process.stdout.write((0, render_2.renderPricing)((0, live_1.readPricing)(HOME, (0, pre_tool_use_1.loadPolicy)(HOME))) + '\n');
+            const rates = (0, live_1.readPricing)(HOME, (0, pre_tool_use_1.loadPolicy)(HOME));
+            show({ kind: 'command', command, values: { rates: { ...pricing_1.MODEL_PRICING, ...rates } } }, (0, render_2.renderPricing)(rates) + '\n');
             return 0;
         }
         case 'statusline':
@@ -112,7 +177,7 @@ async function main(argv) {
             const payload = raw && typeof raw === 'object' ? raw : {};
             const location = (0, sessions_1.selectInsightTranscript)(payload.transcript_path || rest[0] || payload.session_id);
             const observation = (0, live_1.observeTool)(HOME, { ...payload, session_id: payload.session_id || location.sessionId, transcript_path: location.path }, location.host, (0, pre_tool_use_1.loadPolicy)(HOME));
-            process.stdout.write((observation.snapshot ? (0, live_1.renderStatusLine)(observation.snapshot) : 'AgentGuard pace unavailable: local usage metadata is not readable.') + '\n');
+            show({ kind: 'command', command, values: { snapshot: observation.snapshot ? { host: observation.snapshot.host, session: observation.snapshot.sessionId, pace: observation.snapshot.pace, forecast: observation.snapshot.forecast, lastTurnTokens: observation.snapshot.lastTurnTokens, windows: observation.snapshot.windows } : null } }, (observation.snapshot ? (0, live_1.renderStatusLine)(observation.snapshot) : 'AgentGuard pace unavailable: local usage metadata is not readable.') + '\n', command === 'statusline');
             return observation.snapshot ? 0 : 1;
         }
         case 'hook': {
@@ -124,6 +189,11 @@ async function main(argv) {
             catch {
                 // Unparseable payload: allow. We never break the host over our own bug.
             }
+            if (input?.hook_event_name === 'SessionStart') {
+                const warning = await (0, cli_1.prepareSessionStart)(input, HOME);
+                process.stdout.write(JSON.stringify(warning ? { continue: true, suppressOutput: false, systemMessage: warning } : { continue: true, suppressOutput: true }));
+                return 0;
+            }
             process.stdout.write(JSON.stringify((0, pre_tool_use_1.handlePreToolUse)(input, HOME)));
             return 0;
         }
@@ -132,12 +202,7 @@ async function main(argv) {
             const paths = rest.filter((a) => a.endsWith('.jsonl'));
             const targets = paths.length ? paths : (0, simulate_1.discoverTranscripts)();
             const summary = (0, simulate_1.replayAll)(targets, policy.thresholds, Number(flag('--min-tokens') ?? 0));
-            if (has('--json')) {
-                process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
-            }
-            else {
-                process.stdout.write(`${(0, render_1.renderReplay)(summary, { colour: !has('--no-color'), top: Number(flag('--top') ?? 8) })}\n`);
-            }
+            show({ kind: 'replay', summary }, has('--json') ? `${JSON.stringify(summary, null, 2)}\n` : `${(0, render_1.renderReplay)(summary, { colour: false, top: Number(flag('--top') ?? 8) })}\n`, has('--json'));
             return 0;
         }
         case 'calibrate': {
@@ -145,7 +210,7 @@ async function main(argv) {
             const result = (0, calibrate_1.calibrate)(summary.sessions);
             savePolicy(result.policy);
             const t = result.policy.thresholds;
-            process.stdout.write([
+            show({ kind: 'command', command, values: { ...result } }, [
                 `Calibrated from ${result.sessionsUsed} of ${result.sessionsTotal} sessions (${result.sessionsExcluded} excluded as pathological).`,
                 `  raw p90 ${(result.rawWarnP90 / 1e9).toFixed(2)}B  raw p99 ${(result.rawStopP99 / 1e9).toFixed(2)}B`,
                 `  sustained WARN ${(t.sustained.warnTokens / 1e9).toFixed(2)}B   STOP ${(t.sustained.stopTokens / 1e9).toFixed(2)}B`,
@@ -163,7 +228,7 @@ async function main(argv) {
             const gateway = new gateway_1.Gateway(HOME, { sign: false });
             const lc = policy.thresholds.localCompute;
             const override = (0, override_1.readOverride)(HOME);
-            process.stdout.write([
+            show({ kind: 'command', command, values: { mode: policy.mode, thresholds: policy.thresholds, eligibility: e, override: override ? { active: true, once: override.once, until: override.until } : null, hosts: ['claude', 'cursor', 'codex'].map(h => { const { command: omitted, ...metadata } = (0, install_1.health)(h); return metadata; }), sessions: [...(0, status_1.readHookSessions)(HOME), ...gateway.sessions()].map(row => ({ sessionId: row.sessionId, hosts: row.hosts, tokens: row.state.totalTokens, spawns: row.state.spawnCount, liveSpawns: row.liveSpawns, capabilities: row.capabilities })) } }, [
                 `mode: ${policy.mode}${policy.mode === 'enforce' ? '  (the next STOP blocks)' : '  (recording only; nothing is blocked)'}`,
                 `thresholds: fan-out lifetime WARN ${policy.thresholds.fanout.warn}; STOP above ${policy.thresholds.fanout.stop} spawns in ${policy.thresholds.fanout.windowActiveMinutes ?? 120} active minutes; depth above ${policy.thresholds.fanout.maxDepth}`,
                 `spawn-rate: WARN ${policy.thresholds.spawnRate?.warn ?? 8}; STOP ${policy.thresholds.spawnRate?.stop ?? 16} in ${policy.thresholds.spawnRate?.windowActiveMinutes ?? 15} active minutes; ${policy.thresholds.spawnRate?.enforce === false ? 'shadow only' : 'enforcing in enforce mode'}`,
@@ -206,7 +271,7 @@ async function main(argv) {
                     process.stderr.write(`init: refusing to touch ${(0, install_1.configPath)(target)}: ${error instanceof Error ? error.message : String(error)}\n`);
                     return 1;
                 }
-                process.stdout.write((result.changed ? `Wrote ${result.file}${result.backup ? `  (backup: ${result.backup})` : ''}\n` : `${result.file} already has the current hook; nothing changed.\n`) +
+                show({ kind: 'command', command, values: { host: target, changed: result.changed, file: result.file, mode: policy.mode } }, (result.changed ? `Wrote ${result.file}${result.backup ? `  (backup: ${result.backup})` : ''}\n` : `${result.file} already has the current hook; nothing changed.\n`) +
                     `  ${result.command}\n` +
                     (label ? `${label}\n` : '') +
                     tail +
@@ -214,7 +279,7 @@ async function main(argv) {
                 return 0;
             }
             const snippet = target === 'cursor' ? (0, cursor_1.cursorHooksSnippet)(`node ${cli} cursor-hook`) : target === 'codex' ? (0, codex_1.codexHooksSnippet)(`node ${cli} codex-hook`) : (0, pre_tool_use_1.settingsSnippet)(`node ${cli} hook`);
-            process.stdout.write(`Add this to ${(0, install_1.configPath)(target).replace(process.env.HOME ?? '', '~')} (merge into existing "hooks"), or run: agentguard-burn init ${target} --write\n\n${JSON.stringify(snippet, null, 2)}\n\n` +
+            show({ kind: 'command', command, values: { host: target, config: (0, install_1.configPath)(target), snippet, mode: policy.mode } }, `Add this to ${(0, install_1.configPath)(target).replace(process.env.HOME ?? '', '~')} (merge into existing "hooks"), or run: agentguard-burn init ${target} --write\n\n${JSON.stringify(snippet, null, 2)}\n\n` +
                 (label ? `${label}\n` : '') +
                 tail +
                 (target === 'claude' ? `Other hosts: agentguard-burn init cursor | init codex | proxy --upstream http://127.0.0.1:11434 --host ollama\n` : ''));
@@ -226,8 +291,14 @@ async function main(argv) {
             return 0;
         }
         case 'codex-hook': {
+            const input = readStdinJson();
+            if (input && typeof input === 'object' && input.hook_event_name === 'SessionStart') {
+                const warning = await (0, cli_1.prepareSessionStart)(input, HOME);
+                process.stdout.write(JSON.stringify(warning ? { systemMessage: warning } : {}));
+                return 0;
+            }
             const gateway = new gateway_1.Gateway(HOME);
-            process.stdout.write(JSON.stringify((0, codex_1.handleCodexHook)(readStdinJson(), gateway)));
+            process.stdout.write(JSON.stringify((0, codex_1.handleCodexHook)(input, gateway)));
             return 0;
         }
         case 'proxy': {
@@ -251,6 +322,7 @@ async function main(argv) {
                 log: (l) => process.stderr.write(`${l}\n`),
             });
             const policy = (0, pre_tool_use_1.loadPolicy)(HOME);
+            (0, recording_1.recordFrame)({ kind: 'command', command, values: { listening: running.address.origin, host, mode: policy.mode } });
             process.stderr.write(`agentguard-burn proxy  ${running.address.origin}  ->  ${upstreamRaw}  (${host}, ${policy.mode} mode)\n` +
                 `Point your agent at ${running.address.origin}. Send x-agentguard-session: <id> so calls join a session; without it each client port is its own low-confidence session.\n` +
                 `Ctrl-C to stop.\n`);
@@ -263,7 +335,7 @@ async function main(argv) {
         }
         case 'conformance': {
             const result = await (0, conformance_1.runConformance)();
-            process.stdout.write(result.text + '\n');
+            show({ kind: 'command', command, values: { ok: result.ok, checks: result.checks } }, result.text + '\n');
             return result.ok ? 0 : 1;
         }
         case 'enforce': {
@@ -274,18 +346,18 @@ async function main(argv) {
                 return 2;
             }
             savePolicy({ ...policy, mode: 'enforce' });
-            process.stdout.write('Enforcement ON. The next STOP will block the spawn.\n');
+            show({ kind: 'command', command, values: { mode: 'enforce' } }, 'Enforcement ON. The next STOP will block the spawn.\n');
             return 0;
         }
         case 'shadow': {
             savePolicy({ ...(0, pre_tool_use_1.loadPolicy)(HOME), mode: 'shadow' });
-            process.stdout.write('Back to shadow mode. Decisions are recorded, nothing is blocked.\n');
+            show({ kind: 'command', command, values: { mode: 'shadow' } }, 'Back to shadow mode. Decisions are recorded, nothing is blocked.\n');
             return 0;
         }
         case 'resume': {
             if (has('--clear')) {
                 (0, override_1.clearOverride)(HOME);
-                process.stdout.write('Override cleared. The next STOP blocks.\n');
+                show({ kind: 'command', command, values: { override: false } }, 'Override cleared. The next STOP blocks.\n');
                 return 0;
             }
             const reason = flag('--reason');
@@ -296,13 +368,18 @@ async function main(argv) {
             const once = has('--once');
             const now = Date.now();
             (0, override_1.writeOverride)(HOME, once ? { at: now, once: true, reason } : { at: now, once: false, reason, until: now + override_1.OVERRIDE_WINDOW_MS });
-            process.stdout.write(once
+            show({ kind: 'command', command, values: { once, at: now, until: once ? null : now + override_1.OVERRIDE_WINDOW_MS } }, once
                 ? `Override recorded for the next STOP only, on any host: "${reason}"\n`
                 : `Override recorded for the next ${override_1.OVERRIDE_WINDOW_MS / 60000} minutes, on any host: "${reason}"\n  (agentguard-burn resume --clear to end it early)\n`);
             return 0;
         }
         default:
-            process.stdout.write('agentguard-burn <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' +
                 '  why [session]       token attribution and API list-price equivalents\n' +
                 '  rewrites [session|all]   full-prefix cache writes by cause\n' +
@@ -322,7 +399,21 @@ async function main(argv) {
             return command ? 64 : 0;
     }
 }
-main(process.argv.slice(2)).then((code) => process.exit(code), (error) => {
+async function run() {
+    const parsed = (0, recording_1.recordingArguments)(process.argv.slice(2));
+    (0, recording_1.configureRecording)(parsed.file);
+    try {
+        const code = await main(parsed.args);
+        if (!(0, recording_1.recordedFrameCount)())
+            (0, recording_1.recordFrame)({ kind: 'command', command: parsed.args[0] ?? 'help', values: { exitCode: code } });
+        return code;
+    }
+    catch (error) {
+        (0, recording_1.recordFrame)({ kind: 'command', command: parsed.args[0] ?? 'help', values: { exitCode: 4, failed: true } });
+        throw error;
+    }
+}
+run().then((code) => process.exit(code), (error) => {
     process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
     process.exit(4);
 });

package/dist/src/defaults.d.ts

@@ -11,7 +11,7 @@ import type { Policy, Thresholds } from './types';
  * Spawn rate 8/16 over 15 active minutes warns/stops by default. Sustained
  * thresholds remain 3.5B/5B pending review of deduplicated calibration.
  * This is a dated replay snapshot and an upper bound, not labelled evidence
- * of false-positive rates or guaranteed savings.
+ * of false-positive rates or guaranteed reductions in cost exposure.
  *
  * A previous draft shipped a 50M session budget. Routine sessions on the same
  * machine run 1.4B to 3.5B, so that default would have fired within minutes on