Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
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.tsnew file mode 100644index 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.tsindex 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 thediff --git a/console/packages/switch-agent-runtime/src/reap.test.ts b/console/packages/switch-agent-runtime/src/reap.test.tsnew file mode 100644index 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.tsnew file mode 100644index 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}`);+ }+}