export type ProcessTableRow = { pid: number ppid: number /** Process group id. Optional only on rows produced by the legacy parser input shape. */ pgid?: number /** Terminal foreground process group id (`0`/`-1` means no controlling tty). */ tpgid?: number /** Controlling terminal name, when the host process table provides it. */ tty?: string /** Opaque host process start marker (Linux /proc ticks or host ps marker). */ startTime?: string stat: string command: string } // Guard process at module load: sandboxed renderers import this half and a bare read would crash the chunk/app. const HOST_IS_DARWIN = typeof process !== 'undefined' && process.platform === 'darwin' /** Columns used by the evidence reader. Keep command last so its spaces survive parsing. */ export const PS_ARGS = ( HOST_IS_DARWIN ? ['-axo', 'pid=,ppid=,pgid=,tpgid=,stat=,tty=,lstart=,command='] : ['-axo', 'pid=,ppid=,pgid=,tpgid=,stat=,tty=,etimes=,command='] ) as readonly string[] /** Cheap tier proves unchanged subtrees, never process names. Drop costly macOS tty (0.29/0.34s at 1,900 processes) * and Linux argv (1.15s); omit ticking etimes and read stable /proc starts for the pane subtree. */ export const CHEAP_PS_ARGS = ( HOST_IS_DARWIN ? ['-axo', 'pid=,ppid=,pgid=,tpgid=,stat=,lstart='] : ['-axo', 'pid=,ppid=,pgid=,tpgid=,stat='] ) as readonly string[] /** Shell-proof tier keeps job control/argv, dropping costly unused tty/start columns; enough to name foreground processes, * never correlate reused PIDs across captures. */ export const SHELL_FOREGROUND_PS_ARGS = [ '-axo', 'pid=,ppid=,pgid=,tpgid=,stat=,command=' ] as readonly string[] /** The name inside ps's `(comm)`, printed when argv was unreadable (another user's process, an exiting one, or a * recovery the fork budget withheld): its identity is unknown, so it never proves which program holds a terminal. */ export function unreadableArgvName(command: string): string | null { return /^\((.*)\)$/.exec(command.trim())?.[1] ?? null } /** Match shell-tier columns exactly: the full parser’s optional tty/start pair eats argv like python 3 app.py and misreads zombies. * Drop invalid rows, but reject empty captures so missing data cannot prove the shell exited. */ export function parseShellForegroundRows( stdout: string, options?: { strict?: boolean } ): ProcessTableRow[] { const rows: ProcessTableRow[] = [] for (const rawLine of stdout.split(/\r?\n/)) { // Strict keeps a blank-argv row: one process outside the foreground cannot void the capture, and readers // treat a blank foreground member as unreadable. const match = rawLine .trim() .match( options?.strict ? /^(\d+)\s+(\d+)\s+(-?\d+)\s+(-?\d+)\s+(\S+)(?:\s+(.+))?$/ : /^(\d+)\s+(\d+)\s+(-?\d+)\s+(-?\d+)\s+(\S+)\s+(.+)$/ ) const pid = match ? Number(match[1]) : 0 if ( options?.strict && rawLine.trim() && (!match || !Number.isSafeInteger(pid) || pid <= 0 || ![2, 3, 4].every((i) => Number.isSafeInteger(Number(match[i]))) || Number(match[2]) < 0 || Number(match[3]) < 0 || Number(match[4]) < -1) ) { throw new ProcessTableCaptureError('malformed_row') } if (match && Number.isSafeInteger(pid) && pid > 0) { rows.push({ pid, ppid: Number(match[2]), pgid: Number(match[3]), tpgid: Number(match[4]), stat: match[5], command: match[6] ?? '' }) } } if (rows.length === 0) { throw new ProcessTableCaptureError('empty_capture') } return rows } export type CheapProcessTableRow = { pid: number ppid: number pgid: number tpgid: number stat: string /** Host start marker when the column set carries one (macOS `lstart`). */ startTime?: string } /** Lenient cheap rows only make fingerprints differ and trigger strict capture; empty still means unreadable, never no processes. */ export function parseCheapProcessTableRows(stdout: string): CheapProcessTableRow[] { const rows: CheapProcessTableRow[] = [] for (const rawLine of stdout.split(/\r?\n/)) { const match = rawLine.trim().match(/^(\d+)\s+(\d+)\s+(-?\d+)\s+(-?\d+)\s+(\S+)(?:\s+(.+?))?$/) if (!match) { continue } const pid = Number(match[1]) if (!Number.isSafeInteger(pid) || pid <= 0) { continue } rows.push({ pid, ppid: Number(match[2]), pgid: Number(match[3]), tpgid: Number(match[4]), stat: match[5], ...(match[6] !== undefined ? { startTime: match[6] } : {}) }) } if (rows.length === 0) { throw new ProcessTableCaptureError('empty_capture') } return rows } // Node’s 1MB default overflows busy captures (~326KB/1,460 rows; 5KB argv is ordinary), making all reads unverifiable. // Match pty-descendant-termination.ts’s 32MB ceiling. export const PS_MAX_BUFFER_BYTES = 32 * 1024 * 1024 /** TTL beyond capture duration; reported age includes both. Renderer cadence also needs this bound, * so keep it out of the node:child_process reader graph. */ export const PROCESS_TABLE_SNAPSHOT_MAX_STALENESS_MS = 500 /** Parse legacy/evidence ps rows with CRLF tolerance; anchored greedy final command preserves internal spaces. */ export function parseProcessTableRows(stdout: string): ProcessTableRow[] { const rows: ProcessTableRow[] = [] for (const line of stdout.split(/\r?\n/)) { const trimmed = line.trim() const macStartMatch = trimmed.match( /^(\d+)\s+(\d+)\s+(-?\d+)\s+(-?\d+)\s+(\S+)\s+(\S+)\s+(\S+\s+\S+\s+\d{1,2}\s+\S+\s+\d{4})\s+(.+)$/ ) if (macStartMatch) { rows.push({ pid: Number(macStartMatch[1]), ppid: Number(macStartMatch[2]), pgid: Number(macStartMatch[3]), tpgid: Number(macStartMatch[4]), stat: macStartMatch[5], tty: macStartMatch[6], startTime: macStartMatch[7], command: macStartMatch[8] }) continue } const evidenceMatch = trimmed.match( /^(\d+)\s+(\d+)\s+(?:(-?\d+)\s+(-?\d+)\s+)?(\S+)(?:\s+(\S+)\s+(\d+))?\s+(.+)$/ ) if (evidenceMatch) { rows.push({ pid: Number(evidenceMatch[1]), ppid: Number(evidenceMatch[2]), ...(evidenceMatch[3] !== undefined ? { pgid: Number(evidenceMatch[3]), tpgid: Number(evidenceMatch[4]) } : {}), stat: evidenceMatch[5] ?? evidenceMatch[3], ...(evidenceMatch[7] !== undefined ? { tty: evidenceMatch[6], startTime: evidenceMatch[7] } : {}), command: evidenceMatch[8] ?? evidenceMatch[6] ?? evidenceMatch[4] } as ProcessTableRow) continue } const legacyMatch = trimmed.match( /^((?:\d+)\s+(?:\d+)\s+)(?:(-?\d+)\s+(-?\d+)\s+)?(\S+)\s+(.+)$/ ) if (legacyMatch) { rows.push({ pid: Number(legacyMatch[1].trim().split(/\s+/)[0]), ppid: Number(legacyMatch[1].trim().split(/\s+/)[1]), ...(legacyMatch[2] !== undefined ? { pgid: Number(legacyMatch[2]), tpgid: Number(legacyMatch[3]) } : {}), stat: legacyMatch[4], command: legacyMatch[5] } as ProcessTableRow) } } return rows } export class ProcessTableCaptureError extends Error { readonly code = 'process_table_unreadable' constructor(readonly reason: string) { super(`process table unreadable: ${reason}`) this.name = 'ProcessTableCaptureError' } } /** Require every nonframing row: silently dropping truncation could falsely prove no agent. Accept kernel/TTY sentinels * ppid/pgid=0 and tpgid=-1/0; reject pid<=0, negative ppid/pgid or tpgid<-1. Empty/header-only captures are unreadable. */ export function parseStrictProcessTableRows(stdout: string): ProcessTableRow[] { const rows: ProcessTableRow[] = [] for (const rawLine of stdout.split(/\r?\n/)) { const line = rawLine.trim() if (!line) { continue } if (/^PID\s+PPID\s+PGID\s+TPGID\s+STAT\s+COMMAND$/i.test(line)) { continue } const macStartMatch = line.match( /^(\d+)\s+(\d+)\s+(-?\d+)\s+(-?\d+)\s+(\S+)\s+(\S+)\s+(\S+\s+\S+\s+\d{1,2}\s+\S+\s+\d{4})\s+(.+)$/ ) const numericMatch = macStartMatch ? null : line.match(/^(\d+)\s+(\d+)\s+(-?\d+)\s+(-?\d+)\s+(\S+)(?:\s+(\S+)\s+(\d+))?\s+(.+)$/) if (!numericMatch && !macStartMatch) { throw new ProcessTableCaptureError('malformed_row') } const match = numericMatch ?? macStartMatch! const pid = Number(match[1]) const ppid = Number(match[2]) const pgid = Number(match[3]) const tpgid = Number(match[4]) if ( !Number.isSafeInteger(pid) || pid <= 0 || !Number.isSafeInteger(ppid) || ppid < 0 || !Number.isSafeInteger(pgid) || pgid < 0 || !Number.isSafeInteger(tpgid) || (tpgid < 0 && tpgid !== -1) || (match[8] ?? match[6]).length === 0 ) { throw new ProcessTableCaptureError('invalid_numeric_field') } rows.push({ pid, ppid, pgid, tpgid, stat: match[5], ...(numericMatch && match[7] !== undefined ? { tty: match[6], startTime: match[7] } : macStartMatch ? { tty: match[6], startTime: match[7] } : {}), command: numericMatch ? (match[8] ?? match[6]) : match[8] }) } if (rows.length === 0) { throw new ProcessTableCaptureError('empty_capture') } return rows }