cdpilot 0.9.3 → 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,8 @@ 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
@@ -191,9 +264,17 @@ cdpilot frame eval --frame "#card" "document.title"       # runs in the frame's
   (`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.
-- Real mouse input (`hover`, `dblclick`, `rightclick`, `--entropy=on` clicks)
-  is dispatched at page coordinates: the frame's offset in the page is added
-  automatically, so the browser hit-tests into the right frame.
+- 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
@@ -462,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
@@ -505,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.
@@ -633,6 +855,7 @@ 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 browser install chrome-for-testing   # for extension development (see above)
 cdpilot health                # JSON: alive, port, tabs, browser, today's crashes, idle close
 ```
 
@@ -728,6 +951,168 @@ 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