cdpilot 0.9.1 → 0.9.2

package/README.md

@@ -124,7 +124,7 @@ See [CHANGELOG.md](CHANGELOG.md) for the full list with rationale.
 ### Navigation & Content
 
 ```bash
-cdpilot go <url>              # Navigate to URL
+cdpilot go <url>              # Navigate to URL (alias: open <url>)
 cdpilot content               # Get page text content
 cdpilot html                  # Get page HTML
 cdpilot shot [file]           # Take screenshot (PNG)
@@ -537,11 +537,26 @@ cdpilot profile warm          # age the profile for reCAPTCHA v3 score
 which nudges reCAPTCHA v3's behavioral score upward over time. Slow by
 design — run it ahead of a session, not inline.
 
-Verified against public bot-detection panels:
-- **bot.sannysoft.com:** 24/24 PASS (WebDriver, Chrome obj, Plugins as PluginArray, WebGL, PHANTOM_*, HEADCHR_*, SELENIUM_DRIVER)
-- **bot.incolumitas.com** intoli: 6/6 OK — new-tests: 6/7 OK (one FAIL = pure CDP presence, cannot be JS-patched)
-- **nowsecure.nl** (Cloudflare full challenge): passed
-- **arh.antoinevastel.com/areyouheadless:** "You are not Chrome headless"
+Public bot-detection panels, measured 2026-09-27, **headless** Brave (Chrome 154)
+([method and raw results](.claude/docs/stealth-panel-olcumu-2026-09-27.md)):
+
+| `mode` | bot.sannysoft.com (31 rows) | incolumitas intoli | incolumitas fpscanner | incolumitas new-tests |
+|---|---|---|---|---|
+| `regular` (no patches, default) | 28 pass / 3 fail | 5/6 | 17 ok / 3 fail / 1 warn | all ok |
+| `stealth` | 31 pass | 6/6 | 19 ok / 1 fail / 1 warn | all ok |
+| `undetected` | 31 pass | 6/6 | 19 ok / 1 fail / 1 warn | all ok |
+
+- The remaining fpscanner fail is `'webdriver' in navigator`, which is true in every modern
+  Chrome; faking it away would make cdpilot the odd one out.
+- `regular`'s fails all come from the `HeadlessChrome` user agent. `stealth`/`undetected`
+  rewrite it for the page load that `go` starts; a later, separate command in the same page
+  can still read `HeadlessChrome`.
+- new-tests: every key is ok; `connectionRTT` is reported as unknown in all tiers.
+- nowsecure.nl and areyouheadless could not be measured (a fixed always-interactive
+  Turnstile test key; HTTP 502).
+
+Earlier figures on this page (sannysoft 24/24, intoli 6/6) were measured on v0.4.x in April
+2026; they are replaced by the table above.
 
 ### Reliability
 
@@ -559,6 +574,32 @@ until cdpilot health >/dev/null; do cdpilot launch; sleep 2; done
 Surfaces today's Brave crash count from `~/Library/Logs/DiagnosticReports/`
 on macOS — spot degradation before your automation silently stalls.
 
+**Auto-launch.** A page command (`go`, `content`, `click`, `shot`, …) that finds
+the browser not running starts it the same way `cdpilot launch` does (same
+profile, same headless/visible setting), then carries on, printing one line to
+stderr: `cdpilot: browser was not running — launched it (CDPILOT_NO_AUTOLAUNCH=1 to disable)`.
+Lifecycle, status and configuration commands (`launch`, `stop`, `close`,
+`close-tab`, `stop-all`, `project-stop`, `session-close`, `status`, `health`,
+`tabs`, `sessions`, `projects`, `headless`, `proxy`, `browser`, `extensions`,
+`mcp`, `serve`, …) never launch. `CDPILOT_NO_AUTOLAUNCH=1` restores the old
+"CDP connection error. Is the browser running?" error and exit code 1.
+
+**Timeouts.** Any command takes `--timeout <seconds>`, before or after the
+command name, or a default from `CDPILOT_TIMEOUT` (the flag wins; `0`
+disables). It bounds the whole command's wall-clock: on expiry cdpilot prints
+`cdpilot: timed out after <N>s (<command>)` to stderr, kills the child processes
+it started and exits with code **124** (like GNU `timeout`). A browser that was
+already up and registered is left running.
+
+```bash
+cdpilot --timeout 10 click "#submit"      # before the command...
+cdpilot shot page.png --timeout 30        # ...or after it
+CDPILOT_TIMEOUT=60 cdpilot run flow.cdp   # default for every command (and each script line)
+```
+
+For `mcp` and `serve` the value is not applied to the long-running server
+itself; it is passed on to every tool call / request it runs.
+
 ### Scaling & Workstation Use
 
 ```bash
@@ -620,6 +661,8 @@ print(result.stdout)
 | `BROWSER_SESSION` | Auto | Session identifier |
 | `CDPILOT_MODE` | `regular` | Stealth tier override (`regular`/`stealth`/`undetected`) |
 | `CDPILOT_OFFSCREEN` | `0` | Headed but render off-screen — no window steals focus |
+| `CDPILOT_TIMEOUT` | unset | Default `--timeout` in seconds for every command (flag wins, `0` disables); expiry exits 124 |
+| `CDPILOT_NO_AUTOLAUNCH` | `0` | `1` = page commands fail with the old "Is the browser running?" error instead of launching the browser |
 
 ## How It Works
 

package/bin/cdpilot.js

@@ -321,7 +321,14 @@ function showHelp() {
   cdpilot v${VERSION} — Zero-dependency browser automation
 
   USAGE
-    cdpilot <command> [args]
+    cdpilot [--timeout <s>] <command> [args]
+
+  GLOBAL OPTIONS
+    --timeout <s>      Abort the command after <s> seconds (exit 124). Before or
+                       after the command; env CDPILOT_TIMEOUT sets a default
+                       (the flag wins, 0 disables).
+    Page commands start the browser if it is not running
+                       (set CDPILOT_NO_AUTOLAUNCH=1 to get an error instead).
 
   SETUP
     setup              Auto-detect browser, create isolated profile
@@ -332,7 +339,7 @@ function showHelp() {
                        if no user tabs remain (--force quits anyway, --keep never quits)
 
   NAVIGATION
-    go <url>           Navigate to URL
+    go <url>           Navigate to URL (alias: open)
     content            Get page text content
     html               Get page HTML
     shot [file]        Take screenshot
@@ -590,8 +597,23 @@ if (process.argv.includes('--internal-test-runner')) {
   return; // runAll() is async, this exits via process.exit
 }
 
+// Global flags may precede the command name (`cdpilot --timeout 10 click "#x"`).
+// src/cdpilot.py parses and validates them (it is also run directly, without
+// this launcher); here they only have to be skipped to find the command that
+// the launcher answers itself (help / --version / setup / status). args are
+// passed to Python unchanged.
+function commandIndex(argv) {
+  let i = 0;
+  while (i < argv.length) {
+    if (argv[i] === '--timeout') { i += 2; continue; }
+    if (argv[i].startsWith('--timeout=')) { i += 1; continue; }
+    break;
+  }
+  return i;
+}
+
 const args = process.argv.slice(2);
-const cmd = args[0];
+const cmd = args[commandIndex(args)];
 
 if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   showHelp();
@@ -650,7 +672,14 @@ if (cmd === 'status') {
     env,
   });
 
-  child.on('close', (code) => {
-    process.exit(code || 0);
+  // A child killed by a signal reports code === null. `code || 0` turned that
+  // into success, so an OOM-killed or SIGKILLed run looked fine to scripts
+  // and agents. Use the shell convention 128 + signal number instead.
+  child.on('close', (code, signal) => {
+    if (code === null && signal) {
+      console.error(`cdpilot: python was terminated by ${signal}`);
+      process.exit(128 + (os.constants.signals[signal] || 0));
+    }
+    process.exit(code ?? 0);
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdpilot",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "mcpName": "io.github.mehmetnadir/cdpilot",
   "description": "Zero-dependency browser automation CLI. Raw CDP, 70+ commands, friction ladder, 3-tier stealth, CAPTCHA + press-and-hold solvers, proxy pools, MCP server. No Puppeteer/Playwright/Selenium.",
   "bin": {

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.1"
+__version__ = "0.9.2"
 
 import asyncio
 import atexit
@@ -36,6 +43,10 @@ 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 ───
@@ -474,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;
     };
@@ -492,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;
@@ -505,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);
@@ -1224,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
 
@@ -1713,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
@@ -2265,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'
 
@@ -2317,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).
 
@@ -2336,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}')
@@ -2590,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
@@ -2635,9 +2933,8 @@ def cmd_tabs(reap=False, max_tabs=1, include_real=False, dry_run=False):
 
 
 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):
@@ -4489,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:
@@ -5103,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", {}),
@@ -5225,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:
@@ -5233,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."""
@@ -7368,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)
@@ -7515,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()
@@ -7593,31 +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:
-        # Bounded: on some hosts/sandboxes `lsof`/`pkill` can hang instead of
-        # erroring (observed while testing the port-registry fix — a stuck
-        # `lsof -ti :<port>` blocked the whole /v1/sessions DELETE request).
-        # A timeout keeps this best-effort call from ever wedging the caller.
-        result = subprocess.run(
-            ["lsof", "-ti", f":{port}"],
-            capture_output=True, text=True, timeout=5
-        )
-        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, timeout=5
-            )
-            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 ───
@@ -7696,7 +8115,7 @@ def _api_release_session(session_id: str) -> bool:
     port = sess.get('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 lsof/pkill round trip entirely instead of paying its cost for a
+    # 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)
@@ -7821,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:
@@ -7974,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")
 
@@ -12333,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()
@@ -12928,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)
@@ -12947,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.
@@ -12954,6 +13493,15 @@ 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': lambda: cmd_tabs(