@agentguard-run/burn 0.2.7 → 0.3.0

package/dist/src/idle/collect.js

@@ -0,0 +1,543 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gitDirty = void 0;
+exports.checkWorkingDirectory = checkWorkingDirectory;
+exports.collectAudit = collectAudit;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const classify_1 = require("./classify");
+const platform_1 = require("./platform");
+const types_1 = require("./types");
+const localMetadata = {
+    lstat: path => node_fs_1.promises.lstat(path), readdir: path => node_fs_1.promises.readdir(path), realpath: path => node_fs_1.promises.realpath(path),
+    async readFirstLine(path, bytes, signal) {
+        const file = await node_fs_1.promises.open(path, 'r');
+        try {
+            const buffer = Buffer.alloc(bytes);
+            let count = 0;
+            while (count < bytes && !signal?.aborted) {
+                const read = await file.read(buffer, count, 1, count);
+                if (!read.bytesRead)
+                    return '';
+                if (buffer[count] === 10)
+                    return buffer.subarray(0, count).toString('utf8');
+                count++;
+            }
+            return '';
+        }
+        finally {
+            await file.close();
+        }
+    },
+    async readPrefix(path, bytes) {
+        const file = await node_fs_1.promises.open(path, 'r');
+        try {
+            const buffer = Buffer.alloc(bytes);
+            const result = await file.read(buffer, 0, bytes, 0);
+            return buffer.subarray(0, result.bytesRead).toString('utf8');
+        }
+        finally {
+            await file.close();
+        }
+    },
+};
+async function checkWorkingDirectory(cwd, options = {}) {
+    if (!cwd || options.signal?.aborted)
+        return null;
+    const runner = options.runner || platform_1.runLocal;
+    const result = await runner('git', ['-c', 'core.fsmonitor=false', '-c', 'core.untrackedCache=false', '-C', cwd, 'status', '--porcelain=v1', '--untracked-files=normal'], { signal: options.signal, timeoutMs: options.commandTimeoutMs ?? 1500, maxBuffer: 512 * 1024 });
+    if (result.code === 0)
+        return Boolean(result.stdout.trim());
+    if (/not a git repository/i.test(result.stderr || '') && !/permission denied|operation not permitted/i.test(result.stderr || '')) {
+        // A broken worktree's .git pointer is not proof that its contents are clean.
+        let directory = (0, node_path_1.resolve)(cwd);
+        for (let depth = 0; depth < 24; depth++) {
+            if (options.signal?.aborted)
+                return null;
+            try {
+                await node_fs_1.promises.lstat((0, node_path_1.join)(directory, '.git'));
+                return null;
+            }
+            catch (error) {
+                if (!['ENOENT', 'ENOTDIR'].includes(error.code || ''))
+                    return null;
+            }
+            const parent = (0, node_path_1.dirname)(directory);
+            if (parent === directory)
+                return false;
+            directory = parent;
+        }
+    }
+    return null;
+}
+exports.gitDirty = checkWorkingDirectory;
+const blankRow = (kind, id, label) => ({ id, kind, label, host: null, pid: null, pids: [], processes: [], cwd: null,
+    uptimeSeconds: null, idleSeconds: null, idleMethod: 'unknown', rssBytes: 0, sizeBytes: null, modifiedAt: null, dirty: null, openHandles: null,
+    windows: null, orphan: false, warn: false, reasons: [] });
+const cleanThresholds = (input) => {
+    const result = { ...types_1.DEFAULT_AUDIT_THRESHOLDS };
+    for (const key of Object.keys(result)) {
+        const value = input?.[key];
+        if (typeof value === 'number' && Number.isFinite(value) && value >= 0)
+            result[key] = value;
+    }
+    return result;
+};
+/** Bounded local OS and filesystem metadata; no network client or transcript parser is imported. */
+async function collectAudit(options = {}) {
+    const now = options.now ?? Date.now(), platform = options.platform || process.platform, home = options.homeDir || (0, node_os_1.homedir)();
+    const thresholds = cleanThresholds(options.thresholds), runner = options.runner || platform_1.runLocal, metadata = options.metadata || localMetadata;
+    const skipped = [], rows = [], started = performance.now();
+    const limit = options.maxScanEntries ?? 8000, maxDepth = options.maxDepth ?? 5, maxProcesses = options.maxProcesses ?? 10000;
+    let scanned = 0, stopped = false;
+    const alive = () => {
+        if (stopped)
+            return false;
+        if (options.signal?.aborted || performance.now() - started > (options.maxDurationMs ?? 30000)) {
+            stopped = true;
+            skipped.push(options.signal?.aborted ? 'Audit canceled; remaining evidence is unknown.' : 'Audit time budget reached; remaining evidence is unknown.');
+            return false;
+        }
+        return true;
+    };
+    const commandOptions = () => ({ signal: options.signal, timeoutMs: options.commandTimeoutMs ?? 1200 });
+    const run = async (command, args, extra = {}) => alive() ? runner(command, args, { ...commandOptions(), ...extra }) : { code: -1, stdout: '', stderr: 'aborted' };
+    const stat = async (path) => { if (!alive())
+        return null; try {
+        return await metadata.lstat(path);
+    }
+    catch {
+        return null;
+    } };
+    const canonical = async (path) => { if (!alive())
+        return (0, node_path_1.resolve)(path); try {
+        return await metadata.realpath(path);
+    }
+    catch {
+        return (0, node_path_1.resolve)(path);
+    } };
+    async function entries(path) {
+        if (!alive())
+            return null;
+        try {
+            const list = (await metadata.readdir(path)).sort();
+            scanned += list.length;
+            if (scanned > limit) {
+                skipped.push('Filesystem scan entry limit reached; directory evidence is incomplete.');
+                return null;
+            }
+            return list;
+        }
+        catch {
+            return null;
+        }
+    }
+    async function newest(path, depth = 0) {
+        const info = await stat(path);
+        if (!info || info.isSymbolicLink())
+            return null;
+        let value = info.mtimeMs;
+        if (info.isDirectory()) {
+            if (depth >= maxDepth) {
+                skipped.push('Directory activity scan reached its depth bound.');
+                return null;
+            }
+            const names = await entries(path);
+            if (!names)
+                return null;
+            for (const name of names) {
+                if (!alive())
+                    return null;
+                const childPath = (0, node_path_1.join)(path, name), childInfo = await stat(childPath);
+                if (childInfo?.isSymbolicLink())
+                    continue;
+                const child = await newest(childPath, depth + 1);
+                if (child === null)
+                    return null;
+                value = Math.max(value, child);
+            }
+        }
+        return value;
+    }
+    async function directoryFacts(path, depth = 0) {
+        const info = await stat(path);
+        if (!info || info.isSymbolicLink())
+            return null;
+        if (!info.isDirectory())
+            return { size: info.size, newest: info.mtimeMs };
+        if (depth >= maxDepth)
+            return null;
+        const names = await entries(path);
+        if (!names)
+            return null;
+        let size = 0, modified = info.mtimeMs;
+        for (const name of names) {
+            if (!alive())
+                return null;
+            const childPath = (0, node_path_1.join)(path, name), childInfo = await stat(childPath);
+            if (childInfo?.isSymbolicLink())
+                continue; // Never follow workspace symlinks.
+            const child = await directoryFacts(childPath, depth + 1);
+            if (!child)
+                return null;
+            size += child.size;
+            modified = Math.max(modified, child.newest);
+        }
+        return { size, newest: modified };
+    }
+    const ps = await run('ps', ['-axo', 'pid=,ppid=,rss=,tty=,lstart=,etime=,command='], { maxBuffer: 8 * 1024 * 1024 });
+    let processes = ps.code === 0 ? (0, platform_1.parsePs)(ps.stdout) : [];
+    if (!processes.length && platform === 'linux' && alive())
+        processes = await (0, platform_1.procProcesses)(options.procRoot || '/proc', runner, options.signal, maxProcesses, skipped);
+    if (!processes.length)
+        skipped.push('Process table is unavailable; process ownership and memory are unknown.');
+    if (processes.length > maxProcesses) {
+        processes = [];
+        skipped.push('Process table exceeds its safety bound; process ownership is unknown.');
+    }
+    const processByPid = new Map(processes.map(value => [value.pid, value]));
+    const sessionCandidates = processes.filter(value => (0, classify_1.agentHost)(value.command)), browserCandidates = processes.filter(value => (0, classify_1.isAutomationBrowser)(value.command));
+    const daemonCandidates = processes.filter(value => (0, classify_1.isPluginDaemon)(value.command));
+    const relevant = new Map();
+    for (const candidate of [...sessionCandidates, ...browserCandidates, ...daemonCandidates])
+        for (const child of (0, classify_1.descendants)(candidate.pid, processes))
+            relevant.set(child.pid, child);
+    if (relevant.size && alive()) {
+        if (platform === 'darwin' || processes.some(value => value.startedAt?.startsWith('ps:'))) {
+            const result = await run('lsof', ['-nP', '-a', '-d', 'cwd', '-p', [...relevant.keys()].join(','), '-Fpn'], { timeoutMs: options.commandTimeoutMs ?? 5000 });
+            if (result.code === 0 || result.code === 1)
+                for (const [pid, cwd] of (0, platform_1.parseLsofCwds)(result.stdout)) {
+                    const process = processByPid.get(pid);
+                    if (process)
+                        process.cwd = cwd;
+                }
+            else
+                skipped.push('Some process working directories are unavailable from lsof.');
+        }
+        for (const process of relevant.values()) {
+            if (!alive())
+                break;
+            if (platform === 'linux' && !process.cwd) {
+                try {
+                    process.cwd = await node_fs_1.promises.readlink((0, node_path_1.join)(options.procRoot || '/proc', String(process.pid), 'cwd'));
+                }
+                catch { /* Unknown, never inferred. */ }
+            }
+            if (process.cwd)
+                process.cwd = await canonical(process.cwd);
+            if (process.tty) {
+                const ttyPath = process.tty.startsWith('/dev/') ? process.tty : (0, node_path_1.join)('/dev', process.tty);
+                const tty = await stat(ttyPath);
+                if (tty && tty.atimeMs > 0 && tty.atimeMs <= now)
+                    process.terminalIdleSeconds = Math.max(0, (now - tty.atimeMs) / 1000);
+            }
+        }
+    }
+    const dirtyCache = new Map();
+    async function dirty(cwd) {
+        if (!cwd || !alive())
+            return null;
+        if (!dirtyCache.has(cwd))
+            dirtyCache.set(cwd, await checkWorkingDirectory(cwd, { runner, signal: options.signal, commandTimeoutMs: options.commandTimeoutMs }));
+        return dirtyCache.get(cwd) ?? null;
+    }
+    async function existence(path) {
+        if (!alive())
+            return null;
+        try {
+            await metadata.lstat(path);
+            return true;
+        }
+        catch (error) {
+            const code = error.code;
+            return code === 'ENOENT' || code === 'ENOTDIR' ? false : null;
+        }
+    }
+    const registrations = new Map();
+    async function registered(path) {
+        if (registrations.has(path))
+            return registrations.get(path);
+        const top = await run('git', ['-C', path, 'rev-parse', '--show-toplevel']);
+        let value = null;
+        if (top.code === 0 && top.stdout.trim()) {
+            const result = await run('git', ['-C', path, 'worktree', 'list', '--porcelain']);
+            if (result.code === 0) {
+                const listed = await Promise.all((0, platform_1.parseWorktrees)(result.stdout).map(canonical));
+                value = listed.includes(await canonical(top.stdout.trim()));
+            }
+        }
+        else if (/not a git repository/i.test(top.stderr || ''))
+            value = false;
+        registrations.set(path, value);
+        return value;
+    }
+    async function openHandles(path) {
+        if (processes.some(process => process.cwd && (0, classify_1.inside)(process.cwd, path)))
+            return true;
+        if (!processes.length)
+            return null;
+        const result = await run('lsof', ['-nP', '-Fpn', '+D', path]);
+        if (result.code === 0)
+            return /^p\d+$/m.test(result.stdout);
+        if (result.code === 1 && !result.stdout.trim() && !result.stderr?.trim())
+            return false;
+        return null;
+    }
+    let swapUsedBytes = null;
+    if (alive() && platform === 'darwin') {
+        const result = await run('sysctl', ['vm.swapusage']);
+        if (result.code === 0)
+            swapUsedBytes = (0, platform_1.parseSwap)(result.stdout, platform);
+    }
+    else if (alive() && platform === 'linux') {
+        try {
+            swapUsedBytes = (0, platform_1.parseSwap)(await metadata.readPrefix((0, node_path_1.join)(options.procRoot || '/proc', 'meminfo'), 16384), platform);
+        }
+        catch { /* Explicit unknown below. */ }
+    }
+    if (swapUsedBytes === null)
+        skipped.push('Swap usage is unavailable.');
+    const workspacePaths = new Set(), roots = options.workspaceRoots || ['/private/tmp', '/tmp', (0, node_path_1.join)(home, '.claude', 'scratchpads')];
+    async function findWorkspaces(path, depth = 0) {
+        if (!alive())
+            return;
+        if (depth > Math.min(maxDepth, 4)) {
+            skipped.push('Workspace discovery depth limit reached; deeper directories were skipped.');
+            return;
+        }
+        if (workspacePaths.size >= (options.maxWorkspaces ?? 1000)) {
+            skipped.push('Workspace count limit reached; additional candidates were skipped.');
+            return;
+        }
+        const info = await stat(path);
+        if (!info) {
+            if (await existence(path) === null)
+                skipped.push('Some workspace directories were inaccessible; discovery is incomplete.');
+            return;
+        }
+        if (!info.isDirectory() || info.isSymbolicLink())
+            return;
+        const names = await entries(path);
+        if (!names)
+            return;
+        if (names.includes('.git') || names.includes('package.json') || (depth > 0 && /scratchpads?$/i.test((0, node_path_1.basename)(path)))) {
+            workspacePaths.add(await canonical(path));
+            return;
+        }
+        for (const name of names) {
+            if (!alive())
+                return;
+            if (!['node_modules', '.git', '.cache'].includes(name))
+                await findWorkspaces((0, node_path_1.join)(path, name), depth + 1);
+        }
+    }
+    for (const root of new Set(await Promise.all(roots.map(canonical))))
+        await findWorkspaces(root);
+    scanned = 0;
+    const codexLocators = [];
+    let codexLocated = false;
+    async function locateCodex(path, depth = 0) {
+        if (!alive() || depth > 5)
+            return;
+        const names = await entries(path);
+        if (!names)
+            return;
+        for (const name of names) {
+            if (!alive())
+                return;
+            const location = (0, node_path_1.join)(path, name), info = await stat(location);
+            if (!info || info.isSymbolicLink())
+                continue;
+            if (info.isDirectory())
+                await locateCodex(location, depth + 1);
+            else if (name.endsWith('.jsonl') && info.isFile()) {
+                // Only the leading session_meta locator is read. No message is parsed,
+                // retained, printed, or sent; later transcript lines are never read.
+                try {
+                    const first = await (metadata.readFirstLine || localMetadata.readFirstLine)(location, 8192, options.signal);
+                    if (!first)
+                        continue;
+                    const header = JSON.parse(first);
+                    if (header.type === 'session_meta' && typeof header.payload?.cwd === 'string')
+                        codexLocators.push({ cwd: await canonical(header.payload.cwd), path: location, modified: info.mtimeMs });
+                }
+                catch { /* Not a readable locator. */ }
+            }
+        }
+    }
+    async function idle(row) {
+        const terminal = row.processes.map(value => value.terminalIdleSeconds).filter((value) => value !== null);
+        if (terminal.length) {
+            row.idleSeconds = Math.min(...terminal);
+            row.idleMethod = 'terminal';
+            row.reasons.push('Idle time uses the most recent terminal device access among this process group.');
+            return;
+        }
+        if (!row.cwd || !row.host)
+            return;
+        let modified = null;
+        if (row.host === 'claude') {
+            const encoded = row.cwd.replace(/[^A-Za-z0-9]/g, '-');
+            modified = await newest((0, node_path_1.join)(options.claudeProjectsRoot || (0, node_path_1.join)(home, '.claude', 'projects'), encoded));
+            if (modified !== null)
+                row.reasons.push('Idle is a workspace transcript-directory estimate; another session in the same workspace can make it newer.');
+        }
+        else {
+            if (!codexLocated) {
+                codexLocated = true;
+                const previousScanned = scanned;
+                scanned = 0;
+                await locateCodex(options.codexSessionsRoot || (0, node_path_1.join)(home, '.codex', 'sessions'));
+                scanned = previousScanned;
+            }
+            const matching = codexLocators.filter(value => value.cwd === row.cwd);
+            if (matching.length) {
+                modified = Math.max(...matching.map(value => value.modified));
+                row.reasons.push('Idle is a same-workspace Codex transcript metadata estimate; no message content is retained.');
+            }
+        }
+        if (modified !== null && modified <= now) {
+            row.idleSeconds = (now - modified) / 1000;
+            row.idleMethod = 'transcript';
+        }
+        else
+            row.reasons.push('No terminal activity or matching transcript metadata was available.');
+    }
+    const browserRoots = browserCandidates.filter(value => !(0, classify_1.hasAncestor)(value.pid, new Set(browserCandidates.map(item => item.pid)), processByPid));
+    const browserPids = new Set(browserRoots.flatMap(root => (0, classify_1.descendants)(root.pid, processes).map(value => value.pid)));
+    const normalBrowserPids = new Set(processes.filter(value => (0, classify_1.isChromeProcess)(value.command) && !browserPids.has(value.pid))
+        .flatMap(root => (0, classify_1.descendants)(root.pid, processes).map(value => value.pid)));
+    const qualifiedDaemons = new Map();
+    for (const candidate of daemonCandidates) {
+        if (!alive())
+            break;
+        const source = (0, classify_1.daemonPath)(candidate.command), sourceExists = source ? await existence(source) : null;
+        const cwdExists = candidate.cwd ? await existence(candidate.cwd) : null;
+        let marker = false;
+        if (source) {
+            let directory = (0, node_path_1.dirname)(source);
+            for (let depth = 0; depth < 8 && alive(); depth++) {
+                if (await stat((0, node_path_1.join)(directory, '.git'))) {
+                    marker = true;
+                    break;
+                }
+                const parent = (0, node_path_1.dirname)(directory);
+                if (parent === directory)
+                    break;
+                directory = parent;
+            }
+        }
+        const sourceRegistration = source && sourceExists ? await registered((0, node_path_1.dirname)(source)) : null;
+        const temporary = (0, classify_1.isTemporary)(source) || (0, classify_1.isTemporary)(candidate.cwd);
+        const missing = sourceExists === false || cwdExists === false;
+        const unregistered = sourceRegistration === false && (marker || temporary);
+        if (temporary || missing || unregistered)
+            qualifiedDaemons.set(candidate.pid, { orphan: missing || unregistered,
+                reason: missing ? 'Daemon script or working directory no longer exists.' : unregistered ? 'Daemon script is outside the registered git worktrees.' : 'Daemon script or working directory is temporary; registration was not disproven.' });
+    }
+    const daemonRoots = daemonCandidates.filter(value => qualifiedDaemons.has(value.pid) && !(0, classify_1.hasAncestor)(value.pid, new Set(qualifiedDaemons.keys()), processByPid));
+    const daemonPids = new Set(daemonRoots.flatMap(root => (0, classify_1.descendants)(root.pid, processes).map(value => value.pid)));
+    const rootCandidates = [...browserRoots, ...daemonRoots,
+        ...sessionCandidates.filter(value => !(0, classify_1.hasAncestor)(value.pid, new Set(sessionCandidates.map(item => item.pid)), processByPid))];
+    const claimed = new Set();
+    const windows = platform === 'darwin' && browserPids.size && alive() ? await (0, platform_1.browserWindows)([...browserPids], runner, { ...commandOptions(), timeoutMs: options.commandTimeoutMs ?? 5000 }) : null;
+    if (browserPids.size && windows === null)
+        skipped.push('Automation browser window counts are unavailable; no accessibility or remote debugging connection was attempted.');
+    for (const process of rootCandidates) {
+        if (!alive())
+            break;
+        if (claimed.has(process.pid) || normalBrowserPids.has(process.pid))
+            continue;
+        const browser = browserRoots.some(value => value.pid === process.pid), host = (0, classify_1.agentHost)(process.command);
+        const kind = browser ? 'browser' : host ? 'session' : 'daemon';
+        const group = (0, classify_1.descendants)(process.pid, processes).filter(value => !normalBrowserPids.has(value.pid) && !claimed.has(value.pid) && (browser || (!browserPids.has(value.pid) && (daemonRoots.some(root => root.pid === process.pid) || !daemonPids.has(value.pid)))));
+        group.forEach(value => claimed.add(value.pid));
+        const row = blankRow(kind, `${kind}:${process.pid}:${process.startedAt || 'unknown'}`, browser ? 'Automation browser' : host ? `${host} session` : 'Plugin or hook daemon');
+        row.pid = process.pid;
+        row.pids = group.map(value => value.pid);
+        row.processes = group;
+        row.host = host;
+        row.cwd = process.cwd;
+        row.uptimeSeconds = process.uptimeSeconds;
+        row.rssBytes = group.reduce((sum, value) => sum + value.rssBytes, 0);
+        const groupDirty = await Promise.all([...new Set(group.map(value => value.cwd))].map(dirty));
+        row.dirty = groupDirty.some(value => value === true) ? true : groupDirty.some(value => value === null) ? null : false;
+        await idle(row);
+        if (browser) {
+            row.windows = windows ? group.reduce((sum, value) => sum + (windows.get(value.pid) || 0), 0) : null;
+            const profile = (0, classify_1.browserProfile)(process.command);
+            if (row.idleSeconds === null && profile) {
+                const modified = await newest(profile);
+                if (modified !== null && modified <= now) {
+                    row.idleSeconds = (now - modified) / 1000;
+                    row.idleMethod = 'profile';
+                    row.reasons.push('Idle uses automation profile modification time, not browser interaction.');
+                }
+            }
+            row.warn = row.idleSeconds !== null && row.idleSeconds >= thresholds.idle_browser_warn_minutes * 60;
+        }
+        else {
+            if (kind === 'daemon') {
+                const evidence = qualifiedDaemons.get(process.pid);
+                row.orphan = evidence?.orphan || false;
+                if (evidence)
+                    row.reasons.push(evidence.reason);
+            }
+            row.warn = row.orphan || (row.idleSeconds !== null && row.idleSeconds >= thresholds.idle_session_warn_hours * 3600);
+        }
+        if (row.dirty === null)
+            row.reasons.push('Git working-directory state is unknown.');
+        if (!process.startedAt)
+            row.reasons.push('Stable process start identity is unavailable.');
+        if (row.idleSeconds === null)
+            row.reasons.push('Activity is unknown; elapsed process lifetime is not evidence of idleness.');
+        rows.push(row);
+    }
+    for (const workspace of workspacePaths) {
+        if (!alive()) {
+            const row = blankRow('workspace', `workspace:${workspace}`, (0, node_path_1.basename)(workspace));
+            row.cwd = workspace;
+            row.reasons.push('Audit budget ended before workspace evidence could be collected.');
+            rows.push(row);
+            continue;
+        }
+        scanned = 0;
+        const row = blankRow('workspace', `workspace:${workspace}`, (0, node_path_1.basename)(workspace));
+        row.cwd = workspace;
+        const facts = await directoryFacts(workspace);
+        if (facts) {
+            row.sizeBytes = facts.size;
+            row.modifiedAt = new Date(facts.newest).toISOString();
+            row.idleSeconds = facts.newest <= now ? (now - facts.newest) / 1000 : null;
+        }
+        else {
+            const size = await run('du', ['-sk', workspace]);
+            const match = /^(\d+)\s/.exec(size.stdout);
+            if (size.code === 0 && match)
+                row.sizeBytes = Number(match[1]) * 1024;
+            const directory = await stat(workspace);
+            if (directory)
+                row.modifiedAt = new Date(directory.mtimeMs).toISOString();
+            row.reasons.push('Workspace modification time is directory metadata only because the bounded scan could not finish; it is not idle evidence.');
+            if (row.sizeBytes === null)
+                row.reasons.push('Workspace size is unavailable.');
+        }
+        row.dirty = await dirty(workspace);
+        row.openHandles = await openHandles(workspace);
+        const registration = await registered(workspace), liveOwner = processes.some(process => process.cwd && (0, classify_1.inside)(process.cwd, workspace));
+        row.orphan = registration === false && !liveOwner && row.openHandles === false;
+        row.reasons.push(registration === true ? 'Workspace is present in git worktree registrations.' : registration === false ? 'Workspace is absent from git worktree registrations.' : 'Git worktree registration could not be verified.');
+        if (row.openHandles === null)
+            row.reasons.push('Open handles could not be verified.');
+        row.warn = row.orphan && row.idleSeconds !== null && row.idleSeconds >= thresholds.orphan_workspace_warn_days * 86400;
+        rows.push(row);
+    }
+    if (roots.length && (rows.some(row => row.kind === 'workspace' && (row.sizeBytes === null || row.openHandles === null || row.reasons.some(reason => reason.includes('could not be verified'))))
+        || skipped.some(reason => /limit|budget|canceled|discovery is incomplete/.test(reason)))) {
+        skipped.push('Workspace totals are lower bounds over measured, proven orphans; incomplete or inaccessible directories are not counted as zero-sized.');
+    }
+    return { version: 1, generatedAt: new Date(now).toISOString(), platform, rows, processes, swapUsedBytes, skipped: [...new Set(skipped)], thresholds,
+        totals: { idleAgentMemoryBytes: rows.filter(row => row.kind === 'session' && row.warn).reduce((sum, row) => sum + row.rssBytes, 0),
+            orphanWorkspaceBytes: rows.filter(row => row.kind === 'workspace' && row.orphan).reduce((sum, row) => sum + (row.sizeBytes || 0), 0) } };
+}

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

@@ -0,0 +1,17 @@
+/** An advisory SessionStart check. It never denies or signals an audited PID. */
+import type { Policy } from '../types';
+import type { AuditReport, AuditRow, AuditThresholds } from './types';
+export declare const SESSION_START_AUDIT_BUDGET_MS = 150;
+export type CollectIdleAudit = (options: {
+    signal: AbortSignal;
+    thresholds: AuditThresholds;
+}) => Promise<AuditReport>;
+export declare function rowPastThreshold(row: AuditRow, thresholds: AuditThresholds, now: number): boolean;
+export declare function warningForAudit(report: AuditReport, policy: Policy, now?: number): string | null;
+export declare function sessionStartWarning(home: string, policy: Policy, now?: number): string | null;
+export declare function sessionStartCheck(home: string, options: {
+    collect: CollectIdleAudit;
+    policy?: Policy;
+    now?: number;
+    budgetMs?: number;
+}): Promise<string | null>;

package/dist/src/idle/hook.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SESSION_START_AUDIT_BUDGET_MS = void 0;
+exports.rowPastThreshold = rowPastThreshold;
+exports.warningForAudit = warningForAudit;
+exports.sessionStartWarning = sessionStartWarning;
+exports.sessionStartCheck = sessionStartCheck;
+const policy_1 = require("../policy");
+const cache_1 = require("./cache");
+exports.SESSION_START_AUDIT_BUDGET_MS = 150;
+function rowPastThreshold(row, thresholds, now) {
+    if (row.kind === 'workspace') {
+        // A root directory timestamp can be shown when deeper scans were skipped.
+        // Only completed activity evidence may warn; a displayed date is not enough.
+        return row.orphan && row.idleSeconds !== null && Number.isFinite(row.idleSeconds)
+            && row.idleSeconds >= thresholds.orphan_workspace_warn_days * 86400;
+    }
+    if (row.idleSeconds === null || !Number.isFinite(row.idleSeconds))
+        return false;
+    return row.idleSeconds >= (row.kind === 'browser' ? thresholds.idle_browser_warn_minutes * 60 : thresholds.idle_session_warn_hours * 3600);
+}
+function warningForAudit(report, policy, now = Date.now()) {
+    const thresholds = (0, cache_1.auditThresholds)(policy);
+    const warnings = report.rows.filter(row => rowPastThreshold(row, thresholds, Date.parse(report.generatedAt)));
+    if (!warnings.length)
+        return null;
+    const sessions = warnings.filter(row => row.kind === 'session');
+    const gb = sessions.reduce((sum, row) => sum + row.rssBytes, 0) / 1_000_000_000;
+    return `${sessions.length} idle agent sessions holding ${gb.toFixed(1)} GB, run agentguard-burn ps`;
+}
+function sessionStartWarning(home, policy, now = Date.now()) {
+    const report = (0, cache_1.readAuditCache)(home, now);
+    return report ? warningForAudit(report, policy, now) : null;
+}
+async function sessionStartCheck(home, options) {
+    const started = performance.now(), now = options.now ?? Date.now(), policy = options.policy ?? (0, policy_1.loadPolicy)(home);
+    const cached = (0, cache_1.readAuditCache)(home, now);
+    if (cached)
+        return warningForAudit(cached, policy, now);
+    const budget = Math.max(1, Math.min(exports.SESSION_START_AUDIT_BUDGET_MS, options.budgetMs ?? exports.SESSION_START_AUDIT_BUDGET_MS));
+    const remaining = budget - (performance.now() - started);
+    if (remaining <= 0)
+        return null;
+    const controller = new AbortController();
+    let timer;
+    const timeout = new Promise(resolve => { timer = setTimeout(() => { controller.abort(); resolve(null); }, remaining); });
+    try {
+        const report = await Promise.race([Promise.resolve().then(() => options.collect({ signal: controller.signal, thresholds: (0, cache_1.auditThresholds)(policy) })), timeout]);
+        if (!report || controller.signal.aborted || performance.now() - started >= budget)
+            return null;
+        (0, cache_1.writeAuditCache)(home, report);
+        return performance.now() - started < budget ? warningForAudit(report, policy, now) : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+        controller.abort();
+    }
+}

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

@@ -0,0 +1,25 @@
+import type { ProcessSnapshot } from './types';
+export interface CommandResult {
+    stdout: string;
+    stderr?: string;
+    code: number;
+}
+export interface CommandOptions {
+    cwd?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    maxBuffer?: number;
+}
+export type CommandRunner = (command: string, args: string[], options?: CommandOptions) => Promise<CommandResult>;
+export declare const runLocal: CommandRunner;
+export declare function elapsedSeconds(text: string): number | null;
+/** lstart is retained verbatim as an OS identity, never reconstructed from elapsed time. */
+export declare function parsePs(text: string): ProcessSnapshot[];
+export declare function parseLsofCwds(text: string): Map<number, string>;
+export declare function parseWorktrees(text: string): string[];
+export declare function parseSwap(text: string, platform: string): number | null;
+export declare function parseProcStat(text: string, command: string, bootId: string, ticks: number, now: number, uptime: number): ProcessSnapshot | null;
+/** Linux fallback reads proc metadata only. cmdline is process identity, never transcript content. */
+export declare function procProcesses(root: string, runner: CommandRunner, signal: AbortSignal | undefined, limit: number, skipped: string[]): Promise<ProcessSnapshot[]>;
+/** CoreGraphics reads local window metadata without Apple Events or accessibility control. */
+export declare function browserWindows(pids: number[], runner: CommandRunner, options: CommandOptions): Promise<Map<number, number> | null>;