antechamber 1.0.35 → 1.0.37

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project uses [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.0.37] - 2026-11-03
+
+- feat(session-hosts): tear down private OmO hosts on macOS (#85)
+
+## [1.0.36] - 2026-11-03
+
+### Added
+
+- Clean up after the agent on macOS. Disposal now records the agent's process group and re-identifies each member
+  before signalling it, so child processes that outlive the agent are stopped instead of being left behind. Linux
+  keeps reading `/proc`; macOS reads `/bin/ps`, because Node has neither `/proc` nor pidfd there. A process that has
+  already exited (zombie) never counts as a survivor.
+
+- Tear down OmO's private task hosts on macOS. The connector finds the supervisors it started by the `--socket` session
+  shard, entry point and working directory, records every process in their groups, and signals each one by PID only
+  after re-checking its group and start time, escalating to `SIGKILL` after a grace window. A process that outlives its
+  supervisor is still stopped. `antechamber doctor` reports the check as PASS when `/bin/ps` and `/usr/sbin/lsof`
+  exist. Linux keeps the pidfd path.
+
 ## [1.0.35] - 2026-11-03
 
 - test: resolve fixture paths with fileURLToPath (#86)

package/README.md

@@ -354,10 +354,13 @@ Hardening controls (full reference in [docs/configuration.md](docs/configuration
 ## Platform notes
 
 Linux is the primary supported platform. OmO's private task-host teardown
-(killing detached supervisor processes antechamber spawned) needs Linux
-pidfds (`os.pidfd_open`, Linux 5.3+) and `python3` on PATH; Node has no pidfd
-API. On other platforms that teardown step is skipped with one warning instead
-of crashing; antechamber never falls back to signalling numeric PIDs. macOS is untested.
+(killing detached supervisor processes antechamber spawned) uses Linux
+pidfds (`os.pidfd_open`, Linux 5.3+) and `python3` on PATH, because Node has no pidfd
+API; on Linux it never signals a numeric PID. macOS has no pidfd, so there it
+reads `/bin/ps` and `/usr/sbin/lsof` and signals each owned process by PID after
+re-checking its process group and start time (see
+[the OmO backend notes](docs/backends/omo.md#private-task-host-teardown)). CI runs the suite on
+macOS. On other platforms that teardown step is skipped with one warning instead of crashing.
 
 ## Limitations / non-goals
 

package/dist/commands/doctor.js

@@ -84,9 +84,15 @@ export function doctor(options = {}, ctx = createContext(), latestVersion) {
             }
         })
         : undefined;
-    add("private-host-teardown", python === undefined ? "WARN" : "PASS", python === undefined
-        ? "requires Linux and python3 with working pidfd support"
-        : `Linux pidfd support via ${python}`);
+    if (ctx.platform === "darwin") {
+        const tools = ["/bin/ps", "/usr/sbin/lsof"];
+        const missing = tools.filter((tool) => !ctx.fs.existsSync(tool));
+        add("private-host-teardown", missing.length === 0 ? "PASS" : "WARN", missing.length === 0 ? `macOS teardown via ${tools.join(" and ")}` : `requires ${missing.join(" and ")}`);
+    }
+    else
+        add("private-host-teardown", python === undefined ? "WARN" : "PASS", python === undefined
+            ? "requires Linux and python3 with working pidfd support"
+            : `Linux pidfd support via ${python}`);
     const openchamber = resolveBinary("openchamber", ctx);
     if (openchamber === undefined)
         add("openchamber", "WARN", "openchamber is not on PATH");

package/dist/pi-rpc.d.ts

@@ -9,6 +9,8 @@
  */
 import { EventEmitter } from "node:events";
 import { type LifecycleClock } from "./lifecycle.js";
+import { type ProcessTable } from "./proc-table.js";
+export type { ProcessIdentity, ProcessTable } from "./proc-table.js";
 export interface PiRpcCommand {
     id?: string;
     type: string;
@@ -30,17 +32,6 @@ export declare class UpstreamProtocolError extends Error {
  * earlyoom take a workload before the adapter, whose death stops every session at once.
  */
 export declare const AGENT_OOM_SCORE_ADJ_MARGIN = 300;
-/** A process's group and kernel start time: with the PID, the identity that survives PID reuse checks. */
-interface ProcessIdentity {
-    readonly pid: number;
-    readonly group: number;
-    readonly start: string;
-}
-/** Reads process identities so disposal can tell owned survivors from a reused PID. */
-export interface ProcessTable {
-    identity(pid: number): ProcessIdentity | undefined;
-    groupMembers(group: number): ProcessIdentity[];
-}
 /** Why the agent stopped without antechamber disposing it on purpose (eviction, delete, shutdown). */
 export type PiStopReason = {
     readonly kind: "timeout";
@@ -143,4 +134,3 @@ export declare class PiRpcClient extends EventEmitter {
     notify(cmd: Omit<PiRpcCommand, "id">): void;
     dispose(): Promise<void>;
 }
-export {};

package/dist/pi-rpc.js

@@ -11,10 +11,11 @@ import { spawn } from "node:child_process";
 import { StringDecoder } from "node:string_decoder";
 import { EventEmitter } from "node:events";
 import { randomUUID } from "node:crypto";
-import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { readFileSync, writeFileSync } from "node:fs";
 import { constants as osConstants } from "node:os";
 import { systemClock } from "./lifecycle.js";
 import { agentBinary, envSetting } from "./config.js";
+import { createProcessTable } from "./proc-table.js";
 export const RPC_COMMAND_TIMEOUT_MS = 60_000;
 /**
  * `compact` answers only when the summary is written. OmO bounds one compaction by
@@ -50,34 +51,7 @@ function rankAboveAdapterForOom(pid) {
         console.error(`[pi-rpc] could not raise the agent's OOM score: ${error instanceof Error ? error.message : error}`);
     }
 }
-// Linux /proc. Any read failure (gone, no permission, no /proc) means the identity cannot be
-// verified, and an unverifiable process is never signalled: fail closed.
-const procTable = {
-    identity(pid) {
-        let stat;
-        try {
-            stat = readFileSync(`/proc/${pid}/stat`, "utf8");
-        }
-        catch {
-            return undefined;
-        }
-        const fields = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
-        return { pid, group: Number(fields[2]), start: fields[19] ?? "" };
-    },
-    groupMembers(group) {
-        let names;
-        try {
-            names = readdirSync("/proc");
-        }
-        catch {
-            return [];
-        }
-        return names
-            .filter((name) => /^\d+$/.test(name))
-            .flatMap((name) => procTable.identity(Number(name)) ?? [])
-            .filter((member) => member.group === group);
-    },
-};
+const procTable = createProcessTable();
 function duration(ms) {
     if (ms % 60_000 === 0)
         return `${ms / 60_000} min`;

package/dist/proc-table-darwin.d.ts

@@ -0,0 +1,23 @@
+import type { ProcessIdentity, ProcessTable } from "./proc-table.js";
+/**
+ * macOS process table, backed by `/bin/ps`. Used by disposal to identify owned survivors, so it must
+ * report the same three facts Linux reads from `/proc/<pid>/stat`: PID, process group, and a start
+ * time that survives PID reuse checks. `ps` exposes the latter as `lstart` (second granularity).
+ */
+/** Runs `/bin/ps` with the given arguments and returns stdout. Injected so tests never spawn. */
+export type PsRunner = (args: readonly string[]) => string;
+/**
+ * `execFileSync` with an absolute binary: no shell, and no PATH lookup that a user-controlled
+ * directory could shadow. `-ww` disables width truncation; the column set is fixed so every line
+ * has the same shape. LC_ALL is pinned because `lstart` is rendered in the current locale: two
+ * calls must agree with each other even if the user changes the system language mid-session.
+ */
+export declare function runPs(args: readonly string[]): string;
+/** One `ps -A` row with its state and argv, for callers that match processes by command line. */
+export interface PsProcess extends ProcessIdentity {
+    readonly state: string;
+    readonly args: string;
+}
+/** Every live (non-zombie) process with its argv. Throws when `ps` fails, so the caller decides. */
+export declare function listDarwinProcesses(run?: PsRunner): PsProcess[];
+export declare function createDarwinProcTable(run?: PsRunner): ProcessTable;

package/dist/proc-table-darwin.js

@@ -0,0 +1,93 @@
+import { execFileSync } from "node:child_process";
+const PS_TIMEOUT_MS = 2_000;
+const PS_MAX_BUFFER = 8 * 1024 * 1024;
+const PS_COLUMNS = "pid=,pgid=,stat=,lstart=";
+/** `pid pgid stat lstart`, where lstart is "Sun Nov  1 15:55:48 2026" and may end in padding. */
+const PS_LINE = /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(.+?)\s*$/;
+/**
+ * `execFileSync` with an absolute binary: no shell, and no PATH lookup that a user-controlled
+ * directory could shadow. `-ww` disables width truncation; the column set is fixed so every line
+ * has the same shape. LC_ALL is pinned because `lstart` is rendered in the current locale: two
+ * calls must agree with each other even if the user changes the system language mid-session.
+ */
+export function runPs(args) {
+    return execFileSync("/bin/ps", args, {
+        encoding: "utf8",
+        timeout: PS_TIMEOUT_MS,
+        maxBuffer: PS_MAX_BUFFER,
+        env: { ...process.env, LC_ALL: "C", LANG: "C" },
+    });
+}
+function parseLine(line) {
+    const match = PS_LINE.exec(line);
+    if (match === null)
+        return undefined;
+    const pid = Number(match[1]);
+    const group = Number(match[2]);
+    const state = match[3];
+    const start = match[4];
+    if (!Number.isInteger(pid) || !Number.isInteger(group) || state === undefined || start === undefined)
+        return undefined;
+    if (start === "")
+        return undefined;
+    return { pid, group, start, state };
+}
+/**
+ * A zombie has already exited; only its parent is left to reap it. Counting it as a survivor would
+ * make disposal wait out the full grace window for a process that can no longer run, so `Z` entries
+ * are treated as gone in both methods, as `session-hosts` already does on Linux.
+ */
+function alive(entry) {
+    return !entry.state.startsWith("Z");
+}
+// Under LC_ALL=C, lstart is a fixed 24-character field, so argv starts right after it even when it
+// contains spaces.
+const PS_ARGS_LINE = /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(.{24})\s?(.*)$/;
+/** Every live (non-zombie) process with its argv. Throws when `ps` fails, so the caller decides. */
+export function listDarwinProcesses(run = runPs) {
+    return run(["-ww", "-o", `${PS_COLUMNS},args=`, "-A"])
+        .split("\n")
+        .flatMap((line) => {
+        const match = PS_ARGS_LINE.exec(line);
+        if (match === null)
+            return [];
+        const entry = { pid: Number(match[1]), group: Number(match[2]), state: match[3] ?? "", start: match[4] ?? "" };
+        return alive(entry) ? [{ ...entry, args: match[5] ?? "" }] : [];
+    });
+}
+function toIdentity(entry) {
+    return { pid: entry.pid, group: entry.group, start: entry.start };
+}
+export function createDarwinProcTable(run = runPs) {
+    return {
+        identity(pid) {
+            if (!Number.isInteger(pid) || pid <= 0)
+                return undefined;
+            let output;
+            try {
+                output = run(["-ww", "-o", PS_COLUMNS, "-p", String(pid)]);
+            }
+            catch {
+                // The process is gone, or ps could not read it. An unverifiable identity fails closed.
+                return undefined;
+            }
+            const entry = parseLine(output.trim());
+            if (entry === undefined || entry.pid !== pid || !alive(entry))
+                return undefined;
+            return toIdentity(entry);
+        },
+        groupMembers(group) {
+            let output;
+            try {
+                output = run(["-ww", "-o", PS_COLUMNS, "-A"]);
+            }
+            catch {
+                return [];
+            }
+            return output.split("\n").flatMap((line) => {
+                const entry = parseLine(line);
+                return entry !== undefined && entry.group === group && alive(entry) ? [toIdentity(entry)] : [];
+            });
+        },
+    };
+}

package/dist/proc-table.d.ts

@@ -0,0 +1,17 @@
+/** A process's group and kernel start time: with the PID, the identity that survives PID reuse checks. */
+export interface ProcessIdentity {
+    readonly pid: number;
+    readonly group: number;
+    readonly start: string;
+}
+/** Reads process identities so disposal can tell owned survivors from a reused PID. */
+export interface ProcessTable {
+    identity(pid: number): ProcessIdentity | undefined;
+    groupMembers(group: number): ProcessIdentity[];
+}
+/**
+ * The process table for this platform. Linux reads `/proc`; macOS reads `/bin/ps`, because Node has no
+ * `/proc` and no pidfd there. Every other platform keeps the Linux table so a missing `/proc` fails
+ * closed (an identity is never reported that cannot be verified).
+ */
+export declare function createProcessTable(platform?: NodeJS.Platform): ProcessTable;

package/dist/proc-table.js

@@ -0,0 +1,38 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { createDarwinProcTable } from "./proc-table-darwin.js";
+// Linux /proc. Any read failure (gone, no permission, no /proc) means the identity cannot be
+// verified, and an unverifiable process is never signalled: fail closed.
+const linuxProcTable = {
+    identity(pid) {
+        let stat;
+        try {
+            stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+        }
+        catch {
+            return undefined;
+        }
+        const fields = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+        return { pid, group: Number(fields[2]), start: fields[19] ?? "" };
+    },
+    groupMembers(group) {
+        let names;
+        try {
+            names = readdirSync("/proc");
+        }
+        catch {
+            return [];
+        }
+        return names
+            .filter((name) => /^\d+$/.test(name))
+            .flatMap((name) => linuxProcTable.identity(Number(name)) ?? [])
+            .filter((member) => member.group === group);
+    },
+};
+/**
+ * The process table for this platform. Linux reads `/proc`; macOS reads `/bin/ps`, because Node has no
+ * `/proc` and no pidfd there. Every other platform keeps the Linux table so a missing `/proc` fails
+ * closed (an identity is never reported that cannot be verified).
+ */
+export function createProcessTable(platform = process.platform) {
+    return platform === "darwin" ? createDarwinProcTable() : linuxProcTable;
+}

package/dist/session-hosts.d.ts

@@ -1,3 +1,24 @@
+import { type PsRunner } from "./proc-table-darwin.js";
 /** Capability and warning state are captured once, before any shutdown work. */
 export declare function createSessionHostStopper(platform?: NodeJS.Platform, probe?: () => string | undefined): (created: ReadonlyMap<string, string>) => Promise<void>;
 export declare const stopSessionHosts: (created: ReadonlyMap<string, string>) => Promise<void>;
+/** Injected so the darwin path can be tested without running ps, lsof or a signal. */
+export interface DarwinHostDependencies {
+    readonly run: PsRunner;
+    readonly cwdOf: (pid: number) => string | undefined;
+    readonly realpath: (path: string) => string;
+    readonly signal: (pid: number, signal: NodeJS.Signals) => void;
+    readonly delay: (ms: number) => Promise<void>;
+    readonly graceMs: number;
+    readonly pollMs: number;
+}
+/**
+ * macOS teardown without pidfd. Ownership is the Linux rule: a live group leader whose argv names the
+ * supervisor entry point and, as its `--socket` value, the shard of a session this connector created,
+ * and whose working directory is that session's directory. Every member of an owned group is recorded
+ * with its start time in the same scan, and each later signal goes to one PID only after a fresh scan
+ * still shows the same group and start time. Members are tracked individually, so a child that outlives
+ * its supervisor is still stopped. A PID can be recycled between that scan and the signal; the window
+ * is the same one `PiRpcClient.dispose()` accepts.
+ */
+export declare function createDarwinHostStopper(overrides?: Partial<DarwinHostDependencies>): (created: ReadonlyMap<string, string>) => Promise<void>;

package/dist/session-hosts.js

@@ -1,11 +1,17 @@
-import { spawn } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { once } from "node:events";
 import { closeSync, constants, openSync, readFileSync, readdirSync, readlinkSync, realpathSync } from "node:fs";
 import { basename } from "node:path";
 import { findPidfdPython } from "./pidfd.js";
+import { listDarwinProcesses, runPs } from "./proc-table-darwin.js";
+/** How long a darwin teardown waits after SIGTERM before escalating, and how often it re-reads the table. */
+const HOST_TERM_GRACE_MS = 5_000;
+const HOST_POLL_MS = 100;
 /** Capability and warning state are captured once, before any shutdown work. */
 export function createSessionHostStopper(platform = process.platform, probe = findPidfdPython) {
+    if (platform === "darwin")
+        return createDarwinHostStopper();
     const python = platform === "linux" ? probe() : undefined;
     let warned = false;
     return async (created) => {
@@ -22,6 +28,121 @@ export function createSessionHostStopper(platform = process.platform, probe = fi
     };
 }
 export const stopSessionHosts = createSessionHostStopper();
+/** macOS has no `/proc/<pid>/cwd`; lsof prints `p<pid>`, `fcwd`, `n<path>`. */
+function cwdOfHost(pid) {
+    try {
+        const output = execFileSync("/usr/sbin/lsof", ["-a", "-p", String(pid), "-d", "cwd", "-Fn"], {
+            encoding: "utf8",
+            timeout: 2_000,
+            maxBuffer: 1024 * 1024,
+        });
+        for (const line of output.split("\n"))
+            if (line.startsWith("n"))
+                return line.slice(1);
+        return undefined;
+    }
+    catch {
+        // No permission, no process, or no lsof: the directory is unconfirmed and nothing is signalled.
+        return undefined;
+    }
+}
+function signalHost(pid, signal) {
+    try {
+        process.kill(pid, signal);
+    }
+    catch (error) {
+        const code = error instanceof Error && "code" in error ? error.code : undefined;
+        // Gone since the last scan, or not ours to signal: either way nothing was sent.
+        if (code === "ESRCH" || code === "EPERM")
+            return;
+        throw error;
+    }
+}
+function socketName(sessionId) {
+    return `p-${createHash("sha256").update(`p:${sessionId}`).digest("hex").slice(0, 16)}.sock`;
+}
+/**
+ * The value of `--socket`, as Linux reads it from argv. `ps` joins argv with spaces, so the value runs
+ * to the next ` --` flag (a socket directory may contain spaces). Anything else after it makes the
+ * basename miss every shard, which fails closed.
+ */
+function socketArgument(args) {
+    const match = /(?:^|\s)--socket\s+(.+?)(?=\s--|$)/.exec(args);
+    return match?.[1] === undefined ? undefined : basename(match[1].trimEnd());
+}
+function isSupervisor(args) {
+    const tokens = args.split(/\s+/);
+    return (tokens.includes("--internal-rpc-host-supervisor") || tokens.some((token) => token.endsWith("/host-lifecycle.js")));
+}
+/**
+ * macOS teardown without pidfd. Ownership is the Linux rule: a live group leader whose argv names the
+ * supervisor entry point and, as its `--socket` value, the shard of a session this connector created,
+ * and whose working directory is that session's directory. Every member of an owned group is recorded
+ * with its start time in the same scan, and each later signal goes to one PID only after a fresh scan
+ * still shows the same group and start time. Members are tracked individually, so a child that outlives
+ * its supervisor is still stopped. A PID can be recycled between that scan and the signal; the window
+ * is the same one `PiRpcClient.dispose()` accepts.
+ */
+export function createDarwinHostStopper(overrides = {}) {
+    const deps = {
+        run: overrides.run ?? runPs,
+        cwdOf: overrides.cwdOf ?? cwdOfHost,
+        realpath: overrides.realpath ?? realpathSync,
+        signal: overrides.signal ?? signalHost,
+        delay: overrides.delay ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+        graceMs: overrides.graceMs ?? HOST_TERM_GRACE_MS,
+        pollMs: overrides.pollMs ?? HOST_POLL_MS,
+    };
+    return async (created) => {
+        if (created.size === 0)
+            return;
+        const sockets = new Map([...created].map(([id, directory]) => [socketName(id), directory]));
+        const processes = listDarwinProcesses(deps.run);
+        const groups = new Set();
+        for (const row of processes) {
+            if (row.group !== row.pid || !isSupervisor(row.args))
+                continue;
+            const socket = socketArgument(row.args);
+            const directory = socket === undefined ? undefined : sockets.get(socket);
+            if (directory === undefined)
+                continue;
+            const cwd = deps.cwdOf(row.pid);
+            if (cwd === undefined)
+                continue;
+            let expected;
+            try {
+                expected = deps.realpath(directory);
+            }
+            catch {
+                continue;
+            }
+            if (cwd === expected)
+                groups.add(row.group);
+        }
+        const members = processes.filter((row) => groups.has(row.group));
+        if (members.length === 0)
+            return;
+        const survivors = () => {
+            const now = new Map(listDarwinProcesses(deps.run).map((row) => [row.pid, row]));
+            return members
+                .filter((member) => {
+                const row = now.get(member.pid);
+                return row !== undefined && row.group === member.group && row.start === member.start;
+            })
+                .map((member) => member.pid);
+        };
+        for (const signal of ["SIGTERM", "SIGKILL"]) {
+            for (const pid of survivors())
+                deps.signal(pid, signal);
+            for (let waited = 0; waited < deps.graceMs; waited += deps.pollMs) {
+                await deps.delay(deps.pollMs);
+                if (survivors().length === 0)
+                    return;
+            }
+        }
+        throw new Error(`private OmO hosts survived shutdown: ${survivors().join(", ")}`);
+    };
+}
 function processInfo(pid) {
     let fd;
     try {

package/extensions/omo-compat/package.json

@@ -1,6 +1,6 @@
 {
   "name": "antechamber-omo-compat",
-  "version": "1.0.35",
+  "version": "1.0.37",
   "description": "OpenChamber extension: displays OmO tool calls the way OmO means them when OpenChamber runs on antechamber",
   "private": true,
   "type": "module",

package/extensions/omo-dag/package.json

@@ -1,6 +1,6 @@
 {
   "name": "antechamber-omo-graph",
-  "version": "1.0.35",
+  "version": "1.0.37",
   "description": "OpenChamber extension: live, interactive graph of the OmO sub-agents behind the current session",
   "private": true,
   "type": "module",

package/extensions/omo-work/package.json

@@ -1,6 +1,6 @@
 {
   "name": "antechamber-omo-work",
-  "version": "1.0.35",
+  "version": "1.0.37",
   "description": "OpenChamber 2.x Work Status section: OmO todo phases, monitors, eval cells and background work of the current session",
   "private": true,
   "type": "module",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "antechamber",
-  "version": "1.0.35",
+  "version": "1.0.37",
   "description": "OpenCode-compatible HTTP/SSE server that lets OpenChamber drive the pi coding agent (and OmO) over RPC",
   "type": "module",
   "license": "MIT",