@hearsay-tools/squawk 0.0.0-stage → 0.17.0-dev.5682

package/dist/core/runner-stderr.js

@@ -0,0 +1,20 @@
+import { stripVTControlCharacters } from 'node:util';
+/** Keep the exception, not Node's stack/property tail and runtime footer (#499). */
+export function summarizeRunnerStderr(stderr) {
+    const lines = stripVTControlCharacters(stderr)
+        .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/gu, ' ')
+        .split(/\r?\n/)
+        .map(line => line.trimEnd())
+        .filter(line => line.trim() && !/^Node\.js v\d+\./.test(line.trim()));
+    // Select the latest outer exception. Indentation distinguishes nested causes
+    // and multiline error properties from a later top-level fatal diagnostic.
+    const headers = lines.filter(line => /^(?:[\w.$]*(?:Error|Exception)|error|fatal(?: error)?)(?:\s+\[[^\]]+\])?:\s*\S/i.test(line.trimStart()));
+    const indent = (line) => line.length - line.trimStart().length;
+    const outerIndent = headers.reduce((min, line) => Math.min(min, indent(line)), Infinity);
+    const exception = headers.filter(line => indent(line) === outerIndent).at(-1)?.trim();
+    const summary = exception ?? lines.map(line => line.trim()).filter(line => !/^at\s/.test(line) && !/^[{}[\]]+$/.test(line)).slice(-3).join(' | ');
+    if (summary.length <= 500)
+        return summary;
+    return exception ? `${summary.slice(0, 499)}…` : `…${summary.slice(-499)}`;
+}
+//# sourceMappingURL=runner-stderr.js.map

package/dist/core/runner-stderr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner-stderr.js","sourceRoot":"","sources":["../../src/core/runner-stderr.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAErD,oFAAoF;AACpF,MAAM,UAAU,qBAAqB,CAAC,MAAc;IAClD,MAAM,KAAK,GAAG,wBAAwB,CAAC,MAAM,CAAC;SAC3C,OAAO,CAAC,kDAAkD,EAAE,GAAG,CAAC;SAChE,KAAK,CAAC,OAAO,CAAC;SACd,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;SAC3B,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACxE,6EAA6E;IAC7E,0EAA0E;IAC1E,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,iFAAiF,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;IAC/I,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC;IACvE,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IACzF,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;IACtF,MAAM,OAAO,GAAG,SAAS,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClJ,IAAI,OAAO,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,OAAO,CAAC;IAC1C,OAAO,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;AAC7E,CAAC"}

package/dist/core/runner-tool-grants.d.ts

@@ -0,0 +1,19 @@
+import { type ToolGrant } from './agent-runner.ts';
+/**
+ * How each runner without a tool-list builder of its own maps a `ToolGrant` onto its wire
+ * (hearsay-tools/cezarion#1810). One exhaustive switch per runner, so a new grant kind fails to
+ * compile until every runner decides what it sends. Claude and pi keep their switches beside
+ * the builders they call.
+ */
+/** The thread fields each grant kind adds: none, since the app-server has no per-tool allowlist. */
+export declare function codexToolGrantFields(grant: ToolGrant): Record<never, never>;
+/** The session fields each grant kind adds: none, since OpenCode's own permission config governs tools. */
+export declare function opencodeToolGrantFields(grant: ToolGrant): Record<never, never>;
+/** The print flags each grant kind adds: none. Only D1 sends `--allowed-tools`, from the capability list. */
+export declare function cursorPrintToolGrantArgs(grant: ToolGrant): string[];
+/**
+ * The names a grant asks OMP for, or undefined for OMP's own default set. That set includes
+ * unrestricted bash, so a bash allowlist has to name a list (`defaults`, OMP's default set) to
+ * leave it out.
+ */
+export declare function ompRequestedTools(grant: ToolGrant, defaults: readonly string[]): readonly string[] | undefined;

package/dist/core/runner-tool-grants.js

@@ -0,0 +1,54 @@
+import { unknownToolGrant } from './agent-runner.js';
+/**
+ * How each runner without a tool-list builder of its own maps a `ToolGrant` onto its wire
+ * (hearsay-tools/cezarion#1810). One exhaustive switch per runner, so a new grant kind fails to
+ * compile until every runner decides what it sends. Claude and pi keep their switches beside
+ * the builders they call.
+ */
+/** The thread fields each grant kind adds: none, since the app-server has no per-tool allowlist. */
+export function codexToolGrantFields(grant) {
+    switch (grant.kind) {
+        case 'unset':
+        case 'step-default':
+        case 'inherited':
+        case 'explicit': return {};
+        default: return unknownToolGrant(grant);
+    }
+}
+/** The session fields each grant kind adds: none, since OpenCode's own permission config governs tools. */
+export function opencodeToolGrantFields(grant) {
+    switch (grant.kind) {
+        case 'unset':
+        case 'step-default':
+        case 'inherited':
+        case 'explicit': return {};
+        default: return unknownToolGrant(grant);
+    }
+}
+/** The print flags each grant kind adds: none. Only D1 sends `--allowed-tools`, from the capability list. */
+export function cursorPrintToolGrantArgs(grant) {
+    switch (grant.kind) {
+        case 'unset':
+        case 'step-default':
+        case 'inherited':
+        case 'explicit': return [];
+        default: return unknownToolGrant(grant);
+    }
+}
+/**
+ * The names a grant asks OMP for, or undefined for OMP's own default set. That set includes
+ * unrestricted bash, so a bash allowlist has to name a list (`defaults`, OMP's default set) to
+ * leave it out.
+ */
+export function ompRequestedTools(grant, defaults) {
+    switch (grant.kind) {
+        case 'unset': return (grant.bashAllowlist?.length ?? 0) > 0 ? defaults : undefined;
+        case 'step-default':
+        case 'inherited': return grant.tools;
+        // `--tools` filters OMP's built-ins only, so a narrowed list leaves every MCP and extension
+        // tool callable (hearsay-tools/cezarion#1357).
+        case 'explicit': return grant.tools;
+        default: return unknownToolGrant(grant);
+    }
+}
+//# sourceMappingURL=runner-tool-grants.js.map

package/dist/core/runner-tool-grants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner-tool-grants.js","sourceRoot":"","sources":["../../src/core/runner-tool-grants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAkB,MAAM,mBAAmB,CAAC;AAErE;;;;;GAKG;AAEH,oGAAoG;AACpG,MAAM,UAAU,oBAAoB,CAAC,KAAgB;IACnD,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,OAAO,CAAC;QACb,KAAK,cAAc,CAAC;QACpB,KAAK,WAAW,CAAC;QACjB,KAAK,UAAU,EAAE,OAAO,EAAE,CAAC;QAC3B,SAAS,OAAO,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAC1C,CAAC;AACH,CAAC;AAED,2GAA2G;AAC3G,MAAM,UAAU,uBAAuB,CAAC,KAAgB;IACtD,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,OAAO,CAAC;QACb,KAAK,cAAc,CAAC;QACpB,KAAK,WAAW,CAAC;QACjB,KAAK,UAAU,EAAE,OAAO,EAAE,CAAC;QAC3B,SAAS,OAAO,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAC1C,CAAC;AACH,CAAC;AAED,6GAA6G;AAC7G,MAAM,UAAU,wBAAwB,CAAC,KAAgB;IACvD,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,OAAO,CAAC;QACb,KAAK,cAAc,CAAC;QACpB,KAAK,WAAW,CAAC;QACjB,KAAK,UAAU,EAAE,OAAO,EAAE,CAAC;QAC3B,SAAS,OAAO,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAC1C,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAgB,EAChB,QAA2B;IAE3B,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,aAAa,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;QACnF,KAAK,cAAc,CAAC;QACpB,KAAK,WAAW,EAAE,OAAO,KAAK,CAAC,KAAK,CAAC;QACrC,4FAA4F;QAC5F,+CAA+C;QAC/C,KAAK,UAAU,EAAE,OAAO,KAAK,CAAC,KAAK,CAAC;QACpC,SAAS,OAAO,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAC1C,CAAC;AACH,CAAC"}

package/dist/core/secret-redaction.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Best-effort transcript credential redaction by known environment values and token patterns.
+ * Enabled by default; CEZ_REDACT_SECRETS=0 opts out.
+ */
+export declare const REDACTED = "[REDACTED]";
+/**
+ * Shared credential-name rule for environment curation and value collection for redaction.
+ */
+export declare const SECRET_NAME_RE: RegExp;
+/** Collect the concrete secret values present in `env` (deduped, longest
+ *  first so a value that contains another is replaced whole). */
+export declare function collectSecretValues(env?: NodeJS.ProcessEnv): string[];
+/** Replace every known secret value / token shape in `text` with `[REDACTED]`. */
+export declare function redactSecrets(text: string, secretValues: readonly string[]): string;
+/**
+ * Deep-copy `value`, redacting every string leaf. Structure/keys are
+ * preserved; only string values (and string keys are left untouched — keys are
+ * event field names, never secrets) are scrubbed.
+ */
+export declare function redactDeep<T>(value: T, secretValues: readonly string[]): T;

package/dist/core/secret-redaction.js

@@ -0,0 +1,95 @@
+/**
+ * Best-effort transcript credential redaction by known environment values and token patterns.
+ * Enabled by default; CEZ_REDACT_SECRETS=0 opts out.
+ */
+export const REDACTED = '[REDACTED]';
+/**
+ * Shared credential-name rule for environment curation and value collection for redaction.
+ */
+export const SECRET_NAME_RE = /(TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|_KEY$|_KEY_|APIKEY|API_KEY|PRIVATE_KEY|ACCESS_KEY|_AUTH$|_AUTH_|SESSION|COOKIE|PASSPHRASE)/i;
+/** Names matched above whose value is NOT a secret (a socket path, a pid, a
+ *  desktop-session id) — collecting them would scrub ordinary paths from the
+ *  transcript for no benefit. */
+const SECRET_VALUE_NAME_ALLOW = new Set([
+    'SSH_AUTH_SOCK',
+    'SSH_AGENT_PID',
+    'SESSION_MANAGER',
+    'SESSIONNAME',
+    'XDG_SESSION_ID',
+    'XDG_SESSION_TYPE',
+    'XDG_SESSION_CLASS',
+    'XDG_SESSION_DESKTOP',
+]);
+/**
+ * Below this length a "secret" value is too common a word to redact safely.
+ * Verified over-redaction at the old floor of 8 (#427 review): a dev box with
+ * `POSTGRES_PASSWORD=postgres` turned `apt install postgresql-16` into
+ * `apt install [REDACTED]ql-16` in the transcript. Real credentials (API keys,
+ * PATs, AWS secrets) are 20+ chars, so 12 keeps the catch rate while putting
+ * short dictionary words — the whole source of false positives — out of reach.
+ * Pattern-based redaction below is unaffected: it matches token *shapes*, not
+ * env values, and still catches short-but-real tokens.
+ */
+const MIN_SECRET_LEN = 12;
+/** Well-known credential shapes, independent of the host env. */
+const TOKEN_PATTERNS = [
+    /gh[pousr]_[A-Za-z0-9]{20,}/g, // GitHub PAT / OAuth / server / user / refresh
+    /github_pat_[A-Za-z0-9_]{20,}/g, // GitHub fine-grained PAT
+    /sk-ant-[A-Za-z0-9-_]{20,}/g, // Anthropic
+    /sk-[A-Za-z0-9-_]{20,}/g, // OpenAI & compatible
+    /AKIA[0-9A-Z]{16}/g, // AWS access key id
+    /ASIA[0-9A-Z]{16}/g, // AWS temporary access key id
+    /AIza[0-9A-Za-z_-]{35}/g, // Google API key
+    /ya29\.[0-9A-Za-z_-]+/g, // Google OAuth access token
+    /xox[baprs]-[0-9A-Za-z-]{10,}/g, // Slack
+    /glpat-[0-9A-Za-z_-]{20,}/g, // GitLab PAT
+];
+/** Collect the concrete secret values present in `env` (deduped, longest
+ *  first so a value that contains another is replaced whole). */
+export function collectSecretValues(env = process.env) {
+    const values = new Set();
+    for (const [name, value] of Object.entries(env)) {
+        if (!value || value.length < MIN_SECRET_LEN)
+            continue;
+        if (SECRET_VALUE_NAME_ALLOW.has(name.toUpperCase()))
+            continue;
+        if (SECRET_NAME_RE.test(name))
+            values.add(value);
+    }
+    return [...values].sort((a, b) => b.length - a.length);
+}
+/** Replace every known secret value / token shape in `text` with `[REDACTED]`. */
+export function redactSecrets(text, secretValues) {
+    let out = text;
+    for (const value of secretValues) {
+        if (!out.includes(value))
+            continue;
+        out = out.split(value).join(REDACTED);
+    }
+    for (const re of TOKEN_PATTERNS) {
+        out = out.replace(re, REDACTED);
+    }
+    return out;
+}
+/**
+ * Deep-copy `value`, redacting every string leaf. Structure/keys are
+ * preserved; only string values (and string keys are left untouched — keys are
+ * event field names, never secrets) are scrubbed.
+ */
+export function redactDeep(value, secretValues) {
+    if (typeof value === 'string') {
+        return redactSecrets(value, secretValues);
+    }
+    if (Array.isArray(value)) {
+        return value.map((v) => redactDeep(v, secretValues));
+    }
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = redactDeep(v, secretValues);
+        }
+        return out;
+    }
+    return value;
+}
+//# sourceMappingURL=secret-redaction.js.map

package/dist/core/secret-redaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-redaction.js","sourceRoot":"","sources":["../../src/core/secret-redaction.ts"],"names":[],"mappings":"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"}

package/dist/core/session-process.d.ts

@@ -0,0 +1,43 @@
+import { ChildProcess, type ChildProcessWithoutNullStreams } from 'node:child_process';
+/** A `/proc/<pid>/stat` line of a task that is exiting or already a zombie. Field 9 (`flags`)
+ * follows the last `)`, like every field after `comm`. An unparsable line reads as alive. */
+export declare function procStatExited(stat: string): boolean;
+/** A state sample permits cleanup attribution; it is not proof of signal causation. */
+export type LeaderState = 'exited' | 'live' | 'unknown';
+/** Fast evidence only. Failed probes never turn an unknown process into a live one. */
+export declare function leaderState(child: ChildProcess, platform?: NodeJS.Platform): LeaderState;
+/** Read one complete ps state; diagnostics, multiple states and unknown flags are not evidence. */
+export declare function psLeaderState(stdout: string, platform: NodeJS.Platform): LeaderState;
+/** Start fallback evidence within the last 50ms of an EXISTING grace. The caller takes
+ * the sample at its unchanged signal deadline; it never awaits ps. Taking the sample,
+ * or native exit, cancels the probe. A slow/missing ps keeps bounded cleanup, with unknown
+ * attribution. Windows has no state fallback. Signal 0 alone cannot distinguish zombies. */
+export declare function probeLeaderState(child: ChildProcess, graceMs: number, platform?: NodeJS.Platform): () => LeaderState;
+/** Let ordinary stdout EOF/exit ordering settle; collect fallback evidence in that same budget. */
+export declare function waitForEofExit(child: ChildProcess): Promise<LeaderState>;
+export declare function processGroupAlive(pgid: number): boolean;
+export declare function signalProcessGroup(pgid: number, signal: NodeJS.Signals): void;
+/** The process group a live process is in, for destroy's evidence that a recorded group is ours. */
+export declare function processGroupOf(pid: number): number | undefined;
+/** Spawn an agent session leader. Only a real detached `ChildProcess` with a pid is registered,
+ * so a test's fake child (made-up pid) never reaches `process.kill(-pid)`. Under the macOS desktop
+ * shell the leader starts through its trampoline, which execs in place (same pid and group). */
+export declare function spawnSessionLeader(bin: string, args: readonly string[], options: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}): ChildProcessWithoutNullStreams;
+/** Signal a session: its whole group on POSIX, its tree on win32, else the leader alone. A
+ * leader that already exited on its own is not group-signalled here: its exit scheduled the reap
+ * of what it left behind (hearsay-tools/cezarion#1286). */
+export declare function signalSession(child: ChildProcess, signal: NodeJS.Signals, platform?: NodeJS.Platform): void;
+/** Signal what a leader that already exited left in its group, under the reap's guard: Cursor
+ * print ends its group as each turn's leader exits, ahead of the exit drain. A SIGTERM is the reap
+ * itself, sent at most once per group; a SIGKILL goes only to a group that is still ours. */
+export declare function signalExitedSession(child: ChildProcess, signal: 'SIGTERM' | 'SIGKILL'): void;
+/** The pgid of a registered, still-running grouped leader, for the worker process ledger. */
+/** Whether `pid` leads a session this process spawned: an agent's own process, which a process
+ *  wait refuses because it ends only with the session (hearsay-tools/cezarion#1446). */
+export declare function isSessionLeader(pid: number): boolean;
+export declare function sessionGroupOf(pid: number): number | undefined;
+/** cezar's own SIGINT/SIGTERM, passed to every agent group that still has members. */
+export declare function forwardToSessionGroups(signal: NodeJS.Signals): void;

package/dist/core/session-process.js

@@ -0,0 +1,363 @@
+import { ChildProcess, execFile, spawn, spawnSync } from 'node:child_process';
+import { readdirSync, readFileSync } from 'node:fs';
+import { afterExitDrain, exitDrainBudget, KILL_GRACE_MS } from './runner-runtime.js';
+import { disclaimedCommand } from './disclaim-spawn.js';
+/** Grouped leaders this process spawned, keyed by pgid (= the leader's pid). */
+const leaders = new Map();
+/** Every child `spawnSessionLeader` returned, on any platform: win32's taskkill is for these only. */
+const spawned = new WeakSet();
+const exited = (child) => child.exitCode !== null || child.signalCode !== null;
+// include/linux/sched.h: set at the top of do_exit(), before exit_files() closes the sockets.
+const PF_EXITING = 0x4;
+/** A `/proc/<pid>/stat` line of a task that is exiting or already a zombie. Field 9 (`flags`)
+ * follows the last `)`, like every field after `comm`. An unparsable line reads as alive. */
+export function procStatExited(stat) {
+    const fields = stat.slice(stat.lastIndexOf(')') + 1).trim().split(/\s+/);
+    if (!stat.includes(')') || fields.length < 7 || !/^\d+$/.test(fields[6]))
+        return false;
+    return fields[0] === 'Z' || (Number(fields[6]) & PF_EXITING) !== 0;
+}
+/** Exiting, exited, or a zombie Node has not reaped yet. A crashed leader closes its sockets
+ * inside do_exit(), before it is a zombie: OpenCode sees its prompt's ACK drop and stops the
+ * session in that window, so a zombie check alone races (harness row S19). */
+function leaderExited(child) {
+    if (exited(child))
+        return true;
+    const pid = child.pid;
+    if (process.platform === 'linux') {
+        try {
+            return procStatExited(readFileSync(`/proc/${pid}/stat`, 'utf8'));
+        }
+        catch {
+            return true;
+        }
+    }
+    if (process.platform !== 'darwin')
+        return false;
+    // `ps` STAT: Z is a zombie, E a process trying to exit.
+    const ps = spawnSync('ps', ['-o', 'stat=', '-p', String(pid)], { encoding: 'utf8', timeout: 2_000 });
+    return ps.status === 0 ? /^Z|E/.test(ps.stdout.trim()) : ps.status === 1;
+}
+/** Fast evidence only. Failed probes never turn an unknown process into a live one. */
+export function leaderState(child, platform = process.platform) {
+    if (exited(child))
+        return 'exited';
+    const pid = child.pid;
+    if (pid === undefined || !groupId(pid))
+        return 'unknown';
+    try {
+        process.kill(pid, 0);
+    }
+    catch (error) {
+        if (error.code === 'ESRCH')
+            return 'exited';
+    }
+    if (platform !== 'linux')
+        return 'unknown';
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+        const match = /^(\d+) \(.*\) ([RSDZTtXxKWPI]) (?:\S+ ){5}(\d+)(?: |$)/.exec(stat);
+        if (!match || Number(match[1]) !== pid || !Number.isSafeInteger(Number(match[3])))
+            return 'unknown';
+        return procStatExited(stat) || /^[Xx]$/.test(match[2]) ? 'exited' : 'live';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/** Read one complete ps state; diagnostics, multiple states and unknown flags are not evidence. */
+export function psLeaderState(stdout, platform) {
+    const state = stdout.trim();
+    const valid = platform === 'darwin' ? /^[RUSTIZE][+<>LNsXW]*$/ : /^[RSDZTtXxKWPI][<NLsl+]*$/;
+    if (!valid.test(state))
+        return 'unknown';
+    return /^[ZEXx]/.test(state) ? 'exited' : 'live';
+}
+/** Start fallback evidence within the last 50ms of an EXISTING grace. The caller takes
+ * the sample at its unchanged signal deadline; it never awaits ps. Taking the sample,
+ * or native exit, cancels the probe. A slow/missing ps keeps bounded cleanup, with unknown
+ * attribution. Windows has no state fallback. Signal 0 alone cannot distinguish zombies. */
+export function probeLeaderState(child, graceMs, platform = process.platform) {
+    let sampled = 'unknown';
+    let probe;
+    let stopped = false;
+    let launch;
+    const cancel = () => {
+        stopped = true;
+        clearTimeout(launch);
+        child.off('exit', cancel);
+        if (probe && !exited(probe))
+            probe.kill('SIGKILL');
+    };
+    const start = () => {
+        if (stopped || leaderState(child, platform) !== 'unknown' || !child.pid || !groupId(child.pid))
+            return;
+        if (platform !== 'linux' && platform !== 'darwin')
+            return;
+        try {
+            probe = execFile('ps', ['-o', 'stat=', '-p', String(child.pid)], {
+                encoding: 'utf8', timeout: Math.min(50, graceMs), killSignal: 'SIGKILL', maxBuffer: 128,
+            }, (error, stdout, stderr) => {
+                if (!stopped && !error && !stderr.trim())
+                    sampled = psLeaderState(stdout, platform);
+            });
+        }
+        catch { /* unknown; the signal deadline still owns cleanup */ }
+    };
+    child.once('exit', cancel);
+    if (graceMs <= 50)
+        start();
+    else {
+        launch = setTimeout(start, graceMs - 50);
+        launch.unref?.();
+    }
+    return () => {
+        cancel();
+        const current = leaderState(child, platform);
+        // A PID that changed state inconsistently is not positive evidence of liveness.
+        if (current === 'live' && sampled === 'exited')
+            return 'unknown';
+        return current === 'unknown' ? sampled : current;
+    };
+}
+/** Let ordinary stdout EOF/exit ordering settle; collect fallback evidence in that same budget. */
+export function waitForEofExit(child) {
+    const sample = probeLeaderState(child, 50);
+    return new Promise(resolve => {
+        if (exited(child))
+            return resolve(sample());
+        const done = () => { child.off('exit', done); child.off('close', done); clearTimeout(timer); resolve(sample()); };
+        const timer = setTimeout(done, 50);
+        timer.unref?.();
+        child.once('exit', done);
+        child.once('close', done);
+    });
+}
+// -1 and 0 address every process and our own group: never a session.
+const groupId = (pgid) => Number.isSafeInteger(pgid) && pgid > 1;
+export function processGroupAlive(pgid) {
+    if (!groupId(pgid))
+        return false;
+    try {
+        process.kill(-pgid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+export function signalProcessGroup(pgid, signal) {
+    if (!groupId(pgid))
+        return;
+    try {
+        process.kill(-pgid, signal);
+    }
+    catch { /* ESRCH: empty; EPERM: no member is ours */ }
+}
+/** `/proc/<pid>/stat` fields 5 (`pgrp`) and 22 (`starttime`) of a live task; a zombie answers
+ * undefined. */
+function procIdentity(stat) {
+    const fields = stat.slice(stat.lastIndexOf(')') + 1).trim().split(/\s+/);
+    if (!stat.includes(')') || fields.length < 20 || fields[0] === 'Z' || !/^\d+$/.test(fields[2]) || !/^\d+$/.test(fields[19]))
+        return undefined;
+    return { pgrp: Number(fields[2]), token: fields[19] };
+}
+const psEnv = () => ({ ...process.env, LC_ALL: 'C', TZ: 'UTC' });
+/** A live process's group and incarnation; undefined when it is gone or the platform cannot say. */
+function identity(pid) {
+    if (process.platform === 'linux') {
+        try {
+            return procIdentity(readFileSync(`/proc/${pid}/stat`, 'utf8'));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (process.platform !== 'darwin')
+        return undefined;
+    const ps = spawnSync('ps', ['-o', 'pgid=,lstart=', '-p', String(pid)], { encoding: 'utf8', timeout: 2_000, env: psEnv() });
+    const match = ps.status === 0 ? /^\s*(\d+)\s+(.+?)\s*$/.exec(ps.stdout) : null;
+    return match ? { pgrp: Number(match[1]), token: match[2] } : undefined;
+}
+/** The process group a live process is in, for destroy's evidence that a recorded group is ours. */
+export function processGroupOf(pid) {
+    return identity(pid)?.pgrp;
+}
+/** Every live process in group `pgid`, by incarnation. Empty when the platform cannot enumerate. */
+function groupMembers(pgid) {
+    if (process.platform === 'linux') {
+        let names;
+        try {
+            names = readdirSync('/proc').filter(name => /^\d+$/.test(name));
+        }
+        catch {
+            return [];
+        }
+        return names.flatMap((name) => {
+            const id = identity(Number(name));
+            return id?.pgrp === pgid ? [{ pid: Number(name), token: id.token }] : [];
+        });
+    }
+    if (process.platform !== 'darwin')
+        return [];
+    const ps = spawnSync('ps', ['-A', '-o', 'pid=,pgid=,lstart='], { encoding: 'utf8', timeout: 2_000, env: psEnv() });
+    if (ps.status !== 0)
+        return [];
+    return ps.stdout.split('\n').flatMap((line) => {
+        const match = /^\s*(\d+)\s+(\d+)\s+(.+?)\s*$/.exec(line);
+        return match && Number(match[2]) === pgid ? [{ pid: Number(match[1]), token: match[3] }] : [];
+    });
+}
+/** An exited leader's entry that no longer names our group: none of the members recorded at its
+ * exit is still the same process in the group. */
+function stale(pgid, leader) {
+    if (!exited(leader.child))
+        return false;
+    return !(leader.members ?? []).some((member) => {
+        const id = identity(member.pid);
+        return id?.pgrp === pgid && id.token === member.token;
+    });
+}
+function drop(pgid, leader) {
+    if (leaders.get(pgid) === leader)
+        leaders.delete(pgid);
+}
+function prune() {
+    for (const [pgid, leader] of leaders)
+        if (stale(pgid, leader))
+            drop(pgid, leader);
+}
+/** How often a group that got SIGTERM is checked for members left. */
+const GROUP_POLL_MS = 50;
+/** The follow-up SIGKILL for a group that got SIGTERM, while it is still ours. The timer is
+ * referenced so a host with nothing else to do (a headless `cez run`) stays up to send it, and it
+ * stops as soon as the group is empty, so that host exits as soon as the group is gone
+ * (hearsay-tools/cezarion#1286). Each check is one `kill(-pgid, 0)`; only the SIGKILL reads the
+ * members, which on darwin spawns `ps` once each. */
+function scheduleKill(pgid, leader, signalledAt) {
+    const deadline = signalledAt + KILL_GRACE_MS;
+    const check = () => {
+        if (leaders.get(pgid) !== leader)
+            return;
+        if (!processGroupAlive(pgid)) {
+            drop(pgid, leader);
+            return;
+        }
+        const left = deadline - Date.now();
+        if (left > 0)
+            setTimeout(check, Math.min(GROUP_POLL_MS, left));
+        else if (!stale(pgid, leader))
+            signalProcessGroup(pgid, 'SIGKILL');
+    };
+    setTimeout(check, Math.max(0, Math.min(GROUP_POLL_MS, deadline - Date.now())));
+}
+/**
+ * Reap an exited leader’s group only while a recorded member still matches. Rescan before
+ * SIGTERM. If all recorded members disappeared first, retain unprovable descendants rather than
+ * signal a reused group.
+ */
+function reap(pgid, leader) {
+    if (leaders.get(pgid) !== leader || leader.signalledAt !== undefined)
+        return;
+    const recorded = leader.members ?? [];
+    const members = groupMembers(pgid);
+    if (!members.some(m => recorded.some(r => r.pid === m.pid && r.token === m.token))) {
+        drop(pgid, leader);
+        return;
+    }
+    leader.members = members;
+    leader.signalledAt = Date.now();
+    signalProcessGroup(pgid, 'SIGTERM');
+    scheduleKill(pgid, leader, leader.signalledAt);
+}
+/** Spawn an agent session leader. Only a real detached `ChildProcess` with a pid is registered,
+ * so a test's fake child (made-up pid) never reaches `process.kill(-pid)`. Under the macOS desktop
+ * shell the leader starts through its trampoline, which execs in place (same pid and group). */
+export function spawnSessionLeader(bin, args, options) {
+    const grouped = process.platform !== 'win32';
+    const [file, argv] = disclaimedCommand(bin, args, options.env);
+    const child = spawn(file, argv, { cwd: options.cwd, env: options.env, detached: grouped });
+    spawned.add(child);
+    const pid = child.pid;
+    if (!grouped || !(child instanceof ChildProcess) || pid === undefined || !groupId(pid))
+        return child;
+    prune();
+    const leader = { child };
+    leaders.set(pid, leader);
+    // Runners clear their own SIGKILL timers when the leader exits. A member that ignored the
+    // SIGTERM cezar sent outlives it, so the follow-up SIGKILL for the group lives here. A leader
+    // cezar never signalled is reaped after the exit drain, so a descendant's final crash
+    // diagnostic still lands first (harness row S19). The drain is referenced, and bounded by
+    // EXIT_DRAIN_CAP_MS, so a host with nothing else to do stays up to reap.
+    child.once('exit', (code) => {
+        if (leaders.get(pid) !== leader)
+            return;
+        leader.members = processGroupAlive(pid) ? groupMembers(pid) : [];
+        if (stale(pid, leader)) {
+            drop(pid, leader);
+            return;
+        }
+        if (leader.signalledAt === undefined)
+            afterExitDrain(() => reap(pid, leader), exitDrainBudget(code), true);
+        else
+            scheduleKill(pid, leader, leader.signalledAt);
+    });
+    return child;
+}
+/** Signal a session: its whole group on POSIX, its tree on win32, else the leader alone. A
+ * leader that already exited on its own is not group-signalled here: its exit scheduled the reap
+ * of what it left behind (hearsay-tools/cezarion#1286). */
+export function signalSession(child, signal, platform = process.platform) {
+    const pid = child.pid;
+    const leader = pid === undefined ? undefined : leaders.get(pid);
+    if (leader?.child === child && !leaderExited(child)) {
+        leader.signalledAt ??= Date.now();
+        signalProcessGroup(pid, signal);
+        return;
+    }
+    if (platform === 'win32' && pid !== undefined && spawned.has(child) && !exited(child)) {
+        try {
+            const taskkill = spawn('taskkill', ['/T', '/F', '/PID', String(pid)], { stdio: 'ignore', windowsHide: true });
+            taskkill.on('error', () => { if (!exited(child))
+                child.kill(signal); });
+            return;
+        }
+        catch { /* fall back to the leader alone */ }
+    }
+    child.kill(signal);
+}
+/** Signal what a leader that already exited left in its group, under the reap's guard: Cursor
+ * print ends its group as each turn's leader exits, ahead of the exit drain. A SIGTERM is the reap
+ * itself, sent at most once per group; a SIGKILL goes only to a group that is still ours. */
+export function signalExitedSession(child, signal) {
+    const pid = child.pid;
+    const leader = pid === undefined ? undefined : leaders.get(pid);
+    if (leader?.child !== child || !exited(child))
+        return;
+    if (signal === 'SIGTERM')
+        reap(pid, leader);
+    else if (stale(pid, leader))
+        drop(pid, leader);
+    else
+        signalProcessGroup(pid, 'SIGKILL');
+}
+/** The pgid of a registered, still-running grouped leader, for the worker process ledger. */
+/** Whether `pid` leads a session this process spawned: an agent's own process, which a process
+ *  wait refuses because it ends only with the session (hearsay-tools/cezarion#1446). */
+export function isSessionLeader(pid) {
+    return leaders.has(pid);
+}
+export function sessionGroupOf(pid) {
+    const leader = leaders.get(pid);
+    return leader && !exited(leader.child) ? pid : undefined;
+}
+/** cezar's own SIGINT/SIGTERM, passed to every agent group that still has members. */
+export function forwardToSessionGroups(signal) {
+    for (const [pgid, leader] of [...leaders]) {
+        if (stale(pgid, leader))
+            drop(pgid, leader);
+        else if (processGroupAlive(pgid))
+            signalProcessGroup(pgid, signal);
+    }
+}
+//# sourceMappingURL=session-process.js.map