@askjo/camofox-browser 1.3.1 → 1.4.0

package/server.js

@@ -1,12 +1,20 @@
-const { Camoufox, launchOptions } = require('camoufox-js');
-const { firefox } = require('playwright-core');
-const express = require('express');
-const crypto = require('crypto');
-const os = require('os');
-const { expandMacro } = require('./lib/macros');
-const { loadConfig } = require('./lib/config');
-const { windowSnapshot } = require('./lib/snapshot');
-const { detectYtDlp, hasYtDlp, ytDlpTranscript, parseJson3, parseVtt, parseXml } = require('./lib/youtube');
+import { Camoufox, launchOptions } from 'camoufox-js';
+import { firefox } from 'playwright-core';
+import express from 'express';
+import crypto from 'crypto';
+import os from 'os';
+import { expandMacro } from './lib/macros.js';
+import { loadConfig } from './lib/config.js';
+import { windowSnapshot } from './lib/snapshot.js';
+import {
+  MAX_DOWNLOAD_INLINE_BYTES,
+  clearTabDownloads,
+  clearSessionDownloads,
+  attachDownloadListener,
+  getDownloadsList,
+  extractPageImages,
+} from './lib/downloads.js';
+import { detectYtDlp, hasYtDlp, ytDlpTranscript, parseJson3, parseVtt, parseXml } from './lib/youtube.js';
 
 const CONFIG = loadConfig();
 
@@ -72,6 +80,16 @@ function timingSafeCompare(a, b) {
   return crypto.timingSafeEqual(bufA, bufB);
 }
 
+// Custom error for stale/unknown element refs — returned as 422 instead of 500
+class StaleRefsError extends Error {
+  constructor(ref, maxRef, totalRefs) {
+    super(`Unknown ref: ${ref} (valid refs: e1-${maxRef}, ${totalRefs} total). Refs reset after navigation - call snapshot first.`);
+    this.name = 'StaleRefsError';
+    this.code = 'stale_refs';
+    this.ref = ref;
+  }
+}
+
 function safeError(err) {
   if (CONFIG.nodeEnv === 'production') {
     log('error', 'internal error', { error: err.message, stack: err.stack });
@@ -80,6 +98,17 @@ function safeError(err) {
   return err.message;
 }
 
+// Send error response with appropriate status code (422 for stale refs, 500 otherwise)
+function sendError(res, err, extraFields = {}) {
+  const status = err instanceof StaleRefsError ? 422 : (err.statusCode || 500);
+  const body = { error: safeError(err), ...extraFields };
+  if (err instanceof StaleRefsError) {
+    body.code = 'stale_refs';
+    body.ref = err.ref;
+  }
+  res.status(status).json(body);
+}
+
 function validateUrl(url) {
   try {
     const parsed = new URL(url);
@@ -92,26 +121,38 @@ function validateUrl(url) {
   }
 }
 
+function isLoopbackAddress(address) {
+  if (!address) return false;
+  return address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1';
+}
+
 // Import cookies into a user's browser context (Playwright cookies format)
 // POST /sessions/:userId/cookies { cookies: Cookie[] }
 //
 // SECURITY:
 // Cookie injection moves this from "anonymous browsing" to "authenticated browsing".
-// This endpoint is DISABLED unless CAMOFOX_API_KEY is set.
-// When enabled, caller must send: Authorization: Bearer <CAMOFOX_API_KEY>
+// By default, this endpoint is protected by CAMOFOX_API_KEY.
+// For local development convenience, when CAMOFOX_API_KEY is NOT set, we allow
+// unauthenticated cookie import ONLY from loopback (127.0.0.1 / ::1) and ONLY
+// when NODE_ENV != production.
 app.post('/sessions/:userId/cookies', express.json({ limit: '512kb' }), async (req, res) => {
   try {
-    if (!CONFIG.apiKey) {
-      return res.status(403).json({
-        error: 'Cookie import is disabled. Set CAMOFOX_API_KEY to enable this endpoint.',
-      });
-    }
-    const apiKey = CONFIG.apiKey;
-
-    const auth = String(req.headers['authorization'] || '');
-    const match = auth.match(/^Bearer\s+(.+)$/i);
-    if (!match || !timingSafeCompare(match[1], apiKey)) {
-      return res.status(403).json({ error: 'Forbidden' });
+    if (CONFIG.apiKey) {
+      const apiKey = CONFIG.apiKey;
+      const auth = String(req.headers['authorization'] || '');
+      const match = auth.match(/^Bearer\s+(.+)$/i);
+      if (!match || !timingSafeCompare(match[1], apiKey)) {
+        return res.status(403).json({ error: 'Forbidden' });
+      }
+    } else {
+      const remoteAddress = req.socket?.remoteAddress || '';
+      const allowUnauthedLocal = CONFIG.nodeEnv !== 'production' && isLoopbackAddress(remoteAddress);
+      if (!allowUnauthedLocal) {
+        return res.status(403).json({
+          error:
+            'Cookie import is disabled without CAMOFOX_API_KEY except for loopback requests in non-production environments.',
+        });
+      }
     }
 
     const userId = req.params.userId;
@@ -169,12 +210,13 @@ app.post('/sessions/:userId/cookies', express.json({ limit: '512kb' }), async (r
 
 let browser = null;
 // userId -> { context, tabGroups: Map<sessionKey, Map<tabId, TabState>>, lastAccess }
-// TabState = { page, refs: Map<refId, {role, name, nth}>, visitedUrls: Set, toolCalls: number }
+// TabState = { page, refs: Map<refId, {role, name, nth}>, visitedUrls: Set, downloads: Array, toolCalls: number }
 // Note: sessionKey was previously called listItemId - both are accepted for backward compatibility
 const sessions = new Map();
 
 const SESSION_TIMEOUT_MS = CONFIG.sessionTimeoutMs;
 const MAX_SNAPSHOT_NODES = 500;
+const TAB_INACTIVITY_MS = CONFIG.tabInactivityMs;
 const MAX_SESSIONS = CONFIG.maxSessions;
 const MAX_TABS_PER_SESSION = CONFIG.maxTabsPerSession;
 const MAX_TABS_GLOBAL = CONFIG.maxTabsGlobal;
@@ -184,39 +226,70 @@ const PAGE_CLOSE_TIMEOUT_MS = 5000;
 const NAVIGATE_TIMEOUT_MS = CONFIG.navigateTimeoutMs;
 const BUILDREFS_TIMEOUT_MS = CONFIG.buildrefsTimeoutMs;
 const FAILURE_THRESHOLD = 3;
-const TAB_LOCK_TIMEOUT_MS = 30000;
+const MAX_CONSECUTIVE_TIMEOUTS = 3;
+const TAB_LOCK_TIMEOUT_MS = 35000; // Must be > HANDLER_TIMEOUT_MS so active op times out first
+
+// Proper mutex for tab serialization. The old Promise-chain lock on timeout proceeded
+// WITHOUT the lock, allowing concurrent Playwright operations that corrupt CDP state.
+class TabLock {
+  constructor() {
+    this.queue = [];
+    this.active = false;
+  }
 
-// Per-tab locks to serialize operations on the same tab
-// tabId -> Promise (the currently executing operation)
-const tabLocks = new Map();
+  acquire(timeoutMs) {
+    return new Promise((resolve, reject) => {
+      const entry = { resolve, reject, timer: null };
+      entry.timer = setTimeout(() => {
+        const idx = this.queue.indexOf(entry);
+        if (idx !== -1) this.queue.splice(idx, 1);
+        reject(new Error('Tab lock queue timeout'));
+      }, timeoutMs);
+      this.queue.push(entry);
+      this._tryNext();
+    });
+  }
 
-async function withTabLock(tabId, operation) {
-  // Wait for any pending operation on this tab to complete
-  const pending = tabLocks.get(tabId);
-  if (pending) {
-    try {
-      await Promise.race([
-        pending,
-        new Promise((_, reject) => setTimeout(() => reject(new Error('Tab lock timeout')), TAB_LOCK_TIMEOUT_MS))
-      ]);
-    } catch (e) {
-      if (e.message === 'Tab lock timeout') {
-        log('warn', 'tab lock timeout, proceeding', { tabId });
-      }
+  release() {
+    this.active = false;
+    this._tryNext();
+  }
+
+  _tryNext() {
+    if (this.active || this.queue.length === 0) return;
+    this.active = true;
+    const entry = this.queue.shift();
+    clearTimeout(entry.timer);
+    entry.resolve();
+  }
+
+  drain() {
+    this.active = true;
+    for (const entry of this.queue) {
+      clearTimeout(entry.timer);
+      entry.reject(new Error('Tab destroyed'));
     }
+    this.queue = [];
   }
-  
-  // Execute this operation and store the promise
-  const promise = operation();
-  tabLocks.set(tabId, promise);
-  
+}
+
+// Per-tab locks to serialize operations on the same tab
+const tabLocks = new Map(); // tabId -> TabLock
+
+function getTabLock(tabId) {
+  if (!tabLocks.has(tabId)) tabLocks.set(tabId, new TabLock());
+  return tabLocks.get(tabId);
+}
+
+// Timeout is INSIDE the lock so each operation gets its full budget
+// regardless of how long it waited in the queue.
+async function withTabLock(tabId, operation, timeoutMs = HANDLER_TIMEOUT_MS) {
+  const lock = getTabLock(tabId);
+  await lock.acquire(TAB_LOCK_TIMEOUT_MS);
   try {
-    return await promise;
+    return await withTimeout(operation(), timeoutMs, 'action');
   } finally {
-    // Clean up if this is still the active lock
-    if (tabLocks.get(tabId) === promise) {
-      tabLocks.delete(tabId);
-    }
+    lock.release();
   }
 }
 
@@ -425,6 +498,20 @@ function normalizeUserId(userId) {
 async function getSession(userId) {
   const key = normalizeUserId(userId);
   let session = sessions.get(key);
+  
+  // Check if existing session's context is still alive
+  if (session) {
+    try {
+      // Lightweight probe: pages() is synchronous-ish and throws if context is dead
+      session.context.pages();
+    } catch (err) {
+      log('warn', 'session context dead, recreating', { userId: key, error: err.message });
+      session.context.close().catch(() => {});
+      sessions.delete(key);
+      session = null;
+    }
+  }
+  
   if (!session) {
     if (sessions.size >= MAX_SESSIONS) {
       throw new Error('Maximum concurrent sessions reached');
@@ -460,6 +547,94 @@ function getTabGroup(session, listItemId) {
   return group;
 }
 
+function isDeadContextError(err) {
+  const msg = err && err.message || '';
+  return msg.includes('Target page, context or browser has been closed') ||
+         msg.includes('browser has been closed') ||
+         msg.includes('Context closed') ||
+         msg.includes('Browser closed');
+}
+
+function isTimeoutError(err) {
+  const msg = err && err.message || '';
+  return msg.includes('timed out after') ||
+         (msg.includes('Timeout') && msg.includes('exceeded'));
+}
+
+function isTabLockQueueTimeout(err) {
+  return err && err.message === 'Tab lock queue timeout';
+}
+
+function isTabDestroyedError(err) {
+  return err && err.message === 'Tab destroyed';
+}
+
+// Centralized error handler for route catch blocks.
+// Auto-destroys dead browser sessions and returns appropriate status codes.
+function handleRouteError(err, req, res, extraFields = {}) {
+  const userId = req.body?.userId || req.query?.userId;
+  if (userId && isDeadContextError(err)) {
+    destroySession(userId);
+  }
+  // Track consecutive timeouts per tab and auto-destroy stuck tabs
+  if (userId && isTimeoutError(err)) {
+    const tabId = req.body?.tabId || req.query?.tabId || req.params?.tabId;
+    const session = sessions.get(normalizeUserId(userId));
+    if (session && tabId) {
+      const found = findTab(session, tabId);
+      if (found) {
+        found.tabState.consecutiveTimeouts++;
+        if (found.tabState.consecutiveTimeouts >= MAX_CONSECUTIVE_TIMEOUTS) {
+          log('warn', 'auto-destroying tab after consecutive timeouts', { tabId, count: found.tabState.consecutiveTimeouts });
+          destroyTab(session, tabId);
+        }
+      }
+    }
+  }
+  // Lock queue timeout = tab is stuck. Destroy immediately.
+  if (userId && isTabLockQueueTimeout(err)) {
+    const tabId = req.body?.tabId || req.query?.tabId || req.params?.tabId;
+    const session = sessions.get(normalizeUserId(userId));
+    if (session && tabId) {
+      destroyTab(session, tabId);
+    }
+    return res.status(503).json({ error: 'Tab unresponsive and has been destroyed. Open a new tab.', ...extraFields });
+  }
+  // Tab was destroyed while this request was queued in the lock
+  if (isTabDestroyedError(err)) {
+    return res.status(410).json({ error: 'Tab was destroyed. Open a new tab.', ...extraFields });
+  }
+  sendError(res, err, extraFields);
+}
+
+function destroyTab(session, tabId) {
+  const lock = tabLocks.get(tabId);
+  if (lock) {
+    lock.drain();
+    tabLocks.delete(tabId);
+  }
+  for (const [listItemId, group] of session.tabGroups) {
+    if (group.has(tabId)) {
+      const tabState = group.get(tabId);
+      log('warn', 'destroying stuck tab', { tabId, listItemId, toolCalls: tabState.toolCalls });
+      safePageClose(tabState.page);
+      group.delete(tabId);
+      if (group.size === 0) session.tabGroups.delete(listItemId);
+      return true;
+    }
+  }
+  return false;
+}
+
+function destroySession(userId) {
+  const key = normalizeUserId(userId);
+  const session = sessions.get(key);
+  if (!session) return;
+  log('warn', 'destroying dead session', { userId: key });
+  session.context.close().catch(() => {});
+  sessions.delete(key);
+}
+
 function findTab(session, tabId) {
   for (const [listItemId, group] of session.tabGroups) {
     if (group.has(tabId)) {
@@ -475,11 +650,15 @@ function createTabState(page) {
     page,
     refs: new Map(),
     visitedUrls: new Set(),
+    downloads: [],
     toolCalls: 0,
+    consecutiveTimeouts: 0,
     lastSnapshot: null,
   };
 }
 
+
+
 async function waitForPageReady(page, options = {}) {
   const { timeout = 10000, waitForNetwork = true } = options;
   
@@ -569,6 +748,156 @@ async function dismissConsentDialogs(page) {
   }
 }
 
+// --- Google SERP detection ---
+function isGoogleSerp(url) {
+  try {
+    const parsed = new URL(url);
+    return parsed.hostname.includes('google.') && parsed.pathname === '/search';
+  } catch {
+    return false;
+  }
+}
+
+// --- Google SERP: combined extraction (refs + snapshot in one DOM pass) ---
+// Returns { refs: Map, snapshot: string }
+async function extractGoogleSerp(page) {
+  const refs = new Map();
+  if (!page || page.isClosed()) return { refs, snapshot: '' };
+  
+  const start = Date.now();
+  
+  const alreadyRendered = await page.evaluate(() => !!document.querySelector('#rso h3, #search h3, #rso [data-snhf]')).catch(() => false);
+  if (!alreadyRendered) {
+    try {
+      await page.waitForSelector('#rso h3, #search h3, #rso [data-snhf]', { timeout: 5000 });
+    } catch {
+      try {
+        await page.waitForSelector('#rso a[href]:not([href^="/search"]), #search a[href]:not([href^="/search"])', { timeout: 2000 });
+      } catch {}
+    }
+  }
+  
+  const extracted = await page.evaluate(() => {
+    const snapshot = [];
+    const elements = [];
+    let refCounter = 1;
+    
+    function addRef(role, name) {
+      const id = 'e' + refCounter++;
+      elements.push({ id, role, name });
+      return id;
+    }
+    
+    snapshot.push('- heading "' + document.title.replace(/"/g, '\\"') + '"');
+    
+    const searchInput = document.querySelector('input[name="q"], textarea[name="q"]');
+    if (searchInput) {
+      const name = 'Search';
+      const refId = addRef('searchbox', name);
+      snapshot.push('- searchbox "' + name + '" [' + refId + ']: ' + (searchInput.value || ''));
+    }
+    
+    const navContainer = document.querySelector('div[role="navigation"], div[role="list"]');
+    if (navContainer) {
+      const navLinks = navContainer.querySelectorAll('a');
+      if (navLinks.length > 0) {
+        snapshot.push('- navigation:');
+        navLinks.forEach(a => {
+          const text = (a.textContent || '').trim();
+          if (!text || text.length < 1) return;
+          if (/^\d+$/.test(text) && parseInt(text) < 50) return;
+          const refId = addRef('link', text);
+          snapshot.push('  - link "' + text + '" [' + refId + ']');
+        });
+      }
+    }
+    
+    const resultContainer = document.querySelector('#rso') || document.querySelector('#search');
+    if (resultContainer) {
+      const resultBlocks = resultContainer.querySelectorAll(':scope > div');
+      for (const block of resultBlocks) {
+        const h3 = block.querySelector('h3');
+        const mainLink = h3 ? h3.closest('a') : null;
+        
+        if (h3 && mainLink) {
+          const title = h3.textContent.trim().replace(/"/g, '\\"');
+          const href = mainLink.href;
+          const cite = block.querySelector('cite');
+          const displayUrl = cite ? cite.textContent.trim() : '';
+          
+          let snippet = '';
+          for (const sel of ['[data-sncf]', '[data-content-feature="1"]', '.VwiC3b', 'div[style*="-webkit-line-clamp"]', 'span.aCOpRe']) {
+            const el = block.querySelector(sel);
+            if (el) { snippet = el.textContent.trim().slice(0, 300); break; }
+          }
+          if (!snippet) {
+            const allText = block.textContent.trim().replace(/\s+/g, ' ');
+            const titleLen = title.length + (displayUrl ? displayUrl.length : 0);
+            if (allText.length > titleLen + 20) {
+              snippet = allText.slice(titleLen).trim().slice(0, 300);
+            }
+          }
+          
+          const refId = addRef('link', title);
+          snapshot.push('- link "' + title + '" [' + refId + ']:');
+          snapshot.push('  - /url: ' + href);
+          if (displayUrl) snapshot.push('  - cite: ' + displayUrl);
+          if (snippet) snapshot.push('  - text: ' + snippet);
+        } else {
+          const blockLinks = block.querySelectorAll('a[href^="http"]:not([href*="google.com/search"])');
+          if (blockLinks.length > 0) {
+            const blockText = block.textContent.trim().replace(/\s+/g, ' ').slice(0, 200);
+            if (blockText.length > 10) {
+              snapshot.push('- group:');
+              snapshot.push('  - text: ' + blockText);
+              blockLinks.forEach(a => {
+                const linkText = (a.textContent || '').trim().replace(/"/g, '\\"').slice(0, 100);
+                if (linkText.length > 2) {
+                  const refId = addRef('link', linkText);
+                  snapshot.push('  - link "' + linkText + '" [' + refId + ']:');
+                  snapshot.push('    - /url: ' + a.href);
+                }
+              });
+            }
+          }
+        }
+      }
+    }
+    
+    const paaItems = document.querySelectorAll('[jsname="Cpkphb"], div.related-question-pair');
+    if (paaItems.length > 0) {
+      snapshot.push('- heading "People also ask"');
+      paaItems.forEach(q => {
+        const text = (q.textContent || '').trim().replace(/"/g, '\\"').slice(0, 150);
+        if (text) {
+          const refId = addRef('button', text);
+          snapshot.push('  - button "' + text + '" [' + refId + ']');
+        }
+      });
+    }
+    
+    const nextLink = document.querySelector('#botstuff a[aria-label="Next page"], td.d6cvqb a, a#pnnext');
+    if (nextLink) {
+      const refId = addRef('link', 'Next');
+      snapshot.push('- navigation "pagination":');
+      snapshot.push('  - link "Next" [' + refId + ']');
+    }
+    
+    return { snapshot: snapshot.join('\n'), elements };
+  });
+  
+  const seenCounts = new Map();
+  for (const el of extracted.elements) {
+    const key = `${el.role}:${el.name}`;
+    const nth = seenCounts.get(key) || 0;
+    seenCounts.set(key, nth + 1);
+    refs.set(el.id, { role: el.role, name: el.name, nth });
+  }
+  
+  log('info', 'extractGoogleSerp', { elapsed: Date.now() - start, refs: refs.size });
+  return { refs, snapshot: extracted.snapshot };
+}
+
 async function buildRefs(page) {
   const refs = new Map();
   
@@ -577,6 +906,13 @@ async function buildRefs(page) {
     return refs;
   }
   
+  // Google SERP fast path — skip ariaSnapshot entirely
+  const url = page.url();
+  if (isGoogleSerp(url)) {
+    const { refs: googleRefs } = await extractGoogleSerp(page);
+    return googleRefs;
+  }
+  
   const start = Date.now();
   
   // Hard total timeout on the entire buildRefs operation
@@ -719,7 +1055,12 @@ app.post('/youtube/transcript', async (req, res) => {
 
     let result;
     if (hasYtDlp()) {
-      result = await ytDlpTranscript(reqId, url, videoId, lang);
+      try {
+        result = await ytDlpTranscript(reqId, url, videoId, lang);
+      } catch (ytErr) {
+        log('warn', 'yt-dlp failed, falling back to browser', { reqId, error: ytErr.message });
+        result = await browserTranscript(reqId, url, videoId, lang);
+      }
     } else {
       result = await browserTranscript(reqId, url, videoId, lang);
     }
@@ -759,16 +1100,52 @@ async function browserTranscript(reqId, url, videoId, lang) {
       await page.goto(url, { waitUntil: 'domcontentloaded', timeout: NAVIGATE_TIMEOUT_MS });
       await page.waitForTimeout(2000);
 
+      // Extract caption track URLs and metadata from ytInitialPlayerResponse
       const meta = await page.evaluate(() => {
         const r = window.ytInitialPlayerResponse || (typeof ytInitialPlayerResponse !== 'undefined' ? ytInitialPlayerResponse : null);
-        if (!r) return { title: '' };
+        if (!r) return { title: '', tracks: [] };
         const tracks = r?.captions?.playerCaptionsTracklistRenderer?.captionTracks || [];
         return {
           title: r?.videoDetails?.title || '',
-          languages: tracks.map(t => ({ code: t.languageCode, name: t.name?.simpleText || t.languageCode, kind: t.kind || 'manual' })),
+          tracks: tracks.map(t => ({ code: t.languageCode, name: t.name?.simpleText || t.languageCode, kind: t.kind || 'manual', url: t.baseUrl })),
         };
       });
 
+      log('info', 'youtube transcript: extracted caption tracks', { reqId, title: meta.title, trackCount: meta.tracks.length, tracks: meta.tracks.map(t => t.code) });
+
+      // Strategy A: Fetch caption track URL directly from ytInitialPlayerResponse
+      // These URLs are freshly signed by YouTube and work immediately
+      if (meta.tracks && meta.tracks.length > 0) {
+        const track = meta.tracks.find(t => t.code === lang) || meta.tracks[0];
+        if (track && track.url) {
+          const captionUrl = track.url + (track.url.includes('?') ? '&' : '?') + 'fmt=json3';
+          log('info', 'youtube transcript: fetching caption track', { reqId, lang: track.code, url: captionUrl.substring(0, 100) });
+          try {
+            const captionResp = await page.evaluate(async (fetchUrl) => {
+              const resp = await fetch(fetchUrl);
+              return resp.ok ? await resp.text() : null;
+            }, captionUrl);
+            if (captionResp && captionResp.length > 0) {
+              let transcriptText = null;
+              if (captionResp.trimStart().startsWith('{')) transcriptText = parseJson3(captionResp);
+              else if (captionResp.includes('WEBVTT')) transcriptText = parseVtt(captionResp);
+              else if (captionResp.includes('<text')) transcriptText = parseXml(captionResp);
+              if (transcriptText && transcriptText.trim()) {
+                return {
+                  status: 'ok', transcript: transcriptText,
+                  video_url: url, video_id: videoId, video_title: meta.title,
+                  language: track.code, total_words: transcriptText.split(/\s+/).length,
+                  available_languages: meta.tracks.map(t => ({ code: t.code, name: t.name, kind: t.kind })),
+                };
+              }
+            }
+          } catch (fetchErr) {
+            log('warn', 'youtube transcript: caption track fetch failed', { reqId, error: fetchErr.message });
+          }
+        }
+      }
+
+      // Strategy B: Play video and intercept timedtext network response
       await page.evaluate(() => {
         const v = document.querySelector('video');
         if (v) { v.muted = true; v.play().catch(() => {}); }
@@ -781,7 +1158,7 @@ async function browserTranscript(reqId, url, videoId, lang) {
       if (!interceptedCaptions) {
         return {
           status: 'error', code: 404,
-          message: 'No captions loaded during playback (video may have no captions, or ad blocked it)',
+          message: 'No captions available for this video',
           video_url: url, video_id: videoId, title: meta.title,
         };
       }
@@ -838,33 +1215,42 @@ app.post('/tabs', async (req, res) => {
       return res.status(400).json({ error: 'userId and sessionKey required' });
     }
     
-    const session = await getSession(userId);
-    
-    let totalTabs = 0;
-    for (const group of session.tabGroups.values()) totalTabs += group.size;
-    if (totalTabs >= MAX_TABS_PER_SESSION) {
-      return res.status(429).json({ error: 'Maximum tabs per session reached' });
-    }
-    
-    const group = getTabGroup(session, resolvedSessionKey);
-    
-    const page = await session.context.newPage();
-    const tabId = crypto.randomUUID();
-    const tabState = createTabState(page);
-    group.set(tabId, tabState);
-    
-    if (url) {
-      const urlErr = validateUrl(url);
-      if (urlErr) return res.status(400).json({ error: urlErr });
-      await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
-      tabState.visitedUrls.add(url);
-    }
-    
-    log('info', 'tab created', { reqId: req.reqId, tabId, userId, sessionKey: resolvedSessionKey, url: page.url() });
-    res.json({ tabId, url: page.url() });
+    const result = await withTimeout((async () => {
+      const session = await getSession(userId);
+      
+      let totalTabs = 0;
+      for (const group of session.tabGroups.values()) totalTabs += group.size;
+      if (totalTabs >= MAX_TABS_PER_SESSION) {
+        throw Object.assign(new Error('Maximum tabs per session reached'), { statusCode: 429 });
+      }
+      
+      if (getTotalTabCount() >= MAX_TABS_GLOBAL) {
+        throw Object.assign(new Error('Maximum global tabs reached'), { statusCode: 429 });
+      }
+      
+      const group = getTabGroup(session, resolvedSessionKey);
+      
+      const page = await session.context.newPage();
+      const tabId = crypto.randomUUID();
+      const tabState = createTabState(page);
+      attachDownloadListener(tabState, tabId);
+      group.set(tabId, tabState);
+      
+      if (url) {
+        const urlErr = validateUrl(url);
+        if (urlErr) throw Object.assign(new Error(urlErr), { statusCode: 400 });
+        await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
+        tabState.visitedUrls.add(url);
+      }
+      
+      log('info', 'tab created', { reqId: req.reqId, tabId, userId, sessionKey: resolvedSessionKey, url: page.url() });
+      return { tabId, url: page.url() };
+    })(), HANDLER_TIMEOUT_MS, 'tab create');
+
+    res.json(result);
   } catch (err) {
     log('error', 'tab create failed', { reqId: req.reqId, error: err.message });
-    res.status(500).json({ error: safeError(err) });
+    handleRouteError(err, req, res);
   }
 });
 
@@ -906,7 +1292,7 @@ app.post('/tabs/:tabId/navigate', async (req, res) => {
             const group = getTabGroup(session, resolvedSessionKey);
             if (oldestGroup) oldestGroup.delete(oldestTabId);
             group.set(tabId, tabState);
-            tabLocks.delete(oldestTabId);
+            { const _l = tabLocks.get(oldestTabId); if (_l) _l.drain(); tabLocks.delete(oldestTabId); }
             log('info', 'tab recycled (limit reached)', { reqId: req.reqId, tabId, recycledFrom: oldestTabId, userId });
           } else {
             throw new Error('Maximum tabs per session reached');
@@ -914,6 +1300,7 @@ app.post('/tabs/:tabId/navigate', async (req, res) => {
         } else {
           const page = await session.context.newPage();
           tabState = createTabState(page);
+          attachDownloadListener(tabState, tabId, log);
           const group = getTabGroup(session, resolvedSessionKey);
           group.set(tabId, tabState);
           log('info', 'tab auto-created on navigate', { reqId: req.reqId, tabId, userId });
@@ -921,7 +1308,7 @@ app.post('/tabs/:tabId/navigate', async (req, res) => {
       } else {
         tabState = found.tabState;
       }
-      tabState.toolCalls++;
+      tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
       
       let targetUrl = url;
       if (macro) {
@@ -937,6 +1324,15 @@ app.post('/tabs/:tabId/navigate', async (req, res) => {
         await tabState.page.goto(targetUrl, { waitUntil: 'domcontentloaded', timeout: 30000 });
         tabState.visitedUrls.add(targetUrl);
         tabState.lastSnapshot = null;
+        
+        // For Google SERP: skip eager ref building during navigate.
+        // Results render asynchronously after DOMContentLoaded — the snapshot
+        // call will wait for and extract them.
+        if (isGoogleSerp(tabState.page.url())) {
+          tabState.refs = new Map();
+          return { ok: true, tabId, url: tabState.page.url(), refsAvailable: false, googleSerp: true };
+        }
+        
         tabState.refs = await buildRefs(tabState.page);
         return { ok: true, tabId, url: tabState.page.url(), refsAvailable: tabState.refs.size > 0 };
       });
@@ -947,7 +1343,10 @@ app.post('/tabs/:tabId/navigate', async (req, res) => {
   } catch (err) {
     log('error', 'navigate failed', { reqId: req.reqId, tabId, error: err.message });
     const status = err.message && err.message.startsWith('Blocked URL scheme') ? 400 : 500;
-    res.status(status).json({ error: safeError(err) });
+    if (status === 400) {
+      return res.status(400).json({ error: safeError(err) });
+    }
+    handleRouteError(err, req, res);
   }
 });
 
@@ -963,7 +1362,7 @@ app.get('/tabs/:tabId/snapshot', async (req, res) => {
     if (!found) return res.status(404).json({ error: 'Tab not found' });
     
     const { tabState } = found;
-    tabState.toolCalls++;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
 
     // Cached chunk retrieval for offset>0 requests
     if (offset > 0 && tabState.lastSnapshot) {
@@ -978,6 +1377,31 @@ app.get('/tabs/:tabId/snapshot', async (req, res) => {
     }
 
     const result = await withUserLimit(userId, () => withTimeout((async () => {
+      const pageUrl = tabState.page.url();
+      
+      // Google SERP fast path — DOM extraction instead of ariaSnapshot
+      if (isGoogleSerp(pageUrl)) {
+        const { refs: googleRefs, snapshot: googleSnapshot } = await extractGoogleSerp(tabState.page);
+        tabState.refs = googleRefs;
+        tabState.lastSnapshot = googleSnapshot;
+        const annotatedYaml = googleSnapshot;
+        const win = windowSnapshot(annotatedYaml, 0);
+        const response = {
+          url: pageUrl,
+          snapshot: win.text,
+          refsCount: tabState.refs.size,
+          truncated: win.truncated,
+          totalChars: win.totalChars,
+          hasMore: win.hasMore,
+          nextOffset: win.nextOffset,
+        };
+        if (req.query.includeScreenshot === 'true') {
+          const pngBuffer = await tabState.page.screenshot({ type: 'png' });
+          response.screenshot = { data: pngBuffer.toString('base64'), mimeType: 'image/png' };
+        }
+        return response;
+      }
+      
       tabState.refs = await buildRefs(tabState.page);
       const ariaYaml = await getAriaSnapshot(tabState.page);
       
@@ -1040,7 +1464,7 @@ app.get('/tabs/:tabId/snapshot', async (req, res) => {
     res.json(result);
   } catch (err) {
     log('error', 'snapshot failed', { reqId: req.reqId, tabId: req.params.tabId, error: err.message });
-    res.status(500).json({ error: safeError(err) });
+    handleRouteError(err, req, res);
   }
 });
 
@@ -1058,7 +1482,7 @@ app.post('/tabs/:tabId/wait', async (req, res) => {
     res.json({ ok: true, ready });
   } catch (err) {
     log('error', 'wait failed', { reqId: req.reqId, error: err.message });
-    res.status(500).json({ error: safeError(err) });
+    handleRouteError(err, req, res);
   }
 });
 
@@ -1074,13 +1498,15 @@ app.post('/tabs/:tabId/click', async (req, res) => {
     if (!found) return res.status(404).json({ error: 'Tab not found' });
     
     const { tabState } = found;
-    tabState.toolCalls++;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
     
     if (!ref && !selector) {
       return res.status(400).json({ error: 'ref or selector required' });
     }
     
-    const result = await withUserLimit(userId, () => withTimeout(withTabLock(tabId, async () => {
+    const result = await withUserLimit(userId, () => withTabLock(tabId, async () => {
+      const clickStart = Date.now();
+      const remainingBudget = () => Math.max(0, HANDLER_TIMEOUT_MS - 2000 - (Date.now() - clickStart));
       // Full mouse event sequence for stubborn JS click handlers (mirrors Swift WebView.swift)
       // Dispatches: mouseover → mouseenter → mousedown → mouseup → click
       const dispatchMouseSequence = async (locator) => {
@@ -1102,18 +1528,32 @@ app.post('/tabs/:tabId/click', async (req, res) => {
         log('info', 'mouse sequence dispatched', { x: x.toFixed(0), y: y.toFixed(0) });
       };
       
+      // On Google SERPs, skip the normal click attempt (always intercepted by overlays)
+      // and go directly to force click — saves 5s timeout per click
+      const onGoogleSerp = isGoogleSerp(tabState.page.url());
+      
       const doClick = async (locatorOrSelector, isLocator) => {
         const locator = isLocator ? locatorOrSelector : tabState.page.locator(locatorOrSelector);
         
+        if (onGoogleSerp) {
+          try {
+            await locator.click({ timeout: 3000, force: true });
+          } catch (forceErr) {
+            log('warn', 'google force click failed, trying mouse sequence');
+            await dispatchMouseSequence(locator);
+          }
+          return;
+        }
+        
         try {
           // First try normal click (respects visibility, enabled, not-obscured)
-          await locator.click({ timeout: 5000 });
+          await locator.click({ timeout: 3000 });
         } catch (err) {
           // Fallback 1: If intercepted by overlay, retry with force
           if (err.message.includes('intercepts pointer events')) {
             log('warn', 'click intercepted, retrying with force');
             try {
-              await locator.click({ timeout: 5000, force: true });
+              await locator.click({ timeout: 3000, force: true });
             } catch (forceErr) {
               // Fallback 2: Full mouse event sequence for stubborn JS handlers
               log('warn', 'force click failed, trying mouse sequence');
@@ -1131,35 +1571,93 @@ app.post('/tabs/:tabId/click', async (req, res) => {
       
       if (ref) {
         let locator = refToLocator(tabState.page, ref, tabState.refs);
-        if (!locator && tabState.refs.size === 0) {
-          // Auto-refresh refs on stale state before failing
-          log('info', 'auto-refreshing stale refs before click', { ref });
-          tabState.refs = await buildRefs(tabState.page);
+        if (!locator) {
+          // Use tight timeout (4s max) to leave budget for click + post-click buildRefs
+          log('info', 'auto-refreshing refs before click', { ref, hadRefs: tabState.refs.size });
+          try {
+            const preClickBudget = Math.min(4000, remainingBudget());
+            const refreshPromise = buildRefs(tabState.page);
+            const refreshBudget = new Promise((_, reject) => setTimeout(() => reject(new Error('pre_click_refs_timeout')), preClickBudget));
+            tabState.refs = await Promise.race([refreshPromise, refreshBudget]);
+          } catch (e) {
+            if (e.message === 'pre_click_refs_timeout' || e.message === 'buildRefs_timeout') {
+              log('warn', 'pre-click buildRefs timed out, proceeding without refresh');
+            } else {
+              throw e;
+            }
+          }
           locator = refToLocator(tabState.page, ref, tabState.refs);
         }
         if (!locator) {
           const maxRef = tabState.refs.size > 0 ? `e${tabState.refs.size}` : 'none';
-          throw new Error(`Unknown ref: ${ref} (valid refs: e1-${maxRef}, ${tabState.refs.size} total). Refs reset after navigation - call snapshot first.`);
+          throw new StaleRefsError(ref, maxRef, tabState.refs.size);
         }
         await doClick(locator, true);
       } else {
         await doClick(selector, false);
       }
       
-      await tabState.page.waitForTimeout(500);
+      // If clicking on a Google SERP, wait for potential navigation to complete
+      if (onGoogleSerp) {
+        try {
+          await tabState.page.waitForLoadState('domcontentloaded', { timeout: 3000 });
+        } catch {}
+        await tabState.page.waitForTimeout(200);
+        // Skip buildRefs here — SERP clicks typically navigate to a new page,
+        // and the caller always requests /snapshot next which rebuilds refs.
+        tabState.lastSnapshot = null;
+        tabState.refs = new Map();
+        const newUrl = tabState.page.url();
+        tabState.visitedUrls.add(newUrl);
+        return { ok: true, url: newUrl, refsAvailable: false };
+      } else {
+        await tabState.page.waitForTimeout(500);
+      }
       tabState.lastSnapshot = null;
-      tabState.refs = await buildRefs(tabState.page);
+      // buildRefs after click — use remaining budget (min 2s) so we don't blow the handler timeout.
+      // If it times out, return without refs (caller's next /snapshot will rebuild them).
+      const postClickBudget = Math.max(2000, remainingBudget());
+      try {
+        const refsPromise = buildRefs(tabState.page);
+        const refsBudget = new Promise((_, reject) => setTimeout(() => reject(new Error('post_click_refs_timeout')), postClickBudget));
+        tabState.refs = await Promise.race([refsPromise, refsBudget]);
+      } catch (e) {
+        if (e.message === 'post_click_refs_timeout' || e.message === 'buildRefs_timeout') {
+          log('warn', 'post-click buildRefs timed out, returning without refs', { budget: postClickBudget, elapsed: Date.now() - clickStart });
+          tabState.refs = new Map();
+        } else {
+          throw e;
+        }
+      }
       
       const newUrl = tabState.page.url();
       tabState.visitedUrls.add(newUrl);
       return { ok: true, url: newUrl, refsAvailable: tabState.refs.size > 0 };
-    }), HANDLER_TIMEOUT_MS, 'click'));
+    }));
     
     log('info', 'clicked', { reqId: req.reqId, tabId, url: result.url });
     res.json(result);
   } catch (err) {
     log('error', 'click failed', { reqId: req.reqId, tabId, error: err.message });
-    res.status(500).json({ error: safeError(err) });
+    if (err.message?.includes('timed out')) {
+      try {
+        const session = sessions.get(normalizeUserId(req.body.userId));
+        const found = session && findTab(session, tabId);
+        if (found?.tabState?.page && !found.tabState.page.isClosed()) {
+          found.tabState.refs = await buildRefs(found.tabState.page);
+          found.tabState.lastSnapshot = null;
+          return res.status(500).json({
+            error: safeError(err),
+            hint: 'The page may have changed. Call snapshot to see the current state and retry.',
+            url: found.tabState.page.url(),
+            refsCount: found.tabState.refs.size,
+          });
+        }
+      } catch (refreshErr) {
+        log('warn', 'post-timeout refresh failed', { error: refreshErr.message });
+      }
+    }
+    handleRouteError(err, req, res);
   }
 });
 
@@ -1174,7 +1672,7 @@ app.post('/tabs/:tabId/type', async (req, res) => {
     if (!found) return res.status(404).json({ error: 'Tab not found' });
     
     const { tabState } = found;
-    tabState.toolCalls++;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
     
     if (!ref && !selector) {
       return res.status(400).json({ error: 'ref or selector required' });
@@ -1182,8 +1680,13 @@ app.post('/tabs/:tabId/type', async (req, res) => {
     
     await withTabLock(tabId, async () => {
       if (ref) {
-        const locator = refToLocator(tabState.page, ref, tabState.refs);
-        if (!locator) throw new Error(`Unknown ref: ${ref}`);
+        let locator = refToLocator(tabState.page, ref, tabState.refs);
+        if (!locator) {
+          log('info', 'auto-refreshing refs before fill', { ref, hadRefs: tabState.refs.size });
+          tabState.refs = await buildRefs(tabState.page);
+          locator = refToLocator(tabState.page, ref, tabState.refs);
+        }
+        if (!locator) { const maxRef = tabState.refs.size > 0 ? `e${tabState.refs.size}` : 'none'; throw new StaleRefsError(ref, maxRef, tabState.refs.size); }
         await locator.fill(text, { timeout: 10000 });
       } else {
         await tabState.page.fill(selector, text, { timeout: 10000 });
@@ -1193,7 +1696,25 @@ app.post('/tabs/:tabId/type', async (req, res) => {
     res.json({ ok: true });
   } catch (err) {
     log('error', 'type failed', { reqId: req.reqId, error: err.message });
-    res.status(500).json({ error: safeError(err) });
+    if (err.message?.includes('timed out') || err.message?.includes('not an <input>')) {
+      try {
+        const session = sessions.get(normalizeUserId(req.body.userId));
+        const found = session && findTab(session, tabId);
+        if (found?.tabState?.page && !found.tabState.page.isClosed()) {
+          found.tabState.refs = await buildRefs(found.tabState.page);
+          found.tabState.lastSnapshot = null;
+          return res.status(500).json({
+            error: safeError(err),
+            hint: 'The page may have changed. Call snapshot to see the current state and retry.',
+            url: found.tabState.page.url(),
+            refsCount: found.tabState.refs.size,
+          });
+        }
+      } catch (refreshErr) {
+        log('warn', 'post-timeout refresh failed', { error: refreshErr.message });
+      }
+    }
+    handleRouteError(err, req, res);
   }
 });
 
@@ -1208,7 +1729,7 @@ app.post('/tabs/:tabId/press', async (req, res) => {
     if (!found) return res.status(404).json({ error: 'Tab not found' });
     
     const { tabState } = found;
-    tabState.toolCalls++;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
     
     await withTabLock(tabId, async () => {
       await tabState.page.keyboard.press(key);
@@ -1217,7 +1738,7 @@ app.post('/tabs/:tabId/press', async (req, res) => {
     res.json({ ok: true });
   } catch (err) {
     log('error', 'press failed', { reqId: req.reqId, error: err.message });
-    res.status(500).json({ error: safeError(err) });
+    handleRouteError(err, req, res);
   }
 });
 
@@ -1230,7 +1751,7 @@ app.post('/tabs/:tabId/scroll', async (req, res) => {
     if (!found) return res.status(404).json({ error: 'Tab not found' });
     
     const { tabState } = found;
-    tabState.toolCalls++;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
     
     const delta = direction === 'up' ? -amount : amount;
     await tabState.page.mouse.wheel(0, delta);
@@ -1239,7 +1760,7 @@ app.post('/tabs/:tabId/scroll', async (req, res) => {
     res.json({ ok: true });
   } catch (err) {
     log('error', 'scroll failed', { reqId: req.reqId, error: err.message });
-    res.status(500).json({ error: safeError(err) });
+    handleRouteError(err, req, res);
   }
 });
 
@@ -1254,18 +1775,18 @@ app.post('/tabs/:tabId/back', async (req, res) => {
     if (!found) return res.status(404).json({ error: 'Tab not found' });
     
     const { tabState } = found;
-    tabState.toolCalls++;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
     
-    const result = await withTimeout(withTabLock(tabId, async () => {
+    const result = await withTabLock(tabId, async () => {
       await tabState.page.goBack({ timeout: 10000 });
       tabState.refs = await buildRefs(tabState.page);
       return { ok: true, url: tabState.page.url() };
-    }), HANDLER_TIMEOUT_MS, 'back');
+    });
     
     res.json(result);
   } catch (err) {
     log('error', 'back failed', { reqId: req.reqId, error: err.message });
-    res.status(500).json({ error: safeError(err) });
+    handleRouteError(err, req, res);
   }
 });
 
@@ -1280,18 +1801,18 @@ app.post('/tabs/:tabId/forward', async (req, res) => {
     if (!found) return res.status(404).json({ error: 'Tab not found' });
     
     const { tabState } = found;
-    tabState.toolCalls++;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
     
-    const result = await withTimeout(withTabLock(tabId, async () => {
+    const result = await withTabLock(tabId, async () => {
       await tabState.page.goForward({ timeout: 10000 });
       tabState.refs = await buildRefs(tabState.page);
       return { ok: true, url: tabState.page.url() };
-    }), HANDLER_TIMEOUT_MS, 'forward');
+    });
     
     res.json(result);
   } catch (err) {
     log('error', 'forward failed', { reqId: req.reqId, error: err.message });
-    res.status(500).json({ error: safeError(err) });
+    handleRouteError(err, req, res);
   }
 });
 
@@ -1306,18 +1827,18 @@ app.post('/tabs/:tabId/refresh', async (req, res) => {
     if (!found) return res.status(404).json({ error: 'Tab not found' });
     
     const { tabState } = found;
-    tabState.toolCalls++;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
     
-    const result = await withTimeout(withTabLock(tabId, async () => {
+    const result = await withTabLock(tabId, async () => {
       await tabState.page.reload({ timeout: 30000 });
       tabState.refs = await buildRefs(tabState.page);
       return { ok: true, url: tabState.page.url() };
-    }), HANDLER_TIMEOUT_MS, 'refresh');
+    });
     
     res.json(result);
   } catch (err) {
     log('error', 'refresh failed', { reqId: req.reqId, error: err.message });
-    res.status(500).json({ error: safeError(err) });
+    handleRouteError(err, req, res);
   }
 });
 
@@ -1335,7 +1856,7 @@ app.get('/tabs/:tabId/links', async (req, res) => {
     }
     
     const { tabState } = found;
-    tabState.toolCalls++;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
     
     const allLinks = await tabState.page.evaluate(() => {
       const links = [];
@@ -1358,6 +1879,59 @@ app.get('/tabs/:tabId/links', async (req, res) => {
     });
   } catch (err) {
     log('error', 'links failed', { reqId: req.reqId, error: err.message });
+    handleRouteError(err, req, res);
+  }
+});
+
+// Get captured downloads
+app.get('/tabs/:tabId/downloads', async (req, res) => {
+  try {
+    const userId = req.query.userId;
+    const includeData = req.query.includeData === 'true';
+    const consume = req.query.consume === 'true';
+    const maxBytesRaw = Number(req.query.maxBytes);
+    const maxBytes = Number.isFinite(maxBytesRaw) && maxBytesRaw > 0 ? maxBytesRaw : MAX_DOWNLOAD_INLINE_BYTES;
+    const session = sessions.get(normalizeUserId(userId));
+    const found = session && findTab(session, req.params.tabId);
+    if (!found) return res.status(404).json({ error: 'Tab not found' });
+
+    const { tabState } = found;
+    tabState.toolCalls++;
+
+    const downloads = await getDownloadsList(tabState, { includeData, maxBytes });
+
+    if (consume) {
+      await clearTabDownloads(tabState);
+    }
+
+    res.json({ tabId: req.params.tabId, downloads });
+  } catch (err) {
+    log('error', 'downloads failed', { reqId: req.reqId, error: err.message });
+    res.status(500).json({ error: safeError(err) });
+  }
+});
+
+// Get image elements from current page
+app.get('/tabs/:tabId/images', async (req, res) => {
+  try {
+    const userId = req.query.userId;
+    const includeData = req.query.includeData === 'true';
+    const maxBytesRaw = Number(req.query.maxBytes);
+    const limitRaw = Number(req.query.limit);
+    const maxBytes = Number.isFinite(maxBytesRaw) && maxBytesRaw > 0 ? maxBytesRaw : MAX_DOWNLOAD_INLINE_BYTES;
+    const limit = Number.isFinite(limitRaw) && limitRaw > 0 ? Math.min(Math.floor(limitRaw), 20) : 8;
+    const session = sessions.get(normalizeUserId(userId));
+    const found = session && findTab(session, req.params.tabId);
+    if (!found) return res.status(404).json({ error: 'Tab not found' });
+
+    const { tabState } = found;
+    tabState.toolCalls++;
+
+    const images = await extractPageImages(tabState.page, { includeData, maxBytes, limit });
+
+    res.json({ tabId: req.params.tabId, images });
+  } catch (err) {
+    log('error', 'images failed', { reqId: req.reqId, error: err.message });
     res.status(500).json({ error: safeError(err) });
   }
 });
@@ -1377,7 +1951,7 @@ app.get('/tabs/:tabId/screenshot', async (req, res) => {
     res.send(buffer);
   } catch (err) {
     log('error', 'screenshot failed', { reqId: req.reqId, error: err.message });
-    res.status(500).json({ error: safeError(err) });
+    handleRouteError(err, req, res);
   }
 });
 
@@ -1396,11 +1970,36 @@ app.get('/tabs/:tabId/stats', async (req, res) => {
       listItemId, // Legacy compatibility
       url: tabState.page.url(),
       visitedUrls: Array.from(tabState.visitedUrls),
+      downloadsCount: Array.isArray(tabState.downloads) ? tabState.downloads.length : 0,
       toolCalls: tabState.toolCalls,
       refsCount: tabState.refs.size
     });
   } catch (err) {
     log('error', 'stats failed', { reqId: req.reqId, error: err.message });
+    handleRouteError(err, req, res);
+  }
+});
+
+// Evaluate JavaScript in page context
+app.post('/tabs/:tabId/evaluate', express.json({ limit: '1mb' }), async (req, res) => {
+  try {
+    const { userId, expression } = req.body;
+    if (!userId) return res.status(400).json({ error: 'userId is required' });
+    if (!expression) return res.status(400).json({ error: 'expression is required' });
+
+    const session = sessions.get(normalizeUserId(userId));
+    const found = session && findTab(session, req.params.tabId);
+    if (!found) return res.status(404).json({ error: 'Tab not found' });
+
+    session.lastAccess = Date.now();
+    const { tabState } = found;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
+
+    const result = await tabState.page.evaluate(expression);
+    log('info', 'evaluate', { reqId: req.reqId, tabId: req.params.tabId, userId, resultType: typeof result });
+    res.json({ ok: true, result });
+  } catch (err) {
+    log('error', 'evaluate failed', { reqId: req.reqId, error: err.message });
     res.status(500).json({ error: safeError(err) });
   }
 });
@@ -1412,9 +2011,10 @@ app.delete('/tabs/:tabId', async (req, res) => {
     const session = sessions.get(normalizeUserId(userId));
     const found = session && findTab(session, req.params.tabId);
     if (found) {
+      await clearTabDownloads(found.tabState);
       await safePageClose(found.tabState.page);
       found.group.delete(req.params.tabId);
-      tabLocks.delete(req.params.tabId);
+      { const _l = tabLocks.get(req.params.tabId); if (_l) _l.drain(); tabLocks.delete(req.params.tabId); }
       if (found.group.size === 0) {
         session.tabGroups.delete(found.listItemId);
       }
@@ -1423,7 +2023,7 @@ app.delete('/tabs/:tabId', async (req, res) => {
     res.json({ ok: true });
   } catch (err) {
     log('error', 'tab close failed', { reqId: req.reqId, error: err.message });
-    res.status(500).json({ error: safeError(err) });
+    handleRouteError(err, req, res);
   }
 });
 
@@ -1435,6 +2035,7 @@ app.delete('/tabs/group/:listItemId', async (req, res) => {
     const group = session?.tabGroups.get(req.params.listItemId);
     if (group) {
       for (const [tabId, tabState] of group) {
+        await clearTabDownloads(tabState);
         await safePageClose(tabState.page);
         tabLocks.delete(tabId);
       }
@@ -1444,7 +2045,7 @@ app.delete('/tabs/group/:listItemId', async (req, res) => {
     res.json({ ok: true });
   } catch (err) {
     log('error', 'tab group close failed', { reqId: req.reqId, error: err.message });
-    res.status(500).json({ error: safeError(err) });
+    handleRouteError(err, req, res);
   }
 });
 
@@ -1454,6 +2055,7 @@ app.delete('/sessions/:userId', async (req, res) => {
     const userId = normalizeUserId(req.params.userId);
     const session = sessions.get(userId);
     if (session) {
+      await clearSessionDownloads(session);
       await session.context.close();
       sessions.delete(userId);
       log('info', 'session closed', { userId });
@@ -1462,7 +2064,7 @@ app.delete('/sessions/:userId', async (req, res) => {
     res.json({ ok: true });
   } catch (err) {
     log('error', 'session close failed', { error: err.message });
-    res.status(500).json({ error: safeError(err) });
+    handleRouteError(err, req, res);
   }
 });
 
@@ -1471,6 +2073,7 @@ setInterval(() => {
   const now = Date.now();
   for (const [userId, session] of sessions) {
     if (now - session.lastAccess > SESSION_TIMEOUT_MS) {
+      clearSessionDownloads(session).catch(() => {});
       session.context.close().catch(() => {});
       sessions.delete(userId);
       log('info', 'session expired', { userId });
@@ -1482,6 +2085,37 @@ setInterval(() => {
   }
 }, 60_000);
 
+// Per-tab inactivity reaper — close tabs idle for TAB_INACTIVITY_MS
+setInterval(() => {
+  const now = Date.now();
+  for (const [userId, session] of sessions) {
+    for (const [listItemId, group] of session.tabGroups) {
+      for (const [tabId, tabState] of group) {
+        if (!tabState._lastReaperCheck) {
+          tabState._lastReaperCheck = now;
+          tabState._lastReaperToolCalls = tabState.toolCalls;
+          continue;
+        }
+        if (tabState.toolCalls === tabState._lastReaperToolCalls) {
+          const idleMs = now - tabState._lastReaperCheck;
+          if (idleMs >= TAB_INACTIVITY_MS) {
+            log('info', 'tab reaped (inactive)', { userId, tabId, listItemId, idleMs, toolCalls: tabState.toolCalls });
+            safePageClose(tabState.page);
+            group.delete(tabId);
+            { const _l = tabLocks.get(tabId); if (_l) _l.drain(); tabLocks.delete(tabId); }
+          }
+        } else {
+          tabState._lastReaperCheck = now;
+          tabState._lastReaperToolCalls = tabState.toolCalls;
+        }
+      }
+      if (group.size === 0) {
+        session.tabGroups.delete(listItemId);
+      }
+    }
+  }
+}, 60_000);
+
 // =============================================================================
 // OpenClaw-compatible endpoint aliases
 // These allow camoufox to be used as a profile backend for OpenClaw's browser tool
@@ -1526,7 +2160,7 @@ app.get('/tabs', async (req, res) => {
     res.json({ running: true, tabs });
   } catch (err) {
     log('error', 'list tabs failed', { reqId: req.reqId, error: err.message });
-    res.status(500).json({ error: safeError(err) });
+    handleRouteError(err, req, res);
   }
 });
 
@@ -1546,6 +2180,11 @@ app.post('/tabs/open', async (req, res) => {
     
     const session = await getSession(userId);
     
+    // Check global tab limit first
+    if (getTotalTabCount() >= MAX_TABS_GLOBAL) {
+      return res.status(429).json({ error: 'Maximum global tabs reached' });
+    }
+    
     let totalTabs = 0;
     for (const g of session.tabGroups.values()) totalTabs += g.size;
     if (totalTabs >= MAX_TABS_PER_SESSION) {
@@ -1557,6 +2196,7 @@ app.post('/tabs/open', async (req, res) => {
     const page = await session.context.newPage();
     const tabId = crypto.randomUUID();
     const tabState = createTabState(page);
+    attachDownloadListener(tabState, tabId, log);
     group.set(tabId, tabState);
     
     await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
@@ -1572,7 +2212,7 @@ app.post('/tabs/open', async (req, res) => {
     });
   } catch (err) {
     log('error', 'openclaw tab open failed', { reqId: req.reqId, error: err.message });
-    res.status(500).json({ error: safeError(err) });
+    handleRouteError(err, req, res);
   }
 });
 
@@ -1597,6 +2237,11 @@ app.post('/stop', async (req, res) => {
       await browser.close().catch(() => {});
       browser = null;
     }
+    const cleanupTasks = [];
+    for (const session of sessions.values()) {
+      cleanupTasks.push(clearSessionDownloads(session));
+    }
+    await Promise.all(cleanupTasks);
     sessions.clear();
     res.json({ ok: true, stopped: true, profile: 'camoufox' });
   } catch (err) {
@@ -1625,19 +2270,27 @@ app.post('/navigate', async (req, res) => {
     }
     
     const { tabState } = found;
-    tabState.toolCalls++;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
     
-    const result = await withTimeout(withTabLock(targetId, async () => {
+    const result = await withTabLock(targetId, async () => {
       await tabState.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
       tabState.visitedUrls.add(url);
+      tabState.lastSnapshot = null;
+      
+      // Google SERP: defer extraction to snapshot call
+      if (isGoogleSerp(tabState.page.url())) {
+        tabState.refs = new Map();
+        return { ok: true, targetId, url: tabState.page.url(), googleSerp: true };
+      }
+      
       tabState.refs = await buildRefs(tabState.page);
       return { ok: true, targetId, url: tabState.page.url() };
-    }), HANDLER_TIMEOUT_MS, 'openclaw-navigate');
+    });
     
     res.json(result);
   } catch (err) {
     log('error', 'openclaw navigate failed', { reqId: req.reqId, error: err.message });
-    res.status(500).json({ error: safeError(err) });
+    handleRouteError(err, req, res);
   }
 });
 
@@ -1657,7 +2310,7 @@ app.get('/snapshot', async (req, res) => {
     }
     
     const { tabState } = found;
-    tabState.toolCalls++;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
 
     // Cached chunk retrieval
     if (offset > 0 && tabState.lastSnapshot) {
@@ -1670,6 +2323,28 @@ app.get('/snapshot', async (req, res) => {
       return res.json(response);
     }
 
+    const pageUrl = tabState.page.url();
+    
+    // Google SERP fast path
+    if (isGoogleSerp(pageUrl)) {
+      const { refs: googleRefs, snapshot: googleSnapshot } = await extractGoogleSerp(tabState.page);
+      tabState.refs = googleRefs;
+      tabState.lastSnapshot = googleSnapshot;
+      const annotatedYaml = googleSnapshot;
+      const win = windowSnapshot(annotatedYaml, 0);
+      const response = {
+        ok: true, format: 'aria', targetId, url: pageUrl,
+        snapshot: win.text, refsCount: tabState.refs.size,
+        truncated: win.truncated, totalChars: win.totalChars,
+        hasMore: win.hasMore, nextOffset: win.nextOffset,
+      };
+      if (req.query.includeScreenshot === 'true') {
+        const pngBuffer = await tabState.page.screenshot({ type: 'png' });
+        response.screenshot = { data: pngBuffer.toString('base64'), mimeType: 'image/png' };
+      }
+      return res.json(response);
+    }
+    
     tabState.refs = await buildRefs(tabState.page);
     
     const ariaYaml = await getAriaSnapshot(tabState.page);
@@ -1722,7 +2397,7 @@ app.get('/snapshot', async (req, res) => {
     res.json(response);
   } catch (err) {
     log('error', 'openclaw snapshot failed', { reqId: req.reqId, error: err.message });
-    res.status(500).json({ error: safeError(err) });
+    handleRouteError(err, req, res);
   }
 });
 
@@ -1746,9 +2421,9 @@ app.post('/act', async (req, res) => {
     }
     
     const { tabState } = found;
-    tabState.toolCalls++;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
     
-    const result = await withTimeout(withTabLock(targetId, async () => {
+    const result = await withTabLock(targetId, async () => {
       switch (kind) {
         case 'click': {
           const { ref, selector, doubleClick } = params;
@@ -1758,7 +2433,7 @@ app.post('/act', async (req, res) => {
           
           const doClick = async (locatorOrSelector, isLocator) => {
             const locator = isLocator ? locatorOrSelector : tabState.page.locator(locatorOrSelector);
-            const clickOpts = { timeout: 5000 };
+            const clickOpts = { timeout: 3000 };
             if (doubleClick) clickOpts.clickCount = 2;
             
             try {
@@ -1773,8 +2448,13 @@ app.post('/act', async (req, res) => {
           };
           
           if (ref) {
-            const locator = refToLocator(tabState.page, ref, tabState.refs);
-            if (!locator) throw new Error(`Unknown ref: ${ref}`);
+            let locator = refToLocator(tabState.page, ref, tabState.refs);
+            if (!locator) {
+              log('info', 'auto-refreshing refs before click (openclaw)', { ref, hadRefs: tabState.refs.size });
+              tabState.refs = await buildRefs(tabState.page);
+              locator = refToLocator(tabState.page, ref, tabState.refs);
+            }
+            if (!locator) { const maxRef = tabState.refs.size > 0 ? `e${tabState.refs.size}` : 'none'; throw new StaleRefsError(ref, maxRef, tabState.refs.size); }
             await doClick(locator, true);
           } else {
             await doClick(selector, false);
@@ -1795,8 +2475,13 @@ app.post('/act', async (req, res) => {
           }
           
           if (ref) {
-            const locator = refToLocator(tabState.page, ref, tabState.refs);
-            if (!locator) throw new Error(`Unknown ref: ${ref}`);
+            let locator = refToLocator(tabState.page, ref, tabState.refs);
+            if (!locator) {
+              log('info', 'auto-refreshing refs before type (openclaw)', { ref, hadRefs: tabState.refs.size });
+              tabState.refs = await buildRefs(tabState.page);
+              locator = refToLocator(tabState.page, ref, tabState.refs);
+            }
+            if (!locator) { const maxRef = tabState.refs.size > 0 ? `e${tabState.refs.size}` : 'none'; throw new StaleRefsError(ref, maxRef, tabState.refs.size); }
             await locator.fill(text, { timeout: 10000 });
             if (submit) await tabState.page.keyboard.press('Enter');
           } else {
@@ -1817,8 +2502,12 @@ app.post('/act', async (req, res) => {
         case 'scrollIntoView': {
           const { ref, direction = 'down', amount = 500 } = params;
           if (ref) {
-            const locator = refToLocator(tabState.page, ref, tabState.refs);
-            if (!locator) throw new Error(`Unknown ref: ${ref}`);
+            let locator = refToLocator(tabState.page, ref, tabState.refs);
+            if (!locator) {
+              tabState.refs = await buildRefs(tabState.page);
+              locator = refToLocator(tabState.page, ref, tabState.refs);
+            }
+            if (!locator) { const maxRef = tabState.refs.size > 0 ? `e${tabState.refs.size}` : 'none'; throw new StaleRefsError(ref, maxRef, tabState.refs.size); }
             await locator.scrollIntoViewIfNeeded({ timeout: 5000 });
           } else {
             const delta = direction === 'up' ? -amount : amount;
@@ -1833,8 +2522,12 @@ app.post('/act', async (req, res) => {
           if (!ref && !selector) throw new Error('ref or selector required');
           
           if (ref) {
-            const locator = refToLocator(tabState.page, ref, tabState.refs);
-            if (!locator) throw new Error(`Unknown ref: ${ref}`);
+            let locator = refToLocator(tabState.page, ref, tabState.refs);
+            if (!locator) {
+              tabState.refs = await buildRefs(tabState.page);
+              locator = refToLocator(tabState.page, ref, tabState.refs);
+            }
+            if (!locator) { const maxRef = tabState.refs.size > 0 ? `e${tabState.refs.size}` : 'none'; throw new StaleRefsError(ref, maxRef, tabState.refs.size); }
             await locator.hover({ timeout: 5000 });
           } else {
             await tabState.page.locator(selector).hover({ timeout: 5000 });
@@ -1857,19 +2550,19 @@ app.post('/act', async (req, res) => {
         case 'close': {
           await safePageClose(tabState.page);
           found.group.delete(targetId);
-          tabLocks.delete(targetId);
+          { const _l = tabLocks.get(targetId); if (_l) _l.drain(); tabLocks.delete(targetId); }
           return { ok: true, targetId };
         }
         
         default:
           throw new Error(`Unsupported action kind: ${kind}`);
       }
-    }), HANDLER_TIMEOUT_MS, 'act');
+    });
     
     res.json(result);
   } catch (err) {
     log('error', 'act failed', { reqId: req.reqId, kind: req.body?.kind, error: err.message });
-    res.status(500).json({ error: safeError(err) });
+    handleRouteError(err, req, res);
   }
 });
 
@@ -1895,14 +2588,20 @@ setInterval(() => {
 // Active health probe — detect hung browser even when isConnected() lies
 setInterval(async () => {
   if (!browser || healthState.isRecovering) return;
-  // Skip probe if operations are in flight
-  if (healthState.activeOps > 0) {
+  const timeSinceSuccess = Date.now() - healthState.lastSuccessfulNav;
+  // Skip probe if operations are in flight AND last success was recent.
+  // If it's been >120s since any successful operation, probe anyway —
+  // active ops are likely stuck on a frozen browser and will time out eventually.
+  if (healthState.activeOps > 0 && timeSinceSuccess < 120000) {
     log('info', 'health probe skipped, operations active', { activeOps: healthState.activeOps });
     return;
   }
-  const timeSinceSuccess = Date.now() - healthState.lastSuccessfulNav;
   if (timeSinceSuccess < 120000) return;
   
+  if (healthState.activeOps > 0) {
+    log('warn', 'health probe forced despite active ops', { activeOps: healthState.activeOps, timeSinceSuccessMs: timeSinceSuccess });
+  }
+  
   let testContext;
   try {
     testContext = await browser.newContext();
@@ -1954,9 +2653,16 @@ process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
 process.on('SIGINT', () => gracefulShutdown('SIGINT'));
 
 const PORT = CONFIG.port;
-const server = app.listen(PORT, () => {
+const server = app.listen(PORT, async () => {
   log('info', 'server started', { port: PORT, pid: process.pid, nodeVersion: process.version });
-  // Browser launches lazily on first request (saves ~550MB when idle)
+  // Pre-warm browser so first request doesn't eat a 6-7s cold start
+  try {
+    const start = Date.now();
+    await ensureBrowser();
+    log('info', 'browser pre-warmed', { ms: Date.now() - start });
+  } catch (err) {
+    log('error', 'browser pre-warm failed (will retry on first request)', { error: err.message });
+  }
 });
 
 server.on('error', (err) => {