pi-agent-browser-native 0.9.5 → 0.9.7

package/docs/ELECTRON.md

@@ -219,7 +219,7 @@ Cleanup partial failures fail the tool result with `failureCategory: "cleanup-fa
 
 For manual launches, close commands (`close`, `quit`, or `exit`) only close the browser/CDP session. Close the app yourself and clean its profile/temp files with normal host tools.
 
-On Pi `quit`, active wrapper-owned Electron launches are best-effort cleaned. On `/reload`, the current branch-visible active Electron launch and its isolated temp `userDataDir` are preserved for continuity while off-branch owned Electron launches are cleaned before process-local ownership is cleared. First reuse after reload/resume checks that the PID and profile are present, the saved browser WebSocket endpoint still matches the live app, and upstream `get cdp-url` points to that browser or one of its current targets. Ordinary browser calls, status reads, and probes share this check under the existing session lock; no reconnect or ref reset is needed. The `get cdp-url` read honors the caller's `timeoutMs` and cancellation, while localhost CDP requests keep their short fixed fetch budgets. Missing or mismatched evidence does not grant reuse, and generic restore-disabled sessions keep their existing rules. If cleanup is partial and skips or fails `user-data-dir` removal because the process or debug port is still live, the generic temp sweep preserves that profile path across reload, quit, repeated temp cleanup, process-exit cleanup, and stale temp-root pruning after restart rather than deleting it out from under the remaining host resource. If `electron.cleanup` closes the attached managed session but host process/profile cleanup is partial, later default browser calls still rotate away from that closed wrapper-managed session. Stale restored records (PID gone, port dead) are **reported** instead of guessed at or killed.
+On Pi `quit`, active wrapper-owned Electron launches are best-effort cleaned. A managed fork restart (`pi restart` or `/restart`, shutdown disposition `handoff` or `provisional`) is not a quit: every active branch-visible launch keeps running with its isolated profile protected through process exit, and the replacement worker restores its ownership from the transcript for later status, probe, and cleanup; off-branch owned launches are cleaned as on `/reload`. On `/reload`, the current branch-visible active Electron launch and its isolated temp `userDataDir` are preserved for continuity while off-branch owned Electron launches are cleaned before process-local ownership is cleared. First reuse after reload/resume checks that the PID and profile are present, the saved browser WebSocket endpoint still matches the live app, and upstream `get cdp-url` points to that browser or one of its current targets. Ordinary browser calls, status reads, and probes share this check under the existing session lock; no reconnect or ref reset is needed. The `get cdp-url` read honors the caller's `timeoutMs` and cancellation, while localhost CDP requests keep their short fixed fetch budgets. Missing or mismatched evidence does not grant reuse, and generic restore-disabled sessions keep their existing rules. If cleanup is partial and skips or fails `user-data-dir` removal because the process or debug port is still live, the generic temp sweep preserves that profile path across reload, quit, repeated temp cleanup, process-exit cleanup, and stale temp-root pruning after restart rather than deleting it out from under the remaining host resource. If `electron.cleanup` closes the attached managed session but host process/profile cleanup is partial, later default browser calls still rotate away from that closed wrapper-managed session. Stale restored records (PID gone, port dead) are **reported** instead of guessed at or killed.
 
 ### `timeoutMs` by action (quick reference)
 

package/docs/PERFORMANCE.md

@@ -0,0 +1,252 @@
+# Performance
+
+The extension avoids redundant work while preserving native browser capabilities,
+validation, redaction, page-target checks, transcript integrity, and cleanup
+ownership. The largest improvements are in large-result processing and offline
+journal conversion. Browser navigation and model latency remain outside those
+CPU measurements.
+
+## Captured baseline and integrated result
+
+The [retained measurement record](performance/2026-10-12.json) compares baseline
+`41467b70d255c06f5ec5e226a1adec420f8bcf4b` with the integrated runtime, identified by
+source and compiled-tree hashes. Measurements used Node 24.21.0 on macOS arm64,
+Apple M5 Pro, 18 logical CPUs, and 64 GiB RAM. This was a shared host: recorded load
+varied substantially. Paired order was baseline / optimized / optimized / baseline.
+
+### Fixed compiled-owner workloads
+
+Each side has 14 measured samples per workload, after two warmups in each run.
+Values are pooled medians in milliseconds; CPU is process user + system time.
+Outputs, recovery metadata, ordering, UTF-8, discarded JSON grammar, and recording
+replacement controls passed on both revisions.
+
+| Workload                                          | Wall before → after | CPU before → after | CPU reduction |
+| ------------------------------------------------- | ------------------: | -----------------: | ------------: |
+| Redact 1 MiB prose with embedded credentials      |       33.05 → 20.43 |      37.82 → 23.82 |         37.0% |
+| Summarize 20,000 snapshot refs                    |         8.49 → 1.23 |       12.68 → 2.74 |         78.4% |
+| Project batch metadata with 10,000 discarded rows |        22.10 → 0.14 |       26.73 → 0.18 |         99.3% |
+| Merge 10,000 artifact entries                     |       591.48 → 3.46 |      609.91 → 6.37 |         99.0% |
+| Project 1,000 small journal records               |       47.58 → 13.42 |     101.96 → 27.34 |         73.2% |
+
+These are deliberate scaling fixtures, not estimates of every ordinary call.
+For example, batch projection's median transient heap delta fell from 59.24 MiB to
+0.064 MiB, but that delta is not a retained-memory or allocation-total measurement.
+Automatic GC and scheduling still produced wall-time outliers; the record retains
+all samples rather than trimming them.
+
+### Actual native browser calls
+
+The registered extension tools also ran against real agent-browser **0.38.1** and
+headless Chrome for Testing **151.0.7922.77**, using deterministic loopback pages,
+automatic per-root sessions, two warmups, and 30 measured calls per workload on
+each revision. These source-loaded harness calls include native/browser subprocess
+latency; they do not include Pi's model/provider turn or external-site latency.
+
+| Warm native workload         | Median wall ms before → after |
+| ---------------------------- | ----------------------------: |
+| Title read with current refs |               156.14 → 127.19 |
+| Selector text read           |               188.21 → 158.55 |
+| Interactive snapshot         |               229.03 → 211.23 |
+| Two-row native getter batch  |               187.07 → 157.04 |
+| One-getter browser code cell |               185.03 → 154.88 |
+
+Host noise matters: one snapshot run was slower, 239.08 versus 229.25 ms;
+its other pair improved. These samples do not establish a universal browser
+speedup. Instrumented fake-native controls provide stronger work-count evidence:
+qualifying title/batch calls drop from four subprocesses to three; snapshot and
+eval drop from six to five; ref text/fill drop from five to four. No-ref and
+unrelated explicit-session controls keep their existing three subprocesses.
+Within-revision run medians varied by up to about 40 ms, so differences beyond
+the eliminated subprocess are not causally attributed here.
+
+Fifteen fresh import/factory samples on each revision remained below the existing
+250 ms budget: baseline 54.91–57.14 ms, optimized 55.29–58.44 ms. Ranges overlap,
+so no startup improvement is claimed. Both sides included optional search-tool
+registration without a search call. This diagnostic uses the locked development
+SDK snapshot; latest official/fork host qualification is a separate delivery gate.
+
+### Additional owner-boundary evidence
+
+Independent timeout-artifact checks remove cumulative retry waits: 1,000 missing
+paths took a median 50,700.11 → 59.54 ms, while one path stayed 50.58 → 50.66 ms.
+Across three 1,000-path runs, median process-wide sampled peaks were 19.19 MB
+heapUsed and 89.33 MB RSS, compared with 13.92 MB / 82.30 MB before (1 ms sampling). This exchanges modest linear transient memory for
+overlapping independent timers; it does not infer completed native steps.
+
+The distinct-session conversion comparison isolates branch retention: its
+pre-retention converter has the baseline retention logic **with the new tokenizer**,
+not the unchanged baseline commit. At 2,000 identities, median process-wide sampled
+peak heapUsed fell from 96.16 to 31.35 MB (1 ms sampling). At 4,000 identities,
+that pre-retention converter aborted with heap exhaustion (exit 134); the optimized
+converter completed with exact source/checksum checks. Both used `--max-old-space-size=128`; the actual total V8 heap limit was
+335,544,320 bytes, not a 128 MiB process-memory cap.
+The separate integrated compiled >1 GiB proof converted 1,612,280,613 source
+bytes to 1,078,631,285 bytes, verifying 34,683 refs, 100 receipts, three branches,
+and 4,001 distinct sessions. Its actual V8 heap limit was 335,544,320 bytes and
+peak RSS was 375,568 KiB. This correctness proof is separate from the smaller
+scaling comparison.
+
+Synthetic macOS discovery fixtures removed 360 unnecessary payload filesystem
+requests (601 → 241), with median CPU 19.86 → 10.27 ms. The strict quality-prefix
+fixture reduced duplicate policy passes from three to one, with median wall time
+6,085.27 → 3,665.97 ms. That is the prefix, not the entire quality workflow. Raw
+owner measurements and their fixture protocols are retained alongside the final
+integrated profiles.
+
+## Reproduce the warm-path profile
+
+Use the repository's Node and npm versions, install its locked dependencies, and
+build the target first:
+
+```sh
+npm ci --ignore-scripts
+npm run build
+npm run performance-profile -- --samples 7 > performance.json
+```
+
+The profiler imports compiled production owners and checks independently specified
+outputs. It runs two warmups and records every measured sample for five fixed
+workloads: 1 MiB prose redaction, a 20,000-ref snapshot summary, metadata projection
+of a batch containing 10,000 data rows, a 10,000-entry artifact manifest, and 1,000
+small journal projections. It does not launch a browser, Pi, npm, or a subprocess.
+
+To compare revisions, build each in its own worktree and use the **same profiler**
+against both compiled trees. Alternate the order to reduce host-load bias:
+
+```sh
+node --expose-gc scripts/profile-performance.mjs --root ../baseline --samples 7 > baseline-a.json
+node --expose-gc scripts/profile-performance.mjs --root . --samples 7 > optimized-a.json
+node --expose-gc scripts/profile-performance.mjs --root . --samples 7 > optimized-b.json
+node --expose-gc scripts/profile-performance.mjs --root ../baseline --samples 7 > baseline-b.json
+```
+
+Keep Node, fixtures, configuration, and hardware constant. Do not run broad tests
+or builds alongside timing samples. Source, compiled-tree, lockfile, fixture, and
+profiler hashes identify the actual inputs; a package version alone is not a
+revision identifier.
+
+Wall time excludes imports, fixture construction, explicit pre-sample GC, and
+output assertions. CPU includes process user and system time during that interval.
+Heap deltas are transient `heapUsed` differences with the output still alive—not
+allocation totals, retained memory, or peaks. RSS is process-wide; the reported
+high-water mark also includes setup. Shared-host load and automatic GC remain
+sources of variation. There are no warm-path timing thresholds.
+
+Entrypoint startup has a separate fresh-process profiler and its existing 250 ms
+budget:
+
+```sh
+npm run verify -- startup-profile --samples 3
+```
+
+That measurement is extension import/factory time, not full Pi startup or browser
+launch time. See [the proof contract](REFERENCE.md#proof-and-verification).
+
+## What changed
+
+### Results and command planning
+
+- Embedded-JSON redaction searches for structured-value openers and copies ordinary
+  prose in slices rather than appending every character. Balanced-value parsing,
+  malformed-input handling, credential redaction, and unchanged output survive.
+- Snapshot summaries count the existing refs without constructing and sorting a
+  complete ref list that the summary never uses.
+- Compact batch metadata excludes `data` and `stdout` before recursive projection
+  and redaction. Required metadata, warnings, and exact recovery actions remain;
+  full result and replay ownership do not move into the compact observation.
+- Artifact-manifest merging materializes recording candidates only when the entry
+  can supersede a recording. Ordinary image entries no longer copy a growing map
+  for a check that immediately returns empty. Recording identity and ordering stay
+  unchanged.
+- Argv descriptors reuse their already-cleaned command tokens. Launch-flag checks
+  discover command position only for the special `wait --state` distinction;
+  native boolean and restore flag semantics remain intact.
+
+### Journal and artifact storage
+
+Journal projection uses the installed streaming parser's raw tokenizer instead of
+building a Node stream pipeline for each record. Live replay applies the same
+native-or-token selection as its metadata scan to retained-size records; larger
+records still use the tokenizer. Both paths validate UTF-8 and complete JSON,
+including discarded values. The streaming path retains its explicit end-of-input
+flush, and the parser is still loaded lazily.
+
+Both offline converters retain a branch projection only until its last source
+child consumes it. Linear histories no longer retain every historical state map;
+real forks keep the independent state they need. Conversion still verifies the
+unchanged source and publishes an exclusive separate copy, never rewriting the
+original journal. The large-journal proof includes an individual string above
+Node's string ceiling and 4,000 distinct session identities:
+
+```sh
+npm run build
+node --max-old-space-size=128 test/helpers/large-browser-journal.mjs
+```
+
+The `128` setting limits V8 old space, not total V8 heap or process RSS. Report
+those separately. See [session storage](SESSION_STORAGE.md#verification).
+
+Artifact-retention scans overlap four independent file stats at a time, preserving
+scan order before eviction. This does not change the secure socket-directory
+traversal or its validation/error order.
+
+### Browser execution and timeout recovery
+
+A daemon observation may be reused only within one locked call, for its exact
+socket/namespace/session identity, before any intervening browser helper. It is
+not a cross-call cache. Replacement and unknown-generation checks remain
+fail-closed; capture still obtains its distinct post-operation generation receipt.
+Calls with no redundant observation keep their existing probes.
+
+A call waiting for another Pi process's browser operation no longer starts a
+process-identity query every 10 ms while that holder is confirmed alive. It sleeps
+on the holder's owner-lifetime socket and re-runs normal arbitration when the
+socket closes on release or exit. Unverifiable and still-choosing claims,
+unavailable endpoints (including socket paths over the platform limit) and
+native Windows keep polling. See [execution coordination](ARCHITECTURE.md).
+
+Independent timeout-artifact retry windows now overlap. Each declared path still
+gets up to three checks, 25 ms apart; results retain native plan order and page
+inspection starts afterward. A file finishing after **its own** window may remain
+missing. Existing files and recovered URLs remain current-state evidence, never
+proof that a timed-out step executed. See
+[the timeout contract](TOOL_CONTRACT.md#details).
+
+### Discovery, verification, and packages
+
+macOS Electron discovery stops after a missing framework instead of also probing
+its payload. Positive app verification and discovery order are unchanged.
+
+The quality facade runs scope and suppression-policy validation once through
+`lint`, rather than also repeating those checks as standalone steps. The same
+strict checker, compiler, formatting, tests, mutation probes, and document checks
+remain required.
+
+The build retains the complete emitted checkout tree. npm selects the bundled
+extension, unchanged permissioned code worker, and standalone helper bundles under
+`dist/packaged/lib/`. Package-only helpers do not overwrite raw checkout modules:
+that would split shared async-local process context and temporary-resource owners.
+Pi peers stay external and host-provided; source installs keep the existing
+`prepare` build. The package consumer checks execute config, offline conversion,
+the permissioned worker, and real Pi SDK/CLI loading without optional host peers
+installed in the consumer.
+
+## Preserved boundaries and rejected approaches
+
+No cross-call config/secret/DOM cache, pooled JavaScript worker, new recipe layer,
+or weaker validation gate was introduced. Fresh code globals, ordered secrets,
+rate spacing, cancellation, shared locks, live page checks, redaction, and
+branch-visible replay retain their existing owners.
+
+Parallel socket-directory traversal was not adopted: candidate traversal and
+native unknown-Dirent fallback behavior did not preserve the baseline's integrity
+and failure-order controls. The original traversal remains. Helper bundles that
+overwrite emitted checkout modules were also rejected and replaced with separate
+package-only outputs. Smaller whitespace-only bundles did not demonstrate a
+startup improvement beyond host noise.
+
+These decisions bound the performance claims. Synthetic CPU/scaling improvements
+are not an equivalent speedup for arbitrary browser workflows, external sites,
+model responses, or installation time. Windows qualification remains subject to
+the explicit owner waiver in [release guidance](RELEASE.md#current-0616-rollout-waiver).

package/docs/REFERENCE.md

@@ -8,7 +8,7 @@ It is for Pi users who want agents to browse sites, inspect pages, click through
 
 ## Pi release qualification
 
-CI qualifies the latest stable official Pi and latest maintained fork `main`, resolving their version/commit once per run and retaining SDK/CLI identity evidence. Locked development dependencies are reproducible build snapshots, not qualification targets; runtime peers remain wildcard. `npm run check:compat` checks the installed candidate SDK/CLI identity, typechecks, runs the existing offline tests (including the native Pi pipeline with a controlled provider and fake browser), and tests a packed runtime-only installation through both the SDK and the actual bundled RPC CLI. It does not substitute a fork SDK while leaving official types or child CLI installed.
+CI qualifies the latest stable official Pi and latest maintained fork `main`, resolving their version/commit once per run and retaining SDK/CLI identity evidence. Locked development dependencies are reproducible build snapshots, not qualification targets; runtime peers remain wildcard. The development snapshot overrides Undici to exact 8.12.3 because official Pi 1.0.2 through 1.4.0 pins exact Undici 8.10.2, which has the high/moderate advisories GHSA-xjj6-f33q-929c, GHSA-4qv8-2p9j-2685 and GHSA-f72v-6w45-q472; remove the override once the official development SDK depends on 8.12.2 or later. npm applies root overrides only where this repository is the npm root project: checkouts and Git-source installs, whose build-time development tree resolves 8.12.3. Published npm-package consumers never receive it, the extension does not import Undici at runtime, and qualified official Pi hosts keep their own Undici 8.10.2. `npm run check:compat` checks the installed candidate SDK/CLI identity, typechecks, runs the existing offline tests (including the native Pi pipeline with a controlled provider and fake browser), and tests a packed runtime-only installation through both the SDK and the actual bundled RPC CLI. It does not substitute a fork SDK while leaving official types or child CLI installed.
 
 Run in an empty HOME with a **short** TMPDIR outside your real home. Long temporary paths can exceed macOS's 103-byte Unix socket limit; keep the fixture's socket safety checks intact. Native lifecycle controls, live upstream help sampling, lifecycle dogfood, and platform qualification remain the separate gates documented below. A Pi-only compatibility run uses no live browser profiles, credentials, or agent-browser fork, and does not certify those external integrations.
 
@@ -88,7 +88,7 @@ The result is optimized for agent work:
 | Page snapshots are too large or viewport-blind                                                      | Shows compact, main-content-first summaries, surfaces an `Omitted high-value controls` section (plus `details.data.highValueControlRefIds`) when dense pages or desktop host screens hide editables, named surfaces/tabs, primary action buttons, and high-signal named links such as repository results from the trimmed ref lists, supports wrapper-side `snapshot -i --search <text>` / `--filter role=<role>` to trim dense pages while preserving full `details.refSnapshot`, supports `snapshot --viewport` for scroll/viewport metadata, supports `snapshot --diff` for quick ref-map deltas versus the prior tracked snapshot, and stores full redacted output in spill files when needed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `extensions/agent-browser/lib/results/snapshot.ts`, `extensions/agent-browser/lib/orchestration/browser-run/prepare.ts`, `test/agent-browser.presentation.test.ts`, `test/agent-browser.extension-validation.test.ts`                                                                                                                                                                                                                                                                                                                                                             |
 | Screenshots/downloads get lost in text                                                              | Normalizes artifact paths, creates missing parent directories, leaves click/download execution to native download, and reports existence, size, cwd, session, and repair status                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#download-screenshot-and-pdf-files)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | Profile restores and tab drift confuse agents                                                       | Tracks managed sessions, keeps every upstream helper probe on the same idle-timeout launch configuration so the background browser is not restarted between a snapshot and action, retains native CDP target IDs so same-address tabs remain distinct after resume, re-selects target tabs after observed drift, live-verifies the active target and refreshes its title after successful tab selection or `tab close` (while retaining new blank tabs, deliberate `about:blank` selections, and post-close blank targets, including batch transitions), rehydrates branch-backed session state on Pi session-tree changes, and pins later commands only for sessions with drift/restored-session risk                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | generated tab-recovery notes below; `test/agent-browser.extension-tab-recovery.test.ts` (drift and about:blank recovery), `test/agent-browser.extension-tabs.test.ts` (post-close target), `test/agent-browser.extension-ref-guards.test.ts` (snapshot/action environment and session-tree rehydration), `test/agent-browser.resume-state-branch-replay.test.ts` (tab targets / branch replay), `test/agent-browser.resume-state-managed-lifecycle.test.ts` (persisted managed ownership), `test/agent-browser.resume-state-launch-policy.test.ts` (resumed launch configuration) |
-| Auth/profile workflows can leak secrets                                                             | Supports `auth save --password-stdin`, redacts sensitive args, SAML/OAuth-bearing URLs, stdout/stderr, details, and snapshot spills, and discards malformed oversized stdout instead of persisting a parse-failure spill                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `test/agent-browser.extension-security-redaction.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| Auth/profile workflows can leak secrets                                                             | Supports `auth save --password-stdin`, redacts sensitive args, SAML/OAuth-bearing URLs, stdout/stderr, details, and snapshot spills, and discards malformed oversized stdout instead of persisting a parse-failure spill                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `test/agent-browser.extension-security-redaction.test.ts`, `test/agent-browser.extension-artifacts-fallbacks.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | 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, including raw batch rows and ordered code journals; 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                                                                  | Defines full per-session refs once in the native journal, exposes them on dedicated captures, 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; final results return native `isError` and a visible prose failure notice while preserving parseable caller-requested `--json` output. Native structured results expose the same bounded, redacted observations, not internal replay metadata                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | [`docs/TOOL_CONTRACT.md`](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`                                                                                                                                                                                                                                            |
@@ -96,7 +96,7 @@ The result is optimized for agent work:
 | 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; explicit CSS-container scrolling uses instant movement so smooth-scroll CSS cannot cause a premature no-movement failure; 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`](TOOL_CONTRACT.md#details), [`docs/COMMAND_REFERENCE.md`](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 native `args` and `agent_browser_action`; 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`](TOOL_CONTRACT.md#details), [`docs/COMMAND_REFERENCE.md`](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 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`](TOOL_CONTRACT.md#details), [`docs/COMMAND_REFERENCE.md`](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.38.1 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`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| Upstream CLI drift can silently invalidate wrapper behavior                                         | Publishes a repo-readable command reference, verifies it against the recommended 0.41.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`](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                                 | `agent_browser_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`](TOOL_CONTRACT.md#agent_browser_electron), [`docs/COMMAND_REFERENCE.md`](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`](COMMAND_REFERENCE.md#built-in-skills), `extensions/agent-browser/lib/command-policy.ts`, `extensions/agent-browser/lib/runtime.ts`                                                                                                                                                                                                                                                                                                                                                                                                                  |
@@ -119,9 +119,9 @@ Optional external tools unlock the full command surface:
 | `agent-browser` | All browser automation through this extension                                              | See upstream install docs                           |
 | `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.38.1` 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.
+Keep both binaries on `PATH`. This package recommends `agent-browser 0.41.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.
 
-On 0.38.1, use `snapshot --delta` for native full/unchanged/changed revisions and `snapshot --delta --full` to reset its baseline. Surviving DOM nodes keep their refs, but navigation/replaced nodes still require fresh refs. The wrapper preserves native revisions and refreshes complete refs internally for partial results. `screenshot --if-changed` (or `--threshold 0.01`) skips unchanged images without creating an artifact. `--input-mode instant|smooth|human` controls native session pointer movement; `click ... --human`, `drag ... --human`, and timed `mouse move` remain ordinary `args`. Recordings accept `--cursor` and `--contact-sheet`; the latter produces a timestamped PNG verified after stop. `auth login <name> --no-navigate` fills a prepared login page after upstream checks its origin. See the [command reference](COMMAND_REFERENCE.md#upstream-0381-rebaseline) for examples and limits.
+On 0.38+, use `snapshot --delta` for native full/unchanged/changed revisions and `snapshot --delta --full` to reset its baseline. Surviving DOM nodes keep their refs, but navigation/replaced nodes still require fresh refs. The wrapper preserves native revisions and refreshes complete refs internally for partial results. `screenshot --if-changed` (or `--threshold 0.01`) skips unchanged images without creating an artifact. `--input-mode instant|smooth|human` controls native session pointer movement; `click ... --human`, `drag ... --human`, and timed `mouse move` remain ordinary `args`. Recordings accept `--cursor` and `--contact-sheet`; the latter produces a timestamped PNG verified after stop. `auth login <name> --no-navigate` fills a prepared login page after upstream checks its origin. See the [command reference](COMMAND_REFERENCE.md#upstream-0381-rebaseline) for examples and limits.
 
 ### Android / Termux
 
@@ -203,7 +203,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.38.1 remains the recommended baseline
+- the installed upstream is a stable version at or above the supported 0.35.0 floor; 0.41.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
 
@@ -554,7 +554,7 @@ Ordinary native config discovery stays at the project or current managed browser
 
 ### Shared browser defaults
 
-Ordinary browser calls use one native named browser per **root Pi session**. A parent and its subagents share that browser; unrelated roots get different names and can browse concurrently. `pi-subagents` supplies `PI_SUBAGENT_ROOT_SESSION_ID` through its existing launch records, including detached runs, delegated forks, grandchildren, and revived children. Ordinary Pi new/fork/clone sessions get their own root identity; resuming the same root or changing its cwd keeps its browser name.
+Ordinary browser calls use one native named browser per **root Pi session**. A parent and its subagents share that browser; unrelated roots get different names and can browse concurrently. Current `pi-subagents` launches each child with equal `PI_INTERCOM_ROOT_SESSION_ID` and `PI_INTERCOM_PARENT_SESSION_ID` values naming its main session, including fresh and forked delegated runs; older releases supplied `PI_SUBAGENT_CHILD` with `PI_SUBAGENT_ROOT_SESSION_ID`, which remains supported. Ordinary Pi new/fork/clone sessions get their own root identity; resuming the same root or changing its cwd keeps its browser name.
 
 Cooperating updated Pi processes share a cross-process lock keyed by the actual socket context, canonical namespace, and session. It covers a direct call's helpers and action, or an entire code call; different identities can run independently. Coordinate navigation across separate tool calls with existing subagent/intercom tools. This is ordering, not rollback or protection against human navigation, external CLI clients, or older extension versions. Parent or child exit does not close the group browser. Native idle policy applies; explicitly close only your group's browser when the group is finished.
 
@@ -709,7 +709,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.38.1 capability baseline), selecting the sessionless plugin probe separately and then all remaining declarations, including explicit native text. It also runs `test/agent-browser.batch-fidelity.test.ts` and `test/agent-browser.overlay-real-upstream.test.ts` with the same opt-in environment. 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`](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.41.0 capability baseline), selecting the sessionless plugin probe separately and then all remaining declarations, including explicit native text. It also runs `test/agent-browser.batch-fidelity.test.ts` and `test/agent-browser.overlay-real-upstream.test.ts` with the same opt-in environment. 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`](RELEASE.md#real-upstream-contract-validation).
 
 A deterministic host-only live-browser wrapper smoke is available without an LLM choosing tool calls:
 
@@ -729,7 +729,7 @@ npm run smoke:platform:doctor
 npm run verify -- release
 ```
 
-`npm run verify -- release` includes the default verification gate, packaged Pi smoke coverage, and the release-blocking Crabbox platform matrix (the same matrix `npm run smoke:platform:all` runs standalone). For the full maintainer release flow, follow [`docs/RELEASE.md`](RELEASE.md). The package also has a `prepublishOnly` hook that runs the same release gate and `npm pack --dry-run` during `npm publish`.
+`npm run verify -- release` includes the default verification gate, the configured-source lifecycle harness, packaged Pi smoke coverage, and the release-blocking Crabbox platform matrix (the same matrix `npm run smoke:platform:all` runs standalone). For the full maintainer release flow, follow [`docs/RELEASE.md`](RELEASE.md). The package also has a `prepublishOnly` hook that runs the same release gate and `npm pack --dry-run` during `npm publish`.
 
 ## How it works
 
@@ -742,12 +742,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 browser instructions 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.38.1 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.41.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.38.1 and accepts stable runtimes at or above 0.35.0.
+- Recommends upstream `agent-browser` 0.41.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.
@@ -757,11 +757,11 @@ The upstream browser engine remains [`agent-browser`](https://agent-browser.dev/
 
 ## Automatic npm releases (maintainers)
 
-Follow the [shared release procedure](https://github.com/fitchmultz/.github#automatic-npm-releases): merge a reviewed PR into `main` with an intentional `package.json` version bump and a matching versioned `CHANGELOG.md` section. Automation never bumps versions, overwrites releases, or republishes an existing version. Once configured and enabled, it runs existing compatibility and native lifecycle checks, qualifies one candidate tarball, then waits for `fitchmultz` approval in the `npm` environment.
+The [shared release procedure](https://github.com/fitchmultz/.github#automatic-npm-releases) creates a reviewed patch-version PR after changes merge to `main`, then publishes the same version on npm and GitHub using the exact qualified candidate tarball.
 
-Approve only after checking the exact source commit, version, downloaded candidate tarball and summary against [the existing release gates](RELEASE.md#pre-release-checks), including required lifecycle/live-site evidence, artifact checks and all three final reviewer approvals. Apply the documented Windows waiver without claiming a Windows or full composed-gate pass. Approval attests genuine satisfaction of those requirements; it does not create proof. Authenticated, model-backed and paid checks stay outside CI. Automated publication disables npm hooks to publish the already checked bytes; the manual publisher instructions and their gates remain valid.
+Check the final source and candidate against [the existing release gates](RELEASE.md#pre-release-checks), including required lifecycle/live-site evidence and artifact checks. Complete enabled reviews and resolve their findings. Apply the documented Windows waiver without claiming a Windows or full composed-gate pass. Workflow validation is not evidence that publication completed on either service.
 
-Failed/unpublished candidates can retry daily at 12:17 UTC or via manual dispatch of `npm release` on `main`, without another bump. Set repository variable `NPM_RELEASE_ENABLED` to anything other than `true` to stop new release plans; cancel pending runs separately when needed. Workflow validation is not evidence of a completed real OIDC publication.
+Set repository variable `NPM_RELEASE_ENABLED` to anything other than `true` to stop new version and release plans; cancel pending runs separately when needed. Follow the shared procedure to retry an unpublished candidate.
 
 ## Local development
 
@@ -789,7 +789,7 @@ Configured-source lifecycle validation:
 npm run verify -- lifecycle
 ```
 
-The harness defaults to Pi model `zai/glm-5.2` and **180000 ms** per-step tmux waits; pass `--model <id>` and/or `--timeout-ms <ms>` after `lifecycle` when you need different settings (see [Configured-source lifecycle validation](RELEASE.md#configured-source-lifecycle-validation) in `docs/RELEASE.md`). It launches the supported Pi runtime with `--approve` and a deterministic `--session-id`, drives `/reload`, closes Pi, relaunches the exact same session, asserts the JSONL header id, and checks managed-session continuity, compiled-entrypoint pickup after process restart, persisted spill reachability, and native returned failure status and JSON preservation.
+The harness defaults to Pi model `zai/glm-5.2` and **180000 ms** per-step tmux waits; pass `--model <id>` and/or `--timeout-ms <ms>` after `lifecycle` (or after `release`, which forwards them only to its lifecycle step) when you need different settings (see [Configured-source lifecycle validation](RELEASE.md#configured-source-lifecycle-validation) in `docs/RELEASE.md`). It launches the supported Pi runtime with `--approve` and a deterministic `--session-id`, drives `/reload`, closes Pi, relaunches the exact same session, asserts the JSONL header id, and checks managed-session continuity, compiled-entrypoint pickup after process restart, persisted spill reachability, and native returned failure status and JSON preservation.
 
 Use lifecycle validation when testing `/reload`, exact-session relaunch, `/resume`, managed-session continuity, or persisted artifact behavior. Branch-backed state and `session_tree` cleanup ownership are covered by focused extension harness tests. Maintainers must run the lifecycle harness before every publish; see [Pre-release checks](RELEASE.md#pre-release-checks).