@askjo/camofox-browser 1.1.2 → 1.3.0

package/server.js

@@ -5,6 +5,7 @@ const crypto = require('crypto');
 const os = require('os');
 const { expandMacro } = require('./lib/macros');
 const { loadConfig } = require('./lib/config');
+const { windowSnapshot } = require('./lib/snapshot');
 
 const CONFIG = loadConfig();
 
@@ -46,6 +47,19 @@ app.use((req, res, next) => {
 
 const ALLOWED_URL_SCHEMES = ['http:', 'https:'];
 
+// Interactive roles to include - exclude combobox to avoid opening complex widgets
+// (date pickers, dropdowns) that can interfere with navigation
+const INTERACTIVE_ROLES = [
+  'button', 'link', 'textbox', 'checkbox', 'radio',
+  'menuitem', 'tab', 'searchbox', 'slider', 'spinbutton', 'switch'
+  // 'combobox' excluded - can trigger date pickers and complex dropdowns
+];
+
+// Patterns to skip (date pickers, calendar widgets)
+const SKIP_PATTERNS = [
+  /date/i, /calendar/i, /picker/i, /datepicker/i
+];
+
 function timingSafeCompare(a, b) {
   if (typeof a !== 'string' || typeof b !== 'string') return false;
   const bufA = Buffer.from(a);
@@ -158,10 +172,18 @@ let browser = null;
 // Note: sessionKey was previously called listItemId - both are accepted for backward compatibility
 const sessions = new Map();
 
-const SESSION_TIMEOUT_MS = 30 * 60 * 1000; // 30 min
+const SESSION_TIMEOUT_MS = parseInt(process.env.SESSION_TIMEOUT_MS) || 1800000; // 30 min
 const MAX_SNAPSHOT_NODES = 500;
-const MAX_SESSIONS = 50;
-const MAX_TABS_PER_SESSION = 10;
+const MAX_SESSIONS = parseInt(process.env.MAX_SESSIONS) || 50;
+const MAX_TABS_PER_SESSION = parseInt(process.env.MAX_TABS_PER_SESSION) || 10;
+const MAX_TABS_GLOBAL = parseInt(process.env.MAX_TABS_GLOBAL) || 10;
+const HANDLER_TIMEOUT_MS = parseInt(process.env.HANDLER_TIMEOUT_MS) || 30000;
+const MAX_CONCURRENT_PER_USER = parseInt(process.env.MAX_CONCURRENT_PER_USER) || 3;
+const PAGE_CLOSE_TIMEOUT_MS = 5000;
+const NAVIGATE_TIMEOUT_MS = parseInt(process.env.NAVIGATE_TIMEOUT_MS) || 25000;
+const BUILDREFS_TIMEOUT_MS = parseInt(process.env.BUILDREFS_TIMEOUT_MS) || 12000;
+const FAILURE_THRESHOLD = 3;
+const TAB_LOCK_TIMEOUT_MS = 30000;
 
 // Per-tab locks to serialize operations on the same tab
 // tabId -> Promise (the currently executing operation)
@@ -172,9 +194,14 @@ async function withTabLock(tabId, operation) {
   const pending = tabLocks.get(tabId);
   if (pending) {
     try {
-      await pending;
+      await Promise.race([
+        pending,
+        new Promise((_, reject) => setTimeout(() => reject(new Error('Tab lock timeout')), TAB_LOCK_TIMEOUT_MS))
+      ]);
     } catch (e) {
-      // Previous operation failed, continue anyway
+      if (e.message === 'Tab lock timeout') {
+        log('warn', 'tab lock timeout, proceeding', { tabId });
+      }
     }
   }
   
@@ -192,6 +219,60 @@ async function withTabLock(tabId, operation) {
   }
 }
 
+function withTimeout(promise, ms, label) {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) =>
+      setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms)
+    )
+  ]);
+}
+
+const userConcurrency = new Map();
+
+async function withUserLimit(userId, operation) {
+  const key = normalizeUserId(userId);
+  let state = userConcurrency.get(key);
+  if (!state) {
+    state = { active: 0, queue: [] };
+    userConcurrency.set(key, state);
+  }
+  if (state.active >= MAX_CONCURRENT_PER_USER) {
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error('User concurrency limit reached, try again')), 30000);
+      state.queue.push(() => { clearTimeout(timer); resolve(); });
+    });
+  }
+  state.active++;
+  healthState.activeOps++;
+  try {
+    const result = await operation();
+    healthState.lastSuccessfulNav = Date.now();
+    return result;
+  } finally {
+    healthState.activeOps--;
+    state.active--;
+    if (state.queue.length > 0) {
+      const next = state.queue.shift();
+      next();
+    }
+    if (state.active === 0 && state.queue.length === 0) {
+      userConcurrency.delete(key);
+    }
+  }
+}
+
+async function safePageClose(page) {
+  try {
+    await Promise.race([
+      page.close(),
+      new Promise(resolve => setTimeout(resolve, PAGE_CLOSE_TIMEOUT_MS))
+    ]);
+  } catch (e) {
+    log('warn', 'page close failed', { error: e.message });
+  }
+}
+
 // Detect host OS for fingerprint generation
 function getHostOS() {
   const platform = os.platform();
@@ -216,26 +297,123 @@ function buildProxyConfig() {
   };
 }
 
+const BROWSER_IDLE_TIMEOUT_MS = parseInt(process.env.BROWSER_IDLE_TIMEOUT_MS) || 300000; // 5 min
+let browserIdleTimer = null;
+let browserLaunchPromise = null;
+
+function scheduleBrowserIdleShutdown() {
+  clearBrowserIdleTimer();
+  if (sessions.size === 0 && browser) {
+    browserIdleTimer = setTimeout(async () => {
+      if (sessions.size === 0 && browser) {
+        log('info', 'browser idle shutdown (no sessions)');
+        const b = browser;
+        browser = null;
+        await b.close().catch(() => {});
+      }
+    }, BROWSER_IDLE_TIMEOUT_MS);
+  }
+}
+
+function clearBrowserIdleTimer() {
+  if (browserIdleTimer) {
+    clearTimeout(browserIdleTimer);
+    browserIdleTimer = null;
+  }
+}
+
+// --- Browser health tracking ---
+const healthState = {
+  consecutiveNavFailures: 0,
+  lastSuccessfulNav: Date.now(),
+  isRecovering: false,
+  activeOps: 0,
+};
+
+function recordNavSuccess() {
+  healthState.consecutiveNavFailures = 0;
+  healthState.lastSuccessfulNav = Date.now();
+}
+
+function recordNavFailure() {
+  healthState.consecutiveNavFailures++;
+  return healthState.consecutiveNavFailures >= FAILURE_THRESHOLD;
+}
+
+async function restartBrowser(reason) {
+  if (healthState.isRecovering) return;
+  healthState.isRecovering = true;
+  log('error', 'restarting browser', { reason, failures: healthState.consecutiveNavFailures });
+  try {
+    for (const [, session] of sessions) {
+      await session.context.close().catch(() => {});
+    }
+    sessions.clear();
+    if (browser) {
+      await browser.close().catch(() => {});
+      browser = null;
+    }
+    browserLaunchPromise = null;
+    await ensureBrowser();
+    healthState.consecutiveNavFailures = 0;
+    healthState.lastSuccessfulNav = Date.now();
+    log('info', 'browser restarted successfully');
+  } catch (err) {
+    log('error', 'browser restart failed', { error: err.message });
+  } finally {
+    healthState.isRecovering = false;
+  }
+}
+
+function getTotalTabCount() {
+  let total = 0;
+  for (const session of sessions.values()) {
+    for (const group of session.tabGroups.values()) {
+      total += group.size;
+    }
+  }
+  return total;
+}
+
+async function launchBrowserInstance() {
+  const hostOS = getHostOS();
+  const proxy = buildProxyConfig();
+  
+  log('info', 'launching camoufox', { hostOS, geoip: !!proxy });
+  
+  const options = await launchOptions({
+    headless: true,
+    os: hostOS,
+    humanize: true,
+    enable_cache: true,
+    proxy: proxy,
+    geoip: !!proxy,
+  });
+  
+  browser = await firefox.launch(options);
+  log('info', 'camoufox launched');
+  return browser;
+}
+
 async function ensureBrowser() {
-  if (!browser) {
-    const hostOS = getHostOS();
-    const proxy = buildProxyConfig();
-    
-    log('info', 'launching camoufox', { hostOS, geoip: !!proxy });
-    
-    const options = await launchOptions({
-      headless: true,
-      os: hostOS,
-      humanize: true,
-      enable_cache: true,
-      proxy: proxy,
-      geoip: !!proxy,
+  clearBrowserIdleTimer();
+  if (browser && !browser.isConnected()) {
+    log('warn', 'browser disconnected, clearing dead sessions and relaunching', {
+      deadSessions: sessions.size,
     });
-    
-    browser = await firefox.launch(options);
-    log('info', 'camoufox launched');
+    for (const [userId, session] of sessions) {
+      await session.context.close().catch(() => {});
+    }
+    sessions.clear();
+    browser = null;
   }
-  return browser;
+  if (browser) return browser;
+  if (browserLaunchPromise) return browserLaunchPromise;
+  browserLaunchPromise = Promise.race([
+    launchBrowserInstance(),
+    new Promise((_, reject) => setTimeout(() => reject(new Error('Browser launch timeout (30s)')), 30000)),
+  ]).finally(() => { browserLaunchPromise = null; });
+  return browserLaunchPromise;
 }
 
 // Helper to normalize userId to string (JSON body may parse as number)
@@ -296,7 +474,8 @@ function createTabState(page) {
     page,
     refs: new Map(),
     visitedUrls: new Set(),
-    toolCalls: 0
+    toolCalls: 0,
+    lastSnapshot: null,
   };
 }
 
@@ -397,40 +576,53 @@ async function buildRefs(page) {
     return refs;
   }
   
+  const start = Date.now();
+  
+  // Hard total timeout on the entire buildRefs operation
+  const timeoutPromise = new Promise((_, reject) => 
+    setTimeout(() => reject(new Error('buildRefs_timeout')), BUILDREFS_TIMEOUT_MS)
+  );
+  
+  try {
+    return await Promise.race([
+      _buildRefsInner(page, refs, start),
+      timeoutPromise
+    ]);
+  } catch (err) {
+    if (err.message === 'buildRefs_timeout') {
+      log('warn', 'buildRefs: total timeout exceeded', { elapsed: Date.now() - start });
+      return refs;
+    }
+    throw err;
+  }
+}
+
+async function _buildRefsInner(page, refs, start) {
   await waitForPageReady(page, { waitForNetwork: false });
   
-  // Get ARIA snapshot including shadow DOM content
-  // Playwright's ariaSnapshot already traverses shadow roots, but we also
-  // inject a script to collect shadow DOM elements for additional coverage
+  // Budget remaining time for ariaSnapshot
+  const elapsed = Date.now() - start;
+  const remaining = BUILDREFS_TIMEOUT_MS - elapsed;
+  if (remaining < 2000) {
+    log('warn', 'buildRefs: insufficient time for ariaSnapshot', { elapsed });
+    return refs;
+  }
+  
   let ariaYaml;
   try {
-    ariaYaml = await page.locator('body').ariaSnapshot({ timeout: 10000 });
+    ariaYaml = await page.locator('body').ariaSnapshot({ timeout: Math.min(remaining - 1000, 5000) });
   } catch (err) {
     log('warn', 'ariaSnapshot failed, retrying');
-    await page.waitForLoadState('load', { timeout: 5000 }).catch(() => {});
-    ariaYaml = await page.locator('body').ariaSnapshot({ timeout: 10000 });
+    const retryBudget = BUILDREFS_TIMEOUT_MS - (Date.now() - start);
+    if (retryBudget < 2000) return refs;
+    try {
+      ariaYaml = await page.locator('body').ariaSnapshot({ timeout: Math.min(retryBudget - 500, 5000) });
+    } catch (retryErr) {
+      log('warn', 'ariaSnapshot retry failed, returning empty refs', { error: retryErr.message });
+      return refs;
+    }
   }
   
-  // Collect additional interactive elements from shadow DOM
-  const shadowElements = await page.evaluate(() => {
-    const elements = [];
-    const collectFromShadow = (root, depth = 0) => {
-      if (depth > 5) return; // Limit recursion
-      const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
-      while (walker.nextNode()) {
-        const el = walker.currentNode;
-        if (el.shadowRoot) {
-          collectFromShadow(el.shadowRoot, depth + 1);
-        }
-      }
-    };
-    // Start collection from all shadow roots
-    document.querySelectorAll('*').forEach(el => {
-      if (el.shadowRoot) collectFromShadow(el.shadowRoot);
-    });
-    return elements;
-  }).catch(() => []);
-  
   if (!ariaYaml) {
     log('warn', 'buildRefs: no aria snapshot');
     return refs;
@@ -439,19 +631,6 @@ async function buildRefs(page) {
   const lines = ariaYaml.split('\n');
   let refCounter = 1;
   
-  // Interactive roles to include - exclude combobox to avoid opening complex widgets
-  // (date pickers, dropdowns) that can interfere with navigation
-  const interactiveRoles = [
-    'button', 'link', 'textbox', 'checkbox', 'radio',
-    'menuitem', 'tab', 'searchbox', 'slider', 'spinbutton', 'switch'
-    // 'combobox' excluded - can trigger date pickers and complex dropdowns
-  ];
-  
-  // Patterns to skip (date pickers, calendar widgets)
-  const skipPatterns = [
-    /date/i, /calendar/i, /picker/i, /datepicker/i
-  ];
-  
   // Track occurrences of each role+name combo for nth disambiguation
   const seenCounts = new Map(); // "role:name" -> count
   
@@ -463,13 +642,11 @@ async function buildRefs(page) {
       const [, role, name] = match;
       const normalizedRole = role.toLowerCase();
       
-      // Skip combobox role entirely (date pickers, complex dropdowns)
       if (normalizedRole === 'combobox') continue;
       
-      // Skip elements with date/calendar-related names
-      if (name && skipPatterns.some(p => p.test(name))) continue;
+      if (name && SKIP_PATTERNS.some(p => p.test(name))) continue;
       
-      if (interactiveRoles.includes(normalizedRole)) {
+      if (INTERACTIVE_ROLES.includes(normalizedRole)) {
         const normalizedName = name || '';
         const key = `${normalizedRole}:${normalizedName}`;
         
@@ -491,7 +668,12 @@ async function getAriaSnapshot(page) {
     return null;
   }
   await waitForPageReady(page, { waitForNetwork: false });
-  return await page.locator('body').ariaSnapshot({ timeout: 10000 });
+  try {
+    return await page.locator('body').ariaSnapshot({ timeout: 5000 });
+  } catch (err) {
+    log('warn', 'getAriaSnapshot failed', { error: err.message });
+    return null;
+  }
 }
 
 function refToLocator(page, ref, refs) {
@@ -508,18 +690,315 @@ function refToLocator(page, ref, refs) {
   return locator;
 }
 
-// Health check
-app.get('/health', async (req, res) => {
+// --- YouTube transcript extraction via yt-dlp ---
+// POST /youtube/transcript { url, languages? }
+// Uses yt-dlp to extract subtitles — no browser needed, no ads, no playback.
+// yt-dlp handles YouTube's signed caption URLs correctly.
+// Falls back to Camoufox page intercept if yt-dlp is not installed.
+
+const { execFile } = require('child_process');
+const { mkdtemp, readFile, readdir, rm } = require('fs/promises');
+const { tmpdir } = require('os');
+const { join } = require('path');
+
+// Detect yt-dlp binary at startup
+let ytDlpPath = null;
+(async () => {
+  for (const candidate of ['yt-dlp', '/usr/local/bin/yt-dlp', '/usr/bin/yt-dlp']) {
+    try {
+      await new Promise((resolve, reject) => {
+        execFile(candidate, ['--version'], { timeout: 5000 }, (err, stdout) => {
+          if (err) return reject(err);
+          resolve(stdout.trim());
+        });
+      });
+      ytDlpPath = candidate;
+      log('info', 'yt-dlp found', { path: candidate });
+      break;
+    } catch {}
+  }
+  if (!ytDlpPath) log('warn', 'yt-dlp not found — YouTube transcript endpoint will use browser fallback');
+})();
+
+app.post('/youtube/transcript', async (req, res) => {
+  const reqId = req.reqId;
   try {
-    const b = await ensureBrowser();
-    res.json({ 
-      ok: true, 
-      engine: 'camoufox',
-      browserConnected: b.isConnected()
-    });
+    const { url, languages = ['en'] } = req.body;
+    if (!url) return res.status(400).json({ error: 'url is required' });
+
+    const urlErr = validateUrl(url);
+    if (urlErr) return res.status(400).json({ error: urlErr });
+
+    const videoIdMatch = url.match(
+      /(?:youtube\.com\/watch\?v=|youtu\.be\/|youtube\.com\/embed\/|youtube\.com\/shorts\/)([a-zA-Z0-9_-]{11})/
+    );
+    if (!videoIdMatch) {
+      return res.status(400).json({ error: 'Could not extract YouTube video ID from URL' });
+    }
+    const videoId = videoIdMatch[1];
+    const lang = languages[0] || 'en';
+
+    log('info', 'youtube transcript: starting', { reqId, videoId, lang, method: ytDlpPath ? 'yt-dlp' : 'browser' });
+
+    let result;
+    if (ytDlpPath) {
+      result = await ytDlpTranscript(reqId, url, videoId, lang);
+    } else {
+      result = await browserTranscript(reqId, url, videoId, lang);
+    }
+
+    log('info', 'youtube transcript: done', { reqId, videoId, status: result.status, words: result.total_words });
+    res.json(result);
   } catch (err) {
-    res.status(500).json({ ok: false, error: safeError(err) });
+    log('error', 'youtube transcript failed', { reqId, error: err.message, stack: err.stack });
+    res.status(500).json({ error: safeError(err) });
+  }
+});
+
+// Strategy 1: yt-dlp (preferred — fast, no browser, no ads)
+async function ytDlpTranscript(reqId, url, videoId, lang) {
+  const tmpDir = await mkdtemp(join(tmpdir(), 'yt-'));
+  try {
+    // Step 1: Get title via --print (fast, no download)
+    const title = await new Promise((resolve, reject) => {
+      execFile(ytDlpPath, [
+        '--skip-download', '--no-warnings', '--print', '%(title)s', url,
+      ], { timeout: 15000 }, (err, stdout) => {
+        if (err) return reject(new Error(`yt-dlp metadata failed: ${err.message}`));
+        resolve(stdout.trim().split('\n')[0] || '');
+      });
+    });
+
+    // Step 2: Download subtitles to temp dir
+    await new Promise((resolve, reject) => {
+      execFile(ytDlpPath, [
+        '--skip-download',
+        '--write-sub', '--write-auto-sub',
+        '--sub-lang', lang,
+        '--sub-format', 'json3',
+        '-o', join(tmpDir, '%(id)s'),
+        url,
+      ], { timeout: 30000 }, (err, stdout, stderr) => {
+        if (err) return reject(new Error(`yt-dlp subtitle download failed: ${err.message}\n${stderr}`));
+        resolve();
+      });
+    });
+
+    // Find the subtitle file
+    const files = await readdir(tmpDir);
+    const subFile = files.find(f => f.endsWith('.json3') || f.endsWith('.vtt') || f.endsWith('.srv3'));
+    if (!subFile) {
+      return {
+        status: 'error', code: 404,
+        message: 'No captions available for this video',
+        video_url: url, video_id: videoId, title,
+      };
+    }
+
+    const content = await readFile(join(tmpDir, subFile), 'utf8');
+    let transcriptText = null;
+
+    if (subFile.endsWith('.json3')) {
+      transcriptText = parseJson3(content);
+    } else if (subFile.endsWith('.vtt')) {
+      transcriptText = parseVtt(content);
+    } else {
+      transcriptText = parseXml(content);
+    }
+
+    if (!transcriptText || !transcriptText.trim()) {
+      return {
+        status: 'error', code: 404,
+        message: 'Subtitle file found but content was empty',
+        video_url: url, video_id: videoId, title,
+      };
+    }
+
+    // Detect language from filename (e.g., dQw4w9WgXcQ.en.json3)
+    const langMatch = subFile.match(/\.([a-z]{2}(?:-[a-zA-Z]+)?)\.(?:json3|vtt|srv3)$/);
+
+    return {
+      status: 'ok', transcript: transcriptText,
+      video_url: url, video_id: videoId, video_title: title,
+      language: langMatch?.[1] || lang,
+      total_words: transcriptText.split(/\s+/).length,
+    };
+  } finally {
+    await rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+// Strategy 2: Browser fallback — play video, intercept timedtext network response
+async function browserTranscript(reqId, url, videoId, lang) {
+  return await withUserLimit('__yt_transcript__', async () => {
+    await ensureBrowser();
+    const session = await getSession('__yt_transcript__');
+    const page = await session.context.newPage();
+
+    try {
+      // Mute audio
+      await page.addInitScript(() => {
+        const origPlay = HTMLMediaElement.prototype.play;
+        HTMLMediaElement.prototype.play = function() { this.volume = 0; this.muted = true; return origPlay.call(this); };
+      });
+
+      // Intercept timedtext responses — filter by video ID to skip ad captions
+      let interceptedCaptions = null;
+      page.on('response', async (response) => {
+        const respUrl = response.url();
+        if (respUrl.includes('/api/timedtext') && respUrl.includes(`v=${videoId}`) && !interceptedCaptions) {
+          try {
+            const body = await response.text();
+            if (body && body.length > 0) interceptedCaptions = body;
+          } catch {}
+        }
+      });
+
+      await page.goto(url, { waitUntil: 'domcontentloaded', timeout: NAVIGATE_TIMEOUT_MS });
+      await page.waitForTimeout(2000);
+
+      // Extract metadata from ytInitialPlayerResponse
+      const meta = await page.evaluate(() => {
+        const r = window.ytInitialPlayerResponse || (typeof ytInitialPlayerResponse !== 'undefined' ? ytInitialPlayerResponse : null);
+        if (!r) return { title: '' };
+        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' })),
+        };
+      });
+
+      // Start playback to trigger caption loading
+      await page.evaluate(() => {
+        const v = document.querySelector('video');
+        if (v) { v.muted = true; v.play().catch(() => {}); }
+      }).catch(() => {});
+
+      // Wait up to 20s for the target video's captions (may need to sit through an ad)
+      for (let i = 0; i < 40 && !interceptedCaptions; i++) {
+        await page.waitForTimeout(500);
+      }
+
+      if (!interceptedCaptions) {
+        return {
+          status: 'error', code: 404,
+          message: 'No captions loaded during playback (video may have no captions, or ad blocked it)',
+          video_url: url, video_id: videoId, title: meta.title,
+        };
+      }
+
+      log('info', 'youtube transcript: intercepted captions', { reqId, len: interceptedCaptions.length });
+
+      let transcriptText = null;
+      if (interceptedCaptions.trimStart().startsWith('{')) transcriptText = parseJson3(interceptedCaptions);
+      else if (interceptedCaptions.includes('WEBVTT')) transcriptText = parseVtt(interceptedCaptions);
+      else if (interceptedCaptions.includes('<text')) transcriptText = parseXml(interceptedCaptions);
+
+      if (!transcriptText || !transcriptText.trim()) {
+        return {
+          status: 'error', code: 404,
+          message: 'Caption data intercepted but could not be parsed',
+          video_url: url, video_id: videoId, title: meta.title,
+        };
+      }
+
+      return {
+        status: 'ok', transcript: transcriptText,
+        video_url: url, video_id: videoId, video_title: meta.title,
+        language: lang, total_words: transcriptText.split(/\s+/).length,
+        available_languages: meta.languages,
+      };
+    } finally {
+      await safePageClose(page);
+    }
+  });
+}
+
+// --- YouTube transcript parsers ---
+
+function parseJson3(content) {
+  try {
+    const data = JSON.parse(content);
+    const events = data.events || [];
+    const lines = [];
+    for (const event of events) {
+      const segs = event.segs || [];
+      if (!segs.length) continue;
+      const text = segs.map(s => s.utf8 || '').join('').trim();
+      if (!text) continue;
+      const tsMs = event.tStartMs || 0;
+      const tsSec = Math.floor(tsMs / 1000);
+      const mm = Math.floor(tsSec / 60);
+      const ss = tsSec % 60;
+      lines.push(`[${String(mm).padStart(2, '0')}:${String(ss).padStart(2, '0')}] ${text}`);
+    }
+    return lines.join('\n');
+  } catch (e) {
+    return null;
+  }
+}
+
+function parseVtt(content) {
+  const lines = content.split('\n');
+  const result = [];
+  let currentTimestamp = '';
+  for (const line of lines) {
+    const stripped = line.trim();
+    if (!stripped || stripped === 'WEBVTT' || stripped.startsWith('Kind:') || stripped.startsWith('Language:') || stripped.startsWith('NOTE')) continue;
+    if (stripped.includes(' --> ')) {
+      const parts = stripped.split(' --> ');
+      if (parts[0]) currentTimestamp = formatVttTs(parts[0].trim());
+      continue;
+    }
+    const text = stripped.replace(/<[^>]+>/g, '').replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'").trim();
+    if (text && currentTimestamp) { result.push(`[${currentTimestamp}] ${text}`); currentTimestamp = ''; }
+    else if (text) result.push(text);
+  }
+  return result.join('\n');
+}
+
+function parseXml(content) {
+  const lines = [];
+  const regex = /<text\s+start="([^"]*)"[^>]*>([\s\S]*?)<\/text>/g;
+  let match;
+  while ((match = regex.exec(content)) !== null) {
+    const startSec = parseFloat(match[1]) || 0;
+    const text = match[2].replace(/<[^>]+>/g, '').replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'").trim();
+    if (!text) continue;
+    const mm = Math.floor(startSec / 60);
+    const ss = Math.floor(startSec % 60);
+    lines.push(`[${String(mm).padStart(2, '0')}:${String(ss).padStart(2, '0')}] ${text}`);
+  }
+  return lines.join('\n');
+}
+
+function formatVttTs(ts) {
+  const parts = ts.split(':');
+  if (parts.length >= 3) {
+    const hours = parseInt(parts[0]) || 0;
+    const minutes = parseInt(parts[1]) || 0;
+    const totalMin = hours * 60 + minutes;
+    const seconds = (parts[2] || '00').split('.')[0];
+    return `${String(totalMin).padStart(2, '0')}:${seconds}`;
+  } else if (parts.length === 2) {
+    return `${String(parseInt(parts[0])).padStart(2, '0')}:${(parts[1] || '00').split('.')[0]}`;
   }
+  return ts;
+}
+
+app.get('/health', (req, res) => {
+  if (healthState.isRecovering) {
+    return res.status(503).json({ ok: false, engine: 'camoufox', recovering: true });
+  }
+  const running = browser !== null && (browser.isConnected?.() ?? false);
+  res.json({ 
+    ok: true, 
+    engine: 'camoufox',
+    browserConnected: running,
+    browserRunning: running,
+    activeTabs: getTotalTabCount(),
+    consecutiveFailures: healthState.consecutiveNavFailures,
+  });
 });
 
 // Create new tab
@@ -567,39 +1046,81 @@ app.post('/tabs/:tabId/navigate', async (req, res) => {
   const tabId = req.params.tabId;
   
   try {
-    const { userId, url, macro, query } = req.body;
-    const session = sessions.get(normalizeUserId(userId));
-    const found = session && findTab(session, tabId);
-    if (!found) return res.status(404).json({ error: 'Tab not found' });
-    
-    const { tabState } = found;
-    tabState.toolCalls++;
-    
-    let targetUrl = url;
-    if (macro) {
-      targetUrl = expandMacro(macro, query) || url;
-    }
-    
-    if (!targetUrl) {
-      return res.status(400).json({ error: 'url or macro required' });
-    }
-    
-    const urlErr = validateUrl(targetUrl);
-    if (urlErr) return res.status(400).json({ error: urlErr });
-    
-    // Serialize navigation operations on the same tab
-    const result = await withTabLock(tabId, async () => {
-      await tabState.page.goto(targetUrl, { waitUntil: 'domcontentloaded', timeout: 30000 });
-      tabState.visitedUrls.add(targetUrl);
-      tabState.refs = await buildRefs(tabState.page);
-      return { ok: true, url: tabState.page.url() };
-    });
+    const { userId, url, macro, query, sessionKey, listItemId } = req.body;
+    if (!userId) return res.status(400).json({ error: 'userId required' });
+
+    const result = await withUserLimit(userId, () => withTimeout((async () => {
+      await ensureBrowser();
+      let session = sessions.get(normalizeUserId(userId));
+      let found = session && findTab(session, tabId);
+      
+      let tabState;
+      if (!found) {
+        const resolvedSessionKey = sessionKey || listItemId || 'default';
+        session = await getSession(userId);
+        let sessionTabs = 0;
+        for (const g of session.tabGroups.values()) sessionTabs += g.size;
+        if (getTotalTabCount() >= MAX_TABS_GLOBAL || sessionTabs >= MAX_TABS_PER_SESSION) {
+          // Reuse oldest tab in session instead of rejecting
+          let oldestTab = null;
+          let oldestGroup = null;
+          let oldestTabId = null;
+          for (const [gKey, group] of session.tabGroups) {
+            for (const [tid, ts] of group) {
+              if (!oldestTab || ts.toolCalls < oldestTab.toolCalls) {
+                oldestTab = ts;
+                oldestGroup = group;
+                oldestTabId = tid;
+              }
+            }
+          }
+          if (oldestTab) {
+            tabState = oldestTab;
+            const group = getTabGroup(session, resolvedSessionKey);
+            if (oldestGroup) oldestGroup.delete(oldestTabId);
+            group.set(tabId, tabState);
+            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');
+          }
+        } else {
+          const page = await session.context.newPage();
+          tabState = createTabState(page);
+          const group = getTabGroup(session, resolvedSessionKey);
+          group.set(tabId, tabState);
+          log('info', 'tab auto-created on navigate', { reqId: req.reqId, tabId, userId });
+        }
+      } else {
+        tabState = found.tabState;
+      }
+      tabState.toolCalls++;
+      
+      let targetUrl = url;
+      if (macro) {
+        targetUrl = expandMacro(macro, query) || url;
+      }
+      
+      if (!targetUrl) throw new Error('url or macro required');
+      
+      const urlErr = validateUrl(targetUrl);
+      if (urlErr) throw new Error(urlErr);
+      
+      return await withTabLock(tabId, async () => {
+        await tabState.page.goto(targetUrl, { waitUntil: 'domcontentloaded', timeout: 30000 });
+        tabState.visitedUrls.add(targetUrl);
+        tabState.lastSnapshot = null;
+        tabState.refs = await buildRefs(tabState.page);
+        return { ok: true, tabId, url: tabState.page.url(), refsAvailable: tabState.refs.size > 0 };
+      });
+    })(), HANDLER_TIMEOUT_MS, 'navigate'));
     
     log('info', 'navigated', { reqId: req.reqId, tabId, url: result.url });
     res.json(result);
   } catch (err) {
     log('error', 'navigate failed', { reqId: req.reqId, tabId, error: err.message });
-    res.status(500).json({ error: safeError(err) });
+    const status = err.message && err.message.startsWith('Blocked URL scheme') ? 400 : 500;
+    res.status(status).json({ error: safeError(err) });
   }
 });
 
@@ -607,71 +1128,88 @@ app.post('/tabs/:tabId/navigate', async (req, res) => {
 app.get('/tabs/:tabId/snapshot', async (req, res) => {
   try {
     const userId = req.query.userId;
+    if (!userId) return res.status(400).json({ error: 'userId required' });
     const format = req.query.format || 'text';
+    const offset = parseInt(req.query.offset) || 0;
     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++;
-    tabState.refs = await buildRefs(tabState.page);
-    
-    const ariaYaml = await getAriaSnapshot(tabState.page);
-    
-    // Annotate YAML with ref IDs for interactive elements
-    let annotatedYaml = ariaYaml || '';
-    if (annotatedYaml && tabState.refs.size > 0) {
-      // Build a map of role+name -> refId for annotation
-      const refsByKey = new Map();
-      const seenCounts = new Map();
-      for (const [refId, info] of tabState.refs) {
-        const key = `${info.role}:${info.name}:${info.nth}`;
-        refsByKey.set(key, refId);
+
+    // Cached chunk retrieval for offset>0 requests
+    if (offset > 0 && tabState.lastSnapshot) {
+      const win = windowSnapshot(tabState.lastSnapshot, offset);
+      const response = { url: tabState.page.url(), 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' };
       }
+      log('info', 'snapshot (cached offset)', { reqId: req.reqId, tabId: req.params.tabId, offset, totalChars: win.totalChars });
+      return res.json(response);
+    }
+
+    const result = await withUserLimit(userId, () => withTimeout((async () => {
+      tabState.refs = await buildRefs(tabState.page);
+      const ariaYaml = await getAriaSnapshot(tabState.page);
       
-      // Track occurrences while annotating
-      const annotationCounts = new Map();
-      const lines = annotatedYaml.split('\n');
-      // Must match buildRefs - excludes combobox to avoid date pickers/complex dropdowns
-      const interactiveRoles = [
-        'button', 'link', 'textbox', 'checkbox', 'radio',
-        'menuitem', 'tab', 'searchbox', 'slider', 'spinbutton', 'switch'
-      ];
-      const skipPatterns = [/date/i, /calendar/i, /picker/i, /datepicker/i];
-      
-      annotatedYaml = lines.map(line => {
-        const match = line.match(/^(\s*-\s+)(\w+)(\s+"([^"]*)")?(.*)$/);
-        if (match) {
-          const [, prefix, role, nameMatch, name, suffix] = match;
-          const normalizedRole = role.toLowerCase();
-          
-          // Skip combobox and date-related elements (same as buildRefs)
-          if (normalizedRole === 'combobox') return line;
-          if (name && skipPatterns.some(p => p.test(name))) return line;
-          
-          if (interactiveRoles.includes(normalizedRole)) {
-            const normalizedName = name || '';
-            const countKey = `${normalizedRole}:${normalizedName}`;
-            const nth = annotationCounts.get(countKey) || 0;
-            annotationCounts.set(countKey, nth + 1);
-            
-            const key = `${normalizedRole}:${normalizedName}:${nth}`;
-            const refId = refsByKey.get(key);
-            if (refId) {
-              return `${prefix}${role}${nameMatch || ''} [${refId}]${suffix}`;
+      let annotatedYaml = ariaYaml || '';
+      if (annotatedYaml && tabState.refs.size > 0) {
+        const refsByKey = new Map();
+        for (const [refId, info] of tabState.refs) {
+          const key = `${info.role}:${info.name}:${info.nth}`;
+          refsByKey.set(key, refId);
+        }
+        
+        const annotationCounts = new Map();
+        const lines = annotatedYaml.split('\n');
+        
+        annotatedYaml = lines.map(line => {
+          const match = line.match(/^(\s*-\s+)(\w+)(\s+"([^"]*)")?(.*)$/);
+          if (match) {
+            const [, prefix, role, nameMatch, name, suffix] = match;
+            const normalizedRole = role.toLowerCase();
+            if (normalizedRole === 'combobox') return line;
+            if (name && SKIP_PATTERNS.some(p => p.test(name))) return line;
+            if (INTERACTIVE_ROLES.includes(normalizedRole)) {
+              const normalizedName = name || '';
+              const countKey = `${normalizedRole}:${normalizedName}`;
+              const nth = annotationCounts.get(countKey) || 0;
+              annotationCounts.set(countKey, nth + 1);
+              const key = `${normalizedRole}:${normalizedName}:${nth}`;
+              const refId = refsByKey.get(key);
+              if (refId) {
+                return `${prefix}${role}${nameMatch || ''} [${refId}]${suffix}`;
+              }
             }
           }
-        }
-        return line;
-      }).join('\n');
-    }
-    
-    const result = {
-      url: tabState.page.url(),
-      snapshot: annotatedYaml,
-      refsCount: tabState.refs.size
-    };
-    log('info', 'snapshot', { reqId: req.reqId, tabId: req.params.tabId, url: result.url, snapshotLen: result.snapshot?.length, refsCount: result.refsCount });
+          return line;
+        }).join('\n');
+      }
+      
+      tabState.lastSnapshot = annotatedYaml;
+      const win = windowSnapshot(annotatedYaml, 0);
+
+      const response = {
+        url: tabState.page.url(),
+        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;
+    })(), HANDLER_TIMEOUT_MS, 'snapshot'));
+
+    log('info', 'snapshot', { reqId: req.reqId, tabId: req.params.tabId, url: result.url, snapshotLen: result.snapshot?.length, refsCount: result.refsCount, hasScreenshot: !!result.screenshot, truncated: result.truncated });
     res.json(result);
   } catch (err) {
     log('error', 'snapshot failed', { reqId: req.reqId, tabId: req.params.tabId, error: err.message });
@@ -703,6 +1241,7 @@ app.post('/tabs/:tabId/click', async (req, res) => {
   
   try {
     const { userId, ref, selector } = req.body;
+    if (!userId) return res.status(400).json({ error: 'userId required' });
     const session = sessions.get(normalizeUserId(userId));
     const found = session && findTab(session, tabId);
     if (!found) return res.status(404).json({ error: 'Tab not found' });
@@ -714,7 +1253,7 @@ app.post('/tabs/:tabId/click', async (req, res) => {
       return res.status(400).json({ error: 'ref or selector required' });
     }
     
-    const result = await withTabLock(tabId, async () => {
+    const result = await withUserLimit(userId, () => withTimeout(withTabLock(tabId, async () => {
       // Full mouse event sequence for stubborn JS click handlers (mirrors Swift WebView.swift)
       // Dispatches: mouseover → mouseenter → mousedown → mouseup → click
       const dispatchMouseSequence = async (locator) => {
@@ -753,7 +1292,7 @@ app.post('/tabs/:tabId/click', async (req, res) => {
               log('warn', 'force click failed, trying mouse sequence');
               await dispatchMouseSequence(locator);
             }
-          } else if (err.message.includes('not visible') || err.message.includes('timeout')) {
+          } else if (err.message.includes('not visible') || err.message.toLowerCase().includes('timeout')) {
             // Fallback 2: Element not responding to click, try mouse sequence
             log('warn', 'click timeout, trying mouse sequence');
             await dispatchMouseSequence(locator);
@@ -764,7 +1303,13 @@ app.post('/tabs/:tabId/click', async (req, res) => {
       };
       
       if (ref) {
-        const locator = refToLocator(tabState.page, ref, tabState.refs);
+        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);
+          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.`);
@@ -775,12 +1320,13 @@ app.post('/tabs/:tabId/click', async (req, res) => {
       }
       
       await tabState.page.waitForTimeout(500);
+      tabState.lastSnapshot = null;
       tabState.refs = await buildRefs(tabState.page);
       
       const newUrl = tabState.page.url();
       tabState.visitedUrls.add(newUrl);
-      return { ok: true, url: 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);
@@ -883,11 +1429,11 @@ app.post('/tabs/:tabId/back', async (req, res) => {
     const { tabState } = found;
     tabState.toolCalls++;
     
-    const result = await withTabLock(tabId, async () => {
+    const result = await withTimeout(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) {
@@ -909,11 +1455,11 @@ app.post('/tabs/:tabId/forward', async (req, res) => {
     const { tabState } = found;
     tabState.toolCalls++;
     
-    const result = await withTabLock(tabId, async () => {
+    const result = await withTimeout(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) {
@@ -935,11 +1481,11 @@ app.post('/tabs/:tabId/refresh', async (req, res) => {
     const { tabState } = found;
     tabState.toolCalls++;
     
-    const result = await withTabLock(tabId, async () => {
+    const result = await withTimeout(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) {
@@ -1039,7 +1585,7 @@ app.delete('/tabs/:tabId', async (req, res) => {
     const session = sessions.get(normalizeUserId(userId));
     const found = session && findTab(session, req.params.tabId);
     if (found) {
-      await found.tabState.page.close();
+      await safePageClose(found.tabState.page);
       found.group.delete(req.params.tabId);
       tabLocks.delete(req.params.tabId);
       if (found.group.size === 0) {
@@ -1062,7 +1608,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 tabState.page.close().catch(() => {});
+        await safePageClose(tabState.page);
         tabLocks.delete(tabId);
       }
       session.tabGroups.delete(req.params.listItemId);
@@ -1085,6 +1631,7 @@ app.delete('/sessions/:userId', async (req, res) => {
       sessions.delete(userId);
       log('info', 'session closed', { userId });
     }
+    if (sessions.size === 0) scheduleBrowserIdleShutdown();
     res.json({ ok: true });
   } catch (err) {
     log('error', 'session close failed', { error: err.message });
@@ -1102,6 +1649,10 @@ setInterval(() => {
       log('info', 'session expired', { userId });
     }
   }
+  // When all sessions gone, start idle timer to kill browser
+  if (sessions.size === 0) {
+    scheduleBrowserIdleShutdown();
+  }
 }, 60_000);
 
 // =============================================================================
@@ -1109,20 +1660,17 @@ setInterval(() => {
 // These allow camoufox to be used as a profile backend for OpenClaw's browser tool
 // =============================================================================
 
-// GET / - Status (alias for GET /health)
-app.get('/', async (req, res) => {
-  try {
-    const b = await ensureBrowser();
-    res.json({ 
-      ok: true,
-      enabled: true,
-      running: b.isConnected(),
-      engine: 'camoufox',
-      browserConnected: b.isConnected()
-    });
-  } catch (err) {
-    res.status(500).json({ ok: false, error: safeError(err) });
-  }
+// GET / - Status (passive — does not launch browser)
+app.get('/', (req, res) => {
+  const running = browser !== null && (browser.isConnected?.() ?? false);
+  res.json({ 
+    ok: true,
+    enabled: true,
+    running,
+    engine: 'camoufox',
+    browserConnected: running,
+    browserRunning: running,
+  });
 });
 
 // GET /tabs - List all tabs (OpenClaw expects this)
@@ -1252,12 +1800,12 @@ app.post('/navigate', async (req, res) => {
     const { tabState } = found;
     tabState.toolCalls++;
     
-    const result = await withTabLock(targetId, async () => {
+    const result = await withTimeout(withTabLock(targetId, async () => {
       await tabState.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
       tabState.visitedUrls.add(url);
       tabState.refs = await buildRefs(tabState.page);
       return { ok: true, targetId, url: tabState.page.url() };
-    });
+    }), HANDLER_TIMEOUT_MS, 'openclaw-navigate');
     
     res.json(result);
   } catch (err) {
@@ -1270,6 +1818,7 @@ app.post('/navigate', async (req, res) => {
 app.get('/snapshot', async (req, res) => {
   try {
     const { targetId, userId, format = 'text' } = req.query;
+    const offset = parseInt(req.query.offset) || 0;
     if (!userId) {
       return res.status(400).json({ error: 'userId is required' });
     }
@@ -1282,6 +1831,18 @@ app.get('/snapshot', async (req, res) => {
     
     const { tabState } = found;
     tabState.toolCalls++;
+
+    // Cached chunk retrieval
+    if (offset > 0 && tabState.lastSnapshot) {
+      const win = windowSnapshot(tabState.lastSnapshot, offset);
+      const response = { ok: true, format: 'aria', targetId, url: tabState.page.url(), 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);
@@ -1310,14 +1871,28 @@ app.get('/snapshot', async (req, res) => {
       }).join('\n');
     }
     
-    res.json({
+    tabState.lastSnapshot = annotatedYaml;
+    const win = windowSnapshot(annotatedYaml, 0);
+
+    const response = {
       ok: true,
       format: 'aria',
       targetId,
       url: tabState.page.url(),
-      snapshot: annotatedYaml,
-      refsCount: tabState.refs.size
-    });
+      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' };
+    }
+
+    res.json(response);
   } catch (err) {
     log('error', 'openclaw snapshot failed', { reqId: req.reqId, error: err.message });
     res.status(500).json({ error: safeError(err) });
@@ -1346,7 +1921,7 @@ app.post('/act', async (req, res) => {
     const { tabState } = found;
     tabState.toolCalls++;
     
-    const result = await withTabLock(targetId, async () => {
+    const result = await withTimeout(withTabLock(targetId, async () => {
       switch (kind) {
         case 'click': {
           const { ref, selector, doubleClick } = params;
@@ -1453,7 +2028,7 @@ app.post('/act', async (req, res) => {
         }
         
         case 'close': {
-          await tabState.page.close();
+          await safePageClose(tabState.page);
           found.group.delete(targetId);
           tabLocks.delete(targetId);
           return { ok: true, targetId };
@@ -1462,7 +2037,7 @@ app.post('/act', async (req, res) => {
         default:
           throw new Error(`Unsupported action kind: ${kind}`);
       }
-    });
+    }), HANDLER_TIMEOUT_MS, 'act');
     
     res.json(result);
   } catch (err) {
@@ -1490,6 +2065,32 @@ setInterval(() => {
   });
 }, 5 * 60_000);
 
+// 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) {
+    log('info', 'health probe skipped, operations active', { activeOps: healthState.activeOps });
+    return;
+  }
+  const timeSinceSuccess = Date.now() - healthState.lastSuccessfulNav;
+  if (timeSinceSuccess < 120000) return;
+  
+  let testContext;
+  try {
+    testContext = await browser.newContext();
+    const page = await testContext.newPage();
+    await page.goto('about:blank', { timeout: 5000 });
+    await page.close();
+    await testContext.close();
+    healthState.lastSuccessfulNav = Date.now();
+  } catch (err) {
+    log('warn', 'health probe failed', { error: err.message, timeSinceSuccessMs: timeSinceSuccess });
+    if (testContext) await testContext.close().catch(() => {});
+    restartBrowser('health probe failed').catch(() => {});
+  }
+}, 60_000);
+
 // Crash logging
 process.on('uncaughtException', (err) => {
   log('error', 'uncaughtException', { error: err.message, stack: err.stack });
@@ -1528,9 +2129,7 @@ process.on('SIGINT', () => gracefulShutdown('SIGINT'));
 const PORT = CONFIG.port;
 const server = app.listen(PORT, () => {
   log('info', 'server started', { port: PORT, pid: process.pid, nodeVersion: process.version });
-  ensureBrowser().catch(err => {
-    log('error', 'browser pre-launch failed', { error: err.message });
-  });
+  // Browser launches lazily on first request (saves ~550MB when idle)
 });
 
 server.on('error', (err) => {