pi-agent-browser-native 0.6.5 → 0.6.7

package/CHANGELOG.md

@@ -1,6 +1,35 @@
 # Changelog
 
-## Unreleased
+## 0.6.7 - 2026-09-07
+
+### Fixed
+
+- Remove four unused prompt suffix entries without changing runtime guidance. Thanks to @JsonKim for #133.
+- Diagnose misplaced Chromium `--no-sandbox` command/navigation options with effective top-level `--args` guidance, while preserving literal operands and help. Adapted from @ahalekelly's #152.
+- Correct Electron list timeout guidance, label explicit-ID cleaned launch records as historical, and report fresh tracked-profile path presence independently of process/port liveness. Failed-launch output capture remains unresolved (#128).
+- Return structured artifact-directory preparation failures for direct, stdin and raw batch commands, retaining the attempted path and recovery guidance. Document absolute artifact paths for raw batches without rewriting their command strings (#124).
+- Identify image media types and inline attachments from bytes instead of filename suffixes, distinguish known requested and reported artifact paths, and surface fresh-snapshot warnings for reached recording page transitions on success and failure (#127).
+- Accept native `upgrade` text without reporting a JSON parse failure, retain failure diagnostics and explicit `--json` output, and keep timeout/cancellation failures even when the child exits zero. Thanks to @fgpaz for the report and regression approach in #156.
+- Clarify positional screenshot and recording paths, the screenshot `--full` flag, batch stdin's JSON token-array format, text-only `job.assertText`, ref refreshes after clicks, focused `keyboard type <text>`, and positional `wait <ms>` in tool guidance.
+- Stop using duplicate-name snapshot ordinals as click-failure evidence after the page changes. Ambiguous refs pass through to native clicking without a probe; unique targets retain no-event checks, and native dispatch still does not prove application state.
+- Accept an unmapped owner for the operating environment's actual filesystem root when validating private socket storage in Linux user namespaces. Preserve non-root ownership, permissions, alias-destination and entry checks, including existing root-owned sticky modes; automatic restore still rejects unmapped non-root HOME ancestry.
+- Let URL-opening QA clear diagnostics and navigate even when the previous tab is gone. Explicit URL reads, URL accessibility/vitals audits, URL diffs, new windows and URL-bearing recording commands also keep their own destination in direct and batch calls; attached QA and current-page actions still require the intended page.
+- Retain a resumed managed session's pending URL reopen after confirmed shutdown, even when non-page calls start the daemon first or a batch begins with non-page steps. Reopen the complete URL, including its fragment, before current-page reads or history commands; verify the observed tab and discard old refs/frame scope. Unreached batch navigation does not consume the reopen, and native row/error order is unchanged. Restored cookies/storage do not recover unsaved forms, JavaScript memory, or history; live wrong-tab recovery and explicit navigation keep their own intent.
+- Keep follow-ups on the observed page after `window new` or `diff url`, including redirected destinations and reached native batch rows. Do not reselect the old tab for an intentional blank window or an observed blank diff destination; invalidate old refs and require a verified target when the final URL cannot be observed.
+- Preserve the consumed cold-reopen marker and exact session identity in aborted results, so cancellation after an attempted reopen cannot navigate a live browser again after reload. Cancellation before the attempt leaves the reopen pending.
+- Require observed successful page results in lifecycle verification and report the first unexpected completed tool result instead of accepting recovery text or waiting for a later result.
+
+- Preserve native arguments, literal values, refs, and continue-on-error behavior during tab recovery. Failed tab selection stops before user commands; mixed batch failures retain their per-step results and failure counts.
+- Apply stale-ref checks to `@eN`, `eN`, and `ref=eN` selector operands without treating text, paths, or keyboard/mouse data as refs. Explain unsupported `batch --bail=<value>` without running ignored stdin.
+- Retry failed recording journal writes, preserve closed recording state across branch changes and reloads, require absolute stored recording paths, and target cleanup to the exact session and namespace. Preserve the selected managed-session namespace and automatic restore when ambient namespace settings change.
+- Limit `semanticAction.values` to select actions in the tool schema and clarify the supported `stdin` commands. Valid semantic calls are unchanged; runtime validation still applies. Thanks to @lindsayemarc for #139.
+- Check socket-directory ancestry through root-owned symlinks, rejecting unsafe destination parents and intermediate user-owned links while preserving trusted system aliases.
+
+## 0.6.6 - 2026-09-05
+
+### Fixed
+
+- Resolve POSIX process identity with `ps` from `PATH` when the system paths are unavailable, so managed-session locks work on NixOS-style installations. Keep system-path preference and reject malformed identity output. Thanks to @GodTamIt for the report and fix in #142 / #143.
 
 ## 0.6.5 - 2026-09-04
 

package/README.md

@@ -79,7 +79,7 @@ The result is optimized for agent work:
 | Stateful cookies/storage/auth output bloats or leaks context | Presentation layer redacts `details.data` for cookies and credential-like storage values while keeping low-risk local QA values such as `theme: dark` readable; recursively scrubs other structured upstream JSON (network, diff, trace/profiler, stream, dashboard, chat, auth, dialog, frame, state, and similar) using sensitive key names plus string heuristics; masks sensitive argv flags and positionals; scrubs secrets from failed batch step errors; and exposes a compact redacted `batch` matrix on top-level `details.data` | `extensions/agent-browser/lib/results/presentation.ts`, `extensions/agent-browser/lib/results/presentation/diagnostics.ts`, `extensions/agent-browser/lib/runtime.ts`, `test/agent-browser.presentation-diagnostics.test.ts` |
 | Stale `@eN` refs fail mysteriously | Records per-session `details.refSnapshot`, rejects mismatched URLs / unknown refs / unsafe `batch` stdin ordering before spawn, adds recovery guidance to rerun `snapshot -i` or use stable `find` locators | `extensions/agent-browser/index.ts`, `extensions/agent-browser/lib/session-page-state.ts`, `test/agent-browser.session-page-state.test.ts`, `test/agent-browser.results.test.ts`, `test/agent-browser.extension-ref-guards.test.ts`, `test/agent-browser.extension-semantic-recovery.test.ts` |
 | Agents need stable success/failure buckets | Exposes bounded `resultCategory`, `successCategory`, and `failureCategory` on tool `details` for branching without parsing prose; a `tool_result` hook also aligns real Pi `isError` semantics, naming `Pi tool isError: true` in prose output while preserving parseable caller-requested `--json` output | [`docs/TOOL_CONTRACT.md`](docs/TOOL_CONTRACT.md#details), `extensions/agent-browser/lib/results/categories.ts`, `extensions/agent-browser/index.ts`, `extensions/agent-browser/lib/pi-tool-rendering.ts`, `test/agent-browser.results.test.ts`, `test/agent-browser.extension-validation.test.ts`, `test/agent-browser.pi-pipeline.test.ts` |
-| Clicks can report success without the page receiving the event | Top-level non-Electron direct `click` calls on `xpath=` targets or role-gated current `@e…` refs (`button`, `checkbox`, `menuitem`, `radio`, `switch`, `tab`) install a bounded target-specific DOM-event probe; eligible `@e…` refs use the latest snapshot role/name metadata, and duplicate-name refs use snapshot-order `duplicateIndex` rather than requiring a unique name. If upstream reports success but no trusted event reaches the resolved target, the wrapper fails the tool, exposes `details.clickDispatch`, and suggests explicit retry/inspect next actions (no in-page replay), including a nested-scroll `scrollintoview` action when the probe sees the target outside a scroll container or viewport. Unresolved locator clicks such as raw `find … click` are left upstream-owned to avoid false failures for frame-scoped targets. Other click results still expose `details.pageChangeSummary`; `observed: false` explicitly marks dispatch-only mutation summaries and adds a visible `Action dispatched; application change unverified` warning. Unchanged-URL clicks can surface evidence-backed `details.overlayBlockers` candidates. | [`docs/TOOL_CONTRACT.md`](docs/TOOL_CONTRACT.md#details), `extensions/agent-browser/lib/orchestration/browser-run/click-dispatch.ts`, `extensions/agent-browser/lib/results/presentation/navigation.ts`, `test/agent-browser.presentation.test.ts`, `test/agent-browser.extension-click-dispatch.test.ts` |
+| Clicks can report success without the page receiving the event | Top-level non-Electron direct `click` calls on `xpath=` targets or role-gated current `@e…` refs (`button`, `checkbox`, `menuitem`, `radio`, `switch`, `tab`) install a bounded target-specific DOM-event probe; eligible `@e…` refs require a unique role/name in both the latest snapshot and the live candidates. Duplicate-name refs pass through without a probe: their old ordinal cannot prove which element received the click. If upstream reports success but no trusted event reaches the resolved target, the wrapper fails the tool, exposes `details.clickDispatch`, and suggests explicit retry/inspect next actions (no in-page replay), including a nested-scroll `scrollintoview` action when the probe sees the target outside a scroll container or viewport. Unresolved locator clicks such as raw `find … click` are left upstream-owned to avoid false failures for frame-scoped targets. Other click results still expose `details.pageChangeSummary`; `observed: false` explicitly marks dispatch-only mutation summaries and adds a visible `Action dispatched; application change unverified` warning. Unchanged-URL clicks can surface evidence-backed `details.overlayBlockers` candidates. | [`docs/TOOL_CONTRACT.md`](docs/TOOL_CONTRACT.md#details), `extensions/agent-browser/lib/orchestration/browser-run/click-dispatch.ts`, `extensions/agent-browser/lib/results/presentation/navigation.ts`, `test/agent-browser.presentation.test.ts`, `test/agent-browser.extension-click-dispatch.test.ts` |
 | Dashboard scroll commands can look successful while nothing moves | Handles standard `scroll <dir> [px]` against the document first (including pages whose smooth-scroll CSS defeats upstream wheel timing), falls back upstream when the document cannot move, and samples viewport/containers around the fallback; unchanged positions fail as `upstream-error` with `details.scrollNoop`, visible recovery guidance, and exact snapshot/screenshot checks. Unsupported `scrollintoview text=...` fails before dispatch, including inside effective batch rows, and shows exact native `find text ... hover` and snapshot/ref recovery payloads; help remains native pass-through. | [`docs/TOOL_CONTRACT.md`](docs/TOOL_CONTRACT.md#details), [`docs/COMMAND_REFERENCE.md`](docs/COMMAND_REFERENCE.md#core-page-and-element-commands), `test/agent-browser.extension-validation.test.ts` |
 | Dropdown/combobox clicks can focus or hit native option box-model errors | Adds first-class `select <selector> <value...>` paths through raw `args`, `job`, and `semanticAction`; semantic role/name or label select resolves exactly one current visible combobox/listbox ref before action. Custom combobox clicks still detect focused controls with explicit `aria-expanded` state but no visible options and return `details.comboboxFocus` plus exact recovery `nextActions` | [`docs/TOOL_CONTRACT.md`](docs/TOOL_CONTRACT.md#details), [`docs/COMMAND_REFERENCE.md`](docs/COMMAND_REFERENCE.md#core-page-and-element-commands), `extensions/agent-browser/lib/input-modes/semantic-action.ts`, `test/agent-browser.extension-input-modes.test.ts`, `test/agent-browser.extension-validation.test.ts` |
 | Recording workflows fail late when `ffmpeg` is missing or report stale lifecycle state | After successful `record start` / `record restart`, reports `successCategory: "artifact-pending"`, returns an exact `stop-pending-recording` action, warns when `ffmpeg` is unavailable, and tells agents that `record start` switches to a fresh active page whose in-page state does not carry over while invalidating prior page-scoped `@e…` refs on every executed start attempt (even a failed already-active one) and on URL-bearing `record restart` (stale-ref until a fresh snapshot); an unbounded transcript-backed namespace/session index reserves active destinations across aliases, serializes artifact lifecycle and explicit wait/output writes, persists cross-branch close tombstones, retires every successful close path (including every matching namespace owner for `close --all`), rejects missing/stale restart output, coalesces terminal batch state, keeps only the newest pending path per identity, rejects recording starts after a nested close, folds Unicode path aliases, and retains exact cleanup actions with visible guidance on any later same-session failure | [`docs/TOOL_CONTRACT.md`](docs/TOOL_CONTRACT.md#details), [`docs/COMMAND_REFERENCE.md`](docs/COMMAND_REFERENCE.md#diff-debug-and-streaming), `test/agent-browser.extension-validation.test.ts`, `test/agent-browser.presentation-artifacts-batch.test.ts` |
@@ -88,6 +88,8 @@ The result is optimized for agent work:
 | Desktop Electron apps need discovery, CDP attach, and safe teardown | Top-level `electron` runs host `list` / isolated `launch` (temp profile, OS-chosen debug port) / `status` / `probe` / `cleanup`, merges `launchId` plus managed `sessionName`, supports `handoff` `snapshot` / `tabs` / `connect`, and surfaces mismatch and post-command health guidance; wrapper cleanup applies only to launches it created | `extensions/agent-browser/lib/electron/discovery.ts`, `launch.ts`, `cleanup.ts`, [`docs/TOOL_CONTRACT.md`](docs/TOOL_CONTRACT.md#electron), [`docs/COMMAND_REFERENCE.md`](docs/COMMAND_REFERENCE.md#electron-desktop-apps) |
 | Agents need bundled `skills` text and local setup/status commands without touching the live session | Treats `skills list/get/path`, local auth/profile/setup commands, `session list`, and local state lifecycle commands as sessionless reads/actions when upstream does not need a live page. Session/state rows and targets remain visible, and supported upstream state/config/path operations pass through unchanged. Browser-backed workflows still receive an implicit session only when the caller did not choose one. | [`docs/COMMAND_REFERENCE.md`](docs/COMMAND_REFERENCE.md#built-in-skills), `extensions/agent-browser/lib/command-policy.ts`, `extensions/agent-browser/lib/runtime.ts` |
 
+Artifact results show known requested paths separately from reported/resolved locations and infer image MIME types from file headers, not suffixes. Parent-directory failures return path-specific `validation-error` guidance before browser dispatch. Use absolute artifact paths in raw batch strings because the daemon's working directory may differ from Pi's. Dispatched `record start` and URL-bearing `record restart` attempts also return one fresh-snapshot warning on success or failure, including in JSON output; unreached rows do not claim a page change.
+
 ## Fastest way to try it
 
 Use Pi 0.84.0 or newer. This package keeps optional Pi core imports as wildcard `peerDependencies` because Pi package docs require the host Pi install to provide those packages, pins its direct Pi validation dependencies to 0.84.0, and makes older hosts a setup failure through `pi-agent-browser-doctor`. There are no compatibility shims for older Pi releases.
@@ -190,6 +192,8 @@ It does **not** edit Pi settings and does **not** run upstream `agent-browser do
 
 Pi hosts that run as uid 0 should set `PI_AGENT_BROWSER_SOCKET_DIR` to a short absolute directory under private root-owned ancestry, create it with mode `0700`, and keep it owned by the Pi user. The extension validates that directory and forwards it as upstream `AGENT_BROWSER_SOCKET_DIR`; ambient upstream socket overrides remain ignored.
 
+In a Linux user namespace, `/` may report an unmapped owner. Socket checks trust that operating-environment root while retaining checks on every other ancestor and the private socket directory; they do not protect against whoever controls the root filesystem. The demonstrated bubblewrap layout uses a read-only mode-`0755` root and a current-user-owned mode-`0700` `/tmp`, with private HOME and checkout below it. Unmapped non-root ancestors such as `/home` still fail automatic restore checks; this is not support for every bubblewrap layout. See [filesystem trust](docs/ARCHITECTURE.md#ownership).
+
 ## Optional package config and web search
 
 `pi-agent-browser-native` also reads package-owned config under Pi-scoped paths:
@@ -307,6 +311,8 @@ Open a page and inspect it (first-call recipe: open → snapshot -i → interact
 { "args": ["snapshot", "-i"] }
 ```
 
+Chromium launch switches belong in the value of `--args`, for example `{ "args": ["--args", "--no-sandbox", "open", "https://example.com"], "sessionMode": "fresh" }` when that switch is needed. A bare `--no-sandbox` in the command slot is an unknown command; in an `open` / `goto` / `navigate` option position, upstream ignores it. The wrapper diagnoses those forms without rejecting literal text, select values or paths in other commands. For batches, put `--args` in top-level `args` before `batch`, not inside a row.
+
 Watch a browser window during a demo, QA run, or user-completed login by adding upstream's global `--headed` flag on the first launch. Use `sessionMode: "fresh"` if a managed session may already exist, because headed/headless state is launch-scoped. A successful first/fresh local wrapper-managed headed launch, including a launch inside `batch`, returns `details.browserWindow = { mode: "headed", ownership: "wrapper-managed", sessionName, visibility: "unverified" }` and one visible handoff sentence; CDP, auto-connect, provider, and Electron attachments do not. This proves that the wrapper requested and upstream launched headed mode, not that the OS window is visible on the user's display; remote, container, or virtual-display setups can still hide it. After the user finishes in the window, continue with `sessionMode: "auto"`.
 
 ```json
@@ -441,7 +447,7 @@ Typical pitfalls:
 - Do not reuse `@e…` refs across navigation or in-place rerenders. The wrapper records the latest snapshot refs per session and fails stale/recycled getter and mutation refs, including batched getters, before upstream can silently read or hit a different current-page element; use the session-aware `refresh-interactive-refs` next action.
 - If upstream classifies the failure as `stale-ref` and `details.compiledSemanticAction` is present for a compiled `find` action, `details.nextActions` may list `retry-semantic-action-after-stale-ref` after `refresh-interactive-refs`, carrying the same compiled `find` argv so you can retry the locator-stable target once it is safe to do so. `select` calls that used stale `@refs` only get refresh guidance; use a fresh snapshot or stable selector before retrying (contract in [`docs/TOOL_CONTRACT.md#semanticaction`](docs/TOOL_CONTRACT.md#semanticaction)).
 - If the failure is `selector-not-found`, the wrapper may take one fresh snapshot and add `Current snapshot ref fallback` when that snapshot has exact visible role/name matches for the failed `find` / `semanticAction` target. Non-fill targets can include direct `try-current-visible-ref*` next actions, and semantic click misses can still add bounded `Agent-browser candidate fallbacks` such as `button`/`link` role retries for `text` clicks. `semanticAction` does not expose `uncheck` while upstream `find ... uncheck` is not runtime-supported; use raw `args: ["uncheck", <selector-or-ref>]` after a stable selector or fresh snapshot ref. For semantic `fill` misses on desktop or host-controlled rich inputs, prefer `details.richInputRecovery`: refresh refs, choose the current editable `@ref`, focus or click it, then use `keyboard type` for framework-controlled editors that require real key events. `keyboard inserttext` is paste-like and can change a DOM value without updating application state, so use it only with separate application-state verification. Direct contenteditable fills are verified with `get text` when snapshot metadata proves the target is contenteditable; if replacement did not happen, `details.fillVerification` warns before any submit step. Those recovery nextActions do not copy the fill text and do not press `Enter` or submit; only submit when the user flow explicitly calls for it (same contract link).
-- A successful upstream `click` is not proof that the web app handled the event or changed state. For top-level non-Electron direct clicks on `xpath=` targets and eligible current `@e…` refs, the wrapper may fail the tool with `details.clickDispatch` and a `Click dispatch diagnostic` line when upstream reported success but no trusted DOM event reached the resolved target. Raw `find … click` locator calls 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. `@e…` ref click probes are limited to current snapshot refs with accessible role `button`, `checkbox`, `menuitem`, `radio`, `switch`, or `tab`, using duplicate-name snapshot order when needed. Use the suggested `inspect-click-dispatch-miss` / `retry-click-after-dispatch-miss` next actions instead of assuming the click mutated the page; when `details.clickDispatch.scrollContainer` is present, use `scroll-target-into-view-after-dispatch-miss` first. When the task depends on a mutation, follow `inspect-after-mutation` / `pageChangeSummary` evidence with a wait, URL/text check, or fresh snapshot before trusting the result; if the target still did not change, retry with a current visible ref or stable selector and report the workflow issue instead of silently continuing. For static local fixtures where the user only needs to exercise app code, an explicit `eval --stdin` programmatic click such as `document.querySelector("#demo").click()` can be a diagnostic workaround, but treat it as an untrusted scripted activation rather than proof a real user click works, and never use it to bypass user instructions. Respect explicit user stop boundaries yourself: if the user says to stop before order/post/purchase/submit, gather evidence on that page and do not click the final action. The wrapper does not parse broad prompt text into business-intent action blocks; `details.promptGuard` is reserved for concrete artifact-before-close checks.
+- A successful upstream `click` is not proof that the web app handled the event or changed state. For top-level non-Electron direct clicks on `xpath=` targets and eligible current `@e…` refs, the wrapper may fail the tool with `details.clickDispatch` and a `Click dispatch diagnostic` line when upstream reported success but no trusted DOM event reached the resolved target. Raw `find … click` locator calls 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. `@e…` ref click probes are limited to current snapshot refs with accessible role `button`, `checkbox`, `menuitem`, `radio`, `switch`, or `tab`, with a unique role/name in both the saved snapshot and the live candidates. Duplicate-name refs remain upstream-owned; snapshot order is not target identity. Use the suggested `inspect-click-dispatch-miss` / `retry-click-after-dispatch-miss` next actions instead of assuming the click mutated the page; when `details.clickDispatch.scrollContainer` is present, use `scroll-target-into-view-after-dispatch-miss` first. When the task depends on a mutation, follow `inspect-after-mutation` / `pageChangeSummary` evidence with a wait, URL/text check, or fresh snapshot before trusting the result; if the target still did not change, retry with a current visible ref or stable selector and report the workflow issue instead of silently continuing. For static local fixtures where the user only needs to exercise app code, an explicit `eval --stdin` programmatic click such as `document.querySelector("#demo").click()` can be a diagnostic workaround, but treat it as an untrusted scripted activation rather than proof a real user click works, and never use it to bypass user instructions. Respect explicit user stop boundaries yourself: if the user says to stop before order/post/purchase/submit, gather evidence on that page and do not click the final action. The wrapper does not parse broad prompt text into business-intent action blocks; `details.promptGuard` is reserved for concrete artifact-before-close checks.
 - A successful upstream `click` can deliver no input at all on some sites. Reproduced against `https://www.saucedemo.com/` with upstream `agent-browser` 0.34.0 and no wrapper involved: when every CLI invocation in the flow is spaced ~0.6s apart, the React add-to-cart click reports success while **zero** DOM events reach a capture-phase listener and the cart badge never updates (0/5 runs succeeded, versus 4/5 with no spacing). A single idle gap is harmless (5/5); only sustained spacing across the flow triggers it. In that state a scripted `document.querySelector(...).click()` still works and updates the badge, so the page and its handlers are fine and the input never arrives; retries, `scrollintoview`, headed mode, and re-navigation do not recover it. This looks site-specific — React TodoMVC and react.dev were unaffected under the same pacing and command count. Wrapper calls do more per-command work than raw CLI calls, so they sit in the slow regime more often. Running the interaction steps as one `batch` keeps them inside a single upstream process and succeeded 5/5; prefer `batch` for consecutive real-app click flows, and treat a click whose `pageChangeSummary`/`navigationSummary` shows no change as unproven. When a `wait --url` or `assertUrl` times out after a suspected missed click, use the `fresh-session-after-url-wait-timeout` next action (`sessionMode: "fresh"` + `open about:blank`): replace about:blank with the target URL and replay the flow as one batch in a fresh session instead of retrying the wait.
 - A successful `snapshot -i` can surface `Possible overlay blockers` immediately when refs already contain strong dialog/alertdialog evidence plus close/dismiss controls. If a **top-level** `@e…`/`ref=` click succeeds (unified command `click`, not a `batch` step), upstream reports `data.clicked`, and `details.navigationSummary.url` stays on the same tab URL under the same normalization as ref preflight (fragment-insensitive), the wrapper may take one extra `snapshot -i` and add `Possible overlay blockers` with `details.overlayBlockers` (`candidates`, `summary`, optional `snapshot` refresh for refs) plus session-aware `inspect-overlay-state` / bounded `try-overlay-blocker-candidate-*` next actions when that snapshot shows strong modal context (`dialog` / `alertdialog`) and close/dismiss-like controls. Page-wide words like privacy, sign in, or banner alone do not trigger this diagnostic. The unchanged-URL check compares the prior pinned tab target with `details.navigationSummary.url`; CSS selector clicks do not run this overlay probe. Also skipped when tab correction or about-blank recovery already ran on that result.
 - If `get text <selector>` reads a non-ref, non-simple-id CSS selector with multiple matches or a hidden first match while visible matches exist, including successful `batch` steps, the wrapper may add `Selector text visibility warning`, `details.selectorTextVisibility` (plus `selectorTextVisibilityAll` for multiple batched warnings), and `inspect-visible-text-candidates` next actions; the warning names the matching `details.nextActions` id. Prefer a visible `@ref`, a scoped selector, or a targeted `eval --stdin` over hidden tab content.
@@ -451,6 +457,8 @@ Typical pitfalls:
 
 For short repeatable workflows, pass a top-level `job` instead of hand-writing `batch` stdin. Keep dynamic app jobs short around navigation, click, and rerender boundaries; avoid packing a whole checkout into one job. The wrapper only supports constrained steps (`open`, `click`, `fill`, `type`, `select`, `wait`, `assertText`, `assertUrl`, `waitForDownload`, `snapshot`, and `screenshot`), compiles them to existing upstream `batch` commands, and echoes the compiled commands as `details.compiledJob` for auditability. `open` steps can include `loadState` (`domcontentloaded`, `load`, or `networkidle`) to insert a readiness wait before the next step. `click` and `fill` steps can use either CSS `selector` or semantic locator fields (`locator`, `role`/`value`, optional `name`) so a job can express flows like role/name search without brittle selectors. `type` can use `selector`, `text`, optional `delayMs` for per-character pacing, and optional `press` for a final key such as `Enter`; paced type compiles to existing `focus`, `keyboard type`, `wait`, and `press` batch rows, is capped at 200 characters per delayed step, and compacts model-visible batch text while full rows remain in `details.batchSteps`. The same compile path backs top-level `qa`, so long `qa` runs surface the same timeout evidence shape. If a long `job`, `qa`, or `batch` hits the wrapper watchdog, `details.timeoutPartialProgress` may recover per-step status (`completed`, `failed`, `pending`, or `unknown`), current page URL plus a title after the URL is verified, declared artifact paths that already exist on disk, and either a `retry-timeout-step` next action for the first incomplete read-only or idempotent step, `inspect-current-page-after-timeout` when the target is already verified, or a fail-fast `verify-page-target-after-timeout` batch that runs `get url` before `snapshot -i` when the target is unknown (see [`docs/TOOL_CONTRACT.md#details`](docs/TOOL_CONTRACT.md#details)). There is no separate catalog of reusable named browser recipes above one-shot ad hoc `script`, `job`, `qa`, and raw `batch`; `script` has no names, registry, or persistent workflow state; see [`docs/ARCHITECTURE.md#no-reusable-recipe-layer-yet`](docs/ARCHITECTURE.md#no-reusable-recipe-layer-yet) for the closed `RQ-0068` decision and when to revisit it.
 
+`assertText` accepts only `text`, not selector or locator fields. Clicks can stale later `@refs`; split the job and take a fresh snapshot before using them.
+
 **Navigation inside `job` is explicit.** A successful `click` does not prove the next page loaded; add `assertUrl` and/or `assertText` after navigation-prone clicks (forms, checkout, tabs, submit buttons) before screenshots or steps that assume the new page. `assertUrl` accepts exact URLs and `*` / `**` glob-style patterns and now compiles directly to upstream `wait --url` for both forms.
 
 ```json
@@ -497,7 +505,9 @@ For desktop Electron apps, use top-level `electron` to avoid hand-building the d
 { "electron": { "action": "cleanup", "launchId": "electron-…" } }
 ```
 
-`electron.probe.timeoutMs` bounds each underlying read subprocess when dense desktop apps need a shorter or longer probe budget (omit for the normal tool subprocess default). `electron.cleanup.timeoutMs` caps upstream `close` plus host profile/process teardown and defaults to the implicit session close budget unless overridden; if the managed-session close step succeeds but host cleanup is partial, later default browser calls still rotate away from that closed wrapper-managed session. `electron.status.timeoutMs` only tightens managed-session title/url reads used for mismatch checks. Pass `electron.probe.launchId` when you want the probe tied to a wrapper-tracked launch instead of only the current managed session. Launch/status/probe results show both `launchId` (for status/cleanup/probe) and `sessionName` (for browser `snapshot`/`tab` commands); if the managed session drifts to `about:blank` while wrapper status still sees a live renderer, Electron-specific mismatch warnings and `status`/`probe`/`reattach`/`snapshot` next actions replace generic tab guidance. `/reload` preserves the current branch-visible active Electron launch and its isolated temp `userDataDir` for continuity, and cleans off-branch owned Electron launches; if cleanup is partial and skips or fails profile removal, the generic temp sweep preserves that `userDataDir` across reload, quit, later temp cleanup, process exit, and stale temp-root pruning after restart. If the app process/debug port dies after a successful-looking mutation, the wrapper reports `details.electronPostCommandHealth` and fails with `tab-drift` instead of quietly continuing on `about:blank`. Launch timeouts expose `details.electron.failure.diagnostics` for PID, profile, DevToolsActivePort, and timing evidence.
+`electron.list` has no configurable timeout. Other Electron actions accept nested `electron.timeoutMs`; `electron.probe.timeoutMs` bounds each underlying read subprocess when dense desktop apps need a shorter or longer probe budget (omit for the normal tool subprocess default). `electron.cleanup.timeoutMs` applies separately to upstream `close` and the initial process-exit wait, not the whole teardown, and defaults to the implicit session close budget unless overridden; if the managed-session close step succeeds but host cleanup is partial, later default browser calls still rotate away from that closed wrapper-managed session. `electron.status.timeoutMs` only tightens managed-session title/url reads used for mismatch checks. Pass `electron.probe.launchId` when you want the probe tied to a wrapper-tracked launch instead of only the current managed session. Launch/status/probe results show both `launchId` (for status/cleanup/probe) and `sessionName` (for browser `snapshot`/`tab` commands); if the managed session drifts to `about:blank` while wrapper status still sees a live renderer, Electron-specific mismatch warnings and `status`/`probe`/`reattach`/`snapshot` next actions replace generic tab guidance. `/reload` preserves the current branch-visible active Electron launch and its isolated temp `userDataDir` for continuity, and cleans off-branch owned Electron launches; if cleanup is partial and skips or fails profile removal, the generic temp sweep preserves that `userDataDir` across reload, quit, later temp cleanup, process exit, and stale temp-root pruning after restart. If the app process/debug port dies after a successful-looking mutation, the wrapper reports `details.electronPostCommandHealth` and fails with `tab-drift` instead of quietly continuing on `about:blank`. Launch timeouts expose `details.electron.failure.diagnostics` for PID, profile, DevToolsActivePort, and timing evidence.
+
+Explicit-ID `electron.status` labels historical cleaned launch records; default and `all: true` selection exclude them. Current PID/port liveness stays independent of cleanup history. `details.electron.statuses[].userDataDirState` freshly measures only the tracked profile path: `present` (including dangling symlinks), `absent` (ENOENT), or `unknown` (other `lstat` errors), not whether all app residue is gone.
 
 `launch.handoff` still defaults to `"snapshot"`; it retries briefly when the first Electron snapshot has no refs. Use `handoff: "tabs"` as a safer diagnostic starting point when you only need target discovery and do not want interactive refs captured yet, or `handoff: "connect"` when you want attach-only and will run your own `snapshot -i` / tab commands next. For Electron quick inputs that rerender in place, a successful `fill` may include `details.fillVerification` if `get value` still disagrees; re-snapshot and use focus plus keyboard typing before submitting.
 
@@ -512,7 +522,7 @@ For an app you launched yourself with remote debugging enabled, use raw upstream
 
 `connect` success means the debug endpoint accepted the session, not that an active page is ready. Use the returned `verify-connected-session-url` (`get url`) action before page-content reads, then inspect/select a stable tab and verify its URL. If a snapshot says `No active page`, the wrapper clears prior refs for that session; choose a stable `t<N>` tab and retry a condition wait or fresh `snapshot -i` before using `@e…` refs. Close commands (`close`, `quit`, or `exit`) only close the browser/CDP session; manually launched apps, their profiles, and explicit screenshots/downloads/HARs/traces/recordings remain host-owned.
 
-After either path, use `qa: { "attached": true, ... }` for a current-session smoke check without opening a URL. Attached QA preserves existing network/console/page-error buffers instead of clearing them, so it can catch errors raised before the check started; visible output and `details.compiledQaPreset.checks.diagnosticsResetAtStart` identify that scope. Prefer condition waits (`wait --text`, `wait --url`, `wait --fn`, `wait --load <state>`, `wait --download`), `qa.attached`, `electron.probe` / `electron.status`, `tab list` → `tab t<N>`, fresh snapshots, or screenshots over blind sleeps. Fixed waits are a last resort: use explicit `--timeout` or top-level `timeoutMs` for legitimately slow waits, and treat a result like `"waited":"timeout"` as elapsed time only. Batch output promotes dispatch-only mutation evidence and states that fixed waits are not postconditions.
+After either path, use `qa: { "attached": true, ... }` for a current-session smoke check without opening a URL. Attached QA preserves existing network/console/page-error buffers instead of clearing them, so it can catch errors raised before the check started; visible output and `details.compiledQaPreset.checks.diagnosticsResetAtStart` identify that scope. Prefer condition waits (`wait --text`, `wait --url`, `wait --fn`, `wait --load <state>`, `wait --download`), `qa.attached`, `electron.probe` / `electron.status`, `tab list` → `tab t<N>`, fresh snapshots, or screenshots over blind sleeps. Fixed waits are a last resort: use positional `wait <ms>`, not `wait --time <ms>`. Use explicit `--timeout` or top-level `timeoutMs` for legitimately slow waits, and treat a result like `"waited":"timeout"` as elapsed time only. Batch output promotes dispatch-only mutation evidence and states that fixed waits are not postconditions.
 
 ### Lightweight QA preset
 
@@ -574,6 +584,10 @@ Start a fresh launch with a different Chromium-compatible executable:
 }
 ```
 
+After resuming a wrapper-managed session whose daemon has fully stopped, the first current-page operation, including `get url` or `reload`, reopens the complete recorded URL, including its fragment, when automatic managed restore is enabled. Non-page calls such as `tab list` or `read <url>` may start a daemon first without losing that pending reopen. The wrapper verifies the observed page and discards old refs; take a fresh `snapshot -i` before using refs. This restores the URL with cookies/storage, not unsaved forms, JavaScript memory, or history. A still-live wrong tab is selected or reported as missing, never silently navigated. Explicit URL reads, URL `a11y`/`vitals`, `diff url`, `window new`, and explicit navigation/context changes do not require the old tab. Caller-owned/attached and restore-disabled sessions are not auto-reopened. Cancellation after the reopen CLI starts preserves the consumed marker in the aborted result; replay does not repeat the navigation. Cancellation before that attempt leaves the reopen pending.
+
+`window new` leaves its new `about:blank` page active; `diff url` leaves the observed second destination active, including redirects to `about:blank`. Direct calls and reached batch rows discard the old target and refs rather than repinning the old tab. If the final URL cannot be observed, run `get url` before a fresh `snapshot -i`; the second URL argument alone is not proof of the final page.
+
 After a successful unnamed fresh launch, later default `sessionMode: "auto"` calls follow that browser automatically. If the fresh launch fails or times out, `details.managedSessionOutcome` records whether the previous managed session was preserved or the attempted fresh session was abandoned before any managed session became current; a `Managed session outcome: …` line is appended only when the failing call used `sessionMode: "fresh"`. If you explicitly close the current wrapper-managed session with `--session <name> close`, later default auto calls rotate to a new wrapper-generated session instead of reusing that closed name, and repeated closes keep reserving fresh names across resume/branch restore.
 
 ## Authenticated/profile workflows
@@ -797,7 +811,8 @@ These calls return plain text and stay stateless: the extension does not inject
 <!-- 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 the wrapper observes tab-drift risk for a session (for example open correction, overlapping stale opens, or resumed session state), later active-tab commands best-effort pin that tab inside the same upstream invocation. Routine same-session commands are not preflighted with tab list just because a target tab or ref snapshot is known.
+- 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 or read <url> may start a daemon without fulfilling that reopen. 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 this post-command tab-list probe.
 - 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.

package/dist/extensions/agent-browser/index.js

@@ -5,7 +5,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { batchHasSuccessfulCloseAll, getSuccessfulBatchCloseLifecycle } from "./lib/batch-lifecycle.js";
 import { PROJECT_RULE_PROMPT, buildBrowserDefaultProfileGuideline, buildBrowserExecutablePathGuideline, buildToolPromptGuidelines, } from "./lib/playbook.js";
 import { SessionPageState } from "./lib/session-page-state.js";
-import { canUseHeadlessCompatibilityUserAgent, createEphemeralSessionSeed, createFreshSessionName, createImplicitSessionName, extractUpstreamCommandTokens, getImplicitSessionCloseTimeoutMs, getImplicitSessionIdleTimeoutMs, isRestorableManagedSessionName, restoreManagedSessionStateFromBranch, validateToolArgs, redactSensitiveText, isPlainTextInspectionArgs, } from "./lib/runtime.js";
+import { buildExecutionPlan, canUseHeadlessCompatibilityUserAgent, createEphemeralSessionSeed, createFreshSessionName, createImplicitSessionName, extractUpstreamCommandTokens, getImplicitSessionCloseTimeoutMs, getImplicitSessionIdleTimeoutMs, isRestorableManagedSessionName, restoreManagedSessionStateFromBranch, validateToolArgs, redactSensitiveText, isPlainTextInspectionArgs, } from "./lib/runtime.js";
 import { extractExplicitNamespace, extractExplicitSessionName, getAgentBrowserSessionIdentityKey, isAgentBrowserSessionIdentityKeyInNamespace, isUpstreamEnvFlagEnabled, resolveAgentBrowserNamespace } from "./lib/argv-grammar.js";
 import { parseArgvDescriptor } from "./lib/argv-descriptor.js";
 import { needsManagedSession } from "./lib/command-policy.js";
@@ -680,7 +680,7 @@ function shouldSerializeBrowserCommand(options) {
         return true;
     if (options.explicitSessionName === options.managedSessionName)
         return true;
-    if (options.ownedManagedSessions.has(getSessionContextKey(options.explicitSessionName, options.explicitNamespace) ?? options.explicitSessionName))
+    if (options.ownedManagedSessions.has(getSessionContextKey(options.explicitSessionName, options.namespace) ?? options.explicitSessionName))
         return true;
     return getActiveElectronRecords(options.ownedElectronLaunchRecords).some((record) => record.sessionName === options.explicitSessionName);
 }
@@ -844,7 +844,7 @@ export default function agentBrowserExtension(pi) {
     let artifactManifest;
     let activeRecordingReservations = new Map();
     let recordingSessionTombstones = new Map();
-    let recordingSessionTombstonesToPersist = new Map();
+    let recordingReservationsDirty = false;
     let attachedSessionKeys = new Set();
     let networkRoutesBySession = new Map();
     let electronLaunchRecords = new Map();
@@ -861,23 +861,64 @@ export default function agentBrowserExtension(pi) {
     let branchRestoreGeneration = 0;
     let branchStateGeneration = 0;
     const validatedUpstreamPathKeys = new Set();
+    const recordingPersistenceWarning = "Recording persistence warning: recording protection could not be saved to the Pi journal. Restart protection is not yet durable; keep recording destinations untouched until exact stop or close. The next browser operation retries journal persistence; cleanup remains available.";
+    const flushRecordingReservations = () => {
+        if (!recordingReservationsDirty)
+            return;
+        try {
+            // Pi updates branch memory before writing. One failed append can hide an earlier
+            // durable reservation after reopen, so republish all current state, not just the failed row.
+            for (const reservation of recordingSessionTombstones.values())
+                appendRecordingReservationTransition(pi, { reservation, state: "closed" });
+            for (const reservation of activeRecordingReservations.values())
+                appendRecordingReservationTransition(pi, { reservation, state: "active" });
+            recordingReservationsDirty = false;
+        }
+        catch { }
+    };
+    const warnRecordingPersistence = (result) => {
+        if (!recordingReservationsDirty)
+            return result;
+        const content = [...result.content];
+        const first = content[0];
+        let json;
+        if (first?.type === "text") {
+            try {
+                json = JSON.parse(first.text);
+            }
+            catch { }
+        }
+        if (isRecord(json) && typeof json.success === "boolean") {
+            content[0] = { type: "text", text: JSON.stringify({ ...json, warnings: [...(Array.isArray(json.warnings) ? json.warnings : []), recordingPersistenceWarning] }, null, 2) };
+        }
+        else if (first?.type === "text")
+            content[0] = { ...first, text: `${first.text}\n\n${recordingPersistenceWarning}` };
+        else
+            content.push({ type: "text", text: recordingPersistenceWarning });
+        return { ...result, content, details: { ...(isRecord(result.details) ? result.details : {}), recordingPersistenceWarning } };
+    };
+    const notifyRecordingPersistence = (ctx) => {
+        if (!recordingReservationsDirty)
+            return;
+        if (ctx.hasUI)
+            ctx.ui.notify(recordingPersistenceWarning, "warning");
+        else
+            console.warn(recordingPersistenceWarning);
+    };
     const appendRecordingTransitions = (transitions) => {
         for (const transition of transitions) {
             const key = getAgentBrowserSessionIdentityKey(transition.reservation.sessionName, transition.reservation.namespace);
-            if (transition.state === "active") {
+            if (transition.state === "active")
                 recordingSessionTombstones.delete(key);
-                recordingSessionTombstonesToPersist.delete(key);
-            }
-            else {
+            else
                 recordingSessionTombstones.set(key, transition.reservation);
-            }
+            if (recordingReservationsDirty)
+                continue;
             try {
                 appendRecordingReservationTransition(pi, transition);
-                recordingSessionTombstonesToPersist.delete(key);
             }
             catch {
-                if (transition.state === "closed")
-                    recordingSessionTombstonesToPersist.set(key, transition.reservation);
+                recordingReservationsDirty = true;
             }
         }
     };
@@ -885,19 +926,28 @@ export default function agentBrowserExtension(pi) {
         if (result.isError !== true)
             return result;
         const details = isRecord(result.details) ? result.details : {};
-        const nextActions = Array.isArray(details.nextActions) ? [...details.nextActions] : [];
-        if (nextActions.some((action) => action.id === "stop-pending-recording"))
+        const cleanupOnly = details.managedSessionCleanupOnlyReason === "restore-disabled-daemon-without-provenance";
+        const nextActions = (Array.isArray(details.nextActions) ? details.nextActions : [])
+            .filter((action) => !cleanupOnly || action.id !== "stop-pending-recording");
+        const actionId = cleanupOnly ? "close-pending-recording" : "stop-pending-recording";
+        if (nextActions.some((action) => action.id === actionId))
             return result;
         const stopActions = applyNamespaceToNextActions(applySessionToNextActions([
             buildNextToolAction({
-                args: ["record", "stop"],
-                id: "stop-pending-recording",
-                reason: "Stop the active recording so the requested video can be finalized and verified on disk.",
-                safety: "The file remains pending until record stop succeeds; verify details.artifactVerification afterward.",
+                args: cleanupOnly ? ["close"] : ["record", "stop"],
+                id: actionId,
+                reason: cleanupOnly
+                    ? "Close this exact session to abandon the recording; its live daemon lacks current-instance provenance."
+                    : "Stop the active recording so the requested video can be finalized and verified on disk.",
+                safety: cleanupOnly
+                    ? "Close does not verify the WebM. The recording is abandoned/unverified, even if close leaves a file on disk."
+                    : "The file remains pending until record stop succeeds; verify details.artifactVerification afterward.",
             }),
-        ], reservation.sessionName), reservation.namespace);
+        ], reservation.sessionName), cleanupOnly ? reservation.namespace ?? "" : reservation.namespace);
         appendUniqueAgentBrowserNextActions(nextActions, stopActions);
-        const cleanupNotice = "An active recording remains open. Use the exact stop-pending-recording payload in details.nextActions before leaving this session.";
+        const cleanupNotice = cleanupOnly
+            ? "This recording cannot be stopped through the unproven daemon. Use the exact close-pending-recording payload in details.nextActions; any WebM left by close is abandoned/unverified."
+            : "An active recording remains open. Use the exact stop-pending-recording payload in details.nextActions before leaving this session.";
         let noticeAppended = false;
         const content = result.content.map((item) => {
             if (noticeAppended || item.type !== "text")
@@ -917,18 +967,7 @@ export default function agentBrowserExtension(pi) {
         if (!reservation && artifactManifest === previousManifest)
             return;
         const terminalReservation = reservation ?? { absolutePath: "", cwd: managedSessionCwd, namespace, path: "", sessionName };
-        const terminalKey = getAgentBrowserSessionIdentityKey(sessionName, namespace);
-        recordingSessionTombstones.set(terminalKey, terminalReservation);
-        try {
-            appendRecordingReservationTransition(pi, {
-                reservation: terminalReservation,
-                state: "closed",
-            });
-            recordingSessionTombstonesToPersist.delete(terminalKey);
-        }
-        catch {
-            recordingSessionTombstonesToPersist.set(terminalKey, terminalReservation);
-        }
+        appendRecordingTransitions([{ reservation: terminalReservation, state: "closed" }]);
     };
     const syncRecordingReservationsFromResult = (result) => {
         const handledClosedSessionKeys = new Set();
@@ -1107,20 +1146,25 @@ export default function agentBrowserExtension(pi) {
         traceOwners = new Map();
         artifactManifest = restoreArtifactManifestFromBranch(branch);
         const restoredRecordingState = restoreRecordingReservationStateFromBranch(branch);
-        for (const [key, reservation] of recordingSessionTombstones) {
-            if (restoredRecordingState.terminal.has(key))
-                recordingSessionTombstonesToPersist.delete(key);
-            else
-                recordingSessionTombstonesToPersist.set(key, reservation);
+        for (const key of recordingSessionTombstones.keys()) {
+            if (!restoredRecordingState.terminal.has(key))
+                recordingReservationsDirty = true;
         }
         for (const [key, reservation] of restoredRecordingState.terminal) {
             if (!activeRecordingReservations.has(key))
                 recordingSessionTombstones.set(key, reservation);
         }
-        for (const key of recordingSessionTombstones.keys())
+        for (const [key, reservation] of recordingSessionTombstones) {
             restoredRecordingState.active.delete(key);
-        for (const [key, reservation] of activeRecordingReservations)
+            if (artifactManifest)
+                artifactManifest = retirePendingRecordingManifestEntries(artifactManifest, reservation.sessionName, reservation.namespace);
+        }
+        for (const [key, reservation] of activeRecordingReservations) {
+            const restored = restoredRecordingState.active.get(key);
+            if (restored?.absolutePath !== reservation.absolutePath || restored.cwd !== reservation.cwd)
+                recordingReservationsDirty = true;
             restoredRecordingState.active.set(key, reservation);
+        }
         activeRecordingReservations = restoredRecordingState.active;
         attachedSessionKeys = restoreAttachedSessionKeysFromBranch(branch);
         networkRoutesBySession = new Map();
@@ -1214,7 +1258,11 @@ export default function agentBrowserExtension(pi) {
             cwd: ctx.cwd,
             includeProjectConfig: shouldIncludeProjectConfig(ctx),
         }));
-        await artifactExecutionQueue.run(() => managedSessionExecutionQueue.run(() => recoverScriptSessionLeasesWithinQueue(ctx)));
+        await artifactExecutionQueue.run(() => managedSessionExecutionQueue.run(async () => {
+            await recoverScriptSessionLeasesWithinQueue(ctx);
+            flushRecordingReservations();
+            notifyRecordingPersistence(ctx);
+        }));
     });
     pi.on("session_tree", async (_event, ctx) => {
         for (const controller of activeScriptControllers)
@@ -1223,6 +1271,8 @@ export default function agentBrowserExtension(pi) {
         await artifactExecutionQueue.run(() => managedSessionExecutionQueue.run(async () => {
             restoreBranchBackedState(ctx, { resetRuntimeOwnership: false });
             await recoverScriptSessionLeasesWithinQueue(ctx);
+            flushRecordingReservations();
+            notifyRecordingPersistence(ctx);
         }));
     });
     pi.on("session_shutdown", async (event, ctx) => {
@@ -1263,30 +1313,21 @@ export default function agentBrowserExtension(pi) {
             else {
                 await closeOwnedManagedSessionsExcept(ownedManagedSessions, managedSessionRestoreState, managedSessionActive ? managedSessionName : undefined, implicitSessionCloseTimeoutMs, attachedSessionKeys, managedSessionActive ? managedSessionNamespace : undefined, (owner) => retireRecordingSession(owner.sessionName, owner.namespace));
             }
+            flushRecordingReservations();
+            notifyRecordingPersistence(ctx);
         }));
         managedSessionActive = false;
         managedSessionCompatibilityWorkaround = undefined;
         managedSessionHeadedAutosaveDisabled = false;
         managedSessionHeadedAutosaveInterval = undefined;
         managedSessionNamespace = undefined;
-        for (const reservation of recordingSessionTombstonesToPersist.values()) {
-            try {
-                appendRecordingReservationTransition(pi, { reservation, state: "closed" });
-            }
-            catch { }
-        }
-        for (const reservation of activeRecordingReservations.values()) {
-            try {
-                appendRecordingReservationTransition(pi, { reservation, state: "active" });
-            }
-            catch { }
-        }
         sessionPageState.reset();
         traceOwners = new Map();
         artifactManifest = undefined;
-        activeRecordingReservations = new Map();
-        recordingSessionTombstones = new Map();
-        recordingSessionTombstonesToPersist = new Map();
+        if (!recordingReservationsDirty) {
+            activeRecordingReservations = new Map();
+            recordingSessionTombstones = new Map();
+        }
         attachedSessionKeys = new Set();
         networkRoutesBySession = new Map();
         electronLaunchRecords = new Map();
@@ -1365,8 +1406,9 @@ export default function agentBrowserExtension(pi) {
             }
             const applyUnserializedOutputPath = async (result, preserveTextContent = false) => {
                 if (!outputPath || result.isError === true || (isRecord(result.details) && result.details.resultCategory === "failure"))
-                    return result;
+                    return warnRecordingPersistence(result);
                 return artifactExecutionQueue.run(async () => {
+                    flushRecordingReservations();
                     const reservationError = getArtifactPreflightValidationError({
                         activeRecordingReservations: activeRecordingReservations.values(),
                         args: [],
@@ -1374,9 +1416,9 @@ export default function agentBrowserExtension(pi) {
                         outputPath,
                     });
                     if (reservationError) {
-                        return buildValidationFailureResult({ attemptedKind: resolvedInput.kind, kind: "invalid", redactedArgs: resolvedInput.redactedArgs, status: "invalid", toolArgs: resolvedInput.toolArgs, toolStdin: resolvedInput.toolStdin, validationError: reservationError });
+                        return warnRecordingPersistence(buildValidationFailureResult({ attemptedKind: resolvedInput.kind, kind: "invalid", redactedArgs: resolvedInput.redactedArgs, status: "invalid", toolArgs: resolvedInput.toolArgs, toolStdin: resolvedInput.toolStdin, validationError: reservationError }));
                     }
-                    return applyAgentBrowserOutputPath({ cwd: ctx.cwd, outputPath, preserveTextContent, result });
+                    return applyAgentBrowserOutputPath({ cwd: ctx.cwd, outputPath, preserveTextContent, result: warnRecordingPersistence(result) });
                 });
             };
             const versionCheckCommand = extractUpstreamCommandTokens(resolvedInput.toolArgs)[0];
@@ -1459,7 +1501,10 @@ export default function agentBrowserExtension(pi) {
                     signal?.removeEventListener("abort", abortScript);
                     if (leased) {
                         try {
-                            cleanupError = await artifactExecutionQueue.run(() => managedSessionExecutionQueue.run(() => closeScriptSessionLeaseWithinQueue(sessionName, ctx.cwd)));
+                            cleanupError = await artifactExecutionQueue.run(() => managedSessionExecutionQueue.run(() => {
+                                flushRecordingReservations();
+                                return closeScriptSessionLeaseWithinQueue(sessionName, ctx.cwd);
+                            }));
                         }
                         catch {
                             cleanupError = "The isolated script session cleanup operation failed.";
@@ -1563,6 +1608,7 @@ export default function agentBrowserExtension(pi) {
                 : runElectronHostInput();
             const electronHostResult = compiledElectron?.action === "cleanup"
                 ? await artifactExecutionQueue.run(async () => {
+                    flushRecordingReservations();
                     const reservationError = outputPath ? getArtifactPreflightValidationError({
                         activeRecordingReservations: activeRecordingReservations.values(),
                         args: [],
@@ -1570,31 +1616,31 @@ export default function agentBrowserExtension(pi) {
                         outputPath,
                     }) : undefined;
                     if (reservationError) {
-                        return buildValidationFailureResult({ attemptedKind: resolvedInput.kind, kind: "invalid", redactedArgs: resolvedInput.redactedArgs, status: "invalid", toolArgs: resolvedInput.toolArgs, toolStdin: resolvedInput.toolStdin, validationError: reservationError });
+                        return warnRecordingPersistence(buildValidationFailureResult({ attemptedKind: resolvedInput.kind, kind: "invalid", redactedArgs: resolvedInput.redactedArgs, status: "invalid", toolArgs: resolvedInput.toolArgs, toolStdin: resolvedInput.toolStdin, validationError: reservationError }));
                     }
                     const result = await runSerializedElectronHostInput();
-                    return result ? applyAgentBrowserOutputPath({ cwd: ctx.cwd, outputPath, result }) : result;
+                    return result ? applyAgentBrowserOutputPath({ cwd: ctx.cwd, outputPath, result: warnRecordingPersistence(result) }) : result;
                 })
                 : await runSerializedElectronHostInput();
             if (electronHostResult) {
                 return compiledElectron?.action === "cleanup" ? electronHostResult : applyUnserializedOutputPath(electronHostResult);
             }
             const explicitSessionName = extractExplicitSessionName(toolArgs);
-            const explicitNamespace = extractExplicitNamespace(toolArgs);
+            const callerOwnedSessionNamespace = explicitSessionName
+                ? resolveAgentBrowserNamespace(toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE)
+                : undefined;
             const serializeBrowserCommand = shouldSerializeBrowserCommand({
-                explicitNamespace,
+                namespace: callerOwnedSessionNamespace,
                 explicitSessionName,
                 managedSessionName,
                 ownedElectronLaunchRecords,
                 ownedManagedSessions,
             });
-            const callerOwnedSessionNamespace = explicitSessionName
-                ? resolveAgentBrowserNamespace(toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE)
-                : undefined;
             const callerOwnedSessionQueueKey = !serializeBrowserCommand && explicitSessionName
                 ? getSessionContextKey(explicitSessionName, callerOwnedSessionNamespace) ?? explicitSessionName
                 : undefined;
             const runBrowserCommand = async () => {
+                flushRecordingReservations();
                 const branchRestoreGenerationAtStart = branchRestoreGeneration;
                 const generationAtStart = branchStateGeneration;
                 const sessionPageStateUpdate = sessionPageState.beginUpdate();
@@ -1620,6 +1666,14 @@ export default function agentBrowserExtension(pi) {
                     sessionPageState,
                     traceOwners,
                 };
+                const selectedPlan = buildExecutionPlan(toolArgs, {
+                    freshSessionName: createFreshSessionName(browserRunState.managedSessionBaseName, browserRunState.ephemeralSessionSeed, browserRunState.freshSessionOrdinal + 1),
+                    managedSessionActive: browserRunState.managedSessionActive,
+                    managedSessionCompatibilityWorkaround: browserRunState.managedSessionCompatibilityWorkaround,
+                    managedSessionName: browserRunState.managedSessionName,
+                    managedSessionNamespace: browserRunState.managedSessionNamespace,
+                    sessionMode: compiledElectron?.action === "launch" ? "fresh" : params.sessionMode ?? "auto",
+                });
                 const initialArtifactManifest = browserRunState.artifactManifest;
                 const initialNetworkRoutesBySession = browserRunState.networkRoutesBySession;
                 const attachedSessionRequested = isAttachedBrowserInvocation(toolArgs)
@@ -1628,7 +1682,8 @@ export default function agentBrowserExtension(pi) {
                     && (params.sessionMode === "fresh" || (resolvedInput.kind === "electron" && resolvedInput.compiledElectron.action === "launch"));
                 const reusableSessionKey = allocatesFreshManagedSession
                     ? undefined
-                    : callerOwnedSessionQueueKey ?? getSessionContextKey(browserRunState.managedSessionName, browserRunState.managedSessionNamespace);
+                    : getSessionContextKey(selectedPlan.sessionName, selectedPlan.namespace)
+                        ?? getSessionContextKey(browserRunState.managedSessionName, browserRunState.managedSessionNamespace);
                 const attachedSessionKnown = reusableSessionKey !== undefined && attachedSessionKeys.has(reusableSessionKey);
                 let result = await runAgentBrowserTool({
                     ctx,
@@ -1654,7 +1709,7 @@ export default function agentBrowserExtension(pi) {
                     : extractExplicitSessionName(toolArgs);
                 const resultNamespace = typeof resultDetails?.namespace === "string"
                     ? resultDetails.namespace
-                    : resolveAgentBrowserNamespace(toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE);
+                    : selectedPlan.namespace;
                 if (branchRestoreStillCurrent) {
                     const resultBatchCloseLifecycle = getSuccessfulBatchCloseLifecycle(resultDetails?.batchSteps);
                     const resultSessionKey = getSessionContextKey(resultSessionName, resultNamespace) ?? resultSessionName;
@@ -1732,21 +1787,28 @@ export default function agentBrowserExtension(pi) {
                     mergeActiveElectronLaunchRecords(ownedElectronLaunchRecords, electronLaunchRecords, {
                         branchOwnedLaunchIds: branchOwnedElectronLaunchIds,
                         touchedLaunchIds: !result.isError
-                            ? getTouchedElectronLaunchIds(explicitSessionName ?? browserRunState.managedSessionName, electronLaunchRecords, explicitSessionName ? resolveAgentBrowserNamespace(toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE) : browserRunState.managedSessionNamespace)
+                            ? getTouchedElectronLaunchIds(explicitSessionName ?? browserRunState.managedSessionName, electronLaunchRecords, resultNamespace)
                             : undefined,
                     });
                     if (serializeBrowserCommand)
                         branchStateGeneration += 1;
                 }
-                return applyAgentBrowserOutputPath({ cwd: ctx.cwd, outputPath, preserveTextContent: Array.isArray(params.args) && params.args.includes("--json"), result });
+                return applyAgentBrowserOutputPath({ cwd: ctx.cwd, outputPath, preserveTextContent: Array.isArray(params.args) && params.args.includes("--json"), result: warnRecordingPersistence(result) });
             };
             const closesAllSessions = commandClosesAllSessions(toolArgs, resolvedInput.toolStdin);
-            const closeAllNamespace = closesAllSessions
-                ? resolveAgentBrowserNamespace(toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE)
-                : undefined;
             const runWithinSessionQueue = () => {
                 if (closesAllSessions)
-                    return managedSessionExecutionQueue.run(() => callerOwnedSessionExecutionQueues.runExclusive(closeAllNamespace, runBrowserCommand));
+                    return managedSessionExecutionQueue.run(() => {
+                        const plan = buildExecutionPlan(toolArgs, {
+                            freshSessionName: createFreshSessionName(managedSessionBaseName, ephemeralSessionSeed, freshSessionOrdinal + 1),
+                            managedSessionActive,
+                            managedSessionCompatibilityWorkaround,
+                            managedSessionName,
+                            managedSessionNamespace,
+                            sessionMode: params.sessionMode ?? "auto",
+                        });
+                        return callerOwnedSessionExecutionQueues.runExclusive(plan.namespace, runBrowserCommand);
+                    });
                 if (serializeBrowserCommand)
                     return managedSessionExecutionQueue.run(runBrowserCommand);
                 return callerOwnedSessionQueueKey
@@ -1765,10 +1827,11 @@ export default function agentBrowserExtension(pi) {
                 });
                 if (!artifactValidationError)
                     return runWithinSessionQueue();
+                flushRecordingReservations();
                 return applyAgentBrowserOutputPath({
                     cwd: ctx.cwd,
                     outputPath,
-                    result: buildValidationFailureResult({
+                    result: warnRecordingPersistence(buildValidationFailureResult({
                         attemptedKind: resolvedInput.kind,
                         kind: "invalid",
                         redactedArgs: resolvedInput.redactedArgs,
@@ -1776,7 +1839,7 @@ export default function agentBrowserExtension(pi) {
                         toolArgs: resolvedInput.toolArgs,
                         toolStdin: resolvedInput.toolStdin,
                         validationError: artifactValidationError,
-                    }),
+                    })),
                 });
             });
         },