cdpilot 0.9.2 → 0.9.4

package/README.md

@@ -44,7 +44,7 @@ two-axis policy — extension workload × platform stability:
 
 | Your workload | Auto-pick order |
 |---|---|
-| Has extensions registered (`ext-install`) | vivaldi → brave → edge → chromium → chrome |
+| Has extensions registered (`ext-install`) | vivaldi → brave → edge → chromium → chrome (→ Chrome for Testing, if installed) |
 | No extensions (pure automation) | chrome → vivaldi → edge → chromium → brave |
 
 Override anytime:
@@ -52,13 +52,16 @@ Override anytime:
 ```bash
 cdpilot browser            # show current pick + reason
 cdpilot browser vivaldi    # pin to Vivaldi
+cdpilot browser chrome-for-testing   # pin to Chrome for Testing (after installing it, below)
 cdpilot browser auto       # restore smart default
 ```
 
 **Why the split?**
-- **Chrome 147+ silently drops `--load-extension`** for unpacked extensions
-  (no error, no warning). Verified — `chrome://extensions` shows 0 items.
-- **Vivaldi, Brave, Edge, Chromium** honor `--load-extension` (tested).
+- **Chrome 137+ silently drops `--load-extension`** for unpacked extensions
+  (no error, no warning) — Google removed it from branded Chrome builds
+  ([PSA](https://groups.google.com/a/chromium.org/g/chromium-extensions/c/1-g8EFx2BBY/m/S0ET5wPjCAAJ)).
+  Verified — `chrome://extensions` shows 0 items.
+- **Vivaldi, Brave, Edge, Chromium and Chrome for Testing** honor `--load-extension` (tested).
 - On **macOS 26 (Tahoe)** Brave 1.89 crashes deterministically at ~7min
   uptime (SIGTRAP in ThreadPoolForegroundWorker). cdpilot detects the OS
   and demotes Brave automatically until a fixed Brave release ships.
@@ -66,6 +69,43 @@ cdpilot browser auto       # restore smart default
 Each browser gets its own isolated profile (`~/.cdpilot/.../profile-vivaldi`
 etc.) so switching never causes prefs corruption.
 
+### Extension development: Chrome for Testing
+
+If you develop an extension against Chrome itself, install
+[Chrome for Testing](https://developer.chrome.com/blog/chrome-for-testing) (CfT) —
+the Chrome team's versioned, non-auto-updating Chrome build for automation, which
+still loads unpacked extensions:
+
+```bash
+cdpilot browser install chrome-for-testing                    # latest Stable
+cdpilot browser install chrome-for-testing --channel beta     # stable | beta | dev | canary
+cdpilot browser install chrome-for-testing --version 154      # a milestone, or a full version (154.0.8037.57)
+cdpilot ext-install ./my-extension/                           # register your unpacked extension
+cdpilot browser status                                        # shows the CfT version and path
+```
+
+- **Download only on that command.** It is a one-time ~150-190 MB zip (mac-arm64 at
+  154.0.8037.57: 191,429,663 bytes); cdpilot never fetches it by itself. The build comes
+  from the official [CfT JSON endpoints](https://googlechromelabs.github.io/chrome-for-testing/)
+  (`last-known-good-versions-with-downloads.json`, per-version and per-milestone files).
+  Those list URLs only, no hash, so the download is checked against the server's
+  `Content-Length` and its `x-goog-hash` md5; the zip's SHA-256 is recorded.
+- It is extracted to `$CDPILOT_HOME/browsers/chrome-for-testing/<version>/` (on macOS the
+  quarantine attribute is cleared on that directory only) and recorded in `installed.json`.
+- **Used automatically for extension work:** while dev extensions are registered, a
+  branded Chrome pick (`cdpilot browser chrome`, or `auto` with Chrome the only
+  extension-capable choice) becomes Chrome for Testing, with one stderr line saying so.
+  Without CfT installed, `ext-install` on Chrome prints the install command and keeps
+  Vivaldi/Brave as the alternative. `cdpilot browser chrome-for-testing` selects it
+  always. An explicit `CHROME_BIN` is never replaced.
+- It runs with cdpilot's usual per-project isolated profile (`profile-cft`).
+- **It is for extension development and testing — not a stealth browser.** cdpilot
+  makes no anti-bot claims for it; use your regular browser setup for that.
+- **Linux (Ubuntu 23.10+):** AppArmor blocks unprivileged user namespaces, and CfT
+  (unlike the distro's Chrome package) has no profile allowing them, so it exits at
+  start. cdpilot prints this hint; allow them with
+  `sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0`.
+
 ## Installation
 
 ```bash
@@ -86,6 +126,37 @@ npx cdpilot launch    # Start browser with CDP enabled
 npx cdpilot status    # Check connection
 ```
 
+### Claude Code plugin marketplace
+
+Install cdpilot's MCP server and its skill straight into Claude Code, no
+`.mcp.json` editing required:
+
+```bash
+/plugin marketplace add mehmetnadir/cdpilot
+/plugin install cdpilot@cdpilot
+```
+
+This registers the `cdpilot` MCP server (`npx cdpilot mcp`) and a short skill
+that teaches Claude Code when and how to reach for cdpilot's commands. See
+[`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json) and
+[`plugins/cdpilot/`](plugins/cdpilot/).
+
+### MCP Bundle (.mcpb)
+
+For MCP clients that support one-click local server installation (Claude
+Desktop and others), download the `.mcpb` file attached to the
+[latest release](https://github.com/mehmetnadir/cdpilot/releases/latest) and
+open it, or build it yourself:
+
+```bash
+npm run build:mcpb   # writes cdpilot.mcpb at the repo root
+```
+
+The bundle still needs the same runtime on the machine that runs it: Node.js
+18+, Python 3.10+, and Brave/Chrome/Chromium installed. See
+[`manifest.json`](manifest.json) for the bundle's MCP Bundle manifest
+([spec](https://github.com/modelcontextprotocol/mcpb)).
+
 ### Upgrading from 0.4.x → 0.5.0 — read this first
 
 **One breaking change**, the rest is additive.
@@ -144,6 +215,86 @@ cdpilot scroll-to <selector>  # Scroll element into view
 cdpilot drag <from> <to>      # Drag and drop
 ```
 
+A real mouse click (inside a frame, or `--entropy=on`) whose target moves or gets covered while the button is held is not clicked again by script: `click` prints `Pressed (released elsewhere, not clicked): …` and ends with **exit 3** (pressed, release missed the target, not clicked; `1` stays "error"). A target the page replaced or navigated away from on mousedown prints `Pressed (the page replaced or left it, not clicked): …` and exits 0. MCP (`browser_click`, `browser_smart_click`) returns `isError: false` with a first line `{"clicked": false, "reason": "moved"|"gone"|"unknown"}`. `batch` and `run` finish every step, then exit 1 if a step failed, else 3 if a click was not clicked, else 0.
+
+### Element targeting inside iframes
+
+Card forms (Stripe/iyzico-style), embedded login widgets and the reCAPTCHA
+checkbox live inside `<iframe>`s. Name the frame chain before the element
+selector with `>>>`, or pass `--frame`:
+
+```bash
+# Payment-style page: the card fields are inside <iframe id="card" title="Secure card payment">
+cdpilot fill  "iframe#card >>> input[name=cardnumber]" "4242424242424242"
+cdpilot type  --frame "#card" "input[name=cvc]" "123"
+cdpilot click "iframe[title='Secure card payment'] >>> button#pay-btn"
+
+# Nested frames: outermost first
+cdpilot click "iframe.checkout >>> iframe.card >>> button"
+
+# --frame <selector|index|url-substring>, nestable with >>>
+cdpilot click --frame 0 "button.submit"                   # first iframe (same order as `frame list`)
+cdpilot fill  --frame "url=js.stripe.com" "input[name=cardnumber]" "4242424242424242"
+cdpilot frame list --frame "#card"                        # iframes inside that frame
+cdpilot frame eval --frame "#card" "document.title"       # runs in the frame's own page context
+```
+
+- Works for `click`, `fill`, `type`, `submit`, `hover`, `dblclick`, `rightclick`,
+  `smart-click`, `smart-fill`, `smart-select` and `frame list|eval|shadow`.
+- A frame hop is a CSS selector, a 0-based index, a `name`/`id`, or
+  `url=<src substring>`. `--frame` also takes a bare `src` substring.
+  `>>>` inside quotes or `[...]` is literal. A selector that matches an
+  element *wrapping* an iframe (Stripe's `#card-element`) enters the iframe
+  inside it and says so on stderr:
+  `note: '#card-element' is not an iframe; using the iframe inside it`.
+- Selectors and texts that already contain `>>>` keep working: when the part
+  before the first `>>>` finds no iframe in the page, or a segment is empty
+  (`click "Next >>>"`), the whole string is used as written, exactly as
+  before. If that fails too, one stderr line explains:
+  `note: 'Home' matched no iframe; used the selector as written`.
+  `--frame` never falls back: a frame it cannot find is an error (exit 1).
+- For `smart-click` / `smart-fill` / `smart-select` the part before the first
+  `>>>` is a frame only if it looks like a selector (it has `#`, `.` or `[`,
+  or starts with an `iframe`/`frame` tag) or is `url=…`; words stay text.
+  `smart-click "Main >>> Settings"` clicks the page's "Main >>> Settings"
+  link even when a `<main>` element holds an iframe. For a frame index or a
+  bare name use `--frame`.
+- Same-origin **and cross-origin** frames work, including out-of-process
+  iframes (site isolation): cdpilot resolves each hop over CDP
+  (`DOM.describeNode` → frame id → the frame's execution context, or
+  `Target.attachToTarget` with a flat session for an out-of-process frame),
+  never through `contentDocument`, which the browser blocks cross-origin.
+- Inside a frame, `click` and `smart-click` are real mouse input
+  (`isTrusted: true`), like `hover`, `dblclick`, `rightclick` and
+  `--entropy=on` clicks; an element with no box falls back to a script click.
+  Mouse input is dispatched at page coordinates: each frame's offset and scale
+  (`transform: scale()`, `zoom`) in the page is applied automatically, so the
+  browser hit-tests into the right frame. Before pressing, cdpilot checks the
+  point (`elementFromPoint` in each document on the way); if something covers
+  the target, such as a cookie banner, it clicks the target by script instead
+  and says so on one stderr line (`note: … is covered by div#cookie at the
+  click point; used a script click`). cdpilot's own input blocker (`show on`,
+  MCP sessions) lets only cdpilot's click through, for the click itself.
+- `smart-click` / `smart-fill` / `smart-select` look in the page first and
+  compare texts with whitespace collapsed (`&nbsp;` and line breaks count as
+  one space). An enabled page element whose text or label contains the whole
+  query is used. If the page's only such elements are disabled, the command
+  fails as before (`no enabled element matches …`) without looking in frames.
+  Otherwise the visible frames are searched breadth-first for a whole-query
+  match (at most 20 frames, and 2 s for all of the search's CDP calls) and the
+  match is reported on stderr:
+  `smart-click: matched inside frame iframe#card (https://…)`. The search only
+  looks (no click, no typing); the command then acts once, in the chosen
+  frame. With no frame match, the page's partial (word) match is used as
+  before. When the 2 s run out:
+  `smart-click: frame search stopped after 2s (3 of 7 frames)`; a frame that
+  had not answered by then has not been touched.
+- `smart-fill` and `smart-select` search automatically only frames of the
+  page's own origin, so a typed value never lands in a third-party frame (an
+  ad, chat or payment widget) by accident; reach a cross-origin frame with
+  `>>>` or `--frame`. `smart-click` searches all visible frames.
+- `frame list` without `--frame` prints the same list as before.
+
 ### Debugging
 
 ```bash
@@ -308,7 +459,8 @@ cdpilot storage               # localStorage contents
 cdpilot upload <sel> <file>   # Upload file to input
 cdpilot multi-eval <js>       # Execute JS in all tabs
 cdpilot headless [on|off]     # Toggle headless mode
-cdpilot frame list            # List iframes
+cdpilot frame list            # List iframes (index = --frame <index>)
+cdpilot frame eval --frame <f> <js>  # Run JS inside an iframe (cross-origin too)
 cdpilot dialog auto-accept    # Auto-accept dialogs
 cdpilot permission grant geo  # Grant geolocation
 ```
@@ -391,6 +543,8 @@ At launch, cdpilot also passes `--disable-blink-features=AutomationControlled`,
 which closes the Blink runtime flag that Cloudflare and DataDome probe to detect
 an automated browser.
 
+Real mouse clicks (frames, `--entropy=on`, `click @ref`, `dblclick`, `rightclick`) hold the button 40-120 ms like a person's press; `CDPILOT_PRESS_MS=min-max` changes the range (`0-0` = instant).
+
 #### Three-tier stealth mode
 
 `cdpilot mode` is the recommended entry point — one switch that sets how much
@@ -434,6 +588,145 @@ cdpilot adaptive clear        # Drop the stealth host memory entirely
 > when it sees one — adds the host to a persistent list, retries once with
 > stealth on. Never auto-demotes. Conservative by design.
 
+### Web Bot Auth (signed agent)
+
+The opposite of stealth. Stealth tries to make the browser look like a person;
+Web Bot Auth says "this is an automated agent, and here is proof of which one".
+Every request the browser makes carries an Ed25519
+[HTTP Message Signature (RFC 9421)](https://www.rfc-editor.org/rfc/rfc9421)
+that a site, or Cloudflare in front of it, checks against a key directory you
+publish on your own domain. The format follows
+[draft-meunier-web-bot-auth-architecture](https://datatracker.ietf.org/doc/draft-meunier-web-bot-auth-architecture/)
+and [draft-meunier-http-message-signatures-directory](https://datatracker.ietf.org/doc/draft-meunier-http-message-signatures-directory/),
+and reproduces the Ed25519 test vectors of Cloudflare's reference
+implementation ([cloudflare/web-bot-auth](https://github.com/cloudflare/web-bot-auth)).
+
+**Optional dependency.** Signing needs the `cryptography` package, for the Python cdpilot runs
+on (`CDPILOT_PYTHON` if you set it):
+
+```bash
+pip install cryptography
+```
+
+Without it, the `bot-auth` commands and `launch --bot-auth` print that hint and exit 2. Every
+other command works as before.
+
+**1. Generate the key** (once):
+
+```bash
+cdpilot bot-auth init --agent-url https://your-domain.com
+```
+
+This writes an Ed25519 private key to `CDPILOT_HOME/bot-auth/ed25519.key` (default
+`~/.cdpilot`), created with mode `0600`. cdpilot never prints or logs the key, and it warns
+when the file is readable by others. The agent URL must be an `https://` origin (no path). A
+second `init` refuses to replace the key unless you pass `--force`, because the new key would no
+longer match the directory you published.
+
+**2. Host the directory on your own domain, signed.** `cdpilot bot-auth directory` prints the
+public key as a JWKS, where `kid` is the key's RFC 7638 JWK thumbprint. Cloudflare also requires
+the directory *response* to be signed, so `--headers` prints the headers to serve with it:
+
+```bash
+cdpilot bot-auth directory --headers        # headers, a blank line, then the JSON body
+cdpilot bot-auth directory --headers --json # the same as {"authority", "headers", "body"}
+```
+
+```
+Content-Type: application/http-message-signatures-directory+json
+Signature-Input: sig1=("@authority";req);created=…;keyid="<thumbprint>";alg="ed25519";expires=…;nonce="…";tag="http-message-signatures-directory"
+Signature: sig1=:<base64 Ed25519 signature>:
+
+{ "keys": [ … ] }
+```
+
+Serve that body at `https://your-domain.com/.well-known/http-message-signatures-directory` with
+those three headers. The signature covers `("@authority";req)`, the host the directory is fetched
+from: by default the agent URL's host, or `--authority <host>`. There is one signature per key in
+the directory. It is valid for 24 hours (`--ttl <seconds>`), so a static host needs it refreshed
+daily, from cron or an edge function that runs the same signing. A cron example that rewrites the
+headers file and the body your web server serves:
+
+```bash
+# m h dom mon dow  — every day at 03:17, 48 h validity so one missed run does not break it
+17 3 * * *  cdpilot bot-auth directory --headers --ttl 172800 --json > /var/www/wba/directory.json.tmp \
+            && mv /var/www/wba/directory.json.tmp /var/www/wba/directory.json
+```
+
+Your server (or an edge function) reads `headers` and `body` from that JSON and serves them at
+the well-known path. `--content-digest` also covers the body (`Content-Digest`, RFC 9530), as
+in Cloudflare's reference vector; then the body must be served byte for byte as printed.
+
+**3. Launch a signing browser:**
+
+```bash
+cdpilot launch --bot-auth        # or: CDPILOT_BOT_AUTH=1 cdpilot launch
+cdpilot status                   # ... bot-auth: on (keyid <thumbprint>)
+cdpilot go https://example.com   # this request is signed, and so is everything after it
+cdpilot stop                     # stops the browser and the signer
+```
+
+`launch --bot-auth` starts a small detached signer next to the browser. It uses the same
+self-fork as the idle-close watcher and lives exactly as long as the browser. It holds one CDP
+connection and auto-attaches to every page, popup, new tab, out-of-process iframe and worker. It
+signs each request at the Fetch "Request" stage, including every redirect hop. So requests the page makes on its own are
+signed as well: timers, `fetch()` after your cdpilot command has returned, a tab the page opens.
+`data:`, `blob:` and `chrome-extension:` requests never leave the browser, so they pass through
+unchanged. If signing a request fails, that request goes out unsigned, one line is written to
+`CDPILOT_HOME/bot-auth/signers/<port>.log` (host only), and the page is never held up. Running
+`launch --bot-auth` against a browser that is already up adds the signer to it.
+
+Each request gets three headers:
+
+| Header | Value |
+|--------|-------|
+| `Signature-Agent` | `"https://your-domain.com"` |
+| `Signature-Input` | `sig1=("@authority" "signature-agent");created=…;keyid="<thumbprint>";alg="ed25519";expires=…;nonce="…";tag="web-bot-auth"` |
+| `Signature` | `sig1=:<base64 Ed25519 signature>:` |
+
+`expires` is `created` + 5 minutes. The `nonce` is 64 random bytes, base64-encoded, and new for
+every request.
+
+This is the **legacy** `Signature-Agent` form (draft-05 A.2.3), and it is the default because it
+is the form Cloudflare's verifier accepts: Cloudflare rejects the dictionary form of later drafts.
+To send the dictionary form instead (`Signature-Agent: sig1="https://your-domain.com"`, covered as
+`"signature-agent";key="sig1"`), run `cdpilot bot-auth format dict` (`bot-auth format legacy`
+switches back, `bot-auth format` shows it, `bot-auth init --agent-format dict` sets it at
+creation). It applies from the next `launch --bot-auth`.
+
+**What is not signed.** WebSocket handshakes are not signed: the browser does not pass them
+through CDP's `Fetch` domain, so a `wss://` connection the page opens goes out without the
+headers. Service-worker-internal cache hits and `data:`/`blob:` URLs never reach a server.
+
+**If the signer dies or hangs.** While it runs, the signer holds every request of the browser at
+the Fetch stage until it has added the headers. If it is killed, requests go out unsigned; `cdpilot
+status` and `cdpilot go` then print one stderr line (signer not running, requests go out unsigned,
+run `cdpilot launch --bot-auth` again) until you do, or `stop`. If it is frozen (a
+stopped process, a debugger), requests hang: `cdpilot stop` and `launch --bot-auth` again.
+cdpilot trusts its signer state only for the process whose command line is that port's signer and
+only for the browser it attached to, so a stale state file whose pid was reused by another program
+is dropped, never signalled.
+
+**Idle close** still works while the signer runs: the signer is attached to every page, so instead
+of "a page is attached" cdpilot counts the CDP clients other than the signer (by socket owner:
+`netstat` on macOS and Windows, `ss` on Linux), and a `watch` daemon or a Playwright session keeps
+the browser open. On Linux, `ss -tnp` shows only your own processes' sockets, so a client running
+as another user is not counted and idle close may close the browser under it.
+
+**Stealth conflict.** Signing says "I am an agent", and stealth says "I am not". If you pass
+`--bot-auth` together with `--stealth`/`--undetected`, or while `cdpilot mode` is `stealth` or
+`undetected`, cdpilot prints one warning line and applies bot-auth. While the signer runs, no
+stealth script or user-agent override is injected, and adaptive escalation does not retry at a
+stealth tier.
+
+**Register with Cloudflare.** Once the directory is live, submit it through the Bot Submission
+Form in the Cloudflare dashboard as a *signed agent* (an agent acting for its users) or a
+*verified bot*; see Cloudflare's
+[signed agents](https://blog.cloudflare.com/signed-agents/) and
+[verified bots with cryptography](https://blog.cloudflare.com/verified-bots-with-cryptography/)
+posts. Sites behind Cloudflare then see your requests as coming from your agent. Sites that
+don't check Web Bot Auth ignore the headers.
+
 ### Friction Ladder (progressive anti-bot detection)
 
 Real sites don't just throw a CAPTCHA — they stack defenses incrementally.
@@ -562,7 +855,8 @@ Earlier figures on this page (sannysoft 24/24, intoli 6/6) were measured on v0.4
 
 ```bash
 cdpilot browser [name|auto]   # workload-aware browser selection
-cdpilot health                # JSON: alive, port, tabs, browser, today's crashes
+cdpilot browser install chrome-for-testing   # for extension development (see above)
+cdpilot health                # JSON: alive, port, tabs, browser, today's crashes, idle close
 ```
 
 `cdpilot health` is designed for shell watchdogs:
@@ -584,6 +878,33 @@ Lifecycle, status and configuration commands (`launch`, `stop`, `close`,
 `mcp`, `serve`, …) never launch. `CDPILOT_NO_AUTOLAUNCH=1` restores the old
 "CDP connection error. Is the browser running?" error and exit code 1.
 
+**Idle auto-close.** A browser that a page command auto-launched, or that the
+MCP server launched (`browser_launch` included), closes itself after
+**15 minutes** without a cdpilot command or a visible page change, so a
+finished agent task does not leave it holding memory. An explicit CLI
+`cdpilot launch` stays open (you may be browsing in it by hand) unless you ask:
+`cdpilot launch --idle-close 30` or `CDPILOT_IDLE_CLOSE=30`. The env var also
+sets the auto-launch delay (read when the browser starts; fractions allowed);
+`0` turns idle close off. A browser you started yourself, or one cdpilot merely
+attached to, is never closed.
+
+What counts as use: any cdpilot command except the read-only checks (`status`,
+`health`, `projects`, `version` — a `cdpilot health` watchdog loop does not keep
+the browser alive), MCP tool calls, `serve` requests, a CDP client still
+attached to a page (a long-running command, `watch`, Playwright via
+`connectOverCDP`), and any change in the open pages' URLs or in the set of
+tabs (someone navigating, a tab opened or closed). Title changes do not count,
+so a page that rewrites its own title (a clock, an unread counter) cannot keep
+the browser alive. `cdpilot status` and
+`cdpilot health` show `idle close in 12m` or `idle close off`.
+
+How: every command stamps `~/.cdpilot/projects/<id>/last-activity`; the launch
+starts a small detached watcher (one per port, no console window on Windows)
+that checks every ≤30 s, stops the browser like `cdpilot stop`, marks it
+stopped in the registry and exits — it also exits as soon as the browser is
+gone for any other reason. Browsers started by `serve --api` are managed by the
+server and have no idle close.
+
 **Timeouts.** Any command takes `--timeout <seconds>`, before or after the
 command name, or a default from `CDPILOT_TIMEOUT` (the flag wins; `0`
 disables). It bounds the whole command's wall-clock: on expiry cdpilot prints
@@ -600,6 +921,198 @@ CDPILOT_TIMEOUT=60 cdpilot run flow.cdp   # default for every command (and each
 For `mcp` and `serve` the value is not applied to the long-running server
 itself; it is passed on to every tool call / request it runs.
 
+### Session log
+
+Every command (and every MCP tool call) appends one JSON line to a local,
+per-project log, so when a browser task is done there is a record of what was
+done and found. Nothing leaves the machine.
+
+```bash
+cdpilot log                 # today's commands: time, exit, command, url, result
+cdpilot log --md            # Markdown report: pages visited, actions, errors, files produced
+cdpilot log --json          # raw lines (one JSON object per command)
+cdpilot log --days 3        # include the last 3 days
+cdpilot log --path          # where the files are
+```
+
+Each line has `ts`, `cmd`, `args`, `exit`, `duration_ms`, the page `url` and
+`title` after the command (when the command already had them), a ~200-char
+`summary` of its output, the `error` line, and `files` it wrote (screenshots,
+PDFs). Files live in `~/.cdpilot/projects/<project-id>/log/<YYYY-MM-DD>.jsonl`.
+
+Redaction happens before anything is written: values given to `fill`, `type`,
+`smart-fill`, `smart-select`, `assert-value` and `dialog prompt` become
+`«redacted:N chars»`; so do values of password/token/key/secret/cookie/auth
+flags and headers, token-shaped arguments, and URL query/fragment values whose
+names contain token, key, secret, password, auth, code or session. `cookies`
+and `storage` output is never logged; `eval` source is, with string literals
+over 40 chars cut and secret-looking ones replaced. Logging is best effort: it
+never changes a command's output or exit code, and a failed write costs one
+stderr line. `CDPILOT_LOG=0` turns it off; `CDPILOT_LOG_DAYS` (default 14)
+sets how many days are kept. The MCP server exposes it as `browser_log`.
+
+### Use your own browser (human-in-the-loop)
+
+An agent hits a CAPTCHA or a login wall it cannot get past. A person solves it,
+and the agent carries on in the same browser.
+
+**The simplest way needs no `connect`.** cdpilot's own browser is a normal,
+visible window unless you launch it headless (`cdpilot headless on` /
+`CHROME_HEADLESS=1`). The person solves the CAPTCHA or logs in right there, and
+the agent continues:
+
+```bash
+cdpilot go https://example.com/dashboard   # agent: "captcha detected" / login wall
+cdpilot captcha-wait 300                   # agent waits while the person solves it
+cdpilot go https://example.com/dashboard   # agent continues in the same window
+```
+
+That window uses cdpilot's own profile, so the login stays for later runs.
+
+**`connect` is for a browser you start yourself**, with a debugging port and
+your own profile directory (log into it once; it keeps its cookies):
+
+```bash
+# macOS
+"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
+  --remote-debugging-port=9450 --user-data-dir="$HOME/cdpilot-chrome"
+# Linux
+google-chrome --remote-debugging-port=9450 --user-data-dir="$HOME/cdpilot-chrome"
+# Windows
+"%ProgramFiles%\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9450 --user-data-dir="%USERPROFILE%\cdpilot-chrome"
+
+cdpilot connect 9450          # or: cdpilot connect ws://127.0.0.1:9450/devtools/browser/<id>
+cdpilot connect --auto        # or: find it via a DevToolsActivePort file
+cdpilot go https://example.com/dashboard
+cdpilot disconnect            # forget it; the browser keeps running
+```
+
+Since Chrome 136, `--remote-debugging-port` is ignored on the default profile,
+so the separate `--user-data-dir` is required. `connect --auto` reads the
+DevToolsActivePort file of each known profile directory (`~/cdpilot-chrome`
+from the command above, Chrome stable/beta/dev/canary, Chromium, Brave,
+Vivaldi, Edge), skips files left over from a browser that is gone or was
+replaced on that port (the browser id in the file must match), and connects to
+the first live one. It asks over HTTP only; a WebSocket probe (which Chrome's
+chrome://inspect mode may answer with a permission prompt) is sent only when no
+live browser was found.
+
+**Not supported yet: Chrome's `chrome://inspect/#remote-debugging` toggle**
+(Chrome 144+, your everyday logged-in profile). In that mode Chrome answers
+only on its WebSocket (`/json/version` and `/json` return 404) and may ask you
+to allow every new debugging connection, while cdpilot lists tabs over `/json`
+and opens a new connection per command. `connect --auto` recognises the mode
+and exits with code 2 and the start command above instead of half-working.
+
+**What cdpilot does with a connected browser:**
+
+- Page commands (`go`, `click`, `fill`, `shot`, …) run in a tab cdpilot opens
+  for itself in a new window that does not take the focus
+  (`Target.createTarget` with `newWindow` + `background`, so your window and
+  tab keep it) on the first page command, and keep using that tab. `close`,
+  `session-close` and the idle session cleanup close only such tabs, the ones
+  cdpilot opened in this browser run, never the last one. Your own tabs are
+  never navigated or typed into; only a command that names a tab touches it
+  (`switch-tab`, `close-tab <index|id>`, `CDPILOT_TARGET`, and `multi-eval`,
+  which runs its script in every open tab).
+- It never closes or kills the browser. `close`, `close --force`, `stop`,
+  `stop --smart [--force]`, `project-stop`, `stop-all`, `session-close` and MCP
+  `browser_close` close at most cdpilot's own tabs (above) and print
+  "connected browser left running; run `cdpilot disconnect` to forget it".
+  The idle auto-close never touches it,
+  `tabs --reap` closes nothing, `wipe`, `permission`, `cookies load` and `cf-replay` are refused (add `--allow-external` to load/replay cookies anyway),
+  `context close` only destroys a context `context create` made, and `launch` /
+  MCP `browser_launch` start nothing.
+- `close-tab` is an explicit command and **can close your tabs**: the active
+  (cdpilot) tab with no argument, or any tab you name by index or id. It never
+  closes the last tab, which would quit the browser on Windows and Linux.
+- It injects nothing into it: no stealth patch or user-agent override (whatever
+  `cdpilot mode` / `stealth` says), no glow, no input blocker, no dev-extension
+  scripts, no auto-cookie restore.
+- The registration stays until you run `cdpilot disconnect`. If the browser is
+  closed, page commands exit 1 with "your connected browser is gone; run
+  `cdpilot connect` again or `cdpilot disconnect`", and cdpilot never launches a
+  browser in its place.
+- `connect` refuses when this project already has a browser cdpilot launched
+  ("stop it first (`cdpilot stop`) or use another project"), and only
+  `127.0.0.1` / `localhost` is accepted (anything else exits 2). `disconnect`
+  also stops this project's `watch` daemon.
+- cdpilot treats a browser as its own only with proof: the browser id it
+  recorded at `launch` (or, for older entries, a live recorded pid that holds
+  the debug port). A busy port is not proof, so a leftover registry entry never
+  makes `stop` / `close` touch your own Chrome on port 9222.
+
+**Risks:**
+
+- Every cdpilot command, and any agent that can run cdpilot, can read and act
+  with the cookies and sessions of that profile (mail, banking, admin panels).
+  Use a profile that is logged into only what the task needs.
+- The debugging port is open to every local program for as long as that browser
+  runs, not just to cdpilot. Close the browser when you are done.
+- Sites can tell automation more easily: cdpilot applies no stealth to a
+  connected browser.
+- cdpilot's tab sits next to yours in the same window, and an agent may
+  still act in one of your tabs when it names it (`switch-tab`,
+  `close-tab <n>`, `multi-eval`).
+
+### WebMCP tools (opt-in)
+
+[WebMCP](https://webmachinelearning.github.io/webmcp/) lets a page register
+"tools" on `document.modelContext`: imperatively with `registerTool()`, or
+declaratively with `<form toolname tooldescription>` (inputs described by
+`toolparamdescription`). cdpilot lists and calls them through the browser's own
+API, `getTools()` and `executeTool()`. In Chrome the API is behind
+`chrome://flags/#enable-webmcp-testing` (Chromium 146+), so start the browser
+with it:
+
+```bash
+cdpilot launch --webmcp        # saved for this project: later launches (auto-launch too) keep it
+cdpilot go https://example.com/shop
+cdpilot tools list             # name, title, description, annotations, input schema
+cdpilot tools list --json
+cdpilot tools call add_to_cart '{"sku":"A1","qty":2}'
+cdpilot tools call add_to_cart --arg sku=A1 --arg qty=2
+cdpilot launch --no-webmcp     # turn it off again (applies at the next start)
+```
+
+- `launch --webmcp` adds `--enable-features=WebMCP` to the browser's command
+  line and saves the mode next to the stealth mode (`webmcp.json` in the
+  project profile); `CDPILOT_WEBMCP=1|0` overrides it. `cdpilot status` shows a
+  WebMCP line while the mode is on.
+  Chrome reads feature flags only at startup: a browser that is already running
+  keeps its flags until `cdpilot stop`.
+- `tools list` shows the tools of the page and of its same-origin iframes
+  (with the frame URL), marks form tools and whether the form submits itself
+  (`toolautosubmit`), and shows `title` and the `readOnlyHint` /
+  `consequentialHint` / `untrustedContentHint` annotations. Nothing is injected
+  into the page: the list is the browser's registry at that moment, so it
+  follows reloads and navigations. Both commands run in cdpilot's own isolated
+  world (no `Runtime.enable`), so a page script that wraps `getTools()` /
+  `executeTool()` cannot add tools, change results or see the calls; only if
+  that world cannot see `document.modelContext` does cdpilot use the page's
+  main world, and it says so on stderr. With no tools it says why (WebMCP not
+  enabled in the running browser, not a secure context, browser too old,
+  document not origin-keyed, or the page registered none) and exits 0.
+- `tools call` checks the arguments against the tool's `inputSchema` first
+  (`required`, `type` — `true` is not an integer —, `enum`, `const`, nested
+  `properties` and `items`; other keywords are left to the page) and exits 1
+  on a mismatch, an unknown tool or a tool error. It passes an `AbortSignal`
+  and aborts it when `--timeout` (default 20 s) runs out, then exits 124
+  with `timed out after <N>s (--timeout); its execution was aborted`. The
+  signal fires at the `--timeout` deadline; the watchdog waits 3 s more so
+  that report is printed.
+  A form tool without `toolautosubmit` waits for a person to submit the form.
+  When several frames register the same name, `--frame <url-part>` picks one
+  (an exact frame URL wins); without it the top document's tool is used, and
+  if there is none the call stops and lists the frames.
+- MCP: `browser_site_tools` and `browser_site_tool_call` are listed only while
+  the project's WebMCP mode is on (or `CDPILOT_WEBMCP=1` for the server).
+
+> **Security**: `tools call` runs the page's own code, and tool names,
+> descriptions and results are page content: treat them as untrusted.
+> Arguments and results are written to the session log with secret-named
+> fields (password, token, key, secret, auth, ...) redacted at any depth.
+
 ### Scaling & Workstation Use
 
 ```bash
@@ -663,6 +1176,9 @@ print(result.stdout)
 | `CDPILOT_OFFSCREEN` | `0` | Headed but render off-screen — no window steals focus |
 | `CDPILOT_TIMEOUT` | unset | Default `--timeout` in seconds for every command (flag wins, `0` disables); expiry exits 124 |
 | `CDPILOT_NO_AUTOLAUNCH` | `0` | `1` = page commands fail with the old "Is the browser running?" error instead of launching the browser |
+| `CDPILOT_IDLE_CLOSE` | `15` | Minutes without a cdpilot command or page change before a browser cdpilot launched closes itself (fractions allowed, `0` = never; read at launch). Default applies to auto-launch and MCP launches; an explicit CLI `launch` is off unless this is set or `--idle-close <min>` is given |
+| `CDPILOT_LOG` | `1` | `0` = do not write the session log (`cdpilot log`) |
+| `CDPILOT_LOG_DAYS` | `14` | Days of session log to keep; older day files are deleted on the first write of a day (`0` keeps all) |
 
 ## How It Works
 
@@ -823,10 +1339,10 @@ The only browser MCP with built-in test assertions. Here's what we've shipped an
 - [x] **Data extraction** (`extract`) — structured DOM data in text, JSON, or list format
 - [x] **Page observation** (`observe`) — list all interactive elements with available actions
 - [x] **Script runner** (`run`) — execute `.cdp` script files with pass/fail reporting
+- [x] **iframe targeting** — `"iframe#card >>> input"` / `--frame` for element commands, same-origin and cross-origin (out-of-process) frames; smart commands search frames automatically
 
 ### Coming Soon
 
-- [ ] **iframe** support — interact with elements inside iframes (Shadow DOM traversal already shipped in smart commands)
 - [ ] **Multi-instance pool** (`CDPILOT_POOL_SIZE`) — N independent browser processes with least-loaded dispatch
 - [ ] **Session recording & replay** — record browser sessions and replay them deterministically
 - [ ] **Stealth mode** *(Pro)* — human-like mouse/typing, anti-fingerprint, CAPTCHA solving