pi-agent-browser-native 0.9.6 → 0.9.7

package/docs/TOOL_CONTRACT.md

@@ -173,6 +173,24 @@ Use exact labels from the latest snapshot. Return to the model when a fresh obse
 
 `record start` / `restart` accept `--cursor`, `--contact-sheet`, and `--contact-sheet-threshold <n>`. Reported `contactSheetPath` values become image artifacts: pending during capture, checked on disk after stop, and attached when verified. The contact-sheet destination shares the active video's reservation and transcript lifecycle; same-call/batch artifact and `outputPath` aliases are rejected before dispatch. A successful direct `record restart` retains the prior take's known contact-sheet path from the existing reservation, checks it on disk, and labels it unverified because native restart omits terminal sheet evidence. Use `record stop` then a new start when verified completion of both artifacts is required. Video receipt handling remains separate. Without a terminal `previousRecording` receipt, only native `restarted: true` retires the prior take; rejected or pending restarts preserve its reservation and exact stop action. Native `--input-mode <mode>` is a sticky, live-changeable session setting, not a launch flag; per-action pointer options pass through. See the [command reference](COMMAND_REFERENCE.md#upstream-0381-rebaseline).
 
+### Native capability baseline
+
+The recommended separately installed stock native is 0.41.0; stable support still starts at 0.35.0 without an upper cap or version-specific shims. The [0.41.0 guide](COMMAND_REFERENCE.md#upstream-0410-rebaseline) covers crossed native fixes and current integration limits. Native 0.39.2+ rejects hidden, disabled, and off-viewport click/double-click targets. Scroll the intended control into view and refresh refs before retrying; native success alone does not prove the application changed.
+
+`--use-system-ca` accepts an optional separated `true`/`false` and configures CLI HTTPS requests from `read`, `install`, `upgrade`, and `doctor`, not browser launch. `--ca-cert` adds custom roots on every platform for those CLI requests; `SSL_CERT_FILE` is an ambient fallback. Native retains explicit `read` trust choices per session until close, including daemon restarts. Verification stays enabled. Remote CDP/provider TLS is not configured by these options, and browser CA trust remains Linux-Chromium-only.
+
+Experimental `--engine obscura` uses the existing launch-scoped engine path with no bundling or fallback. Accessible-name, hidden-element, iframe, and screenshot fidelity gaps remain upstream-owned; successful connection does not establish Chrome parity. See [setup and limits](COMMAND_REFERENCE.md#obscura-engine-experimental).
+
+A failed native JSON envelope with `code: "outcome_unknown"` means bytes from a mutating/launch request were sent but its response was lost. Native did not retry it; it may have run. Inspect the same session and application state before any repeat. The wrapper preserves the native failure and adds no transport replay or new success category.
+
+Native 0.39.4+ `wait --download <path>` can claim an already-completed download and move its bytes for a locally launched browser; attached/remote CDP paths cannot be moved by this operation. `savedFilePath` remains metadata until `artifactVerification` verifies it, and missing requested output still fails as `artifact-missing`, including on supported 0.35.0–0.39.3 natives that report the requested path without moving the file. Native 0.40+ `state load` and `session info` expose `skippedOrigins` and `restoreSkippedOrigins` respectively when origin storage could not be restored. Default text adds `Skipped storage for origins (page did not stay on that origin): …` after a nonempty `state load` result and includes `restoreSkippedOrigins` in the `session info` runtime metadata; `details.data` and explicit `--json` keep the native fields. The wrapper does not replay skipped values into another origin.
+
+### Native MCP boundary
+
+Native 0.41 `mcp call <tool> '<json>'` is a finite one-shot command, including JSON-stdin input and versioned `_meta.agentBrowserVersion` output. Native MCP stdio can also process a finite input stream. Those upstream capabilities are distinct from this extension's direct browser tools.
+
+The current wrapper validation rejects **all non-help `mcp` invocations**, including finite `mcp call` and stdin-driven MCP; only `mcp --help` / `mcp -h` passes through. Its existing error describes server startup and does not distinguish the finite forms. This is an integration limitation, not an upstream inability or a new authorization rule. Transparent inner session identity, cross-session coordination, command-specific secret presentation, and MCP image delivery are not integrated. Use ordinary `agent_browser` commands or a separately configured external MCP client; no MCP support is claimed here.
+
 <a id="wrapper-json"></a>
 
 ## Wrapper `--json`
@@ -185,7 +203,9 @@ The extension prepends `--json` to normal browser commands when the caller does
 
 Explicit `--json false` selects native text, including native batch output. Optional booleans use upstream's last-occurrence-wins semantics; `--json` and `--json true` select JSON. Caller argv/stdin, config, and environment remain unchanged. Native text is retained as a redacted string, including leading/trailing whitespace and line breaks, even when it resembles JSON or a confirmation banner. Inline data, complete spills and output exports preserve that whitespace. Success means the process completed successfully; nonzero exit, stderr errors, timeout, cancellation, and spawn failure remain failures. Text does not supply trusted batch rows, pending confirmations, lifecycle, page-target or artifact receipts. URL-shaped page content cannot replace the session target; only structured native observations can establish it. Saved-output notices stay prose and never parse native text as JSON, including when an export fails. Native confirmation enforcement and visible confirm/deny instructions remain upstream-owned; the wrapper never auto-confirms. Use JSON mode when structured evidence is required. Helpers that need structured state continue requesting and strictly parsing JSON. Explicit `--action-policy`, `--confirm-actions`, `--debug` and `--no-auto-dialog` selections reach those helpers within the current call, including CLI boolean `false` over true config/environment defaults; the established `--confirm-actions` setting is retained in the existing session lifecycle state for same-identity helpers and follow-ups, including exact confirm/deny actions, code/advanced calls and resume. First launch and new explicit `--confirm-actions` / `--config` selections use native argv → environment → config precedence. Bare follow-ups retain selected strings, including explicit `""`, over ambient environment/discovered-config edits. Native unset is not pinned and continues native default resolution. Native compound confirmations remain pending until every required action is decided; pending navigation never becomes an observed page target, including native batch rows. Completed non-read confirmation results establish their resulting page target before ordinary follow-ups. Successful close retires the setting; replacement cleanup uses the old identity's setting and preserves continuity if close fails; Electron launch and host helpers use the same selected setting. Definitely unestablished attempts (wrapper rejection, native CLI parse/config failure or local inspection) restore the prior setting when no earlier browser helper could have established the request; unknown/interrupted dispatch retains selected intent. Other settings remain call-scoped and must stay consistent to avoid native daemon replacement.
 
-Empty stdin batch rows (`[]`) pass through and are skipped by native execution; `[""]` remains a failing command. Native bail behavior and later reached rows remain intact. When an upstream process exits nonzero with stderr instead of an envelope, stderr is the primary error and `failureCategory` is `upstream-error`; `details.parseError` retains secondary diagnostics. Zero-exit malformed machine output still fails strict JSON parsing.
+Empty stdin batch rows (`[]`) pass through and are skipped by native execution; `[""]` remains a failing command. Native bail behavior and later reached rows remain intact. When an upstream process exits nonzero or is terminated by a signal instead of returning an envelope, `failureCategory` is `upstream-error`; visible diagnostics retain the exit code, observed signal, redacted stderr, and secondary parse error even when stdout and stderr are empty. SIGKILL or exit 137 includes a possible-OOM/external-stop hint, not a claim that OOM was proven. Zero-exit malformed machine output still fails strict JSON parsing.
+
+Native `batch --omit-command` (0.40+) returns `{ index, success, result? | error? }` rows instead of `command` arrays. The zero-based `index` addresses the original input plan, not the compact returned array: empty `[]` stdin rows are skipped without renumbering. Exact `--bail` and `--omit-command` are options, not raw commands; any actual raw command arguments still override stdin. The same command-specific redaction applies to content, JSON, per-step details, exports, and complete spills. Internally restored argv is redacted before canonical lifecycle/ref replay and `outputPath` recording-receipt selection use it, then removed from every returned `batchSteps[].command` and `batchFailure.failedStep.command`, including browser-state persistence failures; indexed prose identifies steps by index rather than echoing argv. Artifact requests remain aligned to returned rows, whose positions exclude skipped empty inputs. Recording receipt recovery uses that same alignment, preserving unrelated step artifacts and later-recording follow-ups.
 
 ## Experimental WebMCP
 
@@ -233,11 +253,11 @@ URL-less `open` is executed as native `get url`, including effective raw/stdin b
 - Do not assume Playwright selector dialects such as text=Close or button:has-text('Close') are supported wrapper syntax unless current upstream agent-browser behavior has been verified.
 - For authenticated or user-specific content explicitly requested by the user, such as feeds, inboxes, account pages, or private dashboards, use a real profile only when the user/config asks for it or profiles have been inspected; do not assume --profile Default exists on every machine. Do not use a real profile for public pages just because they are dashboards. Treat visible page content from real profiles as model-visible transcript data. On macOS, copied Chrome profiles may omit encrypted cookies, so profile selection alone is not proof of authentication; verify the target page and use a user-approved headed login once when needed. Use --auto-connect only if profile-based reuse is unavailable or the task is specifically about attaching to a running debug-enabled browser. If profile/user-data-dir resolution fails, stop retrying opens, run profiles and/or doctor through agent_browser, then report what the user needs to configure.
 - Ordinary bare calls share one native browser within your root Pi parent/subagent group; unrelated roots browse independently. Coordinate multi-call navigation inside your group with existing subagent/intercom tools. Explicit native session defaults still win. Pi quit does not close group browsers; never close an unrelated browser.
-- When using launch-scoped flags (--auto-connect, --allowed-domains, --namespace, --cdp, --ca-cert, --no-ca-cert, --enable, --engine, --executable-path, --webgpu, --no-webmcp, --init-script, --idle-timeout, --args, --user-agent, --headed, --device, --profile, --provider, -p, --session-name, --restore, --restore-save, --restore-check-url, --restore-check-text, --restore-check-fn, --state), put them on the first command for that session. If you intentionally use an explicit --session, keep using that same explicit session for follow-ups.
+- When using launch-scoped flags (--auto-connect, --allowed-domains, --namespace, --cdp, --ca-cert, --no-ca-cert, --enable, --engine, --executable-path, --webgpu, --no-webmcp, --init-script, --idle-timeout, --args, --user-agent, --headed, --device, --profile, --provider, -p, --session-name, --restore, --restore-save, --restore-check-url, --restore-check-text, --restore-check-fn, --state), put them on the first command for that session. If you intentionally use an explicit --session, keep using that same explicit session for follow-ups. If you already used the implicit session and now need launch-scoped flags, retry with top-level sessionMode set to fresh or pass an explicit --session for the new launch; never pass --session-mode inside args. After a successful unnamed fresh launch, later auto calls follow that new session.
 - Cooperating Pi processes serialize each complete browser operation and code cell by native socket context, namespace, and session, including target/ref helpers and state updates. Different identities remain concurrent; namespace-wide close waits for matching operations. All participating Pi instances must load this release; humans, third-party clients, and older extensions are outside that coordination. It is not a transaction or rollback. For raw batches whose later content depends on navigation, use exact batch --bail or split the calls.
 - After a successful `connect`, `--cdp`, or enabled `--auto-connect` call, verify with get url and keep using the resulting session without repeating the attach flag. The wrapper remembers that attachment across active-branch reload/resume and live-checks the URL before later page reads/interactions because an attached browser can drift externally; caller config, file access, launch arguments, and environment pass through unchanged. A successful close clears the marker. When several named sessions share one Chrome, pass --pin-tab once (AGENT_BROWSER_PIN_TAB) so a closed bound tab fails as tab_gone instead of acting on a neighbor; recover with tab new or tab list. --no-pin-tab turns the sticky pin off. tab list includes each tab's CDP targetId, accepted as a tab ref.
-- If you already used the implicit session and now need launch-scoped flags (--auto-connect, --allowed-domains, --namespace, --cdp, --ca-cert, --no-ca-cert, --enable, --engine, --executable-path, --webgpu, --no-webmcp, --init-script, --idle-timeout, --args, --user-agent, --headed, --device, --profile, --provider, -p, --session-name, --restore, --restore-save, --restore-check-url, --restore-check-text, --restore-check-fn, --state), retry with top-level sessionMode set to fresh or pass an explicit --session for the new launch; never pass --session-mode inside args. After a successful unnamed fresh launch, later auto calls follow that new session.
-- Chrome is the default. Use separately installed Lightpanda only when explicitly selected with --engine lightpanda, environment or native config; --engine is launch-scoped, so use sessionMode:fresh to change a managed browser. Lightpanda text-rendered screenshots do not prove graphical layout/visibility or mouse coordinates. Chrome profiles, headed mode, multi-tab, WebGPU and native WebMCP are not parity capabilities; choose Chrome explicitly when needed, never assume automatic fallback.
+- Chrome is the default. Select separately installed Lightpanda or experimental Obscura explicitly with --engine lightpanda|obscura, environment or native config; use sessionMode:fresh to change a managed engine. Lightpanda text-rendered screenshots never establish graphical layout or mouse coordinates. Obscura has accessibility, iframe and screenshot gaps; read its command-reference limits first. Profiles, headed mode, multi-tab, WebGPU and WebMCP are not parity capabilities; choose Chrome when needed, never assume automatic fallback.
+- For CLI HTTPS trust on read/install/upgrade/doctor, use --ca-cert <path> or --use-system-ca; --use-system-ca false disables OS roots and SSL_CERT_FILE is a fallback. These do not disable certificate verification or configure remote CDP trust. Browser CA trust remains Linux-Chromium-only and launch-scoped.
 - For WebGPU pages, use args ["--webgpu", "open", "<url>"] on a fresh local browser launch; use doctor --webgpu (or --headed on Linux/Windows capture paths) to prove rendering before trusting a non-black screenshot. WebGPU cannot be combined with --cdp, --auto-connect, or provider launches unless --webgpu false overrides an enabled config/environment default.
 - For experimental WebMCP page tools, use webmcp list, then webmcp invoke <tool> with --params and optional --frame/--detach/--timeout; use webmcp result or cancel for detached calls. Locally managed Chrome enables WebMCP by default; a positive navigation hint means the page has tools to list. --no-webmcp is launch-scoped and requires a fresh session; invoke/result/cancel can mutate or navigate, so refresh snapshot refs afterward.
 - For --allowed-domains, use a fresh local Chrome context. Upstream rejects CDP/auto-connect, profiles, restore/state replay, direct-page providers, iOS/Safari, and startup/profile Chrome args because they cannot guarantee containment; Chromium also disables RTCPeerConnection while the allowlist is active.
@@ -245,7 +265,7 @@ URL-less `open` is executed as native `get url`, including effective raw/stdin b
 - For first-navigation setup, use open without a URL plus network route --resource-type <csv>, cookies set --curl <file>, or --init-script/--enable before navigate/opening the target page.
 - For stateful browser context work, use auth save --password-stdin with the tool stdin field for credentials, auth list/show/delete/remove for local auth-profile maintenance, auth login when you need the browser to fill a saved profile, and state save/load/list/show/rename/clear/clean for upstream saved-state lifecycle. State paths, restore identifiers, wrapper-prefixed sessions, and all upstream list rows remain available; credential values inside cookie/storage/auth payloads are still redacted from presentation.
 - Upstream restore sessions periodically autosave cookies and localStorage while the browser stays open, including page-driven background changes; AGENT_BROWSER_AUTOSAVE_INTERVAL_MS controls the interval (30000 by default; 0 disables periodic saves but keeps save-on-close), while the never value for --restore-save disables automatic saves for that restore session. For wrapper-owned headed launches, the wrapper defaults the interval to 0 because upstream 0.33.2 collects multi-origin storage through visible temporary tabs, then records and reapplies the effective launch-time value to helpers and follow-ups so daemon configuration remains stable. Native close still saves, but direct window close can lose newer state because upstream exempts headed browsers from idle shutdown; set AGENT_BROWSER_AUTOSAVE_INTERVAL_MS before launch when periodic preservation matters, because changing it on a running wrapper-owned headed session requires close plus a fresh launch.
-- For batch chains that touch cookies, storage, auth, or other secret-bearing commands, use details.batchSteps for per-step artifacts, categories, spill paths, and full structured errors; top-level details.data on batch is only a compact redacted step matrix (success, argv-redacted command, redacted result or scrubbed error text) built from the same presentation rules as standalone calls.
+- For batch chains that touch cookies, storage, auth, or other secret-bearing commands, use details.batchSteps for per-step artifacts, categories, spill paths, and full structured errors; top-level details.data on batch is only a compact redacted step matrix (success, argv-redacted command or native --omit-command index, redacted result or scrubbed error text) built from the same presentation rules as standalone calls. Indexed receipts preserve original input positions, including skipped empty rows, without echoing commands.
 - For non-core families, pass current upstream commands through the native tool directly: network requests, network route <url>, network har start/stop [path], diff snapshot, diff screenshot --baseline <file>, diff url <u1> <u2>, trace start, trace stop [path], profiler start, profiler stop [path], record start <path>, record stop, console/errors [--clear], highlight <selector>, inspect, clipboard read, clipboard write <text>, clipboard copy/paste, stream enable/disable/status, dashboard start/stop, device list for iOS simulator inventory, and chat <message>. For compact network requests output, prefer details.nextActions for request detail, route-mock diagnostics, actionable failed-request agent_browser_network_source, filtering, clearing the aggregate buffer before repro, or HAR capture follow-ups instead of guessing request-id syntax. Artifact-producing commands report details.artifacts and verification state; long-running starts such as stream, dashboard, trace/profiler, and record should be paired with the matching stop/disable command when the task is done; stream enable already-enabled outcomes are treated as idempotent success with status/disable follow-ups.
 - For Electron desktop apps, enable agent_browser_electron through agent_browser_tools for wrapper-owned discovery, isolated launch, status, compact probe, and cleanup: list first, treat likely-sensitive annotations as hints rather than enforcement, launch with the default snapshot handoff unless handoff: "tabs" is the safer diagnostic starting point, use agent_browser_electron probe or snapshot -i/agent_browser_qa attached:true for current-session state, and always cleanup the returned launchId when done. agent_browser_electron launch uses an isolated temporary profile; it does not reuse the app's normal signed-in profile or attach to an already-running authenticated app. For signed-in local app state, host-launch the normal app with --remote-debugging-port when appropriate, then use raw args connect <port|url>; after connect, run get url to verify the active target before page-content reads, inspect tab list, select the stable tab id such as tab t2, verify it again with get url, then run a condition wait or snapshot -i before using refs. close commands (`close`, `quit`, or `exit`) only close the browser/CDP session; leave manually launched app shutdown, profile cleanup, and explicit artifacts to the host owner.
 - For provider or specialized app workflows, load version-matched upstream guidance with skills get agentcore|electron|slack|dogfood|vercel-sandbox|derive-client through the native tool; add --full when you need references/templates, and use skills get --all only for broad skill audits. Use derive-client when recording HAR traffic to generate a standalone API client; prefer network har start (text bodies by default) or network har start --content all|none before multi-step capture. For accessibility audits use a11y or a11y --tags wcag2a,wcag2aa (CDP browsers only). Hosted sandbox workflows should use upstream @agent-browser/sandbox helpers outside this wrapper. Provider launches such as -p ios, --provider browserbase/kernel/browseruse/browserless/agentcore, and iOS --device are upstream-owned setup paths; use sessionMode fresh when switching providers and expect external credentials or local Appium/Xcode setup to be required.
@@ -263,6 +283,7 @@ URL-less `open` is executed as native `get url`, including effective raw/stdin b
 - For evidence-only screenshots, QA captures, or other audit artifacts, save to an explicit path and branch on details.artifactVerification plus details.artifacts before reporting PASS/FAIL; do not require vision review of inline image attachments unless the user asked for visual inspection.
 - Respect explicit user stop boundaries yourself. When the surrounding authenticated employee or automation context is explicitly unattended/auto-approved, ordinary non-destructive form submissions within the requested flow may proceed without separate confirmation. Still require explicit authorization for purchases, production-control actions, destructive or irreversible actions, and account, security, or privacy changes. The wrapper does not infer broad business intent from prompt text; details.promptGuard is reserved for concrete artifact-before-close checks.
 - Recording needs ffmpeg on PATH before start. Current upstream checks it at startup; older natives may defer failure. A pending recording is not verified output.
+- Native 0.41 mcp call and stdin-driven MCP can finish normally, but this wrapper currently rejects all non-help mcp invocations. Session/namespace coordination and credential/image presentation are not integrated; use ordinary agent_browser commands.
 - Do not call --help or other exploratory inspection commands unless the user explicitly asks for them or debugging the browser integration is necessary.
 
 <!-- agent-browser-playbook:end shared-guidelines -->
@@ -473,7 +494,7 @@ For `eval --stdin`, put the script in the top-level `stdin` field. The wrapper n
 - after the upstream command completes, the wrapper writes `details.data` when present, otherwise the model-facing text content; objects/arrays are written as pretty JSON with a trailing newline and strings are written as-is. If a direct `details.data` value, a `batch` row's `result`, or the whole batch is compacted, the wrapper instead reads and serializes each full command-redacted pre-compaction payload only from the corresponding live `spill` entry in its own `details.artifactManifest` (`persistent-session` or `process-temp`). It never writes a compact metadata object as a substitute; any missing, evicted, malformed, or untrusted required spill makes the result fail and leaves `outputPath` unwritten.
 - recording exports use `source: "recording-receipt"` and a JSON envelope containing `success`, `error`, `command`/`subcommand`, native session/namespace, `attempt`, `data`, `artifacts`, `artifactVerification`, and optional `recordingRecovery`. A recovered result may have `success: true` while `attempt.success: false` preserves the timeout/error; saving the receipt file never proves the video succeeded. Preflight failures can export an empty receipt with their failed attempt, without inventing an artifact.
 - `outputPath` must not resolve to the same file as a screenshot, download, recording, or other browser artifact produced by that result, including dangling/existing symlink, hardlink, Unicode-fold, and platform-case aliases. When both destinations are known before launch, preflight rejects the call as `validation-error` without browser activity; if an alias becomes apparent only from the completed result, the writer preserves the browser artifact, rejects the result-data write, and reports `details.outputFile.status: "failed"`
-- successful writes append `details.outputFile = { status: "saved", path, absolutePath, source, bytes }`; they also append a visible `Output file: …` line except when the caller explicitly passed upstream `--json`, where parseable JSON content is preserved and the saved-file notice lives only in `details.outputFile`. Write failures append `details.outputFile.status: "failed"`, remove success-only category fields, and mark the tool result failed without rolling back browser session state.
+- successful writes append `details.outputFile = { status: "saved", path, absolutePath, source, bytes }`; they also append a visible `Output file: …` line except when the caller explicitly passed upstream `--json` or used `agent_browser_code`, where parseable JSON content is preserved. The same redacted `outputFile` receipt is part of the [canonical observation](#canonical-observation), so JSON text, `structuredContent`, and compacted observations keep it ahead of bulky optional fields such as `data`. Write failures append `details.outputFile.status: "failed"` with its error, remove success-only category fields, and mark the tool result failed without rolling back browser session state.
 
 Example:
 
@@ -503,7 +524,7 @@ Example:
 
 ### `sessionMode`
 
-A native `session` default from user/project JSON or `AGENT_BROWSER_SESSION` selects a caller-owned browser for direct, code, action, QA, and source tools. Per-call flags still win. Like literal `--session`, this selection takes precedence over `fresh`; it reports `usedImplicitSession: false` and is not closed when Pi quits. Without a selected native session, attachment, or explicit fresh launch, auto calls select a stable root-Pi named session and root-specific native restore key. `PI_SUBAGENT_ROOT_SESSION_ID` carries the parent identity to descendants; ordinary new/fork/clone roots differ, while resume/cwd changes keep identity. Root sessions report `usedImplicitSession: false` and survive parent/child quit. Global/override package profile names with `policy: "always"` and executable defaults bootstrap only inactive automatic roots whose effective engine is Chrome. Lightpanda receives no wrapper-supplied Chrome profile/executable defaults; caller native args, environment and config remain authoritative. Active roots preserve native launch settings/current restore key, including matching root-name follow-ups; unrelated explicit browsers are unchanged. Profile paths and project-only profile config remain advisory. Native restore covers cookies and web storage, not newly created IndexedDB or memory-only authentication. See the detailed reference for communal bootstrap and persistent-profile fallback. Active older/fresh managed sessions retain the lifecycle below. `agent_browser_qa` with `attached: true` can inspect this shared current session using the same live target checks. See [shared browser defaults](REFERENCE.md#shared-browser-defaults).
+A native `session` default from user/project JSON or `AGENT_BROWSER_SESSION` selects a caller-owned browser for direct, code, action, QA, and source tools. Per-call flags still win. Like literal `--session`, this selection takes precedence over `fresh`; it reports `usedImplicitSession: false` and is not closed when Pi quits. Without a selected native session, attachment, or explicit fresh launch, auto calls select a stable root-Pi named session and root-specific native restore key. Equal `PI_INTERCOM_ROOT_SESSION_ID`/`PI_INTERCOM_PARENT_SESSION_ID` from current pi-subagents, or older `PI_SUBAGENT_CHILD=1` with `PI_SUBAGENT_ROOT_SESSION_ID`, carries the parent identity to descendants; ordinary new/fork/clone roots differ, while resume/cwd changes keep identity. Root sessions report `usedImplicitSession: false` and survive parent/child quit. Global/override package profile names with `policy: "always"` and executable defaults bootstrap only inactive automatic roots whose effective engine is Chrome. Lightpanda receives no wrapper-supplied Chrome profile/executable defaults; caller native args, environment and config remain authoritative. Active roots preserve native launch settings/current restore key, including matching root-name follow-ups; unrelated explicit browsers are unchanged. Profile paths and project-only profile config remain advisory. Native restore covers cookies and web storage, not newly created IndexedDB or memory-only authentication. See the detailed reference for communal bootstrap and persistent-profile fallback. Active older/fresh managed sessions retain the lifecycle below. `agent_browser_qa` with `attached: true` can inspect this shared current session using the same live target checks. See [shared browser defaults](REFERENCE.md#shared-browser-defaults).
 
 - type: `"auto" | "fresh"`
 - optional
@@ -519,6 +540,7 @@ Behavior:
 - upstream `--no-webmcp` is also launch-scoped for bare/`true` and explicit `false` values because it selects whether locally managed Chrome enables the experimental feature
 - upstream restore sessions may periodically save cookies/localStorage while open; an explicit `AGENT_BROWSER_AUTOSAVE_INTERVAL_MS` passes through unchanged when a daemon launches (`30000` upstream default, `0` disables periodic saves but keeps native close saves), while wrapper-owned headed launches default it to `0` when unset to avoid upstream 0.33.2's visible temporary collector tabs; direct window close can lose newer state because headed browsers are exempt from idle shutdown, the effective interval persists across resume and changing it in either direction on a running wrapper-owned headed daemon requires close plus a fresh launch, and those restore files remain upstream-owned rather than wrapper artifacts
 - sessionless paths skip that injection even under `"auto"`: plain-text help/version, read-only skills, local auth/profile/setup commands, `session list`, and syntactically local state lifecycle operations keep `effectiveArgs` free of the implicit managed `--session` unless the caller supplied one. All upstream rows and supported targets remain available. Browser-backed or context-dependent commands such as `auth login` and `state save/load` keep normal managed-session injection when the caller did not choose an explicit session (`extensions/agent-browser/lib/command-policy.ts`, `needsManagedSession`; `extensions/agent-browser/lib/runtime.ts`, `buildExecutionPlan`)
+- `auth save/list/show/delete/remove` maintain upstream's HOME-level `~/.agent-browser/auth` credential store, not a session-specific browser store. An explicit `--session` does not partition those profiles. `auth login <name>` reads the shared profile and applies it to the selected browser; unqualified login keeps the active automatic root or managed session. Saving a profile does not authenticate any browser. Use distinct profile names for different accounts; use browser sessions, persistent profiles, or state save/load for cookie/storage isolation.
 
 Recommended use:
 
@@ -558,7 +580,7 @@ These calls return plain text and stay stateless: the extension does not inject
 
 ### Canonical observation
 
-Direct and advanced results expose the same decision-relevant observation in model-visible JSON or prose; code receives it as data without rendering/reparsing prose. The base is `{ success, resultCategory, data?, error?, summary?, successCategory?, failureCategory? }`; `summary` is omitted when it is byte-identical to `error` so large failure text is not counted twice. Optional fields include exact `nextActions`, warnings, session/namespace, artifact verification, image observations, page-change evidence, timeout partial progress, and QA/source/diagnostic results. Batch observations retain per-step outcomes. Native help/version remains plain text.
+Direct and advanced results expose the same decision-relevant observation in model-visible JSON or prose; code receives it as data without rendering/reparsing prose. The base is `{ success, resultCategory, data?, error?, summary?, successCategory?, failureCategory? }`; `summary` is omitted when it is byte-identical to `error` so large failure text is not counted twice. Optional fields include exact `nextActions`, warnings, session/namespace, artifact verification, the requested `outputPath` receipt (`outputFile`), image observations, page-change evidence, timeout partial progress, and QA/source/diagnostic results. Batch observations retain per-step outcomes. Native help/version remains plain text.
 
 Tool declarations share native Browser namespace metadata and an `outputSchema`. Returned `structuredContent` exposes the same bounded redacted projection, including failed/preparation/cancelled results, rather than raw internal `details`. Oversized observations use the existing compact object and complete redacted spill path. The loader returns `{ inventory, added }`; optional search returns its normalized provider data in the observation's `data`. This supports host-selected native codemode without auto-enabling it, changing advanced activation, or replacing the Browser code VM. Structured image paths/handles are metadata, not native `image()` input; retain verified Pi image blocks and current-cell `emitImage` semantics.
 
@@ -632,7 +654,7 @@ For `agent_browser_code`, the top-level category describes source execution, not
 
 These categories are intentionally bounded and stable so agents can branch on them instead of parsing prose. They do not replace raw diagnostics: `details.error`, `details.stderr`, `details.parseError`, `details.validationError`, and visible content still preserve the specific upstream or wrapper message after normal redaction.
 
-`details.exitCode` preserves the native child close code when available, so it is not a portable timeout indicator: a Windows process stopped with `taskkill` can report `1`. The wrapper uses `124` for its timeout when no native close code is available. Use `failureCategory`, `timedOut`, and `aborted` to distinguish these outcomes.
+`details.exitCode` preserves the native child close code when available, so it is not a portable timeout indicator: a Windows process stopped with `taskkill` can report `1`. The wrapper uses `124` for its timeout when no native close code is available. A signal-terminated child without a numeric code receives the conventional `128 + signal number`, never zero; `details.exitSignal` retains the observed signal separately. Use `failureCategory`, `timedOut`, and `aborted` to distinguish these outcomes.
 
 For argv-supplied `--allowed-domains`, the wrapper treats domain containment as launch-scoped. Upstream owns request, worker, popup, and WebRTC containment plus incompatible-mode rejection; the wrapper passes the setting and upstream result through unchanged.
 
@@ -640,7 +662,7 @@ Final public results return canonical `isError: true` when `resultCategory` is `
 
 For `batch`, top-level `details` still carries `resultCategory` plus `successCategory` or `failureCategory` for the **aggregate** tool outcome: if any step fails, the overall result is a failure (`resultCategory: "failure"`) even when later steps succeed—inspect `batchSteps[]` for per-step outcomes. Each `batchSteps[]` entry includes its own `resultCategory` and either `successCategory` or `failureCategory` for that step. When upstream reports it, successful and failed rows also expose a dedicated `lifecycle` field containing only the bounded `effectiveLaunch.browserLaunched` boolean; on failed rows this preserves launch evidence even though the ordinary result payload is omitted. Live state and transcript replay use that evidence to distinguish a terminal nested close from a post-close browser launch. `batchFailure.failedStep` duplicates the first failing step’s details, including its `failureCategory`, bounded lifecycle evidence, and any `nextActions`.
 
-Top-level `details.data` on `batch` is a compact per-step roll-up (not a verbatim replay of raw upstream batch JSON): each element is `{ success, command, result? | error? }` where `command` is argv-redacted the same way as echoed invocation args (including `clipboard write` text, `cookies set` cookie values, `storage local|session set` values, and other sensitive flags/positionals), `result` is the presentation-layer data for that step after the same structured redaction as non-batch commands, and `error` is failure text with clipboard-write/cookie/storage/password literals stripped when those values appeared in argv. Prefer `batchSteps[]` for full per-step `details` (artifacts, categories, spill paths); use the roll-up when you only need a redacted matrix of what ran. If a large batch/QA result is compacted and spilled, the inline compacted text still includes bounded failed-step context (first failing step, failure category, failure detail, and any failed-step spill path) before the preview and top-level `Full output path:`.
+Top-level `details.data` on `batch` is a compact per-step roll-up (not a verbatim replay of raw upstream batch JSON): each element is `{ success, command, result? | error? }` (or `{ success, index, result? | error? }` with native `--omit-command`) where `command` is argv-redacted the same way as echoed invocation args (including `clipboard write` text, `cookies set` cookie values, `storage local|session set` values, and other sensitive flags/positionals), `result` is the presentation-layer data for that step after the same structured redaction as non-batch commands, and `error` is failure text with clipboard-write/cookie/storage/password literals stripped when those values appeared in argv. Prefer `batchSteps[]` for full per-step `details` (artifacts, categories, spill paths); use the roll-up when you only need a redacted matrix of what ran. If a large batch/QA result is compacted and spilled, the inline compacted text still includes bounded failed-step context (first failing step, failure category, failure detail, and any failed-step spill path) before the preview and top-level `Full output path:`.
 
 `details.refSnapshot` may appear after successful `snapshot` calls and subsequent same-session calls. It records the latest page-scoped ref ids known to the wrapper, optional per-ref accessible `role`/`name` metadata from the same snapshot, and the page target they came from so mutation-prone `@e…` commands can fail fast instead of silently hitting recycled refs after navigation. For wrapper-tracked Electron sessions, `details.electronRefFreshness` may also appear after a successful `@e…` mutation as a softer same-URL rerender warning: run `snapshot -i` before reusing old refs even if the URL did not change.
 
@@ -751,7 +773,7 @@ Additional structured fields can appear when relevant:
 - `promptGuard` when the requested-artifact-before-close guard blocks browser close before required prompt artifact paths are verified; implementation lives in `extensions/agent-browser/lib/orchestration/browser-run/prompt-guards.ts`
 - `overlayBlockers` for conservative overlay/banner/dialog blocker candidates when a successful snapshot itself contains strong modal evidence, or after a qualifying top-level `@e…` / `ref=` click stays on the same URL, no `clickDispatch` diagnostic fired, and a fresh snapshot provides evidence (`candidates`, `summary`, and `snapshot` per `OverlayBlockerDiagnostic` in `extensions/agent-browser/index.ts`). CSS selector clicks do not run this overlay probe.
 - `visibleRefFallback` after a raw `find` or compiled `agent_browser_action` fails with `selector-not-found` and a fresh snapshot finds exact role/name `@ref` matches. Shape follows `VisibleRefFallbackDiagnostic` in `extensions/agent-browser/lib/results/selector-recovery.ts`: `{ candidates, snapshot, summary, target }`, where each candidate has `ref`, `role`, `name`, optional direct ref `args`, and `reason`; visible text appends `Current snapshot ref fallback`. Non-fill candidates with direct args add `try-current-visible-ref` or numbered `try-current-visible-ref-N` actions. Fill candidates omit direct args and target text so recovery details do not repeat potentially sensitive fill text.
-- `browserEventVersion: 1` marks current tool observations; replay authority is the canonical custom journal event, not presentation details. Ordinary commands omit unchanged `refSnapshot`; dedicated snapshot captures retain full membership, accessible metadata, target, snapshot ID and verified native generation when available. A changed or unverifiable generation requires a new complete capture even at the same URL.
+- `browserEventVersion: 1` marks current tool observations; replay authority is the canonical custom journal event, not presentation details. Ordinary commands omit unchanged `refSnapshot`; dedicated snapshot captures retain full membership, accessible metadata, target, snapshot ID and verified native generation when available. A changed or unverifiable generation requires a new complete capture even at the same URL. Incomparable saved/current start formats with the same PID/socket invalidate refs without marking the live daemon cold or reopening its URL. Restored daemon provenance still requires a positive identity match; a restore-disabled session with an incomparable saved identity can refuse reuse until owner-side close and a fresh launch.
 - `refSnapshotInvalidation` after a confirmed cold managed-session shutdown (`reason: "page-transition"`, including when reopening fails), a session `snapshot` fails with `No active page`, any upstream-executed `record start` attempt or URL-bearing `record restart` conservatively invalidates refs (including failures, for older-native protection rather than proof of a page change), a direct or reached batch `window new` / `diff url` attempt changes the page, or a failed non-batch transition command (`eval`, `back`, `forward`, `reload`, `connect`, `state load`, `tab` selection) whose live URL re-verification probe observed the page (a failed transition can still have mutated the document, so the verified URL is kept but the prior refs are not). Shape follows `SessionRefSnapshotInvalidation` in `extensions/agent-browser/lib/session-page-state.ts`: `{ reason: "no-active-page" | "page-transition", summary }`; replay preserves the persisted summary. The wrapper deletes prior refs for that session, persists the invalidation for resume, and blocks mutation-prone `@e…` preflight with `failureCategory: "stale-ref"` until a successful fresh `snapshot -i` records refs again.
 - `snapshotFilter` after wrapper-side `snapshot -i --search <text>` or `snapshot -i --filter role=<role>`. Shape: `{ cleanArgs, search?, role?, matchedRefs, totalRefs, visibleLines, totalLines, renderedTextMatches?, renderedTextTotalMatches?, renderedTextTruncated? }`. Search runs one bounded read-only rendered-DOM probe across the full document; each visible match carries bounded `text`, `tagName`, `kind` (`text` or prioritized `validation`), `offscreen`, optional `role`/accessible `name`, and a unique mapped `ref` when the full snapshot supports it. Hidden elements are excluded. The filtered accessibility snapshot remains separate, while `details.refSnapshot` still records the full upstream ref map for later stale-ref checks.
 - `snapshotViewport` after wrapper-side `snapshot --viewport` (with or without `-i`, `--search`, or `--filter`). Shape matches the scroll-position probe: viewport scroll offsets, inner/document dimensions, sampled scrollable-container count, and bounded container offsets. The wrapper strips `--viewport` before upstream spawn and gathers this with a read-only `eval --stdin` call.
@@ -857,25 +879,26 @@ If `agent-browser` is not on `PATH`, fail with a message that:
 
 ## Session behavior
 
-`session info` is one explicit, read-only preflight, not an automatic probe before every command. Its text distinguishes daemon `active` / `pid` from native `runtime.browser`: `status`, nullable `alive`, Chrome `pid`, exact `userDataDir`, `tabs`, native `ownership` (`launched`, `attached`, `none`, or `unknown`), and `error`. It also preserves native `runtime.recording.current` / `last` receipts and protocol `capabilities`. `data.piCleanupOwnership` separately reports `caller-owned` or `wrapper-managed` from Pi's actual ownership records; an explicit name can still target a wrapper-managed session. The integration does not infer a Chrome PID/profile from config, scan host processes, launch Chrome or change tabs for this preflight. Missing native fields, an active daemon with `runtime: null`, and legacy `browserLaunched` alone do not prove live browser identity. Name-only `session` responses select a session without proving liveness. Restore check URLs, text and code remain omitted from status text.
+`session info` is one explicit, read-only preflight, not an automatic probe before every command. Its text distinguishes daemon `active` / `pid` from native `runtime.browser`: `status`, nullable `alive`, Chrome `pid`, exact `userDataDir`, `tabs`, native `ownership` (`launched`, `attached`, `none`, or `unknown`), and `error`. It also preserves native `runtime.recording.current` / `last` receipts, protocol `capabilities`, and 0.40+ `restoreSkippedOrigins`. `data.piCleanupOwnership` separately reports `caller-owned` or `wrapper-managed` from Pi's actual ownership records; an explicit name can still target a wrapper-managed session. The integration does not infer a Chrome PID/profile from config, scan host processes, launch Chrome or change tabs for this preflight. Missing native fields, an active daemon with `runtime: null`, and legacy `browserLaunched` alone do not prove live browser identity. Name-only `session` responses select a session without proving liveness. Restore check URLs, text and code remain omitted from status text.
 
 - use the root-Pi named browser for ordinary unconfigured calls, with a separate current managed slot for explicit fresh/owned launches
 - keep root identity independent of cwd; generated managed-session bases retain their existing Pi-session/cwd scope
 - respect explicit upstream `--session` and configured native session/namespace defaults with minimal interference; per-call `--config` reaches helpers without changing native precedence
 - treat the extension-managed session as convenience state owned by the wrapper
 - preserve the current branch-visible extension-managed session across `/reload`, exact-session relaunch, `/resume`, and Pi `session_tree` branch transitions so persisted sessions can keep following the live browser after lifecycle changes
-- close the active extension-managed session when the originating `pi` process quits, while leaving explicit caller-provided sessions alone
+- close the active extension-managed session when the originating `pi` process quits, while leaving explicit caller-provided sessions alone; a managed fork restart is not a quit (see below)
 - set one idle timeout on extension-managed sessions as a backstop for abnormal exits or cleanup failures, and pass that same `AGENT_BROWSER_IDLE_TIMEOUT_MS` to top-level commands plus every helper targeting that owned session; caller-owned sessions retain native idle policy so upstream does not restart the background browser, reset the active tab, or discard current refs between a snapshot and action
 - clean up process-private temp spill artifacts on shutdown, while keeping persisted-session snapshot spill files in a private session-scoped artifact directory so `details.fullOutputPath` survives reload/restart and the oldest spill files are evicted if the per-session artifact budget is exceeded
 - reconstruct the current branch-visible extension-managed session, every transcript-proven still-active wrapper-owned identity, latest page-scoped refs, journal-ordered artifact-row changes, and wrapper-tracked Electron launch records from the active transcript branch on `session_start` and Pi `session_tree` so later default and explicit off-current calls keep following owned managed browsers and can continue reporting artifact retention state; successful explicit wrapper-owned close rows and `electron.cleanup` managed-session steps are restore-visible close events
 - keep runtime cleanup ownership separate from branch-visible state: `session_tree` restore and wrapper-owned browser commands are serialized with managed-session work; caller-owned explicit-session commands use local queues plus a cooperating-process execution lock keyed by actual socket context and effective canonical namespace/session (explicit namespace argv wins over inherited `AGENT_BROWSER_NAMESPACE`, including an explicit empty default), so the live URL probe, preparation helpers, semantic snapshot, main command, and state commit for one identity cannot interleave while different identities remain concurrent. Namespace-scoped `close --all` is the exception: it drains and exclusively barriers managed plus matching caller-owned work before clearing global namespace state. Namespace and session identity components are additionally Unicode-normalized and case-folded on macOS and Windows to match their case-insensitive daemon paths. Only the outer tool execution acquires that key; nested helpers run under it without re-entry. Policy, route, and artifact deltas survive unrelated managed-state commits, while a separate branch-restore generation guard prevents stale completions from overwriting a newer branch. Concurrent artifact-producing operations merge under the existing artifact queue and persist ordered row changes; replay derives the same bounded recent view from journal order. Extension-managed sessions and wrapper-launched Electron records owned by the current process remain eligible for quit/cleanup, and fresh-session allocation stays monotonic across branch restores, including auto rows and close rows that reference wrapper-generated fresh names
 - when a close command or `electron.cleanup` successfully closes the current wrapper-managed session, clear live page/ref state, reserve the next generated fresh-session ordinal, and rotate the next default auto call to a fresh wrapper-generated session name rather than reusing the closed name
 - when `/reload` shuts down an extension instance, close off-branch owned managed sessions and off-branch owned Electron launches before clearing process-local ownership; retain attached-browser context for those still-owned off-branch resources so cleanup cannot resend local-launch defaults. Preserve only the current branch-visible active managed session and active Electron launch plus its isolated `userDataDir` for reload continuity, and also persistently protect `userDataDir` paths when partial cleanup intentionally skips or fails profile removal so later temp cleanup, process exit, and stale temp-root pruning after restart do not violate Electron cleanup's safety decision; rebuild active branch state from the active branch on the next `session_start`
+- on a managed fork restart (`pi restart`/`/restart`: `session_shutdown` reason `quit` with `disposition: "handoff"` for a committed restart or `"provisional"` for an unready replacement that may roll back), transfer ownership instead of quitting. Re-read the active branch and keep every owned managed identity the replacement worker's `session_start` restore reclaims (branch-active identities including non-current ones, the current session, and interrupted owned intents); keep active branch-visible Electron launches and persistently protect their isolated `userDataDir` paths through process exit; close only owned managed sessions and Electron launches the replacement cannot restore, as on `/reload`. Live page JavaScript, unsaved forms, and in-progress recordings therefore continue in the same browser. `disposition: "release"` and an absent disposition (official Pi, SDK, print, RPC, and older launchers) keep quit cleanup; if the branch cannot be read at shutdown, only the current session is kept, as on `/reload`
 - when an unnamed `sessionMode: "fresh"` launch succeeds, make it the new extension-managed session so later default calls keep using it
 - when an unnamed `sessionMode: "fresh"` launch fails or times out, preserve the previous managed session when one was active or report the attempted fresh session as abandoned when no managed session was active (`details.managedSessionOutcome`; visible `Managed session outcome: …` when the final tool call used `sessionMode: "fresh"` and failed, or when automatic close of its replaced session failed—see `#details`)
 - if that unnamed fresh launch replaced an already-active managed session, best-effort close the old managed session after the switch succeeds; `details.managedSessionOutcome.replacedSessionClosed` records the cleanup result, and `false` keeps the older identity wrapper-owned across transcript resume for explicit follow-up or cleanup
 - treat every explicit caller-provided `--session` as user-managed, including `piab-*` names. Wrapper-owned implicit sessions set a Pi-transcript- and Git-checkout-generation-scoped `AGENT_BROWSER_RESTORE` key automatically unless disabled with `PI_AGENT_BROWSER_MANAGED_SESSION_RESTORE=0`; explicit caller sessions do not receive that injection unless they exactly target the current wrapper-owned identity. Caller state/restore paths, profiles, upstream config, file access, launch arguments, environment variables, local file pages, `outputPath`, and close arguments pass through unchanged. `session list` and `state list` keep all upstream rows and restore identifiers visible. Automatic restore still validates and pins its own checkout/storage/namespace identity and coordinates same-daemon reuse so the wrapper cannot mix restore pools or corrupt managed lifecycle state. Ambiguous tab, attachment, history, code, or state-load transitions remain page-target correctness boundaries: content calls live-check `get url` or require explicit navigation before acting. Windows uses `cross-spawn` for native executable and `.cmd` argument transport, rather than PowerShell or wrapper-owned argument reordering. Empty operands such as `fill #field ""`, `--args ""`, and explicit default `--namespace ""`, literal doublequotes in fill text, and command/subcommand adjacency are retained. Upstream receives the empty namespace rather than a wrapper omission or environment workaround. The selected child `PATH` shim is not bypassed; POSIX keeps native Node `spawn`.
-- before a DOM/content-bearing read or interaction against a caller-owned explicit session or established attachment, run a session-scoped `get url` probe so stale transcript state cannot target the wrong page. A failed or non-URL probe blocks the requested content command. The shared execution lock orders that probe, semantic snapshot resolution, and the main command across cooperating updated Pi processes. Nested `batch` steps remain unsupported; raw batch command strings mirror upstream's ASCII-space tokenizer, including quoting and backslash handling.
+- before a DOM/content-bearing read or interaction against a caller-owned explicit session or established attachment, run a session-scoped `get url` probe so stale transcript state cannot target the wrong page. A failed or non-URL probe blocks the requested content command. When the call carries browser launch flags and native `session info` reports that caller-owned session inactive, no page exists to verify: the wrapper skips both remembered-tab selection and the page probe so the requested command itself starts the browser with those flags, such as `--ignore-https-errors` on a first `auth login` or after a transcript reload. Dispatch retains its validated guard inputs. Output reconciliation retires the stopped browser's tab identity and refs and, after success, observes the replacement URL/tab before ordinary follow-ups; a failed or unobserved launch leaves the target unknown. The native command determines the replacement page; the wrapper does not reopen or reselect the stopped caller-owned browser's remembered URL. A bootstrap-only URL/title observation establishes the new target but leaves read-only native data unchanged, without claiming navigation or an unverified mutation. Ordered ref invalidation and replay remain intact. Flagless calls and running browsers keep their checks. The shared execution lock orders that probe, semantic snapshot resolution, and the main command across cooperating updated Pi processes. Nested `batch` steps remain unsupported; raw batch command strings mirror upstream's ASCII-space tokenizer, including quoting and backslash handling.
 - pass explicit `--profile` straight through to upstream `agent-browser`; no profile-cloning or isolation layer is added in v1
 
 <!-- agent-browser-playbook:start wrapper-tab-recovery -->

package/docs/platform-smoke.md

@@ -1,14 +1,14 @@
 # Platform smoke testing
 
-`pi-agent-browser-native` uses a Crabbox-backed local platform smoke gate to prove the package on macOS, Ubuntu Linux, and native Windows before release.
+`pi-agent-browser-native` uses a Crabbox-backed required local platform gate on **macOS and Ubuntu Linux**. Native Windows is **best-effort and explicitly on demand**, not a required default PR or release target.
 
-**Current 0.6.16 rollout exception:** the owner explicitly waived Windows qualification on 2026-09-21, including available runners. Windows failures remain visible but nonblocking, not passed; no further Windows repair experiments are part of this rollout. Linux/macOS and all other required checks remain required. See [release waiver and artifact requirements](RELEASE.md#current-0616-rollout-waiver) and [follow-up #191](https://github.com/fitchmultz/pi-agent-browser-native/issues/191). The commands below are unchanged and a waived Windows result does not make the full composition a passing matrix.
+The owner's 2026-10-22 best-effort decision supersedes [#191](https://github.com/fitchmultz/pi-agent-browser-native/issues/191) / PR291's blocking policy, not their unresolved process-lock/Electron failures. The September waiver is historical, not current authority. Routine Windows CI is one nonblocking official-host build/import/process smoke; broader official/fork full qualification and its environment self-check require manual `windows-qualification=true`. Neither a green required aggregate nor a not-run deep suite is a Windows pass.
 
-Outside that rollout exception, this is a release-blocking gate. Missing setup is not a skipped pass. When a maintainer approves an [alternate native transport](#alternate-native-transports), it must prove the same target-local suites; missing upstream `agent-browser` or browser dependencies still blocks that target.
+Missing macOS/Ubuntu setup is not a skipped pass. Default doctor requires only their providers/setup, not Windows, Parallels or Windows credentials. Explicit Windows doctor/run remains strict and returns real nonzero status. No test assertions, runtime ownership checks or budgets are relaxed.
 
 ## Required release gate
 
-Run the cheap harness checks first, build the project-owned Ubuntu image, run doctor explicitly, then run the full matrix and inspect the evidence:
+Run the cheap harness checks first, build the project-owned Ubuntu image, run doctor explicitly, then run the required matrix and inspect the evidence:
 
 ```sh
 npm run check:platform-smoke
@@ -16,33 +16,34 @@ npm run smoke:platform:ubuntu-image
 npm run smoke:platform:doctor
 npm run smoke:platform:all
 crabbox list --provider local-container
-crabbox list --provider parallels
 ```
 
-`smoke:platform:all` also runs `smoke:platform:doctor` before any target suite starts, so the explicit doctor step is a readable release checklist step rather than a hidden precondition. The canonical `npm run verify -- release` gate also runs the configured-source lifecycle harness, then the same platform doctor and full `macos,ubuntu,windows-native` matrix after default verification and packaged Pi smoke, so `npm publish` cannot pass `prepublishOnly` without lifecycle and platform gates. After the matrix, inspect `.artifacts/platform-smoke/<run-id>/...` summaries and manifests; a green Crabbox exit without matching suite assertions is not release proof. Use provider-specific `crabbox list` commands for cleanup review because this host may have unrelated Crabbox providers configured that require credentials.
+`smoke:platform:all` means all **required** configured targets, not optional Windows. It also runs `smoke:platform:doctor` before any target suite starts, so the explicit doctor step is a readable release checklist step rather than a hidden precondition. The canonical `npm run verify -- release` gate also runs the configured-source lifecycle harness, then the same platform doctor and configured required `macos,ubuntu` matrix after default verification and packaged Pi smoke, so `npm publish` cannot pass `prepublishOnly` without lifecycle and platform gates. After the matrix, inspect `.artifacts/platform-smoke/<run-id>/...` summaries and manifests; a green Crabbox exit without matching suite assertions is not release proof. Use provider-specific `crabbox list` commands for cleanup review because this host may have unrelated Crabbox providers configured that require credentials.
 
 Per-target commands are for diagnosis:
 
 ```sh
 npm run smoke:platform:macos
 npm run smoke:platform:ubuntu
+node scripts/platform-smoke.mjs doctor --target windows-native
 npm run smoke:platform:windows-native
+crabbox list --provider parallels # only after an explicitly selected Windows run
 npm run verify -- platform-smoke run --target ubuntu --suite platform-build
 ```
 
 ## Targets
 
-| Target           | Crabbox provider       | Shell contract                                     | Release status                                                      |
-| ---------------- | ---------------------- | -------------------------------------------------- | ------------------------------------------------------------------- |
-| `macos`          | `ssh` static localhost | POSIX shell on macOS                               | Required                                                            |
-| `ubuntu`         | `local-container`      | POSIX shell in a Docker-compatible local container | Required                                                            |
-| `windows-native` | `parallels`            | native Windows PowerShell over OpenSSH             | Nonblocking for the owner-waived 0.6.16 rollout; otherwise required |
+| Target           | Crabbox provider       | Shell contract                                     | Release status                       |
+| ---------------- | ---------------------- | -------------------------------------------------- | ------------------------------------ |
+| `macos`          | `ssh` static localhost | POSIX shell on macOS                               | Required                             |
+| `ubuntu`         | `local-container`      | POSIX shell in a Docker-compatible local container | Required                             |
+| `windows-native` | `parallels`            | native Windows PowerShell over OpenSSH             | Best-effort; explicit selection only |
 
 ## Alternate native transports
 
-With maintainer approval, local macOS execution can replace localhost SSH. Routine GitHub Actions has no Windows job; the separate Crabbox/Parallels release target remains as documented above. Record alternate native checks separately from Crabbox SSH or Parallels results. The default `release` and `prepublishOnly` commands still select the Crabbox matrix; record alternate suite evidence separately rather than reporting those commands as passed.
+With maintainer approval, local macOS execution can replace localhost SSH. For native Windows, routine GitHub Actions includes only the nonblocking smoke. On-demand full Windows jobs and Crabbox/Parallels target results retain their own scope and failures; neither is substituted for required macOS/Ubuntu evidence or relabeled a browser-dogfood pass. Record alternate native checks separately from Crabbox SSH or Parallels results. The default `release` and `prepublishOnly` commands still select the Crabbox matrix; record alternate suite evidence separately rather than reporting those commands as passed.
 
-On macOS, run the unchanged commands returned by `buildPlatformBuildCommand('macos', 'pi-agent-browser-native', '24.21.0')` and `buildBrowserDogfoodCommand('macos', '0.38.1', true)` in [`scripts/platform-smoke/targets.mjs`](../scripts/platform-smoke/targets.mjs), serially in a clean private source copy. Use private HOME, npm and Pi settings, and headless browser profiles, and clear inherited `PI_*` variables first: a shell started from Pi exports `PI_PACKAGE_DIR` and `PI_MANAGED_CLI`, which make the archived Pi CLI report the host package instead of the locked suite version. No Remote Login or host security change is required.
+On macOS, run the unchanged commands returned by `buildPlatformBuildCommand('macos', 'pi-agent-browser-native', '24.21.0')` and `buildBrowserDogfoodCommand('macos', '0.41.0', true)` in [`scripts/platform-smoke/targets.mjs`](../scripts/platform-smoke/targets.mjs), serially in a clean private source copy. Use private HOME, npm and Pi settings, and headless browser profiles, and clear inherited `PI_*` variables first: a shell started from Pi exports `PI_PACKAGE_DIR` and `PI_MANAGED_CLI`, which make the archived Pi CLI report the host package instead of the locked suite version. No Remote Login or host security change is required.
 
 Retain the exact source head/tree, package and tool versions, native OS/architecture, generated commands, stdout/stderr, every `PLATFORM_*` exit marker, actual Pi registration output, dogfood JSON and verified screenshot. Check the suite assertions below and clean up only the run's processes and temporary files. These alternatives do not waive Ubuntu or any non-platform release check.
 
@@ -71,6 +72,7 @@ PLATFORM_SMOKE_MAC_PORT=22
 # The tag suffix is derived from scripts/agent-browser-capability-baseline.mjs.
 PLATFORM_SMOKE_UBUNTU_IMAGE="pi-agent-browser-native-platform:node24-agent-browser<baseline-version>"
 
+# Optional: needed only when windows-native is explicitly selected.
 PLATFORM_SMOKE_WINDOWS_VM="pi-extension-windows-template"
 PLATFORM_SMOKE_WINDOWS_SNAPSHOT="crabbox-ready-ab-0.33.0"
 PLATFORM_SMOKE_WINDOWS_USER="<windows-ssh-user>"
@@ -80,7 +82,7 @@ PLATFORM_SMOKE_WINDOWS_WORK_ROOT="C:\\crabbox\\pi-agent-browser-native"
 PLATFORM_SMOKE_AUTH_ENV=""
 ```
 
-The Ubuntu target image is derived from `node:24-bookworm`, installs the `agent-browser` version from [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs), installs Debian Chromium plus the upstream Linux WebGPU/Xvfb runtime packages (`libvulkan1`, `mesa-vulkan-drivers`, and `xvfb`) through apt, copies the official Go 1.27.1 toolchain onto `PATH` so `platform-target` can build the [corrected quality checker](CODE_QUALITY.md), creates a non-root `circleci` user, and sets `AGENT_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium`. Rebuild it after upstream rebaselining, or override `PLATFORM_SMOKE_UBUNTU_IMAGE` with an equivalent prepared local image. Do not install `agent-browser` ad hoc inside the Ubuntu smoke command; a missing tool is image/template drift.
+The Ubuntu target image is derived from `node:24-bookworm`, installs the latest stock `agent-browser` and checks it against [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs), installs Debian Chromium plus the upstream Linux WebGPU/Xvfb runtime packages (`libvulkan1`, `mesa-vulkan-drivers`, and `xvfb`) through apt, copies the official Go 1.27.1 toolchain onto `PATH` so `platform-target` can build the [corrected quality checker](CODE_QUALITY.md), creates a non-root `circleci` user, and sets `AGENT_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium`. Rebaseline the project when current upstream differs from the audited version, then rebuild the image, or override `PLATFORM_SMOKE_UBUNTU_IMAGE` with an equivalent prepared local image. Do not install `agent-browser` ad hoc inside the Ubuntu smoke command; a missing tool is image/template drift.
 
 The configured upstream `agent-browser` baseline is imported from [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs). Target-local browser suites verify that exact `agent-browser` version before running. Bake the exact upstream CLI and browser runtime into the Windows template/snapshot for speed and reproducibility; missing or stale Windows `agent-browser` / browser readiness is a blocked setup, not something the smoke command repairs. The Windows browser suite checks the preinstalled browser cache and prewarms one short loopback HTTP URL before the extension harness runs.
 
@@ -112,6 +114,8 @@ Each required target runs `platform-build` and `browser-dogfood-smoke` on one Cr
 8. Run `pi list --approve` and assert the package is registered under project packages from the packed install.
 9. Assert the release proof did not use `pi -e .` or `pi --extension .`.
 
+When `PI_AGENT_BROWSER_RELEASE_TARBALL` names a retained release candidate, the harness copies it through the ordinary Crabbox workspace sync and installs that archive in step 6 instead of the target-local pack. The target-local `npm pack` still runs. Each target records and checks the candidate SHA-256 before and after installation; the caller remains responsible for comparing the original archive with the shared preparation receipt.
+
 ### `browser-dogfood-smoke`
 
 1. Run `npm ci` in the synced checkout if needed.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-agent-browser-native",
-	"version": "0.9.6",
+	"version": "0.9.7",
 	"description": "pi extension that exposes agent-browser as a native tool for browser automation",
 	"type": "module",
 	"author": "Mitch Fultz (https://github.com/fitchmultz)",
@@ -120,10 +120,10 @@
 		"smoke:platform:macos": "node scripts/platform-smoke.mjs run --target macos",
 		"smoke:platform:ubuntu": "node scripts/platform-smoke.mjs run --target ubuntu",
 		"smoke:platform:windows-native": "node scripts/platform-smoke.mjs run --target windows-native",
-		"smoke:platform:all": "npm run smoke:platform:doctor && node scripts/platform-smoke.mjs run --target macos,ubuntu,windows-native",
+		"smoke:platform:all": "npm run smoke:platform:doctor && node scripts/platform-smoke.mjs run",
 		"check:compat": "node scripts/compat-host.mjs && npm run typecheck && npm test && node scripts/verify-package.mjs --smoke-pi",
 		"typecheck": "node ./scripts/project.mjs verify typecheck",
-		"test": "node ./scripts/build.mjs && node ./scripts/prepare-quality-checker.mjs && tsx --test --test-reporter=tap \"test/**/!(*.serial).test.ts\" && tsx --test --test-reporter=tap --test-concurrency=1 \"test/**/*.serial.test.ts\"",
+		"test": "node ./scripts/project.mjs test",
 		"verify": "node ./scripts/project.mjs verify",
 		"prepublishOnly": "npm run verify -- release && npm pack --dry-run",
 		"build": "node ./scripts/build.mjs",
@@ -153,5 +153,8 @@
 		"stream-json": "3.7.0",
 		"strip-json-comments": "5.0.3",
 		"which": "2.0.2"
+	},
+	"overrides": {
+		"undici": "8.12.3"
 	}
 }

package/platform-smoke.config.mjs

@@ -1,5 +1,5 @@
 // Platform smoke configuration for pi-agent-browser-native.
-// Crabbox owns the target lease/sync loop; this file is the project source of truth for release-blocking platform coverage.
+// Crabbox owns the target lease/sync loop; this file is the project source of truth for required and explicitly selected best-effort platform coverage.
 
 import packageJson from "./package.json" with { type: "json" };
 import { CAPABILITY_BASELINE } from "./scripts/agent-browser-capability-baseline.mjs";
@@ -10,7 +10,8 @@ const PLATFORM_SMOKE_UBUNTU_IMAGE = `pi-agent-browser-native-platform:node24-age
 export default {
 	packageName: "pi-agent-browser-native",
 	artifactRoot: ".artifacts/platform-smoke",
-	requiredTargets: ["macos", "ubuntu", "windows-native"],
+	requiredTargets: ["macos", "ubuntu"],
+	optionalTargets: ["windows-native"],
 	requiredSuites: ["platform-build", "browser-dogfood-smoke"],
 	requiredCrabbox: {
 		install: "Homebrew package or PLATFORM_SMOKE_CRABBOX override",

package/scripts/agent-browser-capability-baseline.mjs

@@ -89,6 +89,8 @@ const inventorySections = Object.freeze([
 			"session list",
 			"state save <path>",
 			"state load <path>",
+			"skippedOrigins",
+			"restoreSkippedOrigins",
 			"state list",
 			"state show <filename>",
 			"state rename <old-name> <new-name>",
@@ -118,6 +120,7 @@ const inventorySections = Object.freeze([
 			["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>"],
@@ -144,7 +147,8 @@ const inventorySections = Object.freeze([
 		"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>",
@@ -210,6 +214,7 @@ const inventorySections = Object.freeze([
 			root("network <action>"),
 			root("--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>"],
@@ -285,6 +290,7 @@ const inventorySections = Object.freeze([
 		"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>",
@@ -314,8 +320,10 @@ const inventorySections = Object.freeze([
 			"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>",
@@ -323,7 +331,7 @@ const inventorySections = Object.freeze([
 			"profiles",
 		],
 		[
-			root("batch [--bail]"),
+			root('batch [options] ["cmd" ...]'),
 			root("auth save <name>"),
 			root("auth login <name>"),
 			root("confirm <id>"),
@@ -340,6 +348,8 @@ const inventorySections = Object.freeze([
 			root("doctor [--fix]"),
 			root("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>"],
@@ -361,8 +371,12 @@ const inventorySections = Object.freeze([
 			["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"],
 		],
 	),

package/scripts/agent-browser-target.mjs

@@ -1,5 +1,5 @@
 export const TARGET_AGENT_BROWSER_SOURCE = "scripts/agent-browser-target.mjs";
-export const TARGET_AGENT_BROWSER_VERSION = "0.38.1";
+export const TARGET_AGENT_BROWSER_VERSION = "0.41.0";
 export const TARGET_AGENT_BROWSER_VERSION_LABEL = `agent-browser ${TARGET_AGENT_BROWSER_VERSION}`;
 export const MINIMUM_AGENT_BROWSER_VERSION = "0.35.0";
 export const MINIMUM_AGENT_BROWSER_VERSION_LABEL = `agent-browser ${MINIMUM_AGENT_BROWSER_VERSION}`;

package/scripts/capability-options.mjs

@@ -56,6 +56,9 @@ export const optionsAndEnv = section(
 		"--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>",
@@ -75,6 +78,9 @@ export const optionsAndEnv = section(
 		"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",
@@ -141,11 +147,15 @@ export const optionsAndEnv = section(
 		"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",
@@ -210,6 +220,9 @@ export const optionsAndEnv = section(
 		root("--no-ca-cert"),
 		root("AGENT_BROWSER_CA_CERT"),
 		root("AGENT_BROWSER_CLEAR_CA_CERT"),
+		root("--use-system-ca"),
+		root("AGENT_BROWSER_USE_SYSTEM_CA"),
+		["core skill full", "SSL_CERT_FILE"],
 		root("--allow-file-access"),
 		root("AGENT_BROWSER_ALLOW_FILE_ACCESS"),
 		root("--hide-scrollbars <bool>"),
@@ -226,6 +239,12 @@ export const optionsAndEnv = section(
 		root("AGENT_BROWSER_DOWNLOAD_PATH"),
 		root("--engine <name>"),
 		root("AGENT_BROWSER_ENGINE"),
+		root("--engine obscura"),
+		root("OBSCURA_ALLOW_PRIVATE_NETWORK"),
+		root("AGENT_BROWSER_OBSCURA_STEALTH"),
+		root("BROWSER_USE_PROFILE_ID"),
+		root("BROWSER_USE_PROXY_COUNTRY"),
+		root("BROWSER_USE_ENABLE_RECORDING"),
 		root("--input-mode <mode>"),
 		root("--no-auto-dialog"),
 		root("AGENT_BROWSER_NO_AUTO_DIALOG"),
@@ -266,6 +285,7 @@ export const optionsAndEnv = section(
 		root("--debug"),
 		root("AGENT_BROWSER_DEBUG"),
 		root("--config <path>"),
+		root("The auto-discovered ./agent-browser.json cannot set executablePath, args or plugins"),
 		root("AGENT_BROWSER_CONFIG"),
 		root("AGENT_BROWSER_DEFAULT_TIMEOUT"),
 		root("AGENT_BROWSER_AUTOSAVE_INTERVAL_MS"),