pi-agent-browser-native 0.9.6 → 0.9.7

package/CHANGELOG.md

@@ -2,6 +2,100 @@
 
 ## Unreleased
 
+## 0.9.7 - 2026-11-01
+
+<!-- npm-release:unreleased:start -->
+
+### Changed
+
+- Preserve a retained npm candidate through package verification, configured-source lifecycle checks, and the required macOS and Ubuntu Crabbox suites.
+- Run the retained candidate through reusable hosted release qualification for both supported Pi hosts and real browser sites.
+- Recommend separately installed stock `agent-browser` 0.41.0 while retaining the stable 0.35.0 runtime floor and no upper cap. Refresh audited help/source metadata, generated guidance, fixtures, and native CI installation across 0.39.3–0.41.0. Document native download persistence, daemon `.config` cleanup, route CORS, config trust, restore skipped origins, and the current non-help MCP integration limitation. Updating metadata does not speed an installation already on 0.41.0.
+- Read large session journals faster when restoring browser state on startup, resume, switch and tree navigation. Records are framed with native byte search, and records up to 1 MiB whose nesting and structure keep native parsing to a few MiB are validated with native JSON. Larger or denser records and every native rejection still use the token projector in file-read-sized chunks, so accepted records, first errors and ancestry checks are unchanged. Cold restores read the whole journal. Repeated restores on the same native manager/header and file reuse structural metadata or scan only the appended suffix, with full validation after ordinary source invalidation or errors. Selected event and winning ref bodies are always reread. On synthetic 40 MB and 285 MB journals whose records are all under 1 MiB, the journal replay read alone fell about 2.5x and 4.5x in median wall time with identical output; end-to-end restore and session switching were not measured (#303).
+- Document CLI HTTPS trust, experimental Obscura limits, lost-response inspection before retry, stricter native click/ref/policy handling, preserved launch-argument values, and upstream provider changes without bundling or emulation.
+- Wait for a busy shared browser without querying the holder's process identity every 10 ms. Outside native Windows, each browser execution claim owner listens on a local socket in the per-user coordination directory. A waiter that has just confirmed its holder alive, with a published ticket, connects once and sleeps until that connection closes on release or holder exit, then re-runs the normal arbitration. Claims still choosing a ticket, owners whose identity cannot be confirmed, unavailable endpoints (including socket paths over the platform limit) and native Windows keep the existing 10 ms polling with fresh identity checks.
+- Validate the winning snapshot definitions of a restored journal without building and discarding their complete ref maps. Journal reads and branch restore still check every definition at the same point with the same errors, and restored refs, order, targets and generations are unchanged. On the large-journal proof's 34,683-ref definition, each validation fell from about 18.7 to 3.0 ms in median repeat time, with transient allocation down from at least 18.3 MB to 0.6 MB. Replay of captured real journals, whose definitions are small, showed no measurable change.
+- Send about 2.6 KB less browser instruction text with every request that carries the full instructions (about 540 prompt tokens with gpt-6.1-terra and 930 with claude-sonnet-5-5, measured through Cloudflare AI Gateway). The full text no longer repeats the short orientation bullets that only the compact fallback needs and lists the launch-scoped flags once. Every rule, command and tool is still covered, and the compact fallback is unchanged.
+- Let `npm run verify -- release` accept the lifecycle harness options (`--model`, `--timeout-ms`, `--verbose`, `--keep-artifacts`), check their values with the lifecycle parser before any step runs, and forward them only to its lifecycle step, so the complete release gate can run its lifecycle prompts on a chosen model. The lifecycle harness now runs Pi on its own tmux server, so that model's provider credentials come from the verify process environment rather than an already running tmux server, and removes that server's socket after shutdown. Release without options and its other steps are unchanged.
+
+### Fixed
+
+- Inspect npm package-file output correctly in platform doctor, including npm 12 and Windows npm shims, and let native pack preparation finish before reporting repository hygiene.
+- Run the permissioned `agent_browser_code` worker when the installed package path contains symlinks, including macOS temporary directories.
+- Show the actual lint error when quality acceptance fails in CI. `npm run lint` now finishes writing its policy inventory line before Oxlint starts; through a pipe, Oxlint's first diagnostic could otherwise land partway through that line and disappear when `npm run quality:mutations` shortened long lines for the job log. The mutation controls now require each expected diagnostic to survive that shortening.
+- Keep wrapper-owned fresh browsers, Electron apps, their isolated profiles, and in-progress recordings running across a managed fork `pi restart` or `/restart`. The fork reports `session_shutdown` reason `quit` with `disposition: "handoff"` (or `"provisional"` for an unready replacement that may roll back); the extension now treats it as an ownership transfer: it keeps every owned managed session and Electron launch that the replacement worker restores from the active branch, including non-current identities, and closes only owned resources it cannot restore. Live page JavaScript and forms survive the restart. Genuine quit (`release` or no disposition, including official Pi) and `/reload` cleanup are unchanged.
+- Show native 0.40+ skipped restore origins in default text, so a partial storage restore is visible without `--json`: a nonempty `state load` `skippedOrigins` list follows `State loaded`, and `session info` runtime metadata includes `restoreSkippedOrigins`. Structured details and explicit `--json` output are unchanged.
+- Preserve native indexed `batch --omit-command` results while retaining cookie/storage/error redaction, ordered close/reopen and snapshot state, and artifact verification. Match native indexes to the effective raw/stdin plan without losing skipped empty-row positions; public receipts and full spills keep command omission.
+- Keep POSIX process identities stable across timezone and locale changes. Probe native `ps` in UTC/C while preserving the rest of its environment, distinguish qualified identities from unqualified persisted timestamps, and retain ambiguous live execution claims, temp roots, and restored Electron processes instead of treating them as reused PIDs. Incomparable saved daemon identities invalidate old refs without reloading a live managed page; restore-disabled sessions still require verified provenance and may refuse reuse until closed and freshly launched. Restart every Pi process that loads the extension when upgrading: older running releases read the new identities as reused PIDs and can remove the newer release's in-progress or long-held execution claims.
+- Keep the requested `outputPath` receipt (`outputFile`: saved or failed, path, source, bytes or error) visible to the model when a large result is compacted, in explicit `--json` and `agent_browser_code` results, and in `structuredContent`. Previously only `details` kept it, so an agent could not confirm a saved file without reading the full spill.
+- Share the root Pi browser with current pi-subagents delegated children again. Direct and code calls in a child resolve its main session from the equal `PI_INTERCOM_ROOT_SESSION_ID`/`PI_INTERCOM_PARENT_SESSION_ID` pair instead of launching a separate browser (where a bare read saw `about:blank`); older `PI_SUBAGENT_CHILD`/`PI_SUBAGENT_ROOT_SESSION_ID` launches still share their root.
+- Run the maintainer npm facade correctly through symlinked paths, including macOS temporary directories, by using Node's native entrypoint detection instead of comparing noncanonical file URLs.
+- Clear the development-only Undici audit findings (GHSA-xjj6-f33q-929c, GHSA-4qv8-2p9j-2685, GHSA-f72v-6w45-q472) by overriding the development Pi SDK's exact Undici 8.10.2 to 8.12.3 wherever this repository is the npm root project (checkouts and Git-source installs, which build with the development tree). Published npm-package installs, runtime dependencies and the Pi 1.0 floor are unchanged, and official Pi hosts still run their own Undici 8.10.2 (#302).
+- Recognize native `--use-system-ca` optional boolean values during command discovery so `--use-system-ca false read <url>` remains a read command.
+- Let a first page-dependent call on a caller-owned explicit session, such as `--session s1 --ignore-https-errors auth login <profile>`, start the browser with its own launch flags. When the call carries browser launch flags and native `session info` reports no running daemon, remembered-tab selection and the page-target probe no longer cold-start that browser without them, including after a transcript reload. Retire the stopped browser's tab identity and refs after dispatch, and observe the replacement page after success so ordinary follow-ups cannot reuse the old physical tab; failed or unobserved launches leave the target unknown. Replacement-page observation does not label a read-only command as a mutation or reopen the stopped caller-owned browser's remembered URL. Flagless calls and running browsers keep their checks (#294).
+- Read Windows process-start generations through a fresh .NET process lookup and invariant UTC ticks, retaining the existing versioned identity format, native executable, cancellation and probe budgets.
+- Avoid querying a browser execution predecessor's process identity after its immutable claim is confirmed gone, while retaining fresh generation checks for present or unresolved claims and rechecking presence after each query.
+- Retry Windows `EPERM` failures when publishing a browser execution claim only within the original acquisition budget, revalidating the same immutable owner and scope before every retry; cancellation, unknown ownership, and single-attempt probes still fail closed.
+- Time browser execution coordination waits with Node's monotonic `performance.now()` clock instead of the system wall clock. A system clock step (for example an NTP correction or VM resume) no longer makes a waiter give up early or wait past its budget: on Linux a +120 s step had ended a 30 s wait after about 1.5 s, and a −120 s step kept a 5 s wait going until its holder released. This covers polling and owner-endpoint waits, direct-call and code-cell coordination deadlines, and process-identity probe budgets. Persisted claim and file timestamps, including the stale-claim age check, remain wall-clock.
+- Time Electron launch readiness, the 1 s SIGTERM grace after a failed launch, `electron.cleanup` process-exit windows, web-search request spacing, and the phase time in managed-session close timeout messages with the same monotonic clock. On a real Ubuntu guest, a +120 s system clock step failed a healthy stock Electron launch as a timeout within about 0.2 s; a −120 s step kept cleanup of an unresponsive app waiting past its 5 s window (still waiting at 15 s); after a failed launch of an app whose main thread was busy, a −120 s step was still delaying its SIGKILL at 11.6 s, while a +120 s step sent SIGKILL 0.35 s after SIGTERM, cutting the grace short; close timeouts reported −117019 ms or 122938 ms in their phase; and real Exa searches either skipped the 1.1 s request spacing after a +120 s step or held the next search for about two minutes after a −120 s step. Persisted launch timestamps remain wall-clock.
+- Keep a live browser execution lock owner on Linux when the system clock steps. Linux process identity now uses the kernel boot ID and the boot-relative start ticks in `/proc/<pid>/stat` instead of wall-clock-derived `ps` start times, which made a held lock look abandoned and let a second caller acquire it. A recorded identity in a different or untagged format is unknown rather than proof of PID reuse.
+
+<!-- npm-release:unreleased:end -->
+
+- Automate qualified npm releases (#339) ([7420c31](https://github.com/fitchmultz/pi-agent-browser-native/commit/7420c31caf461730c4c148bac33801b63607173c))
+
+### What's Changed
+
+- docs: establish proactive dependency maintenance policy by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/290
+- fix: allow compact prompt fallback on unmanaged Pi hosts (fixes #270) by @youki258 in https://github.com/fitchmultz/pi-agent-browser-native/pull/271
+- Preserve browser CLI signals and empty-output failure diagnostics by @hara-seihun in https://github.com/fitchmultz/pi-agent-browser-native/pull/273
+- fix(ci): restore blocking official/fork Windows qualification by @pi-durable[bot] in https://github.com/fitchmultz/pi-agent-browser-native/pull/291
+- test: repair current-host Browser qualification fixtures by @pi-durable[bot] in https://github.com/fitchmultz/pi-agent-browser-native/pull/292
+- Make native Windows best-effort (1/2) by @pi-durable[bot] in https://github.com/fitchmultz/pi-agent-browser-native/pull/295
+- fix(build): scope checker compiler long-path support to native Git commands by @pi-durable[bot] in https://github.com/fitchmultz/pi-agent-browser-native/pull/293
+- test(auth): verify global profiles and managed browser login by @pi-durable[bot] in https://github.com/fitchmultz/pi-agent-browser-native/pull/296
+- perf: cache documentation paths per loaded extension instance by @pi-durable[bot] in https://github.com/fitchmultz/pi-agent-browser-native/pull/298
+- fix: let cold caller-owned launches keep their flags by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/299
+- Refresh agent-browser baseline to 0.39.2 by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/301
+- deps(dev): override development Pi SDK Undici to 8.12.3 by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/307
+- perf(agent-browser): validate small journal records natively during replay by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/306
+- perf(browser): replay only appended session metadata by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/308
+- Speed up browser journal replay by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/309
+- Fix delegated browser session sharing by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/310
+- Wake browser execution waiters on holder release instead of polling by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/312
+- Require a Pi restart for coordinated package upgrades by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/314
+- Validate replayed snapshot definitions without rebuilding ref maps by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/316
+- Forward lifecycle options through the release gate by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/317
+- Isolate policy GC test fixtures from concurrent processes by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/319
+- Preserve native indexed batch redaction and replay (1/2) by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/313
+- Recommend agent-browser 0.41.0 (2/2) by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/323
+- Stop repeating browser orientation in full instructions by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/321
+- Keep outputPath receipts visible in compacted browser observations by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/318
+- Remove the lifecycle harness's private tmux socket after stopping its server by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/322
+- Fix timezone-dependent POSIX process identity (1/2) by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/311
+- Keep owned browsers across managed fork restarts by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/325
+- fix: keep Linux lock owners when the system clock steps (2/2) by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/315
+- Time browser execution waits on the monotonic clock (1/2) by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/320
+- Keep lint diagnostics visible in piped quality logs by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/326
+- Use the real start identity in the shared-directory policy-debug acquisition test by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/327
+- Stabilize code timeout fixture after emission by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/328
+- Time Electron launch and cleanup, close timeout messages and web-search spacing on the monotonic clock (2/2) by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/324
+- Prepare npm release automation by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/333
+- Use current upstream for release qualification by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/334
+- Fix code sandbox through symlinked installs by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/335
+- Fix platform doctor package inspection by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/336
+- Preserve the retained release candidate through verification (1/3) by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/337
+- Qualify the retained browser candidate on hosted runners (2/3) by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/338
+- Automate qualified browser releases (3/3) by @fitchmultz in https://github.com/fitchmultz/pi-agent-browser-native/pull/339
+
+### New Contributors
+
+- @youki258 made their first contribution in https://github.com/fitchmultz/pi-agent-browser-native/pull/271
+- @hara-seihun made their first contribution in https://github.com/fitchmultz/pi-agent-browser-native/pull/273
+- @pi-durable[bot] made their first contribution in https://github.com/fitchmultz/pi-agent-browser-native/pull/291
+
+**Full Changelog**: https://github.com/fitchmultz/pi-agent-browser-native/compare/v0.9.6...v0.9.7
+
 ## 0.9.6 - 2026-10-14
 
 ### Changed
@@ -1029,7 +1123,7 @@ See the [migration guide](docs/TOOL_CONTRACT.md#07-migration). Restart participa
 
 ### Validation
 
-- Reproduced the `pi install -l --approve https://github.com/fitchmultz/pi-agent-browser-native@v0.2.50` source-install failure, then verified production-dependency source builds, project-local GitHub install, project-local npm install, and release gates before publish.
+- Reproduced the GitHub source-install failure with `pi install -l --approve` against version `0.2.50`, then verified production-dependency source builds, project-local GitHub install, project-local npm install, and release gates before publish.
 
 ## 0.2.50 - 2026-06-11
 

package/README.md

@@ -6,18 +6,18 @@ pi-agent-browser-native adds browser tools to [Pi](https://pi.dev). Use it to re
 
 ## Install and start
 
-Use Node 24.21.0 or later and Pi 1.0.0 or later. This extension requires a separate agent-browser installation.
+Use supported Node.js and Pi releases. This extension requires a separate agent-browser installation. See the [runtime requirements](docs/REQUIREMENTS.md#runtime-requirements) for minimum versions.
 
-The recommended agent-browser version is 0.38.1. This extension accepts stable versions 0.35.0 or later.
+The latest stable agent-browser release is recommended. Older stable releases are supported down to the [documented minimum](docs/REQUIREMENTS.md#runtime-requirements), with no upper version cap. See the [command guide](docs/COMMAND_REFERENCE.md) for native download fixes, daemon-file cleanup, indexed batch output, and the current MCP limitation.
 
 ```bash
-npm install -g agent-browser
+npm install -g agent-browser --allow-scripts=agent-browser
 agent-browser install
 pi install npm:pi-agent-browser-native
 pi
 ```
 
-`agent-browser install` downloads Chrome for Testing. On Linux, use `agent-browser install --with-deps` if browser libraries are missing. Android users need the [Termux setup](docs/REFERENCE.md#android--termux).
+The npm flag permits the browser CLI's install script. `agent-browser install` downloads Chrome for Testing. On Linux, use `agent-browser install --with-deps` if browser libraries are missing. Android users need the [Termux setup](docs/REFERENCE.md#android--termux).
 
 Ask Pi:
 
@@ -72,6 +72,8 @@ Profile access exposes private page content to the model. That content can persi
 
 Credential-like values are redacted, but ordinary page text stays visible. Verify the signed-in page after you select a profile or restore browser state.
 
+Native `batch --omit-command` keeps indexed results without echoed commands. Cookie/storage redaction, ordered close/reopen effects, snapshot refs, and artifact verification still apply, including when empty stdin rows are skipped.
+
 Ask for a headed browser if you need to watch a task or complete a login. Remote environments can keep the window off your desktop.
 
 See [profiles and sessions](docs/REFERENCE.md#authenticatedprofile-workflows) for profile selection, restore limits, and cleanup.
@@ -96,13 +98,19 @@ npm exec --package pi-agent-browser-native -- pi-agent-browser-doctor
 
 It checks the browser CLI, supported versions, and duplicate Pi package sources. It does not change settings.
 
-This is a pre-1.0 package. Windows has unresolved browser session-locking and restored Electron cleanup test failures. Release tests do not cover Android. Electron desktop tools do not apply to Android apps. See the [support matrix](docs/SUPPORT_MATRIX.md) for details.
+For browser execution coordination failures, launch Pi with Node's standard `NODE_DEBUG=pi-agent-browser-policy` environment setting (PowerShell: `$env:NODE_DEBUG = 'pi-agent-browser-policy'`). This optional channel is silent by default and writes failure-stage breadcrumbs to stderr, not tool results. Lines carry Node's PID plus an opaque per-process attempt number and acquisition or release phase (cleanup has separate stage labels); standalone library inspections use attempt `0`. They contain fixed reasons and normalized native error codes/syscalls, never claim contents, paths, session names, or process-start identities. Normal choosing-state missing tickets and confirmed disappearing claims are quiet. A release/cleanup breadcrumb alone does not explain an acquisition failure. Unset `NODE_DEBUG` after collecting diagnostics; these observations do not change coordination policy or budgets.
+
+This package is still early-stage; expect breaking changes as it evolves. **Native Windows is best-effort**, not a required PR or release qualification target. macOS/Linux and official/fork host/API qualification remain strict. Windows has unresolved browser session-locking and restored Electron cleanup test failures; a small nonblocking native CI smoke is not full qualification, and broader Windows suites are explicitly on demand. Release tests do not cover Android. Electron desktop tools do not apply to Android apps. See the [support matrix](docs/SUPPORT_MATRIX.md) for details.
 
 For recordings, install `ffmpeg` with the encoder for your WebM or MP4 output. Verify the completed file after you stop the recording.
 
+Recent agent-browser releases support finite `mcp call` invocations, but this extension currently rejects every non-help `mcp` call. MCP session identity, cross-session coordination, credential presentation, and image handling are not integrated. Use the direct browser tools; see the [MCP boundary](docs/TOOL_CONTRACT.md#native-mcp-boundary).
+
 For remote browsers, use a URL that the browser host can reach. `localhost` refers to the browser host.
 
-For stale references or unexpected tabs, follow the returned recovery actions. Take a fresh snapshot before another interaction. A snapshot inside a batch does not protect refs used after a later page-changing step; add another snapshot after that step or split the batch.
+Preparatory tab/page checks do not launch a stopped caller-owned explicit `--session` ahead of its launch-flagged command, including after resume. After dispatch, the old browser's tab identity and refs are retired. A successful command observes the replacement page before follow-ups; if it cannot be observed, the target stays unknown. Put launch flags on the launch command; an already-running browser may ignore them.
+
+For stale references or unexpected tabs, follow the returned recovery actions. Take a fresh snapshot before another interaction. An incomparable saved process identity after an update invalidates old refs without reloading a still-live page. A snapshot inside a batch does not protect refs used after a later page-changing step; add another snapshot after that step or split the batch.
 
 ## More documentation