pi-agent-browser-native 0.2.19 → 0.2.21

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 0.2.21 - 2026-05-07
+
+### Fixed
+- fixed the published `pi-agent-browser-doctor` bin entrypoint so it runs when invoked through npm's `.bin` symlink
+
+## 0.2.20 - 2026-05-07
+
+### Compatibility
+- updated the extension's upstream capability baseline and command reference for `agent-browser` `0.27.0`
+- documented and passed through the new React introspection commands (`react tree`, `react inspect`, `react renders`, `react suspense`), Web Vitals (`vitals`), SPA navigation (`pushstate`), init-script flags (`--init-script`, `--enable react-devtools`), `network route --resource-type`, and `cookies set --curl`
+- treat `--init-script` and `--enable` as launch-scoped flags in managed-session planning so agents get the same clear `sessionMode: "fresh"` recovery path as profile/state/CDP launches
+
 ## 0.2.19 - 2026-05-03
 
 ### Fixed

package/README.md

@@ -120,7 +120,7 @@ The native tool exposed to the agent is named `agent_browser`.
 The primary session control parameter is `sessionMode`:
 
 - `"auto"` (default) reuses the extension-managed `pi`-scoped session when possible
-- `"fresh"` switches that managed session to a fresh upstream launch so launch-scoped flags like `--profile`, `--session-name`, `--cdp`, `--state`, and `--auto-connect` apply and later auto calls follow the new browser
+- `"fresh"` switches that managed session to a fresh upstream launch so launch-scoped flags like `--profile`, `--session-name`, `--cdp`, `--state`, `--auto-connect`, `--init-script`, and `--enable` apply and later auto calls follow the new browser
 
 ## Agent quick start
 
@@ -166,7 +166,7 @@ Download a file from a known link/control directly:
 { "args": ["download", "@e5", "/tmp/report.pdf"] }
 ```
 
-For dashboards that start an export asynchronously after a click or navigation, click first and then wait for the download. The wrapper reports `Download completed: /tmp/report.csv` and exposes upstream-reported `details.savedFilePath` plus `details.savedFile` for the `wait` result; with upstream `agent-browser 0.26.0`, confirm `details.artifacts[].exists` before relying on a requested `wait --download <path>` file being present on disk (tracked upstream at [vercel-labs/agent-browser#1300](https://github.com/vercel-labs/agent-browser/issues/1300)):
+For dashboards that start an export asynchronously after a click or navigation, click first and then wait for the download. The wrapper reports `Download completed: /tmp/report.csv` and exposes upstream-reported `details.savedFilePath` plus `details.savedFile` for the `wait` result; with upstream `agent-browser 0.27.0`, confirm `details.artifacts[].exists` before relying on a requested `wait --download <path>` file being present on disk (tracked upstream at [vercel-labs/agent-browser#1300](https://github.com/vercel-labs/agent-browser/issues/1300)):
 
 ```json
 { "args": ["click", "@export"] }
@@ -187,6 +187,28 @@ Start a fresh profiled launch after you already used the implicit session:
 
 After a successful unnamed fresh launch, later `sessionMode: "auto"` calls follow that new browser automatically.
 
+React and SPA tooling added upstream in `agent-browser` v0.27.0 is passed through as native tool calls. Launch React introspection with the DevTools hook before first navigation, then use the `react` commands; `vitals` and `pushstate` work as regular command tokens:
+
+```json
+{ "args": ["open", "--enable", "react-devtools", "https://example.com"], "sessionMode": "fresh" }
+{ "args": ["react", "tree"] }
+{ "args": ["react", "inspect", "<fiberId>"] }
+{ "args": ["react", "renders", "start"] }
+{ "args": ["react", "renders", "stop"] }
+{ "args": ["react", "suspense", "--only-dynamic"] }
+{ "args": ["vitals", "https://example.com", "--json"] }
+{ "args": ["pushstate", "/dashboard"] }
+```
+
+For first-navigation setup, launch a fresh blank page before staging routes, cookies, or scripts:
+
+```json
+{ "args": ["open"], "sessionMode": "fresh" }
+{ "args": ["network", "route", "**/*.js", "--abort", "--resource-type", "script"] }
+{ "args": ["cookies", "set", "--curl", "/path/to/cookies.txt", "--domain", "example.com"] }
+{ "args": ["navigate", "https://example.com"] }
+```
+
 Name a new upstream session explicitly when you want to keep reusing it yourself:
 
 ```json
@@ -262,10 +284,11 @@ These calls return plain text and stay stateless: the extension does not inject
 
 Current cautions:
 - passing `--profile` is an explicit upstream choice; this extension does not add its own profile-cloning or isolation layer
-- launch-scoped flags like `--profile`, `--session-name`, `--cdp`, `--state`, and `--auto-connect` are for the first command that launches a session; if the implicit session is already active, retry that call with `sessionMode: "fresh"` or provide an explicit `--session ...` for the new launch
+- launch-scoped flags like `--profile`, `--session-name`, `--cdp`, `--state`, `--auto-connect`, `--init-script`, and `--enable` are for the first command that launches a session; if the implicit session is already active, retry that call with `sessionMode: "fresh"` or provide an explicit `--session ...` for the new launch
 - implicit `piab-*` sessions are extension-managed convenience sessions; they stay alive across `/reload` and resumable session transitions so later default calls can keep following the active managed browser on `/reload` or `/resume`, close when the originating `pi` process quits, rely on the configured idle timeout only as an abnormal-exit backstop, store persisted-session large snapshot spill files under a private session-scoped artifact directory with a bounded per-session budget so `details.fullOutputPath` and metadata-only `details.artifactManifest` survive reload/resume without unbounded growth, and still clean up process-private temp spill artifacts on shutdown
 - `sessionMode: "fresh"` without an explicit `--session` rotates that extension-managed session to the new browser so later auto calls keep using it
 - for local Unix launches, the wrapper uses a short private socket directory under `/tmp` so extension-generated session names do not trip upstream Unix socket-path limits in longer cwd/session-name combinations
+- wrapper-spawned commands clamp `AGENT_BROWSER_DEFAULT_TIMEOUT` to 25 seconds and use a 28-second process watchdog so a single upstream CLI call does not cross the upstream 30-second IPC read-timeout/retry path; split intentionally long waits into shorter tool calls
 - for direct headless local Chrome launches to `chat.com`, `chatgpt.com`, and `chat.openai.com`, the extension injects a normal Chrome user agent when the caller did not explicitly provide `--user-agent`; this keeps the default headless workflow usable without forcing `--headed` or `--auto-connect`
 <!-- agent-browser-playbook:start wrapper-tab-recovery -->
 <!-- Generated from extensions/agent-browser/lib/playbook.ts. Run `npm run docs -- playbook write` to update. -->

package/docs/ARCHITECTURE.md

@@ -98,6 +98,7 @@ Practical policy:
 - once the wrapper knows which tab the agent is operating on, later active-tab commands may synthesize a tiny upstream `batch` that re-selects that tab and then runs the requested command in the same upstream invocation; this stays thin while avoiding reconnect-time drift on profile-restored sessions
 - after a successful command on a known tab target, the wrapper may best-effort restore that same target again if restored/background tabs steal focus after the command returns
 - for local Unix launches, set a short private socket directory so extension-generated session names do not fail on the upstream Unix socket-path length limit
+- keep wrapper-spawned upstream CLI calls inside the upstream IPC budget by clamping `AGENT_BROWSER_DEFAULT_TIMEOUT` to 25 seconds and stopping a stuck child process before the upstream 30-second read-timeout retry loop begins
 
 This is primarily about ownership clarity and avoiding surprise, not adding a heavy safety wrapper. If the extension invented the session, the extension should own its lifecycle without breaking reload/resume semantics. If the caller explicitly chose the upstream session model, the extension should stay out of the way.
 
@@ -106,7 +107,7 @@ This is primarily about ownership clarity and avoiding surprise, not adding a he
 `agent-browser` startup flags are sticky once a session is already running.
 The extension should surface that clearly and avoid hidden restart behavior in v1.
 
-That means explicit startup-scoping flags like `--profile`, `--session-name`, and `--cdp` should remain explicit upstream choices instead of being wrapped in extra hidden restart or cloning logic.
+That means explicit startup-scoping flags like `--profile`, `--session-name`, `--cdp`, `--state`, `--auto-connect`, `--init-script`, and `--enable` should remain explicit upstream choices instead of being wrapped in extra hidden restart or cloning logic.
 
 The wrapper may still apply narrow compatibility normalizations when observed behavior justifies them and the result remains thin, local, and opt-out. For example, if a specific site starts rejecting the default local headless Chrome user agent while the same flow works with a normal Chrome UA, the extension may inject a domain-specific fallback UA only when the caller did not already choose `--user-agent`, `--headed`, `--cdp`, `--auto-connect`, or a provider-backed launch.
 

package/docs/COMMAND_REFERENCE.md

@@ -16,7 +16,7 @@ This project intentionally blocks normal `agent-browser` bash usage in most agen
 
 <!-- agent-browser-capability-baseline:start upstream-baseline -->
 <!-- Generated from scripts/agent-browser-capability-baseline.mjs. Run `npm run docs -- command-reference write` to update. Do not edit manually. -->
-This reference is baselined to the locally installed `agent-browser 0.26.0` command/help surface. Upstream `agent-browser` remains the source of truth for command semantics; this file is the local fallback for Pi agent sessions where direct binary help is blocked or discouraged.
+This reference is baselined to the locally installed `agent-browser 0.27.0` command/help surface. Upstream `agent-browser` remains the source of truth for command semantics; this file is the local fallback for Pi agent sessions where direct binary help is blocked or discouraged.
 
 The lightweight drift check is `npm run verify -- command-reference`. Run it whenever the installed upstream `agent-browser` version changes or this reference is edited.
 <!-- agent-browser-capability-baseline:end upstream-baseline -->
@@ -37,7 +37,7 @@ Tool parameters:
 - `stdin`: only for `batch` and `eval --stdin`; other command/stdin combinations are rejected before `agent-browser` is launched.
 - `sessionMode`:
   - `"auto"` reuses the extension-managed session when possible.
-  - `"fresh"` rotates that managed session to a fresh upstream launch so launch-scoped flags like `--profile`, `--session-name`, `--cdp`, `--state`, or `--auto-connect` apply.
+  - `"fresh"` rotates that managed session to a fresh upstream launch so launch-scoped flags like `--profile`, `--session-name`, `--cdp`, `--state`, `--auto-connect`, `--init-script`, or `--enable` apply.
 
 ## Recommended workflow
 
@@ -52,6 +52,35 @@ Keep routine browser work simple: open a page, inspect it with `snapshot -i`, in
 { "args": ["snapshot", "-i"] }
 ```
 
+### React, SPA, and Web Vitals flows
+
+React introspection requires the React DevTools init hook to be installed before the page's first JavaScript runs. Launch or relaunch that browser session with `--enable react-devtools`; if the implicit session is already active, use `sessionMode: "fresh"`.
+
+```json
+{ "args": ["open", "--enable", "react-devtools", "https://example.com"], "sessionMode": "fresh" }
+{ "args": ["react", "tree"] }
+{ "args": ["react", "inspect", "<fiberId>"] }
+{ "args": ["react", "renders", "start"] }
+{ "args": ["react", "renders", "stop"] }
+{ "args": ["react", "suspense", "--only-dynamic"] }
+```
+
+Use `vitals [url]` for Core Web Vitals plus React hydration timing when available, and `pushstate <url>` for client-side SPA navigation without a full reload:
+
+```json
+{ "args": ["vitals", "https://example.com", "--json"] }
+{ "args": ["pushstate", "/dashboard?tab=settings"] }
+```
+
+For first-navigation setup, start on `about:blank`, then stage routes, cookies, or init scripts before navigating. The relevant v0.27.0 surfaces are `network route <url> [--abort|--body <json>] [--resource-type <csv>]` and `cookies set --curl <file>`:
+
+```json
+{ "args": ["open"], "sessionMode": "fresh" }
+{ "args": ["network", "route", "**/*.js", "--abort", "--resource-type", "script"] }
+{ "args": ["cookies", "set", "--curl", "/path/to/cookies.txt", "--domain", "example.com"] }
+{ "args": ["navigate", "https://example.com"] }
+```
+
 ### Selector strategy
 
 Prefer targets in this order:
@@ -115,7 +144,7 @@ For one-call flows, put the click and wait in `batch`; the wait step keeps the s
 { "args": ["batch"], "stdin": "[[\"click\",\"@export\"],[\"wait\",\"--download\",\"/tmp/report.csv\"]]" }
 ```
 
-A successful wait-based download renders a readable summary such as `Download completed: /tmp/report.csv` and exposes top-level `details.savedFilePath` plus `details.savedFile` for non-batch calls. With the current upstream `agent-browser 0.26.0`, `wait --download <path>` may report the requested path before this environment can verify that the file was persisted there. Treat `details.savedFilePath` as upstream-reported metadata unless `details.artifacts[].exists` is true. Upstream tracking: [vercel-labs/agent-browser#1300](https://github.com/vercel-labs/agent-browser/issues/1300).
+A successful wait-based download renders a readable summary such as `Download completed: /tmp/report.csv` and exposes top-level `details.savedFilePath` plus `details.savedFile` for non-batch calls. With the current upstream `agent-browser 0.27.0`, `wait --download <path>` may report the requested path before this environment can verify that the file was persisted there. Treat `details.savedFilePath` as upstream-reported metadata unless `details.artifacts[].exists` is true. Upstream tracking: [vercel-labs/agent-browser#1300](https://github.com/vercel-labs/agent-browser/issues/1300).
 
 ### Download, screenshot, and PDF files
 
@@ -267,8 +296,8 @@ These calls return plain text and stay stateless: the extension does not inject
 | `find <locator> <value> <action> [text]` | Locator types include `role`, `text`, `label`, `placeholder`, `alt`, `title`, `testid`, `first`, `last`, and `nth`. |
 | `mouse <action> [args]` | `move <x> <y>`, `down [btn]`, `up [btn]`, `wheel <dy> [dx]`. |
 | `set <setting> [value]` | `viewport <w> <h>`, `device <name>`, `geo <lat> <lng>`, `offline [on|off]`, `headers <json>`, `credentials <user> <pass>`, `media [dark|light] [reduced-motion]`. |
-| `network <action>` | `route <url> [--abort|--body <json>]`, `unroute [url]`, `requests [--clear] [--filter <pattern>]`, `request <requestId>`, `har <start|stop> [path]`. |
-| `cookies [get|set|clear]` | Manage cookies. `set` supports `--url`, `--domain`, `--path`, `--httpOnly`, `--secure`, `--sameSite`, and `--expires`. |
+| `network <action>` | `route <url> [--abort|--body <json>] [--resource-type <csv>]`, `unroute [url]`, `requests [--clear] [--filter <pattern>]`, `request <requestId>`, `har <start|stop> [path]`. `--resource-type` filters intercepted requests by CDP resource type, such as `script`, `image`, `font`, `xhr`, or `fetch`. |
+| `cookies [get|set|clear]` | Manage cookies. `set` supports `--url`, `--domain`, `--path`, `--httpOnly`, `--secure`, `--sameSite`, `--expires`, and `--curl <file>` for JSON, cURL, or bare Cookie-header bulk imports. |
 | `storage <local|session>` | Manage web storage. |
 
 ### Tabs
@@ -301,13 +330,13 @@ Stable tab ids look like `t1`, `t2`, and `t3`. Optional user labels such as `doc
 | Mode | Purpose |
 | --- | --- |
 | `wait <selector>` | Wait for an element to appear. |
-| `wait <ms>` | Wait for a fixed number of milliseconds. |
+| `wait <ms>` | Wait for a fixed number of milliseconds. In the native Pi wrapper, keep each fixed wait at `25000` ms or less and split longer waits into multiple tool calls. |
 | `wait --url <pattern>` | Wait for the URL to match a pattern. |
 | `wait --load <state>` | Wait for load state: `load`, `domcontentloaded`, or `networkidle`. |
 | `wait --fn <expression>` | Wait for a JavaScript expression to become truthy. |
 | `wait --text <text>` | Wait for text to appear on the page. |
 | `wait --download [path]` | Wait for a download started by a previous action and optionally save it to `path`; successful wrapper results include upstream-reported `savedFilePath`/`savedFile`, while `details.artifacts[].exists` is the wrapper's on-disk verification signal. |
-| `wait --download [path] --timeout <ms>` | Set download-start timeout in milliseconds. |
+| `wait --download [path] --timeout <ms>` | Set download-start timeout in milliseconds. In the native Pi wrapper, use `25000` ms or less per call to stay under the upstream CLI IPC budget. |
 | `wait <selector> --state hidden` | Wait for an element to become hidden. |
 | `wait <selector> --state detached` | Wait for an element to detach. |
 
@@ -330,8 +359,16 @@ Stable tab ids look like `t1`, `t2`, and `t3`. Optional user labels such as `doc
 | `stream enable [--port <n>]` | Start runtime WebSocket streaming for this session. |
 | `stream disable` | Stop runtime WebSocket streaming. |
 | `stream status` | Show streaming status and active port. |
+| `react tree` | Print the full React component tree. Requires the page to have been launched with `--enable react-devtools`. |
+| `react inspect <id>` | Inspect one React fiber's props, hooks, state, and source. |
+| `react renders start` | Start recording React render activity. |
+| `react renders stop [--json]` | Stop render recording and print mount/re-render counts and changed details. |
+| `react suspense [--only-dynamic] [--json]` | Classify Suspense boundaries with grouped root-cause recommendations. |
+| `vitals [url] [--json]` | Report Core Web Vitals: LCP, CLS, TTFB, FCP, INP, plus React hydration timing when available. |
+| `pushstate <url>` | Perform SPA client-side navigation; detects Next.js router pushes and falls back to history navigation events. |
+| `removeinitscript <id>` | Remove an init script registered through upstream init-script mechanisms. |
 
-When these diagnostic commands are invoked through the native `agent_browser` tool, structured console and page-error outputs render as compact summaries with counts and key fields. Large outputs are previewed with a `Full output path:` spill file instead of dumping the entire payload into context.
+When these diagnostic commands are invoked through the native `agent_browser` tool, structured console, page-error, React, Web Vitals, and SPA outputs render as compact summaries when possible, with large outputs previewed and spilled instead of dumped into context. Large outputs are previewed with a `Full output path:` spill file instead of dumping the entire payload into context.
 
 `trace` and `profiler` share upstream Chrome tracing machinery. Do not run them at the same time. The wrapper tracks owner state it observes in the current Pi session and blocks conflicting starts/stops with "wrapper believes ..." wording because direct upstream CLI use or browser restarts can desynchronize wrapper-local state.
 
@@ -372,6 +409,8 @@ When these commands are invoked through the native `agent_browser` tool, structu
 - `--state <path>`: load saved auth state from JSON. Environment: `AGENT_BROWSER_STATE`.
 - `--auto-connect`: connect to a running Chrome to reuse auth state. Environment: `AGENT_BROWSER_AUTO_CONNECT`.
 - `--headers <json>`: apply HTTP headers scoped to the opened URL's origin.
+- `--init-script <path>`: register a script before first navigation; repeatable. Environment: `AGENT_BROWSER_INIT_SCRIPTS`.
+- `--enable <feature>`: enable built-in init scripts such as `react-devtools`; repeatable or comma-separated. Environment: `AGENT_BROWSER_ENABLE`.
 
 ### Browser launch and runtime flags
 
@@ -427,7 +466,7 @@ Other useful environment variables include `AGENT_BROWSER_DEFAULT_TIMEOUT`, `AGE
 ## Wrapper-specific behavior worth knowing
 
 - The extension may keep following one implicit managed session across later tool calls.
-- If launch-scoped flags like `--profile`, `--session-name`, `--cdp`, `--state`, or `--auto-connect` would be ignored because that implicit session is already active, retry with `sessionMode: "fresh"`.
+- If launch-scoped flags like `--profile`, `--session-name`, `--cdp`, `--state`, `--auto-connect`, `--init-script`, or `--enable` would be ignored because that implicit session is already active, retry with `sessionMode: "fresh"`.
 <!-- agent-browser-playbook:start wrapper-tab-recovery -->
 <!-- Generated from extensions/agent-browser/lib/playbook.ts. Run `npm run docs -- playbook write` to update. -->
 - After launch-scoped open/goto/navigate calls that can restore existing tabs (for example --profile, --session-name, or --state), agent_browser best-effort re-selects the tab whose URL matches the returned page when restored tabs steal focus during launch.
@@ -435,6 +474,7 @@ Other useful environment variables include `AGENT_BROWSER_DEFAULT_TIMEOUT`, `AGE
 - After a successful command on a known target tab, agent_browser also best-effort restores that intended tab if a restored/background tab steals focus after the command completes.
 - If a known session target unexpectedly reports about:blank, agent_browser preserves the prior intended target, best-effort re-selects it when it still exists, and reports exact recovery guidance when it cannot be re-selected.
 <!-- agent-browser-playbook:end wrapper-tab-recovery -->
+- Wrapper-spawned commands clamp `AGENT_BROWSER_DEFAULT_TIMEOUT` to 25 seconds and use a 28-second child-process watchdog so one upstream CLI call does not cross the upstream 30-second IPC read-timeout/retry path.
 - Oversized snapshots and oversized generic outputs may be compacted in tool content, with the full raw 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 are separately bounded by `PI_AGENT_BROWSER_SESSION_ARTIFACT_MAX_BYTES` (default 32 MiB).
 - The wrapper keeps `--help` and `--version` stateless so they do not consume the implicit managed-session slot.
 
@@ -443,7 +483,7 @@ Other useful environment variables include `AGENT_BROWSER_DEFAULT_TIMEOUT`, `AGE
 <!-- agent-browser-capability-baseline:start capability-token-baseline -->
 <!-- Generated from scripts/agent-browser-capability-baseline.mjs. Run `npm run docs -- command-reference write` to update. Do not edit manually. -->
 <details>
-<summary>Generated verifier capability baseline for agent-browser 0.26.0</summary>
+<summary>Generated verifier capability baseline for agent-browser 0.27.0</summary>
 
 This generated block is review data for maintainers. The human-authored reference sections above remain the readable command guide.
 
@@ -476,6 +516,18 @@ This generated block is review data for maintainers. The human-authored referenc
 - root help: `inspect`
 - root help: `clipboard <op> [text]`
 - root help: `stream enable [--port <n>]`
+- root help: `react tree`
+- root help: `react inspect <id>`
+- root help: `react renders start`
+- root help: `react renders stop [--json]`
+- root help: `react suspense [--only-dynamic] [--json]`
+- root help: `vitals [url] [--json]`
+- root help: `pushstate <url>`
+- root help: `removeinitscript <id>`
+- root help: `--init-script <path>`
+- root help: `--enable <feature>`
+- root help: `--resource-type <csv>`
+- root help: `cookies set --curl <file>`
 - root help: `auth save <name>`
 - root help: `confirm <id>`
 - root help: `deny <id>`

package/docs/RELEASE.md

@@ -107,7 +107,7 @@ The default `npm test` and `npm run verify` paths use fast deterministic tests a
 npm run verify -- real-upstream
 ```
 
-This suite requires the installed `agent-browser --version` to exactly match `scripts/agent-browser-capability-baseline.mjs`. It serves fixture pages from localhost and validates real runtime output shapes for `--version`, `open`, `eval --stdin`, `snapshot -i`, `batch` stdin, `wait --download` metadata, wrapper artifact existence reporting for the requested wait-download path, and implicit managed-session reuse. The current upstream `wait --download <path>` saveAs persistence limitation is tracked at [vercel-labs/agent-browser#1300](https://github.com/vercel-labs/agent-browser/issues/1300); until it is fixed, release validation must treat `details.savedFilePath` as upstream-reported metadata and use `details.artifacts[].exists` as the filesystem truth. If the suite fails because JSON/detail keys drifted, update the wrapper behavior or refresh `test/fixtures/agent-browser-real-output-shapes.json` together with the presentation work that consumes those shapes.
+This suite requires the installed `agent-browser --version` to exactly match `scripts/agent-browser-capability-baseline.mjs`. It serves fixture pages from localhost and validates real runtime output shapes for `--version`, `open`, `eval --stdin`, `snapshot -i`, `batch` stdin, `wait --download` metadata, wrapper artifact existence reporting for the requested wait-download path, and implicit managed-session reuse. The current upstream `agent-browser 0.27.0` `wait --download <path>` saveAs persistence limitation is tracked at [vercel-labs/agent-browser#1300](https://github.com/vercel-labs/agent-browser/issues/1300); until it is fixed, release validation must treat `details.savedFilePath` as upstream-reported metadata and use `details.artifacts[].exists` as the filesystem truth. If the suite fails because JSON/detail keys drifted, update the wrapper behavior or refresh `test/fixtures/agent-browser-real-output-shapes.json` together with the presentation work that consumes those shapes.
 
 Example smoke prompt:
 

package/docs/TOOL_CONTRACT.md

@@ -34,8 +34,10 @@ The tool also needs an operating playbook, not just a capability list. The model
 - Do not assume Playwright selector dialects such as text=Close or button:has-text('Close') are supported wrapper syntax unless current upstream agent-browser behavior has been verified.
 - For authenticated or user-specific content like feeds, inboxes, dashboards, and accounts, prefer --profile Default on the first browser call and let the implicit session carry continuity. Use --auto-connect only if profile-based reuse is unavailable or the task is specifically about attaching to a running debug-enabled browser.
 - Do not invent fixed explicit session names for routine tasks. Use the implicit session unless you truly need multiple isolated browser sessions in the same conversation.
-- When using --profile, --session-name, --cdp, --state, or --auto-connect, put them on the first command for that session. If you intentionally use an explicit --session, keep using that same explicit session for follow-ups.
-- If you already used the implicit session and now need launch-scoped flags like --profile, --session-name, --cdp, --state, or --auto-connect, retry with sessionMode set to fresh or pass an explicit --session for the new launch. After a successful unnamed fresh launch, later auto calls follow that new session.
+- When using --profile, --session-name, --cdp, --state, --auto-connect, --init-script, or --enable, put them on the first command for that session. If you intentionally use an explicit --session, keep using that same explicit session for follow-ups.
+- If you already used the implicit session and now need launch-scoped flags like --profile, --session-name, --cdp, --state, --auto-connect, --init-script, or --enable, retry with sessionMode set to fresh or pass an explicit --session for the new launch. After a successful unnamed fresh launch, later auto calls follow that new session.
+- For React introspection, launch the page with --enable react-devtools before first navigation, then use react tree, react inspect <fiberId>, react renders start/stop, or react suspense; use vitals [url] for Core Web Vitals and hydration timing, and pushstate <url> for client-side SPA navigation.
+- For first-navigation setup, use open without a URL plus network route --resource-type <csv>, cookies set --curl <file>, or --init-script/--enable before navigate/opening the target page.
 - If a session lands on the wrong page or tab, an interaction changes origin unexpectedly, or an open call returns blocked, blank, or otherwise unexpected results, use tab list / tab <tab-id-or-label> / snapshot -i to recover state before retrying different URLs or fallback strategies. Only use wait with an explicit argument like milliseconds, --load <state>, --url <matcher>, --fn <js>, or --text <matcher>.
 - For feed, timeline, or inbox reading tasks, focus on the main timeline/list region and read the first item there rather than unrelated composer or sidebar content.
 - For read-only browsing tasks, prefer extracting the answer from the current snapshot, structured ref labels, or eval --stdin on the current page before navigating away. Only click into media viewers, detail routes, or new pages when the current view does not contain the needed information.
@@ -98,7 +100,7 @@ Examples:
 Behavior:
 - if `args` already include `--session`, upstream session choice wins
 - `"auto"` prepends the current extension-managed active session when appropriate
-- `"fresh"` rotates that managed session to a fresh upstream launch so startup-scoped flags like `--profile`, `--session-name`, or `--cdp` apply and later default calls follow the new browser
+- `"fresh"` rotates that managed session to a fresh upstream launch so startup-scoped flags like `--profile`, `--session-name`, `--cdp`, `--state`, `--auto-connect`, `--init-script`, or `--enable` apply and later default calls follow the new browser
 
 Recommended use:
 - use `"auto"` for the common browse/snapshot/click flow inside one `pi` session
@@ -230,8 +232,9 @@ If `agent-browser` is not on `PATH`, fail with a message that:
 - If a known session target unexpectedly reports about:blank, agent_browser preserves the prior intended target, best-effort re-selects it when it still exists, and reports exact recovery guidance when it cannot be re-selected.
 <!-- agent-browser-playbook:end wrapper-tab-recovery -->
 - on local Unix launches, set a short private socket directory for wrapper-spawned `agent-browser` processes so extension-generated session names do not fail the upstream Unix socket-path length limit in longer cwd/session-name combinations
+- keep wrapper-spawned commands below the upstream CLI IPC read-timeout budget by clamping `AGENT_BROWSER_DEFAULT_TIMEOUT` to 25 seconds and stopping a stuck child process before the upstream 30-second retry path begins
 - treat successful plain-text inspection commands like `--help` and `--version` as stateless: do not inject the implicit managed session and do not let those calls claim the managed-session slot
-- if startup-scoped flags like `--profile`, `--session-name`, or `--cdp` are supplied after the implicit session is already active while `sessionMode` is `"auto"`, return a validation error with a structured recovery hint that recommends `sessionMode: "fresh"`
+- if startup-scoped flags like `--profile`, `--session-name`, `--cdp`, `--state`, `--auto-connect`, `--init-script`, or `--enable` are supplied after the implicit session is already active while `sessionMode` is `"auto"`, return a validation error with a structured recovery hint that recommends `sessionMode: "fresh"`
 - for direct headless local Chrome launches to `chat.com` / `chatgpt.com` / `chat.openai.com`, allow a narrow compatibility fallback that injects a normal Chrome `--user-agent` only when the caller did not explicitly provide one and did not choose `--headed`, `--cdp`, `--auto-connect`, or a provider-backed launch
 
 ## Non-goals

package/extensions/agent-browser/index.ts

@@ -17,7 +17,7 @@ import {
 	PROJECT_RULE_PROMPT,
 	buildToolPromptGuidelines,
 } from "./lib/playbook.js";
-import { runAgentBrowserProcess } from "./lib/process.js";
+import { SAFE_AGENT_BROWSER_OPERATION_TIMEOUT_MS, runAgentBrowserProcess } from "./lib/process.js";
 import {
 	buildToolPresentation,
 	getAgentBrowserErrorText,
@@ -77,7 +77,7 @@ const AGENT_BROWSER_PARAMS = Type.Object({
 	sessionMode: Type.Optional(
 		StringEnum(["auto", "fresh"] as const, {
 			description:
-				"Session handling mode. `auto` reuses the extension-managed pi-scoped session when possible. `fresh` switches that managed session to a fresh upstream launch so launch-scoped flags like --profile, --session-name, --cdp, --state, or --auto-connect apply and later auto calls follow the new browser.",
+				"Session handling mode. `auto` reuses the extension-managed pi-scoped session when possible. `fresh` switches that managed session to a fresh upstream launch so launch-scoped flags like --profile, --session-name, --cdp, --state, --auto-connect, --init-script, or --enable apply and later auto calls follow the new browser.",
 			default: DEFAULT_SESSION_MODE,
 		}),
 	),
@@ -452,6 +452,73 @@ async function prepareBatchScreenshotPaths(args: string[], stdin: string | undef
 		: undefined;
 }
 
+function parseMillisecondsToken(token: string | undefined): number | undefined {
+	if (token === undefined || !/^\d+$/.test(token)) {
+		return undefined;
+	}
+	const parsed = Number(token);
+	return Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+
+function findWaitTimeoutMs(commandTokens: string[]): { timeoutMs: number; source: string } | undefined {
+	if (commandTokens[0] !== "wait") {
+		return undefined;
+	}
+	for (let index = 1; index < commandTokens.length; index += 1) {
+		const token = commandTokens[index];
+		if (token === "--timeout") {
+			const timeoutMs = parseMillisecondsToken(commandTokens[index + 1]);
+			return timeoutMs === undefined ? undefined : { source: "wait --timeout", timeoutMs };
+		}
+		if (token.startsWith("--timeout=")) {
+			const timeoutMs = parseMillisecondsToken(token.slice("--timeout=".length));
+			return timeoutMs === undefined ? undefined : { source: "wait --timeout", timeoutMs };
+		}
+		if (!token.startsWith("-")) {
+			const timeoutMs = parseMillisecondsToken(token);
+			if (timeoutMs !== undefined) {
+				return { source: "wait", timeoutMs };
+			}
+		}
+	}
+	return undefined;
+}
+
+function buildIpcUnsafeWaitError(source: string, timeoutMs: number, batchStep?: number): string {
+	const location = batchStep === undefined ? source : `batch step ${batchStep + 1} (${source})`;
+	return `${location} requests ${timeoutMs}ms, but upstream agent-browser CLI calls must stay under its 30s IPC read timeout. Use ${SAFE_AGENT_BROWSER_OPERATION_TIMEOUT_MS}ms or less per wait, split long waits into multiple tool calls, or use a page-specific shorter condition.`;
+}
+
+function validateWaitIpcTimeoutContract(commandTokens: string[], stdin: string | undefined): string | undefined {
+	const directWaitTimeout = findWaitTimeoutMs(commandTokens);
+	if (directWaitTimeout && directWaitTimeout.timeoutMs > SAFE_AGENT_BROWSER_OPERATION_TIMEOUT_MS) {
+		return buildIpcUnsafeWaitError(directWaitTimeout.source, directWaitTimeout.timeoutMs);
+	}
+	if (commandTokens[0] !== "batch" || stdin === undefined) {
+		return undefined;
+	}
+	let steps: unknown;
+	try {
+		steps = JSON.parse(stdin);
+	} catch {
+		return undefined;
+	}
+	if (!Array.isArray(steps)) {
+		return undefined;
+	}
+	for (let index = 0; index < steps.length; index += 1) {
+		const step = steps[index];
+		if (!Array.isArray(step) || !step.every((item) => typeof item === "string")) {
+			continue;
+		}
+		const waitTimeout = findWaitTimeoutMs(step);
+		if (waitTimeout && waitTimeout.timeoutMs > SAFE_AGENT_BROWSER_OPERATION_TIMEOUT_MS) {
+			return buildIpcUnsafeWaitError(waitTimeout.source, waitTimeout.timeoutMs, index);
+		}
+	}
+	return undefined;
+}
+
 async function prepareAgentBrowserArgs(args: string[], stdin: string | undefined, cwd: string): Promise<PreparedAgentBrowserArgs> {
 	const preparedBatch = await prepareBatchScreenshotPaths(args, stdin, cwd);
 	if (preparedBatch) {
@@ -1520,6 +1587,22 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 						isError: true,
 					};
 				}
+				const waitIpcTimeoutError = validateWaitIpcTimeoutContract(commandTokens, params.stdin);
+				if (waitIpcTimeoutError) {
+					return {
+						content: [{ type: "text", text: waitIpcTimeoutError }],
+						details: {
+							args: redactedArgs,
+							command: executionPlan.commandInfo.command,
+							compatibilityWorkaround,
+							effectiveArgs: redactedEffectiveArgs,
+							sessionMode,
+							validationError: waitIpcTimeoutError,
+							...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
+						},
+						isError: true,
+					};
+				}
 
 				const priorSessionTabTargetState = executionPlan.sessionName ? sessionTabTargets.get(executionPlan.sessionName) : undefined;
 				const priorSessionTabTarget = priorSessionTabTargetState?.target;
@@ -1853,6 +1936,8 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 						plainTextInspection,
 						spawnError: processResult.spawnError,
 						stderr: processResult.stderr,
+						timedOut: processResult.timedOut,
+						timeoutMs: processResult.timeoutMs,
 						wrapperRecoveryHint: buildWrapperRecoveryHint({ pinnedBatchUnwrapMode, sessionTabCorrection }),
 					});
 
@@ -1969,6 +2054,8 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 									? undefined
 									: redactSensitiveText(processResult.stdout),
 							summary: redactSensitiveText(presentation.summary),
+							timedOut: processResult.timedOut || undefined,
+							timeoutMs: processResult.timeoutMs,
 						},
 						isError: !succeeded,
 					};

package/extensions/agent-browser/lib/playbook.ts

@@ -14,10 +14,10 @@ export const TOOL_PROMPT_GUIDELINES_PREFIX = [
 ] as const;
 
 export const QUICK_START_GUIDELINES = [
-	"Quick start mental model: args are the exact agent-browser CLI args after the binary; stdin is only for batch and eval --stdin, and other command/stdin combinations are rejected before launch; sessionMode=fresh switches the extension-managed pi-scoped session to a fresh upstream launch when you need new --profile, --session-name, --cdp, --state, or --auto-connect state.",
+	"Quick start mental model: args are the exact agent-browser CLI args after the binary; stdin is only for batch and eval --stdin, and other command/stdin combinations are rejected before launch; sessionMode=fresh switches the extension-managed pi-scoped session to a fresh upstream launch when you need new --profile, --session-name, --cdp, --state, --auto-connect, --init-script, or --enable state.",
 	"Common first calls: { args: [\"open\", \"https://example.com\"] } then { args: [\"snapshot\", \"-i\"] }; after navigation, use { args: [\"click\", \"@e2\"] } then { args: [\"snapshot\", \"-i\"] }.",
-	"Common advanced calls: { args: [\"batch\"], stdin: \"[[\\\"open\\\",\\\"https://example.com\\\"],[\\\"snapshot\\\",\\\"-i\\\"]]\" }, { args: [\"eval\", \"--stdin\"], stdin: \"document.title\" }, and { args: [\"--profile\", \"Default\", \"open\", \"https://example.com/account\"], sessionMode: \"fresh\" }.",
-	"High-value command reference: download <selector> <path> saves a file triggered by a click; get title/url/text/html/value/attr/count reads page state; screenshot [path] captures an image; pdf <path> saves a PDF; tab list and tab <tab-id-or-label> inspect or recover the active tab.",
+	"Common advanced calls: { args: [\"batch\"], stdin: \"[[\\\"open\\\",\\\"https://example.com\\\"],[\\\"snapshot\\\",\\\"-i\\\"]]\" }, { args: [\"eval\", \"--stdin\"], stdin: \"document.title\" }, { args: [\"--profile\", \"Default\", \"open\", \"https://example.com/account\"], sessionMode: \"fresh\" }, and { args: [\"open\", \"--enable\", \"react-devtools\", \"https://example.com\"], sessionMode: \"fresh\" }.",
+	"High-value command reference: download <selector> <path> saves a file triggered by a click; get title/url/text/html/value/attr/count reads page state; screenshot [path] captures an image; pdf <path> saves a PDF; tab list and tab <tab-id-or-label> inspect or recover the active tab; react tree/inspect/renders/suspense introspect React after --enable react-devtools; vitals [url] measures Core Web Vitals; pushstate <url> performs SPA navigation.",
 	"For artifact-producing commands, read the visible artifact block for requested path, absolute path, existence, size, type, cwd, and session; details.artifacts contains the same machine-readable metadata. For annotated screenshots inside batch, put --annotate in top-level args (for example { args: [\"--annotate\", \"batch\"], stdin: \"[[\\\"screenshot\\\",\\\"/tmp/page.png\\\"]]\" }) rather than inside the screenshot step.",
 ] as const;
 
@@ -30,8 +30,10 @@ export const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
 	"Do not assume Playwright selector dialects such as text=Close or button:has-text('Close') are supported wrapper syntax unless current upstream agent-browser behavior has been verified.",
 	"For authenticated or user-specific content like feeds, inboxes, dashboards, and accounts, prefer --profile Default on the first browser call and let the implicit session carry continuity. Use --auto-connect only if profile-based reuse is unavailable or the task is specifically about attaching to a running debug-enabled browser.",
 	"Do not invent fixed explicit session names for routine tasks. Use the implicit session unless you truly need multiple isolated browser sessions in the same conversation.",
-	"When using --profile, --session-name, --cdp, --state, or --auto-connect, put them on the first command for that session. If you intentionally use an explicit --session, keep using that same explicit session for follow-ups.",
-	"If you already used the implicit session and now need launch-scoped flags like --profile, --session-name, --cdp, --state, or --auto-connect, retry with sessionMode set to fresh or pass an explicit --session for the new launch. After a successful unnamed fresh launch, later auto calls follow that new session.",
+	"When using --profile, --session-name, --cdp, --state, --auto-connect, --init-script, or --enable, put them on the first command for that session. If you intentionally use an explicit --session, keep using that same explicit session for follow-ups.",
+	"If you already used the implicit session and now need launch-scoped flags like --profile, --session-name, --cdp, --state, --auto-connect, --init-script, or --enable, retry with sessionMode set to fresh or pass an explicit --session for the new launch. After a successful unnamed fresh launch, later auto calls follow that new session.",
+	"For React introspection, launch the page with --enable react-devtools before first navigation, then use react tree, react inspect <fiberId>, react renders start/stop, or react suspense; use vitals [url] for Core Web Vitals and hydration timing, and pushstate <url> for client-side SPA navigation.",
+	"For first-navigation setup, use open without a URL plus network route --resource-type <csv>, cookies set --curl <file>, or --init-script/--enable before navigate/opening the target page.",
 	"If a session lands on the wrong page or tab, an interaction changes origin unexpectedly, or an open call returns blocked, blank, or otherwise unexpected results, use tab list / tab <tab-id-or-label> / snapshot -i to recover state before retrying different URLs or fallback strategies. Only use wait with an explicit argument like milliseconds, --load <state>, --url <matcher>, --fn <js>, or --text <matcher>.",
 	"For feed, timeline, or inbox reading tasks, focus on the main timeline/list region and read the first item there rather than unrelated composer or sidebar content.",
 	"For read-only browsing tasks, prefer extracting the answer from the current snapshot, structured ref labels, or eval --stdin on the current page before navigating away. Only click into media viewers, detail routes, or new pages when the current view does not contain the needed information.",
@@ -46,8 +48,8 @@ export const TOOL_PROMPT_GUIDELINES_SUFFIX = [
 	"Do not fall back to osascript, AppleScript, or generic browser-driving bash commands when agent_browser can do the job.",
 	"Pass exact agent-browser CLI arguments in args, excluding the binary name.",
 	"Use stdin only for eval --stdin and batch instead of shell heredocs; other command/stdin combinations are rejected before launch.",
-	"Let the extension-managed session handle the common path unless you explicitly need a fresh launch for upstream flags like --profile, --session-name, --cdp, --state, or --auto-connect.",
-	"Use sessionMode=fresh when switching from an existing implicit session to a new profile/debug launch without inventing a fixed explicit session name; later auto calls will follow that new session.",
+	"Let the extension-managed session handle the common path unless you explicitly need a fresh launch for upstream flags like --profile, --session-name, --cdp, --state, --auto-connect, --init-script, or --enable.",
+	"Use sessionMode=fresh when switching from an existing implicit session to a new profile/debug/init-script launch without inventing a fixed explicit session name; later auto calls will follow that new session.",
 ] as const;
 
 export const INSPECTION_TOOL_CALL_EXAMPLES = [

package/extensions/agent-browser/lib/process.ts

@@ -17,7 +17,11 @@ const MAX_BUFFERED_STDERR_CHARS = 32_000;
 const MAX_BUFFERED_STDOUT_TAIL_CHARS = 32_000;
 const PROCESS_STDOUT_SPILL_FILE_PREFIX = "process-stdout";
 const AGENT_BROWSER_SOCKET_DIR_ENV = "AGENT_BROWSER_SOCKET_DIR";
+const AGENT_BROWSER_DEFAULT_TIMEOUT_ENV = "AGENT_BROWSER_DEFAULT_TIMEOUT";
+const PI_AGENT_BROWSER_PROCESS_TIMEOUT_ENV = "PI_AGENT_BROWSER_PROCESS_TIMEOUT_MS";
 const DEFAULT_AGENT_BROWSER_SOCKET_DIR_PREFIX = "/tmp/piab";
+export const SAFE_AGENT_BROWSER_OPERATION_TIMEOUT_MS = 25_000;
+const DEFAULT_AGENT_BROWSER_PROCESS_TIMEOUT_MS = 28_000;
 const httpProxyEnvName = "http_proxy";
 const httpsProxyEnvName = "https_proxy";
 const allProxyEnvName = "all_proxy";
@@ -92,6 +96,8 @@ export interface ProcessRunResult {
 	stderr: string;
 	stdout: string;
 	stdoutSpillPath?: string;
+	timedOut: boolean;
+	timeoutMs?: number;
 }
 
 function appendTail(text: string, addition: string, maxChars: number): string {
@@ -99,6 +105,25 @@ function appendTail(text: string, addition: string, maxChars: number): string {
 	return combined.length <= maxChars ? combined : combined.slice(combined.length - maxChars);
 }
 
+function parsePositiveIntegerEnv(value: string | undefined): number | undefined {
+	if (value === undefined || !/^\d+$/.test(value.trim())) {
+		return undefined;
+	}
+	const parsed = Number(value.trim());
+	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+function clampUpstreamDefaultTimeout(childEnv: NodeJS.ProcessEnv): void {
+	const requestedTimeout = parsePositiveIntegerEnv(childEnv[AGENT_BROWSER_DEFAULT_TIMEOUT_ENV]);
+	if (requestedTimeout === undefined || requestedTimeout > SAFE_AGENT_BROWSER_OPERATION_TIMEOUT_MS) {
+		childEnv[AGENT_BROWSER_DEFAULT_TIMEOUT_ENV] = String(SAFE_AGENT_BROWSER_OPERATION_TIMEOUT_MS);
+	}
+}
+
+export function getAgentBrowserProcessTimeoutMs(env: NodeJS.ProcessEnv = processEnv): number {
+	return parsePositiveIntegerEnv(env[PI_AGENT_BROWSER_PROCESS_TIMEOUT_ENV]) ?? DEFAULT_AGENT_BROWSER_PROCESS_TIMEOUT_MS;
+}
+
 export function getAgentBrowserSocketDir(
 	platform: NodeJS.Platform = processPlatform,
 	uid: number | undefined = typeof process.getuid === "function" ? process.getuid() : undefined,
@@ -134,6 +159,7 @@ export function buildAgentBrowserProcessEnv(
 	}
 
 	if (!overrides) {
+		clampUpstreamDefaultTimeout(childEnv);
 		return childEnv;
 	}
 
@@ -144,6 +170,7 @@ export function buildAgentBrowserProcessEnv(
 			childEnv[name] = value;
 		}
 	}
+	clampUpstreamDefaultTimeout(childEnv);
 	return childEnv;
 }
 
@@ -153,8 +180,10 @@ export async function runAgentBrowserProcess(options: {
 	env?: NodeJS.ProcessEnv;
 	signal?: AbortSignal;
 	stdin?: string;
+	timeoutMs?: number;
 }): Promise<ProcessRunResult> {
 	const { args, cwd, env, signal, stdin } = options;
+	const timeoutMs = options.timeoutMs ?? getAgentBrowserProcessTimeoutMs();
 	const explicitSocketDir = env?.[AGENT_BROWSER_SOCKET_DIR_ENV];
 	let effectiveEnv = explicitSocketDir === undefined ? { ...env, [AGENT_BROWSER_SOCKET_DIR_ENV]: undefined } : env;
 	const requestedSocketDir = explicitSocketDir ?? getAgentBrowserSocketDir();
@@ -175,7 +204,9 @@ export async function runAgentBrowserProcess(options: {
 		let pendingStdoutWrite = Promise.resolve();
 		let stdoutSpillError: Error | undefined;
 		let killTimer: NodeJS.Timeout | undefined;
+		let timeoutTimer: NodeJS.Timeout | undefined;
 		let abortListener: (() => void) | undefined;
+		let timedOut = false;
 
 		const queueStdoutChunk = (buffer: Buffer) => {
 			stdoutTail = appendTail(stdoutTail, buffer.toString("utf8"), MAX_BUFFERED_STDOUT_TAIL_CHARS);
@@ -224,6 +255,9 @@ export async function runAgentBrowserProcess(options: {
 				if (killTimer) {
 					clearTimeout(killTimer);
 				}
+				if (timeoutTimer) {
+					clearTimeout(timeoutTimer);
+				}
 				if (stdoutSpillHandle) {
 					await stdoutSpillHandle.close().catch(() => undefined);
 				}
@@ -237,6 +271,8 @@ export async function runAgentBrowserProcess(options: {
 					stderr,
 					stdout: stdoutSpillPath ? stdoutTail : Buffer.concat(stdoutBuffers).toString("utf8"),
 					stdoutSpillPath,
+					timedOut,
+					timeoutMs: timedOut ? timeoutMs : undefined,
 				});
 			});
 		};
@@ -247,8 +283,13 @@ export async function runAgentBrowserProcess(options: {
 			stdio: ["pipe", "pipe", "pipe"],
 		});
 
-		const abortChild = () => {
-			aborted = true;
+		const terminateChild = (reason: "abort" | "timeout") => {
+			if (settled) return;
+			if (reason === "abort") {
+				aborted = true;
+			} else {
+				timedOut = true;
+			}
 			child.kill("SIGTERM");
 			killTimer = setTimeout(() => {
 				child.kill("SIGKILL");
@@ -286,7 +327,7 @@ export async function runAgentBrowserProcess(options: {
 			finish(127);
 		});
 		child.once("close", (code) => {
-			finish(code ?? (spawnError ? 127 : 0));
+			finish(code ?? (timedOut ? 124 : spawnError ? 127 : 0));
 		});
 		child.stdout.on("data", (chunk: Buffer | string) => {
 			queueStdoutChunk(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
@@ -295,11 +336,16 @@ export async function runAgentBrowserProcess(options: {
 			stderr = appendTail(stderr, chunk.toString(), MAX_BUFFERED_STDERR_CHARS);
 		});
 
+		if (timeoutMs > 0) {
+			timeoutTimer = setTimeout(() => terminateChild("timeout"), timeoutMs);
+			timeoutTimer.unref?.();
+		}
+
 		if (signal) {
 			if (signal.aborted) {
-				abortChild();
+				terminateChild("abort");
 			} else {
-				abortListener = abortChild;
+				abortListener = () => terminateChild("abort");
 				signal.addEventListener("abort", abortListener, { once: true });
 			}
 		}

package/extensions/agent-browser/lib/results/envelope.ts

@@ -116,6 +116,25 @@ function buildExitCodeFallback(options: { command?: string; effectiveArgs?: stri
 	return appendWrapperRecoveryHint(`${invocation} exited with code ${options.exitCode}.`, options.wrapperRecoveryHint);
 }
 
+function buildWatchdogTimeoutMessage(options: { timeoutMs?: number }): string {
+	const timeoutText = options.timeoutMs === undefined ? "the wrapper watchdog" : `the ${options.timeoutMs}ms wrapper watchdog`;
+	return [
+		`agent-browser exceeded ${timeoutText} and was stopped before the upstream CLI entered its 30s IPC retry path.`,
+		"Keep a single agent-browser command under 30 seconds; split long waits into shorter waits or retry with sessionMode: \"fresh\" if the session state looks stale.",
+	].join(" ");
+}
+
+function isUpstreamIpcReadTimeoutMessage(message: string): boolean {
+	return /Failed to read: Resource temporarily unavailable(?: \(os error \d+\))?.*daemon may be busy or unresponsive/i.test(message);
+}
+
+function buildUpstreamIpcReadTimeoutMessage(): string {
+	return [
+		"agent-browser hit the upstream CLI 30s IPC read timeout while waiting for the daemon response.",
+		"The daemon may still be alive; do not blindly retry a non-idempotent command. Prefer a shorter command, split long waits, or retry with sessionMode: \"fresh\" after checking tab list.",
+	].join(" ");
+}
+
 export function getAgentBrowserErrorText(options: {
 	aborted: boolean;
 	command?: string;
@@ -126,10 +145,13 @@ export function getAgentBrowserErrorText(options: {
 	plainTextInspection: boolean;
 	spawnError?: Error;
 	stderr: string;
+	timedOut?: boolean;
+	timeoutMs?: number;
 	wrapperRecoveryHint?: string;
 }): string | undefined {
-	const { aborted, envelope, exitCode, parseError, plainTextInspection, spawnError, stderr } = options;
+	const { aborted, envelope, exitCode, parseError, plainTextInspection, spawnError, stderr, timedOut } = options;
 	if (plainTextInspection) return undefined;
+	if (timedOut) return buildWatchdogTimeoutMessage(options);
 	if (aborted) return "agent-browser was aborted.";
 	if (spawnError) return spawnError.message;
 	if (parseError) return parseError;
@@ -137,7 +159,11 @@ export function getAgentBrowserErrorText(options: {
 		if ((hasStructuredBatchStepFailure(envelope.data) || detectConfirmationRequired(envelope.data)) && envelope.error === undefined) {
 			return undefined;
 		}
-		return extractEnvelopeErrorText(envelope.error) ?? (stderr.trim() || buildFailureFallback(options));
+		const envelopeErrorText = extractEnvelopeErrorText(envelope.error);
+		if (envelopeErrorText && isUpstreamIpcReadTimeoutMessage(envelopeErrorText)) {
+			return buildUpstreamIpcReadTimeoutMessage();
+		}
+		return envelopeErrorText ?? (stderr.trim() || buildFailureFallback(options));
 	}
 	if (exitCode !== 0) {
 		return stderr.trim() || buildExitCodeFallback(options);

package/extensions/agent-browser/lib/runtime.ts

@@ -27,7 +27,8 @@ import { isRecord } from "./parsing.js";
  *
  * Other flags like `--headed`, `--engine`, `--executable-path`, `--user-agent`, and
  * `--download-path` are first-launch-sensitive but not alternate session/auth attach
- * mechanisms, so they are intentionally excluded from the full launch-scoped set.
+ * mechanisms and do not inject pre-page JavaScript, so they are intentionally excluded
+ * from the full launch-scoped set.
  */
 const LAUNCH_SCOPED_FLAG_DEFINITIONS = [
 	{
@@ -38,6 +39,14 @@ const LAUNCH_SCOPED_FLAG_DEFINITIONS = [
 		flag: "--cdp",
 		reason: "selects the browser/CDP endpoint used when an upstream session is launched",
 	},
+	{
+		flag: "--enable",
+		reason: "selects built-in page init scripts before the upstream browser session is launched",
+	},
+	{
+		flag: "--init-script",
+		reason: "registers page init scripts before the upstream browser session is launched",
+	},
 	{
 		flag: "--profile",
 		reason: "selects Chrome profile state for the upstream launch",
@@ -77,6 +86,7 @@ const LEGACY_BASH_ALLOW_PATTERNS = [
 ];
 const BROWSER_PROMPT_PATTERNS = [
 	/\b(?:agent[_ -]?browser|browser automation|eval\s+--stdin|screenshot|snapshot|tab\s+list)\b/i,
+	/\b(?:react\s+(?:tree|inspect|renders|suspense)|web\s+vitals|core\s+web\s+vitals|pushstate)\b/i,
 	/\bbrowser\b.*\b(?:automation|click|fill|navigate|open|page|screenshot|site|snapshot|tab|url|visit|web(?:site| page)?)\b/i,
 	/\b(?:browse|click|fill|login|navigate|open|visit)\b.*\b(?:https?:\/\/\S+|page|site|tab|url|web(?:site| page)?)\b/i,
 ];
@@ -98,6 +108,8 @@ const GLOBAL_FLAGS_WITH_VALUES = new Set([
 	"--headers",
 	"--executable-path",
 	"--extension",
+	"--init-script",
+	"--enable",
 	"--provider",
 	"-p",
 	"--engine",
@@ -328,11 +340,33 @@ function redactStandaloneBasicCredential(text: string): string {
 	});
 }
 
+function credentialTrailingPunctuation(credential: string): string {
+	return credential.match(/^(.+?)([,.]+)$/)?.[2] ?? "";
+}
+
+function isBearerHelpPlaceholder(label: string, credential: string, trailing: string): boolean {
+	return label.toLowerCase() === "authorization bearer" && credential.toLowerCase() === "token" && trailing === ")";
+}
+
+function formatRedactedCredential(label: string, credential: string, trailing = ""): string {
+	return `${label} [REDACTED]${credentialTrailingPunctuation(credential)}${trailing}`;
+}
+
+function redactBearerCredentials(text: string): string {
+	return text
+		.replace(/\b(Authorization\s*:\s*Bearer)\s+([^\s"',)\[\]]+)([),.]?)/gi, (_match, label: string, credential: string, trailing: string) => {
+			return formatRedactedCredential(label, credential, trailing);
+		})
+		.replace(/\b((?:Authorization\s+)?Bearer)\s+([^\s"',)\[\]]+)([),.]?)/gi, (match, label: string, credential: string, trailing: string) => {
+			if (isBearerHelpPlaceholder(label, credential, trailing)) return match;
+			return formatRedactedCredential(label, credential, trailing);
+		});
+}
+
 export function redactSensitiveText(text: string): string {
 	return redactEmbeddedStructuredText(
 		redactStandaloneBasicCredential(
-			redactLooseUrlMatches(text)
-				.replace(/\b(Bearer)\s+[^\s",]+/gi, "$1 [REDACTED]")
+			redactBearerCredentials(redactLooseUrlMatches(text))
 				.replace(/\b(Authorization\s*:\s*Basic)\s+[^\s",]+/gi, "$1 [REDACTED]")
 				.replace(/\b(Cookie|Set-Cookie)\s*:\s*[^\n\r"]+/gi, "$1: [REDACTED]"),
 		),
@@ -978,9 +1012,31 @@ export function chooseOpenResultTabCorrection(options: {
 		: undefined;
 }
 
+function getOpenCommandTarget(commandTokens: string[]): string | undefined {
+	for (let index = 1; index < commandTokens.length; index += 1) {
+		const token = commandTokens[index];
+		if (token === "--init-script" || token === "--enable") {
+			index += 1;
+			continue;
+		}
+		if (token.startsWith("--init-script=") || token.startsWith("--enable=")) {
+			continue;
+		}
+		if (token.startsWith("-")) {
+			continue;
+		}
+		return token;
+	}
+	return undefined;
+}
+
 export function parseCommandInfo(args: string[]): CommandInfo {
 	const commandTokens = extractCommandTokens(args);
-	return { command: commandTokens[0], subcommand: commandTokens[1] };
+	const command = commandTokens[0];
+	return {
+		command,
+		subcommand: command && OPEN_COMMANDS.has(command) ? getOpenCommandTarget(commandTokens) : commandTokens[1],
+	};
 }
 
 export function extractCommandTokens(args: string[]): string[] {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-browser-native",
-  "version": "0.2.19",
+  "version": "0.2.21",
   "description": "pi extension that exposes agent-browser as a native tool for browser automation",
   "type": "module",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",

package/scripts/agent-browser-capability-baseline.mjs

@@ -12,7 +12,7 @@ export const CAPABILITY_BASELINE_BLOCK_MARKER_PREFIX = "agent-browser-capability
 export const COMMAND_REFERENCE_BASELINE_BLOCK_IDS = Object.freeze(["upstream-baseline", "capability-token-baseline"]);
 
 export const CAPABILITY_BASELINE = Object.freeze({
-  targetVersion: "0.26.0",
+  targetVersion: "0.27.0",
   helpCommands: Object.freeze([
     Object.freeze({ label: "root help", args: Object.freeze(["--help"]) }),
     Object.freeze({ label: "tab help", args: Object.freeze(["tab", "--help"]) }),
@@ -43,6 +43,20 @@ export const CAPABILITY_BASELINE = Object.freeze({
     "inspect",
     "clipboard <op> [text]",
     "stream enable [--port <n>]",
+    "react tree",
+    "react inspect <id>",
+    "react renders start",
+    "react renders stop [--json]",
+    "react suspense [--only-dynamic] [--json]",
+    "vitals [url] [--json]",
+    "pushstate <url>",
+    "removeinitscript <id>",
+    "--init-script <path>",
+    "--enable <feature>",
+    "AGENT_BROWSER_INIT_SCRIPTS",
+    "AGENT_BROWSER_ENABLE",
+    "network route <url> [--abort|--body <json>] [--resource-type <csv>]",
+    "cookies set --curl <file>",
     "auth save <name>",
     "confirm <id>",
     "deny <id>",
@@ -84,6 +98,18 @@ export const CAPABILITY_BASELINE = Object.freeze({
     Object.freeze({ token: "inspect", help: "root help" }),
     Object.freeze({ token: "clipboard <op> [text]", help: "root help" }),
     Object.freeze({ token: "stream enable [--port <n>]", help: "root help" }),
+    Object.freeze({ token: "react tree", help: "root help" }),
+    Object.freeze({ token: "react inspect <id>", help: "root help" }),
+    Object.freeze({ token: "react renders start", help: "root help" }),
+    Object.freeze({ token: "react renders stop [--json]", help: "root help" }),
+    Object.freeze({ token: "react suspense [--only-dynamic] [--json]", help: "root help" }),
+    Object.freeze({ token: "vitals [url] [--json]", help: "root help" }),
+    Object.freeze({ token: "pushstate <url>", help: "root help" }),
+    Object.freeze({ token: "removeinitscript <id>", help: "root help" }),
+    Object.freeze({ token: "--init-script <path>", help: "root help" }),
+    Object.freeze({ token: "--enable <feature>", help: "root help" }),
+    Object.freeze({ token: "--resource-type <csv>", help: "root help" }),
+    Object.freeze({ token: "cookies set --curl <file>", help: "root help" }),
     Object.freeze({ token: "auth save <name>", help: "root help" }),
     Object.freeze({ token: "confirm <id>", help: "root help" }),
     Object.freeze({ token: "deny <id>", help: "root help" }),

package/scripts/doctor.mjs

@@ -8,6 +8,7 @@
  */
 
 import { execFile as execFileCallback } from "node:child_process";
+import { realpathSync } from "node:fs";
 import { access, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, resolve, sep } from "node:path";
@@ -415,7 +416,16 @@ export async function main(argv = process.argv.slice(2)) {
 	return 0;
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+export function isDirectRun(metaUrl, argv1 = process.argv[1], resolveRealPath = realpathSync) {
+	if (!argv1) return false;
+	try {
+		return resolveRealPath(argv1) === fileURLToPath(metaUrl);
+	} catch {
+		return false;
+	}
+}
+
+if (isDirectRun(import.meta.url)) {
 	main().then((exitCode) => {
 		process.exitCode = exitCode;
 	});