Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

fix(agent-runtime): exit when the host does, instead of running forever (#307)

Louis Amaudruz52ed04322c3c
diff --git a/console/packages/switch-agent-runtime/src/bin.shutdown.test.ts b/console/packages/switch-agent-runtime/src/bin.shutdown.test.ts
new file mode 100644
index 000000000..8a26b72de
--- /dev/null
+++ b/console/packages/switch-agent-runtime/src/bin.shutdown.test.ts
@@ -0,0 +1,275 @@
+import { type ChildProcess, spawn } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import * as http from 'node:http';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+
+/**
+ * That the runtime dies when its host does.
+ *
+ * A host stops needing this process in more ways than it can tell it so, and
+ * only one of them is an orderly shutdown. The others — killed, crashed,
+ * force-quit — leave stdin at EOF and nothing else, and for a long time nothing
+ * was listening for that: the SDK's stdio transport binds only 'data' and
+ * 'error', so `transport.onclose` never fired and the heartbeat, the lease
+ * renewal and the reconnect loop ran on against a host that was gone. They
+ * accumulated in the hundreds on a developer machine before anyone looked.
+ *
+ * So these assert on the manner of death, not on tidiness: that it exits, that
+ * it exits *promptly*, and that it takes its published port with it.
+ */
+
+const PKG_ROOT = join(import.meta.dirname, '..');
+const BIN = join(PKG_ROOT, 'dist', 'bin.mjs');
+const SOURCE = readFileSync(join(import.meta.dirname, 'bin.ts'), 'utf8');
+
+/**
+ * Generous next to the intended promptness — the exit is immediate — and well
+ * inside the per-test timeout, so a regression fails as "still running after
+ * 3s" rather than as a bare timeout that says nothing about what broke.
+ */
+const EXIT_DEADLINE_MS = 3_000;
+
+/** The startup path talks to a local server and loads its operations first. */
+const HANDSHAKE_DEADLINE_MS = 20_000;
+
+const TEST_TIMEOUT_MS = 30_000;
+
+const INITIALIZE = {
+ jsonrpc: '2.0',
+ id: 1,
+ method: 'initialize',
+ params: {
+ protocolVersion: '2024-11-05',
+ capabilities: {},
+ clientInfo: { name: 'shutdown-test', version: '0' },
+ },
+};
+
+const running: ChildProcess[] = [];
+const servers: http.Server[] = [];
+const sandboxes: string[] = [];
+
+afterEach(() => {
+ for (const child of running.splice(0)) child.kill('SIGKILL');
+ for (const server of servers.splice(0)) server.close();
+ for (const dir of sandboxes.splice(0)) {
+ try {
+ rmSync(dir, { recursive: true, force: true });
+ } catch {
+ // A just-killed child may still hold a file open; the OS reclaims tmp.
+ }
+ }
+});
+
+async function opsServer(): Promise<string> {
+ const server = http.createServer((_req, res) => {
+ res.writeHead(200, { 'content-type': 'application/json' });
+ res.end(JSON.stringify({ operations: {} }));
+ });
+ servers.push(server);
+ await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+ const { port } = server.address() as { port: number };
+ return `http://127.0.0.1:${port}`;
+}
+
+type Running = { child: ChildProcess; root: string; stdout: () => string };
+
+/** A live server in a throwaway HOME, past the handshake and serving. */
+async function serving(): Promise<Running> {
+ const endpoint = await opsServer();
+ const root = mkdtempSync(join(tmpdir(), 'switch-runtime-shutdown-'));
+ sandboxes.push(root);
+
+ const child = spawn(process.execPath, [BIN], {
+ cwd: root,
+ env: {
+ PATH: process.env.PATH ?? '',
+ HOME: root,
+ SWITCH_API_ENDPOINT: endpoint,
+ SWITCH_API_TOKEN: 'tok-shutdown',
+ SWITCH_AGENT_ID: 'agent-shutdown',
+ },
+ stdio: ['pipe', 'pipe', 'pipe'],
+ });
+ running.push(child);
+
+ let out = '';
+ child.stdout!.on('data', (c: Buffer) => {
+ out += c.toString();
+ });
+ // Drained rather than ignored: an unread stderr pipe fills and would itself
+ // stall the child, which is the condition under test in another guise.
+ child.stderr!.on('data', () => {});
+
+ const run = { child, root, stdout: () => out };
+ child.stdin!.write(`${JSON.stringify(INITIALIZE)}\n`);
+ await responseWithin(run, 1, HANDSHAKE_DEADLINE_MS);
+ child.stdin!.write(
+ `${JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' })}\n`
+ );
+ return run;
+}
+
+function responseWithin(run: Running, id: number, ms: number): Promise<void> {
+ const seek = (): boolean =>
+ run
+ .stdout()
+ .split('\n')
+ .some((line) => {
+ if (!line.trim()) return false;
+ try {
+ return (JSON.parse(line) as { id?: number }).id === id;
+ } catch {
+ return false;
+ }
+ });
+
+ return new Promise((resolve, reject) => {
+ if (seek()) return resolve();
+ const timer = setTimeout(() => reject(new Error(`no response to ${id} within ${ms}ms`)), ms);
+ run.child.stdout!.on('data', () => {
+ if (seek()) {
+ clearTimeout(timer);
+ resolve();
+ }
+ });
+ });
+}
+
+/**
+ * How the child died, as a string an assertion can read back.
+ *
+ * `still running` rather than a rejection: the regression is a process that
+ * never exits, and naming it that way makes the failure message the diagnosis.
+ */
+function exitWithin(child: ChildProcess, ms: number): Promise<string> {
+ return new Promise((resolve) => {
+ const timer = setTimeout(() => resolve('still running'), ms);
+ child.on('exit', (code, signal) => {
+ clearTimeout(timer);
+ resolve(signal ? `signal ${signal}` : `exit ${code}`);
+ });
+ });
+}
+
+/** Where the runtime advertises its hook port, keyed by the host's pid. */
+function sessionDir(root: string): string {
+ return join(root, '.switch', 'sessions', String(process.pid));
+}
+
+describe.skipIf(!existsSync(BIN))('the runtime outliving its host', () => {
+ it(
+ 'exits when stdin closes without an orderly shutdown',
+ async () => {
+ const run = await serving();
+
+ // Exactly what a killed host leaves behind: EOF on stdin, no `close()`.
+ run.child.stdin!.end();
+
+ expect(await exitWithin(run.child, EXIT_DEADLINE_MS)).toBe('exit 0');
+ },
+ TEST_TIMEOUT_MS
+ );
+
+ // Node terminates on an unhandled SIGTERM anyway, so what the handler buys is
+ // the cleanup on the way out — assert that, not merely that it died.
+ it(
+ 'shuts down cleanly on SIGTERM rather than dying where it stands',
+ async () => {
+ const run = await serving();
+ await new Promise((r) => setTimeout(r, 500));
+
+ run.child.kill('SIGTERM');
+
+ expect(await exitWithin(run.child, EXIT_DEADLINE_MS)).toBe('exit 0');
+ expect(existsSync(sessionDir(run.root))).toBe(false);
+ },
+ TEST_TIMEOUT_MS
+ );
+
+ it(
+ 'takes its published port file with it',
+ async () => {
+ const run = await serving();
+ // The port is published from the listen callback, which may not have run yet.
+ await new Promise((r) => setTimeout(r, 500));
+
+ run.child.stdin!.end();
+ await exitWithin(run.child, EXIT_DEADLINE_MS);
+
+ expect(existsSync(sessionDir(run.root))).toBe(false);
+ },
+ TEST_TIMEOUT_MS
+ );
+
+ it(
+ 'does not stay alive on the hook listener alone',
+ async () => {
+ const run = await serving();
+ await new Promise((r) => setTimeout(r, 500));
+
+ // The listener is bound by now. If it were still holding the event loop,
+ // closing stdin would leave the process up.
+ run.child.stdin!.end();
+ expect(await exitWithin(run.child, EXIT_DEADLINE_MS)).toBe('exit 0');
+ },
+ TEST_TIMEOUT_MS
+ );
+});
+
+/**
+ * The reparenting watchdog fires on a 30s cadence, which is longer than a test
+ * should wait and longer than the harness above can stage. Read the source for
+ * it instead — enough to catch its removal, which is the regression that
+ * matters.
+ */
+describe('the reparenting watchdog', () => {
+ it('compares the live parent against the one recorded at startup', () => {
+ expect(SOURCE).toContain('process.ppid !== SESSION_PPID');
+ });
+
+ it('does not itself hold the event loop open', () => {
+ const watchdog = SOURCE.slice(SOURCE.indexOf('PARENT_CHECK_INTERVAL_MS'));
+ expect(watchdog).toMatch(/\.unref\(\)/);
+ });
+
+ it('shuts down rather than only logging', () => {
+ const watchdog = SOURCE.slice(
+ SOURCE.indexOf('setInterval(() => {'),
+ SOURCE.indexOf('PARENT_CHECK_INTERVAL_MS)')
+ );
+ expect(watchdog).toContain('shutdown(');
+ });
+});
+
+/**
+ * Every trigger is a case the others miss, so losing one is a silent narrowing
+ * of the fix rather than a test failure somewhere else.
+ */
+describe('the shutdown triggers', () => {
+ it.each([
+ ['the transport closing', "transport.onclose = () => shutdown('transport closed')"],
+ ['stdin ending', "process.stdin.on('end'"],
+ ['stdin closing', "process.stdin.on('close'"],
+ ['a broken stdout', "process.stdout.on('error'"],
+ ['a broken stderr', "process.stderr.on('error'"],
+ ])('shuts down on %s', (_name, snippet) => {
+ expect(SOURCE).toContain(snippet);
+ });
+
+ it('handles the termination signals', () => {
+ expect(SOURCE).toContain("['SIGTERM', 'SIGINT', 'SIGHUP']");
+ });
+
+ it('treats EPIPE as the host being gone rather than an error to log', () => {
+ const handler = SOURCE.slice(SOURCE.indexOf("process.on('uncaughtException'"));
+ expect(handler.slice(0, handler.indexOf('});'))).toContain('EPIPE');
+ });
+
+ it('runs the shutdown work once however many triggers fire', () => {
+ const body = SOURCE.slice(SOURCE.indexOf('function shutdown('));
+ expect(body.slice(0, body.indexOf('\n}'))).toContain('if (shuttingDown) return;');
+ });
+});
diff --git a/console/packages/switch-agent-runtime/src/bin.ts b/console/packages/switch-agent-runtime/src/bin.ts
index 9460cf377..866980c24 100644
--- a/console/packages/switch-agent-runtime/src/bin.ts
+++ b/console/packages/switch-agent-runtime/src/bin.ts
@@ -52,6 +52,7 @@ import {
readAgentStore,
type ResolvedAgent,
} from './credentials';
+import { reapOrphanedRuntimes } from './reap';
import { readSse, type SseFrame } from './sse';
const ENV_ENDPOINT = process.env.SWITCH_API_ENDPOINT ?? '';
@@ -84,7 +85,8 @@ function looksUnresolved(value: string): boolean {
}
const SESSION_PPID = process.ppid;
-const SESSION_DIR = path.join(os.homedir(), '.switch', 'sessions', String(SESSION_PPID));
+const SESSIONS_ROOT = path.join(os.homedir(), '.switch', 'sessions');
+const SESSION_DIR = path.join(SESSIONS_ROOT, String(SESSION_PPID));
const PORT_FILE = path.join(SESSION_DIR, 'port');
const STARTUP_ERROR_FILE = path.join(SESSION_DIR, 'startup-error.log');
@@ -364,6 +366,12 @@ process.on('unhandledRejection', (err) => {
});
process.on('uncaughtException', (err) => {
if (!serving) failStartup(`uncaught exception during startup: ${err}`);
+ // A broken stdio pipe is not an error to carry on through: it means the host
+ // is gone, and carrying on is what leaves this process running for weeks.
+ if ((err as NodeJS.ErrnoException).code === 'EPIPE') {
+ shutdown('stdio pipe broken');
+ return;
+ }
process.stderr.write(`switch: uncaught exception: ${err}\n`);
});
@@ -1584,6 +1592,11 @@ function startHookListener() {
})();
});
+ // Unref'd so it cannot be the only thing keeping this process alive: the
+ // stdin reader holds the loop open while a host is attached, which makes
+ // "alive" mean "someone is talking to us" rather than "a port is bound".
+ server.unref();
+
server.listen(0, '127.0.0.1', () => {
const address = server.address();
const port = typeof address === 'object' && address !== null ? address.port : 0;
@@ -1841,15 +1854,54 @@ async function emitNotification(content: string, meta: Record<string, string>) {
// -- Connect and start -------------------------------------------------------
-const transport = new StdioServerTransport();
+// A host can stop needing this process in more ways than it can tell it so, and
+// every way that is not a clean shutdown leaves the timers below running and the
+// hook listener holding the event loop open. Each trigger here covers a case the
+// others miss; any one of them is enough on its own.
+
+let shuttingDown = false;
-transport.onclose = () => {
+function shutdown(reason: string): void {
+ if (shuttingDown) return;
+ shuttingDown = true;
stopStream();
stopHeartbeat();
stopLeaseRenew();
unpublishPort();
+ // Best-effort: on a broken pipe this is what we are reacting to.
+ try {
+ process.stderr.write(`switch: shutting down — ${reason}\n`);
+ } catch {
+ // Nothing left to say it to.
+ }
process.exit(0);
-};
+}
+
+const transport = new StdioServerTransport();
+
+transport.onclose = () => shutdown('transport closed');
+
+// The SDK's stdio transport binds only 'data' and 'error' on stdin, so `onclose`
+// above is reached only by an orderly `close()` — never by a host that was
+// killed, crashed or force-quit, which is the case it exists for.
+process.stdin.on('end', () => shutdown('stdin ended'));
+process.stdin.on('close', () => shutdown('stdin closed'));
+
+for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP'] as const) {
+ process.on(signal, () => shutdown(signal));
+}
+
+// A pipe whose reader is gone but which was never closed accepts writes that can
+// never drain, and node queues them in memory for as long as the process lives.
+process.stdout.on('error', () => shutdown('stdout gone'));
+process.stderr.on('error', () => shutdown('stderr gone'));
+
+// The backstop, and the only signal that survives every way a host can vanish:
+// losing our parent reparents us, and nothing about that reaches our stdio.
+const PARENT_CHECK_INTERVAL_MS = 30_000;
+setInterval(() => {
+ if (process.ppid !== SESSION_PPID) shutdown('host process exited');
+}, PARENT_CHECK_INTERVAL_MS).unref();
// Load the operation list before serving, so the tool surface is whole the
// first time a host asks for it.
@@ -1892,6 +1944,16 @@ if (!isDegraded()) {
await mcp.connect(transport);
serving = true;
+// After the handshake and never awaited: this scans every process on the
+// machine and may remove thousands of directories, and a host waiting on
+// `initialize` must not pay for either. Needs no identity, so it runs degraded
+// too — an orphan from a previous session is there to clear up regardless.
+void reapOrphanedRuntimes({
+ sessionsRoot: SESSIONS_ROOT,
+ ownSessionDir: SESSION_DIR,
+ log: (message) => process.stderr.write(`switch: ${message}\n`),
+});
+
// Degraded, none of the machinery below has anything to act on: no identity to
// open a connection as, no room to route a hook to. Publishing no port also
// keeps a pre-expansion spawn — which used to exit on sight — from racing the
diff --git a/console/packages/switch-agent-runtime/src/reap.test.ts b/console/packages/switch-agent-runtime/src/reap.test.ts
new file mode 100644
index 000000000..71ff5090d
--- /dev/null
+++ b/console/packages/switch-agent-runtime/src/reap.test.ts
@@ -0,0 +1,177 @@
+import { describe, expect, it } from 'vitest';
+import { findOrphanedRuntimes, parseProcessTable, staleSessionDirs } from './reap';
+
+/**
+ * The reaper's predicate, against process tables shaped like the real ones.
+ *
+ * These are the actual command lines from the machine that prompted this, with
+ * the pids kept: 15860 and 76532 are the two that had grown to 470 MB and
+ * 367 MB, and 15765 / 76464 are their wrappers — alive, orphaned to launchd,
+ * and the reason "is the parent dead?" is the wrong question. Any predicate
+ * that misses those two misses the bug.
+ */
+
+const NPX_BIN = '/Users/dev/.npm/_npx/6dbe1f0400d7a251/node_modules/.bin/switch-agent-runtime';
+
+/** The three-deep tree a live session produces. */
+function liveSession(hostPid: number, wrapperPid: number, runtimePid: number) {
+ return [
+ { pid: hostPid, ppid: 501, command: 'claude' },
+ {
+ pid: wrapperPid,
+ ppid: hostPid,
+ command: 'npm exec @sandboxaq/[email protected]',
+ },
+ { pid: runtimePid, ppid: wrapperPid, command: `node ${NPX_BIN}` },
+ ];
+}
+
+/** The same tree after the host died: the wrapper survives, reparented to init. */
+function orphanedSession(wrapperPid: number, runtimePid: number) {
+ return [
+ { pid: wrapperPid, ppid: 1, command: 'npm exec @sandboxaq/[email protected]' },
+ { pid: runtimePid, ppid: wrapperPid, command: `node ${NPX_BIN}` },
+ ];
+}
+
+const INIT = { pid: 1, ppid: 0, command: '/sbin/launchd' };
+
+describe('parsing the process table', () => {
+ it('reads pid, ppid and the full command line', () => {
+ const rows = parseProcessTable(
+ [' 501 1 /sbin/launchd', '15860 15765 node /path/to/switch-agent-runtime --flag'].join(
+ '\n'
+ )
+ );
+ expect(rows).toEqual([
+ { pid: 501, ppid: 1, command: '/sbin/launchd' },
+ { pid: 15860, ppid: 15765, command: 'node /path/to/switch-agent-runtime --flag' },
+ ]);
+ });
+
+ it('skips headers, blanks and anything malformed', () => {
+ const rows = parseProcessTable([' PID PPID COMMAND', '', ' ', 'garbage'].join('\n'));
+ expect(rows).toEqual([]);
+ });
+});
+
+describe('finding runtimes whose host is gone', () => {
+ it('spares a runtime whose host is alive', () => {
+ const rows = [INIT, ...liveSession(900, 901, 902)];
+ expect(findOrphanedRuntimes(rows, 999)).toEqual([]);
+ });
+
+ it('catches the orphan whose wrapper is alive but reparented', () => {
+ const rows = [INIT, ...orphanedSession(15765, 15860)];
+ // Both, not just the runtime: the wrapper is dead weight once its child is.
+ expect(findOrphanedRuntimes(rows, 999).sort((a, b) => a - b)).toEqual([15765, 15860]);
+ });
+
+ it('catches a runtime reparented directly, its wrapper already gone', () => {
+ const rows = [INIT, { pid: 76532, ppid: 1, command: `node ${NPX_BIN}` }];
+ expect(findOrphanedRuntimes(rows, 999)).toEqual([76532]);
+ });
+
+ it('catches a runtime whose parent vanished from the snapshot', () => {
+ const rows = [INIT, { pid: 4242, ppid: 4241, command: `node ${NPX_BIN}` }];
+ expect(findOrphanedRuntimes(rows, 999)).toEqual([4242]);
+ });
+
+ it('sorts the live from the dead in one pass', () => {
+ const rows = [INIT, ...liveSession(900, 901, 902), ...orphanedSession(15765, 15860)];
+ expect(findOrphanedRuntimes(rows, 999).sort((a, b) => a - b)).toEqual([15765, 15860]);
+ });
+
+ it('ignores processes that are not the runtime', () => {
+ const rows = [
+ INIT,
+ { pid: 300, ppid: 1, command: 'npm exec @playwright/mcp@latest' },
+ { pid: 301, ppid: 1, command: '/Applications/Discord.app/Contents/MacOS/Discord' },
+ ];
+ expect(findOrphanedRuntimes(rows, 999)).toEqual([]);
+ });
+
+ /**
+ * A substring match on the package name kills these, and an early draft of
+ * this did. Any shell that merely mentions the runtime — installing it,
+ * grepping for it, or a tool invocation quoting it back — carries the name in
+ * its own command line, and an orphaned one is indistinguishable from the
+ * real thing unless the match is anchored.
+ */
+ it.each([
+ ['a shell running npx for it', "/bin/zsh -c 'npx -y @sandboxaq/[email protected]'"],
+ ['a shell greping for it', '/bin/bash -c pkill -f [email protected]'],
+ ['an editor with the path open', 'vim /src/switch-agent-runtime/bin.ts'],
+ [
+ 'a shell quoting the binary path',
+ "/bin/sh -c 'node /x/node_modules/.bin/switch-agent-runtime'",
+ ],
+ ])('does not reap %s, even orphaned', (_name, command) => {
+ expect(findOrphanedRuntimes([INIT, { pid: 400, ppid: 1, command }], 999)).toEqual([]);
+ });
+
+ it('still reaps the genuine article in the same table', () => {
+ const rows = [
+ INIT,
+ { pid: 400, ppid: 1, command: "/bin/zsh -c 'grep [email protected] log'" },
+ ...orphanedSession(15765, 15860),
+ ];
+ expect(findOrphanedRuntimes(rows, 999).sort((a, b) => a - b)).toEqual([15765, 15860]);
+ });
+
+ // The reaper runs inside a runtime, so its own chain looks exactly like the
+ // thing it hunts. Nothing else stops it turning on the session it serves.
+ it('never reaps itself', () => {
+ const rows = [INIT, ...liveSession(900, 901, 902)];
+ expect(findOrphanedRuntimes(rows, 902)).toEqual([]);
+ });
+
+ it('never reaps itself even when its own chain looks orphaned', () => {
+ const rows = [INIT, ...orphanedSession(15765, 15860)];
+ expect(findOrphanedRuntimes(rows, 15860)).toEqual([]);
+ });
+
+ it('spares its own wrapper along with itself', () => {
+ const rows = [INIT, ...orphanedSession(15765, 15860)];
+ expect(findOrphanedRuntimes(rows, 15860)).not.toContain(15765);
+ });
+
+ it('terminates on a parent cycle rather than hanging', () => {
+ const rows = [
+ { pid: 10, ppid: 11, command: `node ${NPX_BIN}` },
+ { pid: 11, ppid: 10, command: `node ${NPX_BIN}` },
+ ];
+ expect(findOrphanedRuntimes(rows, 999).sort((a, b) => a - b)).toEqual([10, 11]);
+ });
+
+ it('walks through several wrapper layers to reach the host', () => {
+ const rows = [
+ INIT,
+ { pid: 900, ppid: 501, command: 'codex' },
+ { pid: 901, ppid: 900, command: 'npx -y @sandboxaq/[email protected]' },
+ { pid: 902, ppid: 901, command: 'npm exec @sandboxaq/[email protected]' },
+ { pid: 903, ppid: 902, command: `node ${NPX_BIN}` },
+ ];
+ expect(findOrphanedRuntimes(rows, 999)).toEqual([]);
+ });
+});
+
+describe('sweeping stale session directories', () => {
+ const alive = (pid: number) => pid === 900;
+
+ it('removes only directories whose process is gone', () => {
+ expect(staleSessionDirs(['900', '901', '902'], alive, 'none')).toEqual(['901', '902']);
+ });
+
+ it('keeps the caller’s own directory whatever its liveness looks like', () => {
+ expect(staleSessionDirs(['901', '902'], alive, '901')).toEqual(['902']);
+ });
+
+ it('ignores entries that are not pids', () => {
+ expect(staleSessionDirs(['901', 'media', '.DS_Store', ''], alive, 'none')).toEqual(['901']);
+ });
+
+ it('returns nothing for an empty directory', () => {
+ expect(staleSessionDirs([], alive, 'none')).toEqual([]);
+ });
+});
diff --git a/console/packages/switch-agent-runtime/src/reap.ts b/console/packages/switch-agent-runtime/src/reap.ts
new file mode 100644
index 000000000..69dcf9799
--- /dev/null
+++ b/console/packages/switch-agent-runtime/src/reap.ts
@@ -0,0 +1,207 @@
+/**
+ * Clearing up runtimes that outlived the host that spawned them.
+ *
+ * A runtime is started three deep — host → `npm exec` → runtime — and for a
+ * long time none of them noticed when the host died: the stdio transport
+ * reports only an orderly close, so a killed or crashed host left the runtime
+ * serving nobody, holding a port and beating a heartbeat at a Switch it could
+ * no longer reach. One machine accumulated 486 of them, 3.5 GB, over 18 days.
+ *
+ * `bin.ts` now exits on its own for all of those cases, so nothing this module
+ * kills should ever exist again. It is here for the ones already running: every
+ * published version up to 0.3.2 lacks that fix and will sit there until the
+ * machine reboots. A new runtime clears them out on its way up.
+ *
+ * The signal is the process tree, not anything on disk. When the host dies its
+ * `npm exec` wrapper is reparented to init while the runtime carries on
+ * pointing at a wrapper that is alive but orphaned — so "is the parent dead?"
+ * is the wrong question and would have missed the two worst offenders on the
+ * machine above. Reaching init without passing a live host is the right one.
+ */
+
+import { execFile } from 'node:child_process';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+export type ProcessRow = { pid: number; ppid: number; command: string };
+
+/**
+ * The two shapes this process launches as, matched from the start of the
+ * command rather than anywhere in it.
+ *
+ * A substring test is not safe here: any shell whose command line merely
+ * *mentions* the package matches one — a `zsh -c` running an install or a grep
+ * for it, say — and if that shell were orphaned the reaper would kill it.
+ * Anchoring on argv[0] separates "is this process the runtime" from "does this
+ * process talk about the runtime".
+ *
+ * Matching both shapes with one predicate is deliberate: the wrapper carries no
+ * meaning of its own, so the chain walk can treat the pair as a unit.
+ */
+const RUNTIME_PATTERNS = [
+ // node /…/node_modules/.bin/switch-agent-runtime
+ /^(?:\S*\/)?(?:node\s+)?\S*\/node_modules\/\.bin\/switch-agent-runtime(?:\s|$)/,
+ // npm exec @scope/[email protected] | npx -y @scope/…@1.2.3
+ /^(?:\S*\/)?(?:npm|npx)\s+.*\bswitch-agent-runtime@/,
+];
+
+function isRuntimeProcess(command: string): boolean {
+ return RUNTIME_PATTERNS.some((pattern) => pattern.test(command));
+}
+
+/** Parse `ps -axo pid=,ppid=,command=`. */
+export function parseProcessTable(stdout: string): ProcessRow[] {
+ const rows: ProcessRow[] = [];
+ for (const line of stdout.split('\n')) {
+ const match = /^\s*(\d+)\s+(\d+)\s+(\S.*)$/.exec(line);
+ if (!match) continue;
+ rows.push({ pid: Number(match[1]), ppid: Number(match[2]), command: match[3] });
+ }
+ return rows;
+}
+
+/** Every ancestor of `pid`, and `pid` itself. */
+function chainFrom(pid: number, byPid: Map<number, ProcessRow>): Set<number> {
+ const chain = new Set<number>([pid]);
+ let current = byPid.get(pid)?.ppid ?? 0;
+ while (current > 1 && !chain.has(current)) {
+ chain.add(current);
+ current = byPid.get(current)?.ppid ?? 0;
+ }
+ return chain;
+}
+
+/**
+ * Whether some live process outside this runtime's own launch chain owns it.
+ *
+ * Walks up through the wrapper — which carries the same marker — and stops at
+ * the first ancestor that does not. That ancestor is the host: if we reach init
+ * without finding one, nobody is left to serve.
+ */
+function hasLiveHost(row: ProcessRow, byPid: Map<number, ProcessRow>): boolean {
+ const seen = new Set<number>();
+ let current = row.ppid;
+
+ while (current > 1) {
+ if (seen.has(current)) return false;
+ seen.add(current);
+
+ const parent = byPid.get(current);
+ // Gone between the snapshot and now: it cannot be a host that is still
+ // waiting on this runtime.
+ if (!parent) return false;
+ if (!isRuntimeProcess(parent.command)) return true;
+
+ current = parent.ppid;
+ }
+
+ return false;
+}
+
+/**
+ * The runtime and wrapper processes with no host left, newest ancestor first.
+ *
+ * `selfPid`'s own chain is excluded outright rather than left to the walk. The
+ * walk would spare it anyway — we were just spawned, so our host is alive — but
+ * a reaper that can reach itself is one bad predicate away from killing the
+ * session it was started to serve.
+ */
+export function findOrphanedRuntimes(rows: ProcessRow[], selfPid: number): number[] {
+ const byPid = new Map(rows.map((row) => [row.pid, row]));
+ const protectedPids = chainFrom(selfPid, byPid);
+
+ const orphaned: number[] = [];
+ for (const row of rows) {
+ if (!isRuntimeProcess(row.command)) continue;
+ if (protectedPids.has(row.pid)) continue;
+ if (hasLiveHost(row, byPid)) continue;
+ orphaned.push(row.pid);
+ }
+ return orphaned;
+}
+
+/**
+ * Session directories whose owning process is gone.
+ *
+ * Pure litter: a runtime killed outright never runs `unpublishPort`, and the
+ * directories accumulate one per session forever (8071 on the machine that
+ * prompted this). Nothing reads a directory whose pid is dead, so removing them
+ * is safe independently of anything above.
+ */
+export function staleSessionDirs(
+ entries: string[],
+ isAlive: (pid: number) => boolean,
+ keep: string
+): string[] {
+ return entries.filter(
+ (entry) => entry !== keep && /^\d+$/.test(entry) && !isAlive(Number(entry))
+ );
+}
+
+/** Whether a pid exists, without signalling it. */
+function pidIsAlive(pid: number): boolean {
+ try {
+ process.kill(pid, 0);
+ return true;
+ } catch (err) {
+ // EPERM means it exists and belongs to someone else.
+ return (err as NodeJS.ErrnoException).code === 'EPERM';
+ }
+}
+
+/**
+ * Clear up after previous runtimes. Best-effort throughout: this runs beside a
+ * live session and must never be able to fail it.
+ *
+ * `ps` covers macOS and Linux; Windows has no equivalent worth reimplementing
+ * for a population that will reboot away, so only the directory sweep runs
+ * there.
+ */
+export async function reapOrphanedRuntimes(options: {
+ sessionsRoot: string;
+ ownSessionDir: string;
+ log: (message: string) => void;
+}): Promise<void> {
+ const { sessionsRoot, ownSessionDir, log } = options;
+
+ if (process.platform !== 'win32') {
+ try {
+ const { stdout } = await execFileAsync('ps', ['-axo', 'pid=,ppid=,command=']);
+ const orphaned = findOrphanedRuntimes(parseProcessTable(stdout), process.pid);
+
+ if (orphaned.length > 0) {
+ log(`reaping ${orphaned.length} runtime process(es) whose host is gone`);
+ for (const pid of orphaned) {
+ try {
+ // Every version being reaped predates the shutdown handlers, so
+ // this lands on node's default disposition and terminates them.
+ process.kill(pid, 'SIGTERM');
+ } catch {
+ // Already gone, or not ours to signal.
+ }
+ }
+ }
+ } catch (err) {
+ log(`could not scan for orphaned runtimes: ${err}`);
+ }
+ }
+
+ try {
+ const entries = await fs.readdir(sessionsRoot);
+ const stale = staleSessionDirs(entries, pidIsAlive, path.basename(ownSessionDir));
+ if (stale.length === 0) return;
+
+ log(`removing ${stale.length} stale session director(ies)`);
+ for (const entry of stale) {
+ // Awaited one at a time rather than in bulk: there can be thousands, and
+ // this shares an event loop with a session that is already serving.
+ await fs.rm(path.join(sessionsRoot, entry), { recursive: true, force: true });
+ }
+ } catch (err) {
+ if ((err as NodeJS.ErrnoException).code === 'ENOENT') return;
+ log(`could not sweep stale session directories: ${err}`);
+ }
+}