pi-agent-browser-native 0.9.2 → 0.9.4

package/docs/TOOL_CONTRACT.md

@@ -1,6 +1,7 @@
 # Tool contract
 
 Related docs:
+
 - [`../README.md`](../README.md)
 - [`REQUIREMENTS.md`](REQUIREMENTS.md)
 - [`ARCHITECTURE.md`](ARCHITECTURE.md)
@@ -23,6 +24,7 @@ Official Pi 1.0's initial SDK resume supplies an initial tool selection that byp
 ## Why this tool shape
 
 This keeps the integration:
+
 - thin
 - powerful
 - low-drift
@@ -43,9 +45,9 @@ An SDK host can import the package's compiled `dist/extensions/agent-browser/ind
 
 ```ts
 agentBrowserExtension(pi, {
-  async beforeExecute(toolCallId, ctx) {
-    await saveHostState(toolCallId, ctx.signal);
-  },
+	async beforeExecute(toolCallId, ctx) {
+		await saveHostState(toolCallId, ctx.signal);
+	},
 });
 ```
 
@@ -65,13 +67,13 @@ Config shape:
 
 ```json
 {
-  "webSearch": {
-    "enabled": true,
-    "preferredProvider": "exa",
-    "defaultSearchType": "deep-lite",
-    "exaApiKey": "$EXA_API_KEY",
-    "braveApiKey": "$BRAVE_API_KEY"
-  }
+	"webSearch": {
+		"enabled": true,
+		"preferredProvider": "exa",
+		"defaultSearchType": "deep-lite",
+		"exaApiKey": "$EXA_API_KEY",
+		"braveApiKey": "$BRAVE_API_KEY"
+	}
 }
 ```
 
@@ -79,24 +81,25 @@ Schema:
 
 ```json
 {
-  "query": "search text",
-  "provider": "auto",
-  "searchType": "deep-lite",
-  "includeDomains": ["docs.exa.ai"],
-  "excludeDomains": ["archive.example"],
-  "category": "publication",
-  "additionalQueries": ["Exa search API defaults"],
-  "highlightsDynamic": false,
-  "count": 5,
-  "offset": 0,
-  "country": "US",
-  "searchLang": "en-US",
-  "safesearch": "moderate",
-  "freshness": "pw"
+	"query": "search text",
+	"provider": "auto",
+	"searchType": "deep-lite",
+	"includeDomains": ["docs.exa.ai"],
+	"excludeDomains": ["archive.example"],
+	"category": "publication",
+	"additionalQueries": ["Exa search API defaults"],
+	"highlightsDynamic": false,
+	"count": 5,
+	"offset": 0,
+	"country": "US",
+	"searchLang": "en-US",
+	"safesearch": "moderate",
+	"freshness": "pw"
 }
 ```
 
 Provider notes:
+
 - `provider` is optional; `auto` uses available keys plus `webSearch.preferredProvider`.
 - `offset` skips results, not pages, for both providers. Each fetches the first `count + offset` results and slices locally; the maximum request is 19 results (`count: 10`, `offset: 9`), within Brave's 20-result page limit.
 - `searchType` applies to Exa only and supports `auto`, `fast`, `instant`, `deep-lite`, `deep`, and `deep-reasoning`. Effective precedence is the per-call field, then `webSearch.defaultSearchType`, then `auto`. Use `deep-lite` for implementation research, `deep` for hard multi-source work, and `deep-reasoning` only for the hardest or exhaustive work.
@@ -111,26 +114,26 @@ Result details:
 
 ```json
 {
-  "provider": "exa",
-  "query": "search text",
-  "returnedQuery": "search text",
-  "count": 5,
-  "offset": 0,
-  "searchType": "deep-lite",
-  "requestId": "request-id-when-provider-returns-one",
-  "duplicatesRemoved": 1,
-  "fetchedAt": "2026-06-02T00:00:00.000Z",
-  "results": [
-    {
-      "title": "Result title",
-      "url": "https://example.com/",
-      "description": "Compact summary or first highlight",
-      "highlights": ["Relevant excerpt"],
-      "source": "Example",
-      "pageDate": "2026-06-02",
-      "language": "en"
-    }
-  ]
+	"provider": "exa",
+	"query": "search text",
+	"returnedQuery": "search text",
+	"count": 5,
+	"offset": 0,
+	"searchType": "deep-lite",
+	"requestId": "request-id-when-provider-returns-one",
+	"duplicatesRemoved": 1,
+	"fetchedAt": "2026-06-02T00:00:00.000Z",
+	"results": [
+		{
+			"title": "Result title",
+			"url": "https://example.com/",
+			"description": "Compact summary or first highlight",
+			"highlights": ["Relevant excerpt"],
+			"source": "Example",
+			"pageDate": "2026-06-02",
+			"language": "en"
+		}
+	]
 }
 ```
 
@@ -138,17 +141,17 @@ For Exa, `details.searchType` is the effective requested type even when the prov
 
 ## Input mode chooser
 
-| Need | Tool | Input |
-| --- | --- | --- |
-| One native command | `agent_browser` | `{ args, stdin?, outputPath?, timeoutMs?, sessionMode? }` |
-| Fixed sequence | `agent_browser` | `args: ["batch", "--bail"]` and native JSON-array `stdin` |
-| Loops, branches, aggregation | `agent_browser_code` | `{ code, session?, namespace?, timeoutMs?, outputPath? }` |
-| Discover/enable advanced tools | `agent_browser_tools` | `{ enable?: ["action", "qa", "electron", "source", "network"] }` |
-| Stable locator or native select | `agent_browser_action` | Flat action/locator fields |
-| Diagnostic verdict | `agent_browser_qa` | Flat URL or attached-check fields |
-| Desktop app lifecycle | `agent_browser_electron` | Flat action/target fields |
-| UI/source candidates | `agent_browser_source` | Flat selector/fiber/component fields |
-| Failed-request/source candidates | `agent_browser_network_source` | Flat request/filter fields |
+| Need                             | Tool                           | Input                                                            |
+| -------------------------------- | ------------------------------ | ---------------------------------------------------------------- |
+| One native command               | `agent_browser`                | `{ args, stdin?, outputPath?, timeoutMs?, sessionMode? }`        |
+| Fixed sequence                   | `agent_browser`                | `args: ["batch", "--bail"]` and native JSON-array `stdin`        |
+| Loops, branches, aggregation     | `agent_browser_code`           | `{ code, session?, namespace?, timeoutMs?, outputPath? }`        |
+| Discover/enable advanced tools   | `agent_browser_tools`          | `{ enable?: ["action", "qa", "electron", "source", "network"] }` |
+| Stable locator or native select  | `agent_browser_action`         | Flat action/locator fields                                       |
+| Diagnostic verdict               | `agent_browser_qa`             | Flat URL or attached-check fields                                |
+| Desktop app lifecycle            | `agent_browser_electron`       | Flat action/target fields                                        |
+| UI/source candidates             | `agent_browser_source`         | Flat selector/fiber/component fields                             |
+| Failed-request/source candidates | `agent_browser_network_source` | Flat request/filter fields                                       |
 
 Run `agent_browser_tools {}` for inventory; `enable` adds selected capabilities without removing unrelated active tools. Pi's native selected-tool history handles reload/resume rather than a package-owned activation registry. If an exact recovery action names an inactive advanced tool, enable its capability before using that payload.
 
@@ -168,15 +171,21 @@ Use exact labels from the latest snapshot. Return to the model when a fresh obse
 
 `screenshot --if-changed` and `--threshold <0-1>` preserve native `changed`, `revision`, `pixelChangeRatio`, and `threshold`. An unchanged response has no path, artifact, or image attachment—even if the caller requested an existing file. It succeeds as an observation, not proof that an evidence file was saved.
 
-`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. 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).
+`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).
 
 <a id="wrapper-json"></a>
 
 ## Wrapper `--json`
 
+Native text cookie reads redact `name=value`, including empty names; storage reads redact `key: value`, including empty and colon-containing keys, with the existing benign-value policy. A standalone get-by-key (`storage local|session get <key>` or native shorthand `storage local|session <key>`) redacts the entire value, including embedded newlines, when that policy requires it, even if invocation display redaction changes the supplied key. Content, details, spills and exports use the same redacted text. Effective batch argv takes precedence over stdin when selecting these format heuristics; text never establishes per-row provenance. Native all-entry storage and raw-batch output do not escape multiline values: a secret continuation can look identical to a separate benign entry or ordinary page output. Text redaction cannot resolve that ambiguity; use structured JSON for an unambiguous sensitive-storage boundary. Native JSON all-entry maps retain names and benign values while redacting other values.
+
 When explicitly requested, visible JSON remains parseable for early preparation results too: snapshot/network filters, scroll results, and preparation failures use the same JSON envelope as ordinary execution. Diagnostic metadata remains in `details`; `outputPath` notices do not append prose to JSON. Help/version stays native text.
 
-The extension always plans normal browser commands with `--json` prepended in `effectiveArgs` so upstream returns structured JSON for presentation and `details`. Omit `--json` in caller `args` for ordinary prose. Include it when you need the visible tool text as a parseable JSON envelope; structured `details` remain available in both modes. Plain-text inspection (`--help`, `--version`) keeps its own output shape. Read-only skills and local/setup commands such as auth/profile/setup, `session list`, and syntactically local state lifecycle operations skip implicit session injection as documented under `sessionMode`. Upstream session/state rows and targets remain visible, and state/config/path operations pass through unchanged.
+The extension prepends `--json` to normal browser commands when the caller does not select an output mode, so upstream returns structured JSON for presentation and `details`. Omit `--json` in caller `args` for ordinary prose. Include it when you need the visible tool text as a parseable JSON envelope; structured `details` remain available in both modes. Plain-text inspection (`--help`, `--version`) keeps its own output shape. Read-only skills and local/setup commands such as auth/profile/setup, `session list`, and syntactically local state lifecycle operations skip implicit session injection as documented under `sessionMode`. Upstream session/state rows and targets remain visible, and state/config/path operations pass through unchanged.
+
+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.
 
 ## Experimental WebMCP
 
@@ -194,7 +203,7 @@ Upstream 0.35.2 adds `dashboard start --allowed-origins <origins>` and `AGENT_BR
 
 ## Headed and local fixture limits
 
-Local Chrome uses stock `--args --no-startup-window` at bootstrap and composes it consistently with caller-configured Chrome arguments (CLI overrides environment, which overrides native config). Plain active-session follow-ups do not resend bootstrap settings. A pre-existing custom-argument browser may restart once because stock Chrome launch arguments form part of native session identity; there is no migration or launch-settings journal. Headless remains the default. CDP/auto-connect, providers, Electron, and Lightpanda do not receive this Chrome default. The wrapper does not delete tabs or edit profiles.
+Local Chrome uses stock `--args --no-startup-window` at bootstrap only when native environment/config does not own local launch defaults; caller CLI argument values then follow that default. With native environment/config launch defaults, no wrapper Chrome startup arguments are injected, keeping browser, local auth, and helper invocations consistent. Include `--no-startup-window` in native `args` when a single headed window is required. CLI still overrides environment, which overrides native config. Plain active-session follow-ups do not resend wrapper bootstrap settings. Changed launch settings can trigger native's normal session-identity restart; there is no migration or launch-settings journal. Headless remains the default. CDP/auto-connect, providers, Electron, and Lightpanda do not receive this Chrome default. The wrapper does not delete tabs or edit profiles.
 
 URL-less `open` is executed as native `get url`, including effective raw/stdin batch rows and code calls. This lazily opens a missing browser without navigating an existing page or issuing a second incomplete launch. `details.args` retains the request; `effectiveArgs`, `command`, native URL data and lifecycle show what ran. No launch receipt is synthesized. Explicit URLs, required-URL errors for `goto`/`navigate`, and top-level help/version argv keep their native meanings. Ignored batch stdin remains unchanged.
 
@@ -212,6 +221,7 @@ URL-less `open` is executed as native `get url`, including effective raw/stdin b
 
 <!-- agent-browser-playbook:start shared-guidelines -->
 <!-- Generated from extensions/agent-browser/lib/playbook.ts. Run `npm run docs -- playbook write` to update. -->
+
 - Choose agent_browser for one native command, native batch --bail with JSON-array stdin for a known fixed sequence, or agent_browser_code for loops, branches, and aggregation. Return to the model when a fresh observation needs judgment. Neither tool is a named recipe registry.
 - agent_browser_code takes { code, session?, namespace?, timeoutMs?, outputPath? }. JavaScript globals are fresh for every call; the selected browser persists and is shared with agent_browser. Use await browser({ args, stdin?, timeoutMs? }), inspect result.success, and emit selected JSON instead of whole envelopes. Use emitImage(result.imageObservations[0]) only when image inspection is needed; image handles belong to the current code call. No imports or host filesystem/network/process APIs are exposed.
 - Standard workflow: open the page, snapshot -i, interact using current @refs from that snapshot, and re-snapshot after navigation, scrolling, rerendering, or other major DOM changes because refs are page-scoped; the wrapper fails mutation-prone stale/recycled refs before upstream can silently target a different current-page element. On dense pages, use wrapper-side snapshot -i --search <text> or snapshot -i --filter role=<role> to render matching refs while preserving the full ref map in details.refSnapshot, add snapshot --viewport when scroll position or above/below-fold context matters, and add snapshot --diff when a quick before/after ref-map delta would prevent reading a full spill file.
@@ -239,7 +249,7 @@ URL-less `open` is executed as native `get url`, including effective raw/stdin b
 - 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.
-- For dialogs and frames, use dialog status/accept/dismiss and frame <selector|main> through native args; dialog commands and eval snippets that look like alert/confirm/prompt/dialog triggers are shorter-bounded than normal browser calls, and timed-out dialog-like interactions may add inspect-dialog-after-timeout, dismiss-dialog-after-timeout, or recover-fresh-session-after-dialog-timeout nextActions. When --confirm-actions produces a pending confirmation, use details.nextActions or exact confirm <id> / deny <id> calls instead of inventing ids.
+- For dialogs and frames, use dialog status/accept/dismiss and frame <selector|main> through native args; dialog commands and eval snippets that look like alert/confirm/prompt/dialog triggers are shorter-bounded than normal browser calls, and timed-out dialog-like interactions may add inspect-dialog-after-timeout, dismiss-dialog-after-timeout, or recover-fresh-session-after-dialog-timeout nextActions. Set --confirm-actions on the session's first command; selected strings, including an explicit empty string, follow same-identity helpers and resumed follow-ups until successful close. Native unset keeps ordinary native defaults. Changing a running daemon's policy can discard pending confirmations. When it produces a pending confirmation, including a cold-reopen helper, follow the exact details.nextActions or confirm <id> / deny <id> calls without repeating the policy or inventing ids. Matching native guarded controls avoid page helpers that could replace the pending action; this is not native ID-validation proof or browser independence. In native batch, only a matching first effective decision gets that helper suppression; later page/ref checks remain. Nested decisions remain pending; failed inner actions fail, and completed browser actions reconcile their page state. A pending tab_new transport may show a validated after_confirmation open request and conditional guidance: follow it in the same session and new tab only after successful tab approval, never after denial. The extension does not execute that continuation. Confirmed full snapshots install returned refs; a final confirmed capture supplies the next same-identity call's freshness sample once, including semantic role click/check/fill and unique accessible select resolution, with target/membership/invalidation checks intact. On this one use, live verification compares the complete capture URL, including fragments, and rejects refs when it changes—including wrapper-owned managed sessions and warm sessions without resume. Ordinary ref/tab URL comparisons remain fragment-insensitive. Pending snapshots display confirmation required, not an empty page. Intervening calls or later rows consume it; DOM-only renames on the same page after that sample are not resampled on this one use.
 - If a session lands on the wrong page or tab, an interaction changes origin unexpectedly, or an open call returns blocked, blank, or otherwise unexpected results, use tab list / tab <tab-id-or-label> / snapshot -i to recover state before retrying different URLs or fallback strategies. For headed demos, put --headed on the first launch with sessionMode=fresh and verify with screenshot/tab/get-url evidence because tool success cannot prove the OS window is visible to the user. For desktop readiness, prefer real conditions first: wait --text, wait --url, wait --fn, wait --load <state>, wait --download, or agent_browser_qa attached:true; for disappearance checks, use wait --fn predicates instead of stale upstream-help examples like wait <selector> --state hidden. Use agent_browser_electron probe/status for wrapper-owned launch health or target mismatch. Fixed waits are a last resort: their duration is positional (wait <ms>, not wait --time <ms>). Use explicit --timeout or top-level timeoutMs for legitimately slow waits, and treat a successful payload like "waited":"timeout" as elapsed time only—verify completion with an observed condition, fresh snapshot, or screenshot.
 - For feed, timeline, or inbox reading tasks, focus on the main timeline/list region and read the first item there rather than unrelated composer or sidebar content.
 - For read-only browsing tasks, use read <url> for documentation or other unstructured text without requiring a Chrome page, or read with no URL for rendered active-tab DOM. Prefer the current snapshot, structured ref labels, getters, or scoped eval --stdin when you need interactive structure or targeted page state. Only click into media viewers, detail routes, or new pages when the current view does not contain the needed information.
@@ -247,13 +257,14 @@ URL-less `open` is executed as native `get url`, including effective raw/stdin b
 - On dashboards with nested scroll containers, verify scroll with a screenshot or fresh snapshot -i; if the viewport did not move, details.data.scrolled may be false/noMovement true and you should prefer scrollintoview <@ref> or target the actual scrollable region with scroll <selector> <dir> [px|percent]. For native selects, use select <selector> <value...> (or agent_browser_action select) instead of clicking option refs; for custom comboboxes, a click/agent_browser_action may only focus the field, so re-snapshot and use keyboard type <text> for focused input, press ArrowDown or press Enter, or visible option refs. Raw type requires both <selector> and <text>.
 - When using eval --stdin, scope checks and actions to the target element or route whenever possible instead of relying on broad page-wide text heuristics.
 - When using eval --stdin for extraction, pass the JavaScript through the native tool stdin field, not as an extra args token after --stdin, and return the value you want instead of relying on console.log as the primary result channel. Prefer plain expressions like ({ title: document.title }) or explicitly invoked functions like (() => ({ title: document.title }))(); use outputPath when the eval/get/snapshot data should be saved as a durable local file, but never reuse a screenshot, download, recording, or other browser artifact destination as outputPath. If a function-shaped snippet returns {}, details.evalStdinHint may warn that the function was serialized instead of called. Local file pages and caller-selected output paths are supported when upstream allows them. If get text on a broad CSS selector surfaces details.selectorTextVisibility or selectorTextVisibilityAll, prefer a visible @ref, a more specific selector, or the inspect-visible-text-candidates nextAction over hidden tab content.
-- When details.pageChangeSummary is present, use changeType and summary as a compact signal for navigation, DOM mutation, confirmations, or artifacts; when nextActionIds is set, match those ids to entries in details.nextActions (or per-step nextActions inside batch) for concrete follow-up payloads instead of inferring from prose alone. Click-dispatch probes require native get attr readback of a temporary marker on the candidate target; unproven ref or XPath identity leaves the native click unverified, not failed. If details.clickDispatch reports a click-dispatch miss, refresh/inspect/retry the real click first; for static local fixtures only, an explicit eval --stdin programmatic .click() can exercise app handlers, but treat it as an untrusted scripted workaround and never use it to bypass stop-before-submit/order/purchase boundaries. If an upstream click failure says the target is covered by another element at the target's click point, use the inspect-overlay-state nextAction to refresh refs and inspect the blocker before deciding whether to retry; do not blindly repeat the blocked click. If a no-navigation click surfaces details.overlayBlockers, inspect the fresh snapshot evidence before using a close/dismiss candidate nextAction; ordinary page chrome without dialog/alertdialog evidence should not trigger this diagnostic.
+- When details.pageChangeSummary is present, use changeType and summary as a compact signal for navigation, DOM mutation, confirmations, or artifacts; when nextActionIds is set, match those ids to entries in details.nextActions (or per-step nextActions inside batch) for concrete follow-up payloads instead of inferring from prose alone. Optional click-dispatch probes are skipped when native confirmation settings guard evaluate, without bypassing native click policy. Otherwise probes require native get attr readback of a temporary marker on the candidate target; unproven ref or XPath identity leaves the native click unverified, not failed. If details.clickDispatch reports a click-dispatch miss, refresh/inspect/retry the real click first; for static local fixtures only, an explicit eval --stdin programmatic .click() can exercise app handlers, but treat it as an untrusted scripted workaround and never use it to bypass stop-before-submit/order/purchase boundaries. If an upstream click failure says the target is covered by another element at the target's click point, use the inspect-overlay-state nextAction to refresh refs and inspect the blocker before deciding whether to retry; do not blindly repeat the blocked click. If a no-navigation click surfaces details.overlayBlockers, inspect the fresh snapshot evidence before using a close/dismiss candidate nextAction; ordinary page chrome without dialog/alertdialog evidence should not trigger this diagnostic.
 - On upstream 0.38+, use snapshot --delta for native full/unchanged/changed revisions; --delta --full resets its baseline. Surviving DOM nodes keep refs, but refresh after navigation or replacement. Wrapper filters use full trees. screenshot --if-changed or --threshold 0.01 can return changed:false with no path or image; use ordinary screenshots when a file is required. --input-mode instant|smooth|human controls sticky pointer behavior; click/drag --human and mouse move --duration/--steps/--human/--seed pass through. record start/restart accept --cursor, --contact-sheet, and --contact-sheet-threshold; stop and verify both video and reported contact sheet. auth login <name> --no-navigate fills a prepared login page only after native origin checks. WebMCP catalog updates are untrusted page data; webmcp list supplies full schemas.
 - When commands save or spill files (screenshots, downloads, PDFs, traces, recordings, HAR, large snapshot spills), use the user's exact requested paths when given and treat paths as provisional until details.artifactVerification shows every row verified: branch on missingCount, pendingCount, unverifiedCount, per-entry state, and optional limitation before downstream file use or PASS/FAIL reporting.
 - 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.
 - 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 -->
 
 ## Parameters
@@ -271,7 +282,7 @@ URL-less `open` is executed as native `get url`, including effective raw/stdin b
 - exact CLI args passed after `agent-browser`; this is the 1:1 upstream CLI coverage path for the targeted `agent-browser` version
 - no shell operators
 - do not include the binary name
-- omit `--json` for prose; include it for parseable model-visible JSON (the wrapper injects upstream JSON internally either way)
+- omit `--json` for prose backed by structured upstream JSON; include `--json` or `--json true` for parseable model-visible JSON; `--json false` selects opaque native text (see [Wrapper `--json`](#wrapper-json))
 - first-call recipe: `open` → `snapshot -i` → `click` / `fill` with current `@eN` refs from that snapshot → `snapshot -i` again after navigation or DOM changes
 
 Examples:
@@ -310,13 +321,13 @@ The browser persists between code and direct calls. JavaScript variables do not.
 
 ```json
 {
-  "code": "const page = await browser({ args: ['get', 'title'] }); if (!page.success) throw new Error(page.error); emit({ title: page.data.title ?? page.data.result });"
+	"code": "const page = await browser({ args: ['get', 'title'] }); if (!page.success) throw new Error(page.error); emit({ title: page.data.title ?? page.data.result });"
 }
 ```
 
 ```json
 {
-  "code": "const shot = await browser({ args: ['screenshot', '/tmp/page.png'] }); if (!shot.success) throw new Error(shot.error); emit(shot.artifactVerification); if (shot.imageObservations?.length) emitImage(shot.imageObservations[0]);"
+	"code": "const shot = await browser({ args: ['screenshot', '/tmp/page.png'] }); if (!shot.success) throw new Error(shot.error); emit(shot.artifactVerification); if (shot.imageObservations?.length) emitImage(shot.imageObservations[0]);"
 }
 ```
 
@@ -336,18 +347,18 @@ Abort, timeout, branch change, reload, and shutdown stop/reap the child, settle
 
 Enable `action` through `agent_browser_tools`, then call the tool with flat fields. Optional `outputPath` and `timeoutMs` apply to the ordinary executor; this tool has no `sessionMode` field.
 
-| Field | Contract |
-| --- | --- |
-| `action` | Required: `click`, `check`, `fill`, or `select` |
-| `selector` | Direct CSS/selector/current-ref target; cannot combine with locator fields for click/check/fill |
-| `locator` | `role`, `text`, `label`, `placeholder`, `alt`, `title`, or `testid`; select supports only role/label |
-| `value` | Locator value or one select option; for label select, this is the label |
-| `values` | One or more select options; required for label select; rejected on other actions |
-| `text` | Fill text; required for fill, rejected on select |
-| `role`, `name` | Accessible role and optional name; role may replace locator value and must agree if both are given |
-| `session` | Explicit native session; preserved in compiled commands and recovery |
+| Field          | Contract                                                                                             |
+| -------------- | ---------------------------------------------------------------------------------------------------- |
+| `action`       | Required: `click`, `check`, `fill`, or `select`                                                      |
+| `selector`     | Direct CSS/selector/current-ref target; cannot combine with locator fields for click/check/fill      |
+| `locator`      | `role`, `text`, `label`, `placeholder`, `alt`, `title`, or `testid`; select supports only role/label |
+| `value`        | Locator value or one select option; for label select, this is the label                              |
+| `values`       | One or more select options; required for label select; rejected on other actions                     |
+| `text`         | Fill text; required for fill, rejected on select                                                     |
+| `role`, `name` | Accessible role and optional name; role may replace locator value and must agree if both are given   |
+| `session`      | Explicit native session; preserved in compiled commands and recovery                                 |
 
-Locator click/check/fill compiles to native `find`; direct targets compile to their ordinary command. Select uses native `select <selector> <value...>`. Accessible select resolves exactly one current visible combobox/listbox through a fresh snapshot; missing or ambiguous targets fail before action. Use `role: "combobox"` or `"listbox"` plus `name`, or label plus option `values`. No native `find ... select` capability is assumed.
+Locator click/check/fill compiles to native `find`; direct targets compile to their ordinary command. Select uses native `select <selector> <value...>`. Accessible select resolves exactly one current visible combobox/listbox through a fresh snapshot or the eligible one-use confirmed capture; missing or ambiguous targets fail before action. Use `role: "combobox"` or `"listbox"` plus `name`, or label plus option `values`. No native `find ... select` capability is assumed.
 
 ```json
 { "action": "fill", "locator": "label", "value": "Email", "text": "user@example.com" }
@@ -378,13 +389,13 @@ The verdict is `qaPreset: { passed, failedChecks, notRunChecks, warnings, summar
 
 Enable `electron`. Inputs are flat `{ action, ...fields, outputPath? }`; caller `stdin` and `sessionMode` are not accepted. The [Electron guide](ELECTRON.md) covers workflows and ownership.
 
-| Action | Fields | Behavior |
-| --- | --- | --- |
-| `list` | `query?`, `maxResults?` | Host-only bounded discovery; default 50, cap 200. No timeout field. macOS/Linux scanning only; Windows returns unsupported discovery. |
-| `launch` | Exactly one of `appPath`, `appName`, `bundleId`, `executablePath`; `appArgs?`, `handoff?`, `targetType?`, `timeoutMs?`, `allow?`, `deny?` | Verify Electron evidence, create a temporary isolated profile/OS-chosen debug port, attach through native connect, hand off, and record ownership. |
-| `status` | `launchId?` or `all: true`, `timeoutMs?` | Inspect tracked PID/port/profile and targets; explicit cleaned IDs remain inspectable as historical records. |
-| `probe` | `launchId?`, `timeoutMs?` | Verify URL then read title/focus/tabs/snapshot with owned session settings. Without an ID, inspect the current attached managed session. |
-| `cleanup` | `launchId?` or `all: true`, `timeoutMs?` | Close the tracked native session, stop only the owned app, verify port shutdown, remove its temporary profile. Partial cleanup fails with exact retry guidance. |
+| Action    | Fields                                                                                                                                    | Behavior                                                                                                                                                        |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `list`    | `query?`, `maxResults?`                                                                                                                   | Host-only bounded discovery; default 50, cap 200. No timeout field. macOS/Linux scanning only; Windows returns unsupported discovery.                           |
+| `launch`  | Exactly one of `appPath`, `appName`, `bundleId`, `executablePath`; `appArgs?`, `handoff?`, `targetType?`, `timeoutMs?`, `allow?`, `deny?` | Verify Electron evidence, create a temporary isolated profile/OS-chosen debug port, attach through native connect, hand off, and record ownership.              |
+| `status`  | `launchId?` or `all: true`, `timeoutMs?`                                                                                                  | Inspect tracked PID/port/profile and targets; explicit cleaned IDs remain inspectable as historical records.                                                    |
+| `probe`   | `launchId?`, `timeoutMs?`                                                                                                                 | Verify URL then read title/focus/tabs/snapshot with owned session settings. Without an ID, inspect the current attached managed session.                        |
+| `cleanup` | `launchId?` or `all: true`, `timeoutMs?`                                                                                                  | Close the tracked native session, stop only the owned app, verify port shutdown, remove its temporary profile. Partial cleanup fails with exact retry guidance. |
 
 ```json
 { "action": "launch", "appName": "Visual Studio Code", "handoff": "snapshot" }
@@ -444,7 +455,10 @@ For `eval --stdin`, put the script in the top-level `stdin` field. The wrapper n
 ```
 
 ```json
-{ "args": ["auth", "save", "my-login", "--password-stdin"], "stdin": "password from the user-approved secret source" }
+{
+	"args": ["auth", "save", "my-login", "--password-stdin"],
+	"stdin": "password from the user-approved secret source"
+}
 ```
 
 ### `outputPath`
@@ -460,7 +474,11 @@ For `eval --stdin`, put the script in the top-level `stdin` field. The wrapper n
 Example:
 
 ```json
-{ "args": ["eval", "--stdin"], "stdin": "({ title: document.title, url: location.href })", "outputPath": "logs/page-state.json" }
+{
+	"args": ["eval", "--stdin"],
+	"stdin": "({ title: document.title, url: location.href })",
+	"outputPath": "logs/page-state.json"
+}
 ```
 
 ### `timeoutMs`
@@ -488,6 +506,7 @@ A native `session` default from user/project JSON or `AGENT_BROWSER_SESSION` sel
 - default: `"auto"`
 
 Behavior:
+
 - if `args` already include `--session` (including argv compiled from `agent_browser_action.session`), upstream session choice wins
 - `"auto"` prepends the current extension-managed active session when appropriate
 - after resume, a confirmed inactive wrapper-owned daemon with automatic managed restore enabled reopens its complete recorded URL, including its fragment, before the first current-page operation, including `get url` and `reload`. Non-page calls such as `tab list` or explicit HTTP `read <url>` can start a daemon without consuming that pending reopen, even across branch/reload replay. The wrapper verifies the observed tab and invalidates old refs; native `open` resets frame scope. This reloads the page with restored cookies/storage, not unsaved forms, JavaScript memory, or history. Live wrong-tab recovery does not navigate. Explicit URL reads, URL `a11y`/`vitals`, `diff url`, `window new`, URL-bearing recording commands, and explicit navigation/context changes do not require the old tab. Caller-owned/attached and restore-disabled sessions are not auto-reopened
@@ -498,24 +517,27 @@ Behavior:
 - 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`)
 
 Recommended use:
+
 - use `"auto"` for the common browse/snapshot/click flow inside one `pi` session
 - use `"fresh"` when switching from an already-active implicit session to domain containment or a new profile/browser executable/debug/auth/provider launch without inventing a fixed explicit session name
 - when a fresh launch fails or times out before becoming current, check `details.managedSessionOutcome`: it states whether the prior managed session was preserved or whether the attempted fresh session was abandoned because no prior managed session existed; when `sessionMode` is `"fresh"` and the tool ultimately fails, the model-visible result also appends `Managed session outcome: …` (see `#details` below). Failures under `sessionMode: "auto"` still expose the struct on `details` when the extension injects a managed `--session`, but they do not add that extra prose line.
 
 ## Wrapper behavior
 
-Caller `args` should omit `--json`; the wrapper prepends it for normal execution so `details` and presentation stay structured. See [Wrapper `--json`](#wrapper-json).
+Caller `args` may omit `--json` for structured details and prose; explicit `--json false` selects opaque native text. See [Wrapper `--json`](#wrapper-json).
 
 The extension should:
-- inject `--json`
+
+- inject `--json` when no caller output mode is selected
 - invoke `agent-browser` directly, not through a shell
-- parse JSON output into tool details
+- parse JSON-mode output into tool details
 - handle observed JSON result shapes, including the array returned by `batch --json`
-- allow plain-text output for native inspection calls and valid sessionless `upgrade` commands; all other commands retain JSON envelope validation
+- allow plain-text output for native inspection calls, valid sessionless `upgrade` commands and explicit `--json false`; JSON-mode browser commands retain strict envelope validation
 - support those inspection calls unconditionally so the tool contract stays local and predictable
 
 <!-- agent-browser-playbook:start inspection -->
 <!-- Generated from extensions/agent-browser/lib/playbook.ts. Run `npm run docs -- playbook write` to update. -->
+
 Native inspection calls use the `agent_browser` tool shape, not shell-like direct-binary commands:
 
 - { "args": ["--help"] }
@@ -523,6 +545,7 @@ Native inspection calls use the `agent_browser` tool shape, not shell-like direc
 
 These calls return plain text and stay stateless: the extension does not inject its implicit session and does not let inspection consume the managed-session slot needed for later profile, session, CDP, state, auto-connect, or provider-backed launches.
 <!-- agent-browser-playbook:end inspection -->
+
 - still describe normal browser workflows in guidance so models do not overuse inspection for routine tasks
 - surface stderr and non-zero exits clearly
 - attach images when the result points to a screenshot-like artifact
@@ -554,6 +577,7 @@ Conditional `changed: false` captures have no new image/artifact attachment. A p
 ### Content
 
 Primary content should be:
+
 - useful result text for the model, not just a status line
 - an image attachment when relevant
 - browser-aware compacting for oversized snapshots so the model gets a concise actionable view before raw page noise
@@ -562,6 +586,7 @@ Primary content should be:
 - wrapper-side `snapshot -i --search <text>` and `snapshot -i --filter role=<role>` filters should strip those wrapper-only flags before upstream spawn, preserve the full latest ref map in `details.refSnapshot`, and render matching direct refs plus surrounding snapshot context with `details.snapshotFilter` counts so dense-page agents can find controls without opening raw spill files; search should also run one bounded read-only rendered-DOM probe across the full document so visible below-fold warnings and accessible labels omitted from the accessibility snapshot remain discoverable while hidden nodes stay excluded; the visible summary should distinguish direct ref matches from rendered/contextual matches to avoid apparent count mismatches; wrapper-side `--viewport` should also strip before upstream spawn, run one read-only viewport/scroll probe, and report `details.snapshotViewport`; wrapper-side `--diff` should strip before upstream spawn and report `details.snapshotDiff` against the previous wrapper-tracked ref map for that session
 
 Examples:
+
 - small `snapshot` results should include the actual snapshot text
 - oversized `snapshot` results should switch to a compact view that preserves the primary content, nearby sections, a trimmed set of high-value refs, and a separate bounded list of omitted high-value controls when dense pages or desktop host screens would otherwise hide editable inputs, named surfaces/tabs, or primary action buttons, while exposing the full redacted snapshot path directly in the rendered tool text and via `details.fullOutputPath`
 - successful navigation actions like `click`, `back`, `forward`, and `reload` should include a lightweight post-action title/url summary when the wrapper can address the active session
@@ -574,22 +599,22 @@ Recommended details:
 
 ```json
 {
-  "args": ["snapshot", "-i"],
-  "effectiveArgs": ["--json", "--session", "pi-abc123", "snapshot", "-i"],
-  "command": "snapshot",
-  "sessionMode": "auto",
-  "sessionName": "pi-abc123",
-  "usedImplicitSession": true,
-  "resultCategory": "success",
-  "successCategory": "completed",
-  "data": {
-    "origin": "https://example.com/",
-    "refs": {
-      "e1": { "name": "Example Domain", "role": "heading" }
-    },
-    "snapshot": "- heading \"Example Domain\" [level=1, ref=e1]"
-  },
-  "summary": "Snapshot: 1 refs on https://example.com/"
+	"args": ["snapshot", "-i"],
+	"effectiveArgs": ["--json", "--session", "pi-abc123", "snapshot", "-i"],
+	"command": "snapshot",
+	"sessionMode": "auto",
+	"sessionName": "pi-abc123",
+	"usedImplicitSession": true,
+	"resultCategory": "success",
+	"successCategory": "completed",
+	"data": {
+		"origin": "https://example.com/",
+		"refs": {
+			"e1": { "name": "Example Domain", "role": "heading" }
+		},
+		"snapshot": "- heading \"Example Domain\" [level=1, ref=e1]"
+	},
+	"summary": "Snapshot: 1 refs on https://example.com/"
 }
 ```
 
@@ -635,7 +660,7 @@ For `batch`, each `batchSteps[]` entry can carry its own `nextActions` for that
 
 `pageChangeSummary` is an optional compact summary for mutation-prone and artifact-producing commands. It includes `changeType` (`"navigation"`, `"mutation"`, `"artifact"`, or `"confirmation"`), `observed`, `command`, a readable `summary`, optional `title`/`url`, optional `artifactCount` or `savedFilePath`, and `nextActionIds`. `observed: false` means upstream dispatched a mutation-capable action but the wrapper did not observe an application change; standalone results also append a visible `Action dispatched; application change unverified` warning. The wrapper maintains explicit command/subcommand capability checks through `isPageChangeSummaryCommand` in `extensions/agent-browser/lib/command-taxonomy.ts`: those commands still emit a `mutation`-typed summary when upstream JSON lacks navigation metadata, as long as no stronger signal (artifact, saved path, navigation fields, or pending confirmation) applies. That capability is independent from `invalidatesBatchRefs` and `triggersPostMutationSnapshot`, so artifact summaries like `download` / `screenshot` and guarded-but-non-invalidating `fill` are documented directly in the capability table instead of implied by broad set spreading. Commands outside that set omit `pageChangeSummary` unless the parsed payload shows navigation, a confirmation prompt, saved files, or artifacts—including read-only inspection commands, which normally have no summary unless one of those signals appears. For `batch`, the top-level summary favors artifact rollups when any step produced artifacts; otherwise it synthesizes an observed-or-unverified summary from step evidence. Visible batch output promotes dispatch-only mutation evidence before step details and states that fixed waits are not postconditions. Agents should verify URL/text/state or an external receipt for important mutations before continuing.
 
-`clickDispatch` may appear after a **top-level non-Electron** direct `click` when the wrapper installed a target-specific DOM-event probe, upstream reported success, and the post-click probe found no trusted DOM event reached the resolved target. Target-specific probes cover `xpath=` targets and role-gated `@e…` refs when the latest wrapper-tracked snapshot has role/name metadata; eligible ref roles are `button`, `checkbox`, `menuitem`, `radio`, `switch`, and `tab`, and the role/name must be unique in both the saved snapshot and the live candidates. Before trusting either a ref or XPath candidate, the wrapper sets a per-probe temporary DOM attribute and requires native `get attr <original-selector> <marker>` readback to match it. Missing or mismatched identity, including XPath/frame scope mismatches, cleans up the probe and leaves the native click to run without dispatch verification. This does not implement a new accessible-name algorithm or promise that every ref is observable. Duplicate-name refs pass through without a probe because snapshot order can change and is not proof of target identity. Raw `find … click` locator calls, including compiled `agent_browser_action` clicks that still execute as upstream `find`, are not probed because the wrapper has no concrete element before upstream resolves the locator, and document-level probes can falsely fail frame-scoped clicks. It does **not** take a fresh pre-click snapshot because that could recycle upstream refs before the intended click. The wrapper does **not** replay clicks in-page. On a miss it marks the tool failed, appends `Click dispatch diagnostic: …`, and sets `clickDispatch.status` to `"no-native-event-observed"` with `reason: "native-click-produced-no-target-dom-event"`, `nativeEventCount`, and a redacted `target` descriptor (`kind: "xpath"` plus `selector`, or `kind: "accessible"` plus `refId`, `role`, and redacted `name`). `details.nextActions` gains `inspect-click-dispatch-miss` (`snapshot -i`) and `retry-click-after-dispatch-miss` (same upstream click argv, session-prefixed when applicable). If a local static fixture must be exercised despite this diagnostic, a caller may explicitly run a programmatic activation via `eval --stdin` such as `document.querySelector(...).click()`, but that emits an untrusted scripted event and is only a debugging/workaround path; it must not be used as proof that real user-like clicking works or to bypass prompt stop boundaries. This diagnostic is only for standalone top-level direct click calls; `find` locator clicks and native batch/QA click steps remain upstream-owned behavior.
+`clickDispatch` may appear after a **top-level non-Electron** direct `click` when the wrapper installed a target-specific DOM-event probe, upstream reported success, and the post-click probe found no trusted DOM event reached the resolved target. Target-specific probes cover `xpath=` targets and role-gated `@e…` refs when the latest wrapper-tracked snapshot has role/name metadata; eligible ref roles are `button`, `checkbox`, `menuitem`, `radio`, `switch`, and `tab`, and the role/name must be unique in both the saved snapshot and the live candidates. Before trusting either a ref or XPath candidate, the wrapper sets a per-probe temporary DOM attribute and requires native `get attr <original-selector> <marker>` readback to match it. Missing or mismatched identity, including XPath/frame scope mismatches, cleans up the probe and leaves the native click to run without dispatch verification. Probe listeners and the window marker self-expire after the call's process-timeout budget plus the existing two-second cleanup grace when a pending decision prevents normal cleanup; normal collection cancels the timer. Expiry dispatches no browser helper and missing/expired probes cannot diagnose a dispatch failure. This does not implement a new accessible-name algorithm or promise that every ref is observable. Duplicate-name refs pass through without a probe because snapshot order can change and is not proof of target identity. Raw `find … click` locator calls, including compiled `agent_browser_action` clicks that still execute as upstream `find`, are not probed because the wrapper has no concrete element before upstream resolves the locator, and document-level probes can falsely fail frame-scoped clicks. It does **not** take a fresh pre-click snapshot because that could recycle upstream refs before the intended click. The wrapper does **not** replay clicks in-page. On a miss it marks the tool failed, appends `Click dispatch diagnostic: …`, and sets `clickDispatch.status` to `"no-native-event-observed"` with `reason: "native-click-produced-no-target-dom-event"`, `nativeEventCount`, and a redacted `target` descriptor (`kind: "xpath"` plus `selector`, or `kind: "accessible"` plus `refId`, `role`, and redacted `name`). `details.nextActions` gains `inspect-click-dispatch-miss` (`snapshot -i`) and `retry-click-after-dispatch-miss` (same upstream click argv, session-prefixed when applicable). If a local static fixture must be exercised despite this diagnostic, a caller may explicitly run a programmatic activation via `eval --stdin` such as `document.querySelector(...).click()`, but that emits an untrusted scripted event and is only a debugging/workaround path; it must not be used as proof that real user-like clicking works or to bypass prompt stop boundaries. This diagnostic is only for standalone top-level direct click calls; `find` locator clicks and native batch/QA click steps remain upstream-owned behavior.
 
 `promptGuard` may appear on wrapper-blocked calls only for concrete, machine-checkable prompt requirements. `reason: "requested-artifacts-missing-before-close"` blocks `close` / `quit` / `exit` when the prompt used a direct screenshot/recording creation phrase with a destination such as `here`, `at`, `as`, or `to` and the session artifact manifest has not verified that exact path; a destination heading can carry that intent across contiguous plain or Markdown-bulleted path-only list lines. Bare, review-only, fenced-reference, conditional, permissive/uncertain, directly negated, and Pi clipboard/attachment image/video paths are treated as input, not output requirements, while subordinate requirements such as “do not close until you save” remain output intent. A recording-availability qualifier may precede, appear within, or follow its path/list and is scoped through the next path boundary; if the same path appears more than once, any required occurrence takes precedence. Markdown-link destinations resolve to the destination path. Explicitly optional artifacts are not close requirements. The classifier is deliberately conservative, so use wording such as `Save a screenshot here: <path>` when machine-enforced close blocking matters. Optional recording paths are only required when recording appears available. The wrapper does **not** parse broad user/business intent such as “do not place the order” or “do not post anything” into click/key blocks; agents must follow those instructions themselves. Prompt guards return `failureCategory: "policy-blocked"` and `validationError` text instead of invoking upstream.
 
@@ -697,6 +722,7 @@ Implementation and precedence:
 - The main tool implementation merges these fields into Pi-facing `details` from `extensions/agent-browser/index.ts` and from `extensions/agent-browser/lib/results/presentation.ts` for presentation-time failures.
 
 Additional structured fields can appear when relevant:
+
 - `sessionTabReopenPending: boolean` persists a confirmed-cold managed session's outstanding URL reopen through non-page commands and branch/reload replay. `true` means a daemon may have started but the remembered page has not been reopened; `false` means a reopen attempt or an executed explicit context/navigation command consumed the obligation, not that navigation succeeded. Cancellation after the reopen CLI starts returns `failureCategory: "aborted"`, the exact `sessionName` / `namespace`, the consumed `false` marker and ref invalidation through the normal result path, so replay cannot repeat the navigation. Cancellation before the CLI starts leaves the obligation pending. Successful close clears it with the rest of that session's page state. Internal remembered URLs retain their complete fragment; comparison remains fragment-insensitive and presentation redaction is unchanged. Old persisted targets without a fragment cannot reconstruct it.
 - `closeAllApplied: true` when a successful direct or nested `close` / `quit` / `exit --all` reached upstream. The marker makes live state and transcript replay clear every managed/attached/page/ref/route/trace/recording identity in the effective canonical namespace; a later batch row that proves browser reactivation may rebuild only the effective session.
 - `attachedBrowserSession: true` on successful calls that establish or reuse a wrapper-tracked CDP/auto-connect/Electron attachment, and on a failed fresh attachment only when `managedSessionOutcome.activeAfter` proves its daemon remained active for cleanup. The marker restores attachment continuity from the active transcript branch, including that active-after-failure case; live state and transcript replay remove it after a terminal successful close/cleanup even when aggregate verification failed; a close followed by a later step whose lifecycle reports a browser launch preserves it, while a successful non-launching diagnostic leaves the close terminal. Caller config, environment, paths, and file-access settings remain upstream-owned; the marker only adds live-URL verification and lifecycle continuity.
@@ -744,8 +770,8 @@ Additional structured fields can appear when relevant:
 - `imagePath` / `imagePaths` for Pi inline image attachments from the **`screenshot`** command (including batched screenshot steps). **`diff screenshot`** still records the diff output as an `image`-kind entry in `details.artifacts`, but it does **not** populate `imagePath` / `imagePaths` or attach an inline image: only plain `screenshot` is treated as a trusted live-capture path for automatic inlining (`isTrustedScreenshotOutput` in `extensions/agent-browser/lib/results/presentation/artifacts.ts`).
 - `artifacts` for saved files such as screenshots, `state save` outputs, `diff screenshot` diff images, PDFs, downloads, `wait --download` / `wait -d` files, traces, CPU profiles, completed video recordings, path-bearing HAR captures, and future recording output paths reported by `record start` / `record restart`. Non-file URL payloads such as `data:` / `blob:` / `http(s):` values are not treated as verified local artifacts. For direct artifact commands and batch artifact steps, the wrapper creates parent directories for requested paths before spawning upstream. Filesystem `mkdir` failures at this shared preparation boundary return `validation-error`, `agentBrowserStarted: false`, the attempted directory and `verify-artifact-path` guidance. When execution cwd differs from the launch/project root, relative file operands in raw batch strings are bound to the captured invocation root; otherwise raw strings stay unchanged and absolute artifact paths are preferred. Each artifact includes the original saved or requested `path`, resolved `absolutePath`, `kind`/`artifactType`, optional `mediaType`, optional `extension`, best-effort disk metadata such as `exists`, `sizeBytes`, and `updatedAtMs`, plus `requestedPath`, `status`, `cwd`, `session`, `namespace`, and `tempPath` when applicable. `requestedPath` is retained only when known from the caller, separately from reported/resolved locations; a differing screenshot report remains in `tempPath` and is displayed as `Reported path`, whether it is a temporary file or a canonical path alias. Ordinary file `mediaType` values come from bounded PNG/JPEG/GIF/WebP header recognition, not suffixes; unknown, missing, unreadable or truncated headers leave it undefined. Header recognition is not full-file format validation. Inline screenshot attachments use the same byte classifier and existing size limit. For commands that create/update artifacts, a path that existed but was not updated during this command uses `status: "stale"`; observational `wait --download` may accept a file completed just before the wait began. Pending `record start` / `record restart` artifacts use `status: "pending"`, omit `exists` rather than reporting false, and include `recordingState: "openRecording"` / `willExistOnStop: true`. Within one Pi extension process, the wrapper keeps an unbounded transcript-backed active-recording reservation index separate from the bounded artifact manifest, keyed by canonical namespace plus session; still-live process-owned reservations survive branch switches, while known closures are appended after tree navigation and during shutdown/reload so a close on one branch cannot be resurrected after returning to an older branch. Persisted active reservations require absolute storage paths and cwd; their display paths may remain relative. If a journal append fails, the next serialized browser boundary, tree navigation, or shutdown retries all current reservations and known closures. `recordingPersistenceWarning` and visible warning text remain present while restart protection is not durable; successful recovery is quiet and cleanup still runs. Artifact lifecycle calls, explicit `wait --download <path>` / `wait -d <path>` destinations, and result `outputPath` writes serialize around the global destination check/update, every successful direct, ordered nested-batch, fresh-replacement, code, Electron, or shutdown close retires only its exact identity at that lifecycle point, and destination reuse is rejected through lexical, existing or dangling symlink, hardlink, full Unicode-fold, or macOS/Windows case aliases. Batch preflight rejects `record start` / `record restart` after a close row because upstream can report a recording that did not start; split those operations into separate calls. A `No recording in progress` stop failure, direct or nested, first checks the matching native receipt once. Retirement preserves the receipt and freshly checked file metadata; it never turns an existing file into a missing file merely because no recording is active. A later successful batch recording row opens its new pending path normally. Batch preflight applies the same distinct-destination rule to the steps upstream will execute: raw argument command strings exclusively when any exist, stdin arrays only otherwise; upstream-ignored stdin rows cannot fail artifact preflight, add pending recordings, or create parent directories. Parent directories are prepared for the effective steps in both modes; outside execution-directory binding, raw argument strings stay unchanged, so screenshot normalization and tracked path requests apply to stdin rows only. Outer CLI globals are removed before artifact parsing, but native batch row operands stay literal: `pdf --quick ignored.pdf` targets `--quick`, not `ignored.pdf`. Reservation checks, preparation, and requested-path presentation follow that same distinction. Recording path/URL consumers skip complete numeric `--fps` pairs without rewriting argv; native still validates rate, format and extra arguments. FPS-only calls keep the intended pinned tab.
 
-
   Recording destinations are reserved within one Pi process, not across processes. Use unique paths for concurrent Pi processes: different explicit sessions can overwrite one file even when both `record stop` results are verified. Upstream’s same-session `record start` guard does not reserve the filename across other sessions.
+
 - `savedFilePath` / `savedFile` for direct `download`, `pdf`, and `wait --download` / `wait -d` saved-file workflows when a host file path is reported or wrapper-verified. Batch results preserve the same fields on the relevant `batchSteps` entry. These fields are metadata only until `artifactVerification` verifies the file. Native `download <selector> <path>` always owns the click and download, including loopback links, generated Blob exports, and redirects; the wrapper does not substitute a fetch of an anchor's `href`.
 - `batchSteps[].artifacts` for per-step artifacts in `batch` output; top-level `artifacts` and `artifactManifest` coalesce an earlier pending recording into the later saved, missing, or stale terminal result for the same namespace/session identity. `record restart` includes both the previous recording it finalized (or an explicit missing/stale failure) and the new pending recording; missing/stale terminal rows retire the prior pending manifest row. A successful later `close` / `quit` / `exit` retires an earlier unfinalized pending recording as `subcommand: "close-abandoned"`, clears its stop action, and leaves its file unverified. Batch presentation checks the path: only a confirmed absent file becomes `status: "missing"`; a present or inaccessible file stays unverified. It updates aggregate verification/manifest state consistently; a later successful `record stop` replaces that intermediate abandoned row with its saved artifact. Close also resets ref/page/network-route state produced by earlier rows; later lifecycle-proven browser launches, including `record stop`, can rebuild that state without triggering stale pre-close `about:blank` recovery, explicitly non-launching diagnostics cannot, and unknown later rows stay conservatively active. Per-step history remains unchanged. When any later call on the same namespace/session fails while a recording remains pending, `nextActions` combines its normal recovery with exact `stop-pending-recording` args and visible cleanup guidance; the same applies at top level when a later batch step fails. After reload in a non-Git checkout or with managed restore disabled, a live daemon without current-instance provenance or a matching same-owner native daemon receipt cannot accept a stop. A tracked Electron attachment can rebuild that proof through the live debug-endpoint check described above; unproven restore-disabled sessions cannot rebuild provenance from a name or URL. That policy refusal includes `managedSessionCleanupOnlyReason: "restore-disabled-daemon-without-provenance"` plus the exact `sessionName`/`namespace`, including on implicit calls. It replaces the impossible stop with `close-pending-recording`, an exact close without `sessionMode: "fresh"`. Close retires the recording as `close-abandoned`; any file it leaves is unverified. Same-instance recordings and supported durable-Git reloads still use stop and normal WebM verification.
 - `artifactVerification` for a normalized verification summary on the unified result and on each successful `batchSteps[]` row and on failed recording rows whose receipt identifies an artifact. Top-level `batch` verification rolls up all step file artifacts; each step’s summary reflects that step’s nested tool presentation (including its spill paths and manifest slice). It reports `verified`, `verifiedCount`, `missingCount`, `pendingCount`, `unverifiedCount`, and `artifacts[]` entries with `path`, optional `absolutePath`, optional `requestedPath`, `kind` (a normal file artifact kind or `"spill"` for manifest-backed rows), optional `mediaType`, optional `exists`, optional `sizeBytes`, optional `updatedAtMs`, optional `status`, optional `retentionState` / `storageScope` on manifest-derived rows, `state` (`verified`, `missing`, `pending`, or `unverified`), and optional `limitation` (human-readable lifecycle or retention context, for example pending `record start` / `record restart`, missing, stale, or otherwise unverified files, ephemeral spill files, or evicted persisted spills). The summary `verified` boolean is true only when every entry is `verified`. `record start` / `record restart` are `pending` until `record stop`; `state load` may mention a path in command output but is not a saved artifact row.
@@ -787,11 +813,11 @@ Matching requires the actual namespace/session, expected path and known recordin
 
 ## Browser-independent read confirmations
 
-`details.readConfirmation` stores only native control-response provenance for an actual explicit URL read: `{ id, sessionName, namespace?, source: "native-explicit-url-read", state: "pending" | "cleared", capabilities? }`. Page content, nested JSON text and bare DOM reads do not establish this provenance. It is replayed in existing per-session transcript state on resume/branch changes and retired by successful confirmation/denial or session close.
+`details.readConfirmation` retains native control-response provenance in the existing per-session transcript state: `{ id, sessionName, namespace?, source, state: "pending" | "cleared", capabilities?, command?, action?, refSnapshotFresh?: true }`. `source: "native-guarded-action"` carries only the compact originating command and native action, never argv or a command replay blob. `source: "native-explicit-url-read"` remains specific to explicit URL reads. Page content, eval results and JSON-looking text cannot establish either provenance.
 
-Routing uses the actual native session, including `default` when the original read did not allocate a managed browser. Explicit caller session/namespace choices still win, and code calls cannot borrow another session's confirmation. Legacy native prompts retain this routing. Only a control response with `capabilities.readRequiresConfirmation: true` also proves native explicit-ID matching and enables matching confirm/deny without page helpers or managed-browser replacement. Legacy/unproven and DOM confirmations retain normal page checks. The advertised capability requires native ID validation before consuming a pending action, so a stale read ID cannot approve a later DOM action. A failed or expired confirmation returns exact session-status guidance, not an automatic retry of another ID.
+Routing preserves the actual native session, including `default` for an unallocated explicit read, through resume/branch replay. Explicit caller identities and the code cell's fixed identity still win. An exact pending ID/canonical-identity match for a genuine guarded control suppresses page/pinning helpers that could replace the native pending slot; it neither proves native ID validation nor grants browser independence. Completed guarded actions and confirmed native batch rows use ordinary page/ref reconciliation, including click/eval/tab effects and successful close retirement through direct and code replay. Only a matching first effective guarded batch decision suppresses pre-command helpers; raw arguments still take precedence over stdin, and later page/ref/unknown-target checks remain. Requested-action pending is not labelled as a hidden helper; helper-origin pending retains its own diagnostic, and an early helper decision explicitly states that the requested command was not dispatched. Only explicit URL-read `capabilities.readRequiresConfirmation: true` grants browser-independent confirm/deny and promises native ID validation. Legacy URL reads and unrelated/nonmatching decisions keep normal checks. Failed or expired confirmations offer exact session inspection, never automatic approval of another ID. A genuine `tab_new` control may include the paired transport fields `after_confirmation: ["open", <original requested URL>]` and nonempty `guidance`; other extra fields or mismatched/malformed continuations do not grant confirmation provenance. The original URL is read with ordinary command operand handling, including preceding labels and headers. Valid conditional guidance stays model-visible and redacted: approval creates the blank/labeled tab, and only a separate caller-requested navigation follows; denial must not navigate. These fields are not stored as command replay, automatically executed, or accepted from page/eval/HTTP content.
 
-A confirmed HTTP failure is a tool failure regardless of that capability, including inside a batch. A pending confirmation is not success even when the native outer envelope says otherwise. If a new DOM confirmation replaces a pending read, the old read marker clears and the new confirmation keeps its own approve/deny actions and normal page checks.
+A failed inner native confirmed action is a tool failure, including inside a batch, even when the outer confirmation succeeds. Nested confirmations stay pending and retain the original compact command provenance. A new native guarded control replaces the previous marker and supplies its own exact actions. A completed confirmed full snapshot installs returned refs in direct and ordered batch results; pending, denied, failed or partial captures do not grant freshness. When it is the final completed row, `refSnapshotFresh: true` allows the next same-identity call to reuse that sample once instead of requesting another gated freshness snapshot. Semantic role click/check/fill and unique role/label select use that same eligible capture with its editable metadata and unchanged action payloads. The call consumes the marker, including across direct/code/batch replay; any intervening same-identity call consumes it too. Pending snapshot controls use the ordinary confirmation-required presentation and executable actions; they are not empty-page observations. Target, membership, invalidation and native generation checks remain. On this one use, required live verification compares the complete capture URL, including fragments, and rejects refs when it changes—including wrapper-owned managed sessions and warm sessions without resume. Ordinary ref/tab URL comparisons remain fragment-insensitive. A DOM-only rename on the same page after the approved sample is not resampled on this one use; later ref operations retain ordinary freshness checks. Confirmed close also retires attachment state on live and resumed paths. If a cold managed reopen helper is pending, the result exposes that decision with `agentBrowserStarted: false` for the requested getter, unknown page target and invalid refs; it does not dispatch the getter or replay open. Successful confirm can then reconcile the native resulting target before immediate title/body inspection.
 
 ## High-value result rendering
 
@@ -800,6 +826,7 @@ A confirmed HTTP failure is a tool failure regardless of that capability, includ
 The TUI renderer is user-facing only. It may compact or colorize what the human sees in the Pi transcript, but it must not further truncate, summarize, or remove the model-facing `content` returned by the tool. Use the existing `details.fullOutputPath` / spill-file contracts for content that is too large for the model.
 
 Worth doing in v1:
+
 - screenshots → saved-path summary, visible artifact metadata, `details.artifacts` metadata, and inline image attachment when safe; screenshot paths that upstream would treat ambiguously, such as `.dogfood/run/foo.png`, are normalized to absolute paths before launch and repaired from upstream temp output when possible
 - file artifacts such as PDFs, downloads, `wait --download` / `wait -d` files, `state save` state files, diff screenshot output images, traces, CPU profiles, completed video recordings, and path-bearing HAR captures → concise saved-path summaries plus metadata in `details.artifacts` and changed/referenced invocation receipts in `details.artifactManifest`; `record start` / `record restart` report recording lifecycle state and the future output path without adding a missing manifest entry, and `record restart` can also report the previous wrapper-known recording that was finalized by the restart; native 0.37 checks `ffmpeg` before starting video capture, while older supported natives may defer failure; successful start/restart calls without ffmpeg expose `details.recordingDependencyWarning` and leave output unverified until checked after stop; direct saved-file workflows also expose `details.savedFilePath` / `details.savedFile`; large or binary artifacts are not inlined into model context; the recent manifest cap can age out explicit-file metadata but does not remove explicit saved files from disk
 - `diff screenshot` → same file-artifact pattern as above for the **diff** image path only (summary text uses “Saved diff image” only when the diff output exists; missing output says “Diff image reported; file not verified” and fails as `artifact-missing`); baseline paths and other fields stay in the structured payload but are not echoed as separate saved artifacts in the visible artifact block, and there is no Pi inline image attachment for the diff output
@@ -819,6 +846,7 @@ Worth doing in v1:
 ## Missing binary behavior
 
 If `agent-browser` is not on `PATH`, fail with a message that:
+
 - says `agent-browser` is required
 - says this project does not bundle it
 - points to upstream install/docs
@@ -845,15 +873,19 @@ If `agent-browser` is not on `PATH`, fail with a message that:
 - 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.
 - 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 -->
 <!-- Generated from extensions/agent-browser/lib/playbook.ts. Run `npm run docs -- playbook write` to update. -->
+
 - After open/goto/navigate calls with --profile, --restore, --session-name, or --state, agent_browser best-effort re-selects the tab whose URL matches the returned page when restored tabs steal focus during launch or reconnect.
 - After confirmed shutdown of an automatically restored managed session, the wrapper retains its complete recorded URL, including the fragment, until the first current-page operation (including get url and reload). Non-page calls such as tab list may start a daemon without fulfilling that reopen; explicit URL reads leave the managed browser and pending reopen untouched. The wrapper uses native open once, verifies the observed tab, and discards old refs/frame scope; it does not restore unsaved forms, JavaScript memory, or history. Explicit navigation, caller-owned/attached sessions, and restore-disabled sessions are not auto-reopened.
 - For a still-live browser after tab drift or resume, the wrapper verifies/selects the intended tab before ref/semantic helpers and page commands; failed selection stops the call without navigating. Local commands, read <url>, URL a11y/vitals, diff url, window new, and explicit tab/navigation/connection/state recovery do not require the prior tab. Batch checks follow effective rows past non-page prefixes and stop at explicit context changes, preserving caller argv/stdin and continue-on-error behavior. Same-tab reselection is avoided because it clears refs. Use exact batch --bail for fail-fast, not --bail=<value>. Routine same-session calls skip tab-list preflights.
 - For sessions with observed tab-drift risk, after a successful command on a known target tab, agent_browser also best-effort restores that intended tab if a restored/background tab steals focus after the command completes. Routine same-session commands skip focus correction; observed pages without a native targetId use tab list to establish their identity.
 - If a known session target unexpectedly reports about:blank, agent_browser best-effort re-selects the prior intended target when it still exists; if recovery fails, it records the observed about:blank target and reports exact recovery guidance instead of treating the prior page as active.
 - If upstream reports tab_gone, the pinned bound tab is gone; use details.nextActions (tab list / tab new) instead of assuming another tab is yours.
+
 <!-- agent-browser-playbook:end wrapper-tab-recovery -->
+
 - caller-owned sessions honor native `AGENT_BROWSER_SOCKET_DIR` unless the wrapper-specific socket override is set, using the same integrity checks; on other local Unix launches, set a short private socket directory for wrapper-spawned `agent-browser` processes so extension-generated session names do not fail the upstream Unix socket-path length limit in longer cwd/session-name combinations; require an absolute non-symlink directory owned by the current uid with mode `0700`, otherwise fail before spawn. Socket checks trust the operating environment's actual `/`, not its reported UID; all non-root ownership, permission and alias-destination checks remain in force. This is not protection from the controller of the root filesystem; see [socket trust](ARCHITECTURE.md#ownership). Android/Termux uses a short directory under the owner-only `/data/data/<package>` app sandbox, compacts generated managed identities to one 80-bit digest so ordinary namespace plus fresh-session paths remain within the limit, stores policy-lock coordination under `os.tmpdir()`, and probes process identity with Termux's `ps` beside Node instead of unavailable `/bin/ps`
 - keep wrapper-spawned commands bounded by clamping `AGENT_BROWSER_DEFAULT_TIMEOUT` to the upstream documented default of 25 seconds while the default wrapper child-process watchdog is 35 seconds (`PI_AGENT_BROWSER_PROCESS_TIMEOUT_MS` overrides it, and top-level `timeoutMs` overrides it per call for browser CLI subprocesses). Explicit `wait <ms>`, `wait --timeout <ms>`, and WebMCP `invoke` / `result --timeout <ms>` calls can exceed that default; when top-level `timeoutMs` is omitted, the wrapper derives a per-call subprocess watchdog from the requested command duration plus a small grace window. Dialog commands use `PI_AGENT_BROWSER_DIALOG_PROCESS_TIMEOUT_MS` (default 5000 ms), and click/tap/find refs or tokens plus `eval --stdin` snippets whose text looks like alert/confirm/prompt/dialog triggers use `PI_AGENT_BROWSER_DIALOG_TRIGGER_PROCESS_TIMEOUT_MS` (default 8000 ms). Timed-out advanced QA or native batch calls may add `details.timeoutPartialProgress` and visible `Timeout partial progress` evidence with per-step status, retry payloads, current page title/URL, and declared artifact path checks; timed-out dialog-like commands may add dialog status/dismiss/fresh-session recovery next actions
 - interactive or long-running upstream families such as `chat` without a prompt, `dashboard start`, `stream enable`, `trace start`, `profiler start`, `record start`, `inspect`, `install`, `upgrade`, `doctor --fix`, and `confirm-interactive` are passed through thinly but remain bounded by the same wrapper timeout/session planning rules; prefer explicit arguments, single-shot `chat <message>`, non-interactive flags like `doctor --offline --quick` or `doctor --json`, and cleanup pairs such as `dashboard stop`, `stream disable`, `trace stop`, `profiler stop`, and `record stop`
@@ -871,35 +903,38 @@ This is neither a browser transaction nor rollback. It does not coordinate human
 
 The 0.7 public contract removes old multimode `agent_browser` inputs. Native CLI coverage, authentication, recordings, artifacts, diagnostics, and specialized outcomes remain available.
 
-| Previous 0.6 input | 0.7 replacement |
-| --- | --- |
-| `agent_browser { args, stdin?, outputPath?, timeoutMs?, sessionMode? }` | Same compact direct shape |
-| `agent_browser { script: source }` | `agent_browser_code { code: source, session?, namespace?, timeoutMs?, outputPath? }`; check `.success`, not `.ok`; browser now persists |
-| `agent_browser { job: { steps, failFast? } }` | Native `batch --bail` with argv rows; omit `--bail` only for deliberate safe continuation, or use code for branching |
-| `agent_browser { semanticAction: fields }` | Enable `action`, then `agent_browser_action { ...fields }` |
-| `agent_browser { qa: fields }` | Enable `qa`, then `agent_browser_qa { ...fields }` |
-| `agent_browser { electron: fields }` | Enable `electron`, then `agent_browser_electron { ...fields }` |
-| `agent_browser { sourceLookup: fields }` | Enable `source`, then `agent_browser_source { ...fields }` |
-| `agent_browser { networkSourceLookup: fields }` | Enable `network`, then `agent_browser_network_source { ...fields }` |
+| Previous 0.6 input                                                      | 0.7 replacement                                                                                                                         |
+| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `agent_browser { args, stdin?, outputPath?, timeoutMs?, sessionMode? }` | Same compact direct shape                                                                                                               |
+| `agent_browser { script: source }`                                      | `agent_browser_code { code: source, session?, namespace?, timeoutMs?, outputPath? }`; check `.success`, not `.ok`; browser now persists |
+| `agent_browser { job: { steps, failFast? } }`                           | Native `batch --bail` with argv rows; omit `--bail` only for deliberate safe continuation, or use code for branching                    |
+| `agent_browser { semanticAction: fields }`                              | Enable `action`, then `agent_browser_action { ...fields }`                                                                              |
+| `agent_browser { qa: fields }`                                          | Enable `qa`, then `agent_browser_qa { ...fields }`                                                                                      |
+| `agent_browser { electron: fields }`                                    | Enable `electron`, then `agent_browser_electron { ...fields }`                                                                          |
+| `agent_browser { sourceLookup: fields }`                                | Enable `source`, then `agent_browser_source { ...fields }`                                                                              |
+| `agent_browser { networkSourceLookup: fields }`                         | Enable `network`, then `agent_browser_network_source { ...fields }`                                                                     |
 
 Move former outer `outputPath`/`timeoutMs` alongside advanced flat fields where supported. Action has optional `session` but no `sessionMode`; QA/source/network retain `sessionMode`; Electron `timeoutMs` is flat and action-specific (`list` rejects it). Code chooses session/namespace in the parent.
 
-| Former job step | Native argv rows |
-| --- | --- |
-| `open` plus `loadState` | `open <url>`, then `wait --load <state>` |
-| Selector `click` / `fill` | Ordinary command with selector and optional text |
-| Locator click/fill | `find <locator> <value> <action> ...` |
-| `select` | `select <selector> <value...>` |
-| `wait` | `wait <milliseconds>` |
-| `assertText` / `assertUrl` | `wait --text <text>` / `wait --url <url-or-glob>` |
-| `waitForDownload` | `wait --download <path>` |
-| `snapshot` / `screenshot` | `snapshot -i` / `screenshot <path>` |
-| Paced `type` | Optional `focus <selector>`, interleaved `keyboard type <character>` / `wait <delayMs>`, optional final `press <key>` |
+| Former job step            | Native argv rows                                                                                                      |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `open` plus `loadState`    | `open <url>`, then `wait --load <state>`                                                                              |
+| Selector `click` / `fill`  | Ordinary command with selector and optional text                                                                      |
+| Locator click/fill         | `find <locator> <value> <action> ...`                                                                                 |
+| `select`                   | `select <selector> <value...>`                                                                                        |
+| `wait`                     | `wait <milliseconds>`                                                                                                 |
+| `assertText` / `assertUrl` | `wait --text <text>` / `wait --url <url-or-glob>`                                                                     |
+| `waitForDownload`          | `wait --download <path>`                                                                                              |
+| `snapshot` / `screenshot`  | `snapshot -i` / `screenshot <path>`                                                                                   |
+| Paced `type`               | Optional `focus <selector>`, interleaved `keyboard type <character>` / `wait <delayMs>`, optional final `press <key>` |
 
 For exact delayed-input behavior, build native rows instead of relying on unverified native `--delay` equivalence. Keep the former 200-character pacing bound when porting that workflow. Typing `hi` with a 20 ms gap:
 
 ```json
-{ "args": ["batch", "--bail"], "stdin": "[[\"focus\",\"#prompt\"],[\"keyboard\",\"type\",\"h\"],[\"wait\",\"20\"],[\"keyboard\",\"type\",\"i\"]]" }
+{
+	"args": ["batch", "--bail"],
+	"stdin": "[[\"focus\",\"#prompt\"],[\"keyboard\",\"type\",\"h\"],[\"wait\",\"20\"],[\"keyboard\",\"type\",\"i\"]]"
+}
 ```
 
 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.