@askjo/camofox-browser 1.1.2 → 1.2.0

package/Dockerfile

@@ -57,4 +57,4 @@ ENV CAMOFOX_PORT=3000
 
 EXPOSE 3000
 
-CMD ["node", "server.js"]
+CMD ["sh", "-c", "node --max-old-space-size=${MAX_OLD_SPACE_SIZE:-128} server.js"]

package/README.md

@@ -32,6 +32,7 @@ This project wraps that engine in a REST API built for agents: accessibility sna
 - **C++ Anti-Detection** - bypasses Google, Cloudflare, and most bot detection
 - **Element Refs** - stable `e1`, `e2`, `e3` identifiers for reliable interaction
 - **Token-Efficient** - accessibility snapshots are ~90% smaller than raw HTML
+- **Runs on Anything** - lazy browser launch + idle shutdown keeps memory at ~40MB when idle. Designed to share a box with the rest of your stack — Raspberry Pi, $5 VPS, shared Railway infra.
 - **Session Isolation** - separate cookies/storage per user
 - **Cookie Import** - inject Netscape-format cookie files for authenticated browsing
 - **Proxy + GeoIP** - route traffic through residential proxies with automatic locale/timezone
@@ -294,6 +295,13 @@ Reddit macros return JSON directly (no HTML parsing needed):
 | `CAMOFOX_API_KEY` | Enable cookie import endpoint (disabled if unset) | - |
 | `CAMOFOX_ADMIN_KEY` | Required for `POST /stop` | - |
 | `CAMOFOX_COOKIES_DIR` | Directory for cookie files | `~/.camofox/cookies` |
+| `MAX_SESSIONS` | Max concurrent browser sessions | `50` |
+| `MAX_TABS_PER_SESSION` | Max tabs per session | `10` |
+| `SESSION_TIMEOUT_MS` | Session inactivity timeout | `1800000` (30min) |
+| `BROWSER_IDLE_TIMEOUT_MS` | Kill browser when idle (0 = never) | `300000` (5min) |
+| `HANDLER_TIMEOUT_MS` | Max time for any handler | `30000` (30s) |
+| `MAX_CONCURRENT_PER_USER` | Concurrent request cap per user | `3` |
+| `MAX_OLD_SPACE_SIZE` | Node.js V8 heap limit (MB) | `128` |
 | `PROXY_HOST` | Proxy hostname or IP | - |
 | `PROXY_PORT` | Proxy port | - |
 | `PROXY_USERNAME` | Proxy auth username | - |
@@ -311,7 +319,7 @@ Browser Instance (Camoufox)
         └── Tab (amazon.com)
 ```
 
-Sessions auto-expire after 30 minutes of inactivity.
+Sessions auto-expire after 30 minutes of inactivity. The browser itself shuts down after 5 minutes with no active sessions, and relaunches on the next request.
 
 ## Testing
 

package/lib/config.js

@@ -15,6 +15,8 @@ function loadConfig() {
     adminKey: process.env.CAMOFOX_ADMIN_KEY || '',
     apiKey: process.env.CAMOFOX_API_KEY || '',
     cookiesDir: process.env.CAMOFOX_COOKIES_DIR || join(os.homedir(), '.camofox', 'cookies'),
+    handlerTimeoutMs: parseInt(process.env.HANDLER_TIMEOUT_MS) || 30000,
+    maxConcurrentPerUser: parseInt(process.env.MAX_CONCURRENT_PER_USER) || 3,
     proxy: {
       host: process.env.PROXY_HOST || '',
       port: process.env.PROXY_PORT || '',

package/lib/launcher.js

@@ -14,12 +14,14 @@ const startProcess = cp.spawn;
  * @param {string} opts.pluginDir - Directory containing server.js
  * @param {number} opts.port - Port number for the server
  * @param {object} opts.env - Environment variables to pass to the subprocess
+ * @param {string[]} [opts.nodeArgs] - Extra Node.js CLI flags (e.g. --max-old-space-size=128)
  * @param {{ info: (msg: string) => void, error: (msg: string) => void }} opts.log - Logger
  * @returns {import('child_process').ChildProcess}
  */
-function launchServer({ pluginDir, port, env, log }) {
+function launchServer({ pluginDir, port, env, nodeArgs, log }) {
   const serverPath = join(pluginDir, 'server.js');
-  const proc = startProcess('node', [serverPath], {
+  const args = [...(nodeArgs || []), serverPath];
+  const proc = startProcess('node', args, {
     cwd: pluginDir,
     env: {
       ...env,

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "camofox-browser",
   "name": "Camofox Browser",
   "description": "Anti-detection browser automation for AI agents using Camoufox (Firefox-based)",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "configSchema": {
     "type": "object",
     "properties": {
@@ -19,6 +19,31 @@
         "type": "boolean",
         "description": "Auto-start the camofox-browser server with the Gateway",
         "default": true
+      },
+      "maxSessions": {
+        "type": "number",
+        "description": "Maximum concurrent browser sessions (server default: 50)",
+        "default": 5
+      },
+      "maxTabsPerSession": {
+        "type": "number",
+        "description": "Maximum tabs per session (server default: 10)",
+        "default": 3
+      },
+      "sessionTimeoutMs": {
+        "type": "number",
+        "description": "Session inactivity timeout in milliseconds (server default: 1800000)",
+        "default": 600000
+      },
+      "browserIdleTimeoutMs": {
+        "type": "number",
+        "description": "Kill browser after this many ms with no sessions (0 = never)",
+        "default": 300000
+      },
+      "maxOldSpaceSize": {
+        "type": "number",
+        "description": "Node.js V8 heap limit in MB",
+        "default": 128
       }
     },
     "additionalProperties": false
@@ -34,6 +59,26 @@
     },
     "autoStart": {
       "label": "Auto-start server with Gateway"
+    },
+    "maxSessions": {
+      "label": "Max Sessions",
+      "placeholder": "5"
+    },
+    "maxTabsPerSession": {
+      "label": "Max Tabs per Session",
+      "placeholder": "3"
+    },
+    "sessionTimeoutMs": {
+      "label": "Session Timeout (ms)",
+      "placeholder": "600000"
+    },
+    "browserIdleTimeoutMs": {
+      "label": "Browser Idle Timeout (ms)",
+      "placeholder": "300000"
+    },
+    "maxOldSpaceSize": {
+      "label": "Node Heap Limit (MB)",
+      "placeholder": "128"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askjo/camofox-browser",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Headless browser automation server and OpenClaw plugin for AI agents - anti-detection, element refs, and session isolation",
   "main": "server.js",
   "license": "MIT",

package/plugin.ts

@@ -29,6 +29,11 @@ interface PluginConfig {
   url?: string;
   autoStart?: boolean;
   port?: number;
+  maxSessions?: number;
+  maxTabsPerSession?: number;
+  sessionTimeoutMs?: number;
+  browserIdleTimeoutMs?: number;
+  maxOldSpaceSize?: number;
 }
 
 interface ToolResult {
@@ -109,10 +114,16 @@ let serverProcess: ChildProcess | null = null;
 async function startServer(
   pluginDir: string,
   port: number,
-  log: PluginApi["log"]
+  log: PluginApi["log"],
+  pluginCfg?: PluginConfig
 ): Promise<ChildProcess> {
   const cfg = loadConfig();
-  const proc = launchServer({ pluginDir, port, env: cfg.serverEnv, log });
+  const env: Record<string, string> = { ...cfg.serverEnv };
+  if (pluginCfg?.maxSessions != null) env.MAX_SESSIONS = String(pluginCfg.maxSessions);
+  if (pluginCfg?.maxTabsPerSession != null) env.MAX_TABS_PER_SESSION = String(pluginCfg.maxTabsPerSession);
+  if (pluginCfg?.sessionTimeoutMs != null) env.SESSION_TIMEOUT_MS = String(pluginCfg.sessionTimeoutMs);
+  if (pluginCfg?.browserIdleTimeoutMs != null) env.BROWSER_IDLE_TIMEOUT_MS = String(pluginCfg.browserIdleTimeoutMs);
+  const proc = launchServer({ pluginDir, port, env, log, nodeArgs: pluginCfg?.maxOldSpaceSize != null ? [`--max-old-space-size=${pluginCfg.maxOldSpaceSize}`] : undefined });
 
   proc.on("error", (err: Error) => {
     log?.error?.(`Server process error: ${err.message}`);
@@ -194,7 +205,7 @@ export default function register(api: PluginApi) {
         api.log?.info?.(`Camoufox server already running at ${baseUrl}`);
       } else {
         try {
-          serverProcess = await startServer(pluginDir, port, api.log);
+          serverProcess = await startServer(pluginDir, port, api.log, cfg);
         } catch (err) {
           api.log?.error?.(`Failed to auto-start server: ${(err as Error).message}`);
         }
@@ -499,7 +510,7 @@ export default function register(api: PluginApi) {
             return;
           }
           try {
-            serverProcess = await startServer(pluginDir, port, api.log);
+            serverProcess = await startServer(pluginDir, port, api.log, cfg);
           } catch (err) {
             api.log?.error?.(`Failed to start server: ${(err as Error).message}`);
           }
@@ -622,7 +633,7 @@ export default function register(api: PluginApi) {
             }
             try {
               console.log(`Starting camofox server on port ${port}...`);
-              serverProcess = await startServer(pluginDir, port, api.log);
+              serverProcess = await startServer(pluginDir, port, api.log, cfg);
               console.log(`Camoufox server started at ${baseUrl}`);
             } catch (err) {
               console.error(`Failed to start server: ${(err as Error).message}`);

package/run.sh

@@ -32,6 +32,6 @@ fi
 
 echo "Starting camofox-browser on http://localhost:$CAMOFOX_PORT (with auto-reload)"
 echo "Logs: /tmp/camofox-browser.log"
-nodemon --watch server.js --exec "node server.js" 2>&1 | while IFS= read -r line; do
+nodemon --watch server.js --exec "node --max-old-space-size=128 server.js" 2>&1 | while IFS= read -r line; do
   echo "[$(date '+%Y-%m-%d %H:%M:%S')] $line"
 done | tee -a /tmp/camofox-browser.log

package/server.js

@@ -46,6 +46,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 +171,13 @@ 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 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;
 
 // Per-tab locks to serialize operations on the same tab
 // tabId -> Promise (the currently executing operation)
@@ -192,6 +208,56 @@ 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++;
+  try {
+    return await operation();
+  } finally {
+    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 +282,70 @@ 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;
+  }
+}
+
+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)
@@ -404,33 +514,18 @@ async function buildRefs(page) {
   // inject a script to collect shadow DOM elements for additional coverage
   let ariaYaml;
   try {
-    ariaYaml = await page.locator('body').ariaSnapshot({ timeout: 10000 });
+    ariaYaml = await page.locator('body').ariaSnapshot({ timeout: 5000 });
   } catch (err) {
     log('warn', 'ariaSnapshot failed, retrying');
-    await page.waitForLoadState('load', { timeout: 5000 }).catch(() => {});
-    ariaYaml = await page.locator('body').ariaSnapshot({ timeout: 10000 });
+    try {
+      await page.waitForLoadState('load', { timeout: 3000 }).catch(() => {});
+      ariaYaml = await page.locator('body').ariaSnapshot({ timeout: 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 +534,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 +545,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 +571,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 +593,16 @@ function refToLocator(page, ref, refs) {
   return locator;
 }
 
-// Health check
-app.get('/health', async (req, res) => {
-  try {
-    const b = await ensureBrowser();
-    res.json({ 
-      ok: true, 
-      engine: 'camoufox',
-      browserConnected: b.isConnected()
-    });
-  } catch (err) {
-    res.status(500).json({ ok: false, error: safeError(err) });
-  }
+// Health check (passive — does not launch browser)
+app.get('/health', (req, res) => {
+  const running = browser !== null && (browser.isConnected?.() ?? false);
+  res.json({ 
+    ok: true, 
+    engine: 'camoufox',
+    browserConnected: running,
+    browserRunning: running,
+    sessions: sessions.size,
+  });
 });
 
 // Create new tab
@@ -567,33 +650,50 @@ 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);
+      
+      if (!found) {
+        const resolvedSessionKey = sessionKey || listItemId || 'default';
+        session = await getSession(userId);
+        let totalTabs = 0;
+        for (const g of session.tabGroups.values()) totalTabs += g.size;
+        if (totalTabs >= MAX_TABS_PER_SESSION) {
+          throw new Error('Maximum tabs per session reached');
+        }
+        const page = await session.context.newPage();
+        const newTabState = createTabState(page);
+        const group = getTabGroup(session, resolvedSessionKey);
+        group.set(tabId, newTabState);
+        found = { tabState: newTabState, listItemId: resolvedSessionKey, group };
+        log('info', 'tab auto-created on navigate', { reqId: req.reqId, tabId, userId });
+      }
+      
+      const { tabState } = found;
+      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.refs = await buildRefs(tabState.page);
+        return { ok: true, tabId, url: tabState.page.url() };
+      });
+    })(), HANDLER_TIMEOUT_MS, 'navigate'));
     
     log('info', 'navigated', { reqId: req.reqId, tabId, url: result.url });
     res.json(result);
@@ -607,6 +707,7 @@ 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 session = sessions.get(normalizeUserId(userId));
     const found = session && findTab(session, req.params.tabId);
@@ -614,63 +715,52 @@ app.get('/tabs/:tabId/snapshot', async (req, res) => {
     
     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);
-      }
-      
-      // 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];
+
+    const result = await withUserLimit(userId, () => withTimeout((async () => {
+      tabState.refs = await buildRefs(tabState.page);
+      const ariaYaml = await getAriaSnapshot(tabState.page);
       
-      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
-    };
+          return line;
+        }).join('\n');
+      }
+      
+      return {
+        url: tabState.page.url(),
+        snapshot: annotatedYaml,
+        refsCount: tabState.refs.size
+      };
+    })(), HANDLER_TIMEOUT_MS, 'snapshot'));
+
     log('info', 'snapshot', { reqId: req.reqId, tabId: req.params.tabId, url: result.url, snapshotLen: result.snapshot?.length, refsCount: result.refsCount });
     res.json(result);
   } catch (err) {
@@ -703,6 +793,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 +805,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) => {
@@ -780,7 +871,7 @@ app.post('/tabs/:tabId/click', async (req, res) => {
       const newUrl = tabState.page.url();
       tabState.visitedUrls.add(newUrl);
       return { ok: true, url: newUrl };
-    });
+    }), HANDLER_TIMEOUT_MS, 'click'));
     
     log('info', 'clicked', { reqId: req.reqId, tabId, url: result.url });
     res.json(result);
@@ -883,11 +974,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 +1000,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 +1026,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 +1130,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 +1153,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 +1176,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 +1194,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 +1205,18 @@ 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,
+    sessions: sessions.size,
+  });
 });
 
 // GET /tabs - List all tabs (OpenClaw expects this)
@@ -1252,12 +1346,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) {
@@ -1346,7 +1440,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 +1547,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 +1556,7 @@ app.post('/act', async (req, res) => {
         default:
           throw new Error(`Unsupported action kind: ${kind}`);
       }
-    });
+    }), HANDLER_TIMEOUT_MS, 'act');
     
     res.json(result);
   } catch (err) {
@@ -1528,9 +1622,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) => {