@monoes/monobrowse 1.0.6 → 1.0.7

package/src/browser/browser.ts

@@ -8,11 +8,15 @@ import type { BrowserConfig, CdpTarget } from './types.js';
 import { CHROME_EXECUTABLES } from './types.js';
 import { enableConsoleCapture, setupConsoleCapture } from './console-log.js';
 import { setupDialogAutoHandling } from './dialog.js';
+import { loadActivePortInfo } from './ref-cache.js';
 
 const DEFAULT_PORT = 9222;
 const LAUNCH_TIMEOUT = 10_000;
 const POLL_INTERVAL = 200;
 const BROWSER_CLOSE_TIMEOUT_MS = 3000;
+// A cross-process persisted PID older than this is not trusted for the
+// SIGKILL fallback in closeBrowser() — see the call site for why.
+const PERSISTED_PID_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 
 // Tracks the PID of Chrome instances *we* spawned, keyed by CDP port, so
 // closeBrowser() has a kill fallback when the graceful `Browser.close` CDP
@@ -20,6 +24,19 @@ const BROWSER_CLOSE_TIMEOUT_MS = 3000;
 // to (already-running browser) are never recorded here — we only ever kill
 // processes we launched ourselves.
 const launchedPids = new Map<number, number>();
+// userDataDir per launched port — informational, persisted alongside the pid
+// so a later process could clean up the temp profile dir too if ever needed.
+const launchedUserDataDirs = new Map<number, string>();
+
+/** PID of the Chrome instance *this process* launched on `port`, if any. */
+export function getLaunchedPid(port: number): number | undefined {
+  return launchedPids.get(port);
+}
+
+/** userDataDir of the Chrome instance *this process* launched on `port`, if any. */
+export function getLaunchedUserDataDir(port: number): string | undefined {
+  return launchedUserDataDirs.get(port);
+}
 
 function findChrome(executablePath?: string): string {
   if (executablePath) {
@@ -185,9 +202,13 @@ async function launchOnFreePort(config: BrowserConfig, port: number): Promise<nu
     stdio: 'ignore',
   });
   child.unref();
-  if (child.pid) launchedPids.set(port, child.pid);
+  if (child.pid) {
+    launchedPids.set(port, child.pid);
+    launchedUserDataDirs.set(port, userDataDir);
+  }
 
-  const deadline = Date.now() + LAUNCH_TIMEOUT;
+  const launchTimeout = config.launchTimeoutMs ?? LAUNCH_TIMEOUT;
+  const deadline = Date.now() + launchTimeout;
   while (Date.now() < deadline) {
     await sleep(POLL_INTERVAL);
     if (await isPortOpen(port)) {
@@ -204,12 +225,12 @@ async function launchOnFreePort(config: BrowserConfig, port: number): Promise<nu
   // squatting the port" (confusing generic timeout otherwise) via a raw TCP probe.
   if (await isTcpPortOpen(port)) {
     throw new Error(
-      `Port ${port} is occupied by a non-Chrome process (TCP connection succeeds but no CDP response within ${LAUNCH_TIMEOUT}ms). ` +
+      `Port ${port} is occupied by a non-Chrome process (TCP connection succeeds but no CDP response within ${launchTimeout}ms). ` +
       `Free the port or pass a different one.`
     );
   }
 
-  throw new Error(`Chrome failed to start on port ${port} within ${LAUNCH_TIMEOUT}ms`);
+  throw new Error(`Chrome failed to start on port ${port} within ${launchTimeout}ms`);
 }
 
 export async function enableSessionDomains(client: CdpClient, sessionId: string): Promise<void> {
@@ -277,12 +298,43 @@ export async function closeBrowser(client: CdpClient, port: number): Promise<voi
     // fall through to PID-kill fallback below
   }
 
-  const pid = launchedPids.get(port);
-  if (pid === undefined) return; // not a process we launched — nothing to kill
+  let pid = launchedPids.get(port);
+  if (pid === undefined) {
+    // Fresh process (each CLI invocation is its own node process — see
+    // module header) — launchedPids is per-process and empty here even
+    // though a prior `open` in a DIFFERENT process launched this Chrome.
+    // Fall back to the PID that process persisted via saveActivePort().
+    try {
+      const persisted = await loadActivePortInfo();
+      if (persisted && persisted.port === port && persisted.launched && persisted.pid) {
+        // Bound how far we trust a cross-process PID: if the Chrome we
+        // launched died outside this flow (OOM-killed, host slept, etc.)
+        // without active-port.json ever being cleared, the OS can recycle
+        // that PID for an unrelated process. There is no cmdline/start-time
+        // check available portably, so a coarse age bound is the practical
+        // guard — a PID persisted more than a day ago is far more likely to
+        // be stale/reused than to still be the same live Chrome.
+        const age = persisted.savedAt !== undefined ? Date.now() - persisted.savedAt : undefined;
+        if (age === undefined || age <= PERSISTED_PID_MAX_AGE_MS) {
+          pid = persisted.pid;
+        }
+      }
+    } catch {
+      // best-effort — fall through to "nothing to kill" below
+    }
+  }
+  if (pid === undefined) return; // not a process we launched, or too stale to trust — nothing to kill
   launchedPids.delete(port);
 
+  // Liveness-check before every SIGKILL (not just the safety-net path below)
+  // — process.kill(pid, 0) throws ESRCH if the PID is no longer running,
+  // which also catches the case where the PID has already been recycled by
+  // an unrelated process that happens to have exited too.
   if (!gracefullyClosed) {
-    try { process.kill(pid, 'SIGKILL'); } catch { /* already exited */ }
+    try {
+      process.kill(pid, 0);
+      process.kill(pid, 'SIGKILL');
+    } catch { /* already exited, or never was — nothing to do */ }
     return;
   }
 

package/src/browser/cdp.ts

@@ -1,13 +1,41 @@
 import { WebSocket } from 'ws';
 import type { CdpCommand, CdpResponse, CdpTarget } from './types.js';
 
+// send() had no timeout of its own — a command whose response never arrives
+// (wedged/crashed renderer, dropped socket that never fires 'close') left a
+// pendingCommands entry forever, hanging whatever awaited it (and, since
+// most CLI actions await a single send(), the whole CLI process). Ad-hoc
+// timeouts were previously patched in at a handful of call sites (e.g.
+// actions.ts's evaluateJs) instead of here, so most commands had no
+// protection at all. This is the default for every send() unless a caller
+// passes 0 (no timeout) or a different value.
+export const DEFAULT_CDP_SEND_TIMEOUT_MS = 30_000;
+
 export class CdpClient {
   private ws: WebSocket | null = null;
-  private pendingCommands = new Map<number, { resolve: (r: CdpResponse) => void; reject: (e: Error) => void }>();
+  private pendingCommands = new Map<number, { resolve: (r: CdpResponse) => void; reject: (e: Error) => void; timer?: ReturnType<typeof setTimeout> }>();
   private eventListeners = new Map<string, Set<(params: Record<string, unknown>, sessionId?: string) => void>>();
   private nextId = 1;
   private connected = false;
 
+  constructor() {
+    // Target.targetCrashed/targetDestroyed fire over the same WS connection
+    // as command responses, but a crashed renderer's connection can otherwise
+    // sit open with no 'close'/'error' event ever firing — flush pending
+    // commands here so send() doesn't have to wait out its own timeout.
+    this.on('Target.targetCrashed', () => this.flushPending(new Error('CDP target crashed')));
+    this.on('Target.targetDestroyed', () => this.flushPending(new Error('CDP target destroyed')));
+  }
+
+  private flushPending(err: Error): void {
+    this.connected = false;
+    for (const { reject: r, timer } of this.pendingCommands.values()) {
+      if (timer) clearTimeout(timer);
+      r(err);
+    }
+    this.pendingCommands.clear();
+  }
+
   async connect(wsUrl: string): Promise<void> {
     return new Promise((resolve, reject) => {
       this.ws = new WebSocket(wsUrl);
@@ -22,18 +50,12 @@ export class CdpClient {
           reject(err);
         } else {
           // Post-connect: flush all pending commands — 'close' may not fire on all platforms
-          this.connected = false;
-          for (const { reject: r } of this.pendingCommands.values()) r(err);
-          this.pendingCommands.clear();
+          this.flushPending(err instanceof Error ? err : new Error(String(err)));
         }
       });
 
       this.ws.on('close', () => {
-        this.connected = false;
-        for (const { reject: r } of this.pendingCommands.values()) {
-          r(new Error('CDP connection closed'));
-        }
-        this.pendingCommands.clear();
+        this.flushPending(new Error('CDP connection closed'));
       });
 
       this.ws.on('message', (data) => {
@@ -62,7 +84,12 @@ export class CdpClient {
     });
   }
 
-  send<T = Record<string, unknown>>(method: string, params?: Record<string, unknown>, sessionId?: string): Promise<T> {
+  send<T = Record<string, unknown>>(
+    method: string,
+    params?: Record<string, unknown>,
+    sessionId?: string,
+    timeoutMs: number = DEFAULT_CDP_SEND_TIMEOUT_MS
+  ): Promise<T> {
     return new Promise((resolve, reject) => {
       if (!this.ws || !this.connected) {
         reject(new Error('CDP not connected'));
@@ -76,12 +103,24 @@ export class CdpClient {
       const id = this.nextId++;
       const cmd: CdpCommand = { id, method, params };
       if (sessionId) cmd.sessionId = sessionId;
+
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      if (timeoutMs > 0) {
+        timer = setTimeout(() => {
+          this.pendingCommands.delete(id);
+          reject(new Error(`CDP command "${method}" timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        timer.unref?.();
+      }
+
       this.pendingCommands.set(id, {
-        resolve: (r) => resolve((r.result ?? {}) as T),
-        reject,
+        resolve: (r) => { if (timer) clearTimeout(timer); resolve((r.result ?? {}) as T); },
+        reject: (e) => { if (timer) clearTimeout(timer); reject(e); },
+        timer,
       });
       this.ws.send(JSON.stringify(cmd), (err) => {
         if (err) {
+          if (timer) clearTimeout(timer);
           this.pendingCommands.delete(id);
           reject(err);
         }
@@ -120,9 +159,7 @@ export class CdpClient {
   }
 
   close(): void {
-    this.connected = false;
-    for (const { reject: r } of this.pendingCommands.values()) r(new Error('CDP connection closed'));
-    this.pendingCommands.clear();
+    this.flushPending(new Error('CDP connection closed'));
     this.ws?.close();
     this.ws = null;
     this.eventListeners.clear();

package/src/browser/ref-cache.ts

@@ -97,14 +97,29 @@ export async function clearRefCache(): Promise<void> {
  * falling back to the hardcoded default port and launching/attaching to a
  * second, unrelated Chrome instance.
  */
-export async function saveActivePort(port: number, opts?: { launched?: boolean }): Promise<void> {
+export async function saveActivePort(
+  port: number,
+  opts?: { launched?: boolean; pid?: number; userDataDir?: string }
+): Promise<void> {
   try {
     await mkdir(CACHE_DIR, { recursive: true });
     // `launched` records provenance: true = monobrowse spawned this Chrome
     // (safe to Browser.close later); false = attached to a browser someone
     // else owns (must never be killed). Absent (old files) reads as launched
     // — matches pre-flag behavior where every persisted port came from open.
-    await writeFile(PORT_FILE, JSON.stringify({ port, launched: opts?.launched !== false, savedAt: Date.now() }));
+    //
+    // `pid`/`userDataDir` are persisted so a LATER, fresh CLI process (each
+    // command is its own node process — see module header) can still find
+    // and kill the Chrome this one launched. Without this, closeBrowser()'s
+    // PID-kill fallback can never fire outside the launching process, since
+    // the in-memory launchedPids Map (browser.ts) is empty there.
+    await writeFile(PORT_FILE, JSON.stringify({
+      port,
+      launched: opts?.launched !== false,
+      pid: opts?.pid,
+      userDataDir: opts?.userDataDir,
+      savedAt: Date.now(),
+    }));
   } catch {
     // Best-effort — persistence failure just means the next process falls
     // back to the hardcoded default port, matching prior behavior.
@@ -126,13 +141,21 @@ export async function loadActivePort(): Promise<number | null> {
   return (await loadActivePortInfo())?.port ?? null;
 }
 
-/** Load the persisted active port with its provenance flag. */
-export async function loadActivePortInfo(): Promise<{ port: number; launched: boolean } | null> {
+/** Load the persisted active port with its provenance flag, PID, user-data-dir, and save timestamp. */
+export async function loadActivePortInfo(): Promise<
+  { port: number; launched: boolean; pid?: number; userDataDir?: string; savedAt?: number } | null
+> {
   try {
     const raw = await readFile(PORT_FILE, 'utf8');
-    const data = JSON.parse(raw) as { port?: unknown; launched?: unknown };
+    const data = JSON.parse(raw) as { port?: unknown; launched?: unknown; pid?: unknown; userDataDir?: unknown; savedAt?: unknown };
     if (typeof data.port === 'number' && Number.isInteger(data.port) && data.port >= 1024 && data.port <= 65535) {
-      return { port: data.port, launched: data.launched !== false };
+      return {
+        port: data.port,
+        launched: data.launched !== false,
+        pid: typeof data.pid === 'number' && Number.isInteger(data.pid) && data.pid > 0 ? data.pid : undefined,
+        userDataDir: typeof data.userDataDir === 'string' ? data.userDataDir : undefined,
+        savedAt: typeof data.savedAt === 'number' ? data.savedAt : undefined,
+      };
     }
     return null;
   } catch {

package/src/browser/tabs.ts

@@ -24,11 +24,16 @@ export async function activateTab(client: CdpClient, oldSessionId: string, targe
   return result.sessionId;
 }
 
+export interface FrameSwitchResult {
+  url: string | null;
+  sessionId: string | null;
+}
+
 export async function switchToFrame(
   client: CdpClient,
   sessionId: string,
   frameSelector: string
-): Promise<string | null> {
+): Promise<FrameSwitchResult> {
   const { result } = await client.send<{ result: { result: { value: string | null } } }>(
     'Runtime.evaluate',
     {
@@ -50,7 +55,7 @@ export async function switchToFrame(
   const match = frameTree.childFrames?.find(
     (cf) => cf.frame.url === frameSrc || cf.frame.id === frameSelector
   );
-  if (!match) return frameSrc;
+  if (!match) return { url: frameSrc, sessionId: null };
 
   const targets = await client.send<{ targetInfos: Array<{ targetId: string; type: string; url: string }> }>(
     'Target.getTargets', {}
@@ -59,8 +64,11 @@ export async function switchToFrame(
     (t) => t.type === 'iframe' && t.url === match.frame.url
   );
   if (oopif) {
-    await client.send('Target.attachToTarget', { targetId: oopif.targetId, flatten: true });
+    const attached = await client.send<{ sessionId: string }>(
+      'Target.attachToTarget', { targetId: oopif.targetId, flatten: true }
+    );
+    return { url: frameSrc, sessionId: attached.sessionId };
   }
 
-  return frameSrc;
+  return { url: frameSrc, sessionId: null };
 }

package/src/browser/types.ts

@@ -9,6 +9,10 @@ export interface BrowserConfig {
   executablePath?: string;
   userDataDir?: string;
   args?: string[];
+  /** Milliseconds to wait for the launched Chrome to open its CDP port
+   *  before giving up. Default 10000 — raise this for environments where
+   *  process spawn is consistently slower (e.g. constrained CI runners). */
+  launchTimeoutMs?: number;
 }
 
 export interface SessionState {

package/src/cli/commands.ts

@@ -16,11 +16,52 @@ let _sessionId = '';
 let _targetId = '';
 let _port = DEFAULT_PORT;
 let _refs: Map<string, ElementRef> = new Map();
+// Saved parent sessionId when inside an iframe — restored by `frame main`.
+let _parentSessionId = '';
 
 async function getBrowser() {
   return import('../index.js');
 }
 
+// Best-effort cleanup on Ctrl-C / kill so a launched Chrome doesn't linger as
+// an orphan process when a command is interrupted mid-flight (e.g. during a
+// long-running wait/eval that CdpClient.send()'s own timeout hasn't tripped
+// yet).
+//
+// This module is imported for EVERY `monomind` CLI invocation (commands/
+// index.ts statically imports browse.ts, which imports this file) — not just
+// browse commands — so the handler is only *registered* once a browser
+// session is actually launched here (see ensureSignalCleanupHandlers(),
+// called from the `open` action below), not at module load. Registering
+// unconditionally at import time would call process.exit() on Ctrl-C for
+// every unrelated monomind command (e.g. a long-running `org run` daemon),
+// pre-empting whatever other SIGINT/SIGTERM handling that process needs.
+const SIGNAL_EXIT_CODES: Record<'SIGINT' | 'SIGTERM', number> = { SIGINT: 130, SIGTERM: 143 };
+let _signalHandlersRegistered = false;
+function ensureSignalCleanupHandlers(): void {
+  if (_signalHandlersRegistered) return;
+  _signalHandlersRegistered = true;
+  for (const sig of ['SIGINT', 'SIGTERM'] as const) {
+    process.on(sig, () => {
+      void (async () => {
+        try {
+          const browser = await getBrowser();
+          if (_client) {
+            await browser.closeBrowser(_client, _port);
+          } else {
+            const pid = browser.getLaunchedPid(_port);
+            if (pid !== undefined) {
+              try { process.kill(pid, 'SIGKILL'); } catch { /* already exited */ }
+            }
+          }
+        } catch {
+          // best-effort — never block process exit on cleanup failure
+        }
+      })().finally(() => process.exit(SIGNAL_EXIT_CODES[sig]));
+    });
+  }
+}
+
 // Each CLI invocation is a fresh process, so this module's `_port` variable
 // is always freshly initialized to DEFAULT_PORT — a `--port 9333` passed to
 // an earlier `open` command has no effect on this process's own default.
@@ -62,6 +103,7 @@ async function ensureConnected(port: number, targetId?: string) {
     _client = conn.client;
     _sessionId = conn.sessionId;
     _targetId = conn.target.id;
+    _parentSessionId = '';
     _refs = new Map();
     await hydrateRefsFromCache(browser, _targetId, conn.target.url);
   }
@@ -157,6 +199,7 @@ async function switchToHeaded(url: string, port: number): Promise<void> {
     _client.close();
     _client = null;
     _sessionId = '';
+    _parentSessionId = '';
     _targetId = '';
   }
 
@@ -203,6 +246,7 @@ async function switchToHeaded(url: string, port: number): Promise<void> {
   _client.close();
   _client = null;
   _sessionId = '';
+  _parentSessionId = '';
   _targetId = '';
 
   // Relaunch headless and restore session
@@ -277,14 +321,40 @@ const openCommand: Command = {
       prevClient.close();
       _client = null;
       _sessionId = '';
+      _parentSessionId = '';
       _targetId = '';
       _refs = new Map();
     }
 
     _port = await browser.launchBrowser({ port, headless: !forceHeaded });
     // Persist the active port so subsequent CLI invocations (each a fresh
-    // process) default to attaching here instead of hardcoded 9222.
-    await browser.saveActivePort(_port);
+    // process) default to attaching here instead of hardcoded 9222. Also
+    // persist the launched PID/userDataDir so a later process's closeBrowser
+    // can still kill this Chrome even though launchedPids (browser.ts) is
+    // per-process and empty there.
+    //
+    // launchBrowser() can either LAUNCH a fresh Chrome or ATTACH to one
+    // already listening on the requested port (see its own "attach if
+    // already Chrome" comment) — it returns only a port number, with no
+    // signal telling this caller which happened. getLaunchedPid(_port) is
+    // undefined on the attach path (this process never spawned anything).
+    // Bug fixed here: unconditionally saving {pid: undefined, ...} on
+    // attach used to CLOBBER a real PID a previous `open` had already
+    // persisted for this exact port, destroying the only way a later
+    // process's closeBrowser() PID-kill fallback could ever find it.
+    const freshPid = browser.getLaunchedPid(_port);
+    const freshUserDataDir = browser.getLaunchedUserDataDir(_port);
+    if (freshPid !== undefined) {
+      await browser.saveActivePort(_port, { pid: freshPid, userDataDir: freshUserDataDir });
+    } else {
+      // Attach path: preserve whatever PID/userDataDir was already on file
+      // for this port (most likely from the process that originally
+      // launched it) instead of overwriting with undefined.
+      const existing = await browser.loadActivePortInfo();
+      const preserved = existing && existing.port === _port ? existing : undefined;
+      await browser.saveActivePort(_port, { pid: preserved?.pid, userDataDir: preserved?.userDataDir });
+    }
+    ensureSignalCleanupHandlers();
     const conn = await browser.connectToTarget(_port);
     _client = conn.client;
     _sessionId = conn.sessionId;
@@ -1275,6 +1345,7 @@ const closeCommand: Command = {
       client.close();
       _client = null;
       _sessionId = '';
+      _parentSessionId = '';
       _targetId = '';
       _refs = new Map();
       // Session is gone — forget the persisted port and stale refs so later
@@ -1919,10 +1990,23 @@ const frameCommand: Command = {
     if (!target) throw new Error('Usage: monomind browse frame <selector>|main');
 
     if (target === 'main') {
+      if (_parentSessionId) {
+        // Detach from the OOPIF session (best-effort — it may already be gone)
+        await client.send('Target.detachFromTarget', { sessionId: _sessionId }).catch(() => {});
+        _sessionId = _parentSessionId;
+        _parentSessionId = '';
+      }
       output.printSuccess('Switched to main frame');
     } else {
-      const frameSrc = await browser.switchToFrame(client, sessionId, target);
-      output.printSuccess(`Switched to frame: ${frameSrc ?? target}`);
+      const frameResult = await browser.switchToFrame(client, sessionId, target);
+      if (frameResult.sessionId) {
+        // Save the parent session so `frame main` can restore it
+        _parentSessionId = _sessionId;
+        _sessionId = frameResult.sessionId;
+        // Enable CDP domains on the iframe's session so subsequent commands work
+        await browser.enableSessionDomains(client, _sessionId);
+      }
+      output.printSuccess(`Switched to frame: ${frameResult.url ?? target}`);
     }
     return { success: true };
   },
@@ -1974,6 +2058,7 @@ const tabCommand: Command = {
           client.close();
           _client = null;
           _sessionId = '';
+          _parentSessionId = '';
           _targetId = '';
           _refs = new Map();
         } else {
@@ -2726,6 +2811,7 @@ const connectCommand: Command = {
       prevClient.close();
       _client = null;
       _sessionId = '';
+      _parentSessionId = '';
       _targetId = '';
       _refs = new Map();
     }