pi-agent-browser-native 0.9.6 → 0.9.7

package/docs/COMMAND_REFERENCE.md

@@ -28,15 +28,45 @@ SDK hosts can supply an awaited [`beforeExecute` callback](TOOL_CONTRACT.md#host
 <!-- agent-browser-capability-baseline:start upstream-baseline -->
 <!-- Generated from scripts/agent-browser-capability-baseline.mjs. Run `npm run docs -- command-reference write` to update. Do not edit manually. -->
 
-This reference is baselined to the locally installed `agent-browser 0.38.1` command/help surface, audited against vercel-labs/agent-browser@aff6125c023b810ea3f2e5deec5379e9a4270bdc. Upstream `agent-browser` remains the source of truth for command semantics; this file is the local fallback for Pi agent sessions where direct binary help is blocked or discouraged.
+This reference is baselined to the locally installed `agent-browser 0.41.0` command/help surface, audited against vercel-labs/agent-browser@1453dd37a40c730fe00f592bc32198a896ff8747. Upstream `agent-browser` remains the source of truth for command semantics; this file is the local fallback for Pi agent sessions where direct binary help is blocked or discouraged.
 
 The lightweight drift check is `npm run verify -- command-reference`. Run it whenever the installed upstream `agent-browser` version changes or this reference is edited.
 
 <!-- agent-browser-capability-baseline:end upstream-baseline -->
 
+### Upstream 0.41.0 rebaseline
+
+The recommended release is the separately installed stock npm `agent-browser@0.41.0`, audited against upstream commit `1453dd37a40c730fe00f592bc32198a896ff8747`. Runtime support still starts at stable 0.35.0 with no upper cap or version-specific emulation. This update crosses [0.39.3](https://github.com/vercel-labs/agent-browser/releases/tag/v0.39.3), [0.39.4](https://github.com/vercel-labs/agent-browser/releases/tag/v0.39.4), [0.40.0](https://github.com/vercel-labs/agent-browser/releases/tag/v0.40.0), and [0.41.0](https://github.com/vercel-labs/agent-browser/releases/tag/v0.41.0).
+
+- Native 0.39.4+ `wait --download <path>` handles downloads that completed before the wait and moves a locally launched browser's downloaded bytes to the requested destination. Native refuses to move files reported by an attached/remote CDP browser. The wrapper still requires on-disk artifact verification; a reported path alone is not success, so supported 0.35.0–0.39.3 natives, which report the path without moving the file, fail as `artifact-missing`. See [native download handling](https://github.com/vercel-labs/agent-browser/blob/1453dd37a40c730fe00f592bc32198a896ff8747/cli/src/native/actions.rs#L11403-L11508).
+- Native daemon shutdown removes its own `<session>.config` along with other daemon files, while retaining `.target` and `.log`. This prevents new configuration-file accumulation; it does not sweep all historical orphans or optimize the wrapper's socket-directory scan. Updating this metadata cannot speed an installation already running 0.41.0. See [file ownership](https://github.com/vercel-labs/agent-browser/blob/1453dd37a40c730fe00f592bc32198a896ff8747/cli/src/session_files.rs#L75-L104) and [shutdown cleanup](https://github.com/vercel-labs/agent-browser/blob/1453dd37a40c730fe00f592bc32198a896ff8747/cli/src/native/daemon.rs#L147-L151).
+- `batch --bail --omit-command` reduces native JSON output by replacing command arrays with original zero-based indexes. It is not secret redaction: returned values and errors can still contain credentials. See the [batch contract](#batch-auth-confirmations-sessions-chat-dashboard-devices-and-setup) for wrapper handling.
+- `network route --body` accepts `--allow-origin <origin>` for cross-origin mock responses and preflights; JSON mock bodies default to `application/json`. For example: `network route https://api.example.com/data --body '{"ok":true}' --allow-origin https://app.example.com`. Native owns CORS behavior; see [the route parser](https://github.com/vercel-labs/agent-browser/blob/1453dd37a40c730fe00f592bc32198a896ff8747/cli/src/commands.rs#L3392-L3415).
+- Auto-discovered `./agent-browser.json` cannot set `executablePath`, `args`, or `plugins`; native warns and ignores those fields. User config, environment, CLI flags, or explicitly selected `--config ./agent-browser.json` retain their native authority. This is upstream config loading, not a new Pi wrapper restriction. See [native config precedence](https://github.com/vercel-labs/agent-browser/blob/1453dd37a40c730fe00f592bc32198a896ff8747/cli/src/flags.rs#L368-L424).
+- Native 0.40+ state restoration uses origin-scoped DevTools storage writes rather than page-script setters and writes an origin only while the page stays on it. `state load` reports `skippedOrigins`; `session info` reports `restoreSkippedOrigins` for automatic restore and launch-time `--state`. Default wrapper text shows a nonempty `skippedOrigins` list after `State loaded` and includes `restoreSkippedOrigins` in `session info` runtime metadata; `details.data` and explicit `--json` keep the native fields. Inspect skipped origins instead of assuming every saved origin restored. See [storage restoration](https://github.com/vercel-labs/agent-browser/blob/1453dd37a40c730fe00f592bc32198a896ff8747/cli/src/native/state.rs#L463-L543) and [restore reporting](https://github.com/vercel-labs/agent-browser/blob/1453dd37a40c730fe00f592bc32198a896ff8747/cli/src/native/actions.rs#L7529-L7590).
+- Native 0.41 adds finite `mcp call <tool>` invocations and `@agent-browser/sandbox/mcp-tools.json`. **This extension does not support non-help MCP invocations**, including `mcp call`; its current validation rejects them. Session identity, cross-session coordination, credential presentation, and image handling remain unresolved. See the [MCP boundary](TOOL_CONTRACT.md#native-mcp-boundary), not a promise of wrapper support.
+- Crossed upstream fixes also cover auth-key preservation, copied-profile crash prompts, process-identity cleanup, Windows output capture, high-DPI/element screenshots, wedged tabs, and pinned-tab ownership. Those are upstream fixes, not wrapper emulation or full Windows qualification. The upstream `@agent-browser/eve` extension's 0.41 tool renaming does not rename this package's Pi tools.
+
+### Upstream 0.39.2 rebaseline
+
+The CLI trust, engine, and transport behavior added across 0.38.2–0.39.2 remains part of the recommended native release.
+
+- CLI HTTPS requests from `read`, `install`, `upgrade`, and `doctor` now support `--ca-cert <path>` on every platform, `--use-system-ca` / `AGENT_BROWSER_USE_SYSTEM_CA` / native config `useSystemCa` for OS roots, and `SSL_CERT_FILE` as a fallback CA file. Certificate and hostname verification stay enabled. These options do not configure remote CDP/provider TLS or extend Linux Chromium's browser CA support to other platforms. See [trust options](#browser-launch-and-runtime-flags).
+- `--engine obscura` selects a separately installed experimental engine. Its accessibility, iframe, and screenshot gaps are not Chrome parity. Keep Chrome as the default; inspect the [Obscura limits](#obscura-engine-experimental) before choosing it.
+- Native 0.39.1+ does not replay mutating or launch requests after any request bytes were sent and the response was lost. A failed native JSON envelope with `code: "outcome_unknown"` means the command may have run, not that it failed without effects. Inspect the same session's URL, fresh snapshot, and relevant application state before deciding whether to repeat it. The wrapper adds no transport retry.
+- Native 0.39.2 rejects hidden, disabled, and off-viewport click/double-click targets instead of reporting false success. Use `scrollintoview <selector>` and fresh refs before clicking an offscreen control; a native success still needs application-state verification. Ambiguous stale-ref recovery now fails rather than selecting another element.
+- `--args` / `AGENT_BROWSER_ARGS` preserve commas and negative coordinates inside values. Newlines separate arguments; a comma separates them only before another flag. For example, `"--window-position=-1920,-100\n--disable-features=Translate,HttpsUpgrades"` keeps both values intact.
+- Upstream fixes auth-vault hidden-duplicate targeting, CDP attachment persistence, related target/session invalidation, paused network requests, blocked main-document redirects, and invalid/unreadable policy files failing closed. `--auto-connect` can wait up to 30 seconds for Chrome's remote-debugging approval prompt; it does not bypass that prompt.
+- Provider updates remain upstream-owned: Browser Use Cloud V4 adds `BROWSER_USE_PROFILE_ID`, `BROWSER_USE_PROXY_COUNTRY`, and `BROWSER_USE_ENABLE_RECORDING`; Kernel's named-profile fix adds `KERNEL_PROFILE_SAVE_CHANGES` to opt into saving changes. No provider credentials or paid cloud launches are needed for ordinary local qualification.
+
+```json
+{ "args": ["--use-system-ca", "read", "https://example.com"] }
+{ "args": ["--use-system-ca", "false", "read", "https://example.com"] }
+```
+
 ### Upstream 0.38.1 rebaseline
 
-The recommended release keeps the stable 0.35.0 floor. New options require an upstream release that provides them; the wrapper adds no version-specific emulation.
+These observation options arrived in 0.38 and remain available on the recommended release. New options require an upstream release that provides them; the wrapper adds no version-specific emulation.
 
 - `snapshot --delta` returns a nested `snapshot` object: `kind: full` includes `tree`, `refs`, and `revision`; `unchanged` includes `baseRevision` and `revision`; `delta` also includes ref `changes` and an exact `treeChange` line splice. `snapshot --delta --full` resets the native baseline. The wrapper preserves this payload and shows revisions rather than reporting an empty page. Partial results trigger a full native snapshot read for wrapper ref checks without advancing the delta baseline; there is no wrapper revision cache. Wrapper-only search/filter/viewport/diff options use a full tree instead of native delta output.
 - Surviving DOM elements retain refs across same-document snapshots. Navigation and replaced page/iframe documents invalidate them. Keep refreshing after page changes; persistent refs do not remove page-target checks or same-batch mutation boundaries.
@@ -92,7 +122,7 @@ The 0.35.1 baseline is a bug-fix release with no new commands or flags. Browser-
 The 0.35.0 release is the current runtime floor and adds private proxy CA trust plus one bundled workflow skill.
 
 - `--ca-cert <path>` / `AGENT_BROWSER_CA_CERT` loads a PEM bundle or DER certificate into an isolated NSS trust store for locally launched Linux Chromium. Normal hostname, validity, and unrelated-authority checks remain enabled. Equivalent certificate content reuses Chromium; changed content relaunches it. `--no-ca-cert` / `AGENT_BROWSER_CLEAR_CA_CERT` clears retained trust.
-- Use CA trust only with a fresh managed session. The wrapper treats `--ca-cert` and `--no-ca-cert` as launch-scoped for managed-session planning, disables automatic managed restore when CA trust is enabled, and passes caller-selected certificate paths through unchanged. Upstream rejects CA trust with profiles, CDP/auto-connect, providers, Lightpanda, `--ignore-https-errors`, macOS, or Windows, and requires `certutil` (`install --with-deps` installs it on supported Linux systems).
+- For browser CA trust, use a fresh managed session. The wrapper treats `--ca-cert` and `--no-ca-cert` as launch-scoped for managed browser planning, disables automatic managed restore when CA trust is enabled, and passes caller-selected certificate paths through unchanged. Browser CA trust rejects profiles, CDP/auto-connect, providers, non-Chrome engines, `--ignore-https-errors`, macOS, or Windows, and requires `certutil` (`install --with-deps` installs it on supported Linux systems). CLI HTTPS trust is separate and available on every platform from 0.39.0; see [the current baseline](#upstream-0392-rebaseline).
 - `skills get protected-vercel-deployments --full` loads the bundled short-lived Trusted Sources OIDC workflow. It uses `vc project token` and the `x-vercel-trusted-oidc-idp-token` header, avoids persisting tokens, and hands dashboard-only access-control changes to an authorized human.
 - The release also restores ARM64 build artifacts; no wrapper shim is needed.
 
@@ -175,11 +205,11 @@ The 0.29.1 rebaseline added no new core browser CLI commands. It captured upstre
 The 0.28.0 rebaseline tracks new local/infra upstream surfaces and does not change core browser-command semantics. New agent-facing surface captured by the capability baseline:
 
 - `mcp` starts a local MCP stdio server exposing agent-browser tools. It is intended for external MCP clients that spawn `agent-browser mcp` as a subprocess; an agent inside pi would not normally invoke it, and the wrapper treats it as sessionless (no managed browser session injected).
-- `plugin add <ref>`, `plugin [list]`, `plugin show <name>`, and `plugin run <name> <type>` manage configured plugins in `agent-browser.json` (added from npm or GitHub); all are sessionless in the wrapper.
+- `plugin add <ref>`, `plugin [list]`, `plugin show <name>`, and `plugin run <name> <type>` manage configured plugins (added from npm or GitHub); all are sessionless in the wrapper. Current native defaults `plugin add` to `~/.agent-browser/config.json`; `plugin add <ref> --project` selects `./agent-browser.json`, which must be loaded explicitly with `--config`.
 - `auth login <name> --credential-provider <plugin>` resolves credentials just-in-time from a configured credential plugin (for example, a vault); credentials are not saved locally.
 - `AGENT_BROWSER_PLUGINS` is a JSON plugin registry override.
 
-The wrapper adds no compatibility shim for older upstream releases.
+The wrapper adds no compatibility shim for older upstream releases. Non-help MCP calls currently fail wrapper validation, including the finite forms added later; see the [MCP boundary](TOOL_CONTRACT.md#native-mcp-boundary).
 
 ### Upstream 0.27.3 install-only rebaseline
 
@@ -208,7 +238,7 @@ Ordinary calls share the root Pi parent/subagent browser unless native config, a
 
 A cooperating-process lock covers each direct helper/action sequence or whole code cell, keyed by actual socket context, canonical namespace, and session. Independent identities remain concurrent; direct namespace-wide close barriers matching work. Restart all participants onto the new version. This is not rollback or protection against human/external-client navigation, and separate tool calls still need coordination.
 
-`outputPath` saves result data or recording receipts, including failed recording evidence, through the existing writer. Keep it distinct from browser artifacts; aliasing fails without overwriting the artifact. `timeoutMs` bounds the requested subprocess; managed policy inspection has its separate budget. Unknown mutation outcomes require inspection before retry.
+`outputPath` saves result data or recording receipts, including failed recording evidence, through the existing writer. The visible observation carries the `outputFile` receipt (`status`, `path`, `source`, and `bytes` or `error`), including compacted, `--json`, and `agent_browser_code` results; confirm the save from it instead of reading the full spill. Keep it distinct from browser artifacts; aliasing fails without overwriting the artifact. `timeoutMs` bounds the requested subprocess; managed policy inspection has its separate budget. Unknown mutation outcomes require inspection before retry.
 
 ### Persistent browser code
 
@@ -289,7 +319,7 @@ On a successful first/fresh local wrapper-managed headed launch, including a lau
 
 For local fixtures, remember that `localhost` and `127.0.0.1` are resolved from the browser host, which may differ from the shell that started a temporary HTTP server. `net::ERR_EMPTY_RESPONSE` on `http://localhost:<port>` usually means the browser could not reach that server, not that the page rendered blank. Use a host-reachable HTTP(S) address or a `file://` fixture when upstream browser settings allow it. Local paths, artifact destinations, and top-level `outputPath` are caller-owned and pass through normally.
 
-For an explicit `--session`, content-bearing reads and interactions first run a session-scoped `get url`; missing or stale transcript page state is not trusted, and a failed probe stops the requested content command. Calls to the same canonical namespace/session are serialized through that probe and command. Nested `batch` steps remain unsupported; raw batch command strings mirror upstream's ASCII-space tokenizer, including quoting and backslash handling.
+For an explicit `--session`, content-bearing reads and interactions first run a session-scoped `get url`; missing or stale transcript page state is not trusted, and a failed probe stops the requested content command. When a launch-flagged call targets a confirmed inactive caller-owned session, remembered-tab selection and the page probe wait for the requested command to launch that browser, including after transcript reload. After dispatch, the stopped browser's physical tab and refs are not inherited. Successful commands observe the replacement page; a failed or unobserved launch leaves the target unknown. Flagless calls and running browsers keep their checks. Calls to the same canonical namespace/session are serialized through that probe and command. Nested `batch` steps remain unsupported; raw batch command strings mirror upstream's ASCII-space tokenizer, including quoting and backslash handling.
 
 Temporary HTTP servers and their port/process lifecycle stay outside the native tool. Extension maintainers running real-upstream contract tests can reuse `startAgentBrowserContractFixtureServer()` in [`test/helpers/agent-browser-harness.ts`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/test/helpers/agent-browser-harness.ts) instead of ad-hoc `python3 -m http.server` processes.
 
@@ -313,7 +343,7 @@ Use `vitals [url]` for Core Web Vitals plus React hydration timing when availabl
 { "args": ["pushstate", "/dashboard?tab=settings"] }
 ```
 
-For first-navigation setup, start on `about:blank`, then stage routes, cookies, or init scripts before navigating. The relevant current upstream surfaces are `network route <url> [--abort|--body <json>] [--resource-type <csv>]` and `cookies set --curl <file>`:
+For first-navigation setup, start on `about:blank`, then stage routes, cookies, or init scripts before navigating. The relevant current upstream surfaces are `network route <url> [--abort|--body <json> [--allow-origin <origin>]] [--resource-type <csv>]` and `cookies set --curl <file>`:
 
 ```json
 { "args": ["open"], "sessionMode": "fresh" }
@@ -384,6 +414,8 @@ On tabbed or hidden-DOM pages, `get text <selector>` reads the upstream-selected
 
 ### Run a multi-step flow in one browser invocation
 
+On native 0.40+, add exact `--omit-command` to retain each result's zero-based native `index` instead of echoed `command` arrays. Indexes refer to the original plan, including skipped empty `[]` stdin rows. Raw command arguments still take precedence over stdin. The wrapper restores command attribution internally for ordinary credential redaction, lifecycle/ref state, and artifacts, then omits reconstructed commands from public receipts, JSON, and whole-batch spills.
+
 ```json
 { "args": ["batch"], "stdin": "[[\"open\",\"https://example.com\"],[\"snapshot\",\"-i\"]]" }
 ```
@@ -454,7 +486,7 @@ Call `agent_browser_electron` for lifecycle actions, and `agent_browser` for the
 { "action": "cleanup", "launchId": "electron-…" }
 ```
 
-`electron.status` and `electron.cleanup` take either `launchId`, **`all: true`** (literal boolean) to walk every active wrapper-tracked launch (including dead, failed, or partial records, but excluding cleaned records), or neither when exactly one active launch exists—never both `launchId` and `all`. They can target the current branch-visible launch plus still-owned off-branch launch records by `launchId`; default no-arg calls are intentionally ambiguous when more than one active launch is owned. `/reload` preserves the current branch-visible active Electron launch and its isolated temp `userDataDir` for continuity, and cleans off-branch owned Electron launches. First reuse after reload/resume checks the live app's saved debug endpoint and the exact named upstream connection with `get cdp-url`, without reconnecting or resetting page refs; if cleanup is partial and skips or fails profile removal, the generic temp sweep preserves that `userDataDir` across reload, quit, later temp cleanup, process exit, and stale temp-root pruning after restart. `agent_browser_electron` with `action: "list"` has no timeout field. For `action: "launch"`, flat `timeoutMs` sets host CDP readiness polling to a **15s** default and **120s** cap after target discovery; upstream attach and handoff use separate subprocess budgets. Optional `timeoutMs` on **`status`** applies to each managed-session `get url` / `get title` read and any `get cdp-url` read needed to verify a restored connection (localhost CDP probes stay on a short fixed fetch budget). On **`cleanup`**, it is applied separately to upstream `close` and the initial host process-exit wait, not to the entire teardown; debug-port checks have fixed fetch budgets and profile removal has no configurable deadline; when omitted it follows the implicit session close default (**35s** unless `PI_AGENT_BROWSER_IMPLICIT_SESSION_CLOSE_TIMEOUT_MS` overrides). A successful managed-session close step retires that wrapper-managed session even when host process/profile cleanup remains partial. On **`probe`**, it bounds each underlying upstream read subprocess—omit it to use the normal tool subprocess default, or raise it on slow desktops.
+`electron.status` and `electron.cleanup` take either `launchId`, **`all: true`** (literal boolean) to walk every active wrapper-tracked launch (including dead, failed, or partial records, but excluding cleaned records), or neither when exactly one active launch exists—never both `launchId` and `all`. They can target the current branch-visible launch plus still-owned off-branch launch records by `launchId`; default no-arg calls are intentionally ambiguous when more than one active launch is owned. `/reload` preserves the current branch-visible active Electron launch and its isolated temp `userDataDir` for continuity, and cleans off-branch owned Electron launches. A managed fork `pi restart` keeps every active branch-visible launch and profile for the replacement worker instead of quitting. First reuse after reload/resume checks the live app's saved debug endpoint and the exact named upstream connection with `get cdp-url`, without reconnecting or resetting page refs; if cleanup is partial and skips or fails profile removal, the generic temp sweep preserves that `userDataDir` across reload, quit, later temp cleanup, process exit, and stale temp-root pruning after restart. `agent_browser_electron` with `action: "list"` has no timeout field. For `action: "launch"`, flat `timeoutMs` sets host CDP readiness polling to a **15s** default and **120s** cap after target discovery; upstream attach and handoff use separate subprocess budgets. Optional `timeoutMs` on **`status`** applies to each managed-session `get url` / `get title` read and any `get cdp-url` read needed to verify a restored connection (localhost CDP probes stay on a short fixed fetch budget). On **`cleanup`**, it is applied separately to upstream `close` and the initial host process-exit wait, not to the entire teardown; debug-port checks have fixed fetch budgets and profile removal has no configurable deadline; when omitted it follows the implicit session close default (**35s** unless `PI_AGENT_BROWSER_IMPLICIT_SESSION_CLOSE_TIMEOUT_MS` overrides). A successful managed-session close step retires that wrapper-managed session even when host process/profile cleanup remains partial. On **`probe`**, it bounds each underlying upstream read subprocess—omit it to use the normal tool subprocess default, or raise it on slow desktops.
 
 Explicit-ID `electron.status` labels a cleaned record as historical while measuring PID/port liveness independently. `details.electron.statuses[].userDataDirState` freshly reports the tracked profile path as `present`, `absent` (only ENOENT), or `unknown` (other native `lstat` errors); dangling symlinks are present. This is not an audit of all app residue and does not change stored launch records or cleanup ownership.
 
@@ -515,7 +547,7 @@ For one-call flows, put the click and wait in `batch`; the wait step keeps the s
 }
 ```
 
-A successful wait-based download renders a readable summary such as `Download completed: /tmp/report.csv` and exposes top-level `details.savedFilePath` plus `details.savedFile` for non-batch calls. With current upstream `agent-browser`, `wait --download <path>` may report the requested path before this environment can verify that the file was persisted there. Treat `details.savedFilePath` as upstream-reported metadata unless `details.artifacts[].exists` is true. Upstream tracking: [vercel-labs/agent-browser#1300](https://github.com/vercel-labs/agent-browser/issues/1300).
+A successful wait-based download renders a readable summary such as `Download saved and verified: /tmp/report.csv` and exposes top-level `details.savedFilePath` plus `details.savedFile` for non-batch calls. Native 0.39.4+ handles already-completed downloads and moves their bytes to the requested path for locally launched browsers, but not attached/remote CDP browsers. Treat `details.savedFilePath` as metadata until `details.artifactVerification` verifies the file and `details.artifacts[].exists` is true. A reported-but-missing destination still fails as `artifact-missing`.
 
 ### Download, screenshot, and PDF files
 
@@ -753,6 +785,8 @@ Comboboxes vary by app. For native `<select>` controls, prefer raw `select <sele
 
 A canceled cold-session reopen returns an aborted result with its exact session identity and the consumed reopen marker once the CLI starts. Reload does not repeat that navigation. Cancellation before the attempt leaves the remembered URL pending for the next current-page operation.
 
+An incomparable saved process-start format does not prove a daemon restarted. When its PID and socket still match, the wrapper invalidates old refs and requires a fresh snapshot without reopening the live page or discarding unsaved input. Restored daemon provenance still requires a positive identity match. A restore-disabled session, such as a fresh profile/state launch, can therefore refuse reuse after an update when its saved identity is incomparable; it requires owner-side close and a fresh launch rather than inferring ownership from PID/socket alone.
+
 <!-- agent-browser-playbook:start inspection -->
 <!-- Generated from extensions/agent-browser/lib/playbook.ts. Run `npm run docs -- playbook write` to update. -->
 
@@ -773,7 +807,7 @@ These calls return plain text and stay stateless: the extension does not inject
 - `find <locator> <value> <action> [text]` — Locator types include `role`, `text`, `label`, `placeholder`, `alt`, `title`, and `testid`; selector helpers include `find first <sel>`, `find last <sel>`, and `find nth <n> <sel>`. Role/text filters include `find role <role> --name <name>` and `find ... --exact`. Actions are `click, fill, check, hover, text` only. Prefer `find role` for semantic elements: implicit roles work (`find role heading text --name` for `<h2>`, list/banner landmarks, and similar). Default name matching is a case-insensitive substring; `--exact` makes the accessible name case-sensitive. On misses, upstream 0.32.4+ keeps locator detail such as `Names seen: …` or `No element found: getByRole(...)` instead of a generic flatten.
 - `mouse <action> [args]` — `move <x> <y>`, `down [btn]`, `up [btn]`, `wheel <dy> [dx]`.
 - `set <setting> [value]` — `viewport <w> <h>`, `device <name>`, `geo <lat> <lng>`, `offline [on|off]`, `headers <json>`, `credentials <user> <pass>`, and `set media <features>` (`dark`, `light`, and/or `reduced-motion`).
-- `network <action>` — `network route <url> [--abort|--body <json>] [--resource-type <csv>]`, `network unroute [url]`, `network requests [--clear] [--filter <pattern>] [--type <csv>] [--method <method>] [--status <code|range>]`, `network request <requestId>`, `network har start`, `network har start --content text` (default; embeds text bodies), `network har start --content all`, `network har start --content none`, and `network har stop [path]`. `--resource-type` filters intercepted requests by CDP resource type, such as `script`, `image`, `font`, `xhr`, or `fetch`; request listing filters accept resource types (`xhr,fetch`), methods (`POST`), and statuses (`2xx`, `400-499`). HAR files can include auth headers and bodies—do not share them unredacted. For turning a recording into a reusable API client, load `skills get derive-client`.
+- `network <action>` — `network route <url> [--abort|--body <json> [--allow-origin <origin>]] [--resource-type <csv>]`, `network unroute [url]`, `network requests [--clear] [--filter <pattern>] [--type <csv>] [--method <method>] [--status <code|range>]`, `network request <requestId>`, `network har start`, `network har start --content text` (default; embeds text bodies), `network har start --content all`, `network har start --content none`, and `network har stop [path]`. `--resource-type` filters intercepted requests by CDP resource type, such as `script`, `image`, `font`, `xhr`, or `fetch`; request listing filters accept resource types (`xhr,fetch`), methods (`POST`), and statuses (`2xx`, `400-499`). HAR files can include auth headers and bodies—do not share them unredacted. For turning a recording into a reusable API client, load `skills get derive-client`.
 - `cookies [get|set|clear]` — Manage cookies. Full set form: `cookies set <name> <value> --url <url> --domain <domain> --path <path> --httpOnly --secure --sameSite <Strict|Lax|None> --expires <timestamp>`; also supports `cookies set --curl <file>` for JSON, cURL, or bare Cookie-header bulk imports.
 - `storage <local|session>` — Manage web storage.
 
@@ -886,6 +920,14 @@ Long-running or lifecycle commands should be explicitly paired with cleanup call
 
 ### Batch, auth, confirmations, sessions, chat, dashboard, devices, and setup
 
+Auth profiles are shared in upstream's HOME-level `~/.agent-browser/auth` store:
+`auth save`, `list`, `show`, `delete`, and `remove` do not select a browser, and
+`--session` does not create a separate credential store. Saving a profile alone
+does not log in. `auth login <name>` applies a shared profile to the selected
+browser, preserving an unqualified call's active automatic root or managed session.
+Use distinct auth-profile names for separate accounts; use sessions, persistent
+browser profiles, or `state save/load` to separate cookies and storage.
+
 | Command                                            | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `batch [--bail] ["cmd" ...]`                       | Execute multiple commands sequentially from args or stdin.                                                                                                                                                                                                                                                                                                                                                                                        |
@@ -909,13 +951,13 @@ Long-running or lifecycle commands should be explicitly paired with cleanup call
 | `install --with-deps`                              | Install browser binaries plus Linux system dependencies; exits nonzero when required libraries cannot be installed.                                                                                                                                                                                                                                                                                                                               |
 | `upgrade`                                          | Upgrade `agent-browser` using its detected package manager. Native output is text, even with `--json`; the wrapper displays it with surrounding whitespace trimmed and normal redaction, and exposes it in `details.data`. Caller-requested `--json` stays a parseable result with the text in `data`. Nonzero exits, spawn failures, timeout and cancellation remain failures; failed upgrade stdout and stderr remain available as diagnostics. |
 | `doctor [--fix]`                                   | Diagnose install issues and optionally auto-clean stale files. Use `doctor --offline --quick` for a fast local-only check and `doctor --json` for structured output.                                                                                                                                                                                                                                                                              |
-| `plugin add <ref>`                                 | Add a plugin from npm or GitHub (`<owner>/<repo>` or `@scope/<name>`); writes `agent-browser.json`. Flags such as `--name`, `--capability`, `--global`, and `--no-manifest` shape discovery.                                                                                                                                                                                                                                                      |
+| `plugin add <ref>`                                 | Add a plugin from npm or GitHub (`<owner>/<repo>` or `@scope/<name>`). `--global` (default) writes `~/.agent-browser/config.json`; `--project` writes `./agent-browser.json`, whose plugins load only with explicit `--config ./agent-browser.json`. `--name`, `--capability`, and `--no-manifest` shape discovery.                                                                                                                               |
 | `plugin [list]`                                    | List configured plugins (default subcommand); `{ "plugins": [...] }` is a successful sessionless result.                                                                                                                                                                                                                                                                                                                                          |
 | `plugin show <name>`                               | Show one configured plugin; `{ "plugin": {...} }` is a successful sessionless result.                                                                                                                                                                                                                                                                                                                                                             |
 | `plugin run <name> <type>`                         | Run a `command.run` or custom plugin request over the agent-browser plugin stdio protocol.                                                                                                                                                                                                                                                                                                                                                        |
 | `auth login <name> --credential-provider <plugin>` | Resolve credentials just-in-time from a configured credential plugin (e.g. a vault) instead of saved passwords; pair with `--item <ref>` and optional selector overrides. Credentials are not stored locally.                                                                                                                                                                                                                                     |
 | `mcp --help`                                       | Show MCP server help through the native tool.                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `mcp`                                              | Start a local MCP stdio server for external MCP clients; bare native-tool calls are rejected before spawn. External clients can opt into experimental page tools with `mcp --tools core,webmcp`.                                                                                                                                                                                                                                                  |
+| `mcp`                                              | Native MCP stdio server for external clients; `mcp call <tool>` is the finite native alternative. The wrapper currently rejects every non-help MCP invocation, including finite calls. External clients can opt into experimental page tools with `mcp --tools core,webmcp`; see the MCP boundary.                                                                                                                                                |
 | `profiles`                                         | List available Chrome profiles.                                                                                                                                                                                                                                                                                                                                                                                                                   |
 
 When these commands are invoked through the native `agent_browser` tool, structured diagnostic/status outputs are rendered as compact summaries. `session list` and `state list` keep every upstream row and restore identifier visible. Explicit sessions, state/restore paths, broad state lifecycle commands, config, local files, and launch environment pass through unchanged. Local inspection/setup calls remain sessionless unless you explicitly pass `--session`; browser-backed or context-dependent calls keep normal managed-session behavior when no explicit session is supplied. List-like outputs such as sessions, Chrome profiles, auth profiles, network requests, console messages, and page errors include counts and key fields; large outputs are previewed with a `Full output path:` spill file instead of dumping the entire payload into context. For `network requests`, the wrapper shows a failed-request summary split into actionable versus benign low-impact rows, then status, method, URL, resource/mime type, request id, and, when the installed upstream output includes body-like fields, bounded redacted payload, response, and failure/error snippets. Safe request IDs also produce `details.nextActions` for exact request details, actionable failed-request source lookup candidates, filtered request lists, or starting HAR capture before a repro. If the same session has active wrapper-observed network routes, failed/pending/CORS-looking matched request rows add `details.networkRouteDiagnostics` and executable route-mock next actions before the generic request actions. `data:image` artifact rows are omitted from compact request previews but remain in raw `details.data.requests`. `network request <requestId>` can expose upstream full-detail body fields such as response bodies using the same bounded model-facing preview; its request URL stays diagnostic-only and does not overwrite `details.sessionTabTarget` for later ref guards. Clipboard failures that mention `NotAllowedError` or permission denial are usually browser/OS capability limits, not proof that a read, paste, or page mutation happened; prefer page-native reads (`snapshot -i`, `get text`, `eval --stdin`) or direct typing (`keyboard inserttext` / `keyboard type`) when the workflow allows it, and retry true clipboard flows only from an allowed profile/session on a normal `http(s)` page. Header, cookie, auth, token, and other secret-like fields are not expanded in model-facing text or `details.data`; low-risk primitive storage values may remain visible, while command echoes still redact `--body`, `--headers`, `--password`, proxy credentials, auth-bearing URLs, `clipboard write` text, cookie/storage set values, and bearer/basic credential text in positional arguments. Raw batch row strings receive the same command-aware redaction in visible output and ordered code journals without changing execution argv. Use upstream HAR or full raw details only when complete data is required.
@@ -1003,7 +1045,7 @@ Example config:
 }
 ```
 
-Browser defaults are scoped: global/override `defaultProfile` with `policy: "always"` and a Chrome profile name (not a path), plus `executablePath`, become native subprocess defaults only for automatic root browsers and their helpers when the effective engine is Chrome. Lightpanda omits these wrapper defaults, without changing caller-selected launch settings. Roots have distinct named sessions and restore keys; parents and descendants share one root through `PI_SUBAGENT_ROOT_SESSION_ID`. These defaults never apply to unrelated explicit sessions or Electron launches. Code selecting the ordinary root browser uses the same defaults. Profile paths, other policies, and project-only guidance remain advisory. Native restore keeps cookies/localStorage/sessionStorage, not new IndexedDB, service workers, or memory-only grants; verify app access after a real restart. Avoid global native profile changes or a shared writable profile path; see [shared browser defaults](REFERENCE.md#shared-browser-defaults). Configure profile/executable guidance globally, in trusted project config, or through `PI_AGENT_BROWSER_CONFIG`. Ask the agent to run `profiles` and `doctor` when profile resolution fails, then use the reported Chrome profile directory name, a full profile/user-data directory path if upstream accepts one, or the configured `browser.executablePath` with top-level `sessionMode: "fresh"`.
+Browser defaults are scoped: global/override `defaultProfile` with `policy: "always"` and a Chrome profile name (not a path), plus `executablePath`, become native subprocess defaults only for automatic root browsers and their helpers when the effective engine is Chrome. Lightpanda omits these wrapper defaults, without changing caller-selected launch settings. Roots have distinct named sessions and restore keys; parents and descendants share one root through pi-subagents' equal `PI_INTERCOM_ROOT_SESSION_ID`/`PI_INTERCOM_PARENT_SESSION_ID` (or older `PI_SUBAGENT_CHILD=1` with `PI_SUBAGENT_ROOT_SESSION_ID`). These defaults never apply to unrelated explicit sessions or Electron launches. Code selecting the ordinary root browser uses the same defaults. Profile paths, other policies, and project-only guidance remain advisory. Native restore keeps cookies/localStorage/sessionStorage, not new IndexedDB, service workers, or memory-only grants; verify app access after a real restart. Avoid global native profile changes or a shared writable profile path; see [shared browser defaults](REFERENCE.md#shared-browser-defaults). Configure profile/executable guidance globally, in trusted project config, or through `PI_AGENT_BROWSER_CONFIG`. Ask the agent to run `profiles` and `doctor` when profile resolution fails, then use the reported Chrome profile directory name, a full profile/user-data directory path if upstream accepts one, or the configured `browser.executablePath` with top-level `sessionMode: "fresh"`.
 
 ## Important global flags, config, and environment
 
@@ -1031,13 +1073,14 @@ The extension composes stock `--args --no-startup-window` for local Chrome start
 
 - `--executable-path <path>`: custom Chromium-compatible browser executable, such as Brave/Edge/Arc/Vivaldi when upstream can launch that binary. Environment: `AGENT_BROWSER_EXECUTABLE_PATH`.
 - `--extension <path>`: load browser extensions; repeatable. Environment: `AGENT_BROWSER_EXTENSIONS`.
-- `--args <args>`: browser launch args, comma or newline separated. Chromium switches belong in this value, for example `{ "args": ["--args", "--no-sandbox", "open", "https://example.com"], "sessionMode": "fresh" }`. A bare `--no-sandbox` is diagnosed when it occupies the command slot (unknown command) or an `open` / `goto` / `navigate` option position (ignored by upstream); literal operands in other commands are left alone. For batches, put `--args` before `batch` in top-level `args`, not inside a row. Environment: `AGENT_BROWSER_ARGS`.
+- `--args <args>`: browser launch args, newline separated or comma separated before another flag; commas and negative coordinates inside values stay intact. Chromium switches belong in this value, for example `{ "args": ["--args", "--no-sandbox", "open", "https://example.com"], "sessionMode": "fresh" }`. A bare `--no-sandbox` is diagnosed when it occupies the command slot (unknown command) or an `open` / `goto` / `navigate` option position (ignored by upstream); literal operands in other commands are left alone. For batches, put `--args` before `batch` in top-level `args`, not inside a row. Environment: `AGENT_BROWSER_ARGS`.
 - `--user-agent <ua>`: custom user agent. Environment: `AGENT_BROWSER_USER_AGENT`.
 - `--proxy <server>`: proxy server URL. Environments: `AGENT_BROWSER_PROXY`, `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`.
 - `--proxy-bypass <hosts>`: proxy bypass hosts. Environments: `AGENT_BROWSER_PROXY_BYPASS`, `NO_PROXY`.
 - `--ignore-https-errors`: ignore HTTPS certificate errors. Environment: `AGENT_BROWSER_IGNORE_HTTPS_ERRORS`.
-- `--ca-cert <path>`: trust a PEM bundle or DER certificate in an isolated NSS store for locally launched Linux Chromium. Environment: `AGENT_BROWSER_CA_CERT`. Use `sessionMode: "fresh"`; the wrapper disables automatic managed restore for the CA-enabled session while passing the caller-selected certificate path upstream. Upstream requires `certutil` and rejects profiles, CDP/auto-connect, providers, Lightpanda, `--ignore-https-errors`, macOS, and Windows.
-- `--no-ca-cert`: clear retained CA trust. Environment: `AGENT_BROWSER_CLEAR_CA_CERT`. Use `sessionMode: "fresh"` for wrapper-managed sessions.
+- `--ca-cert <path>`: add a PEM bundle or DER certificate to CLI HTTPS trust on every platform. Environment: `AGENT_BROWSER_CA_CERT`. For `read`, explicit CLI trust is retained per native session through daemon restarts until close; `--no-ca-cert` / `AGENT_BROWSER_CLEAR_CA_CERT` clears it. An unusable explicit file fails; an unusable ambient `SSL_CERT_FILE` fallback is ignored with a warning. CLI trust does not launch a browser or configure remote CDP/provider TLS.
+- `--use-system-ca`: use OS roots instead of built-in Mozilla roots for CLI requests from `read`, `install`, `upgrade`, and `doctor`. Environment: `AGENT_BROWSER_USE_SYSTEM_CA`; native config: `useSystemCa`. A separated `--use-system-ca false` overrides it; `read` retains explicit selections until close. A supplied CA file adds to the selected roots. Certificate and hostname verification remain enabled.
+- Browser CA trust is separate: local Linux Chromium imports `--ca-cert` into an isolated NSS store and requires `certutil`. It rejects profiles, CDP/auto-connect, providers, non-Chrome engines, `--ignore-https-errors`, macOS, and Windows. The wrapper treats `--ca-cert` and `--no-ca-cert` as launch-scoped for managed browsers; use `sessionMode: "fresh"`. Automatic managed restore is disabled for CA-enabled browser sessions, and caller certificate paths pass through unchanged.
 - `--allow-file-access`: upstream capability passed through unchanged from argv or `AGENT_BROWSER_ALLOW_FILE_ACCESS`. Raw `--args` / `AGENT_BROWSER_ARGS`, local file navigation, local-page follow-ups, and caller-selected paths remain upstream-owned. The wrapper adds only its fixed compatibility user-agent argument on eligible new managed launches; it does not clear or replace caller launch settings. Ambiguous page-target transitions still require `get url` before later content calls so the agent cannot silently act on the wrong page.
 - `--hide-scrollbars <bool>`: explicitly show or hide native scrollbars in headless Chromium screenshots.
 - `--headed`: ask upstream to show the browser window. Environment: `AGENT_BROWSER_HEADED`. Use it on the first launch, normally with `sessionMode: "fresh"` when changing an existing managed session. Successful first/fresh local wrapper-managed launches can expose `details.browserWindow.visibility: "unverified"` and a login handoff; attached browsers cannot, but still verify actual OS visibility with the user or screenshot/tab evidence.
@@ -1046,7 +1089,7 @@ The extension composes stock `--args --no-startup-window` for local Chrome start
 - `--cdp <port|url>`: connect through Chrome DevTools Protocol. Use it, `--auto-connect`, or `connect <port|url>` once on a named/fresh session, verify with `get url`, then reuse that session without repeating the attach flag. After a successful attachment the wrapper avoids re-emitting its own compatibility launch argument; caller launch/config/file-access settings remain unchanged. Content-bearing first use is blocked until URL verification; later page reads/interactions live-check the URL because the attached browser can drift externally. `close` clears attachment state.
 - `--color-scheme <scheme>`: `dark`, `light`, or `no-preference`. Environment: `AGENT_BROWSER_COLOR_SCHEME`.
 - `--download-path <path>`: default browser download directory. Environment: `AGENT_BROWSER_DOWNLOAD_PATH`.
-- `--engine <name>`: browser engine, `chrome` by default or `lightpanda`. Environment: `AGENT_BROWSER_ENGINE`. Launch-scoped; use `sessionMode: "fresh"` when changing a managed browser. See [Lightpanda](#lightpanda-engine).
+- `--engine <name>`: `chrome` by default, `lightpanda`, or experimental `obscura`. Environment: `AGENT_BROWSER_ENGINE`. Launch-scoped; use `sessionMode: "fresh"` when changing a managed browser. See [Lightpanda](#lightpanda-engine) and [Obscura](#obscura-engine-experimental).
 
 On Android/Termux, follow the README setup to install the packaged Linux-musl arm64 upstream binary, install Termux's `which`, and expose its launcher as `$PREFIX/bin/chromium`. Prefer that upstream system-browser discovery over ambient `AGENT_BROWSER_EXECUTABLE_PATH`: it survives isolated `HOME` values and works for ordinary native calls. Code retains the selected browser's normal launch configuration. Wrapper-generated Android managed identities use a compact 80-bit digest so ordinary namespaces and fresh rotations fit upstream's Unix socket path.
 
@@ -1055,7 +1098,7 @@ On Android/Termux, follow the README setup to install the packaged Linux-musl ar
 
 ### Lightpanda engine
 
-[Lightpanda 1.0](https://lightpanda.io/blog/posts/lightpanda-1-0) is an optional headless engine, installed separately from this package and `agent-browser`. The [native engine guide](https://github.com/vercel-labs/agent-browser/blob/v0.38.2/docs/src/app/engines/lightpanda/page.mdx) describes setup. Put its `lightpanda` executable on `PATH`; select it with `--engine lightpanda`, `AGENT_BROWSER_ENGINE=lightpanda`, or native config `engine`. Chrome remains the default.
+[Lightpanda 1.0](https://lightpanda.io/blog/posts/lightpanda-1-0) is an optional headless engine, installed separately from this package and `agent-browser`. The [native engine guide](https://github.com/vercel-labs/agent-browser/blob/v0.41.0/docs/content/docs/engines/lightpanda.mdx) describes setup. Put its `lightpanda` executable on `PATH`; select it with `--engine lightpanda`, `AGENT_BROWSER_ENGINE=lightpanda`, or native config `engine`. Chrome remains the default.
 
 ```json
 { "args": ["--engine", "lightpanda", "open", "https://example.com"], "sessionMode": "fresh" }
@@ -1073,6 +1116,30 @@ On Android/Termux, follow the README setup to install the packaged Linux-musl ar
 - Lightpanda 1.0 enforces CORS by default, so cross-origin page `fetch`/XHR can fail where earlier Lightpanda did not. Preserve that protection; navigation is a separate capability.
 - The 1.0 release provides macOS/Linux x86_64/ARM64 binaries (Linux glibc), not native Windows/Android. Remote CDP or WSL is a separate setup, not native-platform qualification. Telemetry is upstream-owned; `LIGHTPANDA_DISABLE_TELEMETRY=true` opts out.
 
+### Obscura engine (experimental)
+
+[Obscura](https://github.com/vercel-labs/agent-browser/blob/v0.41.0/docs/content/docs/engines/obscura.mdx) is an optional separately installed headless engine. Select it with `--engine obscura`, `AGENT_BROWSER_ENGINE=obscura`, or native config `engine`; `--executable-path <path>` can name its binary. Native owns spawning `obscura serve`, CDP connection, and close cleanup. The wrapper uses the existing engine/fresh-session path, not a second driver or automatic fallback.
+
+```json
+{
+	"args": [
+		"--engine",
+		"obscura",
+		"--executable-path",
+		"/path/to/obscura",
+		"open",
+		"https://example.com"
+	],
+	"sessionMode": "fresh"
+}
+```
+
+- Obscura v0.2.2 has known accessible-name, hidden-element, iframe, and screenshot-fidelity gaps. Successful connection or image verification does not establish Chrome parity. Prefer Chrome for tasks depending on those features.
+- Native rejects Chrome profiles, launch `--state`, extensions, headed mode, file access, WebGPU, browser CA trust, Chromium `--args`, and all proxy-bypass settings, including `NO_PROXY` / `no_proxy`, even without a proxy. Remove bypass only when the task does not need it; otherwise use Chrome.
+- Discovery and CDP initialization each have a 10-second deadline with bounded failed-start cleanup. Explicit Obscura launches validate this invocation's resolved bypass settings, including after clearing old settings.
+- Local/private pages require `OBSCURA_ALLOW_PRIVATE_NETWORK=1` before launch. `AGENT_BROWSER_OBSCURA_STEALTH` enables optional native stealth only when the installed Obscura build supports it; accepted values are `1`, `true`, `yes`, and `on`. These are upstream options, not wrapper policy or proof of fidelity.
+- Package Chrome profile/executable defaults are omitted for non-Chrome engines. Caller-selected settings remain untouched. Neither engine is bundled, and optional-engine/provider execution is separate from stock Chrome baseline qualification.
+
 ### Output, provider, policy, and AI flags
 
 - `--json`: JSON output. The wrapper injects this automatically for normal tool execution. Environment: `AGENT_BROWSER_JSON`.
@@ -1083,12 +1150,12 @@ On Android/Termux, follow the README setup to install the packaged Linux-musl ar
 - `--content-boundaries`: wrap page output in boundary markers. Environment: `AGENT_BROWSER_CONTENT_BOUNDARIES`.
 - `--max-output <chars>`: truncate page output to N characters. Environment: `AGENT_BROWSER_MAX_OUTPUT`.
 - `--allowed-domains <list>`: restrict browser and `read` traffic to exact or `*.` wildcard domain patterns. Environment: `AGENT_BROWSER_ALLOWED_DOMAINS`. Use a fresh local Chrome context; upstream 0.32.0 owns containment and incompatible-mode rejection and disables Chromium `RTCPeerConnection` while active. The wrapper passes the setting and result through unchanged.
-- `--action-policy <path>`: action policy JSON file. Environment: `AGENT_BROWSER_ACTION_POLICY`. Explicit policy values also reach internal helpers for the current call. Keep the action-policy path consistent on follow-ups; changing or omitting it can restart the native daemon and discard pending confirmations. The established `--confirm-actions` setting is retained for same-session follow-ups.
+- `--action-policy <path>`: action policy JSON file. Environment: `AGENT_BROWSER_ACTION_POLICY`. Native 0.39.2 denies actions when the selected policy cannot be read or parsed instead of continuing without it. Explicit policy values also reach internal helpers for the current call. Keep the action-policy path consistent on follow-ups; changing or omitting it can restart the native daemon and discard pending confirmations. The established `--confirm-actions` setting is retained for same-session follow-ups.
 - `--confirm-actions <list>`: action categories requiring confirmation. Environment: `AGENT_BROWSER_CONFIRM_ACTIONS`.
 - `--confirm-interactive`: interactive confirmations; auto-denies when stdin is not a TTY. Environment: `AGENT_BROWSER_CONFIRM_INTERACTIVE`.
 - `-p, --provider <name>`: provider such as `ios`, `browserbase`, `kernel`, `browseruse`, `browserless`, or `agentcore`. Environment: `AGENT_BROWSER_PROVIDER`.
 - `--device <name>`: iOS device name. Environment: `AGENT_BROWSER_IOS_DEVICE`.
-- Provider-specific iOS examples from upstream include `agent-browser -p ios device list`, `agent-browser -p ios swipe up`, and `agent-browser -p ios tap @e1`; in pi, pass those tokens through `args` rather than bash. iOS requires external Xcode/Appium setup, and cloud providers (`browserbase`, `kernel`, `browseruse`, `browserless`, `agentcore`) require their upstream accounts, credentials, and provider-specific environment variables. Common provider variables include `BROWSERBASE_API_KEY`, `BROWSERBASE_PROJECT_ID`, `BROWSERLESS_API_KEY`, `BROWSERLESS_API_URL`, `BROWSERLESS_BROWSER_TYPE`, `BROWSERLESS_STEALTH`, `BROWSERLESS_TTL`, `BROWSER_USE_API_KEY`, `KERNEL_API_KEY`, `KERNEL_HEADLESS`, `KERNEL_STEALTH`, `KERNEL_TIMEOUT_SECONDS`, `KERNEL_PROFILE_NAME`, `AGENTCORE_API_KEY`, `AGENTCORE_REGION`, `AGENTCORE_BROWSER_ID`, `AGENTCORE_PROFILE_ID`, `AGENTCORE_SESSION_TIMEOUT`, plus AWS names used by AgentCore such as `AWS_PROFILE`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_REGION`, and `AWS_DEFAULT_REGION`. The wrapper forwards parent environment variables plus provider flags and stays thin; it does not emulate provider setup or cloud browser behavior.
+- Provider-specific iOS examples from upstream include `agent-browser -p ios device list`, `agent-browser -p ios swipe up`, and `agent-browser -p ios tap @e1`; in pi, pass those tokens through `args` rather than bash. iOS requires external Xcode/Appium setup, and cloud providers (`browserbase`, `kernel`, `browseruse`, `browserless`, `agentcore`) require their upstream accounts, credentials, and provider-specific environment variables. Common provider variables include `BROWSERBASE_API_KEY`, `BROWSERBASE_PROJECT_ID`, `BROWSERLESS_API_KEY`, `BROWSERLESS_API_URL`, `BROWSERLESS_BROWSER_TYPE`, `BROWSERLESS_STEALTH`, `BROWSERLESS_TTL`, `BROWSER_USE_API_KEY`, `BROWSER_USE_PROFILE_ID`, `BROWSER_USE_PROXY_COUNTRY`, `BROWSER_USE_ENABLE_RECORDING`, `KERNEL_API_KEY`, `KERNEL_HEADLESS`, `KERNEL_STEALTH`, `KERNEL_TIMEOUT_SECONDS`, `KERNEL_PROFILE_NAME`, `KERNEL_PROFILE_SAVE_CHANGES`, `AGENTCORE_API_KEY`, `AGENTCORE_REGION`, `AGENTCORE_BROWSER_ID`, `AGENTCORE_PROFILE_ID`, `AGENTCORE_SESSION_TIMEOUT`, plus AWS names used by AgentCore such as `AWS_PROFILE`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_REGION`, and `AWS_DEFAULT_REGION`. The wrapper forwards parent environment variables plus provider flags and stays thin; it does not emulate provider setup or cloud browser behavior.
 - `--model <name>`: AI model for `chat`. Environment: `AI_GATEWAY_MODEL`.
 - `-v, --verbose`: show tool commands and raw output.
 - `-q, --quiet`: show only AI text responses.
@@ -1107,6 +1174,8 @@ Standalone `agent-browser` looks for `agent-browser.json` in these locations, fr
 
 Native `session` and `namespace` defaults are honored by ordinary tool calls before implicit-session generation; `sessionName` is only a legacy restore key. Per-call flags override environment, which overrides project/user JSON. `--config` or `AGENT_BROWSER_CONFIG` selects one file instead of merging the discovered files; per-call config also reaches helper subprocesses. Caller-owned native `AGENT_BROWSER_SOCKET_DIR` is honored unless the wrapper-specific socket override is set. Code retains these native defaults while fixing the parent-selected session and namespace for the cell.
 
+Auto-discovered `./agent-browser.json` cannot set `executablePath`, `args`, or `plugins`: native warns and ignores them. Put those values in `~/.agent-browser/config.json`, environment, CLI flags, or explicitly trust the selected file with `--config ./agent-browser.json`. This native rule is separate from Pi's project trust and the package's `.pi/config/...` layers.
+
 Use separated `--config <path>` to load a specific upstream config; upstream 0.33.2 does not recognize `--config=<path>` as the global selector. Browser-backed and sessionless native calls preserve `--config`, `AGENT_BROWSER_CONFIG`, passive project/user config, and other upstream environment exactly as supplied. The Pi-scoped package config under `.pi/config/pi-agent-browser-native/` remains separate. Boolean flags accept optional `true` or `false` values, such as `--headed false`, `--webgpu false`, or `--no-webmcp false`, to override config. Browser extensions from user and project configs are merged rather than replaced.
 
 Other useful environment variables include `AGENT_BROWSER_DEFAULT_TIMEOUT`, `AGENT_BROWSER_AUTOSAVE_INTERVAL_MS`, `AGENT_BROWSER_STREAM_PORT`, `AGENT_BROWSER_STREAM_QUALITY`, `AGENT_BROWSER_STREAM_MAX_WIDTH`, `AGENT_BROWSER_STREAM_MAX_HEIGHT`, `AGENT_BROWSER_IDLE_TIMEOUT_MS`, `AGENT_BROWSER_ENCRYPTION_KEY`, `AGENT_BROWSER_STATE_EXPIRE_DAYS`, `AGENT_BROWSER_IOS_DEVICE`, `AGENT_BROWSER_IOS_UDID`, `AI_GATEWAY_URL`, `AI_GATEWAY_API_KEY`, provider credential names, and AWS credential names when using AgentCore. The upstream child receives the parent environment plus wrapper overrides such as the managed socket directory, clamped default operation timeout, canonical owned-session namespace (including empty default), and Pi-transcript- plus Git-checkout-generation-scoped `AGENT_BROWSER_RESTORE` for wrapper-owned managed sessions (`buildAgentBrowserProcessEnv` in `extensions/agent-browser/lib/process.ts`, ownership carried by the wrapper's typed process options and call-scoped managed-session context). Model-facing output still redacts recognized secret values.
@@ -1138,15 +1207,16 @@ Other useful environment variables include `AGENT_BROWSER_DEFAULT_TIMEOUT`, `AGE
 <!-- agent-browser-capability-baseline:start capability-token-baseline -->
 <!-- Generated from scripts/agent-browser-capability-baseline.mjs. Run `npm run docs -- command-reference write` to update. Do not edit manually. -->
 <details>
-<summary>Generated verifier capability baseline for agent-browser 0.38.1</summary>
+<summary>Generated verifier capability baseline for agent-browser 0.41.0</summary>
 
 This generated block is review data for maintainers. The human-authored reference sections above remain the readable command guide.
 
 #### Source evidence
 
 - repository: `vercel-labs/agent-browser`
-- upstream HEAD: `aff6125c023b810ea3f2e5deec5379e9a4270bdc`
-- upstream package version: `0.38.1`
+- upstream HEAD: `1453dd37a40c730fe00f592bc32198a896ff8747`
+- upstream package version: `0.41.0`
+- inspected: `stock npm agent-browser@0.41.0 tarball and skill-data/`
 - inspected: `agent-browser --version`
 - inspected: `agent-browser --help`
 - inspected: `selected agent-browser <command> --help output`
@@ -1163,19 +1233,28 @@ This generated block is review data for maintainers. The human-authored referenc
 - inspected: `bin/agent-browser.js`
 - inspected: `cli/src/ca_bundle.rs`
 - inspected: `cli/src/commands.rs`
+- inspected: `cli/src/connection.rs`
 - inspected: `cli/src/mcp.rs`
 - inspected: `cli/src/flags.rs`
+- inspected: `cli/src/main.rs`
+- inspected: `cli/src/session_files.rs`
+- inspected: `cli/src/plugins.rs`
 - inspected: `cli/src/read.rs`
+- inspected: `cli/src/tls.rs`
 - inspected: `cli/src/doctor/ffmpeg.rs`
 - inspected: `cli/src/doctor/webgpu.rs`
 - inspected: `cli/src/native/actions.rs`
 - inspected: `cli/src/native/a11y/mod.rs`
 - inspected: `cli/src/native/browser.rs`
+- inspected: `cli/src/native/cdp/obscura.rs`
+- inspected: `cli/src/native/policy.rs`
+- inspected: `cli/src/native/providers.rs`
 - inspected: `cli/src/native/tab_binding.rs`
 - inspected: `cli/src/native/daemon.rs`
 - inspected: `cli/src/native/element.rs`
 - inspected: `cli/src/native/recording.rs`
 - inspected: `cli/src/native/snapshot.rs`
+- inspected: `cli/src/native/state.rs`
 - inspected: `cli/src/native/interaction.rs`
 - inspected: `cli/src/native/screenshot.rs`
 - inspected: `cli/src/native/stream/cdp_loop.rs`
@@ -1184,13 +1263,17 @@ This generated block is review data for maintainers. The human-authored referenc
 - inspected: `cli/src/native/test_fixtures/webmcp_probe.html`
 - inspected: `cli/src/native/webmcp.rs`
 - inspected: `cli/src/output.rs`
-- inspected: `docs/src/app/webgpu/page.mdx`
-- inspected: `docs/src/app/webmcp/page.mdx`
-- inspected: `docs/src/app/network/page.mdx`
-- inspected: `docs/src/app/proxy/page.mdx`
-- inspected: `docs/src/app/selectors/page.mdx`
-- inspected: `docs/src/app/skills/page.mdx`
-- inspected: `docs/src/app/commands/page.mdx`
+- inspected: `docs/content/docs/webgpu.mdx`
+- inspected: `docs/content/docs/webmcp.mdx`
+- inspected: `docs/content/docs/network.mdx`
+- inspected: `docs/content/docs/proxy.mdx`
+- inspected: `docs/content/docs/selectors.mdx`
+- inspected: `docs/content/docs/skills.mdx`
+- inspected: `docs/content/docs/commands.mdx`
+- inspected: `docs/content/docs/engines/obscura.mdx`
+- inspected: `docs/content/docs/providers/browser-use.mdx`
+- inspected: `docs/content/docs/providers/kernel.mdx`
+- inspected: `cli/tests/tls_cli.rs`
 - inspected: `skill-data/derive-client/SKILL.md`
 - inspected: `skill-data/core/SKILL.md`
 - inspected: `skill-data/core/references/video-recording.md`
@@ -1203,7 +1286,6 @@ This generated block is review data for maintainers. The human-authored referenc
 - inspected: `packages/@agent-browser/sandbox/README.md`
 - inspected: `packages/@agent-browser/sandbox/src/shared.ts`
 - inspected: `packages/@agent-browser/sandbox/src/vercel.ts`
-- inspected: `packages/@agent-browser/sandbox/src/eve.ts`
 
 #### Upstream help commands sampled
 
@@ -1271,10 +1353,10 @@ This generated block is review data for maintainers. The human-authored referenc
 
 - Built-in skills: 19 human-doc token(s), 24 upstream token(s)
 - Core page, element, navigation, and extraction commands: 89 human-doc token(s), 94 upstream token(s)
-- Sessions, state, tabs, frames, dialogs, and windows: 28 human-doc token(s), 26 upstream token(s)
-- Network, storage, artifacts, diagnostics, and performance: 62 human-doc token(s), 71 upstream token(s)
-- Batch, auth, confirmations, setup, dashboard, devices, and AI commands: 37 human-doc token(s), 41 upstream token(s)
-- Global flags, config, providers, policy, and environment: 153 human-doc token(s), 120 upstream token(s)
+- Sessions, state, tabs, frames, dialogs, and windows: 30 human-doc token(s), 27 upstream token(s)
+- Network, storage, artifacts, diagnostics, and performance: 63 human-doc token(s), 72 upstream token(s)
+- Batch, auth, confirmations, setup, dashboard, devices, and AI commands: 40 human-doc token(s), 47 upstream token(s)
+- Global flags, config, providers, policy, and environment: 163 human-doc token(s), 130 upstream token(s)
 
 #### Human-authored doc tokens required
 
@@ -1402,6 +1484,8 @@ This generated block is review data for maintainers. The human-authored referenc
 - `session list`
 - `state save <path>`
 - `state load <path>`
+- `skippedOrigins`
+- `restoreSkippedOrigins`
 - `state list`
 - `state show <filename>`
 - `state rename <old-name> <new-name>`
@@ -1426,7 +1510,8 @@ This generated block is review data for maintainers. The human-authored referenc
 ##### Network, storage, artifacts, diagnostics, and performance
 
 - `network <action>`
-- `network route <url> [--abort|--body <json>] [--resource-type <csv>]`
+- `network route <url> [--abort|--body <json> [--allow-origin <origin>]] [--resource-type <csv>]`
+- `--allow-origin <origin>`
 - `network unroute [url]`
 - `network requests [--clear] [--filter <pattern>] [--type <csv>] [--method <method>] [--status <code|range>]`
 - `network request <requestId>`
@@ -1491,6 +1576,7 @@ This generated block is review data for maintainers. The human-authored referenc
 ##### Batch, auth, confirmations, setup, dashboard, devices, and AI commands
 
 - `batch [--bail]`
+- `batch --bail --omit-command`
 - `auth save <name>`
 - `auth save <name> --url <url> --username <user> --password <pass>`
 - `auth save <name> --username-selector <s> --password-selector <s> --submit-selector <s>`
@@ -1520,8 +1606,10 @@ This generated block is review data for maintainers. The human-authored referenc
 - `doctor --webgpu --headed`
 - `doctor --json`
 - `mcp`
+- `mcp call <tool>`
 - `mcp --tools core,webmcp`
 - `plugin add <ref>`
+- `plugin add <ref> --project`
 - `plugin [list]`
 - `plugin show <name>`
 - `plugin run <name> <type>`
@@ -1582,6 +1670,9 @@ This generated block is review data for maintainers. The human-authored referenc
 - `--no-ca-cert`
 - `AGENT_BROWSER_CA_CERT`
 - `AGENT_BROWSER_CLEAR_CA_CERT`
+- `--use-system-ca`
+- `AGENT_BROWSER_USE_SYSTEM_CA`
+- `SSL_CERT_FILE`
 - `--allow-file-access`
 - `AGENT_BROWSER_ALLOW_FILE_ACCESS`
 - `--hide-scrollbars <bool>`
@@ -1601,6 +1692,9 @@ This generated block is review data for maintainers. The human-authored referenc
 - `AGENT_BROWSER_DOWNLOAD_PATH`
 - `--engine <name>`
 - `AGENT_BROWSER_ENGINE`
+- `--engine obscura`
+- `OBSCURA_ALLOW_PRIVATE_NETWORK`
+- `AGENT_BROWSER_OBSCURA_STEALTH`
 - `--input-mode <mode>`
 - `--no-auto-dialog`
 - `AGENT_BROWSER_NO_AUTO_DIALOG`
@@ -1667,11 +1761,15 @@ This generated block is review data for maintainers. The human-authored referenc
 - `BROWSERLESS_STEALTH`
 - `BROWSERLESS_TTL`
 - `BROWSER_USE_API_KEY`
+- `BROWSER_USE_PROFILE_ID`
+- `BROWSER_USE_PROXY_COUNTRY`
+- `BROWSER_USE_ENABLE_RECORDING`
 - `KERNEL_API_KEY`
 - `KERNEL_HEADLESS`
 - `KERNEL_STEALTH`
 - `KERNEL_TIMEOUT_SECONDS`
 - `KERNEL_PROFILE_NAME`
+- `KERNEL_PROFILE_SAVE_CHANGES`
 - `AGENTCORE_API_KEY`
 - `AGENTCORE_REGION`
 - `AGENTCORE_BROWSER_ID`
@@ -1819,6 +1917,7 @@ This generated block is review data for maintainers. The human-authored referenc
 - session help: `--namespace <name>`
 - state help: `save <path>`
 - state help: `load <path>`
+- state help: `elsewhere are skipped and listed`
 - state help: `list`
 - state help: `show <filename>`
 - state help: `rename <old-name> <new-name>`
@@ -1844,6 +1943,7 @@ This generated block is review data for maintainers. The human-authored referenc
 - root help: `network <action>`
 - root help: `--resource-type <csv>`
 - network help: `unroute [url]`
+- network help: `--allow-origin <origin>`
 - network help: `network har start`
 - network help: `network har start --content all`
 - network help: `--content <mode>`
@@ -1915,7 +2015,7 @@ This generated block is review data for maintainers. The human-authored referenc
 
 ##### Batch, auth, confirmations, setup, dashboard, devices, and AI commands
 
-- root help: `batch [--bail]`
+- root help: `batch [options] ["cmd" ...]`
 - root help: `auth save <name>`
 - root help: `auth login <name>`
 - root help: `confirm <id>`
@@ -1932,6 +2032,8 @@ This generated block is review data for maintainers. The human-authored referenc
 - root help: `doctor [--fix]`
 - root help: `profiles`
 - batch help: `--bail`
+- batch help: `--omit-command`
+- batch help: `does not make output safe for secrets`
 - auth help: `--url <url>`
 - auth help: `--username <user>`
 - auth help: `--password <pass>`
@@ -1953,8 +2055,12 @@ This generated block is review data for maintainers. The human-authored referenc
 - auth help: `--credential-provider <p>`
 - auth help: `--no-navigate`
 - mcp help: `agent_browser_open`
+- mcp help: `mcp call <tool>`
+- mcp help: `_meta.agentBrowserVersion`
 - mcp help: `--tools`
 - plugin help: `Add a plugin from npm or GitHub`
+- plugin help: `plugin add writes ~/.agent-browser/config.json by default`
+- plugin help: `--project`
 - plugin help: `credential.read`
 
 ##### Global flags, config, providers, policy, and environment
@@ -2010,6 +2116,9 @@ This generated block is review data for maintainers. The human-authored referenc
 - root help: `--no-ca-cert`
 - root help: `AGENT_BROWSER_CA_CERT`
 - root help: `AGENT_BROWSER_CLEAR_CA_CERT`
+- root help: `--use-system-ca`
+- root help: `AGENT_BROWSER_USE_SYSTEM_CA`
+- core skill full: `SSL_CERT_FILE`
 - root help: `--allow-file-access`
 - root help: `AGENT_BROWSER_ALLOW_FILE_ACCESS`
 - root help: `--hide-scrollbars <bool>`
@@ -2026,6 +2135,12 @@ This generated block is review data for maintainers. The human-authored referenc
 - root help: `AGENT_BROWSER_DOWNLOAD_PATH`
 - root help: `--engine <name>`
 - root help: `AGENT_BROWSER_ENGINE`
+- root help: `--engine obscura`
+- root help: `OBSCURA_ALLOW_PRIVATE_NETWORK`
+- root help: `AGENT_BROWSER_OBSCURA_STEALTH`
+- root help: `BROWSER_USE_PROFILE_ID`
+- root help: `BROWSER_USE_PROXY_COUNTRY`
+- root help: `BROWSER_USE_ENABLE_RECORDING`
 - root help: `--input-mode <mode>`
 - root help: `--no-auto-dialog`
 - root help: `AGENT_BROWSER_NO_AUTO_DIALOG`
@@ -2066,6 +2181,7 @@ This generated block is review data for maintainers. The human-authored referenc
 - root help: `--debug`
 - root help: `AGENT_BROWSER_DEBUG`
 - root help: `--config <path>`
+- root help: `The auto-discovered ./agent-browser.json cannot set executablePath, args or plugins`
 - root help: `AGENT_BROWSER_CONFIG`
 - root help: `AGENT_BROWSER_DEFAULT_TIMEOUT`
 - root help: `AGENT_BROWSER_AUTOSAVE_INTERVAL_MS`

package/docs/ELECTRON.md

@@ -219,7 +219,7 @@ Cleanup partial failures fail the tool result with `failureCategory: "cleanup-fa
 
 For manual launches, close commands (`close`, `quit`, or `exit`) only close the browser/CDP session. Close the app yourself and clean its profile/temp files with normal host tools.
 
-On Pi `quit`, active wrapper-owned Electron launches are best-effort cleaned. On `/reload`, the current branch-visible active Electron launch and its isolated temp `userDataDir` are preserved for continuity while off-branch owned Electron launches are cleaned before process-local ownership is cleared. First reuse after reload/resume checks that the PID and profile are present, the saved browser WebSocket endpoint still matches the live app, and upstream `get cdp-url` points to that browser or one of its current targets. Ordinary browser calls, status reads, and probes share this check under the existing session lock; no reconnect or ref reset is needed. The `get cdp-url` read honors the caller's `timeoutMs` and cancellation, while localhost CDP requests keep their short fixed fetch budgets. Missing or mismatched evidence does not grant reuse, and generic restore-disabled sessions keep their existing rules. If cleanup is partial and skips or fails `user-data-dir` removal because the process or debug port is still live, the generic temp sweep preserves that profile path across reload, quit, repeated temp cleanup, process-exit cleanup, and stale temp-root pruning after restart rather than deleting it out from under the remaining host resource. If `electron.cleanup` closes the attached managed session but host process/profile cleanup is partial, later default browser calls still rotate away from that closed wrapper-managed session. Stale restored records (PID gone, port dead) are **reported** instead of guessed at or killed.
+On Pi `quit`, active wrapper-owned Electron launches are best-effort cleaned. A managed fork restart (`pi restart` or `/restart`, shutdown disposition `handoff` or `provisional`) is not a quit: every active branch-visible launch keeps running with its isolated profile protected through process exit, and the replacement worker restores its ownership from the transcript for later status, probe, and cleanup; off-branch owned launches are cleaned as on `/reload`. On `/reload`, the current branch-visible active Electron launch and its isolated temp `userDataDir` are preserved for continuity while off-branch owned Electron launches are cleaned before process-local ownership is cleared. First reuse after reload/resume checks that the PID and profile are present, the saved browser WebSocket endpoint still matches the live app, and upstream `get cdp-url` points to that browser or one of its current targets. Ordinary browser calls, status reads, and probes share this check under the existing session lock; no reconnect or ref reset is needed. The `get cdp-url` read honors the caller's `timeoutMs` and cancellation, while localhost CDP requests keep their short fixed fetch budgets. Missing or mismatched evidence does not grant reuse, and generic restore-disabled sessions keep their existing rules. If cleanup is partial and skips or fails `user-data-dir` removal because the process or debug port is still live, the generic temp sweep preserves that profile path across reload, quit, repeated temp cleanup, process-exit cleanup, and stale temp-root pruning after restart rather than deleting it out from under the remaining host resource. If `electron.cleanup` closes the attached managed session but host process/profile cleanup is partial, later default browser calls still rotate away from that closed wrapper-managed session. Stale restored records (PID gone, port dead) are **reported** instead of guessed at or killed.
 
 ### `timeoutMs` by action (quick reference)