pi-agent-browser-native 0.2.60 → 0.2.62

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 ## Unreleased
 
+## 0.2.62 - 2026-06-26
+
+### Changed
+
+- Rebaselined upstream capability metadata, command reference, support docs, playbook guidance, and real-upstream output-shape metadata for `agent-browser` `0.31.0` / vercel-labs/agent-browser@5acf7f9.
+- Added upstream `--namespace`, `--restore`, restore-check flags, and `session id` / `session info` support to wrapper parsing, session policy, launch-scoped flag handling, and docs.
+
+### Fixed
+
+- Made wrapper-managed browser state namespace-aware across tab/ref tracking, allowed-domain policy, trace/profiler ownership, branch restore, cleanup, nextActions, and fresh-launch recovery.
+- Reduced post-click diagnostic fragility for upstream `agent-browser 0.31.0`: CSS selector clicks without upstream href/navigation fields now skip immediate helper probes, while ref/href clicks keep navigation summaries and overlay diagnostics.
+- Preserved namespace context for managed-session failure recovery and missing-binary nextActions.
+
+### Validation
+
+- Ran `npm run verify`, `npm run docs -- command-reference check`, `npm run typecheck`, focused runtime/diagnostic/passthrough tests, `npm run verify -- real-upstream`, `npm run verify -- dogfood`, `npm run verify -- lifecycle`, `npm run smoke:platform:doctor`, `npm run smoke:platform:all`, `npm publish --dry-run`, and `git diff --check`.
+- Ran the required reviewer subagent loop until it returned `no findings`.
+
+## 0.2.61 - 2026-06-24
+
+### Changed
+
+- Rebaselined upstream capability metadata, command reference, support docs, playbook guidance, and real-upstream output-shape metadata for `agent-browser` `0.30.1` / vercel-labs/agent-browser@7379f7dbea76ad8dbf47f177349c4c3ce9263dcb.
+- Removed the constrained `job.assertUrl` glob-to-`wait --fn` workaround now that upstream `wait --url` matches glob patterns such as `**/dashboard` against the full active URL.
+
+### Validation
+
+- Ran `npm run verify`, `npm run docs`, focused `npx tsx --test test/agent-browser.extension-input-modes.test.ts`, `npm run verify -- command-reference`, and `git diff --check`.
+- Probed upstream `agent-browser 0.30.1` directly: `wait --url "**/dashboard"` succeeds after `pushstate /dashboard`; `find ... uncheck` and `wait <selector> --state hidden|detached` still fail, so only the URL-glob workaround was removed.
+
 ## 0.2.60 - 2026-06-24
 
 ### Changed

package/README.md

@@ -79,13 +79,13 @@ The result is optimized for agent work:
 | Stateful cookies/storage/auth output bloats or leaks context | Presentation layer redacts `details.data` for cookies and credential-like storage values while keeping low-risk local QA values such as `theme: dark` readable; recursively scrubs other structured upstream JSON (network, diff, trace/profiler, stream, dashboard, chat, auth, dialog, frame, state, and similar) using sensitive key names plus string heuristics; masks sensitive argv flags and positionals; scrubs secrets from failed batch step errors; and exposes a compact redacted `batch` matrix on top-level `details.data` | `extensions/agent-browser/lib/results/presentation.ts`, `extensions/agent-browser/lib/results/presentation/diagnostics.ts`, `extensions/agent-browser/lib/runtime.ts`, `test/agent-browser.presentation-diagnostics.test.ts` |
 | Stale `@eN` refs fail mysteriously | Records per-session `details.refSnapshot`, rejects mismatched URLs / unknown refs / unsafe `batch` stdin ordering before spawn, adds recovery guidance to rerun `snapshot -i` or use stable `find` locators | `extensions/agent-browser/index.ts`, `extensions/agent-browser/lib/session-page-state.ts`, `test/agent-browser.session-page-state.test.ts`, `test/agent-browser.results.test.ts`, `test/agent-browser.extension-ref-guards.test.ts`, `test/agent-browser.extension-semantic-recovery.test.ts` |
 | Agents need stable success/failure buckets | Exposes bounded `resultCategory`, `successCategory`, and `failureCategory` on tool `details` for branching without parsing prose; a `tool_result` hook also aligns real Pi `isError` semantics, naming `Pi tool isError: true` in prose output while preserving parseable caller-requested `--json` output | [`docs/TOOL_CONTRACT.md`](docs/TOOL_CONTRACT.md#details), `extensions/agent-browser/lib/results/categories.ts`, `extensions/agent-browser/lib/results/shared.ts` (re-export barrel), `extensions/agent-browser/index.ts`, `extensions/agent-browser/lib/pi-tool-rendering.ts`, `test/agent-browser.results.test.ts`, `test/agent-browser.extension-validation.test.ts`, `test/agent-browser.pi-pipeline.test.ts` |
-| Clicks can report success without the page receiving the event | Top-level non-Electron direct `click` calls on CSS selectors / `xpath=` targets or role-gated current `@e…` refs (`button`, `checkbox`, `menuitem`, `radio`, `switch`, `tab`) install a bounded target-specific DOM-event probe; eligible `@e…` refs use the latest snapshot role/name metadata, and duplicate-name refs use snapshot-order `duplicateIndex` rather than requiring a unique name. If upstream reports success but no trusted event reaches the resolved target, the wrapper fails the tool, exposes `details.clickDispatch`, and suggests explicit retry/inspect next actions (no in-page replay), including a nested-scroll `scrollintoview` action when the probe sees the target outside a scroll container or viewport. Unresolved locator clicks such as raw `find … click` are left upstream-owned to avoid false failures for frame-scoped targets. Other click results still expose `details.pageChangeSummary`, and unchanged-URL clicks can surface evidence-backed `details.overlayBlockers` candidates. | [`docs/TOOL_CONTRACT.md`](docs/TOOL_CONTRACT.md#details), `extensions/agent-browser/lib/orchestration/browser-run/click-dispatch.ts`, `extensions/agent-browser/lib/results/presentation/navigation.ts`, `test/agent-browser.presentation.test.ts`, `test/agent-browser.extension-click-dispatch.test.ts` |
-| Dashboard scroll commands can look successful while nothing moves | Samples viewport and prominent scroll-container positions around top-level `scroll` calls; unchanged positions produce `details.scrollNoop`, visible recovery guidance, and exact `nextActions` for snapshot/screenshot verification | [`docs/TOOL_CONTRACT.md`](docs/TOOL_CONTRACT.md#details), [`docs/COMMAND_REFERENCE.md`](docs/COMMAND_REFERENCE.md#core-page-and-element-commands), `test/agent-browser.extension-validation.test.ts` |
+| Clicks can report success without the page receiving the event | Top-level non-Electron direct `click` calls on `xpath=` targets or role-gated current `@e…` refs (`button`, `checkbox`, `menuitem`, `radio`, `switch`, `tab`) install a bounded target-specific DOM-event probe; eligible `@e…` refs use the latest snapshot role/name metadata, and duplicate-name refs use snapshot-order `duplicateIndex` rather than requiring a unique name. If upstream reports success but no trusted event reaches the resolved target, the wrapper fails the tool, exposes `details.clickDispatch`, and suggests explicit retry/inspect next actions (no in-page replay), including a nested-scroll `scrollintoview` action when the probe sees the target outside a scroll container or viewport. Unresolved locator clicks such as raw `find … click` are left upstream-owned to avoid false failures for frame-scoped targets. Other click results still expose `details.pageChangeSummary`, and unchanged-URL clicks can surface evidence-backed `details.overlayBlockers` candidates. | [`docs/TOOL_CONTRACT.md`](docs/TOOL_CONTRACT.md#details), `extensions/agent-browser/lib/orchestration/browser-run/click-dispatch.ts`, `extensions/agent-browser/lib/results/presentation/navigation.ts`, `test/agent-browser.presentation.test.ts`, `test/agent-browser.extension-click-dispatch.test.ts` |
+| Dashboard scroll commands can look successful while nothing moves | Samples viewport and prominent scroll-container positions around large top-level `scroll` calls on an existing or fresh managed session; unchanged positions produce `details.scrollNoop`, visible recovery guidance, and exact `nextActions` for snapshot/screenshot verification | [`docs/TOOL_CONTRACT.md`](docs/TOOL_CONTRACT.md#details), [`docs/COMMAND_REFERENCE.md`](docs/COMMAND_REFERENCE.md#core-page-and-element-commands), `test/agent-browser.extension-validation.test.ts` |
 | Dropdown/combobox clicks can focus or hit native option box-model errors | Adds first-class `select <selector> <value...>` paths through raw `args`, `semanticAction`, and `job`; for custom combobox clicks, detects focused controls with explicit `aria-expanded` state but no visible options and returns `details.comboboxFocus` plus exact recovery `nextActions` | [`docs/TOOL_CONTRACT.md`](docs/TOOL_CONTRACT.md#details), [`docs/COMMAND_REFERENCE.md`](docs/COMMAND_REFERENCE.md#core-page-and-element-commands), `extensions/agent-browser/lib/input-modes/semantic-action.ts`, `test/agent-browser.extension-input-modes.test.ts`, `test/agent-browser.extension-validation.test.ts` |
 | Recording workflows fail late when `ffmpeg` is missing | After successful `record start` / `record restart`, warns when `ffmpeg` is not on `PATH` so agents can install or fix PATH before `record stop` | [`docs/TOOL_CONTRACT.md`](docs/TOOL_CONTRACT.md#details), [`docs/COMMAND_REFERENCE.md`](docs/COMMAND_REFERENCE.md#diff-debug-and-streaming), `test/agent-browser.extension-validation.test.ts` |
 | Direct binary help may be blocked in agent sessions | Publishes a repo-readable command reference and verifies it against the target upstream version | `npm run verify` |
 | Desktop Electron apps need discovery, CDP attach, and safe teardown | Top-level `electron` runs host `list` / isolated `launch` (temp profile, OS-chosen debug port) / `status` / `probe` / `cleanup`, merges `launchId` plus managed `sessionName`, supports `handoff` `snapshot` / `tabs` / `connect`, and surfaces mismatch and post-command health guidance; wrapper cleanup applies only to launches it created | `extensions/agent-browser/lib/electron/discovery.ts`, `launch.ts`, `cleanup.ts`, [`docs/TOOL_CONTRACT.md`](docs/TOOL_CONTRACT.md#electron), [`docs/COMMAND_REFERENCE.md`](docs/COMMAND_REFERENCE.md#electron-desktop-apps) |
-| Agents need bundled `skills` text and local setup/status commands without touching the live session | Treats `skills list`, `skills get …`, `skills path …`, local auth profile management (`auth save/list/show/delete/remove`), `profiles`, `dashboard`, `device list`, `doctor`, `install`, `upgrade`, `session list`, `plugin add/list/show/run`, `mcp --help`, and targeted/all saved-state maintenance (`state clear --all`, `state clear -a`, named clear, or `state clean --older-than <days>`) as sessionless reads/actions: no implicit managed `--session` under default `sessionMode: "auto"` (same session-ownership goal as plain-text `--help` / `--version`), while bare `mcp` server calls are blocked and provider/browser-backed workflows stay thin passthroughs that require upstream setup and credentials | [`docs/COMMAND_REFERENCE.md`](docs/COMMAND_REFERENCE.md#built-in-skills), `extensions/agent-browser/lib/command-policy.ts`, `extensions/agent-browser/lib/runtime.ts` |
+| Agents need bundled `skills` text and local setup/status commands without touching the live session | Treats `skills list`, `skills get …`, `skills path …`, local auth profile management (`auth save/list/show/delete/remove`), `profiles`, `dashboard`, `device list`, `doctor`, `install`, `upgrade`, `session list`, `session id`, `session info`, `plugin add/list/show/run`, `mcp --help`, and targeted/all saved-state maintenance (`state clear --all`, `state clear -a`, named clear, or `state clean --older-than <days>`) as sessionless reads/actions: no implicit managed `--session` under default `sessionMode: "auto"` (same session-ownership goal as plain-text `--help` / `--version`), while bare `mcp` server calls are blocked and provider/browser-backed workflows stay thin passthroughs that require upstream setup and credentials | [`docs/COMMAND_REFERENCE.md`](docs/COMMAND_REFERENCE.md#built-in-skills), `extensions/agent-browser/lib/command-policy.ts`, `extensions/agent-browser/lib/runtime.ts` |
 
 ## Fastest way to try it
 
@@ -338,16 +338,16 @@ Typical pitfalls:
 - Do not reuse `@e…` refs across navigation. The wrapper records the latest snapshot refs per session and fails mutation-prone stale/recycled refs before upstream can silently hit a different current-page element; use the session-aware `refresh-interactive-refs` next action.
 - If upstream classifies the failure as `stale-ref` and `details.compiledSemanticAction` is present for a compiled `find` action, `details.nextActions` may list `retry-semantic-action-after-stale-ref` after `refresh-interactive-refs`, carrying the same compiled `find` argv so you can retry the locator-stable target once it is safe to do so. `select` calls that used stale `@refs` only get refresh guidance; use a fresh snapshot or stable selector before retrying (contract in [`docs/TOOL_CONTRACT.md#semanticaction`](docs/TOOL_CONTRACT.md#semanticaction)).
 - If the failure is `selector-not-found`, the wrapper may take one fresh snapshot and add `Current snapshot ref fallback` when that snapshot has exact visible role/name matches for the failed `find` / `semanticAction` target. Non-fill targets can include direct `try-current-visible-ref*` next actions, and semantic click misses can still add bounded `Agent-browser candidate fallbacks` such as `button`/`link` role retries for `text` clicks. `semanticAction` does not expose `uncheck` while upstream `find ... uncheck` is not runtime-supported; use raw `args: ["uncheck", <selector-or-ref>]` after a stable selector or fresh snapshot ref. For semantic `fill` misses on desktop or host-controlled rich inputs, prefer `details.richInputRecovery`: refresh refs, choose the current editable `@ref`, focus or click it, then use `keyboard inserttext` or `keyboard type` with the intended text. Direct contenteditable fills are verified with `get text` when snapshot metadata proves the target is contenteditable; if replacement did not happen, `details.fillVerification` warns before any submit step. Those recovery nextActions do not copy the fill text and do not press `Enter` or submit; only submit when the user flow explicitly calls for it (same contract link).
-- A successful upstream `click` is not proof that the web app handled the event or changed state. For top-level non-Electron direct clicks on selectors, `xpath=` targets, and eligible current `@e…` refs, the wrapper may fail the tool with `details.clickDispatch` and a `Click dispatch diagnostic` line when upstream reported success but no trusted DOM event reached the resolved target. Raw `find … click` locator calls are not probed because the wrapper has no concrete element before upstream resolves the locator, and document-level probes can falsely fail frame-scoped clicks. `@e…` ref click probes are limited to current snapshot refs with accessible role `button`, `checkbox`, `menuitem`, `radio`, `switch`, or `tab`, using duplicate-name snapshot order when needed. Use the suggested `inspect-click-dispatch-miss` / `retry-click-after-dispatch-miss` next actions instead of assuming the click mutated the page; when `details.clickDispatch.scrollContainer` is present, use `scroll-target-into-view-after-dispatch-miss` first. When the task depends on a mutation, follow `inspect-after-mutation` / `pageChangeSummary` evidence with a wait, URL/text check, or fresh snapshot before trusting the result; if the target still did not change, retry with a current visible ref or stable selector and report the workflow issue instead of silently continuing. For static local fixtures where the user only needs to exercise app code, an explicit `eval --stdin` programmatic click such as `document.querySelector("#demo").click()` can be a diagnostic workaround, but treat it as an untrusted scripted activation rather than proof a real user click works, and never use it to bypass user instructions. Respect explicit user stop boundaries yourself: if the user says to stop before order/post/purchase/submit, gather evidence on that page and do not click the final action. The wrapper does not parse broad prompt text into business-intent action blocks; `details.promptGuard` is reserved for concrete artifact-before-close checks.
-- A successful `snapshot -i` can surface `Possible overlay blockers` immediately when refs already contain strong dialog/alertdialog evidence plus close/dismiss controls. If a **top-level** `click` succeeds (unified command `click`, not a `batch` step), upstream reports `data.clicked`, and the tab URL is unchanged under the same normalization as ref preflight (fragment-insensitive), the wrapper may take one extra `snapshot -i` and add `Possible overlay blockers` with `details.overlayBlockers` (`candidates`, `summary`, optional `snapshot` refresh for refs) plus session-aware `inspect-overlay-state` / bounded `try-overlay-blocker-candidate-*` next actions when that snapshot shows strong modal context (`dialog` / `alertdialog`) and close/dismiss-like controls. Page-wide words like privacy, sign in, or banner alone do not trigger this diagnostic. The unchanged-URL check uses `details.navigationSummary`, which is populated with one read-only `eval` summary when the click JSON omits **both** string `data.url` and `data.title`; if upstream already includes either, overlay diagnostics are skipped here. Also skipped when tab correction or about-blank recovery already ran on that result.
-- If `get text <selector>` reads a non-ref CSS selector with multiple matches or a hidden first match while visible matches exist, including successful `batch` steps, the wrapper may add `Selector text visibility warning`, `details.selectorTextVisibility` (plus `selectorTextVisibilityAll` for multiple batched warnings), and `inspect-visible-text-candidates` next actions; the warning names the matching `details.nextActions` id. Prefer a visible `@ref`, a scoped selector, or a targeted `eval --stdin` over hidden tab content.
+- A successful upstream `click` is not proof that the web app handled the event or changed state. For top-level non-Electron direct clicks on `xpath=` targets and eligible current `@e…` refs, the wrapper may fail the tool with `details.clickDispatch` and a `Click dispatch diagnostic` line when upstream reported success but no trusted DOM event reached the resolved target. Raw `find … click` locator calls are not probed because the wrapper has no concrete element before upstream resolves the locator, and document-level probes can falsely fail frame-scoped clicks. `@e…` ref click probes are limited to current snapshot refs with accessible role `button`, `checkbox`, `menuitem`, `radio`, `switch`, or `tab`, using duplicate-name snapshot order when needed. Use the suggested `inspect-click-dispatch-miss` / `retry-click-after-dispatch-miss` next actions instead of assuming the click mutated the page; when `details.clickDispatch.scrollContainer` is present, use `scroll-target-into-view-after-dispatch-miss` first. When the task depends on a mutation, follow `inspect-after-mutation` / `pageChangeSummary` evidence with a wait, URL/text check, or fresh snapshot before trusting the result; if the target still did not change, retry with a current visible ref or stable selector and report the workflow issue instead of silently continuing. For static local fixtures where the user only needs to exercise app code, an explicit `eval --stdin` programmatic click such as `document.querySelector("#demo").click()` can be a diagnostic workaround, but treat it as an untrusted scripted activation rather than proof a real user click works, and never use it to bypass user instructions. Respect explicit user stop boundaries yourself: if the user says to stop before order/post/purchase/submit, gather evidence on that page and do not click the final action. The wrapper does not parse broad prompt text into business-intent action blocks; `details.promptGuard` is reserved for concrete artifact-before-close checks.
+- A successful `snapshot -i` can surface `Possible overlay blockers` immediately when refs already contain strong dialog/alertdialog evidence plus close/dismiss controls. If a **top-level** `@e…`/`ref=` click succeeds (unified command `click`, not a `batch` step), upstream reports `data.clicked`, and `details.navigationSummary.url` stays on the same tab URL under the same normalization as ref preflight (fragment-insensitive), the wrapper may take one extra `snapshot -i` and add `Possible overlay blockers` with `details.overlayBlockers` (`candidates`, `summary`, optional `snapshot` refresh for refs) plus session-aware `inspect-overlay-state` / bounded `try-overlay-blocker-candidate-*` next actions when that snapshot shows strong modal context (`dialog` / `alertdialog`) and close/dismiss-like controls. Page-wide words like privacy, sign in, or banner alone do not trigger this diagnostic. The unchanged-URL check compares the prior pinned tab target with `details.navigationSummary.url`; CSS selector clicks do not run this overlay probe. Also skipped when tab correction or about-blank recovery already ran on that result.
+- If `get text <selector>` reads a non-ref, non-simple-id CSS selector with multiple matches or a hidden first match while visible matches exist, including successful `batch` steps, the wrapper may add `Selector text visibility warning`, `details.selectorTextVisibility` (plus `selectorTextVisibilityAll` for multiple batched warnings), and `inspect-visible-text-candidates` next actions; the warning names the matching `details.nextActions` id. Prefer a visible `@ref`, a scoped selector, or a targeted `eval --stdin` over hidden tab content.
 - In wrapper-tracked attached Electron sessions, broad selectors such as `body`, `html`, `main`, or `[role=application]` may read the whole app shell. The wrapper may add `Broad Electron get text selector warning`, `details.electronGetTextScopeWarning`, and `snapshot-for-electron-text-scope`; ordinary browser pages, including `file://` fixtures, do not qualify without Electron launch provenance. Prefer `snapshot -i`, a current `@ref`, or a narrower panel selector.
 
 ### Constrained browser jobs
 
 For short repeatable workflows, pass a top-level `job` instead of hand-writing `batch` stdin. Keep dynamic app jobs short around navigation, click, and rerender boundaries; avoid packing a whole checkout into one job. The wrapper only supports constrained steps (`open`, `click`, `fill`, `type`, `select`, `wait`, `assertText`, `assertUrl`, `waitForDownload`, `snapshot`, and `screenshot`), compiles them to existing upstream `batch` commands, and echoes the compiled commands as `details.compiledJob` for auditability. `open` steps can include `loadState` (`domcontentloaded`, `load`, or `networkidle`) to insert a readiness wait before the next step. `click` and `fill` steps can use either CSS `selector` or semantic locator fields (`locator`, `role`/`value`, optional `name`) so a job can express flows like role/name search without brittle selectors. `type` can use `selector`, `text`, optional `delayMs` for per-character pacing, and optional `press` for a final key such as `Enter`; paced type compiles to existing `focus`, `keyboard type`, `wait`, and `press` batch rows, is capped at 200 characters per delayed step, and compacts model-visible batch text while full rows remain in `details.batchSteps`. The same compile path backs top-level `qa`, so long `qa` runs surface the same timeout evidence shape. If a long `job`, `qa`, or `batch` hits the wrapper watchdog, `details.timeoutPartialProgress` may recover per-step status (`completed`, `failed`, `pending`, or `unknown`), current page title/URL, declared artifact paths that already exist on disk, and either a `retry-timeout-step` next action for the first incomplete read-only or idempotent step or `inspect-current-page-after-timeout` when the first incomplete step may be mutating and needs state inspection before a shorter follow-up flow (see [`docs/TOOL_CONTRACT.md#details`](docs/TOOL_CONTRACT.md#details)). There is no separate catalog of reusable named browser recipes above `job`, `qa`, and raw `batch`; see [`docs/ARCHITECTURE.md#no-reusable-recipe-layer-yet`](docs/ARCHITECTURE.md#no-reusable-recipe-layer-yet) for the closed `RQ-0068` decision and when to revisit it.
 
-**Navigation inside `job` is explicit.** A successful `click` does not prove the next page loaded; add `assertUrl` and/or `assertText` after navigation-prone clicks (forms, checkout, tabs, submit buttons) before screenshots or steps that assume the new page. `assertUrl` accepts exact URLs and `*` / `**` glob-style patterns; glob patterns compile to a `wait --fn` URL predicate so examples like `**/shipping` do not depend on upstream `wait --url` matcher quirks. In those patterns, `*` stays within one path segment and `**` can cross `/`; exact URLs with no `*` stay literal.
+**Navigation inside `job` is explicit.** A successful `click` does not prove the next page loaded; add `assertUrl` and/or `assertText` after navigation-prone clicks (forms, checkout, tabs, submit buttons) before screenshots or steps that assume the new page. `assertUrl` accepts exact URLs and `*` / `**` glob-style patterns and now compiles directly to upstream `wait --url` for both forms.
 
 ```json
 {
@@ -436,7 +436,7 @@ For local app debugging, `sourceLookup` can gather candidate component/file loca
 
 This is an experiment, not a guarantee. React hints require a session opened with `--enable react-devtools`, and many builds do not expose useful sourcemap/source metadata; `status: "no-candidates"` is common when nothing matched, and `status: "unsupported"` only when no candidates were found **and** a compiled `react` batch step failed (if DOM or workspace search still produced candidates, you get `candidates-found` instead). For wrapper-tracked packaged Electron apps, a no-candidate result includes `details.sourceLookup.workspaceRoot`, optional `details.sourceLookup.electronContext`, limitations explaining that the scan is limited to the Pi cwd and does not unpack app bundles/`app.asar`, plus Electron snapshot/probe/tab next actions when a launch is known.
 
-`networkSourceLookup` is the matching failed-request experiment. It runs `network request <id>` when `requestId` is present and/or `network requests --filter …` when `filter` or `url` is present (`url` supplies the filter pattern when `filter` is omitted); add `session` when the generated batch should target an explicit upstream session. It merges failed-request rows from the batch JSON with initiator-style hints and a bounded workspace literal scan (`maxWorkspaceFiles` defaults to 2000, cap 5000), surfaces everything under `details.networkSourceLookup`, and avoids automatic blame or edits. Compact `network requests` results with safe request IDs also add `details.nextActions` for request details, bounded `networkSourceLookup` on actionable failures, path filtering, diagnostic-buffer clearing before a repro, or HAR capture so agents can branch without guessing request-id syntax. For noisy aggregate buffers, wrapper-side `network requests --current-page` / `--current-origin` keeps only rows matching the active page origin, while `--current-url` keeps exact active-document URL rows and reports counts in `details.networkRequestsPageFilter`. When the wrapper has seen `network route` in the same session, pending fetch/XHR rows or CORS-looking errors that match the route surface `details.networkRouteDiagnostics` plus executable follow-ups to inspect the request or start HAR capture; same-origin/CORS-correct fixture retry guidance stays in prose. Network diagnostics are read-only for wrapper page state: request URLs in `network request` or generated `networkSourceLookup` batches do not replace the session’s active page target or invalidate page-scoped refs from the app page.
+`networkSourceLookup` is the matching failed-request experiment. It runs `network request <id>` when `requestId` is present and/or `network requests --filter …` when `filter` or `url` is present (`url` supplies the filter pattern when `filter` is omitted); add `namespace` / `session` when the generated batch should target an explicit upstream namespace/session. It merges failed-request rows from the batch JSON with initiator-style hints and a bounded workspace literal scan (`maxWorkspaceFiles` defaults to 2000, cap 5000), surfaces everything under `details.networkSourceLookup`, and avoids automatic blame or edits. Compact `network requests` results with safe request IDs also add `details.nextActions` for request details, bounded `networkSourceLookup` on actionable failures, path filtering, diagnostic-buffer clearing before a repro, or HAR capture so agents can branch without guessing request-id syntax. For noisy aggregate buffers, wrapper-side `network requests --current-page` / `--current-origin` keeps only rows matching the active page origin, while `--current-url` keeps exact active-document URL rows and reports counts in `details.networkRequestsPageFilter`. When the wrapper has seen `network route` in the same session, pending fetch/XHR rows or CORS-looking errors that match the route surface `details.networkRouteDiagnostics` plus executable follow-ups to inspect the request or start HAR capture; same-origin/CORS-correct fixture retry guidance stays in prose. Network diagnostics are read-only for wrapper page state: request URLs in `network request` or generated `networkSourceLookup` batches do not replace the session’s active page target or invalidate page-scoped refs from the app page.
 
 ```json
 { "networkSourceLookup": { "requestId": "req-1", "url": "/api/fail" } }
@@ -481,9 +481,9 @@ Use these rules:
 - Use public/temp profiles for tests and examples.
 - Do not assume `--profile Default` is correct. Ask the agent to run `profiles` to list Chrome profile directory names, then `doctor` if profile/user-data-dir resolution still fails.
 - For non-Chrome Chromium browsers such as Brave, Edge, Arc, or Vivaldi, use `--executable-path <path>` when upstream can launch that executable. If you need that browser's existing login state, use the browser's real profile/user-data directory path when upstream accepts it, or attach with `--auto-connect` / `connect` to a debug-enabled running browser when appropriate.
-- Use `sessionMode: "fresh"` when switching from public browsing to `--profile`, `--executable-path`, `--session-name`, `--cdp`, `--state`, `--auto-connect`, `--init-script`, `--enable`, `-p` / `--provider`, or iOS `--device`.
+- Use `sessionMode: "fresh"` when switching from public browsing to `--profile`, `--executable-path`, `--restore`, `--restore-save`, restore check flags, `--namespace`, `--session-name`, `--cdp`, `--state`, `--auto-connect`, `--init-script`, `--enable`, `-p` / `--provider`, or iOS `--device`.
 - Use `--session` when you want to manage a live upstream session name yourself.
-- Do not treat `--session` as persisted auth or tab restore after `close`, `quit`, or `exit`; use `--profile`, `--session-name`, or `--state` for persistence.
+- Do not treat `--session` alone as persisted auth or tab restore after `close`, `quit`, or `exit`; use `--session <id> --restore`, `--profile`, or `--state` for persistence.
 - Prefer page actions and storage checks over cookie dumps. `cookies get` can expose real profile cookies.
 - Prefer `auth save --password-stdin` over putting passwords in `args`; the wrapper only accepts caller `stdin` for `batch`, `eval --stdin`, and `auth save --password-stdin` (top-level `job` and `qa` compile to `batch` and supply their own stdin).
 - Use `state save <path>` / `state load <path>` for portable test state. `state save` is reported as a file artifact with verification metadata; if an upstream-successful artifact command reports a non-pending file path that the wrapper cannot find on disk, the tool fails with `failureCategory: "artifact-missing"` instead of treating the path as durable. `state load` may mention a path but is not treated as a newly saved artifact.
@@ -703,7 +703,7 @@ These calls return plain text and stay stateless: the extension does not inject
 
 <!-- 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.
+- After launch-scoped open/goto/navigate calls that can restore existing tabs (for example --profile, --restore, --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.
 - After the wrapper observes tab-drift risk for a session (for example profile restore correction, overlapping stale opens, or resumed session state), later active-tab commands best-effort pin that tab inside the same upstream invocation. Routine same-session commands are not preflighted with tab list just because a target tab is known.
 - For sessions with observed tab-drift risk, 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. Routine same-session commands skip this post-command tab-list probe.
 - If a known session target unexpectedly reports about:blank, agent_browser best-effort re-selects the prior intended target when it still exists; if recovery fails, it records the observed about:blank target and reports exact recovery guidance instead of treating the prior page as active.

package/dist/extensions/agent-browser/index.js

@@ -10,14 +10,14 @@ import { fileURLToPath } from "node:url";
 import { Text } from "@earendil-works/pi-tui";
 import { PROJECT_RULE_PROMPT, buildBrowserDefaultProfileGuideline, buildBrowserExecutablePathGuideline, buildToolPromptGuidelines, } from "./lib/playbook.js";
 import { SessionPageState } from "./lib/session-page-state.js";
-import { createEphemeralSessionSeed, createFreshSessionName, createImplicitSessionName, extractCommandTokens, getImplicitSessionCloseTimeoutMs, getImplicitSessionIdleTimeoutMs, extractExplicitSessionName, restoreManagedSessionStateFromBranch, validateToolArgs, } from "./lib/runtime.js";
+import { createEphemeralSessionSeed, createFreshSessionName, createImplicitSessionName, extractCommandTokens, extractExplicitNamespace, getImplicitSessionCloseTimeoutMs, getImplicitSessionIdleTimeoutMs, extractExplicitSessionName, restoreManagedSessionStateFromBranch, validateToolArgs, } from "./lib/runtime.js";
 import { isRecord } from "./lib/parsing.js";
 import { buildPromptPolicy, getLatestUserPrompt, shouldAppendBrowserSystemPrompt } from "./lib/prompt-policy.js";
 import { isCloseCommand } from "./lib/command-taxonomy.js";
 import { cleanupSecureTempArtifacts, } from "./lib/temp.js";
 import { AGENT_BROWSER_PARAMS, } from "./lib/input-modes.js";
 import { parseAllowedDomainsPolicyFromArgs } from "./lib/navigation-policy.js";
-import { closeManagedSession, runAgentBrowserTool } from "./lib/orchestration/browser-run.js";
+import { closeManagedSession, getSessionContextKey, runAgentBrowserTool } from "./lib/orchestration/browser-run.js";
 import { findElectronLaunchRecordForSession, getActiveElectronRecords } from "./lib/orchestration/browser-run/session-state.js";
 import { parseBatchStdinJsonArray } from "./lib/orchestration/batch-stdin.js";
 import { ELECTRON_POST_COMMAND_STATUS_SETTLE_MS, ELECTRON_PROFILE_ISOLATION_DETAILS, cleanupActiveElectronHostLaunches, handleElectronHostInput, restoreElectronLaunchRecordsFromBranch, } from "./lib/orchestration/electron-host/index.js";
@@ -95,6 +95,8 @@ function restoreAllowedDomainsBySessionFromBranch(branch) {
         const args = getToolResultArgs(details);
         const command = typeof details.command === "string" ? details.command : extractCommandTokens(args)[0];
         const sessionName = typeof details.sessionName === "string" ? details.sessionName : undefined;
+        const namespace = typeof details.namespace === "string" ? details.namespace : undefined;
+        const sessionKey = getSessionContextKey(sessionName, namespace);
         const explicitSessionName = extractExplicitSessionName(args);
         const outcome = getManagedSessionOutcome(details);
         const outcomeSucceeded = outcome?.succeeded === true;
@@ -104,17 +106,18 @@ function restoreAllowedDomainsBySessionFromBranch(branch) {
         if (outcomeSucceeded && outcomeStatus === "closed") {
             const closedSessionName = outcomeAttemptedSessionName ?? outcomeCurrentSessionName ?? sessionName;
             if (closedSessionName)
-                restoredPolicies.delete(closedSessionName);
+                restoredPolicies.delete(getSessionContextKey(closedSessionName, namespace) ?? closedSessionName);
         }
         if (outcomeSucceeded && outcomeStatus === "replaced") {
             const replacedSessionName = typeof outcome.replacedSessionName === "string" ? outcome.replacedSessionName : undefined;
+            const replacedSessionNamespace = typeof outcome.replacedSessionNamespace === "string" ? outcome.replacedSessionNamespace : namespace;
             if (replacedSessionName)
-                restoredPolicies.delete(replacedSessionName);
+                restoredPolicies.delete(getSessionContextKey(replacedSessionName, replacedSessionNamespace) ?? replacedSessionName);
         }
         if (succeeded && isCloseCommand(command)) {
             const closedSessionName = explicitSessionName ?? sessionName ?? outcomeAttemptedSessionName ?? outcomeCurrentSessionName;
             if (closedSessionName)
-                restoredPolicies.delete(closedSessionName);
+                restoredPolicies.delete(getSessionContextKey(closedSessionName, namespace) ?? closedSessionName);
         }
         const electron = isRecord(details.electron) ? details.electron : undefined;
         const cleanup = isRecord(electron?.cleanup) ? electron.cleanup : undefined;
@@ -126,22 +129,27 @@ function restoreAllowedDomainsBySessionFromBranch(branch) {
         const outcomeKeepsSessionCurrent = outcome?.activeAfter === true
             && (outcomeStatus === "created" || outcomeStatus === "replaced" || outcomeStatus === "unchanged")
             && outcomeCurrentSessionName === sessionName;
-        const policy = (succeeded || outcomeKeepsSessionCurrent) && sessionName && !isCloseCommand(command) ? parseAllowedDomainsPolicyFromArgs(args) : undefined;
-        if (policy && sessionName)
-            restoredPolicies.set(sessionName, policy);
+        const policy = (succeeded || outcomeKeepsSessionCurrent) && sessionKey && !isCloseCommand(command) ? parseAllowedDomainsPolicyFromArgs(args) : undefined;
+        if (policy && sessionKey)
+            restoredPolicies.set(sessionKey, policy);
     }
     return restoredPolicies;
 }
 function trackOwnedManagedSession(sessions, sessionName, cwd, options = {}) {
     if (!sessionName)
         return;
-    const existing = sessions.get(sessionName);
+    const key = getSessionContextKey(sessionName, options.namespace) ?? sessionName;
+    const existing = sessions.get(key);
     const branchOwned = existing && !existing.branchOwned ? false : options.branchOwned === true;
-    sessions.set(sessionName, { branchOwned, cwd });
+    sessions.set(key, { branchOwned, cwd, namespace: options.namespace, sessionName });
 }
-function untrackOwnedManagedSession(sessions, sessionName) {
-    if (sessionName)
+function untrackOwnedManagedSession(sessions, sessionName, namespace) {
+    if (!sessionName)
+        return;
+    if (sessionName.includes("\u0000"))
         sessions.delete(sessionName);
+    else
+        sessions.delete(getSessionContextKey(sessionName, namespace) ?? sessionName);
 }
 function untrackOwnedManagedSessionFromBranchClose(sessions, sessionName, activeBranchRank, closeBranchRank) {
     if (!sessionName || closeBranchRank === undefined)
@@ -163,7 +171,8 @@ function syncOwnedManagedSessionsFromResult(sessions, result, cwd) {
     const currentSessionName = typeof outcome.currentSessionName === "string" ? outcome.currentSessionName : undefined;
     const attemptedSessionName = typeof outcome.attemptedSessionName === "string" ? outcome.attemptedSessionName : undefined;
     if (outcome.activeAfter === true && (status === "created" || status === "replaced" || status === "unchanged")) {
-        trackOwnedManagedSession(sessions, currentSessionName, cwd);
+        const namespace = isRecord(details) && typeof details.namespace === "string" ? details.namespace : undefined;
+        trackOwnedManagedSession(sessions, currentSessionName, cwd, { namespace });
     }
     if (succeeded && status === "closed") {
         untrackOwnedManagedSession(sessions, attemptedSessionName ?? currentSessionName);
@@ -320,6 +329,7 @@ function collectBranchManagedResourceEvents(branch) {
         const args = Array.isArray(details.args) && details.args.every((arg) => typeof arg === "string") ? details.args : [];
         const command = typeof details.command === "string" ? details.command : extractCommandTokens(args)[0];
         const sessionName = typeof details.sessionName === "string" ? details.sessionName : undefined;
+        const namespace = typeof details.namespace === "string" ? details.namespace : undefined;
         const sessionMode = details.sessionMode === "fresh" || details.sessionMode === "auto" ? details.sessionMode : undefined;
         const usedImplicitSession = details.usedImplicitSession === true;
         const explicitSessionName = extractExplicitSessionName(args);
@@ -329,19 +339,20 @@ function collectBranchManagedResourceEvents(branch) {
         const outcomeCurrentSessionName = typeof outcome?.currentSessionName === "string" ? outcome.currentSessionName : undefined;
         const outcomeAttemptedSessionName = typeof outcome?.attemptedSessionName === "string" ? outcome.attemptedSessionName : undefined;
         if (outcomeSucceeded && outcome.activeAfter === true && (outcomeStatus === "created" || outcomeStatus === "replaced" || outcomeStatus === "unchanged")) {
-            setBranchRankForString(events.managedSessionActiveRanks, outcomeCurrentSessionName, eventRank);
+            setBranchRankForString(events.managedSessionActiveRanks, getSessionContextKey(outcomeCurrentSessionName, namespace), eventRank);
         }
         if (outcomeSucceeded && outcomeStatus === "closed") {
-            setBranchRankForString(events.managedSessionCloseRanks, outcomeAttemptedSessionName ?? outcomeCurrentSessionName ?? sessionName, eventRank);
+            setBranchRankForString(events.managedSessionCloseRanks, getSessionContextKey(outcomeAttemptedSessionName ?? outcomeCurrentSessionName ?? sessionName, namespace), eventRank);
         }
         if (outcomeSucceeded && outcomeStatus === "replaced") {
-            setBranchRankForString(events.managedSessionCloseRanks, outcome.replacedSessionName, eventRank);
+            const replacedSessionNamespace = typeof outcome.replacedSessionNamespace === "string" ? outcome.replacedSessionNamespace : namespace;
+            setBranchRankForString(events.managedSessionCloseRanks, getSessionContextKey(typeof outcome.replacedSessionName === "string" ? outcome.replacedSessionName : undefined, replacedSessionNamespace), eventRank);
         }
         if (succeeded && !isCloseCommand(command) && sessionName && (usedImplicitSession || sessionMode === "fresh")) {
-            events.managedSessionActiveRanks.set(sessionName, eventRank);
+            events.managedSessionActiveRanks.set(getSessionContextKey(sessionName, namespace) ?? sessionName, eventRank);
         }
         if (succeeded && isCloseCommand(command)) {
-            setBranchRankForString(events.managedSessionCloseRanks, explicitSessionName ?? sessionName ?? outcomeAttemptedSessionName ?? outcomeCurrentSessionName, eventRank);
+            setBranchRankForString(events.managedSessionCloseRanks, getSessionContextKey(explicitSessionName ?? sessionName ?? outcomeAttemptedSessionName ?? outcomeCurrentSessionName, namespace), eventRank);
         }
         const electron = isRecord(details.electron) ? details.electron : undefined;
         const launch = electron && isElectronLaunchRecord(electron.launch) ? electron.launch : undefined;
@@ -384,13 +395,14 @@ function syncElectronCleanupManagedSessions(sessions, cleanupResults) {
         untrackOwnedManagedSession(sessions, sessionName);
     }
 }
-async function closeOwnedManagedSessionsExcept(sessions, keepSessionName, timeoutMs) {
-    for (const [sessionName, owner] of [...sessions]) {
-        if (sessionName === keepSessionName)
+async function closeOwnedManagedSessionsExcept(sessions, keepSessionName, timeoutMs, keepNamespace) {
+    const keepKey = getSessionContextKey(keepSessionName, keepNamespace);
+    for (const [key, owner] of [...sessions]) {
+        if (key === keepKey)
             continue;
-        const error = await closeManagedSession({ cwd: owner.cwd, sessionName, timeoutMs });
+        const error = await closeManagedSession({ cwd: owner.cwd, namespace: owner.namespace, sessionName: owner.sessionName, timeoutMs });
         if (!error)
-            sessions.delete(sessionName);
+            sessions.delete(key);
     }
 }
 async function closeOwnedManagedSessions(sessions, timeoutMs) {
@@ -410,7 +422,7 @@ function shouldSerializeBrowserCommand(options) {
         return true;
     if (options.explicitSessionName === options.managedSessionName)
         return true;
-    if (options.ownedManagedSessions.has(options.explicitSessionName))
+    if (options.ownedManagedSessions.has(getSessionContextKey(options.explicitSessionName, options.explicitNamespace) ?? options.explicitSessionName))
         return true;
     return getActiveElectronRecords(options.ownedElectronLaunchRecords).some((record) => record.sessionName === options.explicitSessionName);
 }
@@ -470,6 +482,7 @@ export default function agentBrowserExtension(pi) {
     let managedSessionBaseName = createImplicitSessionName(undefined, process.cwd(), ephemeralSessionSeed);
     let managedSessionName = managedSessionBaseName;
     let managedSessionCwd = process.cwd();
+    let managedSessionNamespace;
     let freshSessionOrdinal = 0;
     let sessionPageState = new SessionPageState();
     let traceOwners = new Map();
@@ -483,10 +496,11 @@ export default function agentBrowserExtension(pi) {
     const ownedManagedSessions = new Map();
     const managedSessionExecutionQueue = new AsyncExecutionQueue();
     let branchStateGeneration = 0;
-    const clearSessionScopedBrowserState = (sessionName) => {
-        allowedDomainsBySession.delete(sessionName);
-        networkRoutesBySession.delete(sessionName);
-        sessionPageState.clearSession(sessionName);
+    const clearSessionScopedBrowserState = (sessionName, namespace) => {
+        const key = getSessionContextKey(sessionName, namespace) ?? sessionName;
+        allowedDomainsBySession.delete(key);
+        networkRoutesBySession.delete(key);
+        sessionPageState.clearSession(key);
     };
     const restoreBranchBackedState = (ctx, options) => {
         branchStateGeneration += 1;
@@ -516,6 +530,7 @@ export default function agentBrowserExtension(pi) {
                 ? previousManagedSessionName
                 : createFreshSessionName(managedSessionBaseName, ephemeralSessionSeed, nextFreshSessionOrdinal)
             : restoredState.sessionName;
+        managedSessionNamespace = shouldReservePostCloseSession ? undefined : restoredState.namespace;
         managedSessionCwd = ctx.cwd;
         freshSessionOrdinal = nextFreshSessionOrdinal;
         sessionPageState = SessionPageState.fromBranch(branch);
@@ -536,7 +551,7 @@ export default function agentBrowserExtension(pi) {
             removeInactiveOwnedElectronLaunchRecords(ownedElectronLaunchRecords, branchOwnedElectronLaunchIds, electronLaunchRecords, branchResourceEvents.electronLaunchActiveRanks, branchResourceEvents.electronLaunchCleanupRanks);
         }
         if (restoredState.active) {
-            trackOwnedManagedSession(ownedManagedSessions, restoredState.sessionName, ctx.cwd, { branchOwned: true });
+            trackOwnedManagedSession(ownedManagedSessions, restoredState.sessionName, ctx.cwd, { branchOwned: true, namespace: restoredState.namespace });
         }
         mergeActiveElectronLaunchRecords(ownedElectronLaunchRecords, electronLaunchRecords, {
             branchOwnedLaunchIds: branchOwnedElectronLaunchIds,
@@ -595,10 +610,11 @@ export default function agentBrowserExtension(pi) {
                 await closeOwnedManagedSessions(ownedManagedSessions, implicitSessionCloseTimeoutMs);
             }
             else {
-                await closeOwnedManagedSessionsExcept(ownedManagedSessions, managedSessionActive ? managedSessionName : undefined, implicitSessionCloseTimeoutMs);
+                await closeOwnedManagedSessionsExcept(ownedManagedSessions, managedSessionActive ? managedSessionName : undefined, implicitSessionCloseTimeoutMs, managedSessionActive ? managedSessionNamespace : undefined);
             }
         });
         managedSessionActive = false;
+        managedSessionNamespace = undefined;
         sessionPageState.reset();
         traceOwners = new Map();
         artifactManifest = undefined;
@@ -721,6 +737,7 @@ export default function agentBrowserExtension(pi) {
                         clearSessionScopedBrowserState(closedSessionName);
                         if (closedSessionName === managedSessionName) {
                             managedSessionActive = false;
+                            managedSessionNamespace = undefined;
                             freshSessionOrdinal += 1;
                             managedSessionName = createFreshSessionName(managedSessionBaseName, ephemeralSessionSeed, freshSessionOrdinal);
                         }
@@ -735,7 +752,9 @@ export default function agentBrowserExtension(pi) {
                 return applyAgentBrowserOutputPath({ cwd: ctx.cwd, outputPath, result: electronHostResult });
             }
             const explicitSessionName = extractExplicitSessionName(toolArgs);
+            const explicitNamespace = extractExplicitNamespace(toolArgs);
             const serializeBrowserCommand = shouldSerializeBrowserCommand({
+                explicitNamespace,
                 explicitSessionName,
                 managedSessionName,
                 ownedElectronLaunchRecords,
@@ -756,6 +775,7 @@ export default function agentBrowserExtension(pi) {
                     managedSessionBaseName,
                     managedSessionCwd,
                     managedSessionName,
+                    managedSessionNamespace,
                     networkRoutesBySession,
                     sessionPageState,
                     traceOwners,
@@ -784,6 +804,7 @@ export default function agentBrowserExtension(pi) {
                     managedSessionActive = browserRunState.managedSessionActive;
                     managedSessionCwd = browserRunState.managedSessionCwd;
                     managedSessionName = browserRunState.managedSessionName;
+                    managedSessionNamespace = browserRunState.managedSessionNamespace;
                     for (const closedSessionName of browserRunState.closedManagedSessionNames) {
                         untrackOwnedManagedSession(ownedManagedSessions, closedSessionName);
                     }

package/dist/extensions/agent-browser/lib/argv-descriptor.js

@@ -3,7 +3,7 @@
  * Responsibilities: Own command-token extraction, command/subcommand identification, and descriptor construction.
  * Scope: Pure argv parsing; runtime planning and session policy consume descriptors instead of re-parsing tokens.
  */
-import { GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, VALUE_FLAGS } from "./argv-grammar.js";
+import { GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, VALUE_FLAGS, optionalGlobalValueFlagConsumesNext } from "./argv-grammar.js";
 import { isOpenNavigationCommand } from "./command-taxonomy.js";
 function isBooleanLiteral(token) {
     const normalized = token?.trim().toLowerCase();
@@ -12,12 +12,15 @@ function isBooleanLiteral(token) {
 export function findCommandStartIndex(args) {
     for (let index = 0; index < args.length; index += 1) {
         const token = args[index];
-        if (token.startsWith("--session=")) {
+        if (token.startsWith("--session=") || token.startsWith("--namespace=") || token.startsWith("--restore=")) {
             continue;
         }
         if (token.startsWith("-")) {
             const normalizedToken = token.split("=", 1)[0] ?? token;
-            if (VALUE_FLAGS.has(normalizedToken) && !token.includes("=")) {
+            if (optionalGlobalValueFlagConsumesNext(normalizedToken, args[index + 1])) {
+                index += 1;
+            }
+            else if (VALUE_FLAGS.has(normalizedToken) && !token.includes("=")) {
                 index += 1;
             }
             else if (GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES.has(normalizedToken) &&

package/dist/extensions/agent-browser/lib/argv-grammar.js

@@ -3,12 +3,18 @@
  * Responsibilities: Own global/command value-flag sets and boolean/value-flag validation used during argv parsing.
  * Scope: Pure token grammar; command semantics and subprocess execution live elsewhere.
  */
+import { isKnownCommandToken } from "./command-taxonomy.js";
 export const GLOBAL_VALUE_FLAGS = [
     "--session",
+    "--namespace",
     "--cdp",
     "--config",
     "--profile",
     "--session-name",
+    "--restore-save",
+    "--restore-check-url",
+    "--restore-check-text",
+    "--restore-check-fn",
     "--proxy",
     "--proxy-bypass",
     "--headers",
@@ -52,11 +58,13 @@ export const COMMAND_VALUE_FLAGS = [
     "--name",
     "--older-than",
     "--output",
+    "--prefix",
     "--path",
     "--port",
     "--resource-type",
     "--resource-types",
     "--sameSite",
+    "--scope",
     "--selector",
     "-s",
     "--status",
@@ -69,6 +77,7 @@ export const COMMAND_VALUE_FLAGS = [
     "--password",
     "--wait-until",
 ];
+export const OPTIONAL_GLOBAL_VALUE_FLAGS = new Set(["--restore"]);
 export const VALUE_FLAGS = new Set([...GLOBAL_VALUE_FLAGS, ...COMMAND_VALUE_FLAGS]);
 export const PREVALIDATED_VALUE_FLAGS = new Set(GLOBAL_VALUE_FLAGS);
 export const GLOBAL_VALUE_FLAGS_ALLOWING_DASH_VALUE = new Set(["--args"]);
@@ -116,6 +125,25 @@ export function hasOnlyOptionFlags(tokens, allowedBooleanFlags, allowedValueFlag
     }
     return true;
 }
+export function optionalGlobalValueFlagConsumesNext(flag, nextToken) {
+    if (!OPTIONAL_GLOBAL_VALUE_FLAGS.has(flag) || nextToken === undefined || nextToken.startsWith("-"))
+        return false;
+    return !isKnownCommandToken(nextToken);
+}
 export function stripSessionlessShapeGlobalFlags(commandTokens) {
-    return commandTokens.filter((token) => token !== "--json");
+    const stripped = [];
+    for (let index = 0; index < commandTokens.length; index += 1) {
+        const token = commandTokens[index];
+        const flagName = getFlagName(token);
+        if (token === "--json")
+            continue;
+        if ((flagName === "--session" || flagName === "--namespace") && !token.includes("=")) {
+            index += 1;
+            continue;
+        }
+        if (token.startsWith("--session=") || token.startsWith("--namespace="))
+            continue;
+        stripped.push(token);
+    }
+    return stripped;
 }

package/dist/extensions/agent-browser/lib/command-policy.js

@@ -16,6 +16,7 @@ const DOCTOR_BOOLEAN_FLAGS = new Set(["--fix", "--json", "--offline", "--quick"]
 const INSTALL_BOOLEAN_FLAGS = new Set(["--with-deps", "-d"]);
 const STATE_SESSIONLESS_SUBCOMMANDS = new Set(["list", "show", "clear", "clean", "rename"]);
 const STATE_CLEAN_VALUE_FLAGS = new Set(["--older-than"]);
+const SESSION_ID_VALUE_FLAGS = new Set(["--scope", "--prefix"]);
 function isSessionlessAuthCommand(commandTokens) {
     const [, subcommand, target, ...rest] = commandTokens;
     if (!SESSIONLESS_AUTH_SUBCOMMANDS.has(subcommand ?? ""))
@@ -64,6 +65,14 @@ function isSessionlessPluginCommand(commandTokens) {
         return true;
     return PLUGIN_SESSIONLESS_SUBCOMMANDS.has(subcommand);
 }
+function isSessionlessSessionCommand(commandTokens) {
+    const [, subcommand, ...rest] = commandTokens;
+    if (subcommand === "list" || subcommand === "info")
+        return rest.length === 0;
+    if (subcommand === "id")
+        return hasOnlyOptionFlags(rest, JSON_BOOLEAN_FLAGS, SESSION_ID_VALUE_FLAGS);
+    return false;
+}
 function isSessionlessCommand(commandTokens) {
     const normalizedTokens = stripSessionlessShapeGlobalFlags(commandTokens);
     const [command, subcommand] = normalizedTokens;
@@ -86,7 +95,7 @@ function isSessionlessCommand(commandTokens) {
     if (command === "profiles" || command === "upgrade")
         return normalizedTokens.length === 1;
     if (command === "session")
-        return normalizedTokens.length === 2 && subcommand === "list";
+        return isSessionlessSessionCommand(normalizedTokens);
     if (command === "state")
         return isSessionlessStateCommand(normalizedTokens);
     return false;

package/dist/extensions/agent-browser/lib/command-taxonomy.js

@@ -4,6 +4,9 @@
  * session/ref guards, result recommendations, and presentation summaries without coupling unrelated behaviors.
  * Scope: Static command capability taxonomy only; command-shape parsing, spawning, and formatting live elsewhere.
  */
+const ADDITIONAL_COMMAND_TOKENS = [
+    "auth", "chat", "clipboard", "confirm", "connect", "dashboard", "deny", "device", "dialog", "diff", "doctor", "errors", "eval", "find", "frame", "get", "highlight", "inspect", "install", "is", "mcp", "plugin", "plugins", "profiles", "profiler", "react", "read", "record", "removeinitscript", "session", "set", "skills", "snapshot", "state", "stream", "trace", "upgrade", "vitals", "wait", "web-vitals", "window",
+];
 const COMMAND_CAPABILITIES = [
     {
         command: "back",
@@ -258,6 +261,10 @@ for (const entry of COMMAND_CAPABILITIES) {
         COMMAND_CAPABILITY_BY_NAME.set(alias, entry);
     }
 }
+const KNOWN_COMMAND_TOKENS = new Set([...COMMAND_CAPABILITY_BY_NAME.keys(), ...ADDITIONAL_COMMAND_TOKENS]);
+export function isKnownCommandToken(token) {
+    return KNOWN_COMMAND_TOKENS.has(token);
+}
 function getCommandCapability(command) {
     return command === undefined ? undefined : COMMAND_CAPABILITY_BY_NAME.get(command);
 }

package/dist/extensions/agent-browser/lib/input-modes/job.js

@@ -68,28 +68,6 @@ const JOB_STEP_ALLOWED_FIELDS = {
     wait: new Set(["action", "milliseconds"]),
     waitForDownload: new Set(["action", "path"]),
 };
-function globUrlPatternToRegexSource(pattern) {
-    let source = "^";
-    for (let index = 0; index < pattern.length; index += 1) {
-        const char = pattern.charAt(index);
-        if (char === "*") {
-            let runLength = 1;
-            while (pattern[index + runLength] === "*")
-                runLength += 1;
-            source += runLength === 1 ? "[^/]*" : ".*";
-            index += runLength - 1;
-        }
-        else {
-            source += char.replace(/[\\^$+?.()|[\]{}]/g, "\\$&");
-        }
-    }
-    return `${source}$`;
-}
-function compileJobAssertUrlArgs(url) {
-    if (!url.includes("*"))
-        return ["wait", "--url", url];
-    return ["wait", "--fn", `new RegExp(${JSON.stringify(globUrlPatternToRegexSource(url))}).test(location.href)`];
-}
 function compileJobTypeSteps(step) {
     const text = getRequiredJobString(step, "text", "type");
     if (text.error)
@@ -182,7 +160,7 @@ function compileAssertUrlJobStep(step) {
     const result = getRequiredJobString(step, "url", "assertUrl");
     if (result.error)
         return { error: result.error };
-    return { args: compileJobAssertUrlArgs(result.value) };
+    return { args: ["wait", "--url", result.value] };
 }
 function compilePathArtifactJobStep(step, action) {
     const result = getRequiredJobString(step, "path", action);

package/dist/extensions/agent-browser/lib/input-modes/lookups.js

@@ -259,12 +259,15 @@ export function compileAgentBrowserNetworkSourceLookup(input) {
         return { error: "networkSourceLookup must be an object." };
     const filter = input.filter;
     const requestId = input.requestId;
+    const namespace = input.namespace;
     const session = input.session;
     const url = input.url;
     if (filter !== undefined && (typeof filter !== "string" || filter.trim().length === 0))
         return { error: "networkSourceLookup.filter must be a non-empty string when provided." };
     if (requestId !== undefined && (typeof requestId !== "string" || requestId.trim().length === 0))
         return { error: "networkSourceLookup.requestId must be a non-empty string when provided." };
+    if (namespace !== undefined && (typeof namespace !== "string" || namespace.trim().length === 0))
+        return { error: "networkSourceLookup.namespace must be a non-empty string when provided." };
     if (session !== undefined && (typeof session !== "string" || session.trim().length === 0))
         return { error: "networkSourceLookup.session must be a non-empty string when provided." };
     if (url !== undefined && (typeof url !== "string" || url.trim().length === 0))
@@ -282,8 +285,8 @@ export function compileAgentBrowserNetworkSourceLookup(input) {
     if (effectiveFilter) {
         steps.push({ action: "network", args: ["network", "requests", "--filter", effectiveFilter] });
     }
-    const args = typeof session === "string" ? ["--session", session, "batch"] : ["batch"];
-    return { compiled: { args, query: { filter, maxWorkspaceFiles: maxWorkspaceFiles.value, requestId, session, url }, stdin: JSON.stringify(steps.map((step) => step.args)), steps } };
+    const args = [...(typeof namespace === "string" ? ["--namespace", namespace] : []), ...(typeof session === "string" ? ["--session", session] : []), "batch"];
+    return { compiled: { args, query: { filter, maxWorkspaceFiles: maxWorkspaceFiles.value, namespace, requestId, session, url }, stdin: JSON.stringify(steps.map((step) => step.args)), steps } };
 }
 function getResultPayload(item) {
     return isRecord(item.result) && "data" in item.result ? item.result.data : item.result;