pi-agent-browser-native 0.6.8 → 0.6.10

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.6.10 - 2026-09-08
+
+### Fixed
+
+- Follow native artifact operands and raw-batch precedence consistently in preflight, recording reservations, result metadata and timeout recovery. Preserve literal batch operands and replay retries as a single native row (#168).
+- Handle recording `--fps` options without losing the requested path or intended pinned page. Keep conservative start/ref protection for older supported natives without claiming a page replacement; FPS-only restarts keep refs (#169).
+- Show positive native WebMCP availability in navigation summaries and distinguish current recording dependency checks from older deferred failures (#169).
+
+### Changed
+
+- Recommend `agent-browser` 0.37.0 while keeping the stable 0.35.0 minimum, no upper cap and native-owned recording/tab setup.
+
+### Known limitations
+
+- Native 0.37 short/cold recordings on Ubuntu can still fail or produce a shorter clip. This release does not change the upstream recording engine.
+
+## 0.6.9 - 2026-09-08
+
+### Fixed
+
+- Include redacted stdout/stderr tails in failed Electron startup diagnostics and visible errors (#128). Capture uses private regular files inside the isolated profile, with the last 4096 bytes read per stream; this is not a lifetime disk limit. Preserve the profile and logs when failed-startup process cleanup cannot finish, without changing normal quit cleanup.
+
+- Restore ordinary browser access to a tracked Electron app after Pi reload or resume by checking its live debug endpoint and the named upstream connection. Keep the app, profile, and session intact; unrelated or replaced connections still fail verification.
+
+### Validation
+
+- Verified startup output, reload continuity and quit cleanup with genuine Electron through the official Pi SDK on native macOS and Ubuntu. Native Windows was waived and not run; permanent release gates are unchanged.
+
 ## 0.6.8 - 2026-09-07
 
 ### Fixed

package/README.md

@@ -82,13 +82,13 @@ The result is optimized for agent work:
 | 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` |
-| Upstream CLI drift can silently invalidate wrapper behavior | Publishes a repo-readable command reference, verifies it against the recommended 0.36.0 target, and probes browser-backed calls once per cwd/PATH so stable versions below the 0.35.0 floor fail before browser launch with installed/expected version evidence | `npm run verify` |
-| Pages can expose structured workflows through experimental WebMCP | Passes through `webmcp list`, `invoke`, detached `result` / `cancel`, params/frame/timeout options, and the bundled `webmcp-gen` skill; treats `--no-webmcp` as launch-scoped, keeps pending or unsuccessfully settled targets unverified with an actionable `get url` follow-up, invalidates stale refs after page tools run, and budgets effective raw or stdin batch timeouts | [`docs/COMMAND_REFERENCE.md`](docs/COMMAND_REFERENCE.md#webmcp-page-tools), `test/agent-browser.extension-ref-guards.test.ts`, `test/agent-browser.wait-timeouts.test.ts`, `test/agent-browser.real-upstream-contract.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 older natives report pending output without `ffmpeg`, and conservatively invalidates prior page-scoped `@e…` refs on every executed start attempt and URL-bearing restart to protect older supported natives. This is not evidence of a page change: 0.37 records the active page unless a URL is supplied; FPS-only calls keep the intended tab; 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` |
+| Upstream CLI drift can silently invalidate wrapper behavior | Publishes a repo-readable command reference, verifies it against the recommended 0.37.0 target, and probes browser-backed calls once per cwd/PATH so stable versions below the 0.35.0 floor fail before browser launch with installed/expected version evidence | `npm run verify` |
+| Pages can expose structured workflows through experimental WebMCP | Shows native positive WebMCP availability in navigation summaries and passes through `webmcp list`, `invoke`, detached `result` / `cancel`, params/frame/timeout options, and the bundled `webmcp-gen` skill; treats `--no-webmcp` as launch-scoped, keeps pending or unsuccessfully settled targets unverified with an actionable `get url` follow-up, invalidates stale refs after page tools run, and budgets effective raw or stdin batch timeouts | [`docs/COMMAND_REFERENCE.md`](docs/COMMAND_REFERENCE.md#webmcp-page-tools), `test/agent-browser.extension-ref-guards.test.ts`, `test/agent-browser.wait-timeouts.test.ts`, `test/agent-browser.real-upstream-contract.test.ts` |
 | 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.
+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. It describes conservative ref invalidation, not an observed page change; unreached rows do not emit it.
 
 ## Fastest way to try it
 
@@ -104,13 +104,13 @@ Optional external tools unlock the full command surface:
 | Dependency | Required for | macOS install example |
 | --- | --- | --- |
 | `agent-browser` | All browser automation through this extension | See upstream install docs |
-| `ffmpeg` | `record stop` WebM encoding after `record start` / `record restart` | `brew install ffmpeg` or `brew install ffmpeg-full` |
+| `ffmpeg` | Recording WebM (libvpx) or MP4 (libx264); install before `record start` / `record restart` | `brew install ffmpeg` or `brew install ffmpeg-full` |
 
-Keep both binaries on `PATH`. This package recommends `agent-browser 0.36.0` and accepts stable versions at or above the 0.35.0 floor; browser-backed calls fail fast below that floor while local inspection/setup commands remain available for diagnosis. `record start` can begin without a file on disk, but `record stop` needs `ffmpeg` to encode the WebM.
+Keep both binaries on `PATH`. This package recommends `agent-browser 0.37.0` and accepts stable versions at or above the 0.35.0 floor; browser-backed calls fail fast below that floor while local inspection/setup commands remain available for diagnosis. Native 0.37 validates `ffmpeg`, the output extension and FPS before recording; older supported natives may defer failures until stop. Use `record start <path.webm|path.mp4> [url] [--fps <n>]` (1–60 fps, default 30), then verify the completed file after `record stop`. Native `doctor` checks the recording dependency and encoders.
 
 ### Android / Termux
 
-Android support currently uses Termux's system Chromium rather than Chrome for Testing. Upstream issue [vercel-labs/agent-browser#1587](https://github.com/vercel-labs/agent-browser/issues/1587) tracks native Android packaging; until upstream ships an Android launcher, install the packaged Linux-musl arm64 binary without lifecycle scripts and point the global command at it:
+Android support currently uses Termux's system Chromium rather than Chrome for Testing. Upstream issue [vercel-labs/agent-browser#1587](https://github.com/vercel-labs/agent-browser/issues/1587) tracks native Android packaging; until upstream ships an Android launcher, install the packaged Linux-musl arm64 binary without lifecycle scripts and point the global command at it. The last locally validated Android setup used 0.36.0:
 
 ```bash
 pkg install tur-repo x11-repo
@@ -135,6 +135,8 @@ Then install this Pi package:
 pi install npm:pi-agent-browser-native
 ```
 
+After updating `pi-agent-browser-native`, fully quit and restart Pi before using the updated tools. `/reload` can retain previously loaded compiled JavaScript even after `dist/` is rebuilt, so it is not a reliable way to pick up package updates.
+
 Start Pi and ask for a browser action:
 
 ```text
@@ -184,7 +186,7 @@ npm run doctor
 The doctor checks:
 
 - upstream `agent-browser` exists on `PATH`
-- the installed upstream is a stable version at or above the supported 0.35.0 floor; 0.36.0 remains the recommended baseline
+- the installed upstream is a stable version at or above the supported 0.35.0 floor; 0.37.0 remains the recommended baseline
 - `pi --version` meets the minimum Pi runtime floor for this release; older Pi versions are setup failures
 - Pi settings do not point at multiple active `pi-agent-browser-native` sources
 
@@ -385,7 +387,7 @@ Evaluate page JavaScript through stdin. Put the script in the top-level `stdin`
 
 Use `outputPath` when `eval`, `get`, `snapshot`, or another extraction should be saved as a durable workspace file. Keep it distinct from screenshot, download, recording, and other browser artifact destinations; preflight rejects known same-call aliases before browser activity, and the result writer preserves the browser artifact if an alias becomes apparent only afterward. The wrapper writes `details.data` when present, otherwise the model-facing text content. When presentation compacted a large direct result, a result row, or the whole `batch`, it instead reads the full command-redacted pre-compaction payload only from the corresponding live wrapper-managed spill recorded in `details.artifactManifest`; if any required spill is unavailable or untrusted, the call fails without writing compact metadata to the requested path. `details.outputFile` reports the saved path and byte count. Explicit upstream `--json` content stays parseable; in that case the save notice lives only in `details.outputFile`.
 
-Extract several known refs or selectors in one `batch` call instead of many serial getter calls:
+Extract several known refs or selectors in one `batch` call instead of many serial getter calls. When a prior snapshot and session are available and the same-page freshness checks apply, ref-consuming calls add one extra `snapshot -i` preflight per top-level call or batch. Batching shares that probe across rows; it does not remove it:
 
 ```json
 { "args": ["batch"], "stdin": "[[\"get\",\"text\",\"@e64\"],[\"get\",\"text\",\"@e65\"]]" }
@@ -455,7 +457,7 @@ Typical pitfalls:
 
 ### Constrained browser jobs
 
-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.
+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)). Timeout recovery follows the effective batch source and native artifact operand positions, including literal dash-leading paths. Executable retries preserve the original row in a one-row batch. 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.
 
@@ -505,7 +507,7 @@ For desktop Electron apps, use top-level `electron` to avoid hand-building the d
 { "electron": { "action": "cleanup", "launchId": "electron-…" } }
 ```
 
-`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.
+`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` applies to managed-session title/URL reads and any `get cdp-url` read needed to verify a restored connection. 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. First reuse after reload/resume checks the live app's saved debug endpoint and the exact named upstream connection without reconnecting or resetting page refs; if cleanup is partial and skips or fails profile removal, the generic temp sweep preserves that `userDataDir` across reload, quit, later temp cleanup, process exit, and stale temp-root pruning after restart. 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`. Failed startups expose redacted stdout/stderr tails in visible errors and `details.electron.failure.diagnostics`, alongside PID, profile, DevToolsActivePort, and timing evidence. Each tail reads at most 4096 source bytes; private capture files follow the profile lifecycle, not a lifetime disk cap. See [`docs/ELECTRON.md`](docs/ELECTRON.md#failure-categories-and-recovery).
 
 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.
 
@@ -711,7 +713,7 @@ The opt-in real-upstream suite is separate because it drives a real browser inst
 npm run verify -- real-upstream
 ```
 
-That mode sets `PI_AGENT_BROWSER_REAL_UPSTREAM=1` and runs `test/agent-browser.real-upstream-contract.test.ts` against the real `agent-browser` on `PATH` (the stable version must meet the 0.35.0 floor; current command-reference validation targets the recommended 0.36.0 capability baseline). It covers inspection, skills, experimental WebMCP list/invoke/result/cancel plus `--no-webmcp`, and a broad core interaction and navigation matrix on localhost fixtures (including off-viewport click, frame-scoped selector/wait/click behavior, form command fixes, `batch` stdin, and `pushstate`), plus `vitals`, network route/requests/HAR, diff snapshot/screenshot/url, trace/profiler, console/errors/highlight, stream enable/status/disable, `cookies set --curl`, a `react tree` missing-renderer path, and `wait --download` with the on-disk caveat documented in release notes. The harness uses a throwaway temp `HOME` and dedicated socket/screenshot directories so the run does not touch your normal browser profile paths. Browser-opening or credential-dependent families such as `inspect`, `dashboard`, `chat`, provider clouds, and OS clipboard flows stay in fake-upstream or manual validation unless a safe deterministic fixture is added. For prerequisites, isolation details, and troubleshooting, see [`docs/RELEASE.md`](docs/RELEASE.md#real-upstream-contract-validation).
+That mode sets `PI_AGENT_BROWSER_REAL_UPSTREAM=1` and runs `test/agent-browser.real-upstream-contract.test.ts` against the real `agent-browser` on `PATH` (the stable version must meet the 0.35.0 floor; current command-reference validation targets the recommended 0.37.0 capability baseline). It covers inspection, skills, experimental WebMCP list/invoke/result/cancel plus `--no-webmcp`, and a broad core interaction and navigation matrix on localhost fixtures (including off-viewport click, frame-scoped selector/wait/click behavior, form command fixes, `batch` stdin, and `pushstate`), plus `vitals`, network route/requests/HAR, diff snapshot/screenshot/url, trace/profiler, console/errors/highlight, stream enable/status/disable, `cookies set --curl`, a `react tree` missing-renderer path, and `wait --download` with the on-disk caveat documented in release notes. The harness uses a throwaway temp `HOME` and dedicated socket/screenshot directories so the run does not touch your normal browser profile paths. Browser-opening or credential-dependent families such as `inspect`, `dashboard`, `chat`, provider clouds, and OS clipboard flows stay in fake-upstream or manual validation unless a safe deterministic fixture is added. For prerequisites, isolation details, and troubleshooting, see [`docs/RELEASE.md`](docs/RELEASE.md#real-upstream-contract-validation).
 
 A deterministic host-only live-browser wrapper smoke is available without an LLM choosing tool calls:
 
@@ -744,12 +746,12 @@ npm run verify -- release
 5. Screenshots, downloads, recordings, traces, profiles, and spill files are normalized as Pi-visible artifacts where possible.
 6. Generated playbook text in docs and tool metadata stays aligned with `extensions/agent-browser/lib/playbook.ts`.
 
-The upstream browser engine remains [`agent-browser`](https://agent-browser.dev/). This package does not bundle it. The recommended baseline is 0.36.0 and the stable runtime floor is 0.35.0; newer stable versions are accepted without version-specific compatibility shims.
+The upstream browser engine remains [`agent-browser`](https://agent-browser.dev/). This package does not bundle it. The recommended baseline is 0.37.0 and the stable runtime floor is 0.35.0; newer stable versions are accepted without version-specific compatibility shims.
 
 ## Current limits
 
 - Published pre-1.0 package.
-- Recommends upstream `agent-browser` 0.36.0 and accepts stable runtimes at or above 0.35.0.
+- Recommends upstream `agent-browser` 0.37.0 and accepts stable runtimes at or above 0.35.0.
 - Does not bundle `agent-browser`; users install it separately.
 - Does not provide a human browser UI inside Pi; the primary UX is agent-invoked tool calls. `--headed` asks upstream to show a browser window, but the wrapper cannot yet prove that the window is visible on the user's desktop.
 - Localhost means the browser host's loopback, not necessarily the shell/Pi host. If `http://localhost:<port>` or `http://127.0.0.1:<port>` fails with errors such as `ERR_EMPTY_RESPONSE`, use an environment-specific host-reachable HTTP(S) address. A `file://` fixture is supported when upstream browser launch settings allow it; use HTTP(S) only when the browser environment cannot reach the local file.

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

@@ -6,7 +6,7 @@ import { batchHasSuccessfulCloseAll, getSuccessfulBatchCloseLifecycle } from "./
 import { PROJECT_RULE_PROMPT, buildBrowserDefaultProfileGuideline, buildBrowserExecutablePathGuideline, buildToolPromptGuidelines, } from "./lib/playbook.js";
 import { SessionPageState } from "./lib/session-page-state.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 { deleteIdentityKeysInNamespace, 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";
 import { ManagedSessionRestoreState } from "./lib/managed-session-restore.js";
@@ -67,7 +67,7 @@ function getArtifactPreflightValidationError(options) {
         return error;
     const activeRecordingDestinations = new Set();
     const cleanupOnly = steps.length > 0 && steps.every((step) => {
-        const [command, subcommand] = extractUpstreamCommandTokens(step);
+        const [command, subcommand] = step;
         return isCloseCommand(command) || (command === "record" && subcommand === "stop");
     });
     for (const reservation of options.activeRecordingReservations ?? []) {
@@ -93,10 +93,9 @@ function getArtifactPreflightValidationError(options) {
     }
     const artifactDestinations = new Map();
     let sawBatchClose = false;
-    for (const [index, step] of steps.entries()) {
-        const commandStep = extractUpstreamCommandTokens(step);
+    for (const [index, commandStep] of steps.entries()) {
         if (batch) {
-            const stepValidationError = validateToolArgs(step, { batchStep: true });
+            const stepValidationError = validateToolArgs(commandStep, { batchStep: true });
             if (stepValidationError)
                 return `Unsupported batch step ${index + 1}: ${stepValidationError}`;
             if (sawBatchClose && commandStep[0] === "record" && (commandStep[1] === "start" || commandStep[1] === "restart")) {
@@ -127,7 +126,7 @@ function getArtifactPreflightValidationError(options) {
             }
             artifactDestinations.set(canonicalDestination, index);
         }
-        if (batch && commandStep[0] === "screenshot" && step.includes("--annotate")) {
+        if (batch && commandStep[0] === "screenshot" && commandStep.includes("--annotate")) {
             return [
                 `Unsupported batch screenshot annotation in step ${index + 1}: put --annotate in top-level args, not inside the batch step.`,
                 `Use: { "args": ["--annotate", "batch"], "stdin": "[[\\"screenshot\\",\\"/path/to/image.png\\"]]" }`,
@@ -138,7 +137,7 @@ function getArtifactPreflightValidationError(options) {
 }
 function commandClosesAllSessions(args, stdin) {
     const parsed = getArtifactCommandSteps(args, stdin);
-    return !parsed.error && parsed.steps.some((step) => isCloseAllCommand(extractUpstreamCommandTokens(step)));
+    return !parsed.error && parsed.steps.some(isCloseAllCommand);
 }
 function commandTouchesArtifactLifecycle(args, stdin, outputPath) {
     if (outputPath)
@@ -146,10 +145,7 @@ function commandTouchesArtifactLifecycle(args, stdin, outputPath) {
     const parsed = getArtifactCommandSteps(args, stdin);
     if (parsed.error)
         return true;
-    return parsed.steps.some((step) => {
-        const commandStep = extractUpstreamCommandTokens(step);
-        return getExplicitArtifactDestination(commandStep) !== undefined || commandStep[0] === "record" || commandStep[0] === "screenshot" || isCloseCommand(commandStep[0]);
-    });
+    return parsed.steps.some((step) => getExplicitArtifactDestination(step) !== undefined || step[0] === "record" || step[0] === "screenshot" || isCloseCommand(step[0]));
 }
 function isResultFileArtifact(artifact) {
     return isRecord(artifact)
@@ -299,12 +295,6 @@ function detailsReportCloseAllApplied(details, succeeded) {
         || (succeeded && isCloseAllCommand(extractUpstreamCommandTokens(args)))
         || batchHasSuccessfulCloseAll(details.batchSteps);
 }
-function deleteIdentityKeysInNamespace(entries, namespace) {
-    for (const key of entries.keys()) {
-        if (isAgentBrowserSessionIdentityKeyInNamespace(key, namespace))
-            entries.delete(key);
-    }
-}
 function isAttachedBrowserInvocation(args, env = getAgentBrowserProcessEnvironment()) {
     const autoConnectEnv = env.AGENT_BROWSER_AUTO_CONNECT;
     return extractUpstreamCommandTokens(args)[0] === "connect"
@@ -663,9 +653,6 @@ async function closeOwnedManagedSessionsExcept(sessions, restoreState, keepSessi
         }
     }
 }
-async function closeOwnedManagedSessions(sessions, restoreState, timeoutMs, attachedSessionKeys, onClosed) {
-    await closeOwnedManagedSessionsExcept(sessions, restoreState, undefined, timeoutMs, attachedSessionKeys, undefined, onClosed);
-}
 function getOffBranchOwnedElectronLaunchRecords(ownedRecords, branchRecords) {
     const activeBranchLaunchIds = new Set(getActiveElectronRecords(branchRecords).map((record) => record.launchId));
     const offBranchRecords = new Map();
@@ -1308,7 +1295,7 @@ export default function agentBrowserExtension(pi) {
             for (const identity of getCleanupResultsClosedManagedSessionIdentities(electronCleanupResults))
                 retireRecordingSession(identity.sessionName, identity.namespace);
             if (quitting) {
-                await closeOwnedManagedSessions(ownedManagedSessions, managedSessionRestoreState, implicitSessionCloseTimeoutMs, attachedSessionKeys, (owner) => retireRecordingSession(owner.sessionName, owner.namespace));
+                await closeOwnedManagedSessionsExcept(ownedManagedSessions, managedSessionRestoreState, undefined, implicitSessionCloseTimeoutMs, attachedSessionKeys, undefined, (owner) => retireRecordingSession(owner.sessionName, owner.namespace));
             }
             else {
                 await closeOwnedManagedSessionsExcept(ownedManagedSessions, managedSessionRestoreState, managedSessionActive ? managedSessionName : undefined, implicitSessionCloseTimeoutMs, attachedSessionKeys, managedSessionActive ? managedSessionNamespace : undefined, (owner) => retireRecordingSession(owner.sessionName, owner.namespace));

package/dist/extensions/agent-browser/lib/argv-descriptor.js

@@ -48,14 +48,13 @@ export function parseWaitCommandTokens(commandTokens) {
         if (match)
             return { subcommand: match.token };
     }
-    const download = considered.find((entry) => entry.token === "--download" || entry.token === "-d");
-    if (download) {
-        const downloadPathIndex = download.index + 1;
-        const candidate = commandTokens[downloadPathIndex];
+    const downloadIndex = considered.findIndex((entry) => entry.token === "--download" || entry.token === "-d");
+    if (downloadIndex >= 0) {
+        const candidate = considered[downloadIndex + 1];
         return {
-            downloadPath: candidate && !candidate.startsWith("--") ? candidate : undefined,
-            downloadPathIndex: candidate && !candidate.startsWith("--") ? downloadPathIndex : undefined,
-            subcommand: download.token,
+            downloadPath: candidate && !candidate.token.startsWith("--") ? candidate.token : undefined,
+            downloadPathIndex: candidate && !candidate.token.startsWith("--") ? candidate.index : undefined,
+            subcommand: considered[downloadIndex].token,
         };
     }
     return { subcommand: considered[0]?.token };

package/dist/extensions/agent-browser/lib/argv-grammar.js

@@ -175,6 +175,12 @@ export function isAgentBrowserSessionIdentityKeyInNamespace(identityKey, namespa
     const prefix = getAgentBrowserSessionIdentityKey("", namespace);
     return prefix ? identityKey.startsWith(prefix) : !identityKey.includes("\0");
 }
+export function deleteIdentityKeysInNamespace(entries, namespace) {
+    for (const key of entries.keys()) {
+        if (isAgentBrowserSessionIdentityKeyInNamespace(key, namespace))
+            entries.delete(key);
+    }
+}
 /** Mirror upstream global parsing: full argv, no `--` sentinel, and only global value payloads are skipped. */
 export function scanUpstreamGlobalFlagOccurrences(args, targetFlag) {
     const occurrences = [];

package/dist/extensions/agent-browser/lib/batch-lifecycle.js

@@ -1,12 +1,6 @@
 import { extractUpstreamCommandTokens } from "./argv-descriptor.js";
 import { isCloseAllCommand, isCloseCommand } from "./command-taxonomy.js";
 import { isRecord } from "./parsing.js";
-function getRowBrowserLaunched(row) {
-    const result = isRecord(row.result) ? row.result : isRecord(row.data) ? row.data : undefined;
-    const lifecycle = isRecord(row.lifecycle) ? row.lifecycle : isRecord(result?.lifecycle) ? result.lifecycle : undefined;
-    const effectiveLaunch = isRecord(lifecycle?.effectiveLaunch) ? lifecycle.effectiveLaunch : undefined;
-    return typeof effectiveLaunch?.browserLaunched === "boolean" ? effectiveLaunch.browserLaunched : undefined;
-}
 export function batchHasSuccessfulCloseAll(data, fallbackCommands = []) {
     if (!Array.isArray(data))
         return false;
@@ -34,7 +28,10 @@ export function getSuccessfulBatchCloseLifecycle(rows, fallbackCommands = []) {
         const rowCommand = Array.isArray(row.command) && row.command.every((token) => typeof token === "string")
             ? row.command
             : fallbackCommands[index];
-        const browserLaunched = getRowBrowserLaunched(row);
+        const result = isRecord(row.result) ? row.result : isRecord(row.data) ? row.data : undefined;
+        const lifecycle = isRecord(row.lifecycle) ? row.lifecycle : isRecord(result?.lifecycle) ? result.lifecycle : undefined;
+        const effectiveLaunch = isRecord(lifecycle?.effectiveLaunch) ? lifecycle.effectiveLaunch : undefined;
+        const browserLaunched = typeof effectiveLaunch?.browserLaunched === "boolean" ? effectiveLaunch.browserLaunched : undefined;
         if (!rowCommand) {
             if (sawClose && browserLaunched !== false) {
                 endsClosed = false;
@@ -49,7 +46,6 @@ export function getSuccessfulBatchCloseLifecycle(rows, fallbackCommands = []) {
             endsClosed = true;
             browserActiveAfterClose = false;
             recordingClosedAfterBatch = true;
-            const result = isRecord(row.result) ? row.result : isRecord(row.data) ? row.data : undefined;
             statePath = typeof result?.statePath === "string" ? result.statePath : undefined;
         }
         else if (sawClose && command === "record") {

package/dist/extensions/agent-browser/lib/command-taxonomy.js

@@ -316,13 +316,26 @@ export function isSessionTabPinningExcludedCommand(command) {
 export function isSessionTabPostCommandCorrectionExcludedCommand(command) {
     return hasCommandCapability(command, "excludedFromPostCommandCorrection");
 }
-/** Upstream 0.33.2 record start swaps to a fresh active page before its already-active check, so even a failed start can replace the page; record restart navigates the current page only when a URL operand (any fourth token, mirroring upstream's positional slot) is present. */
+export function getRecordCommandOperands(tokens) {
+    if (tokens[0] !== "record" || !["start", "restart"].includes(tokens[1] ?? ""))
+        return {};
+    const operands = [];
+    for (let index = 2; index < tokens.length && operands.length < 2; index += 1) {
+        // Native validates the range; bare/non-numeric --fps keeps its old literal meaning.
+        if (tokens[index] === "--fps" && /^\+?\d+$/.test(tokens[index + 1] ?? ""))
+            index += 1;
+        else
+            operands.push(tokens[index]);
+    }
+    return operands.length > 0 ? { path: operands[0], url: operands[1] } : { path: tokens[2], url: tokens[3] };
+}
+/** Starts conservatively invalidate refs because older supported natives replace the page, even on failure. Restarts invalidate only when they have a URL. */
 export function isRecordPageTransitionCommand(tokens) {
     if (tokens[0] !== "record")
         return false;
     if (tokens[1] === "start")
         return true;
-    return tokens[1] === "restart" && tokens.length >= 4;
+    return tokens[1] === "restart" && getRecordCommandOperands(tokens).url !== undefined;
 }
 export function isWebMcpPageMutationCommand(tokens) {
     return isWebMcpPageMutation(tokens[0], tokens[1]);

package/dist/extensions/agent-browser/lib/electron/cleanup.js

@@ -24,15 +24,15 @@ function isPidAlive(pid) {
         return code === "EPERM" ? true : false;
     }
 }
-async function isPortAlive(port) {
-    const version = parseCdpVersion(await fetchCdpJson(`http://127.0.0.1:${port}/json/version`));
+async function isPortAlive(port, signal) {
+    const version = parseCdpVersion(await fetchCdpJson(`http://127.0.0.1:${port}/json/version`, signal));
     if (!version)
         return { targets: [] };
-    const targets = parseCdpTargets(await fetchCdpJson(`http://127.0.0.1:${port}/json/list`));
+    const targets = parseCdpTargets(await fetchCdpJson(`http://127.0.0.1:${port}/json/list`, signal));
     return { targets, version };
 }
-export async function inspectElectronLaunchStatus(record) {
-    const cdp = await isPortAlive(record.port);
+export async function inspectElectronLaunchStatus(record, signal) {
+    const cdp = await isPortAlive(record.port, signal);
     let userDataDirState;
     try {
         await lstat(record.userDataDir);

package/dist/extensions/agent-browser/lib/electron/launch.js

@@ -1,10 +1,10 @@
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { readFile, rm } from "node:fs/promises";
-import { dirname } from "node:path";
+import { open, readFile, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import { fetchCdpJson, parseCdpTargets, parseCdpVersion, } from "./cdp.js";
 import { discoverElectronApps, inspectElectronAppPath, inspectElectronExecutablePath, } from "./discovery.js";
-import { createSecureTempDirectory } from "../temp.js";
+import { createSecureTempDirectory, preserveSecureTempDirectory } from "../temp.js";
 export const ELECTRON_LAUNCH_RECORD_VERSION = 1;
 export const ELECTRON_LAUNCH_DEFAULT_TIMEOUT_MS = 15_000;
 export const ELECTRON_LAUNCH_MAX_TIMEOUT_MS = 120_000;
@@ -12,6 +12,8 @@ const DEVTOOLS_ACTIVE_PORT_FILE = "DevToolsActivePort";
 export const ELECTRON_PROFILE_DIR_PREFIX = "electron-profile-";
 const ELECTRON_DEFAULT_APP_ARGS = ["--disable-extensions", "--no-first-run", "--no-default-browser-check"];
 const ELECTRON_DEVTOOLS_POLL_INTERVAL_MS = 100;
+// ponytail: bound failure reads, not lifetime log growth; noisy long-lived apps need rotation if that becomes a problem.
+const ELECTRON_OUTPUT_TAIL_BYTES = 4096;
 function normalizeTimeoutMs(timeoutMs) {
     if (!Number.isSafeInteger(timeoutMs) || (timeoutMs ?? 0) <= 0)
         return ELECTRON_LAUNCH_DEFAULT_TIMEOUT_MS;
@@ -284,40 +286,90 @@ export async function launchElectronApp(options) {
     let exitCode = null;
     let exitSignal = null;
     const args = buildLaunchArgs(userDataDir, appArgs);
-    const child = spawn(target.executablePath, args, {
-        cwd: dirname(target.executablePath),
-        detached: process.platform !== "win32",
-        stdio: "ignore",
-    });
-    child.once("error", (error) => {
-        spawnError = error;
-    });
-    child.once("exit", (code, signal) => {
-        exitCode = code;
-        exitSignal = signal;
-    });
-    child.unref();
+    let child;
+    let outputCaptured = false;
+    const outputFiles = [];
+    try {
+        for (const stream of ["stdout", "stderr"])
+            outputFiles.push(await open(join(userDataDir, `${stream}.log`), "wx", 0o600));
+        options.signal?.throwIfAborted();
+        child = spawn(target.executablePath, args, {
+            cwd: dirname(target.executablePath),
+            detached: process.platform !== "win32",
+            stdio: ["ignore", outputFiles[0].fd, outputFiles[1].fd],
+        });
+        outputCaptured = true;
+        child.once("error", (error) => {
+            spawnError = error;
+        });
+        child.once("exit", (code, signal) => {
+            exitCode = code;
+            exitSignal = signal;
+        });
+        child.unref();
+    }
+    catch (error) {
+        spawnError = error instanceof Error ? error : new Error(String(error));
+    }
+    finally {
+        for (const file of outputFiles) {
+            await file.close().catch((error) => {
+                cleanupError = [cleanupError, `Output handle close failed: ${error instanceof Error ? error.message : String(error)}`].filter(Boolean).join("; ");
+            });
+        }
+    }
     const buildFailureDiagnostics = (options = {}) => ({
         cdpVersionReached: options.cdpVersionReached,
         devToolsActivePort: options.devToolsActivePort,
         elapsedMs: Math.max(0, Date.now() - startedAtMs),
         exitCode,
         exitSignal,
-        outputCaptured: false,
-        pid: child.pid,
-        pidAlive: isLaunchChildPidAlive(child),
+        outputCaptured,
+        pid: child?.pid,
+        pidAlive: child ? isLaunchChildPidAlive(child) : undefined,
         port: options.port ?? options.devToolsActivePort?.port,
         timeoutMs,
         userDataDir,
     });
     const fail = async (reason, detail, diagnosticOptions) => {
         const diagnostics = buildFailureDiagnostics(diagnosticOptions);
-        const processCleanupError = await terminateLaunchChild(child);
+        const processCleanupError = child ? await terminateLaunchChild(child) : undefined;
+        const outputLines = [];
+        if (outputCaptured) {
+            for (const stream of ["stdout", "stderr"]) {
+                let file;
+                try {
+                    file = await open(join(userDataDir, `${stream}.log`), "r");
+                    const { size } = await file.stat();
+                    const buffer = Buffer.alloc(Math.min(size, ELECTRON_OUTPUT_TAIL_BYTES));
+                    const { bytesRead } = await file.read(buffer, 0, buffer.length, Math.max(0, size - buffer.length));
+                    diagnostics[`${stream}Tail`] = buffer.subarray(0, bytesRead).toString("utf8");
+                    diagnostics[`${stream}Truncated`] = size > buffer.length;
+                }
+                catch (error) {
+                    diagnostics[`${stream}Error`] = error instanceof Error ? error.message : String(error);
+                }
+                finally {
+                    await file?.close().catch((error) => {
+                        diagnostics[`${stream}Error`] = [diagnostics[`${stream}Error`], `Output reader close failed: ${error instanceof Error ? error.message : String(error)}`].filter(Boolean).join("; ");
+                    });
+                }
+                const tail = diagnostics[`${stream}Tail`];
+                if (tail !== undefined)
+                    outputLines.push(`App ${stream}${diagnostics[`${stream}Truncated`] ? ` (last ${ELECTRON_OUTPUT_TAIL_BYTES} bytes)` : ""}: ${tail || "(empty)"}`);
+                if (diagnostics[`${stream}Error`])
+                    outputLines.push(`App ${stream} capture error: ${diagnostics[`${stream}Error`]}`);
+            }
+        }
         try {
-            await rm(userDataDir, { force: true, recursive: true });
+            if (processCleanupError)
+                await preserveSecureTempDirectory(userDataDir);
+            else
+                await rm(userDataDir, { force: true, recursive: true });
         }
         catch (error) {
-            cleanupError = error instanceof Error ? error.message : String(error);
+            const message = error instanceof Error ? error.message : String(error);
+            cleanupError = [cleanupError, processCleanupError ? `Profile preservation failed: ${message}` : message].filter(Boolean).join("; ");
         }
         cleanupError = [processCleanupError, cleanupError].filter((value) => value !== undefined).join("; ") || undefined;
         return {
@@ -326,13 +378,15 @@ export async function launchElectronApp(options) {
                 appArgs,
                 cleanupError,
                 diagnostics,
-                error: launchFailureMessage(reason, target, detail),
+                error: [launchFailureMessage(reason, target, detail), ...outputLines].join("\n"),
                 reason,
                 target,
                 userDataDir,
             },
         };
     };
+    if (!child)
+        return fail(options.signal?.aborted ? "aborted" : "spawn-error", spawnError?.message);
     const portResult = await pollDevToolsActivePort({
         deadlineMs,
         getChildExit: () => ({ code: exitCode, signal: exitSignal }),

package/dist/extensions/agent-browser/lib/managed-session-restore.js

@@ -104,7 +104,7 @@ export function agentBrowserExplicitConfigIsPresent(parentEnv = getAgentBrowserP
     return hasExplicitConfigArg(args) || hasUpstreamEnvValue(parentEnv, AGENT_BROWSER_CONFIG_ENV);
 }
 /** Caller-selected upstream config disables the wrapper's automatic restore injection without blocking that config. */
-export function agentBrowserConfigBlocksManagedRestore(_cwd, parentEnv = getAgentBrowserProcessEnvironment(), args = [], platform = process.platform) {
+export function agentBrowserConfigBlocksManagedRestore(parentEnv = getAgentBrowserProcessEnvironment(), args = [], platform = process.platform) {
     return !resolveManagedSessionRestoreHome(parentEnv, platform) || agentBrowserExplicitConfigIsPresent(parentEnv, args);
 }
 function omitWrapperInjectedUserAgent(args, enabled) {
@@ -151,7 +151,7 @@ function isManagedSessionRestoreIncompatible(options, namespace = extractExplici
     const args = omitWrapperInjectedUserAgent(options.args, options.wrapperInjectedUserAgent);
     if (options.cwd && !hasManagedSessionRestoreProjectIdentity(options.cwd))
         return true;
-    if (options.cwd && agentBrowserConfigBlocksManagedRestore(options.cwd, effectiveEnv, args))
+    if (options.cwd && agentBrowserConfigBlocksManagedRestore(effectiveEnv, args))
         return true;
     return !ensureManagedSessionRestoreStorageIsSecure(effectiveEnv, process.platform, namespace);
 }

package/dist/extensions/agent-browser/lib/managed-session-snapshots.js

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { chmodSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join } from "node:path";
-import { createManagedSessionRestoreKey, directoryContainsSymlink, ensureManagedSessionRestoreStorageIsSecure, hasManagedSessionRestoreProjectIdentity, ensureOwnerOnlyDirectory, getManagedRestoreSessionsDirectory, isManagedSessionRestoreKey, resolveManagedSessionRestoreCheckoutRoot, resolveManagedSessionRestoreHome, } from "./managed-session-storage.js";
+import { directoryContainsSymlink, ensureManagedSessionRestoreStorageIsSecure, ensureOwnerOnlyDirectory, getManagedRestoreSessionsDirectory, isManagedSessionRestoreKey, resolveManagedSessionRestoreCheckoutRoot, resolveManagedSessionRestoreHome, } from "./managed-session-storage.js";
 const OWNED_RESTORE_SNAPSHOT_FAMILIES_TO_KEEP = 2;
 const OWNED_RESTORE_SNAPSHOT_MAX_RECORDS = 256;
 const OWNED_RESTORE_SNAPSHOT_RECORD_MAX_BYTES = 16 * 1_024;
@@ -286,10 +286,8 @@ function scanOwnedSnapshots(options) {
 export function pruneOwnedManagedSessionRestoreSnapshots(options) {
     const parentEnv = options.parentEnv ?? process.env;
     const platform = options.platform ?? process.platform;
-    const restoreKey = options.restoreKey === undefined
-        ? hasManagedSessionRestoreProjectIdentity(options.cwd) ? createManagedSessionRestoreKey(options.cwd) : undefined
-        : isManagedSessionRestoreKey(options.restoreKey) ? options.restoreKey : undefined;
-    if (!restoreKey)
+    const restoreKey = options.restoreKey;
+    if (!isManagedSessionRestoreKey(restoreKey))
         return 0;
     const home = resolveManagedSessionRestoreHome(parentEnv, platform);
     if (!home)