cdpilot 0.9.4 → 0.9.5

package/src/cdpilot.py

@@ -8,8 +8,8 @@ Chrome DevTools Protocol (CDP). No Puppeteer, no Playwright, no Selenium.
 Usage:
   cdpilot <command> [arguments]
 
-Elements inside iframes (same-origin or cross-origin; nest with >>>):
-  cdpilot click "iframe#card >>> input[name=cardnumber]"   # or --frame <sel|index|url>
+Elements inside iframes and shadow roots (open shadow DOM; nest with >>>):
+  cdpilot click "iframe#card >>> input[name=cardnumber]"   # or --frame <sel> / my-card >>> .inner
 
 WebMCP tools of the page (browser started with `launch --webmcp`):
   cdpilot tools list [--json] | tools call <name> [json | --arg k=v ...]
@@ -38,6 +38,7 @@ Environment:
   CHROME_BIN           Browser binary path (auto-detected if not set)
   CDPILOT_PROFILE      Isolated browser profile directory
   CDPILOT_LOG=0        Do not write the session log
+  CDPILOT_VAR_<NAME>   Value for flow placeholder {{name}} in replay
   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)
@@ -69,6 +70,22 @@ pip install cryptography):
                        (tabs, popups, iframes, workers), until `stop`
   cdpilot bot-auth status      Agent URL, keyid, signer on/off
 
+Network monitoring & HAR export:
+  cdpilot network [url] [--har <file>]
+                       Monitor HTTP requests of navigation. With `--har <file>`,
+                       exports traffic as HAR 1.2 JSON (`--har -` for stdout).
+                       Sensitive header values (Cookie, Authorization, ...) and
+                       secret-named URL parameters are masked. Response bodies
+                       are omitted.
+
+Record & replay:
+  cdpilot record start [--name <n>]        Start recording commands into active session
+  cdpilot record status                    Show active recording status
+  cdpilot record cancel                    Cancel and discard active recording
+  cdpilot record stop [--save <file.json>] Stop recording and emit flow JSON
+  cdpilot replay <file.json> [--var k=v] [--delay real|none|<ms>] [--dry-run] [--continue]
+                       Replay a recorded flow with variable substitution
+
 Exit codes: 0 ok, 1 error (batch / run: a step failed), 124 --timeout;
   exit 3 from click / smart-click (batch / run: one, and no failed step):
   pressed, release missed the target, not clicked (a real mouse click whose
@@ -77,7 +94,7 @@ Exit codes: 0 ok, 1 error (batch / run: a step failed), 124 --timeout;
   "Pressed (the page replaced or left it ...)" and exits 0.
 """
 
-__version__ = "0.9.4"
+__version__ = "0.9.5"
 
 import asyncio
 import atexit
@@ -501,17 +518,157 @@ DEV_EXTENSIONS_FILE = os.path.join(PROFILE_DIR, 'dev-extensions.json')
 # A function declaration pasted INSIDE each command's IIFE, so it stays local:
 # nothing is left on `window` for page scripts (anti-bot checks, often in an
 # iframe) to find. It used to be window.__cdpilot_waitFor.
-WAIT_AND_QUERY_JS = """
+# ─── Shadow DOM & Selector JS Helper ─────────────────────────────────────────
+# Shared JS helper for resolving CSS selectors with Shadow DOM support.
+# 1. Traverses explicit `>>>` chains through open shadow roots.
+# 2. Automatically falls back to depth-first traversal of all open shadow roots
+#    when a plain CSS selector matches nothing at document level.
+_SHADOW_QUERY_JS = r"""
+function __cdpilot_splitHops(sel) {
+  var parts = [], buf = '', quote = null, depth = 0;
+  for (var i = 0; i < sel.length; i++) {
+    var ch = sel[i];
+    if (ch === '\\' && i + 1 < sel.length) {
+      buf += sel.substr(i, 2);
+      i++;
+      continue;
+    }
+    if (quote) {
+      if (ch === quote) quote = null;
+      buf += ch;
+    } else if (ch === '"' || ch === "'") {
+      quote = ch; buf += ch;
+    } else if (ch === '[' || ch === '(') {
+      depth++; buf += ch;
+    } else if (ch === ']' || ch === ')') {
+      depth = Math.max(0, depth - 1); buf += ch;
+    } else if (depth === 0 && sel.substr(i, 3) === '>>>') {
+      parts.push(buf.trim());
+      buf = '';
+      i += 2;
+    } else {
+      buf += ch;
+    }
+  }
+  parts.push(buf.trim());
+  return parts;
+}
+
+function __cdpilot_walkHops(root, hops) {
+  root = root || document;
+  if (!hops || !hops.length) return { el: null, failedHop: null };
+  var curr = root;
+  var failedHop = null;
+  for (var i = 0; i < hops.length; i++) {
+    var seg = hops[i];
+    var el = null;
+    try { el = curr.querySelector(seg); } catch (e) { return { el: null, failedHop: failedHop }; }
+    if (!el) return { el: null, failedHop: failedHop };
+    if (i === hops.length - 1) {
+      if (!el.shadowRoot && !failedHop) failedHop = seg;
+      return { el: el, failedHop: failedHop };
+    }
+    if (el.shadowRoot) {
+      curr = el.shadowRoot;
+    } else {
+      if (!failedHop) failedHop = seg;
+      return { el: null, failedHop: failedHop };
+    }
+  }
+  return { el: null, failedHop: failedHop };
+}
+
+function __cdpilot_deepQuery(root, selector) {
+  var all = [];
+  try { all = root.querySelectorAll('*'); } catch (e) {}
+  for (var i = 0; i < all.length; i++) {
+    var el = all[i];
+    if (el.shadowRoot) {
+      try {
+        var m = el.shadowRoot.querySelector(selector);
+        if (m) return { el: m, host: el };
+      } catch (e) {}
+      var deeper = __cdpilot_deepQuery(el.shadowRoot, selector);
+      if (deeper) return deeper;
+    }
+  }
+  return null;
+}
+
+function __cdpilot_hostDesc(host) {
+  if (!host) return '';
+  var tag = (host.tagName || '').toLowerCase();
+  return host.id ? tag + '#' + host.id : tag;
+}
+
+function __cdpilot_resolveSelector(root, selector, deepFallback) {
+  root = root || document;
+  if (!selector) return null;
+  if (selector.indexOf('>>>') !== -1) {
+    var parts = __cdpilot_splitHops(selector);
+    if (parts.length > 1 && parts.every(function (p) { return p.length > 0; })) {
+      var res = __cdpilot_walkHops(root, parts);
+      if (res && res.el) {
+        return { el: res.el, host: null };
+      }
+      return null;
+    }
+  }
+  var direct = null;
+  try { direct = root.querySelector(selector); } catch (e) {}
+  if (direct) {
+    return { el: direct, host: null };
+  }
+  if (deepFallback !== false && selector.indexOf('>>>') === -1) {
+    var hit = __cdpilot_deepQuery(root, selector);
+    if (hit) return hit;
+  }
+  return null;
+}
+"""
+
+_SHADOW_NOTES_PRINTED = set()
+
+
+def _maybe_print_shadow_note(sel, host_desc):
+    """Print the shadow fallback note at most once per selector in a command run."""
+    if not host_desc:
+        return
+    key = (sel, host_desc)
+    if key not in _SHADOW_NOTES_PRINTED:
+        _SHADOW_NOTES_PRINTED.add(key)
+        print(_shadow_deep_fallback_note(sel, host_desc), file=sys.stderr)
+
+
+WAIT_AND_QUERY_JS = _SHADOW_QUERY_JS + """
 function __cdpilot_waitFor(selector, timeout) {
   return new Promise(function(resolve) {
-    var el = document.querySelector(selector);
-    if (el) { resolve(el); return; }
-    var obs = new MutationObserver(function() {
-      var found = document.querySelector(selector);
-      if (found) { obs.disconnect(); resolve(found); }
-    });
+    var res = __cdpilot_resolveSelector(document, selector, true);
+    if (res && res.el) { resolve(res.el); return; }
+    var obs = null;
+    var timer = null;
+    var timerTimeout = null;
+    function cleanup() {
+      if (obs) { obs.disconnect(); obs = null; }
+      if (timer) { clearInterval(timer); timer = null; }
+      if (timerTimeout) { clearTimeout(timerTimeout); timerTimeout = null; }
+    }
+    function check() {
+      var found = __cdpilot_resolveSelector(document, selector, true);
+      if (found && found.el) {
+        cleanup();
+        resolve(found.el);
+        return true;
+      }
+      return false;
+    }
+    obs = new MutationObserver(check);
     obs.observe(document.documentElement, {childList: true, subtree: true});
-    setTimeout(function() { obs.disconnect(); resolve(null); }, timeout || 5000);
+    timer = setInterval(check, 200);
+    timerTimeout = setTimeout(function() {
+      cleanup();
+      resolve(null);
+    }, timeout || 5000);
   });
 }
 """
@@ -1471,6 +1628,7 @@ AUTOLAUNCH_SKIP_CMDS = frozenset({
     'tabs', 'session', 'sessions', 'projects', 'heal',
     'headless', 'proxy', 'browser', 'extensions', 'ext-install', 'ext-remove',
     'mcp', 'serve', 'log', 'connect', 'disconnect',
+    'record', 'replay',
 })
 # cmd is set by the CLI dispatcher; None (module imported) means never launch.
 _AUTOLAUNCH = {"cmd": None, "attempted": False, "failure": None}
@@ -1579,6 +1737,7 @@ IDLE_POLL_MAX_S = 30.0
 IDLE_PASSIVE_CMDS = frozenset({
     'status', 'health', 'projects', 'version', '--version', '-v',
     'help', '--help', '-h', 'setup', 'connect', 'disconnect',
+    'record', 'replay',
 })
 _IDLE_WARNED = []
 
@@ -2553,17 +2712,23 @@ def _bot_auth_warn_if_stale(port=None, version=_BOT_AUTH_UNSET):
     return False
 
 
-def _cdp_client_pids(port):
+def _cdp_client_pids(port, _run=None):
     """Pids holding a TCP connection TO the CDP port (clients: a cdpilot
     command, `watch`, Playwright, the signer), or None when it cannot be
-    told. Per OS the tool that answers fast: `netstat -anv` on macOS (lsof
-    there scans every process and took >30 s), `ss -tnp` on Linux (lsof as a
-    fallback), `netstat -ano` on Windows."""
+    told. Per OS the tool that answers fast: `netstat -anv` on macOS with a
+    fallback to port-scoped `lsof` (on macOS 26 `netstat -anv` can exit 0
+    with empty stdout under unprivileged parent interpreters; unscoped lsof
+    scanned every process and took >30 s, but port-scoped lsof answers in
+    ~0.1-0.3 s), `ss -tnp` on Linux (lsof as a fallback), `netstat -ano` on
+    Windows."""
     port = int(port)
 
-    def run(argv):
+    def _default_run(argv):
         r = subprocess.run(argv, capture_output=True, text=True, timeout=5)
-        return r.stdout if r.returncode == 0 else None
+        ok = (0, 1) if (argv and argv[0] == "lsof") else (0,)
+        return r.stdout if r.returncode in ok else None
+
+    run = _run or _default_run
 
     try:
         if os.name == "nt":
@@ -2571,36 +2736,43 @@ def _cdp_client_pids(port):
             return None if out is None else _cdp_client_pids_netstat(out, port)
         if sys.platform == "darwin":
             out = run(["netstat", "-anv", "-p", "tcp"])
-            return None if out is None else _cdp_client_pids_bsd_netstat(out, port)
+            res = None if out is None else _cdp_client_pids_bsd_netstat(out, port)
+            if res is not None:
+                return res
+            out = run(["lsof", "-nP", f"-iTCP:{port}", "-sTCP:ESTABLISHED", "-F", "pn"])
+            return None if out is None else _cdp_client_pids_lsof(out, port)
         try:
             out = run(["ss", "-tnp"])
             if out is not None:
                 return _cdp_client_pids_ss(out, port)
         except OSError:
             pass
-        r = subprocess.run(["lsof", "-nP", f"-iTCP:{port}", "-sTCP:ESTABLISHED", "-F", "pn"],
-                           capture_output=True, text=True, timeout=5)
-        if r.returncode not in (0, 1):  # lsof exits 1 when nothing matches
-            return None
-        return _cdp_client_pids_lsof(r.stdout, port)
+        out = run(["lsof", "-nP", f"-iTCP:{port}", "-sTCP:ESTABLISHED", "-F", "pn"])
+        return None if out is None else _cdp_client_pids_lsof(out, port)
     except (OSError, ValueError, subprocess.SubprocessError):
         return None
 
 
 def _cdp_client_pids_bsd_netstat(text, port):
     """Client pids from macOS `netstat -anv -p tcp`: foreign address
-    `<ip>.<port>`, the owner in the `process:pid` column."""
+    `<ip>.<port>`, the owner in the `process:pid` column. An empty or
+    header-only table returns None (unknown), not an empty set."""
     pids = set()
+    has_rows = False
     for line in (text or "").splitlines():
         parts = line.split()
-        if len(parts) < 6 or not parts[0].startswith("tcp") or parts[5] != "ESTABLISHED":
+        if not parts:
+            continue
+        if parts[0].lower().startswith("tcp"):
+            has_rows = True
+        if len(parts) < 6 or not parts[0].lower().startswith("tcp") or parts[5] != "ESTABLISHED":
             continue
         if parts[4].rsplit(".", 1)[-1] != str(port):
             continue
         m = _re.search(r"\S:(\d+)(?=\s|$)", " ".join(parts[6:]))
         if m and int(m.group(1)) > 0:
             pids.add(int(m.group(1)))
-    return pids
+    return pids if has_rows else None
 
 
 def _cdp_client_pids_ss(text, port):
@@ -3936,6 +4108,44 @@ def _frame_selector_hops(target):
     return parts[:-1], parts[-1]
 
 
+def _frame_fallback_note(hop):
+    """Stderr note when a >>> first hop matches no iframe or shadow host."""
+    return f"note: '{hop}' matched no iframe or shadow host; used the selector as written"
+
+
+def _shadow_closed_error(hop):
+    """Error message when a >>> hop matches an element with a closed shadow root."""
+    return f"'{hop}' has a closed shadow root; cdpilot cannot reach inside it"
+
+
+def _shadow_deep_fallback_note(sel, host_desc):
+    """Stderr note when a selector is resolved via deep shadow-piercing fallback."""
+    return f"note: '{sel}' found inside the shadow root of {host_desc}"
+
+
+def _classify_hop(node_info):
+    """Classify a probed hop target into: 'frame', 'shadow_open', 'shadow_closed', or 'none'.
+
+    Pure.
+    """
+    if not node_info or not node_info.get("found", True):
+        return "none"
+    if node_info.get("frameId"):
+        return "frame"
+    shadow_roots = node_info.get("shadowRoots") or []
+    has_open = False
+    for sr in shadow_roots:
+        if isinstance(sr, dict):
+            st = sr.get("shadowRootType")
+            if st == "closed":
+                return "shadow_closed"
+            if st == "open":
+                has_open = True
+    if has_open:
+        return "shadow_open"
+    return "none"
+
+
 def _frame_selector_plan(target, first_hop_is_frame, kind="css"):
     """How an element command reads `target` once its first hop was probed.
 
@@ -3949,8 +4159,12 @@ def _frame_selector_plan(target, first_hop_is_frame, kind="css"):
     if cand is None:
         return [], target, None
     names, inner = cand
-    if not first_hop_is_frame:
-        return [], target, f"note: '{names[0]}' matched no iframe; used the selector as written"
+    if first_hop_is_frame in ("shadow_closed", "closed"):
+        raise _FrameError(_shadow_closed_error(names[0]))
+    if first_hop_is_frame in ("shadow_open", "shadow"):
+        return [], target, None
+    if not first_hop_is_frame or first_hop_is_frame == "none":
+        return [], target, _frame_fallback_note(names[0])
     return [_parse_frame_hop(n, implicit=True) for n in names], inner, None
 
 
@@ -4493,12 +4707,76 @@ async def _frame_route_rewrite(route, commands):
     return out
 
 
+async def _probe_route_hop(route, hop):
+    """Probe whether `hop` in `route` is an iframe, an open shadow host, closed, or neither.
+
+    Returns (kind, oid, node_info):
+      kind: 'frame', 'shadow_open', 'shadow_closed', or 'none'.
+    """
+    args = f"{json.dumps(hop['kind'])}, {json.dumps(hop['value'])}"
+    # 1. First see if _FRAME_OWNER_JS matches an iframe (same-process or out-of-process)
+    r1 = await _frame_cdp(route, [(1, "Runtime.evaluate",
+                                   route.eval_params(f"({_FRAME_OWNER_JS})({args}, false)", by_value=False),
+                                   route.session_id)])
+    oid1 = r1.get(1, {}).get("result", {}).get("objectId")
+    if oid1:
+        d = await _frame_cdp(route, [(2, "DOM.describeNode", {"objectId": oid1}, route.session_id)])
+        node = d.get(2, {}).get("node", {})
+        if node.get("frameId"):
+            return "frame", oid1, node
+
+    # 2. Not an iframe: query the element itself in the current context
+    r2 = await _frame_cdp(route, [(3, "Runtime.evaluate",
+                                   route.eval_params(f"""(function () {{
+                                     try {{ return document.querySelector({json.dumps(hop['value'])}); }} catch (e) {{ return null; }}
+                                   }})()""", by_value=False),
+                                   route.session_id)])
+    oid2 = r2.get(3, {}).get("result", {}).get("objectId")
+    if not oid2:
+        return "none", None, {"found": False}
+
+    d2 = await _frame_cdp(route, [
+        (4, "DOM.describeNode", {"objectId": oid2, "depth": 1, "pierce": True}, route.session_id)
+    ])
+    node2 = d2.get(4, {}).get("node", {})
+    classification = _classify_hop(node2)
+    return classification, oid2, node2
+
+
+async def _check_chain_closed_shadow(route, names):
+    """Check if any subsequent hop in names has a closed shadow root."""
+    if len(names) <= 1:
+        return
+    chk_closed_js = f"""(function () {{
+      {_SHADOW_QUERY_JS}
+      var res = __cdpilot_walkHops(document, {json.dumps(names)});
+      return res ? res.failedHop : null;
+    }})()"""
+    r_chk = await _frame_cdp(route, [(1, "Runtime.evaluate", route.eval_params(chk_closed_js, by_value=True), route.session_id)])
+    failed_hop = r_chk.get(1, {}).get("result", {}).get("value")
+    if failed_hop:
+        idx = names.index(failed_hop) if failed_hop in names else len(names) - 1
+        sub_hops = names[:idx + 1]
+        get_node_js = f"""(function() {{
+          {_SHADOW_QUERY_JS}
+          var res = __cdpilot_walkHops(document, {json.dumps(sub_hops)});
+          return res ? res.el : null;
+        }})()"""
+        r_nd = await _frame_cdp(route, [(2, "Runtime.evaluate", route.eval_params(get_node_js, by_value=False), route.session_id)])
+        failed_oid = r_nd.get(2, {}).get("result", {}).get("objectId")
+        if failed_oid:
+            d_nd = await _frame_cdp(route, [(3, "DOM.describeNode", {"objectId": failed_oid, "depth": 1, "pierce": True}, route.session_id)])
+            node_d = d_nd.get(3, {}).get("node", {})
+            if _classify_hop(node_d) == "shadow_closed":
+                raise _FrameError(_shadow_closed_error(failed_hop))
+
+
 async def _frame_resolve_target(ws_url, flag_hops, target, kind="css"):
     """Route for one element command: (route or None, selector, note).
 
     `--frame` hops are strict. A `>>>` chain in `target` is used only when its
-    first hop is an iframe (or wraps one) and, for smart-* text, reads as a
-    selector; otherwise `target` stays a plain selector / text with no
+    first hop is an iframe (or wraps one) or an open shadow host and, for smart-*
+    text, reads as a selector; otherwise `target` stays a plain selector / text with no
     routing (None) and `note` explains, if needed.
     """
     route = _FrameRoute(ws_url)
@@ -4507,13 +4785,47 @@ async def _frame_resolve_target(ws_url, flag_hops, target, kind="css"):
         for hop in flag_hops:
             await _frame_route_push(route, hop)
         cand = _frame_chain_candidate(target, kind)
-        found = False
-        if cand is not None:
-            first = _parse_frame_hop(cand[0][0], implicit=True)
-            found = await _frame_route_push(route, first, missing_ok=True)
-        hops, selector, note = _frame_selector_plan(target, found, kind)
-        for hop in hops[1:]:
-            await _frame_route_push(route, hop)
+        if cand is None:
+            if not route.chain:
+                await _frame_route_close(route)
+                return None, target, None
+            return route, target, None
+
+        names, inner = cand
+        first = _parse_frame_hop(names[0], implicit=True)
+        first_kind, first_oid, _ = await _probe_route_hop(route, first)
+        plan_hops, plan_target, note = _frame_selector_plan(target, first_kind, kind)
+        if not first_kind or first_kind == "none":
+            if not route.chain:
+                await _frame_route_close(route)
+                return None, plan_target, note
+            return route, plan_target, note
+        if first_kind in ("shadow_open", "shadow"):
+            await _check_chain_closed_shadow(route, names)
+            if not route.chain:
+                await _frame_route_close(route)
+                return None, plan_target, None
+            return route, plan_target, None
+
+        # First hop is an iframe: enter it
+        await _frame_route_push(route, plan_hops[0])
+        for i, hop_name in enumerate(names[1:], 1):
+            next_hop = plan_hops[i]
+            hop_kind, _, _ = await _probe_route_hop(route, next_hop)
+            if hop_kind == "shadow_closed":
+                raise _FrameError(_shadow_closed_error(hop_name))
+            if hop_kind == "frame":
+                await _frame_route_push(route, next_hop)
+            elif hop_kind == "shadow_open":
+                await _check_chain_closed_shadow(route, names[i:])
+                rem_selector = " >>> ".join(names[i:] + [inner])
+                return route, rem_selector, None
+            else:
+                frames = await _frame_list(route)
+                avail = "; ".join(f"[{f['index']}] {f['id'] or f['name'] or f['src'][:60]}" for f in frames)
+                raise _FrameError(f"no iframe matches '{hop_name}' in {route.describe()}"
+                                  + (f" (frames: {avail})" if avail else " (it has no iframes)"))
+        return route, inner, None
     except _FrameError as e:
         await _frame_route_close(route)
         print(f"Error: {e}", file=sys.stderr)
@@ -4521,10 +4833,6 @@ async def _frame_resolve_target(ws_url, flag_hops, target, kind="css"):
     except BaseException:
         await _frame_route_close(route)
         raise
-    if not route.chain:
-        await _frame_route_close(route)
-        return None, selector, note
-    return route, selector, note
 
 
 def _frame_aware(kind="css"):
@@ -5224,10 +5532,91 @@ async def _smart_act_real(route, expr, label):
         await _frame_cdp(route, [(9, "Runtime.releaseObjectGroup", {"objectGroup": g}, sid)])
 
 
-async def navigate_collect(ws_url, url, network=False, console=False, glow=True):
+def _process_har_event(data, har_records, har_active, har_page_events):
+    method = data.get("method", "")
+    params = data.get("params", {})
+    req_id = params.get("requestId")
+
+    if method == "Network.requestWillBeSent":
+        if req_id and req_id in har_active:
+            prev = har_active[req_id]
+            if "redirectResponse" in params and not prev.get("responseReceived"):
+                prev["responseReceived"] = params["redirectResponse"]
+        req_data = params.get("request", {})
+        post_data = req_data.get("postData")
+        rec = {
+            "requestId": req_id,
+            "requestWillBeSent": {
+                "url": req_data.get("url", ""),
+                "method": req_data.get("method", "GET"),
+                "headers": req_data.get("headers", {}),
+                "hasPostData": req_data.get("hasPostData", bool(post_data)),
+                "postDataLength": len(post_data.encode("utf-8")) if isinstance(post_data, str) else (len(post_data) if post_data else 0),
+                "wallTime": params.get("wallTime"),
+                "timestamp": params.get("timestamp"),
+                "initiator": params.get("initiator", {}),
+                "type": params.get("type", ""),
+            },
+        }
+        har_records.append(rec)
+        if req_id:
+            har_active[req_id] = rec
+
+    elif method == "Network.responseReceived":
+        resp_data = params.get("response", {})
+        rec = har_active.get(req_id)
+        if not rec:
+            rec = {"requestId": req_id}
+            har_records.append(rec)
+            if req_id:
+                har_active[req_id] = rec
+        rec["responseReceived"] = {
+            "status": resp_data.get("status"),
+            "statusText": resp_data.get("statusText", ""),
+            "headers": resp_data.get("headers", {}),
+            "mimeType": resp_data.get("mimeType", ""),
+            "timing": resp_data.get("timing"),
+            "remoteIPAddress": resp_data.get("remoteIPAddress", ""),
+            "remotePort": resp_data.get("remotePort"),
+            "protocol": resp_data.get("protocol", ""),
+            "fromDiskCache": resp_data.get("fromDiskCache", False),
+            "fromServiceWorker": resp_data.get("fromServiceWorker", False),
+            "type": params.get("type", ""),
+        }
+
+    elif method == "Network.loadingFinished":
+        rec = har_active.get(req_id)
+        if rec:
+            rec["loadingFinished"] = {
+                "encodedDataLength": params.get("encodedDataLength", 0),
+                "timestamp": params.get("timestamp"),
+            }
+
+    elif method == "Network.loadingFailed":
+        rec = har_active.get(req_id)
+        if rec:
+            rec["loadingFailed"] = {
+                "errorText": params.get("errorText", ""),
+                "canceled": params.get("canceled", False),
+                "timestamp": params.get("timestamp"),
+            }
+
+    elif method == "Page.domContentEventFired":
+        har_page_events["domContentEventFired"] = params.get("timestamp")
+
+    elif method == "Page.loadEventFired":
+        har_page_events["loadEventFired"] = params.get("timestamp")
+
+
+async def navigate_collect(ws_url, url, network=False, console=False, glow=True, har=False):
     """Navigate to a page and optionally collect network/console events."""
     import websockets
     events = {"network": [], "console": []}
+    har_records = []
+    har_active = {}
+    har_page_events = {}
+    if har:
+        events["har"] = {"records": har_records, "page_events": har_page_events}
 
     async with websockets.connect(ws_url, max_size=100 * 1024 * 1024) as ws:
         # Enable CDP domains
@@ -5289,6 +5678,9 @@ async def navigate_collect(ws_url, url, network=False, console=False, glow=True)
                 data = json.loads(resp)
                 method = data.get("method", "")
 
+                if har:
+                    _process_har_event(data, har_records, har_active, har_page_events)
+
                 if network and method == "Network.responseReceived":
                     r = data["params"]["response"]
                     events["network"].append({
@@ -5377,6 +5769,8 @@ async def navigate_collect(ws_url, url, network=False, console=False, glow=True)
                 resp = await asyncio.wait_for(ws.recv(), timeout=5)
                 data = json.loads(resp)
                 m = data.get("method", "")
+                if har:
+                    _process_har_event(data, har_records, har_active, har_page_events)
                 if network and m == "Network.responseReceived":
                     r = data["params"]["response"]
                     events["network"].append({
@@ -6811,6 +7205,7 @@ def cmd_launch(auto=False, idle_close=None):
             'IPFSCompanion', 'Translate', 'OptimizationGuideModelDownloading',
             'InterestFeedContentSuggestions', 'CalculateNativeWinOcclusion',
             'PasswordManagerOnboarding', 'AutofillServerCommunication',
+            'MacAppCodeSignClone',
         ]),
         # Anti-bot leak fix (2026-05-31): Chrome's blink runtime exposes an
         # "automation controlled" flag when --remote-debugging-port is set;
@@ -7186,17 +7581,21 @@ async def cmd_shot(output=None, quality=None, element=None, fmt=None):
         safe_sel = json.dumps(element)
         js = f"""
         (function() {{
-          var el = document.querySelector({safe_sel});
-          if (!el) return null;
+          {_SHADOW_QUERY_JS}
+          var res = __cdpilot_resolveSelector(document, {safe_sel}, true);
+          if (!res || !res.el) return null;
+          var el = res.el;
           el.scrollIntoView({{block: 'center'}});
           var r = el.getBoundingClientRect();
-          return JSON.stringify({{x: r.x, y: r.y, width: r.width, height: r.height}});
+          return JSON.stringify({{x: r.x, y: r.y, width: r.width, height: r.height, shadowHost: res.host ? __cdpilot_hostDesc(res.host) : null}});
         }})()
         """
         cr = await cdp_send(ws, [(2, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
         rect_str = cr.get(2, {}).get("result", {}).get("value")
         if rect_str:
             rect = json.loads(rect_str)
+            if rect.get("shadowHost"):
+                _maybe_print_shadow_note(element, rect["shadowHost"])
             params["clip"] = {
                 "x": rect["x"], "y": rect["y"],
                 "width": rect["width"], "height": rect["height"],
@@ -7407,6 +7806,22 @@ async def _resolve_selector_ladder(ws_url, inp, strategies=None):
             if r.get(1, {}).get("result", {}).get("value"):
                 tried.append({"strategy": "css", "hit": True, "selector": inp})
                 return inp, tried
+            js_shadow = f"""(function(){{
+{_SHADOW_QUERY_JS}
+var res = __cdpilot_resolveSelector(document, {json.dumps(inp)}, true);
+if (res && res.el) {{
+  return {{ hit: true, shadowHost: res.host ? __cdpilot_hostDesc(res.host) : null }};
+}}
+return {{ hit: false }};
+}})()"""
+            r2 = await cdp_send(ws_url, [(1, "Runtime.evaluate", {
+                "expression": js_shadow, "returnByValue": True})])
+            val = r2.get(1, {}).get("result", {}).get("value") or {}
+            if val.get("hit"):
+                if val.get("shadowHost"):
+                    _maybe_print_shadow_note(inp, val["shadowHost"])
+                tried.append({"strategy": "css", "hit": True, "selector": inp})
+                return inp, tried
             tried.append({"strategy": "css", "hit": False})
             continue
 
@@ -8054,7 +8469,9 @@ async def cmd_submit(selector="form", ladder=None, no_heal=False):
         _log_heal("submit", selector, tried, dur, no_heal)
     safe_sel = json.dumps(res_sel)
     js = f"""(function() {{
-        const form = document.querySelector({safe_sel});
+        {_SHADOW_QUERY_JS}
+        const resolved = __cdpilot_resolveSelector(document, {safe_sel}, true);
+        const form = resolved ? resolved.el : null;
         if (!form) return 'Form not found: ' + {safe_sel};
         const btn = form.querySelector('button[type=submit], input[type=submit], button:last-of-type');
         var res;
@@ -8070,18 +8487,51 @@ async def cmd_submit(selector="form", ladder=None, no_heal=False):
 async def cmd_wait(selector, timeout=5):
     ws, _ = get_page_ws()
     safe_sel = json.dumps(selector)
-    js = f"""new Promise((resolve) => {{
-        const el = document.querySelector({safe_sel});
-        if (el) return resolve('Found: ' + el.tagName + ' ' + (el.textContent||'').substring(0,60).trim());
-        const obs = new MutationObserver(() => {{
-            const el = document.querySelector({safe_sel});
-            if (el) {{ obs.disconnect(); resolve('Found: ' + el.tagName + ' ' + (el.textContent||'').substring(0,60).trim()); }}
+    js = f"""(function() {{
+        {_SHADOW_QUERY_JS}
+        return new Promise((resolve) => {{
+            const res = __cdpilot_resolveSelector(document, {safe_sel}, true);
+            if (res && res.el) {{
+                const el = res.el;
+                const hostDesc = res.host ? __cdpilot_hostDesc(res.host) : null;
+                return resolve({{ out: 'Found: ' + el.tagName + ' ' + (el.textContent||'').substring(0,60).trim(), shadowHost: hostDesc }});
+            }}
+            let obs = null;
+            let timer = null;
+            let timerTimeout = null;
+            function cleanup() {{
+                if (obs) {{ obs.disconnect(); obs = null; }}
+                if (timer) {{ clearInterval(timer); timer = null; }}
+                if (timerTimeout) {{ clearTimeout(timerTimeout); timerTimeout = null; }}
+            }}
+            function check() {{
+                const found = __cdpilot_resolveSelector(document, {safe_sel}, true);
+                if (found && found.el) {{
+                    cleanup();
+                    const el = found.el;
+                    const hostDesc = found.host ? __cdpilot_hostDesc(found.host) : null;
+                    resolve({{ out: 'Found: ' + el.tagName + ' ' + (el.textContent||'').substring(0,60).trim(), shadowHost: hostDesc }});
+                    return true;
+                }}
+                return false;
+            }}
+            obs = new MutationObserver(check);
+            obs.observe(document.documentElement || document.body, {{childList:true, subtree:true}});
+            timer = setInterval(check, 200);
+            timerTimeout = setTimeout(() => {{
+                cleanup();
+                resolve({{ out: 'Timeout: ' + {safe_sel} + ' not found ({timeout}s)' }});
+            }}, {int(timeout)*1000});
         }});
-        obs.observe(document.body, {{childList:true, subtree:true}});
-        setTimeout(() => {{ obs.disconnect(); resolve('Timeout: ' + {safe_sel} + ' not found ({timeout}s)'); }}, {int(timeout)*1000});
-    }})"""
+    }})()"""
     r = await cdp_send(ws, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True, "awaitPromise": True})])
-    print(r.get(1, {}).get("result", {}).get("value", "?"))
+    val = r.get(1, {}).get("result", {}).get("value")
+    if isinstance(val, dict):
+        if val.get("shadowHost"):
+            _maybe_print_shadow_note(selector, val["shadowHost"])
+        print(val.get("out", "?"))
+    else:
+        print(val or "?")
 
 
 async def cmd_batch():
@@ -8145,11 +8595,309 @@ async def cmd_batch():
         sys.exit(CLICK_MISSED_EXIT_CODE)
 
 
-async def cmd_network(url=None):
+def _har_usage_exit():
+    print("Usage: cdpilot network [url] [--har <file>]\ncdpilot: --har needs a value", file=sys.stderr)
+    sys.exit(2)
+
+
+def _atomic_write_har(path, har_dict):
+    """Write HAR dict to path atomically (tmp file in target directory + os.replace)."""
+    target_path = os.path.abspath(path)
+    target_dir = os.path.dirname(target_path) or "."
+    os.makedirs(target_dir, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(prefix=".har-", suffix=".tmp", dir=target_dir)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(har_dict, f, indent=2, ensure_ascii=False)
+            f.write("\n")
+        os.replace(tmp, target_path)
+    except BaseException:
+        try:
+            os.remove(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def _har_from_events(events, page=None, creator_version=None):
+    """Pure builder: converts HAR records and page events into a HAR 1.2 dict."""
+    import urllib.parse
+    import datetime
+
+    records = []
+    page_events = {}
+
+    if isinstance(events, dict):
+        if "har" in events and isinstance(events["har"], dict):
+            h = events["har"]
+            records = h.get("records") or []
+            page_events = h.get("page_events") or {}
+        elif "records" in events:
+            records = events.get("records") or []
+            page_events = events.get("page_events") or {}
+
+    def _format_http_version(protocol):
+        if not protocol:
+            return "HTTP/1.1"
+        p = str(protocol).lower().strip()
+        if p.startswith("h2"):
+            return "HTTP/2"
+        if p.startswith("h3"):
+            return "HTTP/3"
+        if p == "http/1.1":
+            return "HTTP/1.1"
+        if p == "http/1.0":
+            return "HTTP/1.0"
+        return str(protocol).upper()
+
+    def _mask_headers(hdr_dict):
+        """Secret-named headers are masked whole; URL-bearing values of the
+        others (Location, Referer, Link, Refresh) get their secret query
+        parameters masked, like the session log does."""
+        out = []
+        if isinstance(hdr_dict, dict):
+            for k, v in hdr_dict.items():
+                val = "«masked»" if _SLOG_SECRET_NAME_RE.search(str(k)) else _slog_mask_urls(str(v))
+                out.append({"name": str(k), "value": val})
+        elif isinstance(hdr_dict, list):
+            for item in hdr_dict:
+                if isinstance(item, dict) and "name" in item and "value" in item:
+                    k = item["name"]
+                    v = item["value"]
+                    val = "«masked»" if _SLOG_SECRET_NAME_RE.search(str(k)) else _slog_mask_urls(str(v))
+                    out.append({"name": str(k), "value": val})
+        return out
+
+    first_wall = None
+    first_ts = None
+    for rec in records:
+        req_sent = rec.get("requestWillBeSent") or {}
+        w = req_sent.get("wallTime")
+        t = req_sent.get("timestamp")
+        if w is not None and t is not None:
+            first_wall = w
+            first_ts = t
+            break
+
+    entries = []
+    for rec in records:
+        req_sent = rec.get("requestWillBeSent", {})
+        resp_rec = rec.get("responseReceived", {})
+        load_fin = rec.get("loadingFinished")
+        load_fail = rec.get("loadingFailed")
+
+        wall_time = req_sent.get("wallTime")
+        start_ts = req_sent.get("timestamp")
+
+        derived_wall = None
+        missing_wall = False
+        if wall_time is not None:
+            derived_wall = wall_time
+        elif first_wall is not None and first_ts is not None and start_ts is not None:
+            derived_wall = first_wall + (start_ts - first_ts)
+        else:
+            missing_wall = True
+
+        if derived_wall is not None:
+            dt = datetime.datetime.fromtimestamp(derived_wall, tz=datetime.timezone.utc)
+            started_dt = dt.strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
+        else:
+            started_dt = "1970-01-01T00:00:00.000Z"
+
+        if load_fin and "timestamp" in load_fin and start_ts is not None:
+            entry_time = round((load_fin["timestamp"] - start_ts) * 1000, 2)
+            if entry_time < 0:
+                entry_time = -1
+        else:
+            entry_time = -1
+
+        url = _slog_mask_url(req_sent.get("url", ""))
+        method = req_sent.get("method", "GET")
+        protocol = resp_rec.get("protocol", "")
+        http_ver = _format_http_version(protocol)
+        req_headers = _mask_headers(req_sent.get("headers", {}))
+
+        parsed_url = urllib.parse.urlparse(url)
+        qsl = urllib.parse.parse_qsl(parsed_url.query, keep_blank_values=True)
+        query_string = [{"name": k, "value": v} for k, v in qsl]
+
+        body_size = req_sent.get("postDataLength", 0) or 0
+
+        status = resp_rec.get("status", 0) if resp_rec else 0
+        status_text = resp_rec.get("statusText", "") if resp_rec else ""
+        resp_headers = _mask_headers(resp_rec.get("headers", {})) if resp_rec else []
+        mime_type = resp_rec.get("mimeType", "") if resp_rec else ""
+        enc_length = load_fin.get("encodedDataLength", 0) if load_fin else 0
+
+        redirect_url = ""
+        if resp_rec and "headers" in resp_rec:
+            hdrs = resp_rec["headers"]
+            if isinstance(hdrs, dict):
+                for hk, hv in hdrs.items():
+                    if hk.lower() == "location":
+                        redirect_url = _slog_mask_url(str(hv))
+                        break
+            elif isinstance(hdrs, list):
+                for hitem in hdrs:
+                    if isinstance(hitem, dict) and str(hitem.get("name", "")).lower() == "location":
+                        redirect_url = _slog_mask_url(str(hitem.get("value", "")))
+                        break
+
+        timing = resp_rec.get("timing") if resp_rec else None
+        if timing:
+            def _tdiff(end_k, start_k):
+                s = timing.get(start_k)
+                e = timing.get(end_k)
+                if s is not None and e is not None and s != -1 and e != -1 and e >= s:
+                    return round(float(e - s), 2)
+                return -1
+
+            dns = _tdiff("dnsEnd", "dnsStart")
+            connect = _tdiff("connectEnd", "connectStart")
+            ssl = _tdiff("sslEnd", "sslStart")
+            send = _tdiff("sendEnd", "sendStart")
+            wait = _tdiff("receiveHeadersEnd", "sendEnd")
+
+            receive = -1
+            rec_headers_end = timing.get("receiveHeadersEnd")
+            req_time = timing.get("requestTime")
+            if req_time is None and start_ts is not None:
+                req_time = start_ts
+            fin_ts = load_fin.get("timestamp") if load_fin else None
+            if rec_headers_end is not None and rec_headers_end != -1 and req_time is not None and fin_ts is not None:
+                total_ms = (fin_ts - req_time) * 1000
+                if total_ms >= rec_headers_end:
+                    receive = round(float(total_ms - rec_headers_end), 2)
+
+            entry_timings = {
+                "blocked": -1,
+                "dns": dns,
+                "connect": connect,
+                "ssl": ssl,
+                "send": send,
+                "wait": wait,
+                "receive": receive,
+            }
+        else:
+            entry_timings = {
+                "blocked": -1,
+                "dns": -1,
+                "connect": -1,
+                "ssl": -1,
+                "send": -1,
+                "wait": -1,
+                "receive": -1,
+            }
+
+        entry = {
+            "pageref": "page_1",
+            "startedDateTime": started_dt,
+            "time": entry_time,
+            "request": {
+                "method": method,
+                "url": url,
+                "httpVersion": http_ver,
+                "headers": req_headers,
+                "queryString": query_string,
+                "cookies": [],
+                "headersSize": -1,
+                "bodySize": body_size,
+            },
+            "response": {
+                "status": status,
+                "statusText": status_text,
+                "httpVersion": http_ver,
+                "headers": resp_headers,
+                "cookies": [],
+                "content": {
+                    "size": enc_length,
+                    "mimeType": mime_type,
+                },
+                "redirectURL": redirect_url,
+                "headersSize": -1,
+                "bodySize": -1,
+            },
+            "cache": {},
+            "timings": entry_timings,
+            "serverIPAddress": resp_rec.get("remoteIPAddress", "") if resp_rec else "",
+            "_resourceType": resp_rec.get("type") or req_sent.get("type", ""),
+            "_sort_key": (derived_wall if derived_wall is not None else 0, started_dt),
+        }
+
+        if missing_wall:
+            entry["_comment"] = "wallTime missing"
+
+        if resp_rec.get("fromDiskCache"):
+            entry["_fromCache"] = "disk"
+        elif resp_rec.get("fromServiceWorker"):
+            entry["_fromCache"] = "serviceworker"
+
+        if load_fail:
+            entry["_error"] = load_fail.get("errorText", "Failed")
+
+        entries.append(entry)
+
+    entries.sort(key=lambda e: e.pop("_sort_key"))
+
+    ts_list = [r["requestWillBeSent"]["timestamp"] for r in records if (r.get("requestWillBeSent") or {}).get("timestamp") is not None]
+    earliest_ts = min(ts_list) if ts_list else None
+
+    if page_events.get("domContentEventFired") is not None and earliest_ts is not None:
+        diff = round((page_events["domContentEventFired"] - earliest_ts) * 1000, 2)
+        on_content_load = diff if diff >= 0 else -1
+    else:
+        on_content_load = -1
+
+    if page_events.get("loadEventFired") is not None and earliest_ts is not None:
+        diff = round((page_events["loadEventFired"] - earliest_ts) * 1000, 2)
+        on_load = diff if diff >= 0 else -1
+    else:
+        on_load = -1
+
+    page_title = page.get("title", "") if isinstance(page, dict) else ""
+    page_started = entries[0]["startedDateTime"] if entries else "1970-01-01T00:00:00.000Z"
+
+    pages = [{
+        "startedDateTime": page_started,
+        "id": "page_1",
+        "title": page_title,
+        "pageTimings": {
+            "onContentLoad": on_content_load,
+            "onLoad": on_load,
+        }
+    }]
+
+    return {
+        "log": {
+            "version": "1.2",
+            "creator": {
+                "name": "cdpilot",
+                "version": str(creator_version or globals().get("__version__", "1.0")),
+            },
+            "pages": pages,
+            "entries": entries,
+        }
+    }
+
+
+async def cmd_network(url=None, har=None):
     ws, page = get_page_ws()
     if url is None:
         url = page.get("url", "")
-    content, events = await navigate_collect(ws, url, network=True)
+    content, events = await navigate_collect(ws, url, network=True, har=bool(har))
+    if har:
+        har_dict = _har_from_events(events, page, __version__)
+        entry_count = len(har_dict.get("log", {}).get("entries", []))
+        if har == "-":
+            har_json = json.dumps(har_dict, indent=2, ensure_ascii=False)
+            sys.stdout.write(har_json + "\n")
+            sys.stdout.flush()
+            print(f"har: {entry_count} entries -> -", file=sys.stderr)
+        else:
+            _atomic_write_har(har, har_dict)
+            print(f"har: {entry_count} entries -> {har}", file=sys.stderr)
+        return
+
     print("=== Network Requests ===")
     for req in events["network"]:
         s = req.get("status", "?")
@@ -13137,10 +13885,11 @@ async def _get_element_center(ws_url, selector):
     """Return the screen center (x, y) of the element matching selector."""
     js = f"""
     (function() {{
-        var el = document.querySelector({json.dumps(selector)});
-        if (!el) return null;
-        var r = el.getBoundingClientRect();
-        return {{x: Math.round(r.left + r.width/2), y: Math.round(r.top + r.height/2)}};
+        {_SHADOW_QUERY_JS}
+        var res = __cdpilot_resolveSelector(document, {json.dumps(selector)}, true);
+        if (!res || !res.el) return null;
+        var r = res.el.getBoundingClientRect();
+        return {{x: Math.round(r.left + r.width/2), y: Math.round(r.top + r.height/2), shadowHost: res.host ? __cdpilot_hostDesc(res.host) : null}};
     }})()
     """
     res = await cdp_send(ws_url, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
@@ -13148,6 +13897,8 @@ async def _get_element_center(ws_url, selector):
     if not val:
         print(f"Error: element '{selector}' not found.", file=sys.stderr)
         sys.exit(1)
+    if val.get("shadowHost"):
+        _maybe_print_shadow_note(selector, val["shadowHost"])
     return val["x"], val["y"]
 
 
@@ -14448,19 +15199,30 @@ async def cmd_assert(selector, expected_text=None, check_visible=True):
     safe_sel = json.dumps(selector)
     js = f"""
     (function() {{
+      {_SHADOW_QUERY_JS}
       var sel = {safe_sel};
-      var el = document.querySelector(sel);
-      if (!el) return 'FAIL: Element not found: ' + sel;
+      var res = __cdpilot_resolveSelector(document, sel, true);
+      if (!res || !res.el) return {{ msg: 'FAIL: Element not found: ' + sel }};
+      var el = res.el;
       {visible_check}
       {text_check}
       var tag = el.tagName.toLowerCase();
       var txt = (el.textContent || '').substring(0, 60).trim();
-      return 'PASS: ' + tag + (txt ? ' "' + txt + '"' : '') + ' (' + sel + ')';
+      var hostDesc = res.host ? __cdpilot_hostDesc(res.host) : null;
+      return {{
+        msg: 'PASS: ' + tag + (txt ? ' "' + txt + '"' : '') + ' (' + sel + ')',
+        shadowHost: hostDesc
+      }};
     }})()
     """
     r = await cdp_send(ws_url, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
-    result = r.get(1, {}).get("result", {}).get("value", "ERROR")
-    print(result)
+    val = r.get(1, {}).get("result", {}).get("value")
+    if isinstance(val, dict):
+        if val.get("shadowHost"):
+            _maybe_print_shadow_note(selector, val["shadowHost"])
+        print(val.get("msg", "ERROR"))
+    else:
+        print(val or "ERROR")
 
 
 async def cmd_wait_for(selector, timeout_ms=5000):
@@ -14469,22 +15231,56 @@ async def cmd_wait_for(selector, timeout_ms=5000):
     safe_sel = json.dumps(selector)
     js = f"""
     (function() {{
+      {_SHADOW_QUERY_JS}
       return new Promise(function(resolve) {{
         var sel = {safe_sel};
-        var el = document.querySelector(sel);
-        if (el) return resolve('FOUND: ' + el.tagName + ' "' + (el.textContent || '').substring(0, 60).trim() + '"');
-        var obs = new MutationObserver(function() {{
-          var el = document.querySelector(sel);
-          if (el) {{ obs.disconnect(); resolve('FOUND: ' + el.tagName + ' "' + (el.textContent || '').substring(0, 60).trim() + '"'); }}
-        }});
-        obs.observe(document.body, {{childList: true, subtree: true}});
-        setTimeout(function() {{ obs.disconnect(); resolve('TIMEOUT: ' + sel + ' not found after {timeout_ms}ms'); }}, {timeout_ms});
+        var res = __cdpilot_resolveSelector(document, sel, true);
+        if (res && res.el) {{
+          var hostDesc = res.host ? __cdpilot_hostDesc(res.host) : null;
+          return resolve({{
+            out: 'FOUND: ' + res.el.tagName + ' "' + (res.el.textContent || '').substring(0, 60).trim() + '"',
+            shadowHost: hostDesc
+          }});
+        }}
+        var obs = null;
+        var timer = null;
+        var timerTimeout = null;
+        function cleanup() {{
+          if (obs) {{ obs.disconnect(); obs = null; }}
+          if (timer) {{ clearInterval(timer); timer = null; }}
+          if (timerTimeout) {{ clearTimeout(timerTimeout); timerTimeout = null; }}
+        }}
+        function check() {{
+          var found = __cdpilot_resolveSelector(document, sel, true);
+          if (found && found.el) {{
+            cleanup();
+            var hostDesc = found.host ? __cdpilot_hostDesc(found.host) : null;
+            resolve({{
+              out: 'FOUND: ' + found.el.tagName + ' "' + (found.el.textContent || '').substring(0, 60).trim() + '"',
+              shadowHost: hostDesc
+            }});
+            return true;
+          }}
+          return false;
+        }}
+        obs = new MutationObserver(check);
+        obs.observe(document.documentElement || document.body, {{childList: true, subtree: true}});
+        timer = setInterval(check, 200);
+        timerTimeout = setTimeout(function() {{
+          cleanup();
+          resolve({{ out: 'TIMEOUT: ' + sel + ' not found after {timeout_ms}ms' }});
+        }}, {timeout_ms});
       }});
     }})()
     """
     r = await cdp_send(ws_url, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True, "awaitPromise": True})], timeout=max(15, timeout_ms // 1000 + 5))
-    result = r.get(1, {}).get("result", {}).get("value", "ERROR")
-    print(result)
+    val = r.get(1, {}).get("result", {}).get("value")
+    if isinstance(val, dict):
+        if val.get("shadowHost"):
+            _maybe_print_shadow_note(selector, val["shadowHost"])
+        print(val.get("out", "ERROR"))
+    else:
+        print(val or "ERROR")
 
 
 async def cmd_wait_for_text(text, timeout_ms=5000):
@@ -14561,14 +15357,26 @@ async def cmd_check(checks_json=None):
             }}"""
         js = f"""
         (function() {{
-          var el = document.querySelector({safe_sel});
-          if (!el) return 'FAIL: Not found: ' + {safe_sel};
+          {_SHADOW_QUERY_JS}
+          var res = __cdpilot_resolveSelector(document, {safe_sel}, true);
+          if (!res || !res.el) return {{ msg: 'FAIL: Not found: ' + {safe_sel} }};
+          var el = res.el;
           {text_check}
-          return 'PASS: ' + el.tagName + ' (' + {safe_sel} + ')';
+          var hostDesc = res.host ? __cdpilot_hostDesc(res.host) : null;
+          return {{
+            msg: 'PASS: ' + el.tagName + ' (' + {safe_sel} + ')',
+            shadowHost: hostDesc
+          }};
         }})()
         """
         r = await cdp_send(ws_url, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
-        result = r.get(1, {}).get("result", {}).get("value", "ERROR")
+        val = r.get(1, {}).get("result", {}).get("value")
+        if isinstance(val, dict):
+            if val.get("shadowHost"):
+                _maybe_print_shadow_note(sel, val["shadowHost"])
+            result = val.get("msg", "ERROR")
+        else:
+            result = val or "ERROR"
         if result.startswith("PASS"):
             passed += 1
         else:
@@ -14633,16 +15441,24 @@ async def cmd_assert_value(selector, expected_value):
     safe_sel = json.dumps(selector)
     safe_expected = json.dumps(expected_value)
     js = f"""(function() {{
-      var el = document.querySelector({safe_sel});
-      if (!el) return 'FAIL: Element not found: ' + {safe_sel};
+      {_SHADOW_QUERY_JS}
+      var res = __cdpilot_resolveSelector(document, {safe_sel}, true);
+      if (!res || !res.el) return 'FAIL: Element not found: ' + {safe_sel};
+      var el = res.el;
       var val = el.value;
       var expected = {safe_expected};
-      if (val === expected) return 'PASS: Value matches \"' + expected + '\"';
-      return 'FAIL: Expected value \"' + expected + '\" but got \"' + val + '\"';
+      var hostDesc = res.host ? __cdpilot_hostDesc(res.host) : null;
+      var msg = val === expected ? 'PASS: Value matches \"' + expected + '\"' : 'FAIL: Expected value \"' + expected + '\" but got \"' + val + '\"';
+      return {{ msg: msg, shadowHost: hostDesc }};
     }})()"""
     r = await cdp_send(ws_url, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
-    result = r.get(1, {}).get("result", {}).get("value", "ERROR")
-    print(result)
+    val = r.get(1, {}).get("result", {}).get("value")
+    if isinstance(val, dict):
+        if val.get("shadowHost"):
+            _maybe_print_shadow_note(selector, val["shadowHost"])
+        print(val.get("msg", "ERROR"))
+    else:
+        print(val or "ERROR")
 
 
 async def cmd_assert_attr(selector, attr, expected):
@@ -14652,16 +15468,24 @@ async def cmd_assert_attr(selector, attr, expected):
     safe_attr = json.dumps(attr)
     safe_expected = json.dumps(expected)
     js = f"""(function() {{
-      var el = document.querySelector({safe_sel});
-      if (!el) return 'FAIL: Element not found: ' + {safe_sel};
+      {_SHADOW_QUERY_JS}
+      var res = __cdpilot_resolveSelector(document, {safe_sel}, true);
+      if (!res || !res.el) return 'FAIL: Element not found: ' + {safe_sel};
+      var el = res.el;
       var val = el.getAttribute({safe_attr}) || '';
       var expected = {safe_expected};
-      if (val.indexOf(expected) !== -1) return 'PASS: ' + {safe_sel} + '[' + {safe_attr} + '] = \"' + val + '\"';
-      return 'FAIL: Expected ' + {safe_sel} + '[' + {safe_attr} + '] to contain \"' + expected + '\" but got \"' + val + '\"';
+      var hostDesc = res.host ? __cdpilot_hostDesc(res.host) : null;
+      var msg = val.indexOf(expected) !== -1 ? 'PASS: ' + {safe_sel} + '[' + {safe_attr} + '] = \"' + val + '\"' : 'FAIL: Expected ' + {safe_sel} + '[' + {safe_attr} + '] to contain \"' + expected + '\" but got \"' + val + '\"';
+      return {{ msg: msg, shadowHost: hostDesc }};
     }})()"""
     r = await cdp_send(ws_url, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
-    result = r.get(1, {}).get("result", {}).get("value", "ERROR")
-    print(result)
+    val = r.get(1, {}).get("result", {}).get("value")
+    if isinstance(val, dict):
+        if val.get("shadowHost"):
+            _maybe_print_shadow_note(selector, val["shadowHost"])
+        print(val.get("msg", "ERROR"))
+    else:
+        print(val or "ERROR")
 
 
 async def cmd_assert_visible(selector, should_be_visible=True):
@@ -14671,8 +15495,10 @@ async def cmd_assert_visible(selector, should_be_visible=True):
     expect_label = "visible" if should_be_visible else "hidden"
     opposite_label = "hidden" if should_be_visible else "visible"
     js = f"""(function() {{
-      var el = document.querySelector({safe_sel});
-      if (!el) return 'FAIL: Element not found: ' + {safe_sel};
+      {_SHADOW_QUERY_JS}
+      var res = __cdpilot_resolveSelector(document, {safe_sel}, true);
+      if (!res || !res.el) return 'FAIL: Element not found: ' + {safe_sel};
+      var el = res.el;
       var style = window.getComputedStyle(el);
       var rect = el.getBoundingClientRect();
       var isVisible = (
@@ -14682,12 +15508,18 @@ async def cmd_assert_visible(selector, should_be_visible=True):
         (rect.width > 0 || rect.height > 0)
       );
       var expectVisible = {str(should_be_visible).lower()};
-      if (isVisible === expectVisible) return 'PASS: ' + {safe_sel} + ' is {expect_label}';
-      return 'FAIL: ' + {safe_sel} + ' expected {expect_label} but is {opposite_label}';
+      var hostDesc = res.host ? __cdpilot_hostDesc(res.host) : null;
+      var msg = isVisible === expectVisible ? 'PASS: ' + {safe_sel} + ' is {expect_label}' : 'FAIL: ' + {safe_sel} + ' expected {expect_label} but is {opposite_label}';
+      return {{ msg: msg, shadowHost: hostDesc }};
     }})()"""
     r = await cdp_send(ws_url, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
-    result = r.get(1, {}).get("result", {}).get("value", "ERROR")
-    print(result)
+    val = r.get(1, {}).get("result", {}).get("value")
+    if isinstance(val, dict):
+        if val.get("shadowHost"):
+            _maybe_print_shadow_note(selector, val["shadowHost"])
+        print(val.get("msg", "ERROR"))
+    else:
+        print(val or "ERROR")
 
 
 async def cmd_screenshot_diff(path1, path2):
@@ -16167,25 +16999,36 @@ async def cmd_scroll_to(selector, entropy=None):
     if entropy:
         # Get element position then humanize scroll
         js_pos = f"""(function(){{
-            var el=document.querySelector({json.dumps(selector)});
-            if(!el) return null;
-            var r=el.getBoundingClientRect();
-            return {{top: r.top, height: r.height}};
+            {_SHADOW_QUERY_JS}
+            var res = __cdpilot_resolveSelector(document, {json.dumps(selector)}, true);
+            if(!res || !res.el) return null;
+            var r=res.el.getBoundingClientRect();
+            return {{top: r.top, height: r.height, shadowHost: res.host ? __cdpilot_hostDesc(res.host) : null}};
         }})()"""
         res_pos = await cdp_send(ws_url, [(1, "Runtime.evaluate", {"expression": js_pos, "returnByValue": True})])
         val = res_pos.get(1, {}).get("result", {}).get("value")
         if not val:
             print(f"Error: element '{selector}' not found.", file=sys.stderr)
             sys.exit(1)
+        if val.get("shadowHost"):
+            _maybe_print_shadow_note(selector, val["shadowHost"])
         delta = int(val.get("top", 0))
         if delta != 0:
             await _humanize_scroll(ws_url, delta)
         print(f"Scrolled to (entropy): {selector}")
     else:
-        js = f"(function(){{ var el=document.querySelector({json.dumps(selector)}); if(!el) return false; el.scrollIntoView({{behavior:'instant',block:'center'}}); return true; }})()"
+        js = f"""(function(){{
+            {_SHADOW_QUERY_JS}
+            var res = __cdpilot_resolveSelector(document, {json.dumps(selector)}, true);
+            if(!res || !res.el) return null;
+            res.el.scrollIntoView({{behavior:'instant',block:'center'}});
+            return {{ ok: true, shadowHost: res.host ? __cdpilot_hostDesc(res.host) : null }};
+        }})()"""
         res = await cdp_send(ws_url, [(1, "Runtime.evaluate", {"expression": js, "returnByValue": True})])
-        ok = res.get(1, {}).get("result", {}).get("value", False)
-        if ok:
+        val = res.get(1, {}).get("result", {}).get("value")
+        if val and val.get("ok"):
+            if val.get("shadowHost"):
+                _maybe_print_shadow_note(selector, val["shadowHost"])
             print(f"Scrolled to: {selector}")
         else:
             print(f"Error: element '{selector}' not found.", file=sys.stderr)
@@ -16657,30 +17500,67 @@ WEBMCP_LIST_JS = r"""(async () => {
     url: location.href
   };
   if (!facts.api) return { facts };
-  let tools;
-  try {
-    tools = await document.modelContext.getTools();
-  } catch (e) {
-    return { facts, error: { name: String(e && e.name), message: String(e && e.message) } };
-  }
-  const out = [];
-  for (const t of tools) {
-    let schema = t.inputSchema;
-    if (typeof schema === 'string') {
-      try { schema = JSON.parse(schema); } catch (e) { /* keep the string */ }
+  // Every readable document in the frame tree is asked for its own tools. The
+  // top document's getTools() is meant to include its same-origin frames' tools,
+  // but Chromium 156 leaves out a frame that registered after the parent first
+  // touched document.modelContext (CI, 08.11; 153 never answered some frame
+  // registrations at all), so the lists are merged: one entry per (owning
+  // document, name), the owner being RegisteredTool.window. A cross-origin
+  // frame's document is unreadable and stays out, as the Permissions Policy
+  // 'tools' intends.
+  const docs = [window];
+  const walk = (w) => {
+    let n = 0;
+    try { n = w.frames.length; } catch (e) { return; }
+    for (let i = 0; i < n; i++) {
+      const f = w.frames[i];
+      try { if (!f.document) continue; } catch (e) { continue; }
+      docs.push(f);
+      walk(f);
     }
-    let frame = null, form = null;
+  };
+  walk(window);
+  const seen = new Map();
+  const out = [];
+  for (const w of docs) {
+    let mc = null;
+    try { mc = w.document.modelContext; } catch (e) { continue; }
+    if (!mc || typeof mc.getTools !== 'function') continue;
+    let tools;
     try {
-      if (t.window !== window) frame = t.window.location.href;
-      form = t.window.document.querySelector('form[toolname="' + CSS.escape(t.name) + '"]');
-    } catch (e) { /* not readable: leave frame/form unknown */ }
-    const rec = { name: t.name, title: t.title || '', description: t.description,
-                  inputSchema: schema === undefined ? null : schema,
-                  origin: t.origin, frame: frame, declarative: !!form };
-    if (form) rec.autosubmit = form.hasAttribute('toolautosubmit');
-    if (t.annotations) rec.annotations = t.annotations;
-    out.push(rec);
+      tools = await mc.getTools();
+    } catch (e) {
+      if (w === window) {
+        return { facts, error: { name: String(e && e.name), message: String(e && e.message) } };
+      }
+      continue;
+    }
+    for (const t of tools) {
+      let owner = w;
+      try { if (t.window) owner = t.window; } catch (e) { /* keep the document asked */ }
+      let names = seen.get(owner);
+      if (!names) { names = new Set(); seen.set(owner, names); }
+      if (names.has(t.name)) continue;
+      names.add(t.name);
+      let schema = t.inputSchema;
+      if (typeof schema === 'string') {
+        try { schema = JSON.parse(schema); } catch (e) { /* keep the string */ }
+      }
+      let frame = null, form = null;
+      try {
+        if (owner !== window) frame = owner.location.href;
+        form = owner.document.querySelector('form[toolname="' + CSS.escape(t.name) + '"]');
+      } catch (e) { /* not readable: leave frame/form unknown */ }
+      const rec = { name: t.name, title: t.title || '', description: t.description,
+                    inputSchema: schema === undefined ? null : schema,
+                    origin: t.origin, frame: frame, declarative: !!form };
+      if (form) rec.autosubmit = form.hasAttribute('toolautosubmit');
+      if (t.annotations) rec.annotations = t.annotations;
+      out.push(rec);
+    }
   }
+  out.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1
+    : (a.frame || '') < (b.frame || '') ? -1 : (a.frame || '') > (b.frame || '') ? 1 : 0));
   return { facts, tools: out };
 })()"""
 
@@ -16688,15 +17568,42 @@ WEBMCP_LIST_JS = r"""(async () => {
 # fresh getTools(), then executeTool(tool, input, {signal}); the signal aborts
 # after __MS__ ms. Only local bindings: nothing is left on the page.
 WEBMCP_CALL_JS = r"""(async () => {
-  const mc = document.modelContext;
-  if (!mc || typeof mc.executeTool !== 'function') return { status: 'unavailable' };
+  const top = document.modelContext;
+  if (!top || typeof top.executeTool !== 'function') return { status: 'unavailable' };
   const name = __NAME__, frame = __FRAME__, input = __INPUT__;
-  const tools = await mc.getTools();
-  const tool = tools.find((t) => {
-    if (t.name !== name) return false;
-    try { return frame === null ? t.window === window : t.window.location.href === frame; }
-    catch (e) { return false; }
-  });
+  // Looked up again in every readable document (as WEBMCP_LIST_JS lists them)
+  // and run on the modelContext of the document that registered it; the top
+  // document's copy of a frame tool is only the fallback.
+  const docs = [window];
+  const walk = (w) => {
+    let n = 0;
+    try { n = w.frames.length; } catch (e) { return; }
+    for (let i = 0; i < n; i++) {
+      const f = w.frames[i];
+      try { if (!f.document) continue; } catch (e) { continue; }
+      docs.push(f);
+      walk(f);
+    }
+  };
+  walk(window);
+  let mc = null, tool = null;
+  for (const w of docs) {
+    let c = null;
+    try { c = w.document.modelContext; } catch (e) { continue; }
+    if (!c || typeof c.getTools !== 'function' || typeof c.executeTool !== 'function') continue;
+    let tools;
+    try { tools = await c.getTools(); } catch (e) { continue; }
+    const hit = tools.find((t) => {
+      if (t.name !== name) return false;
+      let owner = w;
+      try { if (t.window) owner = t.window; } catch (e) { /* keep the document asked */ }
+      try { return frame === null ? owner === window : owner.location.href === frame; }
+      catch (e) { return false; }
+    });
+    if (!hit) continue;
+    mc = c; tool = hit;
+    if (frame === null || w !== window) break;
+  }
   if (!tool) return { status: 'gone' };
   const ac = new AbortController();
   const timer = setTimeout(() => ac.abort(new DOMException(
@@ -17052,12 +17959,59 @@ class MCPServer:
          "inputSchema": {"type": "object", "properties": {"name": {"type": "string", "description": "Tool name, as returned by browser_site_tools"}, "arguments": {"type": "object", "description": "Tool input: a JSON object matching the tool's inputSchema"}, "frame": {"type": "string", "description": "Only when several frames register the same name: part of the frame URL"}}, "required": ["name"]}},
     ]
 
-    def __init__(self):
+    # Tool profiles (`mcp --tools core|all|a,b,c`, env CDPILOT_MCP_TOOLS): a smaller
+    # tools/list cuts the schema tokens an MCP client sends with every request.
+    CORE_TOOLS = (
+        "browser_navigate", "browser_click", "browser_fill", "browser_content",
+        "browser_screenshot", "browser_eval", "browser_wait_for", "browser_assert",
+        "browser_tabs", "browser_connect",
+    )
+    DISCOVERY_TOOL = {
+        "name": "browser_tools",
+        "description": "Tools outside this server's profile. action=list: name and "
+                       "description of each tool that is not enabled. action=enable "
+                       "with names: add those tools to tools/list "
+                       "(notifications/tools/list_changed follows).",
+        "inputSchema": {"type": "object", "properties": {
+            "action": {"type": "string", "enum": ["list", "enable"]},
+            "names": {"type": "array", "items": {"type": "string"},
+                      "description": "Tool names to enable (action=enable)"}},
+            "required": ["action"]},
+    }
+    NOT_ENABLED = "tool not enabled; call browser_tools enable"
+
+    def __init__(self, tools_spec=None):
         self.tools = self._register_tools()
+        spec = (tools_spec or os.environ.get("CDPILOT_MCP_TOOLS") or "all").strip()
+        self.profiled = spec != "all"
+        self.enabled = set(self.CORE_TOOLS if spec == "core" else spec.split(","))
+        self.pending_notifications = []
 
     def listed_tools(self):
-        """tools/list: the base tools, plus the WebMCP ones while the mode is on."""
-        return self.tools + (self.WEBMCP_TOOLS if get_webmcp_config() else [])
+        """tools/list: the profile's tools (all by default), plus the WebMCP ones
+        while the mode is on."""
+        webmcp = self.WEBMCP_TOOLS if get_webmcp_config() else []
+        if not self.profiled:
+            return self.tools + webmcp
+        base = [t for t in self.tools if t["name"] in self.enabled]
+        return base + [self.DISCOVERY_TOOL] + webmcp
+
+    def _browser_tools(self, req_id, args):
+        """browser_tools: list the tools the profile left out, or enable some."""
+        off = [t for t in self.tools if t["name"] not in self.enabled]
+        if args.get("action") == "enable":
+            names = args.get("names") or []
+            known = {t["name"] for t in off}
+            self.enabled.update(n for n in names if n in known)
+            unknown = [n for n in names if n not in known and n not in self.enabled]
+            text = "enabled: " + ", ".join(n for n in names if n in self.enabled)
+            if unknown:
+                text += "\nunknown tools: " + ", ".join(unknown)
+            self.pending_notifications.append("notifications/tools/list_changed")
+        else:
+            text = "\n".join(f"{t['name']}: {t['description']}" for t in off) or "none"
+        return {"jsonrpc": "2.0", "id": req_id, "result": {
+            "content": [{"type": "text", "text": text}], "isError": False}}
 
     def _register_tools(self):
         return [
@@ -17066,9 +18020,9 @@ class MCPServer:
             {"name": "browser_screenshot", "description": "Capture a screenshot of the current browser viewport. Supports element-level cropping to save tokens (capture only a specific element instead of full page). Use JPEG format with quality parameter for smaller files (~5x smaller than PNG). Prefer element cropping + JPEG for token-efficient AI workflows.",
              "inputSchema": {"type": "object", "properties": {"filename": {"type": "string", "description": "Output file path (e.g. /tmp/screenshot.png). Extension determines format: .png, .jpg, .webp", "default": "screenshot.png"}, "element": {"type": "string", "description": "CSS selector to capture only that element (crops to bounding box). Saves ~3-7x tokens vs full page."}, "quality": {"type": "number", "description": "JPEG quality 1-100 (only for .jpg files). Lower = smaller file = fewer tokens. Default: 80"}}}},
             {"name": "browser_click", "description": "Click an element on the page identified by CSS selector. Auto-waits up to 5 seconds for the element to appear (MutationObserver). Scrolls the element into view before clicking. Returns the tag name and text of the clicked element. When a real mouse click (inside a frame, or with entropy) was pressed but the page changed under the press so the release missed the target, nothing is clicked again by script and the first line is JSON {\"clicked\": false, \"reason\": \"moved\"|\"gone\"|\"unknown\"} (isError stays false): the page may already have reacted to the press, so check it before retrying.",
-             "inputSchema": {"type": "object", "properties": {"selector": {"type": "string", "description": "CSS selector for the element to click (e.g. '#submit-btn', '.nav a', 'button[type=submit]'). Inside an iframe (cross-origin too): 'iframe#card >>> button#pay'"}}, "required": ["selector"]}},
+             "inputSchema": {"type": "object", "properties": {"selector": {"type": "string", "description": "CSS selector for the element to click (e.g. '#submit-btn', '.nav a', 'button[type=submit]'). Inside an iframe or shadow root: 'iframe#card >>> button#pay' or 'my-card >>> button.inner'"}}, "required": ["selector"]}},
             {"name": "browser_type", "description": "Type text into an input or textarea element. Uses React-compatible value setting (native setter + input/change events). Auto-waits up to 5 seconds for the element. Use browser_fill as an alias.",
-             "inputSchema": {"type": "object", "properties": {"selector": {"type": "string", "description": "CSS selector for the input element. Inside an iframe (cross-origin too): 'iframe#card >>> input[name=cardnumber]'"}, "text": {"type": "string", "description": "Text value to type into the element"}}, "required": ["selector", "text"]}},
+             "inputSchema": {"type": "object", "properties": {"selector": {"type": "string", "description": "CSS selector for the input element. Inside an iframe or shadow root: 'iframe#card >>> input[name=cardnumber]' or 'my-card >>> input.inner'"}, "text": {"type": "string", "description": "Text value to type into the element"}}, "required": ["selector", "text"]}},
             {"name": "browser_content", "description": "Get the visible text content of the current page (document.body.innerText). Returns up to 10000 characters. Use this to read page content without HTML markup. Prefer browser_a11y for structured navigation data.",
              "inputSchema": {"type": "object", "properties": {}}},
             {"name": "browser_html", "description": "Get the full HTML source of the current page (document.documentElement.outerHTML). Returns up to 50000 characters. Use sparingly — prefer browser_content or browser_a11y for most tasks as they return smaller, more useful data.",
@@ -17086,7 +18040,7 @@ class MCPServer:
             {"name": "browser_a11y", "description": "Get the accessibility tree of the current page as structured data. Returns interactive elements with @N references that can be used with browser_click. This is the PREFERRED way to understand page structure — uses ~500 tokens vs ~250K for screenshots. Use 'summary' mode for a compact view.",
              "inputSchema": {"type": "object", "properties": {"mode": {"type": "string", "enum": ["full", "summary"], "description": "Output detail level: 'full' for complete tree, 'summary' for interactive elements only", "default": "full"}}}},
             {"name": "browser_fill", "description": "Set an input element's value using React-compatible method (native descriptor setter + input/change events). Auto-waits up to 5 seconds for the element. Works with regular inputs, textareas, and React controlled components.",
-             "inputSchema": {"type": "object", "properties": {"selector": {"type": "string", "description": "CSS selector for the input element. Inside an iframe (cross-origin too): 'iframe#card >>> input[name=cardnumber]'"}, "value": {"type": "string", "description": "Value to set in the input field"}}, "required": ["selector", "value"]}},
+             "inputSchema": {"type": "object", "properties": {"selector": {"type": "string", "description": "CSS selector for the input element. Inside an iframe or shadow root: 'iframe#card >>> input[name=cardnumber]' or 'my-card >>> input.inner'"}, "value": {"type": "string", "description": "Value to set in the input field"}}, "required": ["selector", "value"]}},
             {"name": "browser_launch", "description": "Launch an isolated browser instance with Chrome DevTools Protocol enabled. Uses existing Brave/Chrome/Chromium installation — no browser download needed. Creates an isolated profile directory so your personal browser data is never touched.",
              "inputSchema": {"type": "object", "properties": {}}},
             {"name": "browser_close", "description": "Smart close: shut down every tab cdpilot opened during this automation, then close the whole browser application gracefully ONLY if no user-opened tabs remain. If the user has their own tabs open in the same browser, those are left untouched and the browser stays open. Use this to clean up after automation. Set force=true to close the browser even when user tabs remain; set keep_browser=true to only close cdpilot's tabs and never quit the browser.",
@@ -17176,7 +18130,7 @@ class MCPServer:
         if method == "initialize":
             return {"jsonrpc": "2.0", "id": req_id, "result": {
                 "protocolVersion": "2024-11-05",
-                "capabilities": {"tools": {}},
+                "capabilities": {"tools": {"listChanged": True} if self.profiled else {}},
                 "serverInfo": {"name": "cdpilot", "version": __version__}
             }}
         elif method == "notifications/initialized":
@@ -17184,7 +18138,14 @@ class MCPServer:
         elif method == "tools/list":
             return {"jsonrpc": "2.0", "id": req_id, "result": {"tools": self.listed_tools()}}
         elif method == "tools/call":
-            return self._execute_tool(req_id, params.get("name", ""), params.get("arguments", {}))
+            name, args = params.get("name", ""), params.get("arguments") or {}
+            if self.profiled and name == "browser_tools":
+                return self._browser_tools(req_id, args)
+            if self.profiled and name not in self.enabled and any(
+                    t["name"] == name for t in self.tools):
+                return {"jsonrpc": "2.0", "id": req_id, "result": {
+                    "content": [{"type": "text", "text": self.NOT_ENABLED}], "isError": True}}
+            return self._execute_tool(req_id, name, args)
         elif method == "ping":
             return {"jsonrpc": "2.0", "id": req_id, "result": {}}
         else:
@@ -17212,7 +18173,9 @@ class MCPServer:
             "browser_eval_batch": lambda a: ["eval-batch", json.dumps(a.get("expressions", []))],
             "browser_tabs": lambda a: ["tabs"],
             "browser_console": lambda a: ["console"] + ([a["url"]] if a.get("url") else []),
-            "browser_network": lambda a: ["network"] + ([a["url"]] if a.get("url") else []),
+            # "--" ends option parsing: a url shaped like "--har=/path" (an LLM client
+            # fed by a page) must never choose the HAR output file.
+            "browser_network": lambda a: ["network"] + (["--", a["url"]] if a.get("url") else []),
             "browser_a11y": lambda a: ["a11y"] + ([a["mode"]] if a.get("mode") and a["mode"] != "full" else []),
             "browser_fill": lambda a: ["fill", a.get("selector", ""), a.get("value", "")],
             "browser_launch": lambda a: ["launch"],
@@ -17321,7 +18284,11 @@ class MCPServer:
                 response = self._handle_request(request)
                 if response is not None:
                     sys.stdout.write(json_mod.dumps(response) + "\n")
-                    sys.stdout.flush()
+                for method in self.pending_notifications:
+                    sys.stdout.write(json_mod.dumps(
+                        {"jsonrpc": "2.0", "method": method}) + "\n")
+                self.pending_notifications = []
+                sys.stdout.flush()
             except json_mod.JSONDecodeError as e:
                 sys.stdout.write(json_mod.dumps({"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": f"Parse error: {str(e)}"}}) + "\n")
                 sys.stdout.flush()
@@ -19029,7 +19996,10 @@ SLOG_JS_LITERAL_CHARS = 40
 SLOG_MAX_FILES = 20
 # Long-running servers (their tool calls are logged), the reader itself
 # (reading the log must not grow it) and help.
-SLOG_SKIP_CMDS = frozenset({'mcp', 'serve', 'log', 'help', '--help', '-h', 'bot-auth'})
+SLOG_SKIP_CMDS = frozenset({'mcp', 'serve', 'log', 'help', '--help', '-h', 'bot-auth', 'record', 'replay'})
+RECORD_SKIP_CMDS = frozenset({'record', 'replay', 'log', 'help', '--help', '-h',
+                              'version', '--version', '-v', 'status', 'health',
+                              'mcp', 'serve', 'bot-auth', 'setup', 'connect', 'disconnect'})
 SLOG_CMD_ALIASES = {'open': 'go', '--version': 'version', '-v': 'version'}
 SLOG_VALUE_CMDS = frozenset({'fill', 'type'})  # <selector> <value...>, flags anywhere
 SLOG_VALUE_CMD_FLAGS = frozenset({'--no-heal'})  # their bare flags; --name=value is kept
@@ -19311,6 +20281,105 @@ def _slog_redact_tool_kv(kv, secrets):
     return _slog_clip_mark(_slog_scrub_text(kv, secrets, echo=False), SLOG_ARG_CHARS)
 
 
+def _slog_secret_hits(cmd, args):
+    """Find positions and kinds of secrets that session logging would redact.
+
+    Returns a list of (index, kind, key) tuples where kind is in:
+      {"flag_value", "word_value", "kv_value", "tokenish", "input_value"}
+    and key is the flag / word / kv key name (or None).
+    """
+    args = ["" if a is None else str(a) for a in (args or [])]
+    hits = []
+    done = set()
+
+    if cmd in SLOG_JS_CMDS or (cmd == "frame" and args[:1] == ["eval"]) or cmd == "eval-batch":
+        return []
+
+    if cmd in SLOG_VALUE_CMDS:
+        val_idxs = [i for i, a in enumerate(args) if not a.startswith("--")][1:]
+        for idx in val_idxs:
+            hits.append((idx, "input_value", None))
+            done.add(idx)
+        for i, a in enumerate(args):
+            if a.startswith("--") and "=" not in a and a not in SLOG_VALUE_CMD_FLAGS:
+                hits.append((i, "input_value", None))
+                done.add(i)
+    elif cmd in SLOG_LABEL_VALUE_CMDS or cmd == "assert-value":
+        for idx in range(1, len(args)):
+            hits.append((idx, "input_value", None))
+            done.add(idx)
+    elif cmd == "dialog" and args[:1] == ["prompt"]:
+        for idx in range(1, len(args)):
+            hits.append((idx, "input_value", None))
+            done.add(idx)
+    elif cmd == "assert-attr" and len(args) >= 3 and args[1].lower() == "value":
+        for idx in range(2, len(args)):
+            hits.append((idx, "input_value", None))
+            done.add(idx)
+    elif cmd == "tools" and args[:1] == ["call"] and len(args) >= 2:
+        done.update({0, 1})
+        i = 2
+        while i < len(args):
+            a = args[i]
+            if a in ("--arg", "--frame") and i + 1 < len(args):
+                done.add(i)
+                if a == "--arg":
+                    done.add(i + 1)
+                    k, eq, v = args[i + 1].partition("=")
+                    if eq and v and _SLOG_SECRET_NAME_RE.search(k):
+                        hits.append((i + 1, "kv_value", k))
+                i += 2
+                continue
+            if a.startswith("--arg="):
+                done.add(i)
+                k, eq, v = a.split("=", 1)[1].partition("=")
+                if eq and v and _SLOG_SECRET_NAME_RE.search(k):
+                    hits.append((i, "kv_value", k))
+            elif a[:1] in ("{", "["):
+                done.add(i)
+            i += 1
+
+    for i, arg in enumerate(args):
+        if i in done:
+            continue
+        value_follows = False
+        follow_key = None
+        follow_kind = None
+        if arg.startswith("-"):
+            name, eq, val = arg.lstrip("-").partition("=")
+            if _SLOG_SECRET_NAME_RE.search(name):
+                done.add(i)
+                if eq and val:
+                    key = arg[:len(arg) - len(val)]
+                    hits.append((i, "flag_value", key))
+                elif not eq:
+                    value_follows = True
+                    follow_key = arg
+                    follow_kind = "flag_value"
+        elif _SLOG_SECRET_WORD_RE.fullmatch(arg):
+            done.add(i)
+            value_follows = True
+            follow_key = arg
+            follow_kind = "word_value"
+        if value_follows:
+            if i + 1 < len(args) and i + 1 not in done and not args[i + 1].startswith("--"):
+                hits.append((i + 1, follow_kind, follow_key))
+                done.add(i + 1)
+            continue
+        if i not in done:
+            if _re.match(r"[A-Za-z][A-Za-z0-9+.-]*:", arg) and (
+                    "://" in arg or arg[:11].lower().startswith(("data:", "javascript:"))):
+                continue
+            m = _SLOG_KV_ARG_RE.fullmatch(arg)
+            if m and m.group(3) and (cmd == "cookies" or _SLOG_SECRET_NAME_RE.search(m.group(1))):
+                hits.append((i, "kv_value", m.group(1)))
+                done.add(i)
+            elif _slog_tokenish(arg):
+                hits.append((i, "tokenish", None))
+                done.add(i)
+    return hits
+
+
 def _slog_redact_args(cmd, args):
     """Redact one command line for the session log. Pure: no I/O, no state.
 
@@ -19637,13 +20706,17 @@ def _slog_exit_code():
 def _slog_begin(argv):
     """Start recording this CLI invocation (argv without the program name)."""
     try:
-        if not argv or not _slog_enabled():
+        if not argv:
             return
         cmd = SLOG_CMD_ALIASES.get(argv[0], argv[0])
-        if cmd in SLOG_SKIP_CMDS or cmd in (WATCH_DAEMON_FLAG, BOT_AUTH_SIGNER_FLAG,
-                                            BOT_AUTH_LABEL_FLAG):
+        if cmd in (WATCH_DAEMON_FLAG, BOT_AUTH_SIGNER_FLAG, BOT_AUTH_LABEL_FLAG, IDLE_WATCHER_FLAG):
+            return
+        slog_wants = _slog_enabled() and cmd not in SLOG_SKIP_CMDS
+        rec_wants = _record_active() and cmd not in RECORD_SKIP_CMDS and os.environ.get("CDPILOT_REPLAY_ACTIVE") != "1"
+        if not slog_wants and not rec_wants:
             return
         _SLOG.update(active=True, done=False, cmd=cmd, args=list(argv[1:]),
+                     slog_wants=slog_wants, rec_wants=rec_wants,
                      started=datetime.datetime.now().astimezone(), t0=time.monotonic(),
                      t0_wall=time.time(), lock=threading.Lock(), url=None, title=None,
                      via=os.environ.get(SLOG_VIA_ENV) or None, exit_exc=None,
@@ -19683,11 +20756,14 @@ def _slog_finish(forced_code=None, forced_error=None):
         code = forced_code if forced_code is not None else _slog_exit_code()
         out = st["stdout"].captured() if st.get("stdout") else ""
         err = st["stderr"].captured() if st.get("stderr") else ""
-        _slog_append(_slog_build_entry(
-            st["cmd"], st["args"], code, int((time.monotonic() - st["t0"]) * 1000),
-            st["started"], url=st.get("url"), title=st.get("title"), stdout=out, stderr=err,
-            error=forced_error or st.get("error"), files=_slog_files((out, err), st["t0_wall"]),
-            via=st.get("via")))
+        if st.get("slog_wants"):
+            _slog_append(_slog_build_entry(
+                st["cmd"], st["args"], code, int((time.monotonic() - st["t0"]) * 1000),
+                st["started"], url=st.get("url"), title=st.get("title"), stdout=out, stderr=err,
+                error=forced_error or st.get("error"), files=_slog_files((out, err), st["t0_wall"]),
+                via=st.get("via")))
+        if st.get("rec_wants"):
+            _record_hook_step(st["cmd"], st["args"], code)
     except Exception as e:
         _slog_warn(e)
     finally:
@@ -19696,12 +20772,15 @@ def _slog_finish(forced_code=None, forced_error=None):
 
 def _slog_record_external(argv, code, started, duration_ms, error, via):
     """Log a command whose own process could not (an MCP tool call killed on timeout)."""
-    if not argv or not _slog_enabled():
+    if not argv:
         return
     try:
         cmd = SLOG_CMD_ALIASES.get(argv[0], argv[0])
-        _slog_append(_slog_build_entry(cmd, argv[1:], code, duration_ms, started,
-                                       error=error, via=via))
+        if _slog_enabled() and cmd not in SLOG_SKIP_CMDS:
+            _slog_append(_slog_build_entry(cmd, argv[1:], code, duration_ms, started,
+                                           error=error, via=via))
+        if _record_active() and cmd not in RECORD_SKIP_CMDS and os.environ.get("CDPILOT_REPLAY_ACTIVE") != "1":
+            _record_hook_step(cmd, argv[1:], code)
     except Exception as e:
         _slog_warn(e)
 
@@ -19901,9 +20980,900 @@ def cmd_log(*args):
         _slog_print(_slog_format_table(entries, PROJECT_ID, days))
 
 
-# ─── CLI ───
+# ─── Record & Replay (issue #5) ───
 
-if __name__ == "__main__":
+RECORD_INPUT_CMDS = frozenset({'fill', 'type', 'smart-fill', 'smart-select', 'select', 'assert-value'})
+# Recorder-only widening of the session log's secret-name test, applied to the
+# selector / label of input commands: short words get boundaries so that
+# "#shipping-address" (pin), "#discard" (card) and "#lesson" (ssn) stay verbatim.
+_RECORD_SECRET_SEL_RE = _re.compile(
+    _SLOG_SECRET_NAME_RE.pattern + r"|\bpw\b|\bpin\b|pincode|cvv|cvc|\bcard|iban|\bssn\b|tc(?:kn|kimlik)",
+    _re.I,
+)
+
+
+def _record_slug(s):
+    """Derive a clean snake_case slug from a flag, key, or selector name."""
+    if not s:
+        return None
+    slug = _re.sub(r"[^A-Za-z0-9]+", "_", s).strip("_").lower()
+    return slug or None
+
+
+def _record_dir():
+    home = os.environ.get("CDPILOT_HOME") or CDPILOT_HOME
+    return os.path.join(home, "record")
+
+
+def _record_active_path():
+    return os.path.join(_record_dir(), "active.json")
+
+
+def _record_active():
+    return os.path.isfile(_record_active_path())
+
+
+def _record_hook_step(cmd, args, code):
+    """Append a step to active recording if one is in progress."""
+    if os.environ.get("CDPILOT_REPLAY_ACTIVE") == "1":
+        return
+    cmd = SLOG_CMD_ALIASES.get(cmd, cmd)
+    if cmd in RECORD_SKIP_CMDS:
+        return
+    active_path = _record_active_path()
+    if not os.path.isfile(active_path):
+        return
+    lock_path = active_path + ".lock"
+    lock_file = None
+    has_flock = False
+    try:
+        import fcntl
+        lock_file = open(lock_path, "w")
+        fcntl.flock(lock_file, fcntl.LOCK_EX)
+        has_flock = True
+    except (ImportError, OSError):
+        pass
+
+    try:
+        if not os.path.isfile(active_path):
+            return
+        with open(active_path, "r", encoding="utf-8") as f:
+            state = json.load(f)
+        started_at = state.get("started_at")
+        t_ms = 0
+        if started_at:
+            try:
+                clean_iso = started_at.replace("Z", "+00:00")
+                dt = datetime.datetime.fromisoformat(clean_iso)
+                if dt.tzinfo is None:
+                    dt = dt.replace(tzinfo=datetime.timezone.utc)
+                now = datetime.datetime.now(datetime.timezone.utc)
+                t_ms = max(0, int((now - dt).total_seconds() * 1000))
+            except Exception:
+                pass
+        steps_list = state.setdefault("steps", [])
+        step_num = len(steps_list) + 1
+        vars_dict = state.setdefault("vars", {})
+        redacted_args, vars_dict = _record_detect_placeholders(
+            cmd, args, step_num=step_num, vars_dict=vars_dict
+        )
+        step = {
+            "cmd": cmd,
+            "args": redacted_args,
+            "t_ms": t_ms,
+            "exit": code if isinstance(code, int) else 0
+        }
+        steps_list.append(step)
+        tmp_dir = os.path.dirname(active_path)
+        import tempfile
+        fd, tmp_file = tempfile.mkstemp(prefix=".active-", suffix=".tmp", dir=tmp_dir)
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(state, f, indent=2, ensure_ascii=False)
+        os.replace(tmp_file, active_path)
+    except Exception as e:
+        _slog_warn(e)  # one stderr line, like a failed session-log write; never changes the command's exit code
+    finally:
+        if has_flock and lock_file:
+            try:
+                import fcntl
+                fcntl.flock(lock_file, fcntl.LOCK_UN)
+                lock_file.close()
+            except Exception:
+                pass
+
+
+def _record_slug_from_selector(sel):
+    """Derive a clean variable slug from a selector or label."""
+    if not sel:
+        return None
+    # 1. ID selector: #foo or [id="foo"] or [id=foo]
+    m = _re.search(r"#([A-Za-z0-9_-]+)", sel)
+    if m:
+        return _re.sub(r"[^A-Za-z0-9]+", "_", m.group(1)).strip("_").lower()
+    m = _re.search(r"""\[\s*id\s*=\s*["']?([^"'\]]+)["']?\s*\]""", sel)
+    if m:
+        return _re.sub(r"[^A-Za-z0-9]+", "_", m.group(1)).strip("_").lower()
+    # 2. Name attribute: [name="foo"] or [name=foo]
+    m = _re.search(r"""\[\s*name\s*=\s*["']?([^"'\]]+)["']?\s*\]""", sel)
+    if m:
+        return _re.sub(r"[^A-Za-z0-9]+", "_", m.group(1)).strip("_").lower()
+    # 3. Type attribute: [type="password"] or [type=password]
+    m = _re.search(r"""\[\s*type\s*=\s*["']?([^"'\]]+)["']?\s*\]""", sel)
+    if m:
+        t = _re.sub(r"[^A-Za-z0-9]+", "_", m.group(1)).strip("_").lower()
+        if t in ("password", "pwd"):
+            return "password"
+        return t
+    # 4. Clean free label (e.g. "API key" -> "api_key")
+    clean = _re.sub(r"[^A-Za-z0-9]+", "_", sel).strip("_").lower()
+    if clean and len(clean) <= 30 and not clean.startswith(("input", "button", "select")):
+        return clean
+    return None
+
+
+def _record_redact_js(src, step_num, vars_dict, next_v_name_fn, cmd="eval"):
+    """Find secret string literals in JS and replace their content with {{vN}}."""
+    out, last = [], 0
+    for m in _SLOG_JS_STR_RE.finditer(src):
+        quote, body = m.group(0)[0], m.group(0)[1:-1]
+        before = src[max(0, m.start() - 80):m.start()]
+        if body and (_SLOG_JS_SECRET_CTX_RE.search(before) or _slog_tokenish(body)):
+            v_name = next_v_name_fn()
+            if v_name not in vars_dict:
+                vars_dict[v_name] = {"step": step_num, "hint": f"{cmd} {v_name}"}
+            new_body = f"{{{{{v_name}}}}}"
+        else:
+            new_body = body
+        out.append(src[last:m.start()])
+        out.append(quote + new_body + quote)
+        last = m.end()
+    out.append(src[last:])
+    return "".join(out)
+
+
+def _record_detect_placeholders(cmd, args, step_num=1, vars_dict=None):
+    """Detect secrets in a step's args and replace with {{name}} placeholders.
+
+    Returns (new_args, vars_dict).
+    """
+    if vars_dict is None:
+        vars_dict = {}
+    args = ["" if a is None else str(a) for a in (args or [])]
+    if not args:
+        return list(args), vars_dict
+
+    def next_v_name():
+        n = 1
+        while f"v{n}" in vars_dict:
+            n += 1
+        return f"v{n}"
+
+    # (c) JS commands: eval, eval-batch, frame eval, multi-eval
+    if cmd in SLOG_JS_CMDS and args:
+        if len(args) == 1:
+            new_js = _record_redact_js(args[0], step_num, vars_dict, next_v_name, cmd=cmd)
+            return [new_js], vars_dict
+        new_js = _record_redact_js(" ".join(args), step_num, vars_dict, next_v_name, cmd=cmd)
+        return [new_js], vars_dict
+    if cmd == "frame" and args[:1] == ["eval"] and len(args) > 1:
+        new_js = _record_redact_js(" ".join(args[1:]), step_num, vars_dict, next_v_name, cmd="frame eval")
+        return ["eval", new_js], vars_dict
+    if cmd == "eval-batch" and args:
+        try:
+            exprs = json.loads(args[0])
+        except ValueError:
+            exprs = None
+        if isinstance(exprs, list):
+            red_exprs = [
+                _record_redact_js(e, step_num, vars_dict, next_v_name, cmd=cmd) if isinstance(e, str) else e
+                for e in exprs
+            ]
+            new_arg0 = json.dumps(red_exprs, ensure_ascii=False)
+        else:
+            new_arg0 = _record_redact_js(args[0], step_num, vars_dict, next_v_name, cmd=cmd)
+        return [new_arg0] + args[1:], vars_dict
+
+    # (d) tools call <name> <json>
+    if cmd == "tools" and args[:1] == ["call"] and len(args) >= 2:
+        new_args = list(args)
+        i = 2
+        while i < len(new_args):
+            a = new_args[i]
+            if a in ("--arg", "--frame") and i + 1 < len(new_args):
+                if a == "--arg":
+                    kv = new_args[i + 1]
+                    k, eq, v = kv.partition("=")
+                    if eq and v and _SLOG_SECRET_NAME_RE.search(k):
+                        slug = _record_slug(k) or next_v_name()
+                        if slug not in vars_dict:
+                            vars_dict[slug] = {"step": step_num, "hint": f"{cmd} {k}"}
+                        new_args[i + 1] = f"{k}={{{{{slug}}}}}"
+                i += 2
+                continue
+            if a.startswith("--arg="):
+                kv = a.split("=", 1)[1]
+                k, eq, v = kv.partition("=")
+                if eq and v and _SLOG_SECRET_NAME_RE.search(k):
+                    slug = _record_slug(k) or next_v_name()
+                    if slug not in vars_dict:
+                        vars_dict[slug] = {"step": step_num, "hint": f"{cmd} {k}"}
+                    new_args[i] = f"--arg={k}={{{{{slug}}}}}"
+                i += 1
+                continue
+            if a[:1] in ("{", "["):
+                try:
+                    obj = json.loads(a)
+                except ValueError:
+                    obj = None
+                if obj is not None:
+                    def _redact_json_rec(val):
+                        if isinstance(val, dict):
+                            out_dict = {}
+                            for k, v in val.items():
+                                if _SLOG_SECRET_NAME_RE.search(str(k)) and v is not None:
+                                    slug = _record_slug(str(k)) or next_v_name()
+                                    if slug not in vars_dict:
+                                        vars_dict[slug] = {"step": step_num, "hint": f"{cmd} {k}"}
+                                    out_dict[k] = f"{{{{{slug}}}}}"
+                                else:
+                                    out_dict[k] = _redact_json_rec(v)
+                            return out_dict
+                        elif isinstance(val, list):
+                            return [_redact_json_rec(x) for x in val]
+                        return val
+                    red_obj = _redact_json_rec(obj)
+                    new_args[i] = json.dumps(red_obj, separators=(',', ':'), ensure_ascii=False)
+            i += 1
+        return new_args, vars_dict
+
+    # (b) Input commands
+    new_args = list(args)
+    if cmd in RECORD_INPUT_CMDS:
+        if cmd in ('fill', 'type'):
+            non_flags = [i for i, a in enumerate(args) if not a.startswith("--")]
+            if non_flags:
+                sel_idx = non_flags[0]
+                sel = args[sel_idx]
+                val_idxs = non_flags[1:]
+                val_str = " ".join(args[i] for i in val_idxs) if val_idxs else ""
+                is_secret_sel = bool(_RECORD_SECRET_SEL_RE.search(sel))
+                is_tok = bool(val_idxs and _slog_tokenish(val_str))
+                if (is_secret_sel or is_tok) and val_idxs:
+                    slug = (_record_slug_from_selector(sel) if is_secret_sel else None) or next_v_name()
+                    var_name = slug
+                    if var_name not in vars_dict:
+                        vars_dict[var_name] = {"step": step_num, "hint": f"{cmd} {sel}"}
+                    val_placed = False
+                    new_args = []
+                    for i, a in enumerate(args):
+                        if i in val_idxs:
+                            if not val_placed:
+                                new_args.append(f"{{{{{var_name}}}}}")
+                                val_placed = True
+                        else:
+                            new_args.append(a)
+                    return new_args, vars_dict
+        elif cmd in ('smart-fill', 'smart-select', 'select', 'assert-value'):
+            if len(args) >= 2:
+                sel = args[0]
+                val_str = " ".join(args[1:])
+                is_secret_sel = bool(_RECORD_SECRET_SEL_RE.search(sel))
+                is_tok = bool(_slog_tokenish(val_str))
+                if is_secret_sel or is_tok:
+                    slug = (_record_slug_from_selector(sel) if is_secret_sel else None) or next_v_name()
+                    var_name = slug
+                    if var_name not in vars_dict:
+                        vars_dict[var_name] = {"step": step_num, "hint": f"{cmd} {sel}"}
+                    return [sel, f"{{{{{var_name}}}}}"], vars_dict
+
+    # (a) General hits from _slog_secret_hits
+    hits = _slog_secret_hits(cmd, new_args)
+    handled_indices = set()
+    for idx, kind, key in hits:
+        if kind == "input_value":
+            continue
+        if kind in ("flag_value", "word_value", "kv_value") and key:
+            slug = _record_slug(key) or next_v_name()
+            hint = f"{cmd} {key}"
+        else:
+            slug = next_v_name()
+            hint = f"{cmd} {key}" if key else f"{cmd} {slug}"
+
+        if slug not in vars_dict:
+            vars_dict[slug] = {"step": step_num, "hint": hint}
+
+        if kind == "kv_value":
+            arg = new_args[idx]
+            m = _SLOG_KV_ARG_RE.fullmatch(arg)
+            if m:
+                new_args[idx] = m.group(1) + m.group(2) + f"{{{{{slug}}}}}"
+            else:
+                new_args[idx] = f"{{{{{slug}}}}}"
+            handled_indices.add(idx)
+        elif kind == "flag_value":
+            arg = new_args[idx]
+            if "=" in arg and arg.startswith("-"):
+                prefix, _, _ = arg.partition("=")
+                new_args[idx] = f"{prefix}={{{{{slug}}}}}"
+            else:
+                new_args[idx] = f"{{{{{slug}}}}}"
+            handled_indices.add(idx)
+        elif kind == "word_value":
+            new_args[idx] = f"{{{{{slug}}}}}"
+            handled_indices.add(idx)
+        elif kind == "tokenish":
+            new_args[idx] = f"{{{{{slug}}}}}"
+            handled_indices.add(idx)
+
+    # (e) Existing URL, Bearer, Token-prefix rules for unhandled indices
+    for i, arg in enumerate(new_args):
+        if i in handled_indices:
+            continue
+        # 1. Secret URL params or userinfo password
+        if ("://" in arg or arg.startswith(("http:", "https:"))) and _slog_mask_url(arg) != arg:
+            from urllib.parse import urlsplit, urlunsplit, unquote_plus
+            try:
+                parts = urlsplit(arg)
+                netloc = parts.netloc
+                if "@" in netloc:
+                    userinfo, _, host = netloc.rpartition("@")
+                    if ":" in userinfo:
+                        user, _, password = userinfo.partition(":")
+                        var_name = "password"
+                        if var_name in vars_dict and vars_dict[var_name].get("step") != step_num:
+                            var_name = f"password_{step_num}"
+                        vars_dict[var_name] = {"step": step_num, "hint": f"{cmd} password"}
+                        netloc = f"{user}:{{{{{var_name}}}}}@{host}"
+                qs_parts = []
+                for p in parts.query.split("&") if parts.query else []:
+                    k, sep, v = p.partition("=")
+                    if sep and v and _SLOG_SECRET_PARAM_RE.search(unquote_plus(k)):
+                        slug = _record_slug(k) or next_v_name()
+                        var_name = slug
+                        if var_name in vars_dict and vars_dict[var_name].get("step") != step_num:
+                            var_name = f"{slug}_{step_num}"
+                        vars_dict[var_name] = {"step": step_num, "hint": f"{cmd} {k}"}
+                        p = f"{k}={{{{{var_name}}}}}"
+                    qs_parts.append(p)
+                new_q = "&".join(qs_parts)
+                frag_parts = []
+                for p in parts.fragment.split("&") if parts.fragment else []:
+                    k, sep, v = p.partition("=")
+                    if sep and v and _SLOG_SECRET_PARAM_RE.search(unquote_plus(k)):
+                        slug = _record_slug(k) or next_v_name()
+                        var_name = slug
+                        if var_name in vars_dict and vars_dict[var_name].get("step") != step_num:
+                            var_name = f"{slug}_{step_num}"
+                        vars_dict[var_name] = {"step": step_num, "hint": f"{cmd} {k}"}
+                        p = f"{k}={{{{{var_name}}}}}"
+                    frag_parts.append(p)
+                new_frag = "&".join(frag_parts)
+                new_args[i] = urlunsplit((parts.scheme, netloc, parts.path, new_q, new_frag))
+                continue
+            except Exception:
+                pass
+
+        # 2. Bearer token
+        m_bearer = _SLOG_BEARER_RE.search(arg)
+        if m_bearer:
+            var_name = next_v_name()
+            vars_dict[var_name] = {"step": step_num, "hint": f"{cmd} {m_bearer.group(1)}"}
+            new_args[i] = _SLOG_BEARER_RE.sub(
+                lambda m: f"{m.group(1)}{m.group(2)}{{{{{var_name}}}}}", arg)
+            continue
+
+        # 3. Token prefix
+        m_tok = _SLOG_TOKEN_PREFIX_RE.search(arg)
+        if m_tok:
+            var_name = next_v_name()
+            hint_str = f"{cmd} {args[0]}" if args else cmd
+            vars_dict[var_name] = {"step": step_num, "hint": hint_str}
+            new_args[i] = _SLOG_TOKEN_PREFIX_RE.sub(f"{{{{{var_name}}}}}", arg)
+            continue
+
+    return new_args, vars_dict
+
+
+def cmd_record_start(*args):
+    """Start a recording session."""
+    name = None
+    i = 0
+    while i < len(args):
+        a = args[i]
+        if a == "--name":
+            if i + 1 >= len(args):
+                print("cdpilot: --name requires a name", file=sys.stderr)
+                sys.exit(2)
+            name = args[i + 1]
+            i += 2
+            continue
+        elif a.startswith("--name="):
+            name = a.split("=", 1)[1]
+            i += 1
+            continue
+        elif a.startswith("--"):
+            print(f"cdpilot: unknown record option: {a}", file=sys.stderr)
+            sys.exit(2)
+        i += 1
+
+    active_path = _record_active_path()
+    if os.path.isfile(active_path):
+        name_found = "(unnamed)"
+        try:
+            with open(active_path, "r", encoding="utf-8") as f:
+                state = json.load(f)
+            name_found = state.get("name") or "(unnamed)"
+        except Exception:
+            pass
+        print(f"cdpilot: recording already active: {name_found!r}", file=sys.stderr)
+        sys.exit(1)
+
+    now = datetime.datetime.now(datetime.timezone.utc)
+    if not name:
+        name = f"flow-{now.strftime('%Y%m%d-%H%M%S')}"
+
+    rec_dir = _record_dir()
+    os.makedirs(rec_dir, exist_ok=True)
+    state = {
+        "name": name,
+        "started_at": now.isoformat(),
+        "steps": [],
+        "vars": {}
+    }
+    import tempfile
+    fd, tmp_file = tempfile.mkstemp(prefix=".active-", suffix=".tmp", dir=rec_dir)
+    with os.fdopen(fd, "w", encoding="utf-8") as f:
+        json.dump(state, f, indent=2, ensure_ascii=False)
+    os.replace(tmp_file, active_path)
+    print(f"Recording started: {name}")
+
+
+def cmd_record_status(*args):
+    """Report status of the active recording session."""
+    active_path = _record_active_path()
+    if not os.path.isfile(active_path):
+        print("No recording active.")
+        return
+    try:
+        with open(active_path, "r", encoding="utf-8") as f:
+            state = json.load(f)
+        name = state.get("name") or "(unnamed)"
+        steps = state.get("steps") or []
+        started_at = state.get("started_at") or ""
+        print(f"Recording active: {name} ({len(steps)} steps, started {started_at})")
+    except Exception as e:
+        print(f"cdpilot: error reading active recording: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def cmd_record_cancel(*args):
+    """Cancel and discard the active recording session."""
+    active_path = _record_active_path()
+    if not os.path.isfile(active_path):
+        print("No recording active.")
+        return
+    try:
+        with open(active_path, "r", encoding="utf-8") as f:
+            state = json.load(f)
+        name = state.get("name") or "(unnamed)"
+        os.remove(active_path)
+        lock_path = active_path + ".lock"
+        if os.path.isfile(lock_path):
+            os.remove(lock_path)
+        print(f"Recording cancelled: {name}")
+    except Exception as e:
+        print(f"cdpilot: error cancelling recording: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def cmd_record_stop(*args):
+    """Stop recording session and output flow JSON."""
+    save_path = None
+    i = 0
+    while i < len(args):
+        a = args[i]
+        if a == "--save":
+            if i + 1 >= len(args):
+                print("cdpilot: --save requires a file path", file=sys.stderr)
+                sys.exit(2)
+            save_path = args[i + 1]
+            i += 2
+            continue
+        elif a.startswith("--save="):
+            save_path = a.split("=", 1)[1]
+            i += 1
+            continue
+        elif a.startswith("--"):
+            print(f"cdpilot: unknown record option: {a}", file=sys.stderr)
+            sys.exit(2)
+        i += 1
+
+    active_path = _record_active_path()
+    if not os.path.isfile(active_path):
+        print("cdpilot: no recording active", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        with open(active_path, "r", encoding="utf-8") as f:
+            state = json.load(f)
+    except Exception as e:
+        print(f"cdpilot: error reading active recording: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    name = state.get("name") or "flow"
+    all_steps = state.get("steps") or []
+    recorded_vars = state.get("vars") or {}
+    successful_steps = [s for s in all_steps if s.get("exit") == 0]
+    dropped_count = len(all_steps) - len(successful_steps)
+    if dropped_count > 0:
+        print(f"dropped {dropped_count} failed steps", file=sys.stderr)
+
+    flow_steps = []
+    for s in successful_steps:
+        flow_steps.append({
+            "cmd": s.get("cmd", ""),
+            "args": s.get("args", []),
+            "t_ms": s.get("t_ms", 0)
+        })
+
+    var_pattern = _re.compile(r"\{\{([A-Za-z0-9_-]+)\}\}")
+    first_seen_step = {}
+    for step_idx, s in enumerate(flow_steps, 1):
+        for arg in s.get("args", []):
+            for m in var_pattern.finditer(str(arg)):
+                v_name = m.group(1)
+                if v_name not in first_seen_step:
+                    first_seen_step[v_name] = step_idx
+
+    final_vars = {}
+    for v_name, first_step in first_seen_step.items():
+        if v_name in recorded_vars:
+            v_info = dict(recorded_vars[v_name])
+            v_info["step"] = first_step
+            final_vars[v_name] = v_info
+        else:
+            final_vars[v_name] = {"step": first_step, "hint": v_name}
+
+    now = datetime.datetime.now(datetime.timezone.utc)
+    flow_data = {
+        "cdpilot_flow": 1,
+        "name": name,
+        "recorded_at": now.isoformat(),
+        "cdpilot_version": __version__,
+        "steps": flow_steps,
+        "vars": final_vars
+    }
+
+    if save_path:
+        try:
+            save_dir = os.path.dirname(os.path.abspath(save_path))
+            if save_dir:
+                os.makedirs(save_dir, exist_ok=True)
+            fd = os.open(save_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+            with open(fd, "w", encoding="utf-8") as f:
+                json.dump(flow_data, f, indent=2, ensure_ascii=False)
+                f.write("\n")
+        except Exception as e:
+            print(f"cdpilot: could not write {save_path}: {e}", file=sys.stderr)
+            sys.exit(1)
+
+        try:
+            os.remove(active_path)
+            lock_path = active_path + ".lock"
+            if os.path.isfile(lock_path):
+                os.remove(lock_path)
+        except OSError:
+            pass
+        print(f"Saved flow to {save_path}")
+    else:
+        try:
+            os.remove(active_path)
+            lock_path = active_path + ".lock"
+            if os.path.isfile(lock_path):
+                os.remove(lock_path)
+        except OSError:
+            pass
+        print(json.dumps(flow_data, indent=2, ensure_ascii=False))
+
+
+def cmd_record_dispatch(args):
+    """Dispatch cdpilot record subcommands."""
+    if not args:
+        print("Usage: cdpilot record <subcommand> [options]\n\n"
+              "Subcommands:\n"
+              "  start [--name <n>]        Start recording commands into active session\n"
+              "  status                    Show active recording status\n"
+              "  cancel                    Cancel and discard active recording\n"
+              "  stop [--save <file.json>] Stop recording and emit flow JSON\n",
+              file=sys.stderr)
+        sys.exit(2)
+
+    if args[0] in ('--help', '-h', 'help'):
+        print("Usage: cdpilot record <subcommand> [options]\n\n"
+              "Subcommands:\n"
+              "  start [--name <n>]        Start recording commands into active session\n"
+              "  status                    Show active recording status\n"
+              "  cancel                    Cancel and discard active recording\n"
+              "  stop [--save <file.json>] Stop recording and emit flow JSON\n",
+              file=sys.stderr)
+        sys.exit(0)
+
+    sub = args[0].lower()
+    rest = args[1:]
+    if sub == 'start':
+        cmd_record_start(*rest)
+    elif sub == 'status':
+        cmd_record_status(*rest)
+    elif sub == 'cancel':
+        cmd_record_cancel(*rest)
+    elif sub == 'stop':
+        cmd_record_stop(*rest)
+    else:
+        print(f"Unknown record subcommand: {sub}. Run: cdpilot record --help", file=sys.stderr)
+        sys.exit(1)
+
+
+def cmd_replay(*args):
+    """Replay a recorded flow JSON file."""
+    if not args:
+        print("Usage: cdpilot replay <flow.json> [--var k=v ...] [--delay real|none|<ms>] [--dry-run] [--continue]",
+              file=sys.stderr)
+        sys.exit(2)
+
+    flow_path = None
+    cli_vars = {}
+    delay_mode = "real"
+    delay_fixed_ms = 0
+    dry_run = False
+    continue_on_error = False
+
+    i = 0
+    while i < len(args):
+        a = args[i]
+        if a == "--dry-run":
+            dry_run = True
+            i += 1
+        elif a == "--continue":
+            continue_on_error = True
+            i += 1
+        elif a == "--var":
+            if i + 1 < len(args):
+                kv = args[i + 1]
+                k, sep, v = kv.partition("=")
+                if sep:
+                    cli_vars[k.strip()] = v
+                else:
+                    print(f"cdpilot: invalid --var format: {kv!r} (expected k=v)", file=sys.stderr)
+                    sys.exit(2)
+                i += 2
+            else:
+                print("cdpilot: --var requires k=v", file=sys.stderr)
+                sys.exit(2)
+        elif a.startswith("--var="):
+            kv = a.split("=", 1)[1]
+            k, sep, v = kv.partition("=")
+            if sep:
+                cli_vars[k.strip()] = v
+            else:
+                print(f"cdpilot: invalid --var format: {kv!r} (expected k=v)", file=sys.stderr)
+                sys.exit(2)
+            i += 1
+        elif a == "--delay":
+            if i + 1 < len(args):
+                val = args[i + 1].strip()
+                if val == "real":
+                    delay_mode = "real"
+                elif val == "none":
+                    delay_mode = "none"
+                else:
+                    v = val[:-2] if val.endswith("ms") else val
+                    if v.isdigit():
+                        delay_mode = "fixed"
+                        delay_fixed_ms = int(v)
+                    else:
+                        print(f"cdpilot: invalid delay: {val} (expected 'real', 'none', or milliseconds)", file=sys.stderr)
+                        sys.exit(2)
+                i += 2
+            else:
+                print("cdpilot: --delay requires a value ('real', 'none', or milliseconds)", file=sys.stderr)
+                sys.exit(2)
+        elif a.startswith("--delay="):
+            val = a.split("=", 1)[1].strip()
+            if val == "real":
+                delay_mode = "real"
+            elif val == "none":
+                delay_mode = "none"
+            else:
+                v = val[:-2] if val.endswith("ms") else val
+                if v.isdigit():
+                    delay_mode = "fixed"
+                    delay_fixed_ms = int(v)
+                else:
+                    print(f"cdpilot: invalid delay: {val} (expected 'real', 'none', or milliseconds)", file=sys.stderr)
+                    sys.exit(2)
+            i += 1
+        elif a.startswith("--"):
+            print(f"cdpilot: unknown replay option: {a}", file=sys.stderr)
+            sys.exit(2)
+        else:
+            if flow_path is None:
+                flow_path = a
+            i += 1
+
+    if not flow_path:
+        print("cdpilot: flow file path required", file=sys.stderr)
+        sys.exit(2)
+
+    if not os.path.isfile(flow_path):
+        print(f"cdpilot: file not found: {flow_path}", file=sys.stderr)
+        sys.exit(2)
+
+    try:
+        with open(flow_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    except Exception as e:
+        print(f"cdpilot: invalid JSON in flow file: {e}", file=sys.stderr)
+        sys.exit(2)
+
+    if not isinstance(data, dict):
+        print(f"cdpilot: invalid flow file shape (expected JSON object): {flow_path}", file=sys.stderr)
+        sys.exit(2)
+
+    if "cdpilot_flow" not in data or data.get("cdpilot_flow") != 1:
+        print(f"cdpilot: unknown or missing flow version: {data.get('cdpilot_flow')!r} (expected 1)", file=sys.stderr)
+        sys.exit(2)
+
+    steps = data.get("steps")
+    if not isinstance(steps, list):
+        print("cdpilot: invalid flow file: 'steps' must be a list", file=sys.stderr)
+        sys.exit(2)
+
+    for idx, s in enumerate(steps, 1):
+        if (not isinstance(s, dict)
+                or not isinstance(s.get("cmd"), str)
+                or not s.get("cmd").strip()
+                or not isinstance(s.get("args"), list)
+                or not all(isinstance(x, str) for x in s.get("args"))):
+            print(f"cdpilot: invalid flow file: step {idx} malformed", file=sys.stderr)
+            sys.exit(2)
+
+    collected_vars = {}
+    for env_k, env_v in os.environ.items():
+        if env_k.startswith("CDPILOT_VAR_"):
+            var_name = env_k[len("CDPILOT_VAR_"):].lower()
+            collected_vars[var_name] = env_v
+            collected_vars[env_k[len("CDPILOT_VAR_"):]] = env_v
+
+    collected_vars.update(cli_vars)
+
+    needed_vars = set(data.get("vars", {}).keys())
+    for s in steps:
+        if isinstance(s, dict):
+            for a in s.get("args", []):
+                for m in _re.finditer(r"\{\{([A-Za-z0-9_-]+)\}\}", str(a)):
+                    needed_vars.add(m.group(1))
+
+    def get_var_value(name):
+        if name in collected_vars:
+            return collected_vars[name]
+        if name.lower() in collected_vars:
+            return collected_vars[name.lower()]
+        if name.upper() in collected_vars:
+            return collected_vars[name.upper()]
+        return None
+
+    missing = []
+    for var_name in sorted(needed_vars):
+        if get_var_value(var_name) is None:
+            missing.append(var_name)
+
+    if missing:
+        print(f"cdpilot: missing required variable(s): {', '.join(missing)}", file=sys.stderr)
+        sys.exit(2)
+
+    total_steps = len(steps)
+    if dry_run:
+        for idx, step in enumerate(steps, 1):
+            cmd = step.get("cmd", "")
+            args_list = [str(a) for a in step.get("args", [])]
+            args_str = " ".join(args_list)
+            line = f"[{idx}/{total_steps}] {cmd} {args_str}".strip()
+            print(line)
+        sys.exit(0)
+
+    had_failure = False
+    for idx, step in enumerate(steps, 1):
+        if idx > 1:
+            if delay_mode == "real":
+                prev_t = steps[idx - 2].get("t_ms", 0) if idx >= 2 else 0
+                curr_t = step.get("t_ms", 0)
+                gap_ms = max(0, curr_t - prev_t)
+                sleep_s = min(gap_ms, 10000) / 1000.0
+                if sleep_s > 0:
+                    time.sleep(sleep_s)
+            elif delay_mode == "fixed":
+                if delay_fixed_ms > 0:
+                    time.sleep(delay_fixed_ms / 1000.0)
+
+        cmd = step.get("cmd", "")
+        raw_args = step.get("args", [])
+        sub_args = []
+        for a in raw_args:
+            s_val = str(a)
+            sub = _re.sub(r"\{\{([A-Za-z0-9_-]+)\}\}",
+                          lambda m: str(get_var_value(m.group(1)) if get_var_value(m.group(1)) is not None else m.group(0)),
+                          s_val)
+            sub_args.append(sub)
+
+        # Collect substituted variable values for placeholders in this step
+        step_subs = {}
+        for a in raw_args:
+            for m in _re.finditer(r"\{\{([A-Za-z0-9_-]+)\}\}", str(a)):
+                vname = m.group(1)
+                vval = get_var_value(vname)
+                if vval is not None and str(vval) != "":
+                    step_subs[vname] = str(vval)
+
+        def sanitize_output(text):
+            if not text:
+                return text
+            # Replace longest value first; skip empty values
+            sorted_subs = sorted(step_subs.items(), key=lambda kv: len(kv[1]), reverse=True)
+            for vname, vval in sorted_subs:
+                if vval:
+                    text = text.replace(vval, f"{{{{{vname}}}}}")
+            return text
+
+        if cmd in RECORD_INPUT_CMDS and raw_args:
+            target = next((a for a in raw_args if not a.startswith("--")), raw_args[0])
+            step_label = f"{cmd} {target}"
+        elif raw_args:
+            step_label = f"{cmd} {' '.join(str(a) for a in raw_args)}"
+        else:
+            step_label = cmd
+
+        env = os.environ.copy()
+        env["CDPILOT_REPLAY_ACTIVE"] = "1"
+        env["PYTHONIOENCODING"] = "utf-8"
+        t0 = time.monotonic()
+        child_cmd = [sys.executable, os.path.abspath(__file__), cmd] + sub_args
+        res = subprocess.run(
+            child_cmd,
+            capture_output=True,
+            encoding="utf-8",
+            errors="replace",
+            env=env
+        )
+        dur = time.monotonic() - t0
+
+        if res.returncode == 0:
+            print(f"[{idx}/{total_steps}] {step_label} ... ok {dur:.1f}s")
+        else:
+            print(f"[{idx}/{total_steps}] {step_label} ... failed ({res.returncode}) {dur:.1f}s")
+            raw_err = res.stderr.rstrip() if res.stderr else res.stdout.rstrip()
+            err_msg = sanitize_output(raw_err)
+            if err_msg:
+                print(err_msg, file=sys.stderr)
+            had_failure = True
+            if not continue_on_error:
+                sys.exit(1)
+
+    if had_failure:
+        sys.exit(1)
+
+
+def cmd_replay_dispatch(args):
+    """Dispatch cdpilot replay command."""
+    if not args or args[0] in ('--help', '-h', 'help'):
+        print("Usage: cdpilot replay <flow.json> [--var k=v ...] [--delay real|none|<ms>] [--dry-run] [--continue]\n",
+              file=sys.stderr)
+        sys.exit(0 if (args and args[0] in ('--help', '-h', 'help')) else 2)
+    cmd_replay(*args)
+
+
+# ─── CLI ───
+
+if __name__ == "__main__":
     # On Windows a pipe (an agent's shell, the MCP server, `> file`) gets the
     # ANSI code page, so a Turkish page title or an emoji crashed the command
     # with UnicodeEncodeError. Write UTF-8 unless the user chose an encoding.
@@ -19935,7 +21905,7 @@ if __name__ == "__main__":
     # work in CI and for users who skip the Node wrapper entirely.
     if cmd in ('--version', '-v'):
         cmd = 'version'
-    elif cmd in ('--help', '-h'):
+    elif cmd in ('--help', '-h', 'help'):
         print(__doc__)
         sys.exit(0)
 
@@ -19955,6 +21925,17 @@ if __name__ == "__main__":
             print(f"cdpilot: {_e}", file=sys.stderr)
             sys.exit(2)
 
+    if cmd == "network":
+        for _i, _a in enumerate(args):
+            if _a == "--":
+                break
+            if _a == "--har":
+                if _i + 1 >= len(args):
+                    _har_usage_exit()
+            elif _a.startswith("--har="):
+                if not _a.split("=", 1)[1]:
+                    _har_usage_exit()
+
     # 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.
@@ -20025,6 +22006,8 @@ if __name__ == "__main__":
         'watch': lambda: _dispatch_watch_cmd(args),
         'bot-auth': lambda: cmd_bot_auth(*args),
         'log': lambda: cmd_log(*args),
+        'record': lambda: cmd_record_dispatch(args),
+        'replay': lambda: cmd_replay_dispatch(args),
         'connect': lambda: cmd_connect(*args),
         'disconnect': cmd_disconnect,
     }
@@ -20041,7 +22024,13 @@ if __name__ == "__main__":
         sys.exit(0)
 
     if cmd == "mcp":
-        server = MCPServer()
+        _spec = None
+        for _i, _a in enumerate(args):
+            if _a == '--tools' and _i + 1 < len(args):
+                _spec = args[_i + 1]
+            elif _a.startswith('--tools='):
+                _spec = _a.split('=', 1)[1]
+        server = MCPServer(_spec)
         server.run()
         sys.exit(0)
 
@@ -20085,6 +22074,39 @@ if __name__ == "__main__":
             print(f"Usage: {usage}")
             sys.exit(1)
 
+    def _dispatch_network(net_args):
+        """`network [url] [--har <file>]`; everything after `--` is positional
+        (the MCP server passes the url that way), so an argument that merely
+        looks like `--har=<path>` can never pick the output file."""
+        url = None
+        har_file = None
+        i = 0
+        while i < len(net_args):
+            a = net_args[i]
+            if a == "--":
+                rest = net_args[i + 1:]
+                if url is None and rest:
+                    url = rest[0]
+                break
+            if a == "--har":
+                if i + 1 >= len(net_args):
+                    _har_usage_exit()
+                har_file = net_args[i + 1]
+                i += 2
+            elif a.startswith("--har="):
+                val = a.split("=", 1)[1]
+                if not val:
+                    _har_usage_exit()
+                har_file = val
+                i += 1
+            elif a.startswith("--"):
+                i += 1
+            else:
+                if url is None:
+                    url = a
+                i += 1
+        return cmd_network(url=url, har=har_file)
+
     async_map = {
         "go": lambda: (require_args(1, "go <url>"), cmd_go(args[0]))[1] if not args else cmd_go(args[0]),
         "content": cmd_content,
@@ -20126,7 +22148,7 @@ if __name__ == "__main__":
         ),
         "wait": lambda: (require_args(1, "wait <selector>"), None)[1] if not args else cmd_wait(args[0], int(args[1]) if len(args) > 1 else 5),
         "tabs": cmd_tabs,
-        "network": lambda: cmd_network(args[0] if args else None),
+        "network": lambda: _dispatch_network(args),
         "console": lambda: cmd_console(args[0] if args else None),
         "cookies": lambda: cmd_cookies(*args),
         "storage": cmd_storage,