@monoes/monobrowse 1.0.6 → 1.0.7

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@monoes/monobrowse",
-  "version": "1.0.6",
-  "description": "Native browser automation via Chrome DevTools Protocol — the engine powering monomind browse",
+  "version": "1.0.7",
+  "description": "Native browser automation via Chrome DevTools Protocol \u2014 the engine powering monomind browse",
   "type": "module",
   "bin": {
     "monobrowse": "./dist/src/cli.js"
@@ -34,7 +34,10 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "build": "tsc && mkdir -p dist/src/browser/dashboard && cp src/browser/dashboard/ui.html dist/src/browser/dashboard/ui.html",
+    "build": "tsc && node ../../../scripts/build-fs.mjs copy-into dist/src/browser/dashboard src/browser/dashboard/ui.html",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "prebuild": "node ../../../scripts/build-fs.mjs clean dist tsconfig.tsbuildinfo",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -50,7 +53,7 @@
     "email": "nokhodian@gmail.com",
     "url": "https://github.com/nokhodian"
   },
-  "license": "MIT",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/monoes/monomind.git",
@@ -61,6 +64,7 @@
     "ws": "^8.21.0"
   },
   "devDependencies": {
-    "typescript": "^7.0.2"
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.4"
   }
 }

package/src/__tests__/adapters.test.ts

@@ -0,0 +1,125 @@
+/**
+ * Platform adapters are pure declarations plus two tiny page-probing methods.
+ * A fake PageInterface (evaluate + url) is all that's needed — no browser.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { adapters, getAdapter, type PageInterface } from '../browser/adapters/index.js';
+
+const PLATFORMS = ['linkedin', 'instagram', 'x', 'gemini', 'google', 'microsoft'] as const;
+
+function fakePage(opts: { evaluate?: unknown; url?: string } = {}): PageInterface & {
+  evaluated: string[];
+} {
+  const evaluated: string[] = [];
+  return {
+    evaluated,
+    async evaluate<T>(expression: string): Promise<T> {
+      evaluated.push(expression);
+      return opts.evaluate as T;
+    },
+    async url(): Promise<string> {
+      return opts.url ?? 'https://example.test/';
+    },
+  };
+}
+
+describe('getAdapter', () => {
+  it('returns the adapter whose `platform` matches its registry key', () => {
+    for (const key of PLATFORMS) {
+      expect(getAdapter(key).platform).toBe(key);
+    }
+  });
+
+  it('throws for an unknown platform, listing the supported ones', () => {
+    expect(() => getAdapter('myspace')).toThrow(
+      `Unknown platform: myspace. Supported: ${PLATFORMS.join(', ')}`
+    );
+  });
+
+  it('is case-sensitive (no silent normalization)', () => {
+    expect(() => getAdapter('LinkedIn')).toThrow(/Unknown platform/);
+  });
+
+  it('registers exactly the documented platform set', () => {
+    expect([...adapters.keys()]).toEqual([...PLATFORMS]);
+  });
+});
+
+describe('adapter invariants', () => {
+  for (const key of PLATFORMS) {
+    describe(key, () => {
+      const a = getAdapter(key);
+
+      it('exposes an https baseURL with no trailing slash', () => {
+        expect(a.baseURL).toMatch(/^https:\/\//);
+        expect(a.baseURL.endsWith('/')).toBe(false);
+        expect(() => new URL(a.baseURL)).not.toThrow();
+      });
+
+      it('exposes a parseable https loginURL', () => {
+        const login = a.loginURL();
+        expect(login).toMatch(/^https:\/\//);
+        expect(() => new URL(login)).not.toThrow();
+      });
+
+      it('lists reservedPaths as non-empty root-anchored paths', () => {
+        expect(a.reservedPaths.length).toBeGreaterThan(0);
+        for (const p of a.reservedPaths) expect(p.startsWith('/')).toBe(true);
+      });
+    });
+  }
+});
+
+describe('isLoggedIn', () => {
+  it('coerces the page probe to the boolean the caller expects', async () => {
+    await expect(getAdapter('linkedin').isLoggedIn(fakePage({ evaluate: true }))).resolves.toBe(true);
+    await expect(getAdapter('linkedin').isLoggedIn(fakePage({ evaluate: false }))).resolves.toBe(false);
+  });
+
+  it('google short-circuits to false on the sign-in page without probing the DOM', async () => {
+    const page = fakePage({ url: 'https://accounts.google.com/signin/v2/identifier', evaluate: true });
+    await expect(getAdapter('google').isLoggedIn(page)).resolves.toBe(false);
+    expect(page.evaluated).toEqual([]);
+  });
+
+  it('google probes the DOM once past the sign-in page', async () => {
+    const page = fakePage({ url: 'https://mail.google.com/mail/u/0/', evaluate: true });
+    await expect(getAdapter('google').isLoggedIn(page)).resolves.toBe(true);
+    expect(page.evaluated).toHaveLength(1);
+  });
+
+  it('microsoft short-circuits on both login hostnames', async () => {
+    for (const url of [
+      'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',
+      'https://login.microsoft.com/whatever',
+    ]) {
+      const page = fakePage({ url, evaluate: true });
+      await expect(getAdapter('microsoft').isLoggedIn(page)).resolves.toBe(false);
+      expect(page.evaluated).toEqual([]);
+    }
+  });
+
+  it('microsoft probes the DOM elsewhere', async () => {
+    const page = fakePage({ url: 'https://teams.microsoft.com/', evaluate: true });
+    await expect(getAdapter('microsoft').isLoggedIn(page)).resolves.toBe(true);
+    expect(page.evaluated).toHaveLength(1);
+  });
+});
+
+describe('extractUsername', () => {
+  it('returns whatever the page evaluation yields', async () => {
+    for (const key of PLATFORMS) {
+      await expect(getAdapter(key).extractUsername(fakePage({ evaluate: 'someuser' }))).resolves.toBe(
+        'someuser'
+      );
+    }
+  });
+
+  it('propagates evaluation failures so callers can apply their own fallback', async () => {
+    const page: PageInterface = {
+      evaluate: vi.fn().mockRejectedValue(new Error('detached frame')),
+      url: async () => '',
+    };
+    await expect(getAdapter('x').extractUsername(page)).rejects.toThrow('detached frame');
+  });
+});

package/src/__tests__/cdp-client.test.ts

@@ -0,0 +1,375 @@
+/**
+ * CdpClient dispatch/guard logic and the two HTTP endpoint helpers.
+ *
+ * No browser and no WebSocket server: `connect()` is exercised against a fake
+ * `ws` module (so we can drive 'message'/'close'/'error' by hand), and
+ * fetchTargets/fetchNewTarget run against a stubbed global fetch.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+
+// --- fake `ws` -------------------------------------------------------------
+// Captures the most recently constructed socket so tests can drive its events.
+let lastSocket: FakeWs | null = null;
+
+class FakeWs {
+  handlers = new Map<string, Array<(...a: unknown[]) => void>>();
+  sent: string[] = [];
+  closed = false;
+  /** When set, the `send` callback receives this error instead of success. */
+  sendError: Error | null = null;
+
+  constructor(public url: string) {
+    lastSocket = this;
+  }
+
+  on(event: string, fn: (...a: unknown[]) => void): void {
+    if (!this.handlers.has(event)) this.handlers.set(event, []);
+    this.handlers.get(event)!.push(fn);
+  }
+
+  emit(event: string, ...args: unknown[]): void {
+    for (const fn of [...(this.handlers.get(event) ?? [])]) fn(...args);
+  }
+
+  send(data: string, cb?: (err?: Error) => void): void {
+    this.sent.push(data);
+    cb?.(this.sendError ?? undefined);
+  }
+
+  close(): void {
+    this.closed = true;
+  }
+
+  /** Convenience: deliver a CDP frame as the ws 'message' event does. */
+  deliver(msg: unknown): void {
+    this.emit('message', Buffer.from(JSON.stringify(msg)));
+  }
+}
+
+vi.mock('ws', () => ({ WebSocket: FakeWs }));
+
+const { CdpClient, fetchTargets, fetchNewTarget } = await import('../browser/cdp.js');
+type Client = InstanceType<typeof CdpClient>;
+
+/** Build a connected client plus its fake socket. */
+async function connected(): Promise<{ client: Client; ws: FakeWs }> {
+  const client = new CdpClient();
+  const p = client.connect('ws://127.0.0.1:9222/devtools/page/ABC');
+  lastSocket!.emit('open');
+  await p;
+  return { client, ws: lastSocket! };
+}
+
+beforeEach(() => {
+  lastSocket = null;
+});
+
+describe('connect', () => {
+  it('resolves on open and reports connected', async () => {
+    const { client, ws } = await connected();
+    expect(ws.url).toBe('ws://127.0.0.1:9222/devtools/page/ABC');
+    expect(client.isConnected()).toBe(true);
+  });
+
+  it('rejects when the socket errors before ever opening', async () => {
+    const client = new CdpClient();
+    const p = client.connect('ws://127.0.0.1:1/devtools');
+    lastSocket!.emit('error', new Error('ECONNREFUSED'));
+    await expect(p).rejects.toThrow('ECONNREFUSED');
+    expect(client.isConnected()).toBe(false);
+  });
+});
+
+describe('send', () => {
+  it('rejects when not connected rather than queueing forever', async () => {
+    await expect(new CdpClient().send('Page.enable')).rejects.toThrow('CDP not connected');
+  });
+
+  it('serializes id/method/params and omits sessionId when not given', async () => {
+    const { client, ws } = await connected();
+    void client.send('Page.navigate', { url: 'https://x.test' });
+    expect(JSON.parse(ws.sent[0]!)).toEqual({
+      id: 1,
+      method: 'Page.navigate',
+      params: { url: 'https://x.test' },
+    });
+  });
+
+  it('attaches sessionId when supplied and increments ids monotonically', async () => {
+    const { client, ws } = await connected();
+    void client.send('A', {}, 'S1');
+    void client.send('B', {}, 'S1');
+    expect(JSON.parse(ws.sent[0]!).id).toBe(1);
+    expect(JSON.parse(ws.sent[1]!)).toMatchObject({ id: 2, method: 'B', sessionId: 'S1' });
+  });
+
+  it('resolves with the response result matched by id', async () => {
+    const { client, ws } = await connected();
+    const a = client.send<{ v: string }>('A');
+    const b = client.send<{ v: string }>('B');
+    // Answer out of order to prove id matching, not FIFO.
+    ws.deliver({ id: 2, result: { v: 'second' } });
+    ws.deliver({ id: 1, result: { v: 'first' } });
+    expect(await a).toEqual({ v: 'first' });
+    expect(await b).toEqual({ v: 'second' });
+  });
+
+  it('resolves with {} when the response carries no result', async () => {
+    const { client, ws } = await connected();
+    const p = client.send('A');
+    ws.deliver({ id: 1 });
+    expect(await p).toEqual({});
+  });
+
+  it('rejects with the CDP error code and message', async () => {
+    const { client, ws } = await connected();
+    const p = client.send('Bad.method');
+    ws.deliver({ id: 1, error: { code: -32601, message: 'method not found' } });
+    await expect(p).rejects.toThrow('CDP error -32601: method not found');
+  });
+
+  it('rejects and forgets the command when the socket send callback errors', async () => {
+    const { client, ws } = await connected();
+    ws.sendError = new Error('socket write failed');
+    await expect(client.send('A')).rejects.toThrow('socket write failed');
+    // Not left pending: a later close() must not try to reject it a second time.
+    ws.sendError = null;
+    expect(() => client.close()).not.toThrow();
+  });
+
+  it('refuses to exceed the 1000 in-flight command cap', async () => {
+    const { client } = await connected();
+    const inflight = Array.from({ length: 1000 }, () => client.send('A').catch(() => {}));
+    await expect(client.send('A')).rejects.toThrow('CDP command queue full (>1000 in-flight commands)');
+    client.close();
+    await Promise.all(inflight);
+  });
+
+  describe('#115: default timeout (a response that never arrives must not hang forever)', () => {
+    beforeEach(() => vi.useFakeTimers());
+    afterEach(() => vi.useRealTimers());
+
+    it('rejects a command with no response after the default 30s timeout', async () => {
+      const { client } = await connected();
+      const p = client.send('Runtime.evaluate');
+      const assertion = expect(p).rejects.toThrow('CDP command "Runtime.evaluate" timed out after 30000ms');
+      await vi.advanceTimersByTimeAsync(30_000);
+      await assertion;
+    });
+
+    it('honors a caller-supplied timeout shorter than the default', async () => {
+      const { client } = await connected();
+      const p = client.send('Runtime.evaluate', {}, undefined, 500);
+      const assertion = expect(p).rejects.toThrow('timed out after 500ms');
+      await vi.advanceTimersByTimeAsync(500);
+      await assertion;
+    });
+
+    it('timeoutMs: 0 disables the timeout entirely', async () => {
+      const { client, ws } = await connected();
+      const p = client.send('A', {}, undefined, 0);
+      await vi.advanceTimersByTimeAsync(60_000);
+      // Still pending — no timeout fired.
+      let settled = false;
+      void p.then(() => { settled = true; }).catch(() => { settled = true; });
+      await Promise.resolve();
+      expect(settled).toBe(false);
+      ws.deliver({ id: 1, result: {} });
+      await expect(p).resolves.toEqual({});
+    });
+
+    it('a response arriving before the timeout clears the timer (does not also reject later)', async () => {
+      const { client, ws } = await connected();
+      const p = client.send('A');
+      ws.deliver({ id: 1, result: { ok: true } });
+      await expect(p).resolves.toEqual({ ok: true });
+      // Advancing past the timeout window must not throw/reject anything further.
+      await vi.advanceTimersByTimeAsync(30_000);
+    });
+  });
+
+  describe('#115: Target.targetCrashed / targetDestroyed flush pending commands', () => {
+    it('targetCrashed rejects in-flight commands instead of leaving them pending', async () => {
+      const { client, ws } = await connected();
+      const p = client.send('Runtime.evaluate');
+      ws.deliver({ method: 'Target.targetCrashed', params: {} });
+      await expect(p).rejects.toThrow('CDP target crashed');
+      expect(client.isConnected()).toBe(false);
+    });
+
+    it('targetDestroyed rejects in-flight commands', async () => {
+      const { client, ws } = await connected();
+      const p = client.send('Runtime.evaluate');
+      ws.deliver({ method: 'Target.targetDestroyed', params: {} });
+      await expect(p).rejects.toThrow('CDP target destroyed');
+    });
+  });
+});
+
+describe('event dispatch', () => {
+  it('routes events to listeners with params and sessionId', async () => {
+    const { client, ws } = await connected();
+    const seen: Array<[Record<string, unknown>, string | undefined]> = [];
+    client.on('Page.loadEventFired', (params, sid) => seen.push([params, sid]));
+    ws.deliver({ method: 'Page.loadEventFired', params: { timestamp: 5 }, sessionId: 'S1' });
+    expect(seen).toEqual([[{ timestamp: 5 }, 'S1']]);
+  });
+
+  it('passes {} when the event has no params', async () => {
+    const { client, ws } = await connected();
+    const seen: Array<Record<string, unknown>> = [];
+    client.on('E', (p) => seen.push(p));
+    ws.deliver({ method: 'E' });
+    expect(seen).toEqual([{}]);
+  });
+
+  it('the returned off() unsubscribes', async () => {
+    const { client, ws } = await connected();
+    let count = 0;
+    const off = client.on('E', () => count++);
+    ws.deliver({ method: 'E' });
+    off();
+    ws.deliver({ method: 'E' });
+    expect(count).toBe(1);
+  });
+
+  it('isolates a throwing listener so siblings still run', async () => {
+    const { client, ws } = await connected();
+    let reached = false;
+    client.on('E', () => {
+      throw new Error('listener blew up');
+    });
+    client.on('E', () => {
+      reached = true;
+    });
+    expect(() => ws.deliver({ method: 'E' })).not.toThrow();
+    expect(reached).toBe(true);
+  });
+
+  it('swallows malformed frames instead of crashing the socket', async () => {
+    const { client, ws } = await connected();
+    expect(() => ws.emit('message', Buffer.from('{not json'))).not.toThrow();
+    expect(client.isConnected()).toBe(true);
+  });
+
+  it('caps listeners per event at 100', async () => {
+    const { client } = await connected();
+    for (let i = 0; i < 100; i++) client.on('E', () => {});
+    expect(() => client.on('E', () => {})).toThrow('CDP event listener limit reached for event: E');
+    // The cap is per event name, not global.
+    expect(() => client.on('OtherEvent', () => {})).not.toThrow();
+  });
+});
+
+describe('once / onceWithOff', () => {
+  it('resolves on the first matching event and self-unsubscribes', async () => {
+    const { client, ws } = await connected();
+    const p = client.once('E');
+    ws.deliver({ method: 'E', params: { n: 1 } });
+    ws.deliver({ method: 'E', params: { n: 2 } });
+    expect(await p).toEqual({ n: 1 });
+  });
+
+  it('filters by sessionId when one is given', async () => {
+    const { client, ws } = await connected();
+    const p = client.once('E', 'S1');
+    ws.deliver({ method: 'E', params: { from: 'S2' }, sessionId: 'S2' });
+    ws.deliver({ method: 'E', params: { from: 'S1' }, sessionId: 'S1' });
+    expect(await p).toEqual({ from: 'S1' });
+  });
+
+  it('onceWithOff returns a canceller that stops the waiter from firing', async () => {
+    const { client, ws } = await connected();
+    let settled = false;
+    const [promise, off] = client.onceWithOff('E');
+    void promise.then(() => {
+      settled = true;
+    });
+    off();
+    ws.deliver({ method: 'E' });
+    await Promise.resolve();
+    expect(settled).toBe(false);
+  });
+});
+
+describe('teardown paths', () => {
+  it('close() rejects every pending command, drops listeners and closes the socket', async () => {
+    const { client, ws } = await connected();
+    const pending = client.send('A');
+    let events = 0;
+    client.on('E', () => events++);
+
+    client.close();
+
+    await expect(pending).rejects.toThrow('CDP connection closed');
+    expect(ws.closed).toBe(true);
+    expect(client.isConnected()).toBe(false);
+    ws.deliver({ method: 'E' });
+    expect(events).toBe(0);
+  });
+
+  it('a socket "close" event rejects pending commands', async () => {
+    const { client, ws } = await connected();
+    const pending = client.send('A');
+    ws.emit('close');
+    await expect(pending).rejects.toThrow('CDP connection closed');
+    expect(client.isConnected()).toBe(false);
+  });
+
+  it('a post-connect "error" flushes pending commands with that error', async () => {
+    const { client, ws } = await connected();
+    const pending = client.send('A');
+    ws.emit('error', new Error('EPIPE'));
+    await expect(pending).rejects.toThrow('EPIPE');
+    expect(client.isConnected()).toBe(false);
+  });
+});
+
+describe('fetchTargets / fetchNewTarget', () => {
+  const realFetch = globalThis.fetch;
+  afterEach(() => {
+    globalThis.fetch = realFetch;
+  });
+
+  function stubFetch(impl: (url: string, init?: RequestInit) => Response): ReturnType<typeof vi.fn> {
+    const fn = vi.fn((url: string, init?: RequestInit) => Promise.resolve(impl(url, init)));
+    globalThis.fetch = fn as unknown as typeof fetch;
+    return fn;
+  }
+
+  it('fetchTargets hits /json/list on the given port', async () => {
+    const fn = stubFetch(() => new Response(JSON.stringify([{ id: 'T1', type: 'page' }]), { status: 200 }));
+    await expect(fetchTargets(9333)).resolves.toEqual([{ id: 'T1', type: 'page' }]);
+    expect(fn.mock.calls[0]![0]).toBe('http://127.0.0.1:9333/json/list');
+  });
+
+  it('fetchTargets throws on a non-OK response', async () => {
+    stubFetch(() => new Response('nope', { status: 500, statusText: 'Internal Server Error' }));
+    await expect(fetchTargets(9222)).rejects.toThrow('Failed to fetch targets: Internal Server Error');
+  });
+
+  it('fetchNewTarget uses PUT and percent-encodes the URL', async () => {
+    const fn = stubFetch(() => new Response(JSON.stringify({ id: 'T2' }), { status: 200 }));
+    await expect(fetchNewTarget(9222, 'https://x.test/a?b=1&c=2')).resolves.toEqual({ id: 'T2' });
+    const [url, init] = fn.mock.calls[0] as [string, RequestInit];
+    expect(init.method).toBe('PUT');
+    expect(url).toBe(
+      'http://127.0.0.1:9222/json/new?' + encodeURIComponent('https://x.test/a?b=1&c=2')
+    );
+    // The query separators of the target URL must not leak into Chrome's own query.
+    expect(url.split('?').length).toBe(2);
+  });
+
+  it('fetchNewTarget throws on a non-OK response', async () => {
+    stubFetch(() => new Response('', { status: 405, statusText: 'Method Not Allowed' }));
+    await expect(fetchNewTarget(9222, 'about:blank')).rejects.toThrow(
+      'Failed to create target: Method Not Allowed'
+    );
+  });
+
+  it('rejects responses over the 10 MB body cap instead of parsing them', async () => {
+    const huge = JSON.stringify([{ pad: 'x'.repeat(11 * 1024 * 1024) }]);
+    stubFetch(() => new Response(huge, { status: 200 }));
+    await expect(fetchTargets(9222)).rejects.toThrow(/CDP response too large: \d+ bytes/);
+  });
+});

package/src/__tests__/close-browser.test.ts

@@ -0,0 +1,141 @@
+/**
+ * closeBrowser()'s cross-process PID-kill fallback (browser.ts) — previously
+ * had zero test coverage anywhere in this package (found in a review pass
+ * after commit c4847e22). Covers:
+ *   - using a persisted PID when the in-process launchedPids map is empty
+ *     (the always-true case for a fresh CLI invocation)
+ *   - rejecting a persisted PID that is too old to trust (staleness bound)
+ *   - a liveness check (process.kill(pid, 0)) gating the SIGKILL itself
+ *
+ * No real Chrome or child process is spawned: Browser.close is driven via a
+ * fake `ws` socket (same pattern as cdp-client.test.ts), and process.kill is
+ * spied on rather than actually signaling anything.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdtemp, rm, mkdir, writeFile } from 'fs/promises';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+let lastSocket: FakeWs | null = null;
+
+class FakeWs {
+  handlers = new Map<string, Array<(...a: unknown[]) => void>>();
+  constructor(public url: string) {
+    lastSocket = this;
+  }
+  on(event: string, fn: (...a: unknown[]) => void): void {
+    if (!this.handlers.has(event)) this.handlers.set(event, []);
+    this.handlers.get(event)!.push(fn);
+  }
+  emit(event: string, ...args: unknown[]): void {
+    for (const fn of [...(this.handlers.get(event) ?? [])]) fn(...args);
+  }
+  send(_data: string, cb?: (err?: Error) => void): void {
+    // Never call cb — simulates a hung Browser.close so closeBrowser's own
+    // BROWSER_CLOSE_TIMEOUT_MS race is what settles it (ungraceful path).
+    void cb;
+  }
+  close(): void {}
+  deliver(msg: unknown): void {
+    this.emit('message', Buffer.from(JSON.stringify(msg)));
+  }
+}
+
+vi.mock('ws', () => ({ WebSocket: FakeWs }));
+
+let tempDir: string;
+let killSpy: ReturnType<typeof vi.spyOn>;
+
+beforeEach(async () => {
+  vi.useFakeTimers();
+  lastSocket = null;
+  tempDir = await mkdtemp(join(tmpdir(), 'monobrowse-close-test-'));
+  vi.spyOn(process, 'cwd').mockReturnValue(tempDir);
+  killSpy = vi.spyOn(process, 'kill').mockImplementation(() => true as never);
+});
+
+afterEach(async () => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+async function writePersistedPort(port: number, pid: number, savedAt: number): Promise<void> {
+  const dir = join(tempDir, '.monomind', 'monobrowse');
+  await mkdir(dir, { recursive: true });
+  await writeFile(join(dir, 'active-port.json'), JSON.stringify({ port, pid, launched: true, savedAt }), 'utf-8');
+}
+
+async function connectedClient() {
+  vi.resetModules();
+  const { CdpClient } = await import('../browser/cdp.js');
+  const client = new CdpClient();
+  const p = client.connect('ws://127.0.0.1:9333/devtools/page/ABC');
+  lastSocket!.emit('open');
+  await p;
+  return client;
+}
+
+describe('#115 review follow-up: closeBrowser() cross-process PID-kill fallback', () => {
+  it('uses a fresh persisted PID (in-process map empty) and SIGKILLs it on an ungraceful close', async () => {
+    vi.resetModules();
+    const { closeBrowser, getLaunchedPid } = await import('../browser/browser.js');
+    const port = 9333;
+    await writePersistedPort(port, 54321, Date.now());
+    // Confirm the in-process map really is empty for this port (fresh module state).
+    expect(getLaunchedPid(port)).toBeUndefined();
+
+    const client = await connectedClient();
+    const closePromise = closeBrowser(client, port);
+    await vi.advanceTimersByTimeAsync(3000); // BROWSER_CLOSE_TIMEOUT_MS
+    await closePromise;
+
+    expect(killSpy).toHaveBeenCalledWith(54321, 0);
+    expect(killSpy).toHaveBeenCalledWith(54321, 'SIGKILL');
+  });
+
+  it('#124-review: does not trust a persisted PID older than the staleness bound', async () => {
+    vi.resetModules();
+    const { closeBrowser } = await import('../browser/browser.js');
+    const port = 9334;
+    const twoDaysAgo = Date.now() - 2 * 24 * 60 * 60 * 1000;
+    await writePersistedPort(port, 99999, twoDaysAgo);
+
+    const client = await connectedClient();
+    const closePromise = closeBrowser(client, port);
+    await vi.advanceTimersByTimeAsync(3000);
+    await closePromise;
+
+    expect(killSpy).not.toHaveBeenCalled();
+  });
+
+  it('#124-review: a persisted PID that is no longer alive is not force-killed (liveness check via kill(pid,0))', async () => {
+    vi.resetModules();
+    const { closeBrowser } = await import('../browser/browser.js');
+    const port = 9335;
+    await writePersistedPort(port, 11111, Date.now());
+    killSpy.mockImplementation((_pid: unknown, signal?: unknown) => {
+      if (signal === 0) throw Object.assign(new Error('ESRCH'), { code: 'ESRCH' });
+      return true as never;
+    });
+
+    const client = await connectedClient();
+    const closePromise = closeBrowser(client, port);
+    await vi.advanceTimersByTimeAsync(3000);
+    await closePromise;
+
+    expect(killSpy).toHaveBeenCalledWith(11111, 0);
+    expect(killSpy).not.toHaveBeenCalledWith(11111, 'SIGKILL');
+  });
+
+  it('no persisted port file at all — closeBrowser is a no-op, no kill attempted', async () => {
+    vi.resetModules();
+    const { closeBrowser } = await import('../browser/browser.js');
+    const client = await connectedClient();
+    const closePromise = closeBrowser(client, 9336);
+    await vi.advanceTimersByTimeAsync(3000);
+    await closePromise;
+
+    expect(killSpy).not.toHaveBeenCalled();
+  });
+});