devharness 0.8.0

package/build/supervisor/child-manager.js

@@ -0,0 +1,148 @@
+/**
+ * Spawns and kills the real MCP server as a child process.
+ *
+ * Mirrors the SIGTERM(process-group)->grace-period->SIGKILL(process-group)
+ * escalation pattern used elsewhere in this repo (src/runners/native-runner.ts
+ * `stop()`), but - unlike that runner, which only ever holds a bare pid it
+ * may have recovered across a process restart - this always has a live
+ * ChildProcess handle, so completion is driven by Node's own 'exit' event
+ * rather than external process.kill(pid, 0) polling. That avoids any race
+ * between two independent "is it dead yet" mechanisms.
+ *
+ * Deliberately does NOT call `.unref()` on the spawned child (unlike
+ * native-runner.ts, whose children are meant to outlive it) - the child here
+ * must never outlive this supervisor.
+ */
+import { spawn } from 'child_process';
+export class ChildManager {
+    opts;
+    child = null;
+    onExitCallback = null;
+    killGraceMs;
+    suspendGraceMs;
+    constructor(opts) {
+        this.opts = opts;
+        this.killGraceMs = opts.killGraceMs ?? 3000;
+        this.suspendGraceMs = opts.suspendGraceMs ?? 15000;
+    }
+    /** Registered once; fires for every child this instance ever spawns. */
+    onExit(callback) {
+        this.onExitCallback = callback;
+    }
+    spawn() {
+        const child = spawn(this.opts.execPath, [this.opts.scriptPath, ...this.opts.extraArgs], {
+            cwd: this.opts.cwd,
+            stdio: ['pipe', 'pipe', 'inherit'],
+            detached: true,
+        });
+        this.child = child;
+        child.on('exit', (code, signal) => {
+            if (this.child === child) {
+                this.child = null;
+            }
+            this.onExitCallback?.({ code, signal });
+        });
+        if (!child.stdout || !child.stdin) {
+            throw new Error('Child process did not provide piped stdio streams');
+        }
+        return { stdout: child.stdout, stdin: child.stdin };
+    }
+    isRunning() {
+        return this.child !== null;
+    }
+    /**
+     * Ask the child to release everything it holds - Chrome, managed dev
+     * servers, monitors - and exit, resolving once it has actually gone.
+     *
+     * SIGUSR2 rather than SIGUSR1 because Node reserves SIGUSR1 for starting its
+     * own inspector, and it is sent to the child alone rather than to its
+     * process group: the point is to give the child a chance to shut its own
+     * children down in order, not to kill them out from under it. If it doesn't
+     * finish in time, kill() escalates through the usual SIGTERM/SIGKILL path.
+     */
+    async suspend() {
+        const child = this.child;
+        if (!child || child.pid === undefined) {
+            return;
+        }
+        const exited = await new Promise((resolve) => {
+            let settled = false;
+            const onExit = () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve(true);
+            };
+            child.once('exit', onExit);
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                child.off('exit', onExit);
+                resolve(false);
+            }, this.suspendGraceMs);
+            try {
+                process.kill(child.pid, 'SIGUSR2');
+            }
+            catch {
+                settled = true;
+                clearTimeout(timer);
+                child.off('exit', onExit);
+                resolve(false); // already gone, or unsignalable - let kill() settle it
+            }
+        });
+        if (!exited) {
+            await this.kill();
+        }
+    }
+    /** Kill the current child (if any) and resolve once it has actually exited. */
+    async kill() {
+        const child = this.child;
+        if (!child || child.pid === undefined) {
+            return;
+        }
+        const pid = child.pid;
+        await new Promise((resolve) => {
+            let settled = false;
+            let killTimer;
+            const onExit = () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(killTimer);
+                resolve();
+            };
+            child.once('exit', onExit);
+            try {
+                process.kill(-pid, 'SIGTERM');
+            }
+            catch {
+                try {
+                    process.kill(pid, 'SIGTERM');
+                }
+                catch {
+                    // Already dead
+                }
+            }
+            killTimer = setTimeout(() => {
+                if (settled)
+                    return;
+                try {
+                    process.kill(-pid, 'SIGKILL');
+                }
+                catch {
+                    try {
+                        process.kill(pid, 'SIGKILL');
+                    }
+                    catch {
+                        // Already dead
+                    }
+                }
+                // Deliberately don't resolve here - wait for the real 'exit' event
+                // above so we never consider kill() done before the process is gone.
+            }, this.killGraceMs);
+        });
+    }
+}
+//# sourceMappingURL=child-manager.js.map

package/build/supervisor/child-manager.js.map

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

package/build/supervisor/child-manager.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=child-manager.test.d.ts.map

package/build/supervisor/child-manager.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-manager.test.d.ts","sourceRoot":"","sources":["../../src/supervisor/child-manager.test.ts"],"names":[],"mappings":""}

package/build/supervisor/child-manager.test.js

@@ -0,0 +1,107 @@
+import { describe, it, expect } from 'vitest';
+import * as path from 'path';
+import * as url from 'url';
+import { ChildManager } from './child-manager.js';
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+const FIXTURE_PATH = path.join(__dirname, '__fixtures__', 'test-child.mjs');
+describe('ChildManager (real subprocess)', () => {
+    it('spawns a child and kill() resolves once it exits on SIGTERM', async () => {
+        const manager = new ChildManager({
+            execPath: process.execPath,
+            scriptPath: FIXTURE_PATH,
+            extraArgs: [],
+            cwd: __dirname,
+            killGraceMs: 3000,
+        });
+        manager.spawn();
+        expect(manager.isRunning()).toBe(true);
+        await manager.kill();
+        expect(manager.isRunning()).toBe(false);
+    }, 10000);
+    it('escalates to SIGKILL after the grace period for a child that ignores SIGTERM', async () => {
+        const manager = new ChildManager({
+            execPath: process.execPath,
+            scriptPath: FIXTURE_PATH,
+            extraArgs: ['ignore-sigterm'],
+            cwd: __dirname,
+            killGraceMs: 300, // short for test speed
+        });
+        manager.spawn();
+        // Give the child a moment to actually register its SIGTERM-ignoring handler
+        // before we send the signal, or we'd race its own startup.
+        await new Promise((resolve) => setTimeout(resolve, 200));
+        const start = Date.now();
+        await manager.kill();
+        const elapsed = Date.now() - start;
+        expect(manager.isRunning()).toBe(false);
+        // Should have waited roughly the grace period before SIGKILL landed, not exited instantly.
+        expect(elapsed).toBeGreaterThanOrEqual(250);
+    }, 10000);
+    it('fires onExit for a child that crashes on its own', async () => {
+        const manager = new ChildManager({
+            execPath: process.execPath,
+            scriptPath: FIXTURE_PATH,
+            extraArgs: ['crash'],
+            cwd: __dirname,
+        });
+        const exitInfo = await new Promise((resolve) => {
+            manager.onExit((info) => resolve(info));
+            manager.spawn();
+        });
+        expect(exitInfo.code).toBe(1);
+    }, 10000);
+    it('suspend() signals the child and resolves once it has released and exited', async () => {
+        const manager = new ChildManager({
+            execPath: process.execPath,
+            scriptPath: FIXTURE_PATH,
+            extraArgs: [],
+            cwd: __dirname,
+            suspendGraceMs: 3000,
+        });
+        manager.spawn();
+        await new Promise((resolve) => setTimeout(resolve, 200)); // let its handler register
+        await manager.suspend();
+        expect(manager.isRunning()).toBe(false);
+    }, 10000);
+    it('suspend() escalates to a kill for a child that never finishes releasing', async () => {
+        const manager = new ChildManager({
+            execPath: process.execPath,
+            scriptPath: FIXTURE_PATH,
+            extraArgs: ['ignore-suspend'],
+            cwd: __dirname,
+            suspendGraceMs: 300,
+            killGraceMs: 300,
+        });
+        manager.spawn();
+        await new Promise((resolve) => setTimeout(resolve, 200));
+        await manager.suspend();
+        expect(manager.isRunning()).toBe(false);
+    }, 10000);
+    it('suspend() on an already-dead child resolves immediately without throwing', async () => {
+        const manager = new ChildManager({
+            execPath: process.execPath,
+            scriptPath: FIXTURE_PATH,
+            extraArgs: ['crash'],
+            cwd: __dirname,
+        });
+        await new Promise((resolve) => {
+            manager.onExit(() => resolve());
+            manager.spawn();
+        });
+        await expect(manager.suspend()).resolves.toBeUndefined();
+    }, 10000);
+    it('kill() on an already-dead child resolves immediately without throwing', async () => {
+        const manager = new ChildManager({
+            execPath: process.execPath,
+            scriptPath: FIXTURE_PATH,
+            extraArgs: ['crash'],
+            cwd: __dirname,
+        });
+        await new Promise((resolve) => {
+            manager.onExit(() => resolve());
+            manager.spawn();
+        });
+        await expect(manager.kill()).resolves.toBeUndefined();
+    }, 10000);
+});
+//# sourceMappingURL=child-manager.test.js.map

package/build/supervisor/child-manager.test.js.map

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

package/build/supervisor/client-watcher.d.ts

@@ -0,0 +1,48 @@
+export interface ProcessInfo {
+    ppid: number;
+    command: string;
+}
+export interface ProcessProbe {
+    /** Parent pid + command for a pid, or null if the pid is gone/unreadable. */
+    info(pid: number): ProcessInfo | null;
+    /** Whether the pid still exists. */
+    isAlive(pid: number): boolean;
+}
+export interface ClientIdentity {
+    pid: number;
+    command: string;
+}
+/** Reads process info via `ps`. Unavailable on Windows, which has no `ps`. */
+export declare const systemProcessProbe: ProcessProbe;
+/**
+ * Walk up from `startPid`'s parent and return the first ancestor that isn't
+ * launch plumbing, or null if there is none.
+ */
+export declare function resolveClientIdentity(startPid: number, probe: ProcessProbe, maxDepth?: number): ClientIdentity | null;
+export interface ClientWatcherOptions {
+    /** How often to check the client is still alive (default: 60s). */
+    pollIntervalMs?: number;
+    probe?: ProcessProbe;
+    logStderr?: (message: string) => void;
+}
+/**
+ * Polls the resolved client's liveness and calls back once, when it dies.
+ * Does nothing at all when no client could be resolved.
+ */
+export declare class ClientWatcher {
+    private readonly options;
+    private timer;
+    private readonly probe;
+    private readonly pollIntervalMs;
+    private readonly logStderr;
+    private client;
+    constructor(options?: ClientWatcherOptions);
+    getClient(): ClientIdentity | null;
+    /**
+     * Resolve the client and start watching. Returns the client it will watch,
+     * or null if none could be resolved (in which case nothing is watched).
+     */
+    start(startPid: number, onClientGone: (client: ClientIdentity) => void): ClientIdentity | null;
+    stop(): void;
+}
+//# sourceMappingURL=client-watcher.d.ts.map

package/build/supervisor/client-watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-watcher.d.ts","sourceRoot":"","sources":["../../src/supervisor/client-watcher.ts"],"names":[],"mappings":"AA+BA,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAAC;IACtC,oCAAoC;IACpC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AA4DD,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,EAAE,YAwBhC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,YAAY,EACnB,QAAQ,SAAK,GACZ,cAAc,GAAG,IAAI,CAYvB;AAED,MAAM,WAAW,oBAAoB;IACnC,mEAAmE;IACnE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC;AAED;;;GAGG;AACH,qBAAa,aAAa;IAOZ,OAAO,CAAC,QAAQ,CAAC,OAAO;IANpC,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4B;IACtD,OAAO,CAAC,MAAM,CAA+B;gBAEhB,OAAO,GAAE,oBAAyB;IAM/D,SAAS,IAAI,cAAc,GAAG,IAAI;IAIlC;;;OAGG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,GAAG,cAAc,GAAG,IAAI;IA0B9F,IAAI,IAAI,IAAI;CAMb"}

package/build/supervisor/client-watcher.js

@@ -0,0 +1,186 @@
+/**
+ * Watches the MCP client (Claude Code, the Claude desktop app, an IDE) that
+ * this supervisor was launched to serve, and reports when it is gone.
+ *
+ * WHY THIS EXISTS
+ * The supervisor already shuts down on stdin end/close, which is supposed to
+ * catch a client that dies without signalling. It does not fire when the
+ * client was launched through `npx`: the `npm exec` wrapper sits between the
+ * client and this process, survives the client's death (reparented to init),
+ * and keeps holding the write end of our stdin pipe. No EOF ever arrives, so
+ * the whole tree - supervisor, real server, its Chrome and dev servers - lives
+ * on for days holding memory nobody is asking it to hold (issue #138).
+ *
+ * So instead of waiting to be told, we find out who the client actually is and
+ * check whether it is still alive.
+ *
+ * FINDING THE CLIENT
+ * Walk up the process ancestry from this process and take the first ancestor
+ * that isn't part of the launch plumbing - Node itself, npm/npx, a shell. For
+ * the three shapes seen in the wild that lands on:
+ *   node <- npm exec <- claude                          => claude
+ *   node <- npm exec <- disclaimer <- Claude.app         => disclaimer (the
+ *       Claude app's own helper - it dies with the app, which is what matters)
+ *   node <- code helper                                  => the IDE helper
+ *
+ * If the walk finds nothing but plumbing all the way to pid 1, there is no
+ * client to watch and reaping is disabled - better to leak than to kill a tree
+ * that is still serving someone.
+ */
+import { execFileSync } from 'child_process';
+/**
+ * Package managers and shells that are only ever launch plumbing, never the
+ * client itself. Matched against the command's leading token's basename.
+ */
+const PLUMBING = new Set([
+    'npm',
+    'npx',
+    'pnpm',
+    'yarn',
+    'bunx',
+    'sh',
+    'bash',
+    'zsh',
+    'fish',
+    'dash',
+    'ksh',
+    'env',
+    'exec',
+    'login',
+]);
+/** Runtimes that are plumbing or client depending on what they are running. */
+const RUNTIMES = new Set(['node', 'node.exe', 'nodejs', 'bun', 'deno']);
+/**
+ * Scripts that mean a runtime process is npm/npx machinery rather than the
+ * client. Anything else a runtime is running is treated as the client itself:
+ * an npm-installed MCP host appears in `ps` as `node .../cli.js`, and calling
+ * every node process plumbing would walk straight past it to the user's shell
+ * and terminal - which live for weeks, so the tree would never be reaped.
+ */
+const RUNTIME_PLUMBING_SCRIPTS = [
+    'npm-cli.js',
+    'npx-cli.js',
+    'npm-prefix.js',
+    '/node_modules/.bin/',
+    '/npm/bin/',
+    '/_npx/',
+    '/corepack/',
+];
+function isPlumbing(command) {
+    const tokens = command.trim().split(/\s+/);
+    const basename = (tokens[0] ?? '').split('/').pop() ?? '';
+    if (PLUMBING.has(basename))
+        return true;
+    if (RUNTIMES.has(basename)) {
+        // A bare runtime with no script (a REPL, or an unreadable command) tells
+        // us nothing; treat it as plumbing, as before.
+        const script = tokens.slice(1).find((token) => !token.startsWith('-'));
+        if (!script)
+            return true;
+        return RUNTIME_PLUMBING_SCRIPTS.some((marker) => script.includes(marker));
+    }
+    return false;
+}
+/** Reads process info via `ps`. Unavailable on Windows, which has no `ps`. */
+export const systemProcessProbe = {
+    info(pid) {
+        try {
+            const out = execFileSync('ps', ['-o', 'ppid=,command=', '-p', String(pid)], {
+                encoding: 'utf-8',
+                timeout: 2000,
+            }).trim();
+            if (!out)
+                return null;
+            const match = out.match(/^\s*(\d+)\s+(.*)$/);
+            if (!match)
+                return null;
+            return { ppid: Number(match[1]), command: match[2] };
+        }
+        catch {
+            return null;
+        }
+    },
+    isAlive(pid) {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (err) {
+            // EPERM means it exists but belongs to another user - still alive.
+            return err?.code === 'EPERM';
+        }
+    },
+};
+/**
+ * Walk up from `startPid`'s parent and return the first ancestor that isn't
+ * launch plumbing, or null if there is none.
+ */
+export function resolveClientIdentity(startPid, probe, maxDepth = 12) {
+    let current = probe.info(startPid);
+    for (let depth = 0; depth < maxDepth; depth++) {
+        if (!current || current.ppid <= 1)
+            return null;
+        const parent = probe.info(current.ppid);
+        if (!parent)
+            return null;
+        if (!isPlumbing(parent.command)) {
+            return { pid: current.ppid, command: parent.command };
+        }
+        current = { ppid: parent.ppid, command: parent.command };
+    }
+    return null;
+}
+/**
+ * Polls the resolved client's liveness and calls back once, when it dies.
+ * Does nothing at all when no client could be resolved.
+ */
+export class ClientWatcher {
+    options;
+    timer = null;
+    probe;
+    pollIntervalMs;
+    logStderr;
+    client = null;
+    constructor(options = {}) {
+        this.options = options;
+        this.probe = options.probe ?? systemProcessProbe;
+        this.pollIntervalMs = options.pollIntervalMs ?? 60_000;
+        this.logStderr = options.logStderr ?? (() => { });
+    }
+    getClient() {
+        return this.client;
+    }
+    /**
+     * Resolve the client and start watching. Returns the client it will watch,
+     * or null if none could be resolved (in which case nothing is watched).
+     */
+    start(startPid, onClientGone) {
+        if (process.platform === 'win32') {
+            this.logStderr('Client watcher disabled on Windows (no ps); relying on stdin close');
+            return null;
+        }
+        this.client = resolveClientIdentity(startPid, this.probe);
+        if (!this.client) {
+            this.logStderr('Could not identify the MCP client process; orphan reaping disabled');
+            return null;
+        }
+        const client = this.client;
+        this.logStderr(`Watching client PID ${client.pid} (${client.command.slice(0, 80)})`);
+        this.timer = setInterval(() => {
+            if (this.probe.isAlive(client.pid))
+                return;
+            this.stop();
+            this.logStderr(`Client PID ${client.pid} is gone; shutting down`);
+            onClientGone(client);
+        }, this.pollIntervalMs);
+        this.timer.unref?.();
+        return client;
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+}
+//# sourceMappingURL=client-watcher.js.map

package/build/supervisor/client-watcher.js.map

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

package/build/supervisor/client-watcher.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=client-watcher.test.d.ts.map

package/build/supervisor/client-watcher.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-watcher.test.d.ts","sourceRoot":"","sources":["../../src/supervisor/client-watcher.test.ts"],"names":[],"mappings":""}

package/build/supervisor/client-watcher.test.js

@@ -0,0 +1,121 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { ClientWatcher, resolveClientIdentity } from './client-watcher.js';
+/** Builds a probe over a fake process table: pid -> { ppid, command }. */
+function makeProbe(table, dead = new Set()) {
+    return {
+        info: (pid) => (dead.has(pid) ? null : table[pid] ?? null),
+        isAlive: (pid) => !dead.has(pid) && pid in table,
+    };
+}
+describe('resolveClientIdentity', () => {
+    it('finds the client through an npm exec wrapper', () => {
+        // node <- npm exec <- claude, the shape a `npx cdp-tools-mcp` launch takes
+        const probe = makeProbe({
+            100: { ppid: 200, command: '/opt/node/bin/node /path/.bin/cdp-tools-mcp' },
+            200: { ppid: 300, command: 'npm exec cdp-tools-mcp@latest' },
+            300: { ppid: 400, command: 'claude' },
+            400: { ppid: 1, command: '/bin/zsh' },
+        });
+        expect(resolveClientIdentity(100, probe)).toEqual({ pid: 300, command: 'claude' });
+    });
+    it('finds the desktop app helper below the app itself', () => {
+        const probe = makeProbe({
+            100: { ppid: 200, command: 'node .bin/cdp-tools-mcp' },
+            200: { ppid: 300, command: 'npm exec cdp-tools-mcp@latest' },
+            300: { ppid: 400, command: '/Applications/Claude.app/Contents/Helpers/disclaimer' },
+            400: { ppid: 1, command: '/Applications/Claude.app/Contents/MacOS/Claude' },
+        });
+        const client = resolveClientIdentity(100, probe);
+        expect(client?.pid).toBe(300);
+    });
+    it('treats an npm-installed node host as the client, not as plumbing', () => {
+        // The host itself is a node script here, so a rule that called every node
+        // process plumbing would walk past it to the shell and terminal - which
+        // outlive the client, leaving the tree unreaped.
+        const probe = makeProbe({
+            100: { ppid: 200, command: 'node /Users/x/.npm/_npx/abc/node_modules/.bin/cdp-tools-mcp' },
+            200: { ppid: 300, command: 'npm exec cdp-tools-mcp@latest' },
+            300: { ppid: 400, command: 'node /usr/local/lib/node_modules/@anthropic-ai/claude-code/cli.js' },
+            400: { ppid: 500, command: '/bin/zsh -l' },
+            500: { ppid: 1, command: '/Applications/iTerm.app/Contents/MacOS/iTerm2' },
+        });
+        expect(resolveClientIdentity(100, probe)?.pid).toBe(300);
+    });
+    it('still walks past npm and npx machinery running under node', () => {
+        const probe = makeProbe({
+            100: { ppid: 200, command: 'node /path/node_modules/.bin/cdp-tools-mcp' },
+            200: { ppid: 300, command: 'node /opt/homebrew/lib/node_modules/npm/bin/npm-cli.js exec' },
+            300: { ppid: 1, command: 'claude' },
+        });
+        expect(resolveClientIdentity(100, probe)?.pid).toBe(300);
+    });
+    it('treats a bare runtime with no script as plumbing', () => {
+        const probe = makeProbe({
+            100: { ppid: 200, command: 'node /path/.bin/cdp-tools-mcp' },
+            200: { ppid: 300, command: 'node' },
+            300: { ppid: 1, command: 'code-helper' },
+        });
+        expect(resolveClientIdentity(100, probe)?.pid).toBe(300);
+    });
+    it('returns null when every ancestor is launch plumbing', () => {
+        const probe = makeProbe({
+            100: { ppid: 200, command: 'node /path/node_modules/.bin/cdp-tools-mcp' },
+            200: { ppid: 300, command: 'npm exec cdp-tools-mcp@latest' },
+            300: { ppid: 1, command: '/bin/bash' },
+        });
+        expect(resolveClientIdentity(100, probe)).toBeNull();
+    });
+    it('returns null when the ancestry is unreadable', () => {
+        expect(resolveClientIdentity(100, makeProbe({}))).toBeNull();
+    });
+    it('gives up rather than looping on a deep ancestry', () => {
+        // Every entry is plumbing, so a bounded walk is the only thing that stops it.
+        const table = {};
+        for (let pid = 100; pid < 200; pid++) {
+            table[pid] = { ppid: pid + 1, command: 'npm exec something' };
+        }
+        expect(resolveClientIdentity(100, makeProbe(table), 5)).toBeNull();
+    });
+});
+describe('ClientWatcher', () => {
+    beforeEach(() => vi.useFakeTimers());
+    afterEach(() => vi.useRealTimers());
+    const TABLE = {
+        100: { ppid: 200, command: 'node .bin/cdp-tools-mcp' },
+        200: { ppid: 300, command: 'npm exec cdp-tools-mcp@latest' },
+        300: { ppid: 1, command: 'claude' },
+    };
+    it('calls back once the client is gone', () => {
+        const dead = new Set();
+        const watcher = new ClientWatcher({ pollIntervalMs: 1000, probe: makeProbe(TABLE, dead) });
+        const onGone = vi.fn();
+        expect(watcher.start(100, onGone)).toEqual({ pid: 300, command: 'claude' });
+        vi.advanceTimersByTime(3000);
+        expect(onGone).not.toHaveBeenCalled();
+        dead.add(300);
+        vi.advanceTimersByTime(1000);
+        expect(onGone).toHaveBeenCalledTimes(1);
+        expect(onGone).toHaveBeenCalledWith({ pid: 300, command: 'claude' });
+        // Stops polling after firing - one shutdown is enough.
+        vi.advanceTimersByTime(10_000);
+        expect(onGone).toHaveBeenCalledTimes(1);
+    });
+    it('watches nothing when no client can be identified', () => {
+        const watcher = new ClientWatcher({ pollIntervalMs: 1000, probe: makeProbe({}) });
+        const onGone = vi.fn();
+        expect(watcher.start(100, onGone)).toBeNull();
+        vi.advanceTimersByTime(60_000);
+        expect(onGone).not.toHaveBeenCalled();
+    });
+    it('stops polling when stopped', () => {
+        const dead = new Set();
+        const watcher = new ClientWatcher({ pollIntervalMs: 1000, probe: makeProbe(TABLE, dead) });
+        const onGone = vi.fn();
+        watcher.start(100, onGone);
+        watcher.stop();
+        dead.add(300);
+        vi.advanceTimersByTime(10_000);
+        expect(onGone).not.toHaveBeenCalled();
+    });
+});
+//# sourceMappingURL=client-watcher.test.js.map