@agentguard-run/burn 0.2.7 → 0.3.1

package/dist/src/idle/platform.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runLocal = void 0;
+exports.elapsedSeconds = elapsedSeconds;
+exports.parsePs = parsePs;
+exports.parseLsofCwds = parseLsofCwds;
+exports.parseWorktrees = parseWorktrees;
+exports.parseSwap = parseSwap;
+exports.parseProcStat = parseProcStat;
+exports.procProcesses = procProcesses;
+exports.browserWindows = browserWindows;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const runLocal = (command, args, options = {}) => new Promise(resolve => {
+    if (options.signal?.aborted) {
+        resolve({ stdout: '', stderr: 'aborted', code: -1 });
+        return;
+    }
+    (0, node_child_process_1.execFile)(command, args, { cwd: options.cwd, timeout: options.timeoutMs ?? 1500,
+        signal: options.signal, killSignal: 'SIGTERM', maxBuffer: options.maxBuffer ?? 4 * 1024 * 1024,
+        encoding: 'utf8', env: { ...process.env, LC_ALL: 'C', GIT_OPTIONAL_LOCKS: '0' } }, (error, stdout, stderr) => {
+        resolve({ stdout, stderr: stderr || (error && typeof error.code !== 'number' ? error.message : ''), code: error ? typeof error.code === 'number' ? error.code : -1 : 0 });
+    });
+});
+exports.runLocal = runLocal;
+function elapsedSeconds(text) {
+    const match = /^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/.exec(text);
+    if (!match)
+        return /^\d+$/.test(text) ? Number(text) : null;
+    return Number(match[1] || 0) * 86400 + Number(match[2] || 0) * 3600 + Number(match[3]) * 60 + Number(match[4]);
+}
+/** lstart is retained verbatim as an OS identity, never reconstructed from elapsed time. */
+function parsePs(text) {
+    const rows = [], seen = new Set();
+    for (const line of text.split('\n')) {
+        const match = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+([A-Za-z]{3}\s+[A-Za-z]{3}\s+\d{1,2}\s+\d\d:\d\d:\d\d\s+\d{4})\s+(\S+)\s+(.+?)\s*$/.exec(line);
+        if (!match)
+            continue;
+        const pid = Number(match[1]);
+        if (seen.has(pid))
+            continue;
+        seen.add(pid);
+        rows.push({ pid, ppid: Number(match[2]), rssBytes: Number(match[3]) * 1024, tty: ['?', '??', '-'].includes(match[4]) ? null : match[4],
+            startedAt: 'ps:' + match[5].replace(/\s+/g, ' '), uptimeSeconds: elapsedSeconds(match[6]), command: match[7], cwd: null, terminalIdleSeconds: null });
+    }
+    return rows;
+}
+function parseLsofCwds(text) {
+    const result = new Map();
+    let pid = null;
+    for (const line of text.split('\n')) {
+        if (/^p\d+$/.test(line))
+            pid = Number(line.slice(1));
+        else if (pid !== null && line.startsWith('n/'))
+            result.set(pid, line.slice(1));
+    }
+    return result;
+}
+function parseWorktrees(text) {
+    return text.split('\n').filter(line => line.startsWith('worktree ')).map(line => line.slice(9));
+}
+function parseSwap(text, platform) {
+    if (platform === 'darwin') {
+        const match = /used\s*=\s*([\d.]+)([KMG])\b/.exec(text);
+        return match ? Math.round(Number(match[1]) * ({ K: 1024, M: 1024 ** 2, G: 1024 ** 3 }[match[2]])) : null;
+    }
+    const total = /^SwapTotal:\s+(\d+)\s+kB$/m.exec(text), free = /^SwapFree:\s+(\d+)\s+kB$/m.exec(text);
+    return total && free ? Math.max(0, Number(total[1]) - Number(free[1])) * 1024 : null;
+}
+function parseProcStat(text, command, bootId, ticks, now, uptime) {
+    const match = /^(\d+) \((.*)\) (.*)$/.exec(text.trim());
+    if (!match)
+        return null;
+    const fields = match[3].split(/\s+/), start = Number(fields[19]), rssPages = Number(fields[21]);
+    if (!Number.isSafeInteger(start) || !Number.isFinite(rssPages) || !ticks)
+        return null;
+    return { pid: Number(match[1]), ppid: Number(fields[1]), command: command || match[2],
+        startedAt: `proc:${bootId}:${start}`, uptimeSeconds: Math.max(0, uptime - start / ticks), rssBytes: rssPages * 4096,
+        cwd: null, tty: null, terminalIdleSeconds: null };
+}
+/** Linux fallback reads proc metadata only. cmdline is process identity, never transcript content. */
+async function procProcesses(root, runner, signal, limit, skipped) {
+    let names, bootId, uptime;
+    try {
+        names = (await node_fs_1.promises.readdir(root)).filter(name => /^\d+$/.test(name)).sort((a, b) => Number(a) - Number(b));
+        bootId = (await node_fs_1.promises.readFile((0, node_path_1.join)(root, 'sys/kernel/random/boot_id'), 'utf8')).trim();
+        uptime = Number((await node_fs_1.promises.readFile((0, node_path_1.join)(root, 'uptime'), 'utf8')).split(' ')[0]);
+    }
+    catch {
+        skipped.push('Linux process metadata is unavailable.');
+        return [];
+    }
+    if (names.length > limit) {
+        skipped.push('Linux process scan exceeds its limit; process ownership is incomplete.');
+        return [];
+    }
+    const clock = await runner('getconf', ['CLK_TCK'], { signal, timeoutMs: 500 });
+    const pages = await runner('getconf', ['PAGESIZE'], { signal, timeoutMs: 500 });
+    const ticks = clock.code === 0 ? Number(clock.stdout.trim()) : NaN, pageSize = pages.code === 0 ? Number(pages.stdout.trim()) : NaN;
+    if (!Number.isFinite(ticks) || !Number.isFinite(pageSize)) {
+        skipped.push('Linux clock tick or page size is unavailable; stable process snapshots were skipped.');
+        return [];
+    }
+    const rows = [];
+    for (const name of names) {
+        if (signal?.aborted)
+            break;
+        try {
+            const [stat, cmdline] = await Promise.all([node_fs_1.promises.readFile((0, node_path_1.join)(root, name, 'stat'), 'utf8'), node_fs_1.promises.readFile((0, node_path_1.join)(root, name, 'cmdline'), 'utf8')]);
+            const row = parseProcStat(stat, cmdline.replace(/\0/g, ' ').trim(), bootId, ticks, Date.now(), uptime);
+            if (!row)
+                continue;
+            row.rssBytes = row.rssBytes / 4096 * pageSize;
+            try {
+                row.cwd = await node_fs_1.promises.readlink((0, node_path_1.join)(root, name, 'cwd'));
+            }
+            catch { /* Exited or inaccessible. */ }
+            try {
+                const tty = await node_fs_1.promises.readlink((0, node_path_1.join)(root, name, 'fd/0'));
+                if (/^\/dev\/(?:pts\/\d+|tty\w*)$/.test(tty))
+                    row.tty = tty.slice(5);
+            }
+            catch { /* No accessible terminal. */ }
+            rows.push(row);
+        }
+        catch { /* Process exited between enumeration and stat. */ }
+    }
+    return rows;
+}
+/** CoreGraphics reads local window metadata without Apple Events or accessibility control. */
+async function browserWindows(pids, runner, options) {
+    if (!pids.length)
+        return new Map();
+    const safePids = pids.filter(pid => Number.isSafeInteger(pid) && pid > 0);
+    // The default JXA bridge treats CFArrayRef as an opaque Ref. An explicit
+    // toll-free NSObject return type makes the local array readable without AX.
+    const source = `ObjC.import('CoreGraphics'); ObjC.bindFunction('CGWindowListCopyWindowInfo',['id',['unsigned int','unsigned int']]); var ids=${JSON.stringify(safePids)}; var counts={}; ids.forEach(function(id){counts[id]=0;}); var windows=ObjC.deepUnwrap($.CGWindowListCopyWindowInfo(0,0)); windows.forEach(function(w){var pid=Number(w.kCGWindowOwnerPID); if(Number(w.kCGWindowLayer)===0 && ids.indexOf(pid)!==-1) counts[pid]++;}); JSON.stringify(counts);`;
+    const result = await runner('osascript', ['-l', 'JavaScript', '-e', source], options);
+    if (result.code !== 0)
+        return null;
+    try {
+        const parsed = JSON.parse(result.stdout), values = new Map();
+        for (const pid of safePids) {
+            if (!Number.isSafeInteger(parsed[pid]) || parsed[pid] < 0)
+                return null;
+            values.set(pid, parsed[pid]);
+        }
+        return values;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,41 @@
+import type { AuditReport } from './types';
+type Awaitable<T> = T | Promise<T>;
+export interface ReapDependencies {
+    inputIsTTY: boolean;
+    outputIsTTY: boolean;
+    readAudit(): Awaitable<AuditReport>;
+    /** The CLI supplies OS operations. Tests supply fakes, never real signals. */
+    signal(pid: number, signal: 'SIGTERM'): Awaitable<void>;
+    alive(pid: number): Awaitable<boolean>;
+    gitDirty?(cwd: string): Awaitable<boolean | null>;
+    wait?(milliseconds: number): Promise<void>;
+    currentPid?: number;
+    timeoutMs?: number;
+}
+export interface InteractiveReapDependencies extends ReapDependencies {
+    question(prompt: string): Awaitable<string>;
+}
+export interface ReapPidResult {
+    pid: number;
+    status: 'exited' | 'still_running' | 'signal_failed' | 'refused';
+    reason: string;
+}
+export interface ReapRowResult {
+    selection: number;
+    id: string;
+    label: string;
+    status: 'refused' | 'terminated' | 'still_running' | 'signal_failed';
+    reason: string;
+    pids: ReapPidResult[];
+}
+export interface ReapResult {
+    cancelled: boolean;
+    results: ReapRowResult[];
+}
+/** Accept numbers actually typed at the prompt, never flags or an implied all. */
+export declare function parseReapSelection(value: string, rowCount: number): number[];
+/** The displayed snapshot is immutable authorization: recollection can only narrow it. */
+export declare function reapSelected(snapshot: AuditReport, selectionText: string, dependencies: ReapDependencies): Promise<ReapResult>;
+/** The CLI prints the entire audit before calling this prompt. */
+export declare function interactiveReap(snapshot: AuditReport, dependencies: InteractiveReapDependencies): Promise<ReapResult>;
+export {};

package/dist/src/idle/reap.js

@@ -0,0 +1,262 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseReapSelection = parseReapSelection;
+exports.reapSelected = reapSelected;
+exports.interactiveReap = interactiveReap;
+const DAY_SECONDS = 24 * 60 * 60;
+function interactive(dependencies) {
+    if (dependencies.inputIsTTY !== true || dependencies.outputIsTTY !== true) {
+        throw new Error('Reap requires an interactive terminal for both input and output. Nothing was closed.');
+    }
+}
+/** Accept numbers actually typed at the prompt, never flags or an implied all. */
+function parseReapSelection(value, rowCount) {
+    if (typeof value !== 'string')
+        throw new Error('Type displayed item numbers to select processes.');
+    const input = value.trim();
+    if (!input)
+        return [];
+    if (!/^[1-9]\d*(?:[\s,]+[1-9]\d*)*$/.test(input)) {
+        throw new Error('Type displayed item numbers separated by spaces or commas. Flags, ranges and yes are not accepted.');
+    }
+    const numbers = input.split(/[\s,]+/).map(Number);
+    if (numbers.some(number => !Number.isSafeInteger(number) || number > rowCount)) {
+        throw new Error('Every selected number must name an item in the displayed audit. Nothing was closed.');
+    }
+    return [...new Set(numbers)];
+}
+function byPid(report) {
+    const result = new Map();
+    for (const item of report.processes) {
+        if (!Number.isSafeInteger(item.pid) || item.pid < 1 || result.has(item.pid))
+            return null;
+        result.set(item.pid, item);
+    }
+    return result;
+}
+function protectedPids(report, currentPid) {
+    const map = byPid(report);
+    if (!map || !Number.isSafeInteger(currentPid) || currentPid < 1)
+        return null;
+    const protectedSet = new Set([1]);
+    let pid = currentPid;
+    while (pid > 1) {
+        if (protectedSet.has(pid))
+            return null;
+        protectedSet.add(pid);
+        const item = map.get(pid);
+        if (!item || !Number.isSafeInteger(item.ppid) || item.ppid < 0)
+            return null;
+        pid = item.ppid;
+    }
+    return protectedSet;
+}
+function sameProcess(before, after) {
+    return typeof before.startedAt === 'string' && before.startedAt.length > 0 && before.startedAt === after.startedAt
+        && before.pid === after.pid && before.ppid === after.ppid && before.command.length > 0 && before.command === after.command
+        && before.cwd === after.cwd && before.tty === after.tty;
+}
+function sameOwnership(before, after) {
+    return before.id === after.id && before.kind === after.kind && before.host === after.host
+        && before.pid === after.pid && before.label === after.label && before.cwd === after.cwd;
+}
+function descendants(pid, processes) {
+    const rows = [...processes], result = new Set();
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const item of rows)
+            if ((item.ppid === pid || result.has(item.ppid)) && !result.has(item.pid) && item.pid !== pid) {
+                result.add(item.pid);
+                changed = true;
+            }
+    }
+    return result;
+}
+function listMatches(values, expected) {
+    return values.length === new Set(values).size && values.length === expected.size && values.every(pid => expected.has(pid));
+}
+async function refusal(snapshot, row, fresh, dependencies, alreadyExited = new Set(), checkGit = true) {
+    if (row.kind === 'workspace')
+        return row.openHandles === true
+            ? 'Workspace has open file handles; information only. Workspaces are never deleted or closed.'
+            : 'Workspaces are informational only and are never deleted or closed.';
+    if (!['session', 'browser', 'daemon'].includes(row.kind))
+        return 'This item has no supported process ownership classification.';
+    if (row.pid === null || !row.pids.includes(row.pid) || row.pids.length === 0)
+        return 'The audit has no complete process group for this item.';
+    const currentPid = dependencies.currentPid ?? process.pid;
+    const originalProtected = protectedPids(snapshot, currentPid), currentProtected = protectedPids(fresh, currentPid);
+    if (!originalProtected || !currentProtected)
+        return 'The current process ancestry could not be verified.';
+    if (row.pids.some(pid => originalProtected.has(pid) || currentProtected.has(pid)))
+        return 'The selection includes this reap process or one of its ancestors.';
+    const initial = byPid(snapshot), current = byPid(fresh);
+    if (!initial || !current)
+        return 'The process inventory is ambiguous or incomplete.';
+    const matches = fresh.rows.filter(item => item.id === row.id);
+    if (matches.length !== 1 || !sameOwnership(row, matches[0]))
+        return 'The item disappeared or its ownership classification changed after confirmation.';
+    const latest = matches[0];
+    if (latest.dirty === true)
+        return 'The selected process group has a working directory with dirty or untracked files.';
+    if (!checkGit && latest.dirty !== false)
+        return 'Fresh Git status for the selected process group is unknown. Nothing further will be closed.';
+    const remaining = new Set(row.pids.filter(pid => !alreadyExited.has(pid)));
+    if (!listMatches(row.processes.map(item => item.pid), new Set(row.pids)))
+        return 'The confirmed audit did not include every process identity.';
+    if (!listMatches(latest.pids, remaining) || !listMatches(latest.processes.map(item => item.pid), remaining)) {
+        return 'The process group changed after confirmation. New or unlisted processes will not be closed.';
+    }
+    for (const child of descendants(row.pid, current.values())) {
+        if (!remaining.has(child))
+            return `Unlisted descendant PID ${child} prevents closing this process group.`;
+    }
+    for (const pid of remaining) {
+        const before = initial.get(pid), now = current.get(pid);
+        const rowBefore = row.processes.find(item => item.pid === pid), rowNow = latest.processes.find(item => item.pid === pid);
+        if (!before || !now || !rowBefore || !rowNow || !sameProcess(before, rowBefore) || !sameProcess(now, rowNow) || !sameProcess(before, now)) {
+            return `PID ${pid} disappeared, was reused, changed working directory or was reparented after confirmation.`;
+        }
+        const session = row.kind === 'session' || fresh.rows.some(item => item.kind === 'session' && item.pid === pid);
+        const unknownTerminal = now.terminalIdleSeconds === null || !Number.isFinite(now.terminalIdleSeconds);
+        if ((session && unknownTerminal) || (!unknownTerminal && now.terminalIdleSeconds < DAY_SECONDS)) {
+            return now.terminalIdleSeconds === null || !Number.isFinite(now.terminalIdleSeconds)
+                ? `Terminal activity for PID ${pid} is unknown. Transcript or profile age cannot authorize closing it.`
+                : `PID ${pid} has terminal input within the last 24 hours.`;
+        }
+        if (!now.cwd)
+            return `The working directory for PID ${pid} is unknown.`;
+        if (!checkGit)
+            continue;
+        let dirty = null;
+        try {
+            if (dependencies.gitDirty)
+                dirty = await dependencies.gitDirty(now.cwd);
+            else {
+                const evidence = fresh.rows.filter(item => item.cwd === now.cwd).map(item => item.dirty);
+                dirty = evidence.includes(true) ? true : evidence.length > 0 && evidence.every(value => value === false) ? false : null;
+            }
+        }
+        catch { /* Unknown Git state never authorizes a close. */ }
+        if (dirty === true)
+            return `PID ${pid} has a working directory with dirty or untracked files.`;
+        if (dirty !== false)
+            return `Git status for PID ${pid}'s working directory is unknown.`;
+    }
+    return null;
+}
+function childFirst(row) {
+    const processes = new Map(row.processes.map(item => [item.pid, item]));
+    const depth = (pid) => {
+        const visited = new Set();
+        let current = pid;
+        while (processes.has(current) && !visited.has(current)) {
+            visited.add(current);
+            current = processes.get(current).ppid;
+        }
+        return visited.size;
+    };
+    return [...row.pids].sort((a, b) => depth(b) - depth(a) || a - b);
+}
+async function waitForExit(pid, dependencies) {
+    const requested = dependencies.timeoutMs ?? 3000;
+    const duration = Number.isFinite(requested) ? Math.max(0, Math.min(10000, requested)) : 3000;
+    const wait = dependencies.wait ?? (milliseconds => new Promise(resolve => setTimeout(resolve, milliseconds)));
+    let elapsed = 0;
+    while (true) {
+        try {
+            if (!await dependencies.alive(pid))
+                return true;
+        }
+        catch {
+            return false;
+        }
+        if (elapsed >= duration)
+            return false;
+        const interval = Math.min(100, duration - elapsed);
+        try {
+            await wait(interval);
+        }
+        catch {
+            return false;
+        }
+        elapsed += interval;
+    }
+}
+/** The displayed snapshot is immutable authorization: recollection can only narrow it. */
+async function reapSelected(snapshot, selectionText, dependencies) {
+    interactive(dependencies);
+    const selections = parseReapSelection(selectionText, snapshot.rows.length);
+    if (selections.length === 0)
+        return { cancelled: true, results: [] };
+    const authorization = structuredClone(snapshot);
+    const results = [];
+    const signaled = new Set();
+    for (const selection of selections) {
+        const row = authorization.rows[selection - 1];
+        const result = { selection, id: row.id, label: row.label, status: 'refused', reason: '', pids: [] };
+        results.push(result);
+        const exited = new Set();
+        for (const pid of childFirst(row)) {
+            let reason;
+            try {
+                reason = await refusal(authorization, row, await dependencies.readAudit(), dependencies, exited);
+                // Git inspection can await subprocesses. Recheck OS identity and
+                // ownership after that wait, immediately before the individual signal.
+                if (!reason)
+                    reason = await refusal(authorization, row, await dependencies.readAudit(), dependencies, exited, false);
+            }
+            catch {
+                reason = 'A fresh process and working-directory audit could not be completed.';
+            }
+            if (reason) {
+                result.reason = reason;
+                result.pids.push({ pid, status: 'refused', reason });
+                break;
+            }
+            if (signaled.has(pid)) {
+                result.reason = `PID ${pid} was already selected in another item; it will not be signaled twice.`;
+                break;
+            }
+            // This is the only signal site. It never targets a process group and never
+            // escalates to SIGKILL, including when a selected process stays alive.
+            try {
+                await dependencies.signal(pid, 'SIGTERM');
+                signaled.add(pid);
+            }
+            catch {
+                const message = `SIGTERM could not be sent to PID ${pid}. No stronger signal was attempted.`;
+                result.pids.push({ pid, status: 'signal_failed', reason: message });
+                result.status = 'signal_failed';
+                result.reason = message;
+                break;
+            }
+            const ended = await waitForExit(pid, dependencies);
+            const message = ended ? `PID ${pid} exited after SIGTERM.` : `PID ${pid} is still alive or its exit could not be verified. No stronger signal was sent.`;
+            result.pids.push({ pid, status: ended ? 'exited' : 'still_running', reason: message });
+            if (ended)
+                exited.add(pid);
+            else {
+                result.status = 'still_running';
+                result.reason = message;
+                break;
+            }
+        }
+        if (result.pids.length === 0)
+            result.reason = row.kind === 'workspace'
+                ? row.openHandles === true ? 'Workspace has open file handles; information only. Workspaces are never deleted or closed.'
+                    : 'Workspaces are informational only and are never deleted or closed.' : 'No verified process identities were listed.';
+        else if (result.pids.length === row.pids.length && result.pids.every(item => item.status === 'exited')) {
+            result.status = 'terminated';
+            result.reason = 'Every selected process exited after SIGTERM.';
+        }
+    }
+    return { cancelled: false, results };
+}
+/** The CLI prints the entire audit before calling this prompt. */
+async function interactiveReap(snapshot, dependencies) {
+    interactive(dependencies);
+    const selection = await dependencies.question('Type displayed item numbers to close with SIGTERM, or press Enter to cancel: ');
+    return reapSelected(snapshot, selection, dependencies);
+}

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

@@ -0,0 +1,10 @@
+import type { AuditReport } from './types';
+export declare function memory(bytes: number | null): string;
+export declare function duration(seconds: number | null): string;
+export declare function rankAudit(report: AuditReport): AuditReport;
+/** Raw command lines can contain prompts or credentials. They are never printed. */
+export declare function auditForJson(report: AuditReport): unknown;
+export declare function renderAudit(report: AuditReport, options?: {
+    colour?: boolean;
+    width?: number;
+}): string;

package/dist/src/idle/render.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.memory = memory;
+exports.duration = duration;
+exports.rankAudit = rankAudit;
+exports.auditForJson = auditForJson;
+exports.renderAudit = renderAudit;
+/** Local resource tables use Burn's existing light frame and WARN vocabulary. */
+const frames_1 = require("../frames");
+const plain = (value) => value.replace(/[\x00-\x1f\x7f-\x9f]/g, '?');
+const shorten = (value, width) => {
+    const chars = Array.from(plain(value));
+    return chars.length <= width ? chars.join('') : chars.slice(0, Math.max(0, width - 3)).join('') + '...';
+};
+const pad = (value, width) => {
+    const clean = shorten(value, width);
+    return clean + ' '.repeat(Math.max(0, width - Array.from(clean).length));
+};
+function memory(bytes) {
+    if (bytes === null)
+        return 'unknown';
+    return bytes >= 1e9 ? `${(bytes / 1e9).toFixed(2)} GB` : `${(bytes / 1e6).toFixed(1)} MB`;
+}
+function duration(seconds) {
+    if (seconds === null)
+        return '?';
+    if (seconds >= 86400)
+        return `${(seconds / 86400).toFixed(1)}d`;
+    if (seconds >= 3600)
+        return `${(seconds / 3600).toFixed(1)}h`;
+    return `${Math.max(0, Math.floor(seconds / 60))}m`;
+}
+function rankAudit(report) {
+    return { ...report, rows: [...report.rows].sort((a, b) => {
+            if ((a.kind === 'workspace') !== (b.kind === 'workspace'))
+                return a.kind === 'workspace' ? 1 : -1;
+            return (a.kind === 'workspace' ? (b.sizeBytes ?? 0) - (a.sizeBytes ?? 0) : b.rssBytes - a.rssBytes) || a.id.localeCompare(b.id);
+        }) };
+}
+/** Raw command lines can contain prompts or credentials. They are never printed. */
+function auditForJson(report) {
+    const process = ({ command: ignored, ...metadata }) => metadata;
+    const owned = new Set(report.rows.flatMap(row => row.pids));
+    return { ...report, processes: report.processes.filter(row => owned.has(row.pid)).map(process), rows: report.rows.map(row => ({ ...row, processes: row.processes.map(process) })) };
+}
+function renderAudit(report, options = {}) {
+    if (report.platform === 'win32')
+        return 'not supported on this platform yet';
+    if (options.colour)
+        return (0, frames_1.renderFrame)((0, frames_1.auditFrame)('ps', report), { width: Math.min(104, options.width ?? process.stdout.columns ?? 104), colour: true }).render();
+    const width = Math.max(100, Math.min(160, options.width ?? 118)), inner = width - 4;
+    const lines = [];
+    const border = (left, middle, right) => lines.push(left + middle.repeat(width - 2) + right);
+    const line = (value = '') => {
+        let content = pad(value, inner);
+        if (options.colour)
+            content = content.replace(/\[WARN\]/g, '\x1b[33m[WARN]\x1b[0m');
+        lines.push(`│ ${content} │`);
+    };
+    const wrap = (value, prefix = '') => {
+        let rest = Array.from(plain(value));
+        do {
+            line(prefix + rest.splice(0, inner - prefix.length).join(''));
+        } while (rest.length);
+    };
+    border('╭', '─', '╮');
+    line('AGENTGUARD BURN | LOCAL COST EXPOSURE');
+    line(`Observed ${report.generatedAt} | ${report.platform} | memory first, then workspace disk`);
+    border('├', '─', '┤');
+    const pathWidth = inner - 79;
+    const columns = (values) => values.map((value, index) => pad(value, [4, 9, 8, pathWidth, 10, 7, 7, 11, 8, 6][index])).join(' ');
+    line(columns(['#', 'HOST/KIND', 'PID', 'WORKING DIRECTORY', 'MEMORY', 'UPTIME', 'IDLE', 'METHOD', 'WINDOWS', '']));
+    let hasWorkspaces = false;
+    report.rows.forEach((row, index) => {
+        if (row.kind === 'workspace') {
+            if (!hasWorkspaces) {
+                border('├', '─', '┤');
+                line('WORKSPACES | information only, never deleted');
+                hasWorkspaces = true;
+            }
+            wrap(`${index + 1}. ${row.warn ? '[WARN] ' : ''}${row.cwd ?? row.label}`);
+            line(`   Disk ${memory(row.sizeBytes)} | modified ${row.modifiedAt ?? 'unknown'} | ${row.orphan ? 'orphan' : 'registered or in use'}`);
+            line(`   Dirty: ${row.dirty === null ? 'unknown' : row.dirty ? 'yes, modified or untracked' : 'no'} | Open handles: ${row.openHandles === null ? 'unknown' : row.openHandles ? 'yes' : 'no'}`);
+        }
+        else {
+            line(columns([String(index + 1), row.host ?? row.kind, String(row.pid ?? '?'), row.cwd ?? '?', memory(row.rssBytes), duration(row.uptimeSeconds), duration(row.idleSeconds), row.idleMethod, row.kind === 'browser' ? String(row.windows ?? '?') : '', row.warn ? '[WARN]' : '']));
+            if (row.cwd && Array.from(row.cwd).length > pathWidth)
+                wrap(row.cwd, '   cwd: ');
+            if (row.pids.length > 1)
+                wrap(`   ${row.pids.length} processes: ${row.pids.join(', ')}`);
+        }
+        for (const reason of row.reasons)
+            wrap(reason, '   ');
+    });
+    if (!report.rows.length)
+        line('No agent-owned resources found in the readable scope.');
+    border('├', '─', '┤');
+    line(`Idle agent held memory: ${memory(report.totals.idleAgentMemoryBytes)}`);
+    line(`Orphan workspace disk: ${memory(report.totals.orphanWorkspaceBytes)}`);
+    line(`Swap in use: ${memory(report.swapUsedBytes)}`);
+    wrap('Swap is only released by the operating system on reboot. Burn does not touch it.');
+    wrap('RSS is resident memory, not a bill. Shared pages can be counted in more than one process.');
+    wrap('Idle methods: terminal device access time; transcript file writes; profile file writes; unknown.');
+    for (const skipped of report.skipped)
+        wrap(`Skipped: ${skipped}`);
+    border('╰', '─', '╯');
+    return lines.join('\n');
+}

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

@@ -0,0 +1,56 @@
+/** Local metadata only. Unknown evidence is explicit and never authorizes reaping. */
+export interface AuditThresholds {
+    idle_session_warn_hours: number;
+    idle_browser_warn_minutes: number;
+    orphan_workspace_warn_days: number;
+}
+export interface ProcessSnapshot {
+    pid: number;
+    ppid: number;
+    command: string;
+    /** Stable OS start identity, checked again before signaling to avoid PID reuse. */
+    startedAt: string | null;
+    uptimeSeconds: number | null;
+    rssBytes: number;
+    cwd: string | null;
+    tty: string | null;
+    terminalIdleSeconds: number | null;
+}
+export type AuditKind = 'session' | 'daemon' | 'browser' | 'workspace';
+export interface AuditRow {
+    id: string;
+    kind: AuditKind;
+    label: string;
+    host: 'claude' | 'codex' | null;
+    pid: number | null;
+    pids: number[];
+    processes: ProcessSnapshot[];
+    cwd: string | null;
+    uptimeSeconds: number | null;
+    idleSeconds: number | null;
+    idleMethod: 'terminal' | 'transcript' | 'profile' | 'unknown';
+    rssBytes: number;
+    sizeBytes: number | null;
+    modifiedAt: string | null;
+    dirty: boolean | null;
+    openHandles: boolean | null;
+    windows: number | null;
+    orphan: boolean;
+    warn: boolean;
+    reasons: string[];
+}
+export interface AuditReport {
+    version: 1;
+    generatedAt: string;
+    platform: string;
+    rows: AuditRow[];
+    processes: ProcessSnapshot[];
+    swapUsedBytes: number | null;
+    skipped: string[];
+    totals: {
+        idleAgentMemoryBytes: number;
+        orphanWorkspaceBytes: number;
+    };
+    thresholds: AuditThresholds;
+}
+export declare const DEFAULT_AUDIT_THRESHOLDS: AuditThresholds;

package/dist/src/idle/types.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_AUDIT_THRESHOLDS = void 0;
+exports.DEFAULT_AUDIT_THRESHOLDS = {
+    idle_session_warn_hours: 24,
+    idle_browser_warn_minutes: 60,
+    orphan_workspace_warn_days: 2,
+};

package/dist/src/install.js

@@ -110,11 +110,13 @@ function install(host, cliPath, home = (0, node_os_1.homedir)()) {
     let changed;
     if (host === 'claude') {
         command = `node ${cliPath} hook`;
-        changed = mergeMatcherStyle(cfg, 'PreToolUse', '.*', command, 15);
+        const startChanged = mergeMatcherStyle(cfg, 'SessionStart', '.*', command, 1);
+        changed = mergeMatcherStyle(cfg, 'PreToolUse', '.*', command, 15) || startChanged;
     }
     else if (host === 'codex') {
         command = `node ${cliPath} codex-hook`;
-        changed = mergeMatcherStyle(cfg, 'PreToolUse', '.*', command, 15);
+        const startChanged = mergeMatcherStyle(cfg, 'SessionStart', '.*', command, 1);
+        changed = mergeMatcherStyle(cfg, 'PreToolUse', '.*', command, 15) || startChanged;
     }
     else {
         command = `node ${cliPath} cursor-hook`;