pi-agent-browser-native 0.9.5 → 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 -->
@@ -339,9 +360,9 @@ Source runs in a fresh permissioned Node child with an empty child environment,
 
 `codeRun` reports `callCount`, `emitCount`, `failedCallCount`, `rejectedCallCount`, and timeout/abort flags. `codeSteps` retains bounded audit rows. Handled browser failures may coexist with successful source completion, but remain model-visible in `failures` with exact recovery evidence and in the failure count. A successful code result therefore does not assert that every inner command succeeded. Invalid inner input shapes make the outer result fail even if source handles their observations. Uncaught source exceptions use `script-error`; deadline and cancellation use `timeout` and `aborted`; output/bridge validation retains its specific failure.
 
-Direct browser use in a disabled/no-file Pi session (`--no-session`) records current in-memory state without claiming persistence. Code requires an actually published journal, and a named but not-yet-published persistent conversation refuses browser dispatch. Sessionless local inspections and browser-independent reads remain available without journal publication, including complete redacted private spills and selected output files; observation-only artifact receipts are optional until publication. Direct, code and Electron host operations use one canonical journal event/reducer. Begin/finish records correlate operation ID, outer tool-call ID and inner command index, preserving native effects before presentation/export. Complete snapshots are defined once; ordinary finishes explicitly reuse, replace, invalidate or keep refs unknown. An unfinished begin requires inspection and a new capture, without repeating the mutation. Failed finish publication reports `browserStatePersistence: "finish-unconfirmed"` and stops dependent code calls; failed begin reports `"begin-unconfirmed"` and prevents dispatch. These acknowledgments do not promise power-loss-atomic browser actions. See [session storage and conversion](SESSION_STORAGE.md).
+Direct browser use in a disabled/no-file Pi session (`--no-session`) records current in-memory state without claiming persistence. Code requires an actually published journal, and a named but not-yet-published persistent conversation refuses browser dispatch. Sessionless local inspections and browser-independent reads remain available without journal publication, including complete redacted private spills and selected output files; observation-only artifact receipts are optional until publication. Direct, code and Electron host operations use one canonical journal event/reducer. Begin/finish records correlate operation ID, outer tool-call ID and inner command index, preserving native effects before presentation/export. Complete snapshots are defined once; ordinary finishes explicitly reuse, replace, invalidate or keep refs unknown. An unfinished begin requires inspection and a new capture, without repeating the mutation. Failed finish publication reports `browserStatePersistence: "finish-unconfirmed"` and stops dependent code calls; failed begin reports `"begin-unconfirmed"` and prevents dispatch. These acknowledgments do not promise power-loss-atomic browser actions. Historical browser receipts resume automatically through the same canonical reducer at the unchanged native journal locator, without conversion or rewritten bytes. Native validation, generation checks and publication requirements still apply. See [session storage](SESSION_STORAGE.md).
 
-Abort, timeout, branch change, reload, and shutdown stop/reap the child, settle the active inner call and join outer observation finalization before releasing lifecycle coordination. A result from a prior branch retains its complete caller observation in a process-private spill without changing the newly selected branch's artifact state. They do not roll back browser actions or automatically close the selected browser. Existing ownership still controls later shutdown cleanup. The offline converter normalizes exact pre-0.7 isolated-session cleanup leases into owner-qualified canonical events; runtime only reads those canonical cleanup facts, without old public script execution.
+Abort, timeout, branch change, reload, and shutdown stop/reap the child, settle the active inner call and join outer observation finalization before releasing lifecycle coordination. A result from a prior branch retains its complete caller observation in a process-private spill without changing the newly selected branch's artifact state. They do not roll back browser actions or automatically close the selected browser. Existing ownership still controls later shutdown cleanup. The shared read-only decoder normalizes exact pre-0.7 isolated-session cleanup leases into owner-qualified canonical events for ordinary replay or optional archive conversion; runtime retains only those cleanup facts, without old public script execution.
 
 ### `agent_browser_action`
 
@@ -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.
@@ -767,7 +789,7 @@ Additional structured fields can appear when relevant:
 - `electronGetTextScopeWarning` after a successful wrapper-tracked attached Electron `get text <selector>` (standalone or successful `batch`) when a broad non-ref CSS selector such as `body`, `html`, `main`, `div`, or `[role=application]` may read the whole app shell. Ordinary browser pages do not qualify without wrapper-owned Electron launch provenance. Shape: `{ selector, summary, electronContext: { launchId?, sessionName?, url? } }`; multiple batched diagnostics use `electronGetTextScopeWarnings`. Visible text appends `Broad Electron get text selector warning`, and next actions use `snapshot-for-electron-text-scope` ids with session-scoped `snapshot -i` payloads.
 - `evalStdinHint` after a successful `eval --stdin` when caller stdin (trimmed) looks function-shaped to the wrapper’s lightweight detector (in `extensions/agent-browser/lib/orchestration/browser-run/diagnostics.ts`: leading `function` / `async function`, parenthesized arrow `(…) =>`, or a concise `name =>` / `async name =>` form) **and** upstream JSON `data` is an object whose `result` field is a plain empty object (`{}`). Arrays such as `[]` do not qualify. It includes `reason` and `suggestion`; visible output appends `Eval stdin hint` with the same guidance. This is a heuristic for the common mistake of returning a function object instead of invoking it or passing a plain expression, not a JavaScript parser or proof that the page returned no useful data. Before this diagnostic path runs, the wrapper also recovers the common malformed native-tool call `args: ["eval", "--stdin", "..."]` with no top-level `stdin` by moving trailing `args` tokens after `--stdin` into the process stdin stream.
 - `evalResultWarning` after a successful `eval --stdin` when the current or prior page URL is `file:` (from navigation summary, session tab target, or persisted session page state), upstream JSON `data.result` is strictly `null`, and stdin is non-empty and not a trivial literal `null`/`undefined`. Fields: `reason`, `suggestion`. Visible output appends `Eval result warning` without failing the tool. Use snapshot -i, ref-based getters, screenshots, or http(s) fixtures when file:// null results are inconclusive.
-- `timeoutPartialProgress` after `runAgentBrowserProcess` reports `timedOut` (wrapper child-process watchdog) when best-effort recovery finds useful context. `summary` counts planned steps with unknown outcomes and observed declared artifact paths, plus whether page context came from live session reads or only from a planned URL. An existing file or matching URL is current-state evidence, not proof that any planned step ran. `steps` lists planned argv from the compiled QA batch plan (`compiledJob` remains its internal metadata name) or, when that object is absent, from the effective upstream `batch` source: raw argument command strings exclusively when present, otherwise JSON-array stdin, whether caller-authored or wrapper-generated by advanced source tools (1-based indices). Ignored stdin does not contribute recovery steps or artifact evidence. Generated QA rows may include `generatedFrom`. Each step has `status: "unknown"` and a `reason`: the watchdog fired before upstream reported its outcome. Multi-step timeouts do not identify a completed prefix, failed step, pending suffix, or retry position. For a single read-only or idempotent step such as a wait, snapshot, screenshot, navigation, or diagnostic, `retryStep.retry` and `retry-timeout-step` may offer a candidate after inspection; its outcome remains unknown. Each retry uses `args: ["batch"]` with `stdin` containing the original row, preserving native row operands instead of reinterpreting them as outer CLI globals. Otherwise, when the target is already verified, `inspect-current-page-after-timeout` (`snapshot -i`) lets the agent inspect state before deciding how to resume. When the target is unknown, every standalone snapshot action is removed and replaced by one executable `verify-page-target-after-timeout` action: a session-scoped `batch --bail` with stdin `[["get","url"],["snapshot","-i"]]`, so snapshot runs only after the wrapper's page-target guard is satisfied; visible failure text prints those redacted args and short stdin rather than pointing only to structured details. Dialog `status`, `accept`, and `dismiss` remain allowed while the target is unknown so timeout dialog recovery actions are executable. When a retryable step timed out during `sessionMode: "fresh"` and no live URL was recovered, `retry-timeout-step` uses top-level `sessionMode: "fresh"` instead of prefixing the abandoned generated session name. `currentPage` comes from session-scoped `get url` followed by `get title` when the session answers, otherwise a fallback URL may be inferred from the last `open` / `navigate` / `pushstate` step in the plan; `liveUrlRecovered` is true only when the wrapper recovered a live URL, so planned URLs are not treated as proof that the page actually opened. `artifacts` reports post-timeout path existence, not creation by this invocation or step completion. It covers declared output paths on `screenshot`, `pdf`, `download`, and `wait --download` steps (absolute path, existence, `state`, optional `sizeBytes`, `stepIndex`). It uses native operand positions, including literal dash-leading paths: first operand for `pdf`, second for `download`, and the next retained operand after the first timeout pair is removed for `wait --download` / `-d`. Visible text repeats the same block under `Timeout partial progress`, applying URL and path-segment redaction; the prose `Planned steps` list shows at most six steps, then an omitted-count line when the plan is longer. This is recovery evidence only; missing entries do not prove the upstream step never ran or that no other side effects occurred.
+- `timeoutPartialProgress` after `runAgentBrowserProcess` reports `timedOut` (wrapper child-process watchdog) when best-effort recovery finds useful context. `summary` counts planned steps with unknown outcomes and observed declared artifact paths, plus whether page context came from live session reads or only from a planned URL. An existing file or matching URL is current-state evidence, not proof that any planned step ran. `steps` lists planned argv from the compiled QA batch plan (`compiledJob` remains its internal metadata name) or, when that object is absent, from the effective upstream `batch` source: raw argument command strings exclusively when present, otherwise JSON-array stdin, whether caller-authored or wrapper-generated by advanced source tools (1-based indices). Ignored stdin does not contribute recovery steps or artifact evidence. Generated QA rows may include `generatedFrom`. Each step has `status: "unknown"` and a `reason`: the watchdog fired before upstream reported its outcome. Multi-step timeouts do not identify a completed prefix, failed step, pending suffix, or retry position. For a single read-only or idempotent step such as a wait, snapshot, screenshot, navigation, or diagnostic, `retryStep.retry` and `retry-timeout-step` may offer a candidate after inspection; its outcome remains unknown. Each retry uses `args: ["batch"]` with `stdin` containing the original row, preserving native row operands instead of reinterpreting them as outer CLI globals. Otherwise, when the target is already verified, `inspect-current-page-after-timeout` (`snapshot -i`) lets the agent inspect state before deciding how to resume. When the target is unknown, every standalone snapshot action is removed and replaced by one executable `verify-page-target-after-timeout` action: a session-scoped `batch --bail` with stdin `[["get","url"],["snapshot","-i"]]`, so snapshot runs only after the wrapper's page-target guard is satisfied; visible failure text prints those redacted args and short stdin rather than pointing only to structured details. Dialog `status`, `accept`, and `dismiss` remain allowed while the target is unknown so timeout dialog recovery actions are executable. When a retryable step timed out during `sessionMode: "fresh"` and no live URL was recovered, `retry-timeout-step` uses top-level `sessionMode: "fresh"` instead of prefixing the abandoned generated session name. `currentPage` comes from session-scoped `get url` followed by `get title` when the session answers, otherwise a fallback URL may be inferred from the last `open` / `navigate` / `pushstate` step in the plan; `liveUrlRecovered` is true only when the wrapper recovered a live URL, so planned URLs are not treated as proof that the page actually opened. `artifacts` reports post-timeout path existence, not creation by this invocation or step completion. Independent paths are sampled concurrently in plan order, each with up to three filesystem checks separated by 25 ms; page inspection starts after these retry windows settle. A file finishing after its own window may remain missing, even if a later page probe succeeds. It covers declared output paths on `screenshot`, `pdf`, `download`, and `wait --download` steps (absolute path, existence, `state`, optional `sizeBytes`, `stepIndex`). It uses native operand positions, including literal dash-leading paths: first operand for `pdf`, second for `download`, and the next retained operand after the first timeout pair is removed for `wait --download` / `-d`. Visible text repeats the same block under `Timeout partial progress`, applying URL and path-segment redaction; the prose `Planned steps` list shows at most six steps, then an omitted-count line when the plan is longer. This is recovery evidence only; missing entries do not prove the upstream step never ran or that no other side effects occurred.
 - `managedSessionHeadedAutosaveInterval` on active/current-after-failure wrapper-owned headed session rows, containing the canonical effective launch-time `AGENT_BROWSER_AUTOSAVE_INTERVAL_MS` string (invalid or out-of-range explicit values resolve to upstream's `"30000"` default). It is `"0"` for the wrapper default and can hold an explicit interval such as `"1000"`; transcript replay and still-owned off-current helpers reapply the recorded value. It is omitted for sessionless, headless, caller-owned, abandoned, and closed calls. If a resumed Pi process explicitly requests a different value in either direction, non-close calls fail with close-plus-fresh recovery guidance while close still uses the recorded daemon value.
 - `managedSessionHeadedAutosaveDisabled: true` is the narrower compatibility marker that the targeted session uses the wrapper's default interval `0`, rather than an explicit caller interval. It accompanies `managedSessionHeadedAutosaveInterval: "0"` on active rows and remains omitted for explicitly configured autosave.
 - `managedSessionOutcome` after a managed-session plan reaches process execution (`buildManagedSessionOutcome` / `formatManagedSessionOutcomeText` in `extensions/agent-browser/lib/orchestration/browser-run/session-state.ts`). Populated when `buildExecutionPlan` injects an extension-managed implicit or fresh `--session`, and also when a successful explicit `--session <current-wrapper-managed-session> close` closes the current managed session. It remains omitted for unrelated explicit user-managed sessions and for sessionless inspection/local paths that skip injection. Successful nested-batch lifecycle rows are evaluated in order: a terminal close reports and replays `status: "closed"` even when aggregate artifact verification makes the tool result fail; a later lifecycle-proven browser launch (including a post-close `record stop`) keeps the session active, an explicitly non-launching diagnostic leaves it closed, and an unknown row stays conservatively active even when the failed batch was the first managed call. Fields: `status` (`created`, `replaced`, `unchanged`, `closed`, `preserved`, or `abandoned`), `sessionMode`, `attemptedSessionName`, `previousSessionName`, `currentSessionName`, optional `currentSessionNamespace`, optional `replacedSessionName`, optional `replacedSessionNamespace`, optional `replacedSessionClosed` (false means automatic close failed and the previous session remains wrapper-owned/restorable for explicit cleanup), `activeBefore`, `activeAfter`, `succeeded`, and `summary` (machine-oriented; may include generated session names). Use `currentSessionNamespace` with `currentSessionName` when following preserved-session recovery actions; retry-fresh actions stay in the attempted namespace. Model-visible echo: when `sessionMode` is `"fresh"` **and** `succeeded` is false, or when `replacedSessionClosed` is false after a replacement, the wrapper appends action-oriented `Managed session outcome` and `Recovery` lines without repeating generated session ids in visible prose; session names remain in `details.managedSessionOutcome`. Failed fresh launches may also append `details.nextActions` such as `run-agent-browser-doctor`, `verify-current-managed-session`, `snapshot-current-managed-session`, or `retry-fresh-managed-session`. When other trailing diagnostic prose is also emitted in the same result, that block is concatenated **after** semantic-action candidate lines, overlay/selector-visibility tails, eval hints/warnings, and `Timeout partial progress` (see `rawAppendedDiagnosticText` in `extensions/agent-browser/lib/orchestration/browser-run/final-result.ts`). For `"auto"` failures the same struct may appear on `details` without that extra line. When post-upstream analysis (for example **`qa`** preset failure) flips the overall tool result after a successful batch, or a fresh native batch opens the requested page and then a later step fails, the managed-session transition still reflects that the fresh browser became current. The visible recovery says the fresh launch became current and points to `failureCategory` / `qaPreset` / `batchFailure` for the post-launch failure instead of telling the agent that the old session was preserved.
@@ -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 -->
@@ -941,7 +964,7 @@ For exact delayed-input behavior, build native rows instead of relying on unveri
 }
 ```
 
-Fixed waits are elapsed time, not postconditions. Preserve explicit URL/text waits, same-snapshot fill ordering, fresh refs after mutations, and partial-progress inspection. There is no legacy public script/job runtime. Exact isolated-script cleanup leases are normalized only by offline conversion so canonical replay can retire their recorded pre-upgrade resources. Saved auth and original Pi transcripts are not rewritten or deleted; [rollback](RELEASE.md#07-upgrade-and-rollback) changes the package version, not browser side effects.
+Fixed waits are elapsed time, not postconditions. Preserve explicit URL/text waits, same-snapshot fill ordering, fresh refs after mutations, and partial-progress inspection. There is no legacy public script/job runtime. Exact isolated-script cleanup leases are normalized during ordinary read-only replay so the canonical cleanup path can retire recorded pre-upgrade resources without acquiring a parent's cleanup rights on a fork. Optional separate-copy conversion uses the same decoder. Saved auth and original Pi transcripts are not rewritten or deleted; [rollback](RELEASE.md#07-upgrade-and-rollback) changes the package version, not browser side effects.
 
 ## Non-goals