# Current upstream support matrix

Related docs:
- [`../README.md`](../README.md)
- [`../AGENTS.md`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/AGENTS.md) (rebaselining and verification stack)
- [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md)
- [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md)
- [`ELECTRON.md`](ELECTRON.md)
- [`RELEASE.md`](RELEASE.md)
- [`platform-smoke.md`](platform-smoke.md)
- [`REQUIREMENTS.md`](REQUIREMENTS.md)

## Purpose

This is the durable release-readiness checklist for the targeted upstream version in [`scripts/agent-browser-target.mjs`](../scripts/agent-browser-target.mjs), which `CAPABILITY_BASELINE.targetVersion` imports. It maps the capability inventory in [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs) to documentation, runtime handling, tests, and validation evidence. Update it whenever the target version or inventory changes.

## Maintainer refresh checklist

When upstream ships a new `agent-browser` or the inventory changes:

1. Edit [`scripts/agent-browser-target.mjs`](../scripts/agent-browser-target.mjs) for the runtime target and [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs) for `helpCommands` / `inventorySections`, using real `--help` output from the binary you intend to target (neither file shells out to `agent-browser`).
2. Align human prose and required tokens in [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md) outside the generated HTML-comment blocks.
3. Regenerate bounded blocks with `npm run docs -- command-reference write`, then run `npm run docs` (or `npm run docs -- command-reference check`).
4. Update the **Baseline checklist by inventory section** table below so each `CAPABILITY_BASELINE.inventorySections[].id` row still points at the right docs, code, tests, and status notes.
5. Re-run the gates in **Verification evidence** on a machine that matches release expectations (`pi`, `tmux`, model config for lifecycle) and replace the dated status cells with fresh outcomes.

## Audit result

- Target upstream: `agent-browser 0.34.0` (must match `TARGET_AGENT_BROWSER_VERSION` in [`scripts/agent-browser-target.mjs`](../scripts/agent-browser-target.mjs); the capability baseline imports it).
- Source of truth: `CAPABILITY_BASELINE.inventorySections` in the same file (stable `id` keys: `skills`, `core-commands`, `state-tabs-frames-dialogs`, `network-storage-artifacts-diagnostics`, `batch-auth-setup-ai`, `options-and-env`).
- Status: source and wrapper adaptation target the 2026-08-11 0.34.0 audit. Keeps 0.33.0 a11y/HAR/`find` coverage, documents 0.33.1 idle-timeout/tab-recovery and 0.33.2 stream quality/size env vars, and enables Git-checkout-generation-stable `AGENT_BROWSER_RESTORE` for extension-managed `piab-*` sessions so SSO cookies survive browser relaunches. Prior helper idle-timeout, post-`tab close` target refresh, and document-direction scroll behavior remain.
- High-priority support gaps: 2026-05-26 audit found sessionless local commands and command-scoped value flags needed sharper wrapper handling; runtime/tests/docs now cover those paths. The 0.28.0 rebaseline added local `mcp` and `plugin` surfaces plus plugin-backed credential login; wrapper docs/tests mark `mcp` and known `plugin` commands sessionless, with no compatibility shim for older upstream releases. The 0.29.1 rebaseline added upstream `@agent-browser/sandbox` helper-package guidance and stricter `install --with-deps` failure semantics; no new wrapper runtime mode or bundled dependency was required. The 0.30.1 rebaseline fixed upstream `wait --url` glob matching, so constrained `job.assertUrl` delegates glob and exact patterns directly to `wait --url`. The 0.31.0 rebaseline adds restore workflow and namespace/session lifecycle surfaces (`--restore`, restore checks, `--namespace`, `session id`, and `session info`) without adding a wrapper compatibility layer. The 0.31.1 rebaseline fixes upstream React renderer selection for `react tree`, `react inspect`, and `react suspense`; no wrapper runtime change was required. The 0.31.2 rebaseline adds the local-launch-only `--webgpu` preset and `doctor --webgpu`, plus periodic restore-state autosaves controlled by `AGENT_BROWSER_AUTOSAVE_INTERVAL_MS`; the wrapper treats WebGPU as launch-scoped and, for wrapper-owned headed launches, defaults autosave off to avoid upstream 0.33.2's visible temporary storage-collector tabs while preserving save-on-close and explicit opt-in at daemon launch; changing a running daemon requires close plus a fresh launch. The 0.32.0 rebaseline hardens request/worker/popup/WebRTC containment behind `--allowed-domains`, fixes waits against already-complete documents, and adds a separate `@agent-browser/eve` package; the wrapper makes containment launch-scoped, retains its final-URL check as defense in depth, and adds no Eve-specific mode. The 0.32.1–0.32.2 rebaseline updates only eve compatibility/packaging, but the full current-surface audit also found the local reference had omitted upstream `read [url]` since 0.30.0; baseline/help sampling, content-first presentation, tab-target preservation, timeout budgeting, docs, and tests now cover it. The 0.32.3–0.32.4 rebaseline adds HAR response-body capture modes, the `derive-client` skill, fixed `find role` implicit-ARIA / accessible-name matching with locator-detail misses, and an advertised `find` action list of `click, fill, check, hover, text` only; the wrapper documents and classifies those surfaces without adding a new input mode. Remaining upstream-owned caveat: some help paths still mention `wait <selector> --state hidden` / `detached`, but runtime probes show those shapes still fail, so wrapper docs keep `wait --fn` disappearance predicates and top-level `uncheck` / `type` / `focus` passthrough instead of `find` for those actions. `wait --download <path>` still reports the requested path without guaranteed on-disk persistence ([#1300](https://github.com/vercel-labs/agent-browser/issues/1300)).
- Post-`v0.2.29` review state: commits `eb55320` through `86abbfb` add browser guidance/smoke coverage plus `RQ-0086` click-probe reduction, `RQ-0087` same-snapshot form fill batching, `RQ-0088` current-ref fallback on locator misses, `RQ-0089` direct-upstream click mutation investigation, and `RQ-0090` stop-boundary/artifact-path guidance. Verification gates below were rerun on 2026-05-18 after those tasks landed. Constrained `job` (`RQ-0064`), the lightweight `qa` preset (`RQ-0065`), the experimental `sourceLookup` helper (`RQ-0066`), the experimental `networkSourceLookup` helper (`RQ-0067`), optional Exa/Brave-backed `agent_browser_web_search` with Pi-scoped package config (`RQ-0121`), and agent recovery for search/profile configuration failures (`RQ-0122`) are implemented; see [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#job), [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#qa), [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#sourcelookup), [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#networksourcelookup), and [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#optional-companion-web-search). Reusable browser recipes (`RQ-0068`) are intentionally not adopted as a runtime surface; see [`ARCHITECTURE.md`](ARCHITECTURE.md#no-reusable-recipe-layer-yet).

## UX/reliability decisions from 2026-05-29 agent feedback

Closed feedback decisions map to their canonical contracts in [`docs/support-notes.md`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/docs/support-notes.md). Keep this active matrix limited to release-critical status and gates.

Current summary:

| Range | Status | Source of truth |
| --- | --- | --- |
| RQ-0110–RQ-0120 | Agent feedback triage resolved or documented; remaining unsupported areas are environment/upstream-owned. | [`docs/support-notes.md`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/docs/support-notes.md) |
| RQ-0123–RQ-0127 | Stress-report wrapper fixes shipped; prompt-derived business-action blocking remains intentionally out of scope. | [`docs/support-notes.md`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/docs/support-notes.md) |
| `agent-browser 0.27.2` baseline | Historical upstream rebaseline shipped; `RQ-0101` remains the compact-snapshot high-value-controls decision. | [`docs/support-notes.md`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/docs/support-notes.md) |
| RQ-0128 | Upstream `agent-browser 0.27.3` install-only rebaseline shipped; no new wrapper capability adopted. | [`docs/support-notes.md`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/docs/support-notes.md) |
| RQ-0129 | Upstream `agent-browser 0.29.1` rebaseline shipped; sandbox helpers are documented upstream package guidance, not a wrapper runtime. | [`docs/support-notes.md`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/docs/support-notes.md) |
| RQ-0130 | Upstream `agent-browser 0.30.1` rebaseline shipped; `wait --url` glob support replaces the wrapper `job.assertUrl` predicate workaround. | [`docs/support-notes.md`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/docs/support-notes.md) |
| RQ-0131 | Upstream `agent-browser 0.31.0` rebaseline shipped; restore workflow and namespace/session lifecycle globals are parsed, documented, and carried through wrapper-managed probes/state. | [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#upstream-0310-rebaseline) |
| RQ-0132 | Upstream `agent-browser 0.31.1` rebaseline shipped; React renderer selection is upstream-fixed for `react tree`, `react inspect`, and `react suspense`, with no wrapper CLI/schema changes. | [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#upstream-0311-rebaseline) |
| RQ-0133 | Upstream `agent-browser 0.31.2` rebaseline adds WebGPU launch/doctor/MCP surfaces and periodic restore-state autosaves; wrapper launch parsing/policy and docs now cover both. | [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#upstream-0312-rebaseline) |
| RQ-0134 | Upstream `agent-browser 0.32.0` rebaseline hardens domain containment, fixes completed-page waits, and adds a separate eve extension package; wrapper launch policy and docs cover the relevant behavior. | [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#upstream-0320-rebaseline) |
| RQ-0135 | Upstream `agent-browser 0.32.2` rebaseline updates eve packaging only and closes the wrapper's prior missing `read [url]` inventory/presentation contract. | [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#upstream-0322-rebaseline) |
| RQ-0136 | Wrapper regression fix keeps helper subprocess launch environments stable, refreshes active tab state after `tab close`, and makes ordinary document-direction scrolling deterministic before upstream fallback. | [`docs/ARCHITECTURE.md`](ARCHITECTURE.md), [`docs/TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details) |
| RQ-0137 | Upstream `agent-browser 0.32.4` rebaseline adds HAR `--content` body modes, the `derive-client` skill, and fixed `find role` implicit-ARIA/name matching with locator-detail misses; wrapper classifier/argv/docs cover those surfaces. | [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#upstream-0330-rebaseline) |
| RQ-0138 | Upstream `agent-browser 0.33.0` rebaseline adds `a11y` axe-core audits and discarded-tab revival on tab switch; wrapper documents/presents `a11y` and samples the new help surface. | [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#upstream-0330-rebaseline) |
| RQ-0139 | Upstream `agent-browser 0.33.2` rebaseline documents daemon idle timeout, stream quality/size envs, and tab-recovery fields; wrapper enables Pi-transcript- and Git-checkout-generation-scoped managed-session restore for SSO stickiness without cross-chat newest-file clobber with canonical namespace identity, replayable pinned managed/Electron probes, nested attachment isolation, check-to-spawn config pinning with native POSIX/Windows stale-root identity, fail-closed restore storage, JSON close-state capture, and lockless convergent ownership-proven snapshot retention plus immutable ticket-claim cross-process daemon-policy locking with mandatory per-winner daemon inspection, a pre-update v2 bridge, absolute POSIX process probes, PID/start-identity dead-claim/artifact recovery, final post-setup spawn revalidation, managed restore-capability redaction/access guards, same-process restore-disabled daemon provenance plus inactive-daemon null-policy restart, owned-policy Electron probes, abort-safe Electron launch, independent daemon-inspection timeout, case-insensitive reserved managed live-session names, all-failed Electron probe classification, fail-closed POSIX socket ancestry/entry validation plus Android app-sandbox socket/storage trust, Termux-local process probes and policy locks, Android device/inode generation fallback, pinned-disabled file access (including raw Chrome args/config) plus protected local CLI/environment input/output paths, authoritative persisted unverified/failed page transitions and URL-first Electron handoff cleanup, and local state-file navigation, same-checkout-lineage generation expiry, malformed-output discard, a per-key 256-record churn bound, caller-owned explicit-session live URL gating before content access, process-local canonical per-session serialization through semantic snapshots and main execution, non-bail batch failure-path analysis that prevents prior-page content exposure, semantic live gating before snapshot resolution, Windows drive-relative protected-path detection, nested batch rejection, and upstream ASCII-space batch-tokenizer parity. | [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#upstream-0332-rebaseline), [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) |
| RQ-0140 | Successful CDP/auto-connect and Electron sessions preserve one attached browser across native-tool follow-ups and cleanup by omitting wrapper local-launch defaults, with environment support, branch replay, first-use content blocking, live URL gates against external drift, and close cleanup. | [`docs/ARCHITECTURE.md`](ARCHITECTURE.md), [`docs/TOOL_CONTRACT.md`](TOOL_CONTRACT.md), `test/agent-browser.extension-passthrough-validation.test.ts` |
| RQ-0141 | Headed managed sessions avoid upstream 0.33.2 visible autosave targets by default and retain that daemon environment across helpers, still-owned off-current follow-ups, failed-replacement ownership, Electron cleanup, and reload/resume; slow daemon-policy inspection uses a 35-second budget; headed mode is launch-scoped; the effective launch interval persists across resume and changes in either direction require close plus a fresh daemon; and bare, review-only, fenced-reference, conditional, directly negated, or reference attachment paths do not become close-blocking output requirements while explicit contiguous output path lists, per-clause availability, duplicate precedence, and Markdown destinations are handled conservatively and linearly. | [`docs/ARCHITECTURE.md`](ARCHITECTURE.md), [`docs/TOOL_CONTRACT.md`](TOOL_CONTRACT.md), `test/agent-browser.managed-session-daemon-policy.test.ts`, `test/agent-browser.process.test.ts`, `test/agent-browser.prompt-policy.test.ts` |
| RQ-0142 | Top-level `script` provides bounded one-shot JavaScript loops, branches, and multi-page aggregation through the complete ordinary browser executor. A permissioned child exposes only null-prototype `browser` / `emit` task functions, receives no user-visible host capabilities, serializes at most 25 calls, and uses a unique restore-disabled wrapper session with a durable pre-spawn Pi lease, finally-close, active branch/shutdown abort-and-wait cleanup, and exact lease recovery. Script-owned helpers/cleanup case-insensitively clear ambient upstream launch/profile/restore/attachment and proxy controls; final data is compact-serialized with a second post-redaction byte/depth guard; rehydrated spills reserve IPC-envelope headroom, inner summary/text are bounded, complete response envelopes are size-checked, and script-visible next actions are policy-compatible after isolated identity removal; malformed bridge calls and missing workers fail structurally; policy-rejection and dispatched-failure counters are disjoint. The collapsed Pi call row shows a bounded terminal-safe source preview with visible line-break markers and its expanded state shows the full terminal-safe source with JavaScript line terminators preserved and removed controls marked. It requires persisted Pi sessions, classifies uncaught source exceptions as `script-error`, confirms successful cleanup in compact prose, and deliberately has no named recipe/import/shared-state surface. The same dogfood pass compacted common/QA output, made failure `nextActions` model-visible and exact-namespace/session-stable (including explicit empty namespace overrides), limited close cleanup guidance to existing explicit artifacts, clarified raw batch stdin, normalized empty semantic names, and added bounded timeout/navigation recovery actions. | [`docs/TOOL_CONTRACT.md`](TOOL_CONTRACT.md#script), [`docs/ARCHITECTURE.md`](ARCHITECTURE.md#one-shot-script-isolation), [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#one-shot-code-mode), `test/agent-browser.script.test.ts` |
| RQ-0143 | Browser-backed calls require the exact canonical upstream version at runtime, report expected/observed version mismatch before launch, and keep stateless/local diagnostics available; target metadata is shared by runtime, docs verification, and package contents. | [`scripts/agent-browser-target.mjs`](../scripts/agent-browser-target.mjs), [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#upstream-0332-rebaseline), `test/agent-browser.upstream-version.test.ts` |
| RQ-0144 | Managed restore keys are scoped to both checkout generation and Pi transcript so upstream 0.33.2's newest-file-wins loading cannot let concurrent chats clobber or inherit cookies/storage. Fresh rotations, reload, restart, and `/resume` of one transcript retain continuity; passive upstream configs are safely ignored under the pinned empty config while explicit overrides remain incompatible. | [`docs/ARCHITECTURE.md`](ARCHITECTURE.md), [`docs/TOOL_CONTRACT.md`](TOOL_CONTRACT.md), `test/agent-browser.managed-session-restore.test.ts`, `test/agent-browser.real-upstream-contract.test.ts` |
| RQ-0145 | Mega-dogfood correctness closes false-positive success paths: URL QA subtracts only unchanged post-clear page-error residue and waits 150 ms for immediate post-load diagnostics, stale pre-existing artifacts and missing/stale recordings finalized by restart fail verification, aliased destinations (including dangling symlinks, full macOS/Windows Unicode folds, final short/long diff output flags, and same-call `outputPath` aliases) and active recording-path reuse through artifacts, path-bearing HAR stops, long/short or reordered explicit download waits, interspersed-global command forms, Electron cleanup output, or normalized output writes is rejected through an atomic process-wide, transcript-backed namespace/session reservation index independent of bounded manifest eviction; cross-branch close tombstones survive reload and each direct or ordered nested close retires exact identity at that lifecycle point while terminal closes clear attached/ref/page/route state, later lifecycle-proven browser launches—including failed post-close rows and `record stop`—can reactivate/rebuild it without stale pre-close `about:blank` recovery while bounded launch evidence survives failed-step presentation and transcript replay, explicitly non-launching diagnostics preserve the close, missing evidence stays conservatively active even on the first managed call, every successful direct/nested close clears wrapper trace/profiler ownership before later successful rows can rebuild it, and namespace-scoped `close --all` clears all matching managed/attached/page/ref/route/trace/recording ownership, only the newest pending recording path remains authoritative even across same-timestamp restart rows, legacy batch replay retires stale pending manifests only when ordered lifecycle leaves recording closed, while later browser reactivation plus recording start keeps the new reservation and malformed manifest rows are ignored, definitive direct/batch no-recording stop failures retire stale state at their ordered step, recording starts after nested close are rejected, pending rows coalesce into terminal batch outcomes without retaining an intermediate close-abandoned duplicate after a later saved stop, and any later same-session failure retains exact cleanup actions, same-page getter refs are refreshed, locator select resolves exact current native controls, no-movement scroll fails honestly, and script cleanup always attempts fail-closed close. | [`docs/TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details), [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md), `test/agent-browser.extension-input-modes.test.ts`, `test/agent-browser.extension-ref-guards.test.ts`, `test/agent-browser.presentation.test.ts`, `test/agent-browser.presentation-artifacts-batch.test.ts`, `test/agent-browser.recording-reservations.test.ts`, `test/agent-browser.extension-validation.test.ts`, `test/agent-browser.script.test.ts` |
| RQ-0146 | Upstream `agent-browser 0.34.0` rebaseline adds sticky `--pin-tab` / `--no-pin-tab` (`AGENT_BROWSER_PIN_TAB`) for shared CDP/auto-connect sessions, CDP target ids as tab refs, and `tab_gone` recovery data (`data.targetId`, optional `data.lastUrl`). The wrapper parses those flags as optional global booleans rather than launch-scoped, classifies `tab_gone` as `failureCategory: "tab-gone"` with `list-tabs-after-tab-gone` / `open-tab-after-tab-gone`, and shows `targetId` in `tab list` presentation. | [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#upstream-0340-rebaseline), [`docs/TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details), `test/agent-browser.results.test.ts`, `test/agent-browser.runtime.test.ts` |
| RQ-0147 | Native follow-ups preserve profiled and other launch-configured browser pages by omitting empty or retained compatibility launch arguments while the daemon is active; daemon inspection reapplies the retained compatibility user agent only when relaunch is required. Caller `--args` and `--user-agent` are launch-scoped, untrusted caller-owned/attached sessions cannot navigate to local files, and cancellation wins over policy validation before spawn. | [`docs/ARCHITECTURE.md`](ARCHITECTURE.md), [`docs/TOOL_CONTRACT.md`](TOOL_CONTRACT.md), `test/agent-browser.runtime.test.ts`, `test/agent-browser.process.test.ts`, `test/agent-browser.real-upstream-contract.test.ts` |

## Verification evidence

Re-run the gates below before each release; this table records what the closure audit exercised. Package 0.4.2 was refreshed on 2026-08-13 against upstream 0.34.0 and Pi 0.84.1. Default/pre-PR, package, real-upstream, deterministic dogfood, doctor, and isolated checkout tmux smoke passed. Configured-source lifecycle, packaged-Pi, startup profile, and the full Crabbox platform matrix were not rerun for this rebaseline.

| Gate | Evidence | Status |
| --- | --- | --- |
| Default local gate | `npm run verify` checks generated playbook drift, clean-builds generated `dist/`, runs `tsc --noEmit`, unit/fake tests, generated command-reference blocks, and live command-reference sampling. | **Current for 0.34.0 / package 0.4.2 / Pi 0.84.1:** pass on 2026-08-13; 768 tests passed, two opt-in real-upstream tests skipped, and build/typecheck/docs/live command-reference gates passed. |
| Pre-PR local gate | `npm run verify -- pre-pr` composes the default gate with package-content verification. Use before larger local handoffs or PR-ready claims when lifecycle/platform/live dogfood cost is not warranted. | **Current for 0.34.0 / package 0.4.2:** pass on 2026-08-13; the serial default suite and 130-file tarball verification completed in one composed run. |
| Real upstream contract | `npm run verify -- real-upstream` runs the localhost fixture matrix against the real installed `agent-browser` matching the baseline. | **Current for 0.34.0:** pass on 2026-08-13 (2/2 real-upstream tests). |
| Packaged Pi smoke | `npm run verify -- package-pi` validates package contents, loads the packaged `agent_browser` tool without requiring optional Brave config, and executes fake-upstream `--version`. | **Current for package 0.4.1 / Pi 0.84.1:** pass on 2026-08-10; the 130-file tarball includes the compiled script worker and canonical runtime target metadata. |
| Startup profile | `npm run verify -- startup-profile --samples <n>` clean-builds generated `dist/`, records direct package entrypoint import/factory timing in fresh Node processes, and writes `.artifacts/startup-profile/latest.json`. It must not launch Pi, tmux, mise, npm, browsers, or `agent-browser`; full Pi TUI ready-prompt profiling is intentionally excluded after it proved too invasive for routine verification. Run this opt-in evidence when package layout, the compiled entrypoint, top-level imports, schema registration, or prompt/config startup logic changes. | **Current for compiled 0.4.1 entrypoint:** pass on 2026-08-10 with five samples; median 67.7 ms and max 74.1 ms, below the 250 ms budget. |
| Deterministic dogfood smoke | `npm run verify -- dogfood` clean-builds, then `scripts/verify-agent-browser-dogfood.ts` drives the native wrapper against a loopback HTTP fixture through top-level `script` conditional aggregation/cleanup, `qa`, `semanticAction`, constrained `job`, screenshot artifact verification, and session close with the real `agent-browser` on `PATH`. | **Current for 0.34.0 / package 0.4.2 / Pi 0.84.1:** pass on 2026-08-13; QA, script branching/cleanup, fresh/current opens, semantic navigation, constrained-job screenshot verification, and final close all passed. |
| WebGPU and restore autosave | Live 0.31.2 feature probes validate the new upstream paths independently from ordinary browser dogfood. | **macOS:** `doctor --webgpu` passed Apple Metal render/readback and headless red-pixel screenshot checks; the official Hello Triangle sample exposed the Metal adapter and produced a verified non-black screenshot. **Ubuntu image:** `doctor --webgpu --headed --json` passed SwiftShader render/readback and red-pixel screenshot checks with the baked Vulkan/Mesa/Xvfb dependencies. **Restore autosave:** an idle headless page timer changed localStorage and the namespaced restore file contained the new value before close; test state was removed. Wrapper-owned headed launches default periodic autosave off to avoid upstream 0.33.2 visible temporary collector tabs; native close still saves, direct window close can lose newer state because headed browsers are exempt from idle shutdown, and explicit `AGENT_BROWSER_AUTOSAVE_INTERVAL_MS` opts in at daemon launch; its effective value persists across resume, and changing a running wrapper-owned headed daemon in either direction requires close plus a fresh launch. On 2026-08-06, a headed checkout dogfood run crossed `react.dev` → `example.com` → `react.dev`, idled past the autosave interval while recording, showed no temporary page switch in frame/contact-sheet review, and closed both sessions successfully; disposable evidence was removed. **Windows interactive desktop:** post-release validation on 2026-07-15 used a disposable clone of snapshot `57cc3c0d-7d7c-4a4c-9c57-8270d4174679`, a logged-in console session, `agent-browser 0.31.2`, and Edge 150. The headed doctor WebGPU render/readback subcheck passed in 0.99s and its decoded screenshot subcheck passed with `rgb(255,0,0)`; a separate `--webgpu --headed` launch opened the proof page and the Parallels console capture visibly recorded the red triangle (553,500 bright-red pixels; SHA-256 `f5a28f5336cbdfeb0ff557af9425458bddc6b266d3cc6b946de7b101a0b43288`). The full doctor remained nonzero only for the unrelated absence of a separately installed Chrome binary; the explicit Edge executable completed the launch and both WebGPU probes. Local evidence is under `.artifacts/windows-webgpu-interactive/20260715T150903Z/summary.json`; the disposable clone and temporary account were deleted afterward. |
| Android/Termux local bring-up | Non-release-blocking source validation uses Termux system Chromium through upstream's Linux `which chromium` discovery, the packaged Linux-musl arm64 CLI, real Pi managed-session smoke, deterministic dogfood, and the default unit/package gate. Electron desktop lifecycle is not applicable. | **Current local evidence:** Android 17 / arm64 Termux passed implicit, explicit, and namespaced fresh sessions, managed restore, script, QA, semantic action, job, click, eval/batch stdin, screenshot attachment, recording dependencies, and cleanup; Android is not yet a Crabbox release target. |
| Crabbox platform smoke | `npm run check:platform-smoke` syntax-checks the harness and cheap invariants. `npm run smoke:platform:ubuntu-image` builds the project-owned Linux image, `npm run smoke:platform:doctor` checks Crabbox 0.26.0+ and local target readiness, and `npm run smoke:platform:all` runs doctor first, then fast target-local `platform-build` (`npm run verify -- platform-target`, pack, clean Pi install) plus `browser-dogfood-smoke` on Crabbox `macos`, `ubuntu`, and `windows-native`; see [`platform-smoke.md`](platform-smoke.md). Target artifacts include Crabbox/provider/work-root metadata, and release review also checks provider-specific `crabbox list` commands for leftover leases/clones. | **Current for 0.33.2 / package 0.4.1 / Pi 0.84.1:** Ubuntu `platform-build` and `browser-dogfood-smoke` passed on 2026-08-09, and the second suite proved dependency reuse with `PLATFORM_NPM_CI_SKIPPED=1`. Full doctor remained setup-blocked by the macOS SSH probe and missing `prlctl` for native Windows. |
| `verify -- release` / `prepublishOnly` | `npm run verify -- release` chains the default gate with the configured-source lifecycle harness, packaged Pi smoke, and the release-blocking Crabbox platform matrix (`verifySteps` `release` in [`scripts/project.mjs`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/scripts/project.mjs)). `package.json` `prepublishOnly` runs that compose before `npm pack --dry-run` during `npm publish`. It intentionally omits standalone real-upstream and host-only dogfood modes—see [`RELEASE.md`](RELEASE.md#pre-release-checks). | **Package 0.4.1:** full composition was environment-blocked by isolated lifecycle credentials plus macOS/native-Windows provider setup. Default/pre-PR, package-Pi, startup, real-upstream, deterministic dogfood, Ubuntu platform, and interactive tmux gates passed independently. This release creates GitHub artifacts only; npm publishing is not authorized. |
| Configured-source lifecycle | `npm run verify -- lifecycle` (`scripts/verify-lifecycle.mjs`) drives `/reload`, closes and relaunches Pi with the same exact `--session-id`, checks the JSONL session header id, session continuity, slash-command sentinel tokens (`v1` before reload and `v2` after full relaunch because compiled JS package modules are process-cached), persisted spill reachability, and real Pi `tool_result` failure-patch semantics for a QA reclassification with a fake upstream on `PATH`. Default Pi model is `zai/glm-5.2`; default per-step wait is **180000 ms** (`DEFAULT_TIMEOUT_MS`); override model with `--model <id>` and waits with `--timeout-ms <ms>`. Passthrough flags in [`scripts/project.mjs`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/scripts/project.mjs): `--keep-artifacts`, `--model`, `--verbose`, and `--timeout-ms` plus a value (for example `npm run verify -- lifecycle --model openai-codex/gpt-5.5:minimal --keep-artifacts --verbose --timeout-ms 600000`). | **Pi 0.84.1 attempt on 2026-08-09:** environment-blocked before the first model response because the isolated Pi home had no `openai-codex` API key; no browser or extension assertion ran. The retained diagnostics were inspected and removed. |
| Quick isolated Pi smoke | `pi --approve --no-extensions --no-skills -e . --tools agent_browser` from trusted repo root; native `agent_browser` only. | **Current for 0.34.0 / package 0.4.2 / Pi 0.84.1:** isolated checkout tmux smoke passed on 2026-08-13; `--version`/open/`snapshot -i`/close against example.com reported `agent-browser 0.34.0`. |

Runtime floor note: package metadata keeps optional Pi core package peer ranges wildcard per installed Pi package docs, pins direct Pi validation dependencies to 0.84.0, and makes `pi --version` below 0.84.0 a setup failure through `pi-agent-browser-doctor` / `npm run doctor`. The 0.3.0 support-floor change intentionally includes no compatibility shims for older Pi releases.

## Baseline checklist by inventory section

| Baseline section | Baseline items | Documentation | Runtime handling | Test coverage | Validation status |
| --- | --- | --- | --- | --- | --- |
| Built-in skills | 16 canonical tokens from baseline section `skills`; see [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs) and generated [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#built-in-skills). | [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#built-in-skills), generated baseline block, README proof section, release docs. | `needsManagedSession` keeps read-only skills inspection sessionless while preserving thin upstream passthrough; upstream `@agent-browser/sandbox` remains external package guidance, not a bundled wrapper dependency. | Runtime and extension-validation skills/provider matrix; real-upstream inspection/skills group. | Supported. |
| Core page, element, navigation, and extraction commands | 82 canonical tokens from baseline section `core-commands`; see [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs) and generated [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#core-page-and-element-commands). | [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#core-page-and-element-commands), [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md), README quick start. | Thin passthrough with wrapper-owned JSON/session planning, ref guidance, artifact verification, page-change summaries, click-dispatch diagnostics, deterministic document scroll before wheel/no-op diagnostics, shorthand compilers, and redaction. | Real-upstream core matrix (including snapshot-ref select) plus fake core matrix for passthrough, ordering, diagnostics, and compiler validation. | Supported. Upstream semantics remain upstream-owned. |
| Sessions, state, tabs, frames, dialogs, and windows | 28 canonical tokens from baseline section `state-tabs-frames-dialogs`; see [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs) and generated [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#session-state-frames-dialogs-windows-and-inspection-commands). | [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#session-state-frames-dialogs-windows-and-inspection-commands), stateful workflow notes, [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details). | Stateful summaries/redaction including managed capability/path removal, filtered managed session/state listings, reserved managed live-session names, cross-checkout state-access guards, stable helper subprocess launch environment, state artifact handling, sessionless local command planning, managed-session restore, tab target pinning, active-target refresh after tab close, and close alias cleanup. | Extension tab/ref tests, real-upstream stable-id/label tab lifecycle, runtime session/resume tests, presentation redaction tests, lifecycle harness. | Supported. External profile/auth state remains operator-owned. |
| Network, storage, artifacts, diagnostics, and performance | 49 canonical tokens from baseline section `network-storage-artifacts-diagnostics`; see [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs) and generated [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#page-state-finding-mouse-settings-network-and-storage). | [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#page-state-finding-mouse-settings-network-and-storage), diagnostic sections, [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details). | Thin passthrough plus compact diagnostics, route-mock warnings, useful-but-redacted storage output, stream idempotency normalization, artifact metadata, missing-ffmpeg warnings, sensitive-data redaction, timeout bounds, and cleanup-pair guidance. | Fake non-core matrix and safe real-upstream coverage for network/HAR, diff, trace/profiler, console/errors/highlight, stream, vitals, and React missing-renderer. | Supported. Environment-sensitive operations need suitable local/browser state. |
| Batch, auth, confirmations, setup, dashboard, devices, and AI commands | 33 canonical tokens from baseline section `batch-auth-setup-ai`; see [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs) and generated [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#batch-auth-confirmations-sessions-chat-dashboard-devices-and-setup). | [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#batch-auth-confirmations-sessions-chat-dashboard-devices-and-setup), README security notes, release docs. | Native-tool batch stdin, generated `job`/`qa`/lookup batch plans, auth/confirmation redaction, sessionless local auth/setup/dashboard/doctor/plugin planning, plugin list/show JSON envelope normalization, bare-`mcp` validation with `mcp --help` preserved, timeout/cleanup guidance. | Parser/runtime plugin and MCP unit coverage; fake-upstream plugin list/show and MCP help/blocking coverage; real-upstream plugin list shape probe; structured input-mode tests. | Supported. Interactive side-effecting setup/auth/chat remains upstream-owned. `plugin` is local/sessionless; `mcp` is external-client-only except help; `auth login --credential-provider` resolves credentials via a plugin; `install --with-deps` failures remain upstream-owned. |
| Global flags, config, providers, policy, and environment | 145 canonical tokens from baseline section `options-and-env`; see [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs) and generated [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#important-global-flags-config-and-environment). | [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#important-global-flags-config-and-environment), README provider/setup notes, [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#sessionmode), architecture/runtime docs. | Runtime handles command discovery, value-flag prevalidation, launch-scoped flags, redacted echoes, fresh-session recovery hints, explicit sessions, provider/device launch-scoping, parent env forwarding with consistent managed idle-timeout/socket/operation-timeout overrides on top-level and helper subprocesses, subprocess completion, and package-owned Pi-scoped config for optional companion features. | Runtime tests for flags/planning/redaction/session behavior; process/ref tests for env consistency and stdio-linger completion; config/web-search/CLI tests; fake provider/specialized-skill matrix; package doctor. | Supported. Provider clouds, iOS/Appium, proxies, profiles, and credentials require external setup. |

## Follow-up decision after closure

The compact decision index lives at [`docs/support-notes.md`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/docs/support-notes.md). Keep this section as the active index of shipped follow-up areas and their canonical contracts.

| Area | Active contract | Decision index |
| --- | --- | --- |
| Native structured input modes (`script`, `job`, `qa`, `sourceLookup`, `networkSourceLookup`, `semanticAction`) | [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md), [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md) | [`docs/support-notes.md`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/docs/support-notes.md) |
| Electron lifecycle, manual CDP attach, desktop readiness, and tab/surface recovery | [`ELECTRON.md`](ELECTRON.md), [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#electron), [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#electron-desktop-apps) | [`docs/support-notes.md`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/docs/support-notes.md) |
| Ref lifecycle, click dispatch, selector recovery, rich inputs, and dense snapshots | [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details), [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#selector-strategy), README pitfalls | [`docs/support-notes.md`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/docs/support-notes.md) |
| Diagnostics, artifacts, QA/network classification, timeout recovery, scroll/combobox/recording guidance | [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details), [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md), [`RELEASE.md`](RELEASE.md) | [`docs/support-notes.md`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/docs/support-notes.md) |
| Package config and optional web search | [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#optional-companion-web-search), README optional package config, [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#optional-package-config-and-companion-web-search) | [`docs/support-notes.md`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/docs/support-notes.md) |