cdpilot 0.9.0 → 0.9.2

package/src/cdpilot.py

@@ -8,13 +8,20 @@ Chrome DevTools Protocol (CDP). No Puppeteer, no Playwright, no Selenium.
 Usage:
   cdpilot <command> [arguments]
 
+Global options:
+  --timeout <seconds>  Abort the command after <seconds> (exit 124). Accepted
+                       before or after the command name; 0 disables.
+
 Environment:
   CDP_PORT             CDP debugging port (default: 9222)
   CHROME_BIN           Browser binary path (auto-detected if not set)
   CDPILOT_PROFILE      Isolated browser profile directory
+  CDPILOT_TIMEOUT      Default for --timeout (the flag wins)
+  CDPILOT_NO_AUTOLAUNCH=1  Do not start the browser when a page command
+                       finds it not running (print the error instead)
 """
 
-__version__ = "0.9.0"
+__version__ = "0.9.2"
 
 import asyncio
 import atexit
@@ -35,13 +42,20 @@ import secrets
 import glob
 import datetime
 import concurrent.futures
+import tempfile
+import contextlib
+import io
+import threading
+import weakref
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 
 # ─── Project-Based Multi-Instance Configuration ───
 # Each project directory (cwd) gets its own browser instance with
 # a unique CDP port and isolated profile directory. Zero-config.
 
-CDPILOT_HOME = os.path.expanduser("~/.cdpilot")
+# CDPILOT_HOME override lets tests (and advanced users) point the registry
+# at an isolated directory instead of the real ~/.cdpilot.
+CDPILOT_HOME = os.environ.get("CDPILOT_HOME") or os.path.expanduser("~/.cdpilot")
 REGISTRY_FILE = os.path.join(CDPILOT_HOME, "registry.json")
 CDPILOT_PORT_RANGE_START = 9222
 CDPILOT_PORT_RANGE_END = 9322
@@ -65,10 +79,19 @@ def _get_project_id():
 
 
 def _is_port_free(port):
-    """Check if a port is available for binding."""
+    """Check if a port is available for binding.
+
+    On Windows, SO_REUSEADDR lets a socket bind on top of a port that another
+    socket is actively listening on, so a probe using it called every port
+    free (and registry cleanup pruned live entries). Exclusive use fails when
+    anything holds the port. POSIX SO_REUSEADDR only skips TIME_WAIT.
+    """
     with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
         try:
-            s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            if os.name == "nt":
+                s.setsockopt(socket.SOL_SOCKET, socket.SO_EXCLUSIVEADDRUSE, 1)
+            else:
+                s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
             s.bind(("127.0.0.1", port))
             return True
         except OSError:
@@ -86,10 +109,26 @@ def _load_registry():
 
 
 def _save_registry(projects):
-    """Write the global project registry."""
-    os.makedirs(os.path.dirname(REGISTRY_FILE), exist_ok=True)
-    with open(REGISTRY_FILE, 'w') as f:
-        json.dump({"version": 1, "projects": projects}, f, indent=2)
+    """Write the global project registry atomically.
+
+    Writes to a temp file in the same directory and os.replace()s it into
+    place, so a concurrent cdpilot invocation reading registry.json always
+    sees either the fully-old or fully-new content — never a torn/partial
+    write (os.replace is atomic on both POSIX and Windows).
+    """
+    reg_dir = os.path.dirname(REGISTRY_FILE)
+    os.makedirs(reg_dir, exist_ok=True)
+    fd, tmp_path = tempfile.mkstemp(prefix='.registry-', suffix='.tmp', dir=reg_dir)
+    try:
+        with os.fdopen(fd, 'w') as f:
+            json.dump({"version": 1, "projects": projects}, f, indent=2)
+        os.replace(tmp_path, REGISTRY_FILE)
+    except BaseException:
+        try:
+            os.remove(tmp_path)
+        except OSError:
+            pass
+        raise
 
 
 def _register_project(project_id, port, profile_dir, pid=None):
@@ -108,25 +147,83 @@ def _register_project(project_id, port, profile_dir, pid=None):
     _save_registry(registry)
 
 
+def _pid_alive(pid):
+    """True if a process with this pid exists. Never signals it.
+
+    Sending signal 0 is a harmless existence probe on POSIX, but on Windows
+    Python maps every signal other than CTRL_C/CTRL_BREAK to TerminateProcess:
+    the "probe" kills the process. Registry pids are stale by nature and may
+    have been reused by an unrelated program, so on Windows ask the kernel
+    through OpenProcess/GetExitCodeProcess instead. Defined this early because
+    it runs at import time (_resolve_project_config -> _allocate_port).
+    """
+    try:
+        pid = int(pid)
+    except (TypeError, ValueError):
+        return False
+    if pid <= 0:
+        return False
+    if os.name == "nt":
+        import ctypes
+        kernel32 = ctypes.windll.kernel32
+        handle = kernel32.OpenProcess(0x1000, False, pid)  # QUERY_LIMITED_INFORMATION
+        if not handle:
+            return False
+        try:
+            code = ctypes.c_ulong()
+            if not kernel32.GetExitCodeProcess(handle, ctypes.byref(code)):
+                return False
+            return code.value == 259  # STILL_ACTIVE
+        finally:
+            kernel32.CloseHandle(handle)
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True  # exists, just owned by another user
+    except OSError:
+        return False
+    return True
+
+
+def _is_registry_entry_dead(info):
+    """A registry entry is dead only when we can PROVE nothing is using it.
+
+    Dead = nothing is listening on its port AND (if a pid was recorded)
+    that process is no longer alive. If the port is currently bound, we
+    never call it dead even if our own bookkeeping (status/pid) looks
+    stale — it may be another project's live browser instance, and a
+    live entry must never be pruned.
+    """
+    port = info.get("port")
+    if port and not _is_port_free(port):
+        return False
+    pid = info.get("pid")
+    if pid and _pid_alive(pid):
+        return False
+    return True
+
+
 def _cleanup_registry():
-    """Update status for dead processes and return cleaned registry."""
+    """Prune dead entries from the registry and return what's left.
+
+    Called before every port allocation (see _allocate_port) so the
+    registry never accumulates stale entries that starve the
+    9222-9322 port range — the root cause of the "No free port" failure
+    documented in .claude/docs/vaat-denetimi-2026-09-27.md.
+    """
     registry = _load_registry()
-    changed = False
-    for pid_key, info in registry.items():
-        if info.get("status") == "running":
-            port = info.get("port")
-            if port and _is_port_free(port):
-                info["status"] = "stopped"
-                info["pid"] = None
-                changed = True
-    if changed:
-        _save_registry(registry)
-    return registry
+    alive = {pid_key: info for pid_key, info in registry.items()
+             if not _is_registry_entry_dead(info)}
+    if len(alive) != len(registry):
+        _save_registry(alive)
+    return alive
 
 
 def _allocate_port(project_id):
     """Find a free port for the given project."""
-    registry = _load_registry()
+    registry = _cleanup_registry()
 
     # Reuse existing port if still free
     if project_id in registry:
@@ -388,7 +485,9 @@ STEALTH_JS_FULL = r"""
         length:      { value: 1,           enumerable: true },
         '0':         { value: mime,        enumerable: true }
       });
-      p.item = function(i) { return i === 0 ? mime : null; };
+      // `i >>> 0` = WebIDL unsigned long (ToUint32), like the native item():
+      // item(4294967296) wraps to item(0) (incolumitas overflowTest).
+      p.item = function(i) { return (i >>> 0) === 0 ? mime : null; };
       p.namedItem = function(n) { return n === mime.type ? mime : null; };
       return p;
     };
@@ -406,7 +505,7 @@ STEALTH_JS_FULL = r"""
       Object.defineProperty(plugins, p.name, { value: p });
     }
     Object.defineProperty(plugins, 'length', { value: pluginNames.length });
-    plugins.item = function(i) { return plugins[i] || null; };
+    plugins.item = function(i) { return plugins[i >>> 0] || null; };
     plugins.namedItem = function(n) {
       for (var k = 0; k < plugins.length; k++) if (plugins[k].name === n) return plugins[k];
       return null;
@@ -419,26 +518,39 @@ STEALTH_JS_FULL = r"""
   } catch (e) {}
 
   // 4b) Worker stealth — workers have their own global scope, so navigator.webdriver
-  // patches above do NOT propagate. Fingerprint scripts that probe via Worker
-  // (e.g. fpscanner.WEBDRIVER) catch this inconsistency. Fix: wrap the Worker
-  // constructor to prepend a navigator.webdriver patch via blob URL. Limitations:
-  // module workers and same-origin script URLs are best-effort (importScripts
-  // doesn't support module workers; cross-origin URLs may bypass via direct fetch).
+  // patches above do NOT propagate. Fix: wrap the Worker constructor to prepend a
+  // navigator.webdriver patch via blob URL. (fpscanner.WEBDRIVER is NOT a worker
+  // probe: it is `'webdriver' in navigator` on the page, true in every modern
+  // Chrome.) Limitations: module workers are skipped (importScripts can't load
+  // them); inside the blob worker, self.location is the blob: URL.
+  // Worker scope has no navigator.webdriver in Chrome; the patch only acts if a
+  // worker ever reports `true` (defining it unconditionally made 'webdriver' in
+  // navigator true inside workers - a tell). The script URL is resolved against
+  // the page: a relative URL inside a blob: worker resolves against blob: and
+  // failed to load (incolumitas `new Worker("webworker2.js")` never answered).
   try {
     var OrigWorker = window.Worker;
     if (OrigWorker && !window.__cdpilot_worker_patched) {
-      var workerPatch = "(function(){try{Object.defineProperty(self.navigator||{},'webdriver',{get:function(){return undefined;},configurable:true});}catch(e){}})();";
+      var workerPatch = "(function(){try{if(self.navigator&&self.navigator.webdriver===true){Object.defineProperty(self.navigator,'webdriver',{get:function(){return false;},configurable:true});}}catch(e){}})();";
       var WrappedWorker = function(scriptURL, options) {
+        var origURL = scriptURL;
         try {
           var isModule = options && options.type === 'module';
           if (typeof scriptURL === 'string' && !isModule) {
             // Wrap script in a blob that applies the patch then importScripts the original.
-            var wrapped = workerPatch + "importScripts(" + JSON.stringify(String(scriptURL)) + ");";
+            var absURL = new URL(String(scriptURL), document.baseURI).href;
+            var wrapped = workerPatch + "importScripts(" + JSON.stringify(absURL) + ");";
             var blob = new Blob([wrapped], { type: 'application/javascript' });
             scriptURL = URL.createObjectURL(blob);
           }
-        } catch (e) {}
-        return new OrigWorker(scriptURL, options);
+        } catch (e) { scriptURL = origURL; }
+        try {
+          return new OrigWorker(scriptURL, options);
+        } catch (e) {
+          // e.g. CSP forbids blob: workers - fall back to the untouched native call.
+          if (scriptURL === origURL) throw e;
+          return new OrigWorker(origURL, options);
+        }
       };
       WrappedWorker.prototype = OrigWorker.prototype;
       Object.setPrototypeOf(WrappedWorker, OrigWorker);
@@ -1138,11 +1250,86 @@ def cdp_cache_invalidate():
     _CDP_GET_CACHE.clear()
 
 
+# ─── Auto-launch ───
+# Measured on ~1,225 real agent sessions: "CDP connection error. Is the browser
+# running?" was the #1 failure (292 times) — the agent never ran `launch`, or
+# the browser died between commands. A page-level command that finds the CDP
+# port unreachable now launches the browser exactly like `cdpilot launch`
+# (same profile, same headless/visible config), then continues once.
+AUTOLAUNCH_DISABLE_ENV = "CDPILOT_NO_AUTOLAUNCH"
+AUTOLAUNCH_NOTICE = ("cdpilot: browser was not running — launched it "
+                     "(CDPILOT_NO_AUTOLAUNCH=1 to disable)")
+# Commands that never start a browser, whatever they touch:
+#   lifecycle      — launching to stop/close would be absurd;
+#   status/diag    — a check must report the state, not change it;
+#   launch config  — must take effect on the NEXT launch, not after one we forced;
+#   servers        — startup never launches (`mcp` tool calls run as separate
+#                    page-level commands and do auto-launch).
+# status/setup/help/--version are answered by bin/cdpilot.js; listed so a direct
+# `python src/cdpilot.py <name>` can never launch either.
+AUTOLAUNCH_SKIP_CMDS = frozenset({
+    'launch', 'stop', 'close', 'close-tab', 'session-close', 'project-stop', 'stop-all',
+    'status', 'health', 'setup', 'help', '--help', '-h', 'version', '--version', '-v',
+    'tabs', 'session', 'sessions', 'projects', 'heal',
+    'headless', 'proxy', 'browser', 'extensions', 'ext-install', 'ext-remove',
+    'mcp', 'serve',
+})
+# cmd is set by the CLI dispatcher; None (module imported) means never launch.
+_AUTOLAUNCH = {"cmd": None, "attempted": False, "failure": None}
+
+
+def _autolaunch_disabled():
+    return os.environ.get(AUTOLAUNCH_DISABLE_ENV, "").strip().lower() in ("1", "true", "yes", "on")
+
+
+def _autolaunch_if_down():
+    """Launch the browser (once per process) when this command may and CDP is down.
+
+    Returns True when CDP answers afterwards. Never exits: on failure the
+    reason is kept for _print_autolaunch_failure(), which callers print right
+    after their usual error, so CDPILOT_NO_AUTOLAUNCH=1 output stays identical.
+    """
+    cmd = _AUTOLAUNCH["cmd"]
+    if (cmd is None or cmd in AUTOLAUNCH_SKIP_CMDS or _AUTOLAUNCH["attempted"]
+            or _autolaunch_disabled()):
+        return False
+    _AUTOLAUNCH["attempted"] = True
+    if cdp_get("/json/version", no_cache=True):
+        return True  # came up meanwhile (e.g. a parallel `cdpilot launch`)
+    out, err = io.StringIO(), io.StringIO()
+    code = 0
+    try:
+        # cmd_launch's progress lines would land in the command's stdout,
+        # which agents parse — keep them out; errors become the failure reason.
+        with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
+            cmd_launch()
+    except SystemExit as e:
+        code = 0 if e.code is None else (e.code if isinstance(e.code, int) else 1)
+    except Exception as e:
+        err.write(f"{type(e).__name__}: {e}")
+        code = 1
+    cdp_cache_invalidate()
+    if code == 0 and cdp_get("/json/version", no_cache=True):
+        print(AUTOLAUNCH_NOTICE, file=sys.stderr)
+        return True
+    reason = err.getvalue().strip() or out.getvalue().strip() or "browser did not answer on the CDP port"
+    _AUTOLAUNCH["failure"] = " / ".join(ln.strip() for ln in reason.splitlines() if ln.strip())
+    return False
+
+
+def _print_autolaunch_failure():
+    if _AUTOLAUNCH["failure"]:
+        print(f"cdpilot: auto-launch failed: {_AUTOLAUNCH['failure']}", file=sys.stderr)
+
+
 def get_tabs():
-    """Retrieve all CDP targets."""
+    """Retrieve all CDP targets, auto-launching the browser once if allowed."""
     result = cdp_get("/json")
+    if result is None and _autolaunch_if_down():
+        result = cdp_get("/json", no_cache=True)
     if result is None:
         print("CDP connection error. Is the browser running?", file=sys.stderr)
+        _print_autolaunch_failure()
         sys.exit(1)
     return result
 
@@ -1627,6 +1814,9 @@ async def navigate_collect(ws_url, url, network=False, console=False, glow=True)
                 "id": 50, "method": "Page.addScriptToEvaluateOnNewDocument",
                 "params": {"source": stealth_source}
             }))
+            # Same session, same lifetime: headless -> drop the HeadlessChrome
+            # token from UA header, navigator and UA-CH brands (regular: never).
+            await apply_headless_ua_override(ws)
 
         # Apply request blocking BEFORE navigate, on this same WS session.
         # Network.setBlockedURLs is session-bound (just like the stealth
@@ -2179,7 +2369,8 @@ def get_headless_config():
 # Tiers, weakest fingerprint footprint -> strongest spoof:
 #   regular    -> inject NOTHING (cleanest, default)
 #   stealth    -> STEALTH_JS_LIGHT (webdriver/chrome.runtime/permissions only)
-#   undetected -> STEALTH_JS_FULL  (light + plugins + WebGL + Worker)
+#                 + headless UA override (HeadlessChrome -> Chrome, UA-CH brands)
+#   undetected -> STEALTH_JS_FULL  (light + plugins + WebGL + Worker) + same UA override
 MODE_TIERS = ('regular', 'stealth', 'undetected')
 DEFAULT_MODE_TIER = 'regular'
 
@@ -2231,6 +2422,187 @@ def stealth_js_for_tier(tier):
     return None
 
 
+# ─── Headless UA override (stealth + undetected tiers only) ───────────────────
+# Headless Chromium says "HeadlessChrome/<v>" in the HTTP User-Agent header AND
+# in navigator.userAgent/appVersion. No JS patch can fix the header, and the
+# token alone fails sannysoft/incolumitas User-Agent + HEADCHR_UA; ua-parser then
+# names the browser "Chrome Headless", which is what fails fpscanner CHR_MEMORY.
+# The stealth tiers therefore send Emulation.setUserAgentOverride on the SAME
+# navigate WS that registers the stealth script (session-bound like it: active
+# for this navigation and its load; it lapses when the WS closes).
+# userAgentMetadata is mandatory: an override without it empties
+# navigator.userAgentData.brands and drops Sec-CH-UA (measured) - a louder tell.
+
+def headless_ua_rewrite(ua):
+    """'... HeadlessChrome/154.0.0.0 ...' -> '... Chrome/154.0.0.0 ...'.
+
+    Pure. A UA without the headless token (headed browser) comes back unchanged,
+    which is also how callers detect that there is nothing to override.
+    """
+    if not isinstance(ua, str) or 'HeadlessChrome' not in ua:
+        return ua
+    return ua.replace('HeadlessChrome', 'Chrome')
+
+
+def headless_brand_rewrite(brands):
+    """UA-CH brand list with 'HeadlessChrome' renamed to 'Google Chrome' (what a
+    headed Chrome reports). Chromium / Brave / GREASE entries are kept as-is."""
+    out = []
+    for b in brands or []:
+        if isinstance(b, dict) and 'brand' in b:
+            name = 'Google Chrome' if b['brand'] == 'HeadlessChrome' else str(b['brand'])
+            out.append({'brand': name, 'version': str(b.get('version', ''))})
+    return out
+
+
+def grease_brand_list(major, brand, full_version=None):
+    """Chromium's GREASEd brand list for a major version (port of
+    components/embedder_support/user_agent_utils.cc). Fallback only, for when
+    the current document is not a secure context and cannot report its own list.
+    Matches real Sec-CH-UA: 120 -> Not_A Brand/8, Chromium, Google Chrome;
+    131 -> Google Chrome, Chromium, Not_A Brand/24; 154 -> Chromium, Brave, Not A(Brand/99.
+    """
+    seed = int(major)
+    chars = [' ', '(', ':', '-', '.', '/', ')', ';', '=', '?', '_']
+    order = [(0, 1, 2), (0, 2, 1), (1, 0, 2), (1, 2, 0), (2, 0, 1), (2, 1, 0)][seed % 6]
+    grease_version = ['8', '99', '24'][seed % 3]
+    if full_version:
+        grease_version += '.0.0.0'
+    version = full_version or str(seed)
+    out = [None, None, None]
+    out[order[0]] = {'brand': 'Not' + chars[seed % 11] + 'A' + chars[(seed + 1) % 11] + 'Brand',
+                     'version': grease_version}
+    out[order[1]] = {'brand': 'Chromium', 'version': version}
+    out[order[2]] = {'brand': brand, 'version': version}
+    return out
+
+
+# Evaluated in the CURRENT document (before navigating) to copy the browser's
+# real UA-CH values. userAgentData exists only in secure contexts; the other
+# fields feed the synthesized fallback.
+UA_HINTS_PROBE_JS = r"""(async () => {
+  var r = {brave: !!navigator.brave, platform: navigator.platform};
+  try {
+    var d = navigator.userAgentData;
+    if (d && d.getHighEntropyValues) {
+      r.hints = await d.getHighEntropyValues(['architecture', 'bitness', 'model',
+        'platformVersion', 'fullVersionList', 'uaFullVersion', 'wow64', 'formFactors']);
+    }
+  } catch (e) {}
+  return JSON.stringify(r);
+})()"""
+
+
+def headless_ua_metadata(probe, version_info):
+    """CDP UserAgentMetadata for the override. Copies the live document's own
+    hints (exact) with HeadlessChrome renamed; synthesizes a Chromium-accurate
+    set only when the current document could not report them."""
+    probe = probe if isinstance(probe, dict) else {}
+    hints = probe.get('hints')
+    if isinstance(hints, dict) and hints.get('brands'):
+        meta = {
+            'brands': headless_brand_rewrite(hints.get('brands')),
+            'fullVersionList': headless_brand_rewrite(hints.get('fullVersionList')),
+            'platform': str(hints.get('platform', '')),
+            'platformVersion': str(hints.get('platformVersion', '')),
+            'architecture': str(hints.get('architecture', '')),
+            'model': str(hints.get('model', '')),
+            'mobile': bool(hints.get('mobile', False)),
+        }
+        if hints.get('uaFullVersion'):
+            meta['fullVersion'] = str(hints['uaFullVersion'])
+        if hints.get('bitness') is not None:
+            meta['bitness'] = str(hints['bitness'])
+        if 'wow64' in hints:
+            meta['wow64'] = bool(hints['wow64'])
+        if isinstance(hints.get('formFactors'), list):
+            meta['formFactors'] = [str(f) for f in hints['formFactors']]
+        return meta
+    # Fallback: insecure current document. Version from Browser.getVersion.
+    product = str((version_info or {}).get('product', ''))
+    ua = str((version_info or {}).get('userAgent', ''))
+    m = _re.search(r'Chrome/(\d+)\.(\d+)\.(\d+)\.(\d+)', product) or \
+        _re.search(r'Chrome/(\d+)\.(\d+)\.(\d+)\.(\d+)', ua)
+    if not m:
+        return None
+    major = m.group(1)
+    if probe.get('brave'):
+        brand, full = 'Brave', major + '.0.0.0'   # Brave reports reduced versions
+    else:
+        brand = 'Microsoft Edge' if 'Edg/' in ua else 'Google Chrome'
+        full = '.'.join(m.groups())
+    nav_platform = str(probe.get('platform', ''))
+    if nav_platform.startswith('Mac') or 'Macintosh' in ua:
+        plat, plat_ver = 'macOS', platform.mac_ver()[0]
+    elif nav_platform.startswith('Win') or 'Windows' in ua:
+        plat, plat_ver = 'Windows', ''
+    else:
+        plat, plat_ver = 'Linux', ''
+    machine = platform.machine().lower()
+    return {
+        'brands': grease_brand_list(major, brand),
+        'fullVersionList': grease_brand_list(major, brand, full),
+        'fullVersion': full,
+        'platform': plat,
+        'platformVersion': plat_ver,
+        'architecture': 'arm' if machine.startswith(('arm', 'aarch')) else 'x86',
+        'bitness': '64' if '64' in machine else '32',
+        'model': '',
+        'mobile': False,
+        'wow64': False,
+    }
+
+
+async def _ws_request(ws, msg_id, method, params=None, timeout=3.0):
+    """Send one CDP command on a raw navigate WS and wait for its reply,
+    skipping interleaved events. Returns the reply message or None on timeout."""
+    await ws.send(json.dumps({"id": msg_id, "method": method, "params": params or {}}))
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        try:
+            raw = await asyncio.wait_for(ws.recv(), timeout=max(0.05, deadline - time.time()))
+        except asyncio.TimeoutError:
+            break
+        msg = json.loads(raw)
+        if msg.get("id") == msg_id:
+            return msg
+    return None
+
+
+async def apply_headless_ua_override(ws, base_id=40):
+    """Stealth/undetected tiers: on this navigate session, stop advertising
+    HeadlessChrome (HTTP header, navigator.userAgent/appVersion, UA-CH brands).
+
+    Headless is detected from the browser itself (Browser.getVersion userAgent
+    carries the HeadlessChrome token); headed browsers get no command at all.
+    Returns the applied UA, or None. Never raises - navigation must proceed.
+    """
+    try:
+        ver = await _ws_request(ws, base_id, "Browser.getVersion")
+        info = (ver or {}).get("result") or {}
+        real_ua = info.get("userAgent", "")
+        new_ua = headless_ua_rewrite(real_ua)
+        if not new_ua or new_ua == real_ua:
+            return None
+        probe = None
+        r = await _ws_request(ws, base_id + 1, "Runtime.evaluate", {
+            "expression": UA_HINTS_PROBE_JS, "returnByValue": True, "awaitPromise": True})
+        try:
+            probe = json.loads(r["result"]["result"]["value"])
+        except Exception:
+            probe = None
+        params = {"userAgent": new_ua}
+        meta = headless_ua_metadata(probe, info)
+        if meta:
+            params["userAgentMetadata"] = meta
+        res = await _ws_request(ws, base_id + 2, "Emulation.setUserAgentOverride", params)
+        if not res or "error" in res:
+            return None
+        return new_ua
+    except Exception:
+        return None
+
+
 def cmd_mode(tier=None):
     """Get or set the three-tier stealth mode (regular | stealth | undetected).
 
@@ -2250,8 +2622,10 @@ def cmd_mode(tier=None):
         current = get_mode_config()
         patch = {
             'regular': 'none (no fingerprint patch — cleanest)',
-            'stealth': 'STEALTH_JS_LIGHT (webdriver, chrome.runtime, permissions)',
-            'undetected': 'STEALTH_JS_FULL (light + plugins + WebGL + Worker)',
+            'stealth': 'STEALTH_JS_LIGHT (webdriver, chrome.runtime, permissions)'
+                       ' + headless UA override',
+            'undetected': 'STEALTH_JS_FULL (light + plugins + WebGL + Worker)'
+                          ' + headless UA override',
         }[current]
         print(f'Mode: {current}')
         print(f'  Injects: {patch}')
@@ -2504,13 +2878,23 @@ def cmd_launch():
         chrome_args.append('--headless=new')
         print('  Mode: headless')
 
-    proc = subprocess.Popen(chrome_args, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE)
+    try:
+        proc = subprocess.Popen(chrome_args, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE)
+    except OSError as e:
+        # Windows' FileNotFoundError ("[WinError 2] The system cannot find the
+        # file specified") does not name the binary; say which one, on every OS,
+        # instead of a traceback.
+        print(f"Cannot start browser {chrome_args[0]!r}: {e.strerror or e}", file=sys.stderr)
+        sys.exit(1)
 
     for _ in range(20):
         time.sleep(0.5)
         if cdp_get('/json/version'):
             if PROJECT_ID:
                 _register_project(PROJECT_ID, CDP_PORT, PROFILE_DIR, pid=proc.pid)
+            # Up and registered: the browser is meant to outlive this command,
+            # so a --timeout expiring later must not kill it as an orphan.
+            _timeout_release_child(proc)
             # Off-screen / minimized placement (opt-in). Keeps the browser
             # HEADED (anti-bot still sees a real GPU-backed window) but parks it
             # out of the way so long bench runs never steal focus or pop in
@@ -2528,7 +2912,16 @@ def cmd_launch():
     sys.exit(1)
 
 
-def cmd_tabs():
+def cmd_tabs(reap=False, max_tabs=1, include_real=False, dry_run=False):
+    if reap:
+        result = _reap_tabs(max_tabs=max_tabs, include_real=include_real,
+                            dry_run=dry_run)
+        verb = "would close" if result.get("dry_run") else "closed"
+        print(f"{verb} {len(result['closed'])} tab(s), kept {result['kept']}"
+              f" (blank {result.get('blank', 0)}, real {result.get('real', 0)})")
+        if result.get("reason"):
+            print(f"  {result['reason']}")
+        return
     tabs = get_tabs()
     pages = [t for t in tabs if t.get("type") == "page"]
     for i, p in enumerate(pages):
@@ -2540,9 +2933,8 @@ def cmd_tabs():
 
 
 async def cmd_go(url):
-    if not cdp_get("/json/version"):
-        cmd_launch()
-
+    # No explicit launch here any more: get_page_ws() -> get_tabs()
+    # auto-launches (quietly, honouring CDPILOT_NO_AUTOLAUNCH).
     ws, page = get_page_ws()
     # Mark this tab as cdpilot-owned so a later `close` knows it can shut it.
     if isinstance(page, dict):
@@ -4394,9 +4786,7 @@ async def cmd_glow(state="on"):
 
 async def cmd_debug(url=None):
     """Full auto-debug: navigate + console + network + perf + screenshot."""
-    if not cdp_get("/json/version"):
-        cmd_launch()
-
+    # get_page_ws() auto-launches the browser if needed (see _autolaunch_if_down).
     ws, page = get_page_ws()
 
     if url is None:
@@ -4527,6 +4917,87 @@ def _is_chrome_internal_url(url):
             or u.startswith("vivaldi://"))
 
 
+def _close_target(target_id):
+    """Close one CDP target. Returns True when the browser accepted it."""
+    try:
+        urllib.request.urlopen(f"{CDP_BASE}/json/close/{target_id}", timeout=2)
+        return True
+    except Exception:
+        return False
+
+
+def _reap_tabs(max_tabs=1, include_real=False, dry_run=False):
+    """Enforce a tab budget on the connected browser.
+
+    A long-lived browser accumulates abandoned tabs: every client that opens a
+    target and exits without closing it leaks one, and nothing collects them.
+    Measured on srv21 2026-08-30 — 513 pages, 506 of them about:blank, 12.7 GB
+    across 529 renderer processes, growing ~6/hour for three days on a box with
+    47 GB total.
+
+    Blank tabs go first: they hold nothing a caller could still want. Pages with
+    a real URL are never touched unless include_real is set, because on a shared
+    browser they may belong to somebody else. The session's own tab and the last
+    remaining page always survive.
+    """
+    tabs = cdp_get("/json", no_cache=True)
+    if not tabs:
+        return {"closed": [], "kept": 0, "reason": "no CDP connection"}
+    pages = [t for t in tabs if t.get("type") == "page"]
+    if len(pages) <= 1:
+        return {"closed": [], "kept": len(pages), "reason": "nothing to reap"}
+
+    session_id = _get_session_window_target_id()
+    real, blank = [], []
+    for t in pages:
+        (blank if _is_chrome_internal_url(t.get("url")) else real).append(t)
+
+    keep_ids = []
+    if session_id and any(t.get("id") == session_id for t in pages):
+        keep_ids.append(session_id)
+    if not include_real:
+        keep_ids += [t["id"] for t in real if t["id"] not in keep_ids]
+    for t in blank:
+        if len(keep_ids) >= max_tabs:
+            break
+        if t["id"] not in keep_ids:
+            keep_ids.append(t["id"])
+    if not keep_ids:  # never leave the browser with zero pages
+        keep_ids.append(pages[0]["id"])
+
+    doomed = [t for t in pages if t["id"] not in keep_ids]
+    closed = []
+    for t in doomed:
+        if dry_run or _close_target(t["id"]):
+            closed.append(t["id"])
+    if closed and not dry_run:
+        cdp_cache_invalidate()
+        owned = _load_owned_tabs()
+        if owned & set(closed):
+            _save_owned_tabs(owned - set(closed))
+    return {"closed": closed, "kept": len(keep_ids),
+            "blank": len(blank), "real": len(real), "dry_run": dry_run}
+
+
+def _enforce_tab_budget():
+    """Opt-in post-command reaping via CDPILOT_MAX_TABS.
+
+    Off unless the variable is set: silently closing tabs would be hostile on a
+    desktop where the browser is also the user's. On an unattended server it is
+    the difference between one tab and five hundred.
+    """
+    raw = os.environ.get("CDPILOT_MAX_TABS", "").strip()
+    if not raw.isdigit() or int(raw) < 1:
+        return
+    try:
+        result = _reap_tabs(max_tabs=int(raw))
+    except Exception:
+        return
+    if result.get("closed"):
+        print(f"[cdpilot] tab budget: closed {len(result['closed'])} idle tab(s)",
+              file=sys.stderr)
+
+
 async def _browser_close_graceful():
     """Ask the browser to shut down gracefully via the CDP Browser.close
     command (cleanest cross-platform path — flushes state, no orphaned procs).
@@ -4927,12 +5398,13 @@ async def cmd_context_create(url='about:blank'):
     The target_id is what CDPILOT_TARGET expects.
     """
     if not cdp_get('/json/version'):
-        cmd_launch()
+        _autolaunch_if_down()
     # Resolve a base WS to talk to the browser itself (not a tab).
     ver = cdp_get('/json/version')
     browser_ws = ver.get('webSocketDebuggerUrl') if ver else None
     if not browser_ws:
         print('Cannot reach browser-level WS', file=sys.stderr)
+        _print_autolaunch_failure()
         sys.exit(1)
     r = await cdp_send(browser_ws, [
         (1, "Target.createBrowserContext", {}),
@@ -5049,6 +5521,8 @@ async def cmd_new_tab(url='about:blank'):
     """Open a new tab."""
     import urllib.parse
     safe_chars = ":/?#[]@!$&'()*+,;="
+    if not cdp_get('/json/version'):
+        _autolaunch_if_down()
     data = cdp_get(f'/json/new?{urllib.parse.quote(url, safe=safe_chars)}')
     cdp_cache_invalidate()
     if data:
@@ -5057,6 +5531,7 @@ async def cmd_new_tab(url='about:blank'):
         print(f'  ID: {data.get("id", "?")}')
     else:
         print('Failed to open tab', file=sys.stderr)
+        _print_autolaunch_failure()
 
 def cmd_switch_tab(index_or_id):
     """Switch to a tab by index number or tab ID."""
@@ -7192,9 +7667,10 @@ async def cmd_press_hold(selector=None):
       cdpilot press-hold              # auto-find the px-captcha target
       cdpilot press-hold "#px-captcha button"
     """
-    if not cdp_get("/json/version"):
+    if not cdp_get("/json/version") and not _autolaunch_if_down():
         print(json.dumps({'solved': False, 'error': 'no_browser',
                           'hint': 'Run: cdpilot launch'}, ensure_ascii=False))
+        _print_autolaunch_failure()
         sys.exit(1)
     ws, _ = get_page_ws()
     res = await _solve_press_and_hold(ws, target_sel=selector)
@@ -7339,8 +7815,9 @@ async def cmd_profile_warm(minutes=None, sites=None):
     if not site_list:
         site_list = WARM_SAFE_SITES
 
-    if not cdp_get("/json/version"):
+    if not cdp_get("/json/version") and not _autolaunch_if_down():
         print(json.dumps({'error': 'no_browser', 'hint': 'Run: cdpilot launch'}, ensure_ascii=False))
+        _print_autolaunch_failure()
         sys.exit(1)
 
     ws, _ = get_page_ws()
@@ -7417,27 +7894,149 @@ async def cmd_profile_dispatch(args: list) -> None:
 # ─── End Captcha Solver Plugin ───────────────────────────────────────────
 
 
-def _stop_browser_on_port(port):
-    """Stop the browser process listening on the given port."""
-    import signal
+def _cdp_browser_close(port):
+    """Send CDP Browser.close to the browser answering /json/version on port.
+
+    Same command the smart close sends, through the same cdp_send. It runs on
+    a worker thread with its own loop, so callers inside a running loop
+    (_browser_close_graceful) work too. True once the command went out.
+    """
     try:
-        result = subprocess.run(
-            ["lsof", "-ti", f":{port}"],
-            capture_output=True, text=True
-        )
-        pids = [p.strip() for p in result.stdout.strip().split("\n") if p.strip()]
-        if pids:
-            for pid in pids:
-                os.kill(int(pid), signal.SIGTERM)
-            return True
-        else:
-            subprocess.run(
-                ["pkill", "-f", f"remote-debugging-port={port}"],
-                capture_output=True, text=True
-            )
-            return True
+        url = f"http://127.0.0.1:{int(port)}/json/version"
+        with urllib.request.urlopen(url, timeout=2) as resp:
+            ws_url = json.loads(resp.read()).get("webSocketDebuggerUrl")
     except Exception:
         return False
+    if not ws_url:
+        return False
+    import threading
+    sent = []
+
+    def _send():
+        try:
+            asyncio.run(cdp_send(ws_url, [(1, "Browser.close", {})], timeout=5))
+            sent.append(True)
+        except SystemExit:
+            pass  # cdp_send exits when it cannot connect at all
+        except Exception as e:
+            # The browser may drop the socket before it answers.
+            if type(e).__name__.startswith("ConnectionClosed"):
+                sent.append(True)
+
+    worker = threading.Thread(target=_send, daemon=True)
+    worker.start()
+    worker.join(8)
+    return bool(sent)
+
+
+def _debug_port_pids(port):
+    """Pids whose command line carries --remote-debugging-port=<port> exactly.
+
+    Port 9222 never matches a 92220 flag. Every probe is bounded: `lsof` hung
+    forever on a Mac with a stale network mount (2026-09-27), so it is gone.
+    """
+    port = int(port)
+    pids = set()
+    try:
+        if os.name == "nt":
+            script = (
+                "Get-CimInstance Win32_Process | Where-Object { $_.ProcessId -ne $PID"
+                " -and $_.CommandLine -match '--remote-debugging-port=%d(?!\\d)' }"
+                " | ForEach-Object { $_.ProcessId }" % port
+            )
+            out = subprocess.run(
+                ["powershell", "-NoProfile", "-NonInteractive", "-Command", script],
+                capture_output=True, text=True, timeout=10).stdout
+        else:
+            out = subprocess.run(
+                ["pgrep", "-f", f"remote-debugging-port={port}( |$)"],
+                capture_output=True, text=True, timeout=5).stdout
+        pids = {int(t) for t in out.split() if t.isdigit()}
+    except (OSError, subprocess.SubprocessError):
+        pass
+    # The registry pid, if alive and its command line has the exact flag
+    # (covers hosts without pgrep). Windows: the CIM query above is complete.
+    for info in _load_registry().values():
+        pid = info.get("pid")
+        if (os.name != "nt" and info.get("port") == port and _pid_alive(pid)
+                and int(pid) not in pids):
+            try:
+                with open(f"/proc/{int(pid)}/cmdline", "rb") as f:
+                    cmd = f.read().replace(b"\0", b" ").decode("utf-8", "replace")
+            except OSError:
+                try:
+                    cmd = subprocess.run(["ps", "-o", "command=", "-p", str(int(pid))],
+                                         capture_output=True, text=True, timeout=5).stdout
+                except (OSError, subprocess.SubprocessError):
+                    cmd = ""
+            if _re.search(rf"--remote-debugging-port={port}(?!\d)", cmd):
+                pids.add(int(pid))
+    pids.discard(os.getpid())
+    return pids
+
+
+def _stop_browser_on_port(port, verbose=False):
+    """Stop cdpilot's browser on `port`; True if one was stopped.
+
+    1. Graceful: CDP Browser.close, then wait up to 5 s for the port to free
+       and up to 10 s more for the browser's processes to exit.
+    2. Otherwise end ONLY the processes whose command line has
+       --remote-debugging-port=<port> exactly: SIGTERM, SIGKILL after 3 s on
+       POSIX; `taskkill /PID <pid> /T /F` on Windows. Never by image name:
+       killing every chrome.exe/brave.exe also took the user's own browser.
+    Every subprocess call has a timeout (a hung `lsof` froze `cdpilot stop`).
+    """
+    port = int(port)
+    closed = _cdp_browser_close(port)
+    deadline = time.time() + 5
+    while closed and time.time() < deadline and not _is_port_free(port):
+        time.sleep(0.1)
+    pids = _debug_port_pids(port)
+    if closed and _is_port_free(port):
+        # The main process outlives its socket while it shuts down (measured
+        # on macOS: 0.5-2 s warm, ~7 s on a fresh profile). Let it exit rather
+        # than signal it, so a following launch does not race its profile lock.
+        deadline = time.time() + 10
+        while pids and time.time() < deadline:
+            time.sleep(0.2)
+            pids = {p for p in pids if _pid_alive(p)}
+        if not pids:
+            if verbose:
+                print("  Closed via CDP Browser.close.")
+            return True
+    if not pids:
+        if closed and verbose:
+            print("  Closed via CDP Browser.close.")
+        return closed
+    if os.name == "nt":
+        for pid in sorted(pids):
+            try:
+                subprocess.run(["taskkill", "/PID", str(pid), "/T", "/F"],
+                               capture_output=True, text=True, timeout=10)
+            except (OSError, subprocess.SubprocessError):
+                pass
+        method = "taskkill"
+    else:
+        import signal
+        for pid in pids:
+            try:
+                os.kill(pid, signal.SIGTERM)
+            except OSError:
+                pass
+        deadline = time.time() + 3
+        while time.time() < deadline and any(_pid_alive(p) for p in pids):
+            time.sleep(0.1)
+        method = "SIGTERM"
+        for pid in pids:
+            if _pid_alive(pid):
+                try:
+                    os.kill(pid, signal.SIGKILL)
+                    method = "SIGTERM+SIGKILL"
+                except OSError:
+                    pass
+    if verbose:
+        print(f"  Stopped via {method}: PID {', '.join(str(p) for p in sorted(pids))}")
+    return True
 
 
 # ─── Browserbase-Compatible Local API ───
@@ -7514,7 +8113,11 @@ def _api_release_session(session_id: str) -> bool:
     if not sess:
         return False
     port = sess.get('port')
-    if port:
+    # In TEST_MODE, _api_create_session never actually launched a browser on
+    # `port` (see the sibling check there) — nothing is listening, so skip
+    # the Browser.close/pgrep round trip entirely instead of paying its cost for a
+    # no-op every time.
+    if port and os.environ.get('CDPILOT_API_TEST_MODE') != '1':
         _stop_browser_on_port(port)
     sess['status'] = 'STOPPED'
     del _api_session_store[session_id]
@@ -7637,48 +8240,12 @@ def cmd_serve(api: bool = False, port: int = 9333):
 
 
 def cmd_stop():
-    """Stop the browser instance managed by cdpilot."""
-    if platform.system() == "Windows":
-        browser_procs = ["brave.exe", "chrome.exe", "chromium.exe"]
-        stopped_any = False
-        for proc in browser_procs:
-            try:
-                result = subprocess.run(
-                    ["taskkill", "/F", "/IM", proc],
-                    capture_output=True, text=True
-                )
-                if result.returncode == 0:
-                    print(f"  {proc} terminated")
-                    stopped_any = True
-            except Exception:
-                pass
-        if stopped_any:
-            print(f"Browser stopped (port {CDP_PORT}).")
-        else:
-            print(f"No browser process found (port {CDP_PORT}).", file=sys.stderr)
-        return
-
-    import signal
-    try:
-        result = subprocess.run(
-            ["lsof", "-ti", f":{CDP_PORT}"],
-            capture_output=True, text=True
-        )
-        pids = [p.strip() for p in result.stdout.strip().split("\n") if p.strip()]
-        if pids:
-            for pid in pids:
-                os.kill(int(pid), signal.SIGTERM)
-                print(f"  PID {pid} terminated")
-            print(f"Browser stopped (port {CDP_PORT}).")
-        else:
-            # lsof bulamazsa pkill ile dene
-            subprocess.run(
-                ["pkill", "-f", f"remote-debugging-port={CDP_PORT}"],
-                capture_output=True, text=True
-            )
-            print(f"Browser stopped (port {CDP_PORT}).")
-    except Exception as e:
-        print(f"Stop error: {e}", file=sys.stderr)
+    """Stop the browser instance managed by cdpilot (only that one: never the
+    user's own Brave/Chrome — see _stop_browser_on_port)."""
+    if _stop_browser_on_port(CDP_PORT, verbose=True):
+        print(f"Browser stopped (port {CDP_PORT}).")
+    else:
+        print(f"No browser process found (port {CDP_PORT}).", file=sys.stderr)
 
     # Update registry
     if PROJECT_ID:
@@ -7790,8 +8357,11 @@ async def _get_element_center(ws_url, selector):
 async def _get_browser_ws():
     """Return the browser-level WebSocket URL (/json/version)."""
     info = cdp_get("/json/version")
+    if not info and _autolaunch_if_down():
+        info = cdp_get("/json/version", no_cache=True)
     if not info:
         print("Error: browser not running (CDP /json/version unreachable).", file=sys.stderr)
+        _print_autolaunch_failure()
         sys.exit(1)
     return info.get("webSocketDebuggerUrl")
 
@@ -11999,13 +12569,8 @@ def _watch_clear_state():
 
 
 def _watch_pid_alive(pid):
-    if not pid:
-        return False
-    try:
-        os.kill(int(pid), 0)
-        return True
-    except (OSError, ValueError):
-        return False
+    # os.kill(pid, 0) terminates the process on Windows — see _pid_alive.
+    return _pid_alive(pid)
 
 
 def _watch_parse_timecode(spec):
@@ -12154,8 +12719,9 @@ async def _watch_daemon_run(url, fps, quality, max_width, retention_s,
     fdir = _watch_frames_dir()
     os.makedirs(fdir, exist_ok=True)
 
-    # Launch browser if needed
-    if not cdp_get("/json/version"):
+    # Launch browser if needed (the daemon is forked by `watch start`, a page
+    # command, so it follows the same CDPILOT_NO_AUTOLAUNCH switch).
+    if not cdp_get("/json/version") and not _autolaunch_disabled():
         cmd_launch()
 
     ws_url, _ = get_page_ws()
@@ -12749,9 +13315,156 @@ def _dispatch_watch_cmd(args):
 # ─── End cdpilot watch namespace ──────────────────────────────────────────────
 
 
+# ─── Global --timeout (issue #2) ───
+# Measured on ~1,225 real agent sessions: 171 had a command hang with no way to
+# bound it. `--timeout <s>` (before or after the command name) or
+# CDPILOT_TIMEOUT caps the whole command's wall-clock. On expiry: one stderr
+# line, exit 124 (GNU `timeout` convention), child processes killed.
+#
+# Mechanism: a daemon watchdog thread that ends the process with os._exit(124).
+#   - SIGALRM does not exist on Windows.
+#   - asyncio.wait_for cannot preempt the blocking sync calls commands make all
+#     over (urllib, time.sleep, subprocess.run), and many commands are sync —
+#     a cooperative timeout would miss exactly the hangs we measured.
+#   - Killing from the Node launcher would miss `python src/cdpilot.py ...`,
+#     MCP tool calls and `run` scripts, which spawn cdpilot.py directly.
+# os._exit from a helper thread ends the process on every OS whatever the main
+# thread is blocked in. Children spawned while the watchdog is armed are
+# tracked and killed first; the browser counts as ours only until it is up and
+# registered (like `cdpilot launch`, it is meant to outlive the command).
+TIMEOUT_ENV = "CDPILOT_TIMEOUT"
+TIMEOUT_EXIT_CODE = 124
+# Long-running servers are not bounded themselves; the value is exported in
+# CDPILOT_TIMEOUT so each per-request child (MCP tool call, API launch) is.
+TIMEOUT_EXEMPT_CMDS = frozenset({'mcp', 'serve'})
+# Commands that parse their own `--timeout` after the command name: that flag
+# is left in their args and wins; the global value is only their default.
+# None exist today — checked when --timeout was added.
+COMMANDS_WITH_OWN_TIMEOUT = frozenset()
+_TIMEOUT_CHILDREN = weakref.WeakSet()
+
+
+def _parse_timeout_seconds(raw, source):
+    """Seconds as float from a --timeout / CDPILOT_TIMEOUT value; 0 = no timeout."""
+    try:
+        val = float(str(raw).strip())
+    except (TypeError, ValueError):
+        raise ValueError(f"{source} expects a number of seconds, got {raw!r}")
+    if val != val or val < 0 or val == float("inf"):
+        raise ValueError(f"{source} expects seconds >= 0, got {raw!r}")
+    return val
+
+
+def _extract_timeout(argv, env=None):
+    """Split the global --timeout flag out of argv (argv excludes the program).
+
+    Accepts `--timeout N` / `--timeout=N` before or after the command name.
+    Returns (seconds, remaining_argv): seconds is None when neither the flag
+    nor CDPILOT_TIMEOUT is set, 0.0 when explicitly disabled. The flag wins
+    over the env var. Raises ValueError on a malformed value.
+    """
+    env = os.environ if env is None else env
+    seconds = None
+    rest = []
+    cmd = None
+    i = 0
+    while i < len(argv):
+        a = argv[i]
+        own = cmd in COMMANDS_WITH_OWN_TIMEOUT
+        if not own and a == "--timeout":
+            if i + 1 >= len(argv):
+                raise ValueError("--timeout expects a number of seconds")
+            seconds = _parse_timeout_seconds(argv[i + 1], "--timeout")
+            i += 2
+            continue
+        if not own and a.startswith("--timeout="):
+            seconds = _parse_timeout_seconds(a.split("=", 1)[1], "--timeout")
+            i += 1
+            continue
+        if cmd is None:
+            cmd = a
+        rest.append(a)
+        i += 1
+    if seconds is None:
+        raw = (env.get(TIMEOUT_ENV) or "").strip()
+        if raw:
+            seconds = _parse_timeout_seconds(raw, TIMEOUT_ENV)
+    return seconds, rest
+
+
+class _TimeoutTrackedPopen(subprocess.Popen):
+    """subprocess.Popen that registers the child for the --timeout watchdog.
+
+    Installed only while a timeout is armed. Detached children (own session,
+    e.g. the `watch` daemon) are meant to outlive cdpilot and are left alone.
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        detached = kwargs.get("start_new_session") or (
+            kwargs.get("creationflags", 0) & getattr(subprocess, "DETACHED_PROCESS", 0))
+        if not detached:
+            _TIMEOUT_CHILDREN.add(self)
+
+
+def _timeout_release_child(proc):
+    """Stop treating proc as a child to kill on timeout (it is meant to live on)."""
+    _TIMEOUT_CHILDREN.discard(proc)
+
+
+def _arm_timeout_watchdog(seconds, cmd):
+    """Start the watchdog: after `seconds`, kill tracked children, exit 124."""
+    subprocess.Popen = _TimeoutTrackedPopen  # subprocess.run() uses it too
+    message = f"cdpilot: timed out after {seconds:g}s ({cmd})\n".encode()
+
+    def _flush_std_streams():
+        for stream in (sys.stdout, sys.stderr):
+            try:
+                stream.flush()
+            except Exception:
+                pass
+
+    def _expire():
+        try:
+            children = list(_TIMEOUT_CHILDREN)
+        except RuntimeError:  # main thread added one mid-copy
+            children = list(_TIMEOUT_CHILDREN)
+        for proc in children:
+            try:
+                if proc.poll() is None:
+                    proc.kill()
+            except Exception:
+                pass
+        # Keep what the command already printed. Flush from a helper thread
+        # with a deadline: the main thread may hold the stdout lock while
+        # blocked on a full pipe, and the timeout must still fire.
+        flusher = threading.Thread(target=_flush_std_streams, daemon=True)
+        flusher.start()
+        flusher.join(0.5)
+        try:
+            os.write(2, message)
+        except OSError:
+            pass
+        os._exit(TIMEOUT_EXIT_CODE)
+
+    timer = threading.Timer(seconds, _expire)
+    timer.daemon = True
+    timer.start()
+    atexit.register(timer.cancel)  # finished in time: never fire during shutdown
+    return timer
+
+
 # ─── CLI ───
 
 if __name__ == "__main__":
+    try:
+        _timeout_s, _argv = _extract_timeout(sys.argv[1:])
+    except ValueError as _e:
+        print(f"cdpilot: {_e}", file=sys.stderr)
+        sys.exit(2)
+    # Downstream code (and anything reading sys.argv) sees argv without it.
+    sys.argv = sys.argv[:1] + _argv
+
     if len(sys.argv) < 2:
         print(__doc__)
         sys.exit(0)
@@ -12768,6 +13481,11 @@ if __name__ == "__main__":
         print(__doc__)
         sys.exit(0)
 
+    # `open <url>` is what agents type when they mean `go` (14 times in ~1,225
+    # measured sessions). `open` has no other meaning here, so alias it.
+    if cmd == 'open':
+        cmd = 'go'
+
     # Hidden re-entrant entry for the watch daemon. `cdpilot watch start`
     # forks this process with the flag so the screencast consumer runs in
     # the background while the foreground process returns immediately.
@@ -12775,9 +13493,23 @@ if __name__ == "__main__":
         _cmd_watch_daemon_entry()
         sys.exit(0)
 
+    _AUTOLAUNCH["cmd"] = cmd
+    if _timeout_s is not None:
+        # Children (MCP tool calls, `run` lines, test steps) inherit the bound.
+        os.environ[TIMEOUT_ENV] = f"{_timeout_s:g}"
+    if _timeout_s and cmd not in TIMEOUT_EXEMPT_CMDS and not (
+            cmd in COMMANDS_WITH_OWN_TIMEOUT
+            and any(a == "--timeout" or a.startswith("--timeout=") for a in args)):
+        _arm_timeout_watchdog(_timeout_s, cmd)
+
     sync_cmds = {
         'launch': cmd_launch,
-        'tabs': cmd_tabs,
+        'tabs': lambda: cmd_tabs(
+            reap='--reap' in args,
+            max_tabs=next((int(a.split('=')[1]) for a in args
+                           if a.startswith('--max=') and a.split('=')[1].isdigit()), 1),
+            include_real='--all' in args,
+            dry_run='--dry-run' in args),
         'extensions': cmd_extensions,
         'stop': cmd_stop,
         'version': cmd_version,
@@ -12857,6 +13589,7 @@ if __name__ == "__main__":
 
     if cmd in sync_cmds:
         sync_cmds[cmd]()
+        _enforce_tab_budget()
         sys.exit(0)
 
     def require_args(n, usage):
@@ -13001,6 +13734,7 @@ if __name__ == "__main__":
         if cmd in NO_CONTROL_CMDS:
             asyncio.run(async_map[cmd]())
             _update_session_timestamp()
+            _enforce_tab_budget()
         else:
             async def _wrapped():
                 ws_url = None
@@ -13021,6 +13755,7 @@ if __name__ == "__main__":
                                 await _control_end(ws_url)
             asyncio.run(_wrapped())
             _update_session_timestamp()
+            _enforce_tab_budget()
     else:
         print(f"Unknown command: {cmd}", file=sys.stderr)
         all_cmds = sorted(set(list(sync_cmds.keys()) + list(async_map.keys())))