@with-logic/elwood 0.2.1 → 0.2.2

package/dist/runtime/shutdown/process-table.js

@@ -0,0 +1,147 @@
+/**
+ * Reads the host process table and finds the process groups a PTY leader's
+ * descendants have moved into. Implements PRD §5.3 and §9.4 (C-LIFE-10): Claude and
+ * Codex start every hook command with `setsid()`, so a hook runs in its OWN session and
+ * process group and a SIGKILL of the leader's group cannot reach it. The parent-pid
+ * chain is the only thing tying such a descendant to the leader, and it holds only
+ * while every process between them is alive: when any of them exits, the processes
+ * below it are reparented to PID 1 and are out of reach. So this walk runs before
+ * Elwood kills the leader, and it finds only descendants still linked at that point.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { coalesceUnstarted } from "./coalesce.js";
+import { createAdmittedPsRunner } from "./native-read-admission.js";
+// An absolute path, so a caller's PATH can never substitute another `ps`. macOS is
+// the only supported platform (PRD §2); `-A -o` is POSIX, so Linux CI parses the same.
+export const PS_PATH = "/bin/ps";
+const PS_ARGS = ["-A", "-o", "pid=,ppid=,pgid=,stat=,lstart=,ucomm=,pid="];
+// Only these: in the C locale `lstart` is always `Www Mmm dd hh:mm:ss yyyy`, so where it
+// ends is known, and in UTC a process's start reads the same however the host's zone changes.
+const PS_ENV = { LC_ALL: "C", TZ: "UTC" };
+// About 80 bytes a row: 16 MiB holds over 200,000 processes, yet bounds a runaway `ps`.
+const PS_MAX_OUTPUT_BYTES = 16 * 1024 * 1024;
+// The short name may hold spaces or be empty, and `ps` prints it raw, so a newline in it
+// starts what reads as another row: each row ends with its pid again (docs/cli-behavior.md).
+const ROW = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(\S+ \S+ +\d+ [\d:]+ \d+)\s(.*)\s(\d+)\s*$/;
+/** One process's identity: its pid and start time, which no later process with its pid shares. */
+export function processIdentity(row) {
+    return `${row.pid} ${row.startedAt}`;
+}
+/** A row's fields where no read showed them: a live process not stopped, of no known start. */
+export const UNREAD = {
+    ppid: 0,
+    zombie: false,
+    stopped: false,
+    startedAt: "",
+    name: "",
+    shared: false,
+};
+/** Full scans and daemon probes share admission without changing request coalescing. */
+export const runFile = createAdmittedPsRunner(promisify(execFile));
+/** The bounds every `ps` run gets: `timeoutMs`, the output cap, SIGKILL, and `PS_ENV`. */
+export function psRunOptions(timeoutMs) {
+    return { timeout: timeoutMs, maxBuffer: PS_MAX_OUTPUT_BYTES, killSignal: "SIGKILL", env: PS_ENV };
+}
+/** Lists every process on the host, rejecting when `ps` fails or exceeds `timeoutMs`. */
+export async function listProcessTable(timeoutMs, run = runFile) {
+    const { stdout } = await run(PS_PATH, PS_ARGS, psRunOptions(timeoutMs));
+    return parseProcessTable(stdout);
+}
+/** The production listing: concurrent shutdowns share one `ps` per event-loop turn. */
+export const listProcessTableShared = coalesceUnstarted(listProcessTable);
+/**
+ * Parses a `PS_ARGS` read (C locale). Throws on a line that is not one whole row: one cut
+ * short, or one whose trailing pid is not its first, as a line a newline in a name
+ * started is (`ROW`). Throws, too, on a pid listed twice.
+ */
+export function parseProcessTable(stdout) {
+    const entries = [];
+    const pids = new Set();
+    for (const line of stdout.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        const [, pid = "", ppid, pgid, state = "", startedAt = "", name = "", trailingPid] = ROW.exec(line) ?? [];
+        if (pid === "" || pid !== trailingPid) {
+            throw new Error("process table read has a line that is not one whole row");
+        }
+        if (pids.has(Number(pid)))
+            throw new Error(`process table read lists pid ${pid} twice`);
+        pids.add(Number(pid));
+        entries.push({
+            pid: Number(pid),
+            ppid: Number(ppid),
+            pgid: Number(pgid),
+            zombie: state.startsWith("Z"),
+            stopped: state.startsWith("T"),
+            startedAt,
+            name: name.trim(),
+            shared: false,
+        });
+    }
+    return entries;
+}
+/**
+ * The process groups, other than the leader's own, that hold at least one LIVE
+ * descendant of `leaderPid`, each mapped to the rows of its members' parents that sit
+ * in OTHER groups (a parent in the same group adds nothing). Descent follows parent
+ * pids transitively, so only descendants still linked to the leader when the table was
+ * read are found. A returned group holds only descendants: a group lives inside one
+ * session, and every member of the leader's session or of a session a descendant
+ * created is itself a descendant. Its id is only a snapshot, and is free for reuse
+ * once the group is gone, so the parent rows let a caller signal it only once a parent
+ * is known to be stopped: a stopped parent cannot reap its exited child, so that child
+ * keeps its pid and the group keeps its id. A leader missing from the table is given
+ * as a row that is not stopped. The host's group (`hostPid`'s) and the ids `kill(-pgid)`
+ * would misroute (`<= 1`) are never returned. Nor is a `shared` process (Codex's daemon
+ * or its updater) or anything it started: the walk never descends into one.
+ */
+export function detachedDescendantGroups(table, { leaderPid, hostPid }) {
+    const children = childrenByParent(table);
+    const leader = table.find((entry) => entry.pid === leaderPid) ?? {
+        ...UNREAD,
+        pid: leaderPid,
+        pgid: leaderPid,
+    };
+    const excluded = new Set([leaderPid, hostPid, leader.pgid]);
+    for (const entry of table)
+        if (entry.pid === hostPid)
+            excluded.add(entry.pgid);
+    const groups = new Map();
+    const pending = [leader];
+    const visited = new Set([leaderPid]);
+    for (let parent = pending.pop(); parent !== undefined; parent = pending.pop()) {
+        for (const child of children.get(parent.pid) ?? []) {
+            if (visited.has(child.pid) || child.shared)
+                continue;
+            visited.add(child.pid);
+            pending.push(child);
+            if (child.zombie || child.pgid <= 1 || excluded.has(child.pgid))
+                continue;
+            const parents = groups.get(child.pgid) ?? new Set();
+            if (parent.pgid !== child.pgid)
+                parents.add(parent);
+            groups.set(child.pgid, parents);
+        }
+    }
+    return groups;
+}
+/** The table's rows grouped by their parent's pid, built once per table. */
+export function childrenByParent(table) {
+    const built = childIndexes.get(table);
+    if (built !== undefined)
+        return built;
+    const children = new Map();
+    for (const entry of table) {
+        const siblings = children.get(entry.ppid);
+        if (siblings)
+            siblings.push(entry);
+        else
+            children.set(entry.ppid, [entry]);
+    }
+    childIndexes.set(table, children);
+    return children;
+}
+/** Each read's index, built once however many walks from different roots read it. */
+const childIndexes = new WeakMap();
+//# sourceMappingURL=process-table.js.map

package/dist/runtime/shutdown/process-table.js.map

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

package/dist/runtime/shutdown/process-tree-ops.d.ts

@@ -0,0 +1,39 @@
+/**
+ * System process-group operations and the shared inert test seam.
+ * Implements PRD §5.3 and §9.4 (C-LIFE-10).
+ */
+import type { SweepOps } from "./detached-sweep/index.ts";
+/**
+ * The process-tree operations teardown performs, injectable so tests never signal real
+ * processes: the group reap's SIGKILL, and the detached sweep's SIGSTOP, SIGKILL, the
+ * SIGCONT that resumes a group holding Codex's daemon, and table read.
+ */
+export type ProcessTreeOps = SweepOps;
+/** The part of the process-tree ops the group reap uses. */
+export type GroupReapOps = Pick<ProcessTreeOps, "killGroup">;
+export declare const osProcessTreeOps: ProcessTreeOps;
+/** The operations currently selected by the shared shutdown seam. */
+export declare function activeProcessTreeOps(): ProcessTreeOps;
+/**
+ * Replaces the process-tree ops. Ops a test leaves out become inert, never the real
+ * ones, so faking only the kill cannot leave a real sweep live (see `quietProcessTree`).
+ */
+export declare function setProcessTreeOpsForTests(ops: GroupReapOps & Partial<ProcessTreeOps>): void;
+/**
+ * Inert sweep ops for tests: a process tree holding only the group leaders it was asked
+ * to stop, each read as stopped with nothing under it. A sweep driven by them signals
+ * no real process, finds no descendant, and converges on its second read.
+ */
+export declare function quietProcessTree(): Omit<ProcessTreeOps, "killGroup">;
+export declare function resetProcessTreeOpsForTests(): void;
+/**
+ * Swallows the ESRCH raised when the group is already empty (the normal case:
+ * the leader and its children exited together) and re-throws any other error —
+ * a real failure (e.g. EPERM) that must not be reported as a successful reap.
+ * Reads the errno through `errnoCode`, which narrows object-ness first, so a
+ * thrown `null`/non-Error is preserved and rethrown rather than triggering a
+ * secondary TypeError while inspecting it (C-ERR-01). Exported for focused
+ * coverage of both branches without an unsafe real signal.
+ */
+export declare function rethrowUnlessGroupGone(error: unknown): void;
+//# sourceMappingURL=process-tree-ops.d.ts.map

package/dist/runtime/shutdown/process-tree-ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-tree-ops.d.ts","sourceRoot":"","sources":["../../../src/runtime/shutdown/process-tree-ops.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAI1D;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;AAEtC,4DAA4D;AAC5D,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;AAK7D,eAAO,MAAM,gBAAgB,EAAE,cAe9B,CAAC;AAOF,qEAAqE;AACrE,wBAAgB,oBAAoB,IAAI,cAAc,CAErD;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI,CAE3F;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAAC,cAAc,EAAE,WAAW,CAAC,CAQpE;AAID,wBAAgB,2BAA2B,IAAI,IAAI,CAElD;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAE3D"}

package/dist/runtime/shutdown/process-tree-ops.js

@@ -0,0 +1,73 @@
+/**
+ * System process-group operations and the shared inert test seam.
+ * Implements PRD §5.3 and §9.4 (C-LIFE-10).
+ */
+import { errnoCode } from "../../core/errors.js";
+import { UNREAD } from "./process-table.js";
+import { listProcessTableMarkingDaemon } from "./shared-daemon.js";
+// Production uses `process.kill` and `/bin/ps`. One seam covers the group reap AND the
+// detached sweep, so a test that fakes the kill can never leave a real sweep live.
+// Exported for a real-process test that wraps one of them.
+export const osProcessTreeOps = {
+    killGroup(pgid) {
+        try {
+            process.kill(-pgid, "SIGKILL");
+        }
+        catch (error) {
+            rethrowUnlessGroupGone(error);
+        }
+    },
+    stopGroup(pgid) {
+        process.kill(-pgid, "SIGSTOP");
+    },
+    continueGroup(pgid) {
+        process.kill(-pgid, "SIGCONT");
+    },
+    listProcesses: (timeoutMs, scope) => listProcessTableMarkingDaemon(timeoutMs, scope),
+};
+// The ops used when a caller does not inject them. A test seam so session lifecycle
+// tests can observe (and neutralize) the group SIGKILL without a real signal, and
+// without every session/terminate call site taking an ops param.
+let activeOps = osProcessTreeOps;
+/** The operations currently selected by the shared shutdown seam. */
+export function activeProcessTreeOps() {
+    return activeOps;
+}
+/**
+ * Replaces the process-tree ops. Ops a test leaves out become inert, never the real
+ * ones, so faking only the kill cannot leave a real sweep live (see `quietProcessTree`).
+ */
+export function setProcessTreeOpsForTests(ops) {
+    activeOps = { ...quietProcessTree(), ...ops };
+}
+/**
+ * Inert sweep ops for tests: a process tree holding only the group leaders it was asked
+ * to stop, each read as stopped with nothing under it. A sweep driven by them signals
+ * no real process, finds no descendant, and converges on its second read.
+ */
+export function quietProcessTree() {
+    const stopped = new Set();
+    return {
+        stopGroup: (pgid) => void stopped.add(pgid),
+        continueGroup: (pgid) => void stopped.delete(pgid),
+        listProcesses: () => Promise.resolve([...stopped].map((pgid) => ({ ...QUIET_ROW, pid: pgid, pgid }))),
+    };
+}
+const QUIET_ROW = { ...UNREAD, ppid: 1, stopped: true };
+export function resetProcessTreeOpsForTests() {
+    activeOps = osProcessTreeOps;
+}
+/**
+ * Swallows the ESRCH raised when the group is already empty (the normal case:
+ * the leader and its children exited together) and re-throws any other error —
+ * a real failure (e.g. EPERM) that must not be reported as a successful reap.
+ * Reads the errno through `errnoCode`, which narrows object-ness first, so a
+ * thrown `null`/non-Error is preserved and rethrown rather than triggering a
+ * secondary TypeError while inspecting it (C-ERR-01). Exported for focused
+ * coverage of both branches without an unsafe real signal.
+ */
+export function rethrowUnlessGroupGone(error) {
+    if (errnoCode(error) !== "ESRCH")
+        throw error;
+}
+//# sourceMappingURL=process-tree-ops.js.map

package/dist/runtime/shutdown/process-tree-ops.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-tree-ops.js","sourceRoot":"","sources":["../../../src/runtime/shutdown/process-tree-ops.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEjD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,6BAA6B,EAAE,MAAM,oBAAoB,CAAC;AAYnE,uFAAuF;AACvF,mFAAmF;AACnF,2DAA2D;AAC3D,MAAM,CAAC,MAAM,gBAAgB,GAAmB;IAC9C,SAAS,CAAC,IAAY;QACpB,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACjC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,sBAAsB,CAAC,KAAK,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IACD,SAAS,CAAC,IAAY;QACpB,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACjC,CAAC;IACD,aAAa,CAAC,IAAY;QACxB,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACjC,CAAC;IACD,aAAa,EAAE,CAAC,SAAS,EAAE,KAAK,EAAE,EAAE,CAAC,6BAA6B,CAAC,SAAS,EAAE,KAAK,CAAC;CACrF,CAAC;AAEF,oFAAoF;AACpF,kFAAkF;AAClF,iEAAiE;AACjE,IAAI,SAAS,GAAmB,gBAAgB,CAAC;AAEjD,qEAAqE;AACrE,MAAM,UAAU,oBAAoB;IAClC,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,GAA2C;IACnF,SAAS,GAAG,EAAE,GAAG,gBAAgB,EAAE,EAAE,GAAG,GAAG,EAAE,CAAC;AAChD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,OAAO;QACL,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;QAC3C,aAAa,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC;QAClD,aAAa,EAAE,GAAG,EAAE,CAClB,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,SAAS,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;KACnF,CAAC;AACJ,CAAC;AAED,MAAM,SAAS,GAAG,EAAE,GAAG,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAExD,MAAM,UAAU,2BAA2B;IACzC,SAAS,GAAG,gBAAgB,CAAC;AAC/B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,IAAI,SAAS,CAAC,KAAK,CAAC,KAAK,OAAO;QAAE,MAAM,KAAK,CAAC;AAChD,CAAC"}

package/dist/runtime/shutdown/read-timeout.d.ts

@@ -0,0 +1,4 @@
+/** Builds shutdown read deadline errors (PRD §5.3/§9.4, C-LIFE-10). */
+/** Retain each read's diagnostic message with the shared deadline error code. */
+export declare function processReadTimeout(message: string): Error;
+//# sourceMappingURL=read-timeout.d.ts.map

package/dist/runtime/shutdown/read-timeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-timeout.d.ts","sourceRoot":"","sources":["../../../src/runtime/shutdown/read-timeout.ts"],"names":[],"mappings":"AAAA,uEAAuE;AAEvE,iFAAiF;AACjF,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAEzD"}

package/dist/runtime/shutdown/read-timeout.js

@@ -0,0 +1,6 @@
+/** Builds shutdown read deadline errors (PRD §5.3/§9.4, C-LIFE-10). */
+/** Retain each read's diagnostic message with the shared deadline error code. */
+export function processReadTimeout(message) {
+    return Object.assign(new Error(message), { code: "ETIMEDOUT" });
+}
+//# sourceMappingURL=read-timeout.js.map

package/dist/runtime/shutdown/read-timeout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-timeout.js","sourceRoot":"","sources":["../../../src/runtime/shutdown/read-timeout.ts"],"names":[],"mappings":"AAAA,uEAAuE;AAEvE,iFAAiF;AACjF,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;AAClE,CAAC"}

package/dist/runtime/shutdown/reap-queue.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Per-session descendant signal passes (PRD §5.3 and §9.4, C-LIFE-10):
+ * begin an idle pass in the caller's tick, and serialize every later pass behind it.
+ */
+export declare class SerialDetachedSweepQueue {
+    private tail;
+    /** Return this attempt’s outcome; release the next pass after either success or failure. */
+    run<T>(attempt: () => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=reap-queue.d.ts.map

package/dist/runtime/shutdown/reap-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reap-queue.d.ts","sourceRoot":"","sources":["../../../src/runtime/shutdown/reap-queue.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,wBAAwB;IACnC,OAAO,CAAC,IAAI,CAA4B;IAExC,4FAA4F;IAC5F,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAkB9C"}

package/dist/runtime/shutdown/reap-queue.js

@@ -0,0 +1,29 @@
+/**
+ * Per-session descendant signal passes (PRD §5.3 and §9.4, C-LIFE-10):
+ * begin an idle pass in the caller's tick, and serialize every later pass behind it.
+ */
+export class SerialDetachedSweepQueue {
+    tail;
+    /** Return this attempt’s outcome; release the next pass after either success or failure. */
+    run(attempt) {
+        const previous = this.tail;
+        const { promise: held, resolve } = Promise.withResolvers();
+        this.tail = held;
+        const release = () => {
+            resolve();
+            if (this.tail === held)
+                this.tail = undefined;
+        };
+        let result;
+        try {
+            result = previous === undefined ? attempt() : previous.then(attempt);
+        }
+        catch (error) {
+            release();
+            return Promise.reject(error);
+        }
+        void result.then(release, release);
+        return result;
+    }
+}
+//# sourceMappingURL=reap-queue.js.map

package/dist/runtime/shutdown/reap-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reap-queue.js","sourceRoot":"","sources":["../../../src/runtime/shutdown/reap-queue.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,OAAO,wBAAwB;IAC3B,IAAI,CAA4B;IAExC,4FAA4F;IAC5F,GAAG,CAAI,OAAyB;QAC9B,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC;QAC3B,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,aAAa,EAAQ,CAAC;QACjE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,OAAO,EAAE,CAAC;YACV,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI;gBAAE,IAAI,CAAC,IAAI,GAAG,SAAS,CAAC;QAChD,CAAC,CAAC;QACF,IAAI,MAAkB,CAAC;QACvB,IAAI,CAAC;YACH,MAAM,GAAG,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,EAAE,CAAC;YACV,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC/B,CAAC;QACD,KAAK,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACnC,OAAO,MAAM,CAAC;IAChB,CAAC;CACF"}

package/dist/runtime/shutdown/reap-tree.d.ts

@@ -1,42 +1,26 @@
 /**
- * Reaps the process tree of a PTY leader on session teardown.
+ * Reaps the process tree of a PTY leader on session teardown, but Codex's shared
+ * app-server daemon, its updater, and what they started (`shared-daemon.ts`).
  * Implements PRD §5.3 and §9.4 (C-LIFE-10): a CLI-spawned helper such as the
  * Claude hook bridge is a descendant of the PTY leader. Because POSIX reparents
  * a surviving descendant to PID 1 the instant its parent exits, a parent-pid
  * walk (`pgrep -P`) cannot find it afterwards — but node-pty starts the leader
  * as its own session/process-group leader, and group membership is inherited
  * and survives reparenting. So we reap by SIGKILLing the leader's process group,
- * which reaches every descendant in one in-process syscall: no subprocess, no
- * PATH lookup, no post-exit reparenting blind spot.
+ * which reaches every descendant still IN that group in one in-process syscall: no
+ * subprocess, no PATH lookup, no post-exit reparenting blind spot.
+ *
+ * A descendant that started its own group is outside it: Claude and Codex start every
+ * hook with `setsid()` (docs/cli-behavior.md, "Hook and MCP process groups").
+ * `sweepDetached` finds those groups by parent pid and kills them, all but the daemon's
+ * and its updater's, which other Codex sessions share, so it has to run
+ * while that link still exists: before the live leader is SIGKILLed (see
+ * `sweepDetachedGroups` in `detached-sweep/index.ts`).
  */
-/** Injectable so tests never signal real process groups; production uses `process.kill`. */
-export type ProcessGroupKiller = {
-    /** SIGKILLs the process group `pgid` (via `kill(-pgid)`); tolerates an empty/dead group. */
-    readonly killGroup: (pgid: number) => void;
-};
-/**
- * SIGKILLs the process group led by `leaderPid`, reaping every descendant still
- * in the group — including one already reparented to PID 1. node-pty starts the
- * leader via `setsid()`, so it heads its own session and its pgid equals its pid;
- * that group is always distinct from the host's own group, so this cannot signal
- * the host process. Refuses only pids the kernel would misroute (see
- * `isReapableGroupId`), never an arbitrary numeric floor. An already-dead group
- * (leader and children exited together) is the normal case and its `ESRCH` is
- * swallowed; a real kill failure such as `EPERM` propagates.
- */
-export declare function reapProcessGroup(leaderPid: number, ops?: ProcessGroupKiller): void;
-export declare function setGroupKillerForTests(killer: ProcessGroupKiller): void;
-export declare function resetGroupKillerForTests(): void;
-/**
- * Swallows the ESRCH raised when the group is already empty (the normal case:
- * the leader and its children exited together) and re-throws any other error —
- * a real failure (e.g. EPERM) that must not be reported as a successful reap.
- * Reads the errno through `errnoCode`, which narrows object-ness first, so a
- * thrown `null`/non-Error is preserved and rethrown rather than triggering a
- * secondary TypeError while inspecting it (C-ERR-01). Exported for focused
- * coverage of both branches without an unsafe real signal.
- */
-export declare function rethrowUnlessGroupGone(error: unknown): void;
+import { type ProcessTreeOps } from "./process-tree-ops.ts";
+export { reapProcessGroup } from "./leader-group.ts";
+export { osProcessTreeOps, type ProcessTreeOps, quietProcessTree, resetProcessTreeOpsForTests, rethrowUnlessGroupGone, setProcessTreeOpsForTests, } from "./process-tree-ops.ts";
+export type LeaderPtySignalOutcome = "signal-sent" | "leader-group-gone";
 /**
  * Owns a single PTY leader's group reap. A SUCCESSFUL reap MUST happen at most
  * once: `stop()` then a later `teardown()` both want to guarantee the group is
@@ -51,12 +35,38 @@ export declare class SessionReaper {
     private readonly leaderPid;
     private readonly ops;
     private done;
-    constructor(leaderPid: number, ops?: ProcessGroupKiller);
+    private pendingSweeps;
+    /** Terminal evidence about the entire group, never inferred merely from leader exit. */
+    private leaderGroupGone;
+    private readonly detachedSweepQueue;
+    /** A detached sweep that failed; once the leader is gone it can never be confirmed. */
+    private unresolvedSweep;
+    constructor(leaderPid: number, ops?: ProcessTreeOps);
     /**
      * Reap the group once it succeeds; a successful call latches so subsequent
      * calls no-op (no recycled-pgid double-kill). A failed kill does NOT latch and
      * rethrows, keeping the reap retryable on a later lifecycle call.
      */
     reap(): void;
+    /** Dispatch a PTY signal only while this session has not confirmed its group gone. */
+    signalLeaderPty(send: () => void): LeaderPtySignalOutcome;
+    /**
+     * The group reap for an explicit shutdown's retry: it also keeps failing while an
+     * earlier detached sweep is unresolved, so a later `stop()`/`kill()`/`teardown()`
+     * never reports success for a hook that may still be running. It says nothing about
+     * a sweep that never ran: the caller sweeps first, before any SIGKILL it sends to a
+     * live leader.
+     */
+    reapAndThrowOnDetachedSweepFailure(): void;
+    /**
+     * Kill the process groups the leader's descendants moved into. Valid only while
+     * the leader is alive — afterwards its detached descendants are reparented to
+     * PID 1 and cannot be found — so it runs just before the leader is SIGKILLed, with
+     * `leaderExited` reporting whether the caller has seen the leader exit. A failure,
+     * including a leader exit that left a found group unreached, is kept for
+     * `reapAndThrowOnDetachedSweepFailure`, then thrown. Refuses the same misrouted ids
+     * as the group reap.
+     */
+    sweepDetached(leaderExited: () => boolean): Promise<void>;
 }
 //# sourceMappingURL=reap-tree.d.ts.map

package/dist/runtime/shutdown/reap-tree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reap-tree.d.ts","sourceRoot":"","sources":["../../../src/runtime/shutdown/reap-tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,4FAA4F;AAC5F,MAAM,MAAM,kBAAkB,GAAG;IAC/B,4FAA4F;IAC5F,QAAQ,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C,CAAC;AAoBF;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,GAAE,kBAAiC,GAAG,IAAI,CAGhG;AAiBD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAEvE;AAED,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAE3D;AAED;;;;;;;;;GASG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqB;IACzC,OAAO,CAAC,IAAI,CAAS;gBAET,SAAS,EAAE,MAAM,EAAE,GAAG,GAAE,kBAAiC;IAKrE;;;;OAIG;IACH,IAAI,IAAI,IAAI;CAKb"}
+{"version":3,"file":"reap-tree.d.ts","sourceRoot":"","sources":["../../../src/runtime/shutdown/reap-tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAGlF,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EACL,gBAAgB,EAChB,KAAK,cAAc,EACnB,gBAAgB,EAChB,2BAA2B,EAC3B,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAE/B,MAAM,MAAM,sBAAsB,GAAG,aAAa,GAAG,mBAAmB,CAAC;AAEzE;;;;;;;;;GASG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAiB;IACrC,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,aAAa,CAAK;IAC1B,wFAAwF;IACxF,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAkC;IACrE,uFAAuF;IACvF,OAAO,CAAC,eAAe,CAA2B;gBAEtC,SAAS,EAAE,MAAM,EAAE,GAAG,GAAE,cAAuC;IAK3E;;;;OAIG;IACH,IAAI,IAAI,IAAI;IAOZ,sFAAsF;IACtF,eAAe,CAAC,IAAI,EAAE,MAAM,IAAI,GAAG,sBAAsB;IASzD;;;;;;OAMG;IACH,kCAAkC,IAAI,IAAI;IAK1C;;;;;;;;OAQG;IACG,aAAa,CAAC,YAAY,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAkBhE"}

package/dist/runtime/shutdown/reap-tree.js

@@ -1,80 +1,28 @@
 /**
- * Reaps the process tree of a PTY leader on session teardown.
+ * Reaps the process tree of a PTY leader on session teardown, but Codex's shared
+ * app-server daemon, its updater, and what they started (`shared-daemon.ts`).
  * Implements PRD §5.3 and §9.4 (C-LIFE-10): a CLI-spawned helper such as the
  * Claude hook bridge is a descendant of the PTY leader. Because POSIX reparents
  * a surviving descendant to PID 1 the instant its parent exits, a parent-pid
  * walk (`pgrep -P`) cannot find it afterwards — but node-pty starts the leader
  * as its own session/process-group leader, and group membership is inherited
  * and survives reparenting. So we reap by SIGKILLing the leader's process group,
- * which reaches every descendant in one in-process syscall: no subprocess, no
- * PATH lookup, no post-exit reparenting blind spot.
+ * which reaches every descendant still IN that group in one in-process syscall: no
+ * subprocess, no PATH lookup, no post-exit reparenting blind spot.
+ *
+ * A descendant that started its own group is outside it: Claude and Codex start every
+ * hook with `setsid()` (docs/cli-behavior.md, "Hook and MCP process groups").
+ * `sweepDetached` finds those groups by parent pid and kills them, all but the daemon's
+ * and its updater's, which other Codex sessions share, so it has to run
+ * while that link still exists: before the live leader is SIGKILLed (see
+ * `sweepDetachedGroups` in `detached-sweep/index.ts`).
  */
-import { errnoCode } from "../../core/errors.js";
-/**
- * A pgid is reapable when it identifies the KNOWN-OWNED node-pty leader's group
- * rather than a system group or the host itself. Ownership is NOT inferred from a
- * numeric floor — that is an allocation detail, and after PID-space wrap or inside
- * a constrained namespace a legitimate leader can be low (a prior arbitrary `< 100`
- * floor silently no-op'd such leaders and leaked their descendants). We instead
- * accept every valid child pid while refusing the two ids a group SIGKILL must
- * never touch:
- *   - `pgid <= 1` — pid 0 means "our own group" to `kill(2)`, and pid 1 is
- *     `init`/`launchd`; a fake pid 1 in tests once reaped a developer's real apps.
- *   - the host's OWN pid — node-pty gives the leader a fresh session via `setsid()`
- *     so its pgid can never legitimately equal ours, but if a bad pgid ever did we
- *     must not signal `-process.pid` and kill ourselves.
- */
-function isReapableGroupId(pgid) {
-    return Number.isInteger(pgid) && pgid > 1 && pgid !== process.pid;
-}
-/**
- * SIGKILLs the process group led by `leaderPid`, reaping every descendant still
- * in the group — including one already reparented to PID 1. node-pty starts the
- * leader via `setsid()`, so it heads its own session and its pgid equals its pid;
- * that group is always distinct from the host's own group, so this cannot signal
- * the host process. Refuses only pids the kernel would misroute (see
- * `isReapableGroupId`), never an arbitrary numeric floor. An already-dead group
- * (leader and children exited together) is the normal case and its `ESRCH` is
- * swallowed; a real kill failure such as `EPERM` propagates.
- */
-export function reapProcessGroup(leaderPid, ops = activeKiller) {
-    if (!isReapableGroupId(leaderPid))
-        return;
-    ops.killGroup(leaderPid);
-}
-const defaultKiller = {
-    killGroup(pgid) {
-        try {
-            process.kill(-pgid, "SIGKILL");
-        }
-        catch (error) {
-            rethrowUnlessGroupGone(error);
-        }
-    },
-};
-// The killer used when a caller does not inject one. A test seam so session
-// lifecycle tests can observe (and neutralize) the group SIGKILL without a real
-// signal, and without every session/terminate call site taking a killer param.
-let activeKiller = defaultKiller;
-export function setGroupKillerForTests(killer) {
-    activeKiller = killer;
-}
-export function resetGroupKillerForTests() {
-    activeKiller = defaultKiller;
-}
-/**
- * Swallows the ESRCH raised when the group is already empty (the normal case:
- * the leader and its children exited together) and re-throws any other error —
- * a real failure (e.g. EPERM) that must not be reported as a successful reap.
- * Reads the errno through `errnoCode`, which narrows object-ness first, so a
- * thrown `null`/non-Error is preserved and rethrown rather than triggering a
- * secondary TypeError while inspecting it (C-ERR-01). Exported for focused
- * coverage of both branches without an unsafe real signal.
- */
-export function rethrowUnlessGroupGone(error) {
-    if (errnoCode(error) !== "ESRCH")
-        throw error;
-}
+import { sweepDetachedGroups } from "./detached-sweep/index.js";
+import { isReapableGroupId, reapProcessGroup } from "./leader-group.js";
+import { activeProcessTreeOps } from "./process-tree-ops.js";
+import { SerialDetachedSweepQueue } from "./reap-queue.js";
+export { reapProcessGroup } from "./leader-group.js";
+export { osProcessTreeOps, quietProcessTree, resetProcessTreeOpsForTests, rethrowUnlessGroupGone, setProcessTreeOpsForTests, } from "./process-tree-ops.js";
 /**
  * Owns a single PTY leader's group reap. A SUCCESSFUL reap MUST happen at most
  * once: `stop()` then a later `teardown()` both want to guarantee the group is
@@ -89,7 +37,13 @@ export class SessionReaper {
     leaderPid;
     ops;
     done = false;
-    constructor(leaderPid, ops = activeKiller) {
+    pendingSweeps = 0;
+    /** Terminal evidence about the entire group, never inferred merely from leader exit. */
+    leaderGroupGone = false;
+    detachedSweepQueue = new SerialDetachedSweepQueue();
+    /** A detached sweep that failed; once the leader is gone it can never be confirmed. */
+    unresolvedSweep;
+    constructor(leaderPid, ops = activeProcessTreeOps()) {
         this.leaderPid = leaderPid;
         this.ops = ops;
     }
@@ -99,10 +53,63 @@ export class SessionReaper {
      * rethrows, keeping the reap retryable on a later lifecycle call.
      */
     reap() {
-        if (this.done)
+        // The active shutdown owner reaps after its sweep, including any pending confirmation.
+        if (this.done || this.leaderGroupGone || this.pendingSweeps > 0)
             return;
         reapProcessGroup(this.leaderPid, this.ops);
         this.done = true;
     }
+    /** Dispatch a PTY signal only while this session has not confirmed its group gone. */
+    signalLeaderPty(send) {
+        if (this.leaderGroupGone) {
+            this.reapAndThrowOnDetachedSweepFailure();
+            return "leader-group-gone";
+        }
+        send();
+        return "signal-sent";
+    }
+    /**
+     * The group reap for an explicit shutdown's retry: it also keeps failing while an
+     * earlier detached sweep is unresolved, so a later `stop()`/`kill()`/`teardown()`
+     * never reports success for a hook that may still be running. It says nothing about
+     * a sweep that never ran: the caller sweeps first, before any SIGKILL it sends to a
+     * live leader.
+     */
+    reapAndThrowOnDetachedSweepFailure() {
+        this.reap();
+        if (this.unresolvedSweep !== undefined)
+            throw this.unresolvedSweep;
+    }
+    /**
+     * Kill the process groups the leader's descendants moved into. Valid only while
+     * the leader is alive — afterwards its detached descendants are reparented to
+     * PID 1 and cannot be found — so it runs just before the leader is SIGKILLed, with
+     * `leaderExited` reporting whether the caller has seen the leader exit. A failure,
+     * including a leader exit that left a found group unreached, is kept for
+     * `reapAndThrowOnDetachedSweepFailure`, then thrown. Refuses the same misrouted ids
+     * as the group reap.
+     */
+    async sweepDetached(leaderExited) {
+        if (!isReapableGroupId(this.leaderPid))
+            return;
+        this.pendingSweeps += 1;
+        try {
+            const failure = await this.detachedSweepQueue.run(() => {
+                // A queued request must recheck after the preceding pass has confirmed exit.
+                if (this.leaderGroupGone)
+                    return Promise.resolve(undefined);
+                return sweepDetachedGroups(this.leaderPid, this.ops, leaderExited, undefined, () => {
+                    this.leaderGroupGone = true;
+                });
+            });
+            if (failure === undefined)
+                return;
+            this.unresolvedSweep = failure;
+            throw failure;
+        }
+        finally {
+            this.pendingSweeps -= 1;
+        }
+    }
 }
 //# sourceMappingURL=reap-tree.js.map