@lincoln504/pi-research 0.1.12 → 1.0.0

package/src/infrastructure/browser/browser-cleanup.ts

@@ -0,0 +1,309 @@
+/**
+ * Browser Cleanup Utilities
+ *
+ * Functions for cleaning up orphaned browser processes and related resources.
+ */
+
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import * as os from 'node:os';
+import { logger } from '../../logger.ts';
+
+const execAsync = promisify(exec);
+
+/**
+ * Find and kill orphaned Camoufox browser processes.
+ *
+ * Orphaned processes are those that:
+ * 1. Are running Camoufox/Firefox browsers
+ * 2. Have a parent PID that no longer exists
+ * 3. Are not part of an active browser pool
+ *
+ * This should be called after pool destruction to clean up any stragglers.
+ */
+export async function cleanupOrphanedCamoufoxProcesses(): Promise<void> {
+  const platform = os.platform();
+  
+  try {
+    if (platform === 'darwin' || platform === 'linux') {
+      await cleanupOrphanedProcessesUnix();
+    } else if (platform === 'win32') {
+      await cleanupOrphanedProcessesWindows();
+    } else {
+      logger.warn(`[BrowserCleanup] Platform ${platform} not supported for orphan cleanup`);
+    }
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    logger.warn(`[BrowserCleanup] Failed to cleanup orphaned processes: ${msg}`);
+  }
+}
+
+/**
+ * Marker that identifies a browser process as one WE launched (Camoufox via
+ * Playwright), never the user's own system Firefox. We match on the launched
+ * EXECUTABLE — `camoufox-bin` (Linux), `camoufox.exe` (Windows) or
+ * `…/MacOS/camoufox` (macOS), per camoufox-js's LAUNCH_FILE — plus our
+ * `…/pi-research/profiles/…` profile path (the fallback when PI_RESEARCH_TMP_DIR
+ * relocates profiles). Anchoring on the executable name (rather than a bare
+ * `camoufox` substring) keeps an incidental `tail camoufox.log`, `grep camoufox`,
+ * or an editor buffer from ever matching — the system Firefox matches none of
+ * these. (A user's OWN orphaned standalone Camoufox is the one indistinguishable
+ * case; it is gated further by the strict orphan conditions below.)
+ */
+export const PI_BROWSER_MARKER = /camoufox-bin\b|camoufox\.exe\b|[/\\]MacOS[/\\]camoufox\b|[/\\]pi-research[/\\]profiles[/\\]/i;
+
+/**
+ * Cleanup orphaned processes on Unix-like systems (macOS, Linux)
+ */
+async function cleanupOrphanedProcessesUnix(): Promise<void> {
+  try {
+    // Scan by FULL command line (args), not comm, so we can positively identify our
+    // own Camoufox processes and never touch the user's system Firefox.
+    const { stdout } = await execAsync(
+      'ps -eo pid,ppid,args 2>/dev/null',
+    );
+
+    const lines = stdout.trim().split('\n');
+    const cleanupTasks: Promise<void>[] = [];
+
+    for (const line of lines) {
+      // Capture PID, PPID, and the remaining args from each line.
+      const match = line.trim().match(/^\s*(\d+)\s+(\d+)\s+(.*)$/);
+      if (!match || !match[1] || !match[2]) continue;
+
+      const args = match[3] || '';
+      // Only ever consider OUR Camoufox processes — never the user's Firefox.
+      if (!PI_BROWSER_MARKER.test(args)) continue;
+
+      const pid = parseInt(match[1], 10);
+      const ppid = parseInt(match[2], 10);
+      const comm = 'camoufox';
+      // Never target ourselves.
+      if (pid === process.pid) continue;
+
+      // Determine if orphan:
+      // 1. PPID is 1 (adopted by init)
+      // 2. Parent PID is dead (process.kill(ppid, 0) throws)
+      let isOrphan = false;
+      if (ppid === 1) {
+        isOrphan = true;
+      } else {
+        try {
+          process.kill(ppid, 0);
+          isOrphan = false;
+        } catch (e) {
+          // ESRCH = parent is gone (genuine orphan). EPERM = parent is ALIVE but
+          // owned by another user — NOT an orphan. Conflating them would let a
+          // multi-user host / CI side-car kill a live, foreign-owned browser.
+          isOrphan = (e as NodeJS.ErrnoException)?.code !== 'EPERM';
+        }
+      }
+
+      if (isOrphan) {
+        cleanupTasks.push((async () => {
+          logger.log(`[BrowserCleanup] Found orphaned ${comm} process: PID ${pid}, parent PID ${ppid}`);
+          
+          try {
+            // Kill the orphaned process gracefully
+            process.kill(pid, 'SIGTERM');
+            
+            // Give it a moment to exit gracefully (wait in parallel)
+            await new Promise(resolve => setTimeout(resolve, 500));
+            
+            // Check if it's still running and force kill if needed
+            try {
+              process.kill(pid, 0);
+              // Still running, force kill
+              process.kill(pid, 'SIGKILL');
+              logger.warn(`[BrowserCleanup] Force killed orphaned process: PID ${pid}`);
+            } catch {
+              // Process exited
+              logger.log(`[BrowserCleanup] Terminated orphaned process: PID ${pid}`);
+            }
+          } catch (killError) {
+            const msg = killError instanceof Error ? killError.message : String(killError);
+            logger.warn(`[BrowserCleanup] Failed to kill orphaned process PID ${pid}: ${msg}`);
+          }
+        })());
+      }
+    }
+    
+    if (cleanupTasks.length > 0) {
+      await Promise.all(cleanupTasks);
+      logger.log(`[BrowserCleanup] Cleaned up ${cleanupTasks.length} orphaned browser process(es)`);
+    }
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    logger.warn(`[BrowserCleanup] Failed to find orphaned processes: ${msg}`);
+  }
+}
+
+interface WinProc { pid: number; ppid: number; name: string; commandLine: string; }
+
+/**
+ * Snapshot all Windows processes with their parent PID and FULL command line.
+ *
+ * Uses PowerShell/CIM rather than `wmic` (removed by default in Windows 11 24H2
+ * and Server 2025). A single call returns the whole process table, which lets us
+ * (a) positively identify OUR Camoufox via {@link PI_BROWSER_MARKER} on the
+ * command line — never the user's own firefox.exe — and (b) detect dead parents
+ * from the same snapshot without a per-PID query.
+ */
+async function queryWindowsProcesses(): Promise<WinProc[]> {
+  const cmd =
+    'powershell -NoProfile -NonInteractive -Command ' +
+    '"Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,Name,CommandLine | ConvertTo-Json -Compress"';
+  const { stdout } = await execAsync(cmd, { maxBuffer: 1024 * 1024 * 16 }).catch(() => ({ stdout: '' }));
+  if (!stdout.trim()) return [];
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return [];
+  }
+  // ConvertTo-Json emits a bare object for a single result, an array otherwise.
+  const arr = Array.isArray(parsed) ? parsed : [parsed];
+  const procs: WinProc[] = [];
+  for (const p of arr) {
+    if (!p || typeof p !== 'object') continue;
+    const rec = p as Record<string, unknown>;
+    const pid = Number(rec['ProcessId']);
+    if (!Number.isFinite(pid)) continue;
+    const ppid = Number(rec['ParentProcessId']);
+    const name = rec['Name'];
+    const commandLine = rec['CommandLine'];
+    procs.push({
+      pid,
+      // 0 is an "unknown parent" sentinel (unparseable/missing ParentProcessId).
+      // It must NEVER be treated as orphaned — see cleanupOrphanedProcessesWindows.
+      ppid: Number.isFinite(ppid) && ppid > 0 ? ppid : 0,
+      name: typeof name === 'string' ? name : '',
+      commandLine: typeof commandLine === 'string' ? commandLine : '',
+    });
+  }
+  return procs;
+}
+
+/**
+ * Cleanup orphaned processes on Windows
+ */
+async function cleanupOrphanedProcessesWindows(): Promise<void> {
+  try {
+    const procs = await queryWindowsProcesses();
+    if (procs.length === 0) return;
+
+    // Live-PID set from the same snapshot. A process whose ParentProcessId is
+    // absent from this set has a dead parent — the Windows analogue of the Unix
+    // path's `process.kill(ppid, 0)` liveness probe. (Windows does NOT reparent
+    // to PID 1, and never resets a dead parent's PID to 0, so absence-from-table
+    // is the correct signal.)
+    const alivePids = new Set(procs.map((p) => p.pid));
+    const cleanupTasks: Promise<void>[] = [];
+
+    for (const proc of procs) {
+      // ONLY ever consider our own Camoufox — match the full command line so the
+      // user's personal firefox.exe is never a candidate. This is the safety
+      // guarantee the old image-name-only match lacked.
+      if (!PI_BROWSER_MARKER.test(proc.commandLine)) continue;
+      if (proc.pid === process.pid) continue;
+      // Unknown parent (sentinel 0): we cannot prove it is orphaned, so we must
+      // NOT kill it — a live pool browser must never be force-killed on a guess.
+      if (proc.ppid <= 0) continue;
+      // Orphaned iff the parent is gone from the live process table.
+      if (alivePids.has(proc.ppid)) continue;
+
+      cleanupTasks.push((async () => {
+        logger.log(`[BrowserCleanup] Found orphaned Camoufox process: PID ${proc.pid}, dead parent PID ${proc.ppid}`);
+        try {
+          await execAsync(`taskkill /PID ${proc.pid} /F /T`);
+          logger.log(`[BrowserCleanup] Terminated orphaned process: PID ${proc.pid}`);
+        } catch (killError) {
+          const msg = killError instanceof Error ? killError.message : String(killError);
+          logger.warn(`[BrowserCleanup] Failed to kill orphaned process PID ${proc.pid}: ${msg}`);
+        }
+      })());
+    }
+
+    if (cleanupTasks.length > 0) {
+      await Promise.all(cleanupTasks);
+      logger.log(`[BrowserCleanup] Cleaned up ${cleanupTasks.length} orphaned browser process(es)`);
+    }
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    logger.warn(`[BrowserCleanup] Failed to find orphaned processes on Windows: ${msg}`);
+  }
+}
+
+
+// ============================================================================
+// Browser Manager Cleanup Functions
+// ============================================================================
+
+/**
+ * Snapshot browser PIDs that are children of the given worker PIDs
+ */
+export async function getBrowserPidsForWorkers(workerPids: number[]): Promise<number[]> {
+  const platform = os.platform();
+  const pids: number[] = [];
+  if (!workerPids || workerPids.length === 0) return pids;
+
+  try {
+    if (platform === 'darwin' || platform === 'linux') {
+      const { stdout } = await execAsync('ps -eo pid,ppid,comm | grep -E "(firefox|camoufox)" | grep -v grep').catch(() => ({ stdout: '' }));
+      const lines = stdout.trim().split('\n');
+      for (const line of lines) {
+        const match = line.trim().match(/^\s*(\d+)\s+(\d+)\s+/);
+        if (match && match[1] && match[2]) {
+          const pid = parseInt(match[1], 10);
+          const ppid = parseInt(match[2], 10);
+          if (workerPids.includes(ppid)) pids.push(pid);
+        }
+      }
+    } else if (platform === 'win32') {
+      // wmic-free: one CIM snapshot, matched on the full command line so only
+      // OUR Camoufox children of the given workers are returned.
+      const procs = await queryWindowsProcesses();
+      for (const proc of procs) {
+        if (!PI_BROWSER_MARKER.test(proc.commandLine)) continue;
+        if (workerPids.includes(proc.ppid)) pids.push(proc.pid);
+      }
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logger.warn(`[BrowserCleanup] Failed to get browser PIDs for workers: ${msg}`);
+  }
+  return pids;
+}
+
+/**
+ * Kill specific browser processes in parallel
+ */
+export async function killBrowserProcesses(pids: number[]): Promise<void> {
+  if (!pids || pids.length === 0) return;
+  const platform = os.platform();
+  
+  // Parallelize killing processes for speed
+  await Promise.all(pids.map(async (pid) => {
+    try {
+      if (platform === 'win32') {
+        await execAsync(`taskkill /PID ${pid} /F /T`);
+        logger.debug(`[BrowserCleanup] Terminated worker browser process: PID ${pid}`);
+      } else {
+        process.kill(pid, 'SIGTERM');
+        // Reduce wait time for graceful exit from 500ms to 200ms
+        await new Promise(resolve => setTimeout(resolve, 200));
+        try {
+          process.kill(pid, 0);
+          process.kill(pid, 'SIGKILL');
+          logger.debug(`[BrowserCleanup] Force killed worker browser process: PID ${pid}`);
+        } catch {
+          logger.debug(`[BrowserCleanup] Terminated worker browser process: PID ${pid}`);
+        }
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      logger.debug(`[BrowserCleanup] Failed to kill browser process PID ${pid}: ${msg}`);
+    }
+  }));
+}

package/src/infrastructure/browser/browser-client.ts

@@ -0,0 +1,199 @@
+/**
+ * Browser Client for Remote Scheduler Communication
+ *
+ * HTTP client that communicates with a remote scheduler via HTTP.
+ * Extracted from browser-manager.ts for better separation of concerns.
+ */
+
+import * as http from 'node:http';
+import type { Config } from '../../config.ts';
+import type { SearchResult } from '../../web-research/types.ts';
+import type { IScheduler } from '../../core/interfaces/scheduler-interfaces.ts';
+import { logger } from '../../logger.ts';
+import { errorTracker } from '../../utils/error-tracker.ts';
+import { getClientAgent } from './client-agent.ts';
+import type { NodeError } from '../../types/index.ts';
+
+/**
+ * HTTP client that communicates with a remote scheduler.
+ * Used when this process is not the leader.
+ */
+export class BrowserClient implements IScheduler {
+    private readonly authSecret: string;
+
+    constructor(private readonly port: number, authSecret?: string) {
+        this.authSecret = authSecret ?? process.env['PI_BROWSER_AUTH_SECRET'] ?? '';
+        logger.log(`[BrowserClient] Connecting to global scheduler at http://127.0.0.1:${port}`);
+    }
+
+    private async request<T>(path: string, data: any, signal?: AbortSignal): Promise<T> {
+        const start = Date.now();
+        // Extract operation from path for error tracking
+        const operation = path.includes('/search') ? 'search' :
+                         path.includes('/scrape') ? 'browser-task' :
+                         path.includes('/healthcheck') ? 'healthcheck' : 'network';
+
+        return new Promise((resolve, reject) => {
+            const agent = getClientAgent();
+            // 60s timeout for client requests (1/3 of original 180s)
+            const timeoutMs = 60000;
+            let resolved = false;
+            const controller = new AbortController();
+            
+            // Merge outer signal with our local controller
+            let abortCleanup: (() => void) | undefined;
+            if (signal) {
+                if (signal.aborted) {
+                    return reject(new Error('Aborted'));
+                }
+                const onAbort = () => {
+                    if (resolved) return;
+                    resolved = true;
+                    controller.abort();
+                    reject(new Error('Aborted'));
+                };
+                signal.addEventListener('abort', onAbort, { once: true });
+                abortCleanup = () => signal.removeEventListener('abort', onAbort);
+            }
+
+            const timer = setTimeout(() => {
+                if (!resolved) {
+                    resolved = true;
+                    // Remove the outer-signal abort listener on timeout too. Without this,
+                    // a long-lived run signal shared across many client requests accumulates
+                    // one never-removed listener per timed-out request for the run's duration.
+                    abortCleanup?.();
+                    controller.abort();
+                    const error = new Error(`[BrowserClient] Request to ${path} timed out after ${timeoutMs}ms (Shared queue may be deep)`);
+                    errorTracker.trackError(error, {
+                        component: 'browser-manager',
+                        operation,
+                        errorType: 'timeout',
+                    });
+                    reject(error);
+                }
+            }, timeoutMs);
+            // FIX (#34): Don't keep the event loop alive for timeout timers
+            if (timer.unref) timer.unref();
+
+            const req = http.request({
+                hostname: '127.0.0.1',
+                port: this.port,
+                path,
+                method: 'POST',
+                agent,
+                signal: controller.signal,
+                headers: {
+                    'Content-Type': 'application/json',
+                    // FIX (#21): Send auth token to authenticate with browser server
+                    'X-Browser-Auth': this.authSecret,
+                }
+            }, (res) => {
+                // Do NOT clear the timeout/abort here. The response callback fires
+                // when headers arrive, but the body is still streaming — clearing
+                // now would let a stalled body hang forever and make an external
+                // abort a no-op. Keep both armed until 'end' or 'error'.
+                let body = '';
+                res.on('data', chunk => body += chunk);
+                res.on('end', () => {
+                    if (resolved) return;
+                    resolved = true;
+                    clearTimeout(timer);
+                    abortCleanup?.();
+                    const duration = Date.now() - start;
+                    try {
+                        const parsed = JSON.parse(body);
+                        if (res.statusCode !== 200) {
+                            const error = new Error(parsed.error || `HTTP ${res.statusCode}`);
+                            errorTracker.trackError(error, {
+                                component: 'browser-manager',
+                                operation,
+                                errorType: 'http_error',
+                            });
+                            reject(error);
+                        } else {
+                            logger.debug(`[BrowserClient] Request ${path} completed in ${duration}ms`);
+                            resolve(parsed);
+                        }
+                    } catch (_e) {
+                        // FIX (#23): Truncate response body in error to prevent data leakage
+                        const preview = body.length > 200 ? body.slice(0, 200) + '...' : body;
+                        const error = new Error(`Failed to parse response (status ${res.statusCode}): ${preview}`);
+                        errorTracker.trackError(error, {
+                            component: 'browser-manager',
+                            operation,
+                            errorType: 'parse_error',
+                        });
+                        reject(error);
+                    }
+                });
+                res.on('error', (err) => {
+                    if (resolved) return;
+                    resolved = true;
+                    clearTimeout(timer);
+                    abortCleanup?.();
+                    const error = new Error(`[BrowserClient] Response stream error on ${path}: ${err.message}`);
+                    errorTracker.trackError(error, {
+                        component: 'browser-manager',
+                        operation,
+                        errorType: 'response_stream_error',
+                    });
+                    reject(error);
+                });
+            });
+
+            req.on('error', (err) => {
+                if (resolved) return;
+                resolved = true;
+                clearTimeout(timer);
+                abortCleanup?.();
+                
+                // If it's just a timeout abort error, the timer already rejected it.
+                if (err.name === 'AbortError') return;
+                // Enhance error message with socket-specific details
+                const nodeErr = err as NodeError;
+                let errorMsg: string;
+                let errorType: string;
+                if (nodeErr.code === 'ECONNRESET' || nodeErr.code === 'EPIPE') {
+                    errorMsg = `Browser pool socket ${path} closed (pool likely busy or restarting) - ${err.message}`;
+                    errorType = 'connection_reset';
+                } else if (nodeErr.code === 'ECONNREFUSED') {
+                    errorMsg = `Browser pool ${path} unreachable (server restarting or torn down) - ${err.message}`;
+                    errorType = 'connection_refused';
+                } else if (nodeErr.code === 'ETIMEDOUT') {
+                    errorMsg = `Browser pool ${path} timed out (slow browser response) - ${err.message}`;
+                    errorType = 'timeout';
+                } else {
+                    errorMsg = `Browser pool ${path} error: ${err.message}`;
+                    errorType = 'unknown';
+                }
+                const error = new Error(errorMsg);
+                logger.error(`[BrowserClient] Request to http://127.0.0.1:${this.port}${path} failed:`, errorMsg);
+                errorTracker.trackError(error, {
+                    component: 'browser-manager',
+                    operation,
+                    errorType,
+                });
+                reject(error);
+            });
+            req.write(JSON.stringify(data));
+            req.end();
+        });
+    }
+
+    async runSearch(query: string, _config?: Config, signal?: AbortSignal): Promise<SearchResult[]> {
+        return this.request('/search', { query }, signal);
+    }
+
+    async runScrape(url: string, _config?: Config, signal?: AbortSignal): Promise<any> {
+        return this.request('/scrape', { url }, signal);
+    }
+
+    async runHealthCheck(_config?: Config, signal?: AbortSignal): Promise<{ success: boolean }> {
+        return this.request('/healthcheck', {}, signal);
+    }
+
+    async shutdown() {
+        // Clients don't shutdown the server
+    }
+}

package/src/infrastructure/browser/browser-error-utils.ts

@@ -0,0 +1,160 @@
+/**
+ * Browser Error Utilities
+ *
+ * Error detection and circuit breaker utilities for browser operations.
+ * Extracted from browser-manager.ts for better separation of concerns.
+ */
+
+import { CircuitBreaker } from '../../utils/circuit-breaker.ts';
+import type { NodeError } from '../../types/index.ts';
+
+/**
+ * Check if an error is a transient socket error that can be retried.
+ */
+export function isTransientSocketError(error: unknown): boolean {
+    if (!error || typeof error !== 'object') return false;
+    const err = error as NodeError;
+    return typeof err.message === 'string' && (
+        err.message.includes('ECONNREFUSED') ||
+        err.message.includes('ECONNRESET') ||
+        err.message.includes('socket hang up') ||
+        err.message.includes('EPIPE') ||
+        err.message.includes('ETIMEDOUT') ||
+        err.message.includes('timed out') ||
+        err.message.includes('pool busy') ||
+        err.message.includes('unreachable') ||
+        // WorkerPoolManager throws this during the window between forceSchedulerRestart
+        // clearing the scheduler reference and the old pool's 1500ms drain completing.
+        // It is a transient state — retry after a short delay succeeds once drain finishes.
+        err.message.includes('Worker pool is shutting down') ||
+        // Poolifier throws this when pool.execute() is called while the pool is being
+        // destroyed (e.g., during scheduler restart). Treat as transient — the pool will
+        // be ready for new tasks once destruction completes and a new pool is initialized.
+        err.message.includes('Cannot execute a task on destroying pool') ||
+        err.message.includes('destroying pool')
+    );
+}
+
+/**
+ * Check if an error is a Cloudflare block/challenge error.
+ * These are content-layer rejections, not infrastructure failures — they must NOT
+ * count toward the circuit breaker failure threshold. Counting them caused the
+ * breaker to open during normal searches and block all subsequent requests.
+ */
+export function isCloudflareBlockError(error: unknown): boolean {
+    if (!error || typeof error !== 'object') return false;
+    const err = error as NodeError;
+    return typeof err.message === 'string' && (
+        err.message.includes('Fetch blocked: Cloudflare') ||
+        err.message.includes('Cloudflare challenge')
+    );
+}
+
+/**
+ * Check if an error is a task-level timeout (search/scrape/healthcheck timed out).
+ * These indicate the remote site is slow or unresponsive — a normal occurrence during
+ * a burst of 20 parallel queries. They must NOT trip the circuit breaker; only true
+ * socket-layer infrastructure failures (ECONNREFUSED, ECONNRESET, etc.) should do so.
+ */
+export function isTaskTimeoutError(error: unknown): boolean {
+    if (!error || typeof error !== 'object') return false;
+    const err = error as NodeError;
+    return typeof err.message === 'string' && (
+        err.message.includes('timed out after') ||
+        err.message.includes('Search task timed out') ||
+        err.message.includes('Scrape task timed out') ||
+        err.message.includes('Health check timed out') ||
+        err.message.includes('[BrowserClient] Request to')
+    );
+}
+
+/**
+ * Check if an error is specifically a pool-shutdown / pool-drain error.
+ * For these errors the scheduler itself is fine — only the WorkerPool is temporarily
+ * draining. The correct recovery is to wait for the drain to finish and retry,
+ * NOT to call forceSchedulerRestart (which would start another drain cycle).
+ */
+export function isPoolShutdownError(error: unknown): boolean {
+    if (!error || typeof error !== 'object') return false;
+    const err = error as NodeError;
+    return typeof err.message === 'string' && (
+        err.message.includes('Worker pool is shutting down') ||
+        err.message.includes('Cannot execute a task on destroying pool') ||
+        err.message.includes('destroying pool')
+    );
+}
+
+// Session-scoped circuit breaker storage to support concurrent research runs
+const sessionCircuitBreakers = new Map<string, CircuitBreaker>();
+// Hard cap so a cleanup path that ever skips clearSessionCircuitBreaker (e.g. an earlier
+// throw in the cleanup closure) can't grow the map unboundedly over a long-lived TUI
+// process with many sessions. Far above any realistic concurrent-session count. Mirrors
+// the MAX_PATTERNS bound in error-tracker.ts.
+const MAX_SESSION_BREAKERS = 256;
+
+/**
+ * Default circuit breaker configuration
+ */
+const DEFAULT_BREAKER_CONFIG: any = {
+    // Raised from 3→8: parallel search bursts of 20 queries frequently produce
+    // simultaneous timeouts on slow/CF-protected sites. A threshold of 3 caused
+    // the breaker to open mid-burst, blocking all subsequent requests for the round.
+    failureThreshold: 8,
+    // Raised from 15s→45s: enough time for one full search burst + retry window
+    // to complete before the breaker attempts to half-open.
+    resetTimeoutMs: 45000,
+    name: 'BrowserPool',
+    isTransientError: (error: unknown) => {
+        // Pool-drain transients: pool recovers on its own — don't count.
+        if (isPoolShutdownError(error)) return false;
+        // Cloudflare blocks are content-layer rejections, not infra failures — don't count.
+        if (isCloudflareBlockError(error)) return false;
+        // Task-level timeouts (slow/unresponsive sites) are expected during parallel
+        // search bursts — don't count toward the circuit breaker threshold.
+        if (isTaskTimeoutError(error)) return false;
+        // Only genuine socket-layer failures (ECONNREFUSED, ECONNRESET, etc.) trip the circuit.
+        return isTransientSocketError(error);
+    }
+};
+
+/**
+ * Get or create a session-scoped circuit breaker
+ */
+export function getBrowserCircuitBreaker(sessionId: string): CircuitBreaker {
+    let breaker = sessionCircuitBreakers.get(sessionId);
+    if (!breaker) {
+        // Evict the oldest (insertion-order) entry when at the cap before inserting.
+        if (sessionCircuitBreakers.size >= MAX_SESSION_BREAKERS) {
+            const oldest = sessionCircuitBreakers.keys().next().value;
+            if (oldest !== undefined) sessionCircuitBreakers.delete(oldest);
+        }
+        breaker = new CircuitBreaker({ ...DEFAULT_BREAKER_CONFIG, name: `BrowserPool-${sessionId}` });
+        sessionCircuitBreakers.set(sessionId, breaker);
+    }
+    return breaker;
+}
+
+/**
+ * Clear a session's circuit breaker
+ */
+export function clearSessionCircuitBreaker(sessionId: string): void {
+    sessionCircuitBreakers.delete(sessionId);
+}
+
+/**
+ * Global fallback circuit breaker — used when no sessionId is available.
+ */
+export const browserCircuitBreaker = new CircuitBreaker(DEFAULT_BREAKER_CONFIG);
+
+/**
+ * Reset all browser circuit breakers
+ * Call this in test teardown/setup to prevent cross-test circuit state bleed.
+ */
+export function resetBrowserCircuitBreaker(sessionId?: string): void {
+    if (sessionId) {
+        clearSessionCircuitBreaker(sessionId);
+    } else {
+        sessionCircuitBreakers.clear();
+        browserCircuitBreaker.reset();
+    }
+}