pi-agent-browser-native 0.9.5 → 0.9.6

package/docs/ARCHITECTURE.md

@@ -16,6 +16,16 @@ The package install path is the primary product path. Local checkout development
 
 Runtime graphs that use Pi host APIs are statically imported through Pi's extension loader, which supplies the host-peer mapping. Native ESM lazy imports must not bypass that mapping: a runtime-only global package does not install its optional Pi peers. The browser runner and observation/image publication retain Pi's native image primitives without a package-owned resolver or bundled host.
 
+The build keeps the complete emitted checkout tree, with its shared module-owned
+process environment and temporary-artifact cleanup state. Only the canonical
+`dist/extensions/agent-browser/index.js` is replaced by its bundle; the worker and
+all emitted libraries remain untouched. Six private package-only helper bundles
+live under `dist/packaged/lib/`: config policy, offline session conversion, parsing,
+playbook, snapshot, and runtime. npm publishes those helpers, the canonical extension,
+and the unchanged permissioned worker through exact `package.json` paths. CLI imports
+use the private packaged helpers; package imports stay external, including optional
+Pi peers. GitHub/source installs retain the same `prepare` build.
+
 ## Chosen shape
 
 ### Compact tools and native discovery
@@ -60,7 +70,7 @@ All participating Pi processes must restart with the updated package. The lock i
 
 `lib/browser-transcript.ts` defines one canonical `data.event` format and optional once-stored `data.snapshot`. Direct, advanced, code and Electron host operations record begin/finish receipts before dispatch and after observed effects, using outer tool-call ID plus inner index and a unique operation ID. The shared page reducer retains an inaccessible candidate during unresolved work and requires explicit reuse/replace/invalidate/unknown disposition. Ordinary results omit unchanged maps and unrelated artifact receipts; journal events carry redacted artifact-row changes in commit order. Final rendering queues actual spill writes and manifest publication, allowing unrelated small observations to finish while another namespace holds its artifact/lifecycle operation. `lib/orchestration/browser-run/artifact-merge.ts` preserves concurrent three-way manifest updates and recording lifecycle order. Native lifecycle evidence is retained before presentation/export. Failed begin blocks dispatch; failed finish stops dependent work and requires inspection without mutation replay. A named persistent journal requires actual publication even before Pi's first conversation. Disabled/no-file sessions use the native current in-memory ancestry for direct browser work without claiming durability; code still requires a published intent journal. Observation-only artifact receipts are optional without a published journal, so sessionless local results retain complete redacted private spills and selected files. Code lifecycle joins include outer finalization, and the shared generation guard keeps prior-branch observation spills process-private and prevents their artifact publication onto the new branch. JavaScript variables are never persisted.
 
-`lib/browser-journal.ts` token-projects published envelopes and ancestry through public Pi file/header/leaf APIs, loading only winning snapshot definitions. It captures the selected leaf before asynchronous reads and validates that same branch through public `getEntry()` ancestry on both hosts. Capture-local admission reuses a validated append-only prefix while checking endpoint identity/parent and new suffixes; publication/durability checks remain independent. Startup/tree restoration uses one queued captured replay for branch state and cleanup leases, with one per-session launch-configuration fold. Stock official 1.0.0 still eagerly loads native history before extension startup. Legacy adapters live only in `lib/browser-session-conversion.ts`, which publishes a validated stopped separate copy while retaining the source. Native generation checks use PID/start and socket identity, never saved URL or delta revision alone. Filtered/helper captures share this check. Small owner-qualified launch receipts retain observed restore-key provenance; restart verifies the current native generation and key before treating that provenance as live. Full storage, migration and consumer-memory boundaries are documented in [`SESSION_STORAGE.md`](SESSION_STORAGE.md).
+`lib/browser-journal.ts` token-projects published envelopes and ancestry through public Pi file/header/leaf APIs, loading only winning snapshot definitions. It captures the selected leaf before asynchronous reads and validates that same branch through public `getEntry()` ancestry on both hosts. Capture-local admission reuses a validated append-only prefix while checking endpoint identity/parent and new suffixes; publication/durability checks remain independent. Startup/tree restoration uses one queued captured replay for branch state and cleanup leases, with one per-session launch-configuration fold. Stock official 1.0.0 still eagerly loads native history before extension startup. `lib/browser-legacy-projection.ts` and its shared field projection normalize historical receipts read-only into this same canonical reducer at the journal boundary. Normal resume keeps the original bytes and locator; mixed-format ancestry, confirmation settings/provenance and cleanup ownership remain branch-relative. Non-winning legacy maps are discarded after each receipt. Native event validation cannot downgrade to the legacy path. `lib/browser-session-conversion.ts` reuses that decoder only when an operator explicitly requests a validated stopped separate archive copy. Native generation checks use PID/start and socket identity, never saved URL or delta revision alone. Filtered/helper captures share this check. Small owner-qualified launch receipts retain observed restore-key provenance; restart verifies the current native generation and key before treating that provenance as live. Full storage, migration and consumer-memory boundaries are documented in [`SESSION_STORAGE.md`](SESSION_STORAGE.md).
 
 ### Canonical observations and image geometry
 

package/docs/CODE_QUALITY.md

@@ -32,6 +32,12 @@ Review fixes before committing; dangerous fixes and suggestion fixes are not par
 `lint:fix`. Run formatting after reviewed lint fixes and rerun acceptance. Failures
 are never converted to success by these commands.
 
+The default, quality, pre-pr, platform-target, and release facades run scope and
+suppression-policy validation once through `lint`, before the corrected checker.
+Standalone `quality:policy` and `quality:scope` remain available for focused
+inspection and intentional scope regeneration; running them separately in the
+facade would repeat the same validation without adding coverage.
+
 ### Test scheduling
 
 `npm test` builds once and prepares the corrected checker once, then runs
@@ -53,6 +59,11 @@ than rewriting this checkout's `dist/` while other files consume it.
 focused serial checker suite. The allowance-isolation mutation must fail in the
 parallel stage with its named `code-quality.test.ts` diagnostic.
 
+The real prepare/pack fixture in `test/verify-package.test.ts` also runs a plain
+Node child against emitted checkout modules. It verifies shared process-environment
+session/namespace propagation and snapshot-spill cleanup through the imported temp
+owner; source-loaded tests cannot detect bundles overwriting these shared modules.
+
 ## Language and role scope
 
 The root `.oxlintrc.json` enables type-aware rules and compiler diagnostics. The

package/docs/COMMAND_REFERENCE.md

@@ -567,7 +567,7 @@ Detailed receipt/live-browser fields and browser-independent native read/confirm
 
 #### Artifact retention and dogfood-heavy QA runs
 
-The wrapper's internal recent artifact view defaults to 100 metadata rows, configurable with `PI_AGENT_BROWSER_SESSION_ARTIFACT_MANIFEST_MAX_ENTRIES=<count>`. That cap bounds the current view, not append-only history. Journal events store row changes; `details.artifactManifest` contains changed or referenced receipts for this invocation rather than the unchanged history. Complete reference captures are likewise defined once, with small reuse/invalidation events. See [browser session storage and stopped-copy conversion](SESSION_STORAGE.md).
+The wrapper's internal recent artifact view defaults to 100 metadata rows, configurable with `PI_AGENT_BROWSER_SESSION_ARTIFACT_MANIFEST_MAX_ENTRIES=<count>`. That cap bounds the current view, not append-only history. Journal events store row changes; `details.artifactManifest` contains changed or referenced receipts for this invocation rather than the unchanged history. Complete reference captures are likewise defined once, with small reuse/invalidation events. Historical browser journals resume automatically at the original path without rewriting history; the same ref and native-generation checks still apply. See [browser session storage](SESSION_STORAGE.md).
 
 This cap controls the internal recent view and summaries such as `Session artifacts: 42 live, 0 evicted (42/100 recent)`. It does not delete explicit files that upstream saved to paths you chose, such as screenshots, PDFs, downloads, traces, HAR files, or WebM recordings.
 
@@ -1129,7 +1129,7 @@ Other useful environment variables include `AGENT_BROWSER_DEFAULT_TIMEOUT`, `AGE
 
 <!-- agent-browser-playbook:end wrapper-tab-recovery -->
 
-- Wrapper-spawned commands clamp `AGENT_BROWSER_DEFAULT_TIMEOUT` to the upstream documented 25-second default and use a 35-second child-process watchdog (`PI_AGENT_BROWSER_PROCESS_TIMEOUT_MS` overrides the default 35s budget; top-level `timeoutMs` overrides it per browser CLI call). Explicit `wait <ms>`, `wait --timeout <ms>`, and WebMCP `invoke` / `result --timeout <ms>` calls can exceed that default; when top-level `timeoutMs` is omitted, the wrapper derives a subprocess watchdog from the requested command duration plus a small grace window. Batch budgeting and timeout recovery read the same effective source as upstream: raw command strings when present, otherwise stdin rows. Dialog commands are additionally bounded to 5 seconds (`PI_AGENT_BROWSER_DIALOG_PROCESS_TIMEOUT_MS`), and click/tap/find refs or tokens plus `eval --stdin` snippets that look like alert/confirm/prompt/dialog triggers are bounded to 8 seconds (`PI_AGENT_BROWSER_DIALOG_TRIGGER_PROCESS_TIMEOUT_MS`). A `session info` timeout returns only an exact-session `retry-session-info` status action, without page probes, liveness claims, or changes to existing page/ref state. When a browser-operation watchdog fires, `details.timeoutPartialProgress` may include a planned step list with `status: "unknown"` (including `generatedFrom` labels for generated QA rows). Current URLs and existing files do not establish which steps ran, failed, or remained pending. Multi-step timeouts offer `inspect-current-page-after-timeout` when the target is already verified, rather than guessing a retry position. A single read-only or idempotent step may offer a `retry-timeout-step` candidate with a one-row native batch (`args: ["batch"]` plus `stdin`); inspect the current state before retrying because its outcome is still unknown. If the target is unknown, standalone snapshots are removed and visible failure text plus `details.nextActions` show `verify-page-target-after-timeout`, including its session-scoped `batch --bail` args and short stdin for fail-fast `get url` then `snapshot -i`; dialog status/accept/dismiss actions remain allowed for blocking-dialog recovery. It also includes current page URL from best-effort session `get url`, followed by `get title` only after a URL is recovered (or a planned URL inferred from the step list when the session cannot answer), and declared artifact paths such as `screenshot`, `pdf`, `download`, or `wait --download` outputs with existence/state checks; the same evidence is appended under `Timeout partial progress` in visible text with URL/path redaction.
+- Wrapper-spawned commands clamp `AGENT_BROWSER_DEFAULT_TIMEOUT` to the upstream documented 25-second default and use a 35-second child-process watchdog (`PI_AGENT_BROWSER_PROCESS_TIMEOUT_MS` overrides the default 35s budget; top-level `timeoutMs` overrides it per browser CLI call). Explicit `wait <ms>`, `wait --timeout <ms>`, and WebMCP `invoke` / `result --timeout <ms>` calls can exceed that default; when top-level `timeoutMs` is omitted, the wrapper derives a subprocess watchdog from the requested command duration plus a small grace window. Batch budgeting and timeout recovery read the same effective source as upstream: raw command strings when present, otherwise stdin rows. Dialog commands are additionally bounded to 5 seconds (`PI_AGENT_BROWSER_DIALOG_PROCESS_TIMEOUT_MS`), and click/tap/find refs or tokens plus `eval --stdin` snippets that look like alert/confirm/prompt/dialog triggers are bounded to 8 seconds (`PI_AGENT_BROWSER_DIALOG_TRIGGER_PROCESS_TIMEOUT_MS`). A `session info` timeout returns only an exact-session `retry-session-info` status action, without page probes, liveness claims, or changes to existing page/ref state. When a browser-operation watchdog fires, `details.timeoutPartialProgress` may include a planned step list with `status: "unknown"` (including `generatedFrom` labels for generated QA rows). Current URLs and existing files do not establish which steps ran, failed, or remained pending. Multi-step timeouts offer `inspect-current-page-after-timeout` when the target is already verified, rather than guessing a retry position. A single read-only or idempotent step may offer a `retry-timeout-step` candidate with a one-row native batch (`args: ["batch"]` plus `stdin`); inspect the current state before retrying because its outcome is still unknown. If the target is unknown, standalone snapshots are removed and visible failure text plus `details.nextActions` show `verify-page-target-after-timeout`, including its session-scoped `batch --bail` args and short stdin for fail-fast `get url` then `snapshot -i`; dialog status/accept/dismiss actions remain allowed for blocking-dialog recovery. It also includes current page URL from best-effort session `get url`, followed by `get title` only after a URL is recovered (or a planned URL inferred from the step list when the session cannot answer), and declared artifact paths such as `screenshot`, `pdf`, `download`, or `wait --download` outputs with existence/state checks. Independent artifact retry windows overlap (up to three checks per path, 25 ms apart), preserve plan order, and settle before page inspection; files finishing after their own window may remain missing. The same evidence is appended under `Timeout partial progress` in visible text with URL/path redaction.
 - Oversized snapshots and oversized generic outputs may be compacted in tool content, with the full redacted output written to a spill file path shown directly in the tool result. Recent artifact metadata is bounded by `PI_AGENT_BROWSER_SESSION_ARTIFACT_MANIFEST_MAX_ENTRIES` (default 100); persisted spill files have a separate `PI_AGENT_BROWSER_SESSION_ARTIFACT_MAX_BYTES` budget (default 32 MiB; `0` disables automatic eviction).
 - The wrapper keeps `--help` and `--version` stateless so they do not consume the implicit managed-session slot.
 

package/docs/PERFORMANCE.md

@@ -0,0 +1,243 @@
+# 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. Fatal incremental UTF-8 decoding,
+full JSON validation—including discarded values—and an explicit end-of-input
+flush remain required. 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.
+
+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

@@ -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`                                                                                                                                                                                                                                            |
@@ -757,9 +757,9 @@ 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.
+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 publishes it without an approval step.
 
-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.
+Merging publishes, so before merging check the final PR head (up to date with `main`) and version 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. Merging 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.
 
 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.
 

package/docs/SESSION_STORAGE.md

@@ -24,9 +24,17 @@ Required replay snapshots stay in retained journal ancestry, outside observation
 
 Startup and tree changes serialize branch restore with managed/artifact work, reusing one captured replay for state and cleanup-lease recovery. Launch configuration is folded once per session during that replay. Tree changes join code execution through its complete observation finalization before restoring branch-visible state. Interrupted results retain complete caller observations in process-private spills without publishing their artifact state onto the newly selected branch. Tree changes do not roll back the real browser; process-owned cleanup and recording facts remain separate. An ordinary fork has a new native Pi UUID and cannot acquire its parent's managed/Electron/script cleanup rights. Wrapper-owned begins retain their selected socket root and owner UUID even if the launch finish is lost; restart can inspect or clean that original identity without declaring the launch successful. Owned follow-ups, code and cleanup keep that root when process defaults change; unrelated caller sessions retain native routing.
 
-## Converting a retained legacy journal
+## Resuming a retained legacy journal
 
-Legacy repeated maps/manifests and retired isolated-script leases are decoded only by the offline converter. Normal runtime replay requires the canonical event format and reports a conversion requirement rather than keeping a permanent second replay engine.
+Ordinary resume and tree navigation automatically read historical browser tool results, repeated maps/manifests and retired isolated-script leases at the original native journal locator. Replay opens the journal read-only: it does not rewrite bytes, invoke a converter, or require a new conversation. Subsequent operations append canonical events through Pi as usual.
+
+One shared legacy decoder normalizes each selected receipt into the same canonical event/reducer used by current journals and optional archive conversion. Mixed old/new branches preserve ancestry, interrupted outcomes, exact page URLs, explicit native confirmation settings (including `""`), compact pending/cleared provenance, artifacts and recorded cleanup owners. A legacy fork without an explicit original cleanup owner cannot acquire its parent's leases. Canonical event validation, committed-leaf/publication checks, native-generation ref guards and source identity checks remain in force; malformed native events cannot fall back to legacy decoding.
+
+Legacy maps are materialized one receipt at a time and discarded after normalization; only winning snapshot definitions are retained for selected-branch replay. An individual selected legacy map still must fit the consumer's memory. Missing generation evidence, evicted files and unrecorded effects remain unknown; replay never repeats browser commands or invents native confirmation capabilities.
+
+## Optional separate-copy conversion
+
+Conversion is an archive maintenance option, not a prerequisite for normal resume. Use it only when you explicitly want a distinct normalized copy.
 
 1. Stop or quiesce the exact writer through its owner. Do not convert an active journal or relaunch work merely to repair storage.
 2. Keep the original journal and choose a distinct private destination outside automatic session discovery.
@@ -51,7 +59,7 @@ Select the converted locator explicitly through the native session/worker owner.
 
 Focused storage tests exercise incident-sized refs, small-event growth, begin/finish append faults with actual dispatch counts, interruption, branch projections and native generation replacement. Existing tab/ref, confirmation, recording, artifact and lifecycle suites retain their behavior checks.
 
-After `npm run build`, the opt-in model-free proof runs a journal above 1 GiB, including an ignored individual string above Node's string ceiling and repeated legacy maps, through conversion and selected replay under a constrained V8 heap:
+After `npm run build`, the opt-in model-free proof runs a journal above 1 GiB, including an ignored individual string above Node's string ceiling, repeated legacy maps, and 4,000 distinct session identities, through conversion and selected replay under a constrained V8 heap:
 
 ```sh
 node --max-old-space-size=128 test/helpers/large-browser-journal.mjs

package/docs/SUPPORT_MATRIX.md

@@ -93,10 +93,10 @@ Current summary:
 | RQ-0149                         | Upstream 0.35.1 fixes snapshot-diff ref lifecycle, active-main-frame stream URL updates, and Windows ARM64 launcher selection without adding commands or flags. The wrapper preserves the 0.35.0 stable floor and accepts newer stable versions without version-specific shims.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#upstream-0351-rebaseline), [`scripts/agent-browser-target.mjs`](../scripts/agent-browser-target.mjs), `test/agent-browser.upstream-version.test.ts`, `test/agent-browser.real-upstream-contract.test.ts`                                                                                                                                                                                                                                                                                       |
 | RQ-0150                         | Upstream 0.35.2 hardens standalone dashboard origin access and fixes root remote CDP WebSocket query URLs. The wrapper parses `--allowed-origins` as a value and keeps explicit or implicit dashboard-start lifecycle calls sessionless; upstream owns origin validation, tokens, and the CDP fix.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#upstream-0352-rebaseline), [`docs/TOOL_CONTRACT.md`](TOOL_CONTRACT.md#dashboard-reverse-proxy-origins), `test/agent-browser.runtime.test.ts`                                                                                                                                                                                                                                                                                                                                                   |
 | RQ-0151                         | Upstream 0.36.0 adds experimental WebMCP page tools, default local-Chrome enablement with launch-scoped `--no-webmcp`, an opt-in MCP profile, and the `webmcp-gen` skill. The wrapper passes list/invoke/result/cancel through, preserves params/frame/detach/timeout arguments, derives watchdogs from effective direct/raw/stdin commands, keeps pending detached targets unverified, and restores batch target/ref state only after URL verification and a fresh snapshot, while keeping 0.35.0 as the stable floor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#upstream-0360-rebaseline), [`docs/TOOL_CONTRACT.md`](TOOL_CONTRACT.md#experimental-webmcp), `test/agent-browser.runtime.test.ts`, `test/agent-browser.wait-timeouts.test.ts`, `test/agent-browser.process.test.ts`, `test/agent-browser.page-target-validation.test.ts`, `test/agent-browser.extension-ref-guards.test.ts`, `test/agent-browser.real-upstream-contract.test.ts`                                                                                                                |
-| RQ-0153                         | Browser storage retains native JSONL authority, once-stored ancestral ref definitions, small correlated begin/finish events, explicit uncertainty/reuse and native-generation validation, invocation-only artifact receipts and ordered row changes. Failed persistence never retries effects; ordinary forks retain facts without acquiring parent cleanup rights. Read-only token replay and stopped separate-copy conversion preserve all ancestry, explicit observations and original audit bytes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | [`docs/SESSION_STORAGE.md`](SESSION_STORAGE.md), `lib/browser-transcript.ts`, `lib/browser-journal.ts`, `lib/browser-session-conversion.ts`, `test/agent-browser.storage-growth.test.ts`, `test/agent-browser.storage-recovery.test.ts`, existing script/ref/confirmation/Electron lifecycle tests                                                                                                                                                                                                                                                |
+| RQ-0153                         | Browser storage retains native JSONL authority, once-stored ancestral ref definitions, small correlated begin/finish events, explicit uncertainty/reuse and native-generation validation, invocation-only artifact receipts and ordered row changes. Failed persistence never retries effects; ordinary forks retain facts without acquiring parent cleanup rights. Read-only token replay automatically normalizes historical receipts through the same canonical reducer at the unchanged locator/bytes, retaining mixed-format ancestry, confirmation settings/provenance and cleanup ownership. Optional stopped separate-copy conversion reuses that decoder.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | [`docs/SESSION_STORAGE.md`](SESSION_STORAGE.md), `lib/browser-transcript.ts`, `lib/browser-journal.ts`, `lib/browser-session-conversion.ts`, `test/agent-browser.storage-growth.test.ts`, `test/agent-browser.storage-recovery.test.ts`, existing script/ref/confirmation/Electron lifecycle tests                                                                                                                                                                                                                                                |
 | RQ-0152                         | Agent feedback closes recovery and evidence gaps without a new runtime layer: unknown-target timeouts return a visibly executable `get url` → `snapshot -i` fail-fast action while dialog recovery remains allowed; successful tab creation/selection/close, including dispatched batch rows, live-verifies URL/fresh titles and retains new, selected, and post-close blank tabs; compacted direct or batched `outputPath` writes use only full command-redacted live wrapper spills and fail rather than save metadata; explicit URL reads/all-read batches avoid browser helpers and managed replacement, while proven native read confirmations preserve exact session routing and capability-gated browser independence; single session-info preflights distinguish daemon/browser/native/Pi ownership; native recording receipts expose capture versus encoded measurements and survive failure/timeout exports, with bounded identity-matched recovery and no file-only success; direct or batched first/fresh local headed launches expose an unverified `browserWindow` handoff while attachments do not; snapshot spills and SAML/OAuth URL values are redacted at model/persistence boundaries; unsupported direct/batch `scrollintoview text=...` fails before upstream false success with visible native recovery payloads while help passes through; and web search sends Exa primary/version guidance, removes exact normalized-URL duplicates without overfetch, and labels provider page dates without claiming crawl/version proof.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | [`docs/TOOL_CONTRACT.md`](TOOL_CONTRACT.md), [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md), [`docs/ARCHITECTURE.md`](ARCHITECTURE.md), `test/agent-browser.extension-errors-artifacts.test.ts`, `test/agent-browser.extension-tabs.test.ts`, `test/agent-browser.extension-validation.test.ts`, `test/agent-browser.page-target-validation.test.ts`, `test/agent-browser.runtime.test.ts`, `test/agent-browser.snapshot-presentation.test.ts`, `test/agent-browser.web-search.test.ts`, `test/agent-browser.real-upstream-contract.test.ts` |
 
-Browser journal storage (RQ-0153) uses one canonical small event/reducer, once-stored complete captures and journal-ordered artifact changes. `test/agent-browser.storage-growth.test.ts` protects the incident-sized map and ordinary-code growth; `test/agent-browser.storage-recovery.test.ts` covers actual append-fault dispatch counts, concurrent publication during captured-branch replay, unpublished selected-leaf refusal, unknown prefixes, same-URL generation replacement, branch conversion and strict token validation. Existing tab/ref, read-confirmation, recording, artifact and Electron lifecycle suites retain their contracts. The opt-in `test/helpers/large-browser-journal.mjs` exercises a >1 GiB original with a giant ignored value under a constrained V8 heap; it reports actual RSS separately. Official and fork load/restart qualification remains independent, and stock official 1.0.0's native eager loader is not repaired by the extension alone. Conversion is offline and source-retaining; see [`SESSION_STORAGE.md`](SESSION_STORAGE.md).
+Browser journal storage (RQ-0153) uses one canonical small event/reducer, once-stored complete captures and journal-ordered artifact changes. `test/agent-browser.storage-growth.test.ts` protects the incident-sized map and ordinary-code growth; `test/agent-browser.storage-recovery.test.ts` covers actual append-fault dispatch counts, concurrent publication during captured-branch replay, unpublished selected-leaf refusal, unknown prefixes, same-URL generation replacement, branch conversion and strict token validation. Existing tab/ref, read-confirmation, recording, artifact and Electron lifecycle suites retain their contracts. The opt-in `test/helpers/large-browser-journal.mjs` exercises a >1 GiB original with a giant ignored value under a constrained V8 heap; it reports actual RSS separately. Official and fork load/restart qualification remains independent, and stock official 1.0.0's native eager loader is not repaired by the extension alone. Ordinary legacy resume preserves the original locator and bytes; optional archive conversion is offline and source-retaining. The shared harness retains raw legacy fixtures so resume suites exercise runtime normalization, not pre-converted journals. See [`SESSION_STORAGE.md`](SESSION_STORAGE.md).
 
 QA truthfulness (#121, RQ-0145) is covered by the registered-tool controls in `test/agent-browser.extension-input-modes.test.ts` and the strict `contract suite matches QA non-pass after same-URL error-buffer rollover` case in `test/agent-browser.real-upstream-contract.test.ts`. The real fixture fills the native error FIFO with identical rows, then verifies that a new document actually throws again at the same URL and that QA is always non-pass. Matched rows fail as an unverified check, not an application-error assertion. Empty/cleared and explicit `checkErrors: false` controls preserve valid passes; the wrapper does not fix upstream `errors --clear` or accept a warning-only pass as resolution.
 
@@ -114,7 +114,7 @@ Upstream 0.38.1 observation and input compatibility is covered by `test/agent-br
 
 Upstream 0.37 recording compatibility uses one command-local path/URL reader around numeric `--fps` pairs; direct, raw-batch and stdin-batch preflight reject destination collisions before native dispatch. FPS-only calls keep the intended pinned tab, and FPS-only restarts keep refs. Every dispatched start still requires fresh refs to protect older supported natives. `test/agent-browser.artifact-diagnostics.test.ts`, `test/agent-browser.batch-fidelity.test.ts` and presentation tests cover these boundaries. The native contract also checks positive/absent WebMCP hints and first-load header inheritance/clearing without custom tab setup. Short/cold native Ubuntu captures can fail to encode; the FPS fixture explicitly logs 12-second captures and verifies output rather than treating an empty file as a frame.
 
-Artifact argv and timeout recovery (#119, RQ-0076) use native operand positions, retain literal global-looking tokens inside batch rows, and select raw batch commands instead of ignored stdin. Timeout observations retain current page and artifact existence evidence while all unacknowledged planned rows stay unknown; neither a matching URL nor an existing file proves execution. Multi-step timeouts offer inspection without inferring a failed/pending boundary. Executable retry candidates for a single retryable step preserve the original row in a one-row batch. Interleaved `wait --download` / `-d` timeout pairs keep the next retained path and its original index. Runtime, artifact-diagnostics, and timeout tests cover extraction, reservation, preparation, and presentation; `test/agent-browser.batch-fidelity.test.ts` adds real native saved-file, missing wait-download, reservation, and watchdog evidence under `npm run verify -- real-upstream`. Getter batching amortizes one extra ref-freshness snapshot per top-level call or batch when the existing checks apply. Direct `session info` timeouts stay status-only (`retry-session-info`), preserving page/ref/reopen state; cold-boundary and result tests cover this.
+Artifact argv and timeout recovery (#119, RQ-0076) use native operand positions, retain literal global-looking tokens inside batch rows, and select raw batch commands instead of ignored stdin. Timeout observations retain current page and artifact existence evidence while all unacknowledged planned rows stay unknown; neither a matching URL nor an existing file proves execution. Independent artifact paths overlap their own three-check, 25 ms retry windows, preserve native row and JSON field order, and settle before page probes; late files may remain missing after their own window. Multi-step timeouts offer inspection without inferring a failed/pending boundary. Executable retry candidates for a single retryable step preserve the original row in a one-row batch. Interleaved `wait --download` / `-d` timeout pairs keep the next retained path and its original index. Runtime, artifact-diagnostics, and timeout tests cover extraction, reservation, preparation, and presentation; `test/agent-browser.batch-fidelity.test.ts` adds real native saved-file, missing wait-download, reservation, and watchdog evidence under `npm run verify -- real-upstream`. Getter batching amortizes one extra ref-freshness snapshot per top-level call or batch when the existing checks apply. Direct `session info` timeouts stay status-only (`retry-session-info`), preserving page/ref/reopen state; cold-boundary and result tests cover this.
 
 Cold URL reopen is covered by `test/agent-browser.cold-resume.test.ts`, the daemon/page-boundary regressions in `test/agent-browser.cold-boundaries-session-policy.test.ts`, `test/agent-browser.cold-boundaries-page-reopen.test.ts` and `test/agent-browser.cold-boundaries-command-classification.test.ts`, and the opt-in `contract suite matches cold URL reopen after quit` case in `test/agent-browser.real-upstream-contract.test.ts`. Deterministic boundary tests cover non-page prefixes, fragment routes, history commands, explicit destinations, transcript replay, unreached navigation and unchanged native batch/error order. `test/agent-browser.destination-cancel.test.ts` covers direct/native-batch new-window and URL-diff follow-ups, redirected/unknown targets (including blank redirects with a remembered duplicate tab), ordered ref invalidation, reached versus unreached rows, and cancellation before or after a cold-reopen attempt with replay and process cleanup. Release acceptance requires the first page operation after confirmed shutdown to observe the remembered non-root URL with both empty and origin storage, including after non-page calls and on hash-routed pages, before any explicit open, with refreshed refs. Focused native Mac evidence does not replace actual Ubuntu, real Pi lifecycle, checkout, live-site, or final release gates.
 
@@ -126,7 +126,7 @@ Lightpanda support preserves native command access rather than promising Chrome
 
 Confirmation-policy continuity uses existing canonical session page events, resolved before helpers. The focused native nextAction case proves exact denial, a useful confirmed audit followed immediately by title/body reads across resume, bare getter/PID continuity, and denied recording-restart sentinel/original-take preservation; the shared-defaults owner covers selected-string/empty/unset precedence, code/advanced routing, ordered pending-batch targets/replay with a gated URL helper, failed replacement cleanup/recovery, off-branch cleanup, close and identity isolation. Strict native guarded-control markers reuse the same transcript reducer with compact command/action provenance, not command replay; exact decisions avoid helper-slot replacement without claiming native ID validation or browser independence. Read-confirmation tests cover forged/foreign/first-nondecision controls, raw-argv-over-stdin decisions, later unknown-page checks, ordered confirmed batch effects, truthful requested/early-helper/post-command-helper pending copy, and completed click/tab/failed-inner/close reconciliation through real code intent/finish replay, cold-resume covers pending helper exposure/replay, and Electron host tests cover ambient/retained policy. Definite no-admission attempts restore prior policy while interrupted work retains intent. Pending close does not retire ownership or restore state. Native policy changes still restart normally; pending commands remain native-owned. Read-confirmation regressions also cover ordered confirmed snapshots, later pending/failed/invalidation rows, one-use freshness consumption through direct/code/batch resume, semantic role click/check/fill and unique role/label select after snapshot approval with unchanged payloads, absent/ambiguous select targets and drift, warm/no-resume direct and semantic select success on unchanged path/hash routes for caller-owned and freshly established wrapper-owned managed sessions versus refusal after a live-observed complete-URL change, including hash-only routes, without a gated-snapshot loop or changing ordinary fragment-insensitive ref/tab comparisons, plus live/resumed attachment retirement after confirmed close. Registered confirmation tests also cover direct/batch tab transport metadata, exact approval/denial, visible conditional continuation, malformed/mismatched extras and page/eval/HTTP provenance rejection; actual SDK/native proof uses the real authenticated-tab transport with a dummy loopback token. Presentation tests distinguish direct/nested pending snapshot controls from complete empty snapshots and preserve redacted recovery actions and explicit JSON. Click-dispatch owner tests and local native SDK proof cover timer cancellation, pending-safe marker/listener expiry without an extra helper, and native ref/XPath click dispatch when `evaluate` guards optional diagnostic probes. The patched recording-restart/navigation subcase has a separate test-only opt-in; stock upstream still runs the remaining confirmation checks. See [real upstream qualification](RELEASE.md#real-upstream-contract-validation).
 
-Shared native defaults are covered by `test/agent-browser.shared-defaults.test.ts`: environment/file/argv precedence, caller-owned reuse across independent Pi contexts, quit ownership, native helper idle settings, unchanged implicit cleanup, and an opt-in real local-profile fixture proving shared state and code follows the selected ordinary browser rather than a disposable isolated session. Code tests cover the fresh child language boundary and persistent browser behavior; the local Electron handoff regression in `test/agent-browser.extension-electron-host-lifecycle.test.ts` keeps generated launch ownership despite a native session environment default; native config validation uses upstream rather than a second schema. See [shared browser defaults](REFERENCE.md#shared-browser-defaults). These tests do not promise permanent third-party authentication.
+Shared native defaults are covered by `test/agent-browser.shared-defaults.test.ts`: environment/file/argv precedence, caller-owned reuse across independent Pi contexts, quit ownership, native helper idle settings, unchanged implicit cleanup, and an opt-in real local-profile fixture proving shared state and code follows the selected ordinary browser rather than a disposable isolated session. Code tests cover the fresh child language boundary and persistent browser behavior; the local Electron handoff regression in `test/agent-browser.extension-electron-host-lifecycle.test.ts` keeps generated launch ownership despite a native session environment default; native config validation uses upstream rather than a second schema. See [shared browser defaults](REFERENCE.md#shared-browser-defaults). These tests do not promise permanent third-party authentication. Call-local daemon-observation regressions also require exact identity, one status probe before helper-free preparation, refusal of replaced or unknown generations, native confirmation handling, and a fresh post-capture receipt; observations are never cached across calls.
 
 Browser correctness regressions cover credential-bearing filtered network details/exports, native generated-Blob downloads with actual saved bytes, accessible-name click target identity and abstention, smooth CSS-container movement, and parseable early-result JSON. Native fixture coverage complements deterministic dispatch/cleanup and output-shape checks; release qualification remains separate.
 
@@ -142,6 +142,10 @@ Linux/macOS, declared Node floors, official/fork host identities, required consu
 
 ## Verification evidence
 
+[Performance measurements](PERFORMANCE.md) document the measured result, journal,
+execution, discovery, package, and verification changes. Their synthetic CPU and
+scaling profiles remain separate from real-browser latency and host qualification.
+
 **0.38.1 PR evidence (2026-09-17, local macOS):** the full unit/fake suite passed 1,146 tests with 27 opt-in skips; the final review fixes then passed typecheck and 64 affected tests. Generated docs, live command-reference sampling, and the 132-file packaged Pi smoke passed. The real-upstream contract and 75 native batch/fidelity checks passed, as did all eight deterministic dogfood flows. Interactive compiled-checkout Pi smoke covered example.com and react.dev, delta/ref follow-ups, conditional screenshots, and a recording batch whose persisted result had two verified artifacts and no pending artifacts. Separate native probes confirmed helper-consumed WebMCP catalog updates remain visible. These checks do not qualify release-only platform/lifecycle gates; the hosted native-Windows result is recorded on the PR.
 
 Re-run the gates below before each release. Dated outcomes in this table are historical evidence for their named source/version, not qualification of the current Pi 1.0 implementation. The earlier 0.36.0 rebaseline passed local pre-PR, real-upstream and deterministic dogfood on 2026-09-01; the 0.35.0 floor was last validated locally on 2026-08-26. The historical 0.38.1 PR qualification used local macOS and the hosted native-Windows gate. Current explicit owner waivers take precedence; neither historical passes nor failures qualify the new candidate. Release-only cross-platform/model/lifecycle and publication gates remain separate.