@agentguard-run/burn 0.2.7 → 0.3.0

package/dist/src/frames.d.ts

@@ -0,0 +1,38 @@
+/** Recorded frames carry observations, not ANSI, screen text or process arguments. */
+import { Canvas } from './canvas';
+import type { AuditReport, AuditRow } from './idle/types';
+import type { BurnReport } from './types';
+import type { ReplaySummary } from './replay/simulate';
+export type AuditFrameReport = Omit<AuditReport, 'processes' | 'rows'> & {
+    rows: Array<Omit<AuditRow, 'processes'>>;
+};
+export type BurnFrame = {
+    kind: 'audit';
+    command: 'ps' | 'reap';
+    report: AuditFrameReport;
+    page?: number;
+} | {
+    kind: 'report';
+    report: BurnReport;
+    subject?: 'spawn' | 'call';
+    outcome?: 'blocked' | 'shadow' | 'overridden' | 'allowed';
+} | {
+    kind: 'replay';
+    summary: ReplaySummary;
+    page?: number;
+} | {
+    kind: 'command';
+    command: string;
+    values: Record<string, unknown>;
+    page?: number;
+};
+export interface FrameOptions {
+    recorded?: boolean;
+    at?: string;
+    width?: number;
+    height?: number;
+    colour?: boolean;
+}
+export declare function auditFrame(command: 'ps' | 'reap', report: AuditReport): BurnFrame;
+export declare function framePageCount(data: BurnFrame, options?: FrameOptions): number;
+export declare function renderFrame(data: BurnFrame, options?: FrameOptions): Canvas;

package/dist/src/frames.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.auditFrame = auditFrame;
+exports.framePageCount = framePageCount;
+exports.renderFrame = renderFrame;
+/** Recorded frames carry observations, not ANSI, screen text or process arguments. */
+const canvas_1 = require("./canvas");
+function auditFrame(command, report) {
+    const { processes: ignored, rows, ...metadata } = report;
+    return { kind: 'audit', command, report: { ...metadata, rows: rows.map(({ processes: omitted, ...row }) => row) } };
+}
+const memory = (n) => n === null ? '?' : n >= 1e9 ? `${(n / 1e9).toFixed(2)}G` : `${(n / 1e6).toFixed(1)}M`;
+const duration = (n) => n === null ? '?' : n >= 86400 ? `${(n / 86400).toFixed(1)}d` : n >= 3600 ? `${(n / 3600).toFixed(1)}h` : `${Math.floor(n / 60)}m`;
+const flag = (v) => v === null ? '?' : v ? 'yes' : 'no';
+const fit = (v, n) => String(v ?? '?').slice(0, n).padEnd(n);
+function framePageCount(data, options = {}) {
+    const c = new canvas_1.Canvas(options);
+    if (data.kind === 'audit')
+        return Math.max(1, Math.ceil(data.report.rows.length / Math.max(1, Math.floor((c.height - 18) / 2))));
+    if (data.kind === 'command')
+        return Math.max(1, Math.ceil(valueRows(data.values).length / Math.max(1, c.height - 6)));
+    if (data.kind === 'replay')
+        return Math.max(1, Math.ceil(data.summary.sessions.length / Math.max(1, c.height - 16)));
+    return 1;
+}
+function valueRows(values, prefix = '', depth = 0) {
+    return Object.entries(values).flatMap(([key, value]) => {
+        const name = prefix ? `${prefix}.${key}` : key;
+        if (value && typeof value === 'object' && depth < 3)
+            return valueRows(value, name, depth + 1);
+        return [`${name}: ${typeof value === 'object' ? JSON.stringify(value) : String(value)}`];
+    });
+}
+function renderFrame(data, options = {}) {
+    const canvas = new canvas_1.Canvas(options), w = canvas.width, h = canvas.height;
+    const replay = options.recorded || data.kind === 'replay';
+    const at = options.at ?? new Date().toISOString();
+    const pages = framePageCount(data, options), page = 'page' in data ? Math.max(0, Math.min(pages - 1, data.page ?? 0)) : 0;
+    canvas.header('AGENTGUARD / BURN', replay ? 'RECORDED RUN · 1x' : 'LIVE');
+    canvas.footer(`${replay ? 'recorded run' : 'local only'} · ${page + 1}/${pages}`, at.slice(11, 19) + ' UTC');
+    if (data.kind === 'audit') {
+        const report = data.report, slots = Math.max(1, Math.floor((h - 18) / 2));
+        canvas.put(2, 0, `${data.command.toUpperCase()} · LOCAL COST EXPOSURE · ${report.platform}`, 'mint');
+        canvas.put(3, 0, `Observed ${report.generatedAt} · memory first, then workspace disk`, 'slate');
+        const wide = w >= 100;
+        canvas.put(5, 0, wide ? '#   HOST      PID     MEMORY  UPTIME IDLE   METHOD     WIN  WORKING DIRECTORY' : '#   HOST      PID     MEMORY  IDLE   METHOD     WIN', 'slate');
+        report.rows.slice(page * slots, (page + 1) * slots).forEach((row, i) => {
+            const y = 6 + i * 2, n = page * slots + i + 1;
+            const common = `${fit(n, 3)} ${fit(row.host ?? row.kind, 9)} ${fit(row.pid, 7)} ${fit(memory(row.kind === 'workspace' ? row.sizeBytes : row.rssBytes), 7)} `;
+            const details = wide ? `${fit(duration(row.uptimeSeconds), 6)} ${fit(duration(row.idleSeconds), 6)} ${fit(row.idleMethod, 10)} ${fit(row.kind === 'browser' ? row.windows : '', 4)} ${fit(row.cwd, Math.max(0, w - 66))}`
+                : `${fit(duration(row.idleSeconds), 6)} ${fit(row.idleMethod, 10)} ${fit(row.kind === 'browser' ? row.windows : '', 4)}`;
+            canvas.put(y, 0, (common + details).slice(0, w - 6), row.warn ? 'amber' : 'white');
+            if (row.warn)
+                canvas.put(y, w - 5, 'WARN', 'amber');
+            canvas.put(y + 1, 4, row.kind === 'workspace'
+                ? `dirty:${flag(row.dirty)} open:${flag(row.openHandles)} ${row.orphan ? 'orphan' : 'registered/in use'} modified:${row.modifiedAt ?? '?'} ${row.cwd ?? row.label}`
+                : `${wide ? '' : `up:${duration(row.uptimeSeconds)} · `}${row.cwd ?? '?'} · ${row.pids.length} process(es)${row.reasons.length ? ' · ' + row.reasons.join('; ') : ''}`, 'slate');
+        });
+        if (!report.rows.length)
+            canvas.put(6, 0, 'No agent-owned resources found in the readable scope.', 'slate');
+        const y = h - 11, half = Math.floor(w / 2);
+        canvas.rule(y, 0, w);
+        canvas.put(y + 1, 0, 'IDLE AGENT MEMORY · GB', 'slate');
+        canvas.put(y + 1, half, 'ORPHAN DISK · GB', 'slate');
+        canvas.digits(y + 2, 0, (report.totals.idleAgentMemoryBytes / 1e9).toFixed(2), report.totals.idleAgentMemoryBytes ? 'amber' : 'mint');
+        canvas.digits(y + 2, half, (report.totals.orphanWorkspaceBytes / 1e9).toFixed(2), report.totals.orphanWorkspaceBytes ? 'amber' : 'mint');
+        canvas.put(y + 5, 0, `Swap ${memory(report.swapUsedBytes)} · Only the operating system releases swap on reboot.`, 'slate');
+        canvas.put(y + 6, 0, 'Burn does not touch swap or delete workspaces. RSS may count shared pages twice.', 'slate');
+        canvas.put(y + 7, 0, report.skipped.length ? `Skipped ${report.skipped.length}: ${report.skipped[0]} · full detail: ps --json` : 'Idle method shown per row. Unknown evidence never authorizes closing a session.', report.skipped.length ? 'amber' : 'slate');
+    }
+    else if (data.kind === 'report') {
+        const r = data.report, color = r.verdict === 'STOP' ? 'red' : r.verdict === 'WARN' ? 'amber' : 'mint';
+        canvas.put(3, 0, `AGENTGUARD ${r.verdict}`, color);
+        canvas.put(4, 0, data.outcome === 'blocked' ? (data.subject === 'call' ? 'model call blocked' : 'agent spawn blocked') : data.outcome === 'shadow' ? 'shadow: would have blocked, call allowed' : data.outcome === 'overridden' ? 'override: call allowed' : r.verdict === 'STOP' ? 'STOP boundary · enforcement outcome not recorded' : 'session advisory', color);
+        canvas.digits(6, 0, r.totals.spawns, color);
+        canvas.put(10, 0, `spawns · ${r.totals.tokens.toLocaleString('en-US')} tokens · depth ${r.totals.maxDepth}`, 'slate');
+        r.findings.slice(0, 5).forEach((f, i) => canvas.put(12 + i, 0, `${f.detector}: ${f.summary}`, color));
+        canvas.put(18, 0, 'DO NOW', 'white');
+        r.prescriptions.slice(0, Math.max(0, h - 23)).forEach((p, i) => canvas.put(20 + i, 0, `${i + 1}. ${p}`, 'white'));
+        canvas.put(h - 4, 0, 'override once:  agentguard-burn resume --once --reason "..."', 'slate');
+    }
+    else if (data.kind === 'replay') {
+        const s = data.summary, slots = Math.max(1, h - 16);
+        canvas.put(3, 0, 'REPLAY · OBSERVED HISTORY', 'mint');
+        canvas.digits(5, 0, Math.round(s.catchableShare * 100), 'amber');
+        canvas.put(9, 0, 'percent of recorded tokens after the first STOP boundary', 'slate');
+        canvas.put(10, 0, `${s.totalTokens.toLocaleString('en-US')} tokens · ${s.sessions.length} sessions`, 'white');
+        canvas.bar(11, 0, Math.min(65, w), s.catchableShare, 'amber');
+        s.sessions.slice(page * slots, (page + 1) * slots).forEach((row, i) => canvas.put(13 + i, 0, `${row.sessionId.slice(0, 8)}  ${row.totalTokens.toLocaleString('en-US')} tokens  ${row.spawns} spawns  ${row.finalVerdict}`, row.finalVerdict === 'STOP' ? 'red' : row.finalVerdict === 'WARN' ? 'amber' : 'white'));
+        canvas.put(h - 3, 0, 'Upper bound; assumes no override or restart. Nothing left this machine.', 'slate');
+    }
+    else {
+        canvas.put(3, 0, data.command.toUpperCase(), 'mint');
+        const slots = Math.max(1, h - 6);
+        valueRows(data.values).slice(page * slots, (page + 1) * slots).forEach((line, i) => canvas.put(4 + i, 0, line, 'white'));
+    }
+    return canvas;
+}

package/dist/src/gateway.js

@@ -31,6 +31,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Gateway = void 0;
 exports.mergeCapabilities = mergeCapabilities;
+const recording_1 = require("./recording");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const defaults_1 = require("./defaults");
@@ -381,6 +382,8 @@ class Gateway {
             compute: d.compute,
             coverage: meta.capabilities,
         })}\n`, { mode: 0o600 });
+        if (notify || d.blocked)
+            (0, recording_1.recordFrame)({ kind: 'report', report: d.report, subject: d.action === 'spawn' ? 'spawn' : 'call', outcome: d.blocked ? 'blocked' : d.override ? 'overridden' : d.wouldBlock ? 'shadow' : 'allowed' });
         return {
             decisionId,
             action: d.action,

package/dist/src/hook/pre-tool-use.d.ts

@@ -17,6 +17,7 @@
 import { type ReaderCursor, type UsageSnapshot } from '../history/claude-transcript';
 import type { BurnReport, SessionState } from '../types';
 export interface HookInput {
+    hook_event_name?: string;
     session_id?: string;
     transcript_path?: string;
     tool_name?: string;

package/dist/src/hook/pre-tool-use.js

@@ -34,8 +34,10 @@ const reservations_1 = require("../state/reservations");
 const session_1 = require("../state/session");
 const policy_1 = require("../policy");
 const override_1 = require("../override");
+const recording_1 = require("../recording");
 const render_1 = require("../replay/render");
 const live_1 = require("../insights/live");
+const hook_1 = require("../idle/hook");
 const SPAWN_TOOLS = new Set(['Agent', 'Task']);
 function sessionFile(home, sessionId) {
     return (0, node_path_1.join)(home, 'sessions', `${sessionId.replace(/[^a-zA-Z0-9_-]/g, '_')}.json`);
@@ -159,6 +161,10 @@ function rememberNotified(home, sessionId, signature) {
     }
 }
 function handlePreToolUse(input, home, now = Date.now()) {
+    if (input.hook_event_name === 'SessionStart') {
+        const warning = (0, hook_1.sessionStartWarning)(home, (0, policy_1.loadPolicy)(home), now);
+        return warning ? { continue: true, suppressOutput: false, systemMessage: warning } : { continue: true, suppressOutput: true };
+    }
     const observation = (0, live_1.observeTool)(home, input, 'claude', (0, policy_1.loadPolicy)(home), now);
     const output = handleSpawnPreToolUse(input, home, now);
     if (!observation.messages.length)
@@ -219,8 +225,11 @@ function handleSpawnPreToolUse(input, home, now) {
                 totals: report.totals,
             });
             if (shouldDeny && policy.mode === 'enforce') {
-                if (!override)
+                if (!override) {
+                    (0, recording_1.recordFrame)({ kind: 'report', report, outcome: 'blocked' });
                     return deny(reason);
+                }
+                (0, recording_1.recordFrame)({ kind: 'report', report, outcome: 'overridden' });
                 return {
                     continue: true,
                     systemMessage: `AgentGuard STOP overridden${override.once ? ' once' : ''} ("${override.reason}"): ${report.findings[0]?.summary ?? ''}`,
@@ -231,6 +240,7 @@ function handleSpawnPreToolUse(input, home, now) {
                 if (signature === notified)
                     return { continue: true, suppressOutput: true };
                 rememberNotified(home, input.session_id, signature);
+                (0, recording_1.recordFrame)({ kind: 'report', report, outcome: policy.mode === 'shadow' && shouldDeny ? 'shadow' : 'allowed' });
                 return {
                     continue: true,
                     systemMessage: `AgentGuard ${report.verdict}${policy.mode === 'shadow' && shouldDeny ? ' (shadow: would have blocked)' : ''}: ${report.findings[0]?.summary ?? ''}`,
@@ -265,6 +275,7 @@ function deny(reason) {
 function settingsSnippet(command) {
     return {
         hooks: {
+            SessionStart: [{ matcher: '.*', hooks: [{ type: 'command', command, timeout: 1 }] }],
             PreToolUse: [{ matcher: '.*', hooks: [{ type: 'command', command, timeout: 15 }] }],
         },
     };

package/dist/src/idle/cache.d.ts

@@ -0,0 +1,8 @@
+import type { Policy } from '../types';
+import { type AuditReport, type AuditThresholds } from './types';
+export declare const AUDIT_CACHE_TTL_MS: number;
+export declare const AUDIT_CACHE_MAX_BYTES: number;
+export declare const auditCachePath: (home: string) => string;
+export declare function auditThresholds(policy: Policy): AuditThresholds;
+export declare function readAuditCache(home: string, now?: number): AuditReport | null;
+export declare function writeAuditCache(home: string, report: AuditReport): void;

package/dist/src/idle/cache.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.auditCachePath = exports.AUDIT_CACHE_MAX_BYTES = exports.AUDIT_CACHE_TTL_MS = void 0;
+exports.auditThresholds = auditThresholds;
+exports.readAuditCache = readAuditCache;
+exports.writeAuditCache = writeAuditCache;
+/** Five-minute local metadata cache. Hooks never perform a synchronous scan. */
+const node_fs_1 = require("node:fs");
+const node_crypto_1 = require("node:crypto");
+const node_path_1 = require("node:path");
+const types_1 = require("./types");
+exports.AUDIT_CACHE_TTL_MS = 5 * 60_000;
+exports.AUDIT_CACHE_MAX_BYTES = 4 * 1024 * 1024;
+const auditCachePath = (home) => (0, node_path_1.join)(home, 'idle-audit-cache.json');
+exports.auditCachePath = auditCachePath;
+function auditThresholds(policy) {
+    const result = { ...types_1.DEFAULT_AUDIT_THRESHOLDS };
+    for (const field of Object.keys(result)) {
+        const value = policy.thresholds[field];
+        if (typeof value === 'number' && Number.isFinite(value) && value >= 0)
+            result[field] = value;
+    }
+    return result;
+}
+function usable(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const report = value;
+    return report.version === 1 && typeof report.generatedAt === 'string' && Number.isFinite(Date.parse(report.generatedAt))
+        && Array.isArray(report.rows) && report.rows.length <= 10_000 && report.rows.every(row => row && typeof row === 'object'
+        && ['session', 'daemon', 'browser', 'workspace'].includes(row.kind)
+        && Number.isFinite(row.rssBytes) && row.rssBytes >= 0
+        && (row.idleSeconds === null || (Number.isFinite(row.idleSeconds) && row.idleSeconds >= 0)));
+}
+function readAuditCache(home, now = Date.now()) {
+    try {
+        const file = (0, exports.auditCachePath)(home), stat = (0, node_fs_1.lstatSync)(file);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > exports.AUDIT_CACHE_MAX_BYTES)
+            return null;
+        const value = JSON.parse((0, node_fs_1.readFileSync)(file, 'utf8'));
+        if (!usable(value))
+            return null;
+        const age = now - Date.parse(value.generatedAt);
+        return age >= 0 && age < exports.AUDIT_CACHE_TTL_MS ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeAuditCache(home, report) {
+    if (!usable(report))
+        throw new Error('invalid_idle_audit');
+    // Hook summaries do not need command lines; never cache process arguments.
+    const summary = { ...report, processes: [], rows: report.rows.map(row => ({ ...row, processes: [] })) };
+    const text = JSON.stringify(summary) + '\n';
+    if (Buffer.byteLength(text) > exports.AUDIT_CACHE_MAX_BYTES)
+        throw new Error('idle_audit_too_large');
+    (0, node_fs_1.mkdirSync)(home, { recursive: true, mode: 0o700 });
+    const file = (0, exports.auditCachePath)(home), temporary = `${file}.${process.pid}.${(0, node_crypto_1.randomUUID)()}`;
+    try {
+        (0, node_fs_1.writeFileSync)(temporary, text, { mode: 0o600, flag: 'wx' });
+        (0, node_fs_1.renameSync)(temporary, file);
+    }
+    finally {
+        try {
+            (0, node_fs_1.unlinkSync)(temporary);
+        }
+        catch { }
+    }
+}

package/dist/src/idle/classify.d.ts

@@ -0,0 +1,13 @@
+import type { ProcessSnapshot } from './types';
+/** Command parsing is identity-only; these values stay on the local machine. */
+export declare function commandWords(command: string): string[];
+export declare function agentHost(command: string): 'claude' | 'codex' | null;
+export declare function isTemporary(path: string | null): boolean;
+export declare function browserProfile(command: string): string | null;
+export declare function isChromeProcess(command: string): boolean;
+export declare function isAutomationBrowser(command: string): boolean;
+export declare function daemonPath(command: string): string | null;
+export declare function isPluginDaemon(command: string): boolean;
+export declare function descendants(root: number, processes: ProcessSnapshot[]): ProcessSnapshot[];
+export declare function hasAncestor(pid: number, candidates: Set<number>, processes: Map<number, ProcessSnapshot>): boolean;
+export declare function inside(path: string, directory: string): boolean;

package/dist/src/idle/classify.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.commandWords = commandWords;
+exports.agentHost = agentHost;
+exports.isTemporary = isTemporary;
+exports.browserProfile = browserProfile;
+exports.isChromeProcess = isChromeProcess;
+exports.isAutomationBrowser = isAutomationBrowser;
+exports.daemonPath = daemonPath;
+exports.isPluginDaemon = isPluginDaemon;
+exports.descendants = descendants;
+exports.hasAncestor = hasAncestor;
+exports.inside = inside;
+const node_path_1 = require("node:path");
+/** Command parsing is identity-only; these values stay on the local machine. */
+function commandWords(command) {
+    const words = [];
+    let word = '', quote = '', escaped = false;
+    for (const character of command) {
+        if (escaped) {
+            word += character;
+            escaped = false;
+            continue;
+        }
+        if (character === '\\' && quote !== "'") {
+            escaped = true;
+            continue;
+        }
+        if (quote) {
+            if (character === quote)
+                quote = '';
+            else
+                word += character;
+            continue;
+        }
+        if (character === '"' || character === "'") {
+            quote = character;
+            continue;
+        }
+        if (/\s/.test(character)) {
+            if (word) {
+                words.push(word);
+                word = '';
+            }
+        }
+        else
+            word += character;
+    }
+    if (escaped)
+        word += '\\';
+    if (word)
+        words.push(word);
+    return words;
+}
+function agentHost(command) {
+    const words = commandWords(command), executable = (0, node_path_1.basename)(words[0] || '');
+    if (['claude', 'codex'].includes(executable))
+        return executable;
+    if (/^node(?:js)?$/.test(executable)) {
+        const script = words.slice(1).find(word => !word.startsWith('-')) || '';
+        if (/(?:^|\/)codex(?:\.js)?$/.test(script) || /\/@openai\/codex\/bin\/codex\.js$/.test(script))
+            return 'codex';
+        if (/(?:^|\/)claude(?:\.js)?$/.test(script) || /\/@anthropic-ai\/claude-code\/cli\.js$/.test(script))
+            return 'claude';
+    }
+    return null;
+}
+function isTemporary(path) {
+    return Boolean(path && /^(?:\/private)?\/tmp(?:\/|$)|^\/private\/var\/folders\/[^/]+\/[^/]+\/T(?:\/|$)|^\/var\/tmp(?:\/|$)/.test(path));
+}
+function browserProfile(command) {
+    const words = commandWords(command);
+    const inline = words.find(word => word.startsWith('--user-data-dir='));
+    const index = words.indexOf('--user-data-dir');
+    const value = inline?.slice('--user-data-dir='.length) || (index >= 0 ? words[index + 1] : null);
+    return value && (0, node_path_1.isAbsolute)(value) ? value : null;
+}
+function isChromeProcess(command) {
+    // The browser executable must be the actual process, not a shell/node command
+    // that merely mentions Chrome or an ordinary helper's ancestor.
+    const words = commandWords(command), first = words[0] || '', executable = (0, node_path_1.basename)(first);
+    const browser = /^(?:Google Chrome(?: for Testing)?|Chromium)(?: Helper(?: \([^)]*\))?)?$/.test(executable) || /(?:^|\/)(?:chrome|chromium|chromium-browser|headless_shell)$/.test(first)
+        || (!/^(?:node(?:js)?|sh|bash|zsh|python3?)$/.test(executable) && /^\/[^\n]*\/(?:Google Chrome(?: for Testing)?|Chromium)(?: Helper(?: \([^)]*\))?)?(?:\s|$)/.test(command))
+        || /^(?:Google Chrome(?: for Testing)?|Chromium)(?:\s|$)/.test(command);
+    return browser;
+}
+function isAutomationBrowser(command) {
+    if (!isChromeProcess(command))
+        return false;
+    const profile = browserProfile(command);
+    return /(?:^|\s)--(?:remote-debugging-(?:port(?:=\d+)?|pipe)|enable-automation)(?:\s|$)/.test(command)
+        || Boolean(profile && (isTemporary(profile) || /(?:playwright|puppeteer)[-_]/i.test(profile)));
+}
+function daemonPath(command) {
+    const words = commandWords(command);
+    return words.slice(1).find(word => (0, node_path_1.isAbsolute)(word) && /(?:\.[cm]?[jt]s|\.py|worker|daemon|server|hook)(?:$|\/)/i.test(word)) || null;
+}
+function isPluginDaemon(command) {
+    const words = commandWords(command), executable = (0, node_path_1.basename)(words[0] || '');
+    if (!/^(?:node(?:js)?|bun|python(?:3(?:\.\d+)?)?)$/.test(executable))
+        return false;
+    const source = daemonPath(command);
+    return Boolean(source && /(?:agentguard|codex-plugin|claude-code|(?:^|\/)plugins?(?:\/|[-.])|(?:^|\/)hooks?(?:\/|[-.]))/i.test(source)
+        && /(?:worker|daemon|hook|mcp(?:[-/]server)?|plugin[-/]server|server\.[cm]?js)/i.test(source));
+}
+function descendants(root, processes) {
+    const found = new Set([root]);
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const process of processes)
+            if (found.has(process.ppid) && !found.has(process.pid)) {
+                found.add(process.pid);
+                changed = true;
+            }
+    }
+    return processes.filter(process => found.has(process.pid));
+}
+function hasAncestor(pid, candidates, processes) {
+    const seen = new Set();
+    let process = processes.get(pid);
+    while (process && process.ppid > 0 && !seen.has(process.ppid)) {
+        if (candidates.has(process.ppid))
+            return true;
+        seen.add(process.ppid);
+        process = processes.get(process.ppid);
+    }
+    return false;
+}
+function inside(path, directory) {
+    const suffix = (0, node_path_1.relative)(directory, path);
+    return suffix === '' || (!suffix.startsWith('..') && !(0, node_path_1.isAbsolute)(suffix));
+}

package/dist/src/idle/cli.d.ts

@@ -0,0 +1,2 @@
+export declare function prepareSessionStart(input: unknown, home: string): Promise<string | null>;
+export declare function runIdleCommand(command: 'ps' | 'reap', args: string[], home: string): Promise<number>;

package/dist/src/idle/cli.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareSessionStart = prepareSessionStart;
+exports.runIdleCommand = runIdleCommand;
+/** Interactive cleanup is separate from the read-only audit and hook advisory. */
+const presentation_1 = require("../presentation");
+const frames_1 = require("../frames");
+const promises_1 = require("node:readline/promises");
+const policy_1 = require("../policy");
+const collect_1 = require("./collect");
+const cache_1 = require("./cache");
+const render_1 = require("./render");
+const reap_1 = require("./reap");
+const hook_1 = require("./hook");
+async function prepareSessionStart(input, home) {
+    if (!input || typeof input !== 'object' || input.hook_event_name !== 'SessionStart')
+        return null;
+    // A cache miss gets at most 150 ms of audit work. It is advisory in both modes.
+    return (0, hook_1.sessionStartCheck)(home, { collect: options => (0, collect_1.collectAudit)(options) });
+}
+async function runIdleCommand(command, args, home) {
+    if (process.platform === 'win32') {
+        process.stdout.write('not supported on this platform yet\n');
+        return 0;
+    }
+    const allowed = command === 'ps' ? ['--json', '--no-color'] : ['--no-color'];
+    if (args.some(arg => !allowed.includes(arg))) {
+        process.stderr.write(command === 'reap'
+            ? 'reap requires numbers typed at its interactive prompt. There is no --yes flag.\n'
+            : 'Usage: agentguard-burn ps [--json] [--no-color]\n');
+        return 64;
+    }
+    if (command === 'reap' && (!process.stdin.isTTY || !process.stdout.isTTY)) {
+        process.stderr.write('reap requires an interactive terminal and confirmation. Nothing was closed.\n');
+        return 1;
+    }
+    const thresholds = (0, cache_1.auditThresholds)((0, policy_1.loadPolicy)(home));
+    const readAudit = async () => (0, render_1.rankAudit)(await (0, collect_1.collectAudit)({ thresholds }));
+    const audit = await readAudit();
+    try {
+        (0, cache_1.writeAuditCache)(home, audit);
+    }
+    catch {
+        audit.skipped.push('The local five-minute audit cache could not be written.');
+    }
+    (0, presentation_1.present)((0, frames_1.auditFrame)(command, audit), (args.includes('--json') ? JSON.stringify((0, render_1.auditForJson)(audit), null, 2)
+        : (0, render_1.renderAudit)(audit, { colour: false, width: process.stdout.columns })) + '\n', { colour: Boolean(process.stdout.isTTY) && !args.includes('--no-color') && process.env.NO_COLOR === undefined, protocol: args.includes('--json') });
+    if (command === 'ps')
+        return 0;
+    process.stdout.write('Only selected process rows can receive SIGTERM. Workspaces are information only.\n');
+    const terminal = (0, promises_1.createInterface)({ input: process.stdin, output: process.stdout });
+    try {
+        const result = await (0, reap_1.interactiveReap)(audit, {
+            inputIsTTY: Boolean(process.stdin.isTTY), outputIsTTY: Boolean(process.stdout.isTTY), currentPid: process.pid,
+            readAudit: async () => (0, render_1.rankAudit)(await (0, collect_1.collectAudit)({ thresholds, workspaceRoots: [] })), gitDirty: cwd => (0, collect_1.checkWorkingDirectory)(cwd),
+            question: prompt => terminal.question(prompt), signal: (pid, signal) => { process.kill(pid, signal); },
+            alive: pid => { try {
+                process.kill(pid, 0);
+                return true;
+            }
+            catch (error) {
+                return error.code !== 'ESRCH';
+            } },
+        });
+        const plain = (result.cancelled ? 'Cancelled. Nothing was closed.\n' : '') + result.results.map(row => `${row.selection}. ${row.status}: ${row.reason}\n` + row.pids.map(pid => `   ${pid.reason}\n`).join('')).join('');
+        (0, presentation_1.present)({ kind: 'command', command: 'reap', values: { cancelled: result.cancelled, results: result.results } }, plain, { colour: Boolean(process.stdout.isTTY) && !args.includes('--no-color') && process.env.NO_COLOR === undefined });
+        return 0;
+    }
+    finally {
+        terminal.close();
+    }
+}

package/dist/src/idle/collect.d.ts

@@ -0,0 +1,38 @@
+import { type Stats } from 'node:fs';
+import { type CommandRunner } from './platform';
+import { type AuditReport, type AuditThresholds } from './types';
+export type { CommandRunner } from './platform';
+export interface MetadataAccess {
+    lstat(path: string): Promise<Stats>;
+    readdir(path: string): Promise<string[]>;
+    realpath(path: string): Promise<string>;
+    readPrefix(path: string, bytes: number): Promise<string>;
+    readFirstLine?(path: string, bytes: number, signal?: AbortSignal): Promise<string>;
+}
+export interface CollectAuditOptions {
+    thresholds?: Partial<AuditThresholds>;
+    now?: number;
+    signal?: AbortSignal;
+    platform?: string;
+    homeDir?: string;
+    workspaceRoots?: string[];
+    claudeProjectsRoot?: string;
+    codexSessionsRoot?: string;
+    procRoot?: string;
+    runner?: CommandRunner;
+    metadata?: MetadataAccess;
+    maxProcesses?: number;
+    maxScanEntries?: number;
+    maxDepth?: number;
+    maxWorkspaces?: number;
+    maxDurationMs?: number;
+    commandTimeoutMs?: number;
+}
+export declare function checkWorkingDirectory(cwd: string, options?: {
+    runner?: CommandRunner;
+    signal?: AbortSignal;
+    commandTimeoutMs?: number;
+}): Promise<boolean | null>;
+export declare const gitDirty: typeof checkWorkingDirectory;
+/** Bounded local OS and filesystem metadata; no network client or transcript parser is imported. */
+export declare function collectAudit(options?: CollectAuditOptions): Promise<AuditReport>;