browser-pilot-cli 0.3.0 → 0.5.0

package/docs/plans/browser-capability-evolution.md

@@ -299,11 +299,11 @@ Preserve Browser Pilot advantages:
 - [x] **B5.4** Update the universal skill with decision guidance grounded in
   actual tool errors and state, not framework-specific prompts.
   - Covers: FR-1, FR-8.
-  - Complete: the Agent-neutral skill now separates direct one-shot CLI use
-    from embedded stdio integration, starts from current tab/page state, uses
+  - Complete: the Agent-neutral skill now uses the same CLI workflow for
+    Agent-installed and product-bundled use, starts from current tab/page state, uses
     fresh refs, verifies action results, and gives explicit recovery decisions
-    for structured evidence, hints, stable errors, events, reconnects, dialogs,
-    and Artifacts. Command guidance now reflects all-tab inventory, explicit
+    for structured evidence, hints, stable errors, reconnects, dialogs, and
+    local file results. Command guidance now reflects all-tab inventory, explicit
     dialog handling, managed-only bulk cleanup, and actual local capture output.
     It names no Agent framework in its runtime decisions and adds no adapter or
     prompt-specific production behavior.
@@ -383,8 +383,8 @@ Preserve Browser Pilot advantages:
     `stagnant_page`; action parameters, typed values, page text, and hashes are
     not exposed.
 - [x] **B7.6** Keep the additions Agent-neutral and backward compatible.
-  - Complete: one-shot CLI commands and Broker `tools/list` share the canonical
-    implementations. The tools reuse existing capabilities and are additive
+  - Complete: all CLI commands use the Broker's canonical internal
+    implementations and schemas. The commands reuse existing capabilities and are additive
     for protocol 1.0/1.1. Multi-action queues, LLM extraction, planning, and
     memory remain Host-Agent responsibilities.
 

package/docs/plans/profile-context-routing.md

@@ -1,7 +1,7 @@
 # Profile Context Routing Plan
 
 Status: **Complete**
-Target: Browser Pilot `v0.3.0`, protocol `1.2`
+Target: Browser Pilot `v0.4.0`, protocol `1.3`
 Source of truth: `docs/architecture/browser-pilot-platform-spec.md`
 
 ## Goal
@@ -53,7 +53,8 @@ It has:
 - an internal raw CDP browser-context ID, never exposed;
 - the owning BrowserInstance and connection generation;
 - a connection-scoped neutral label;
-- an optional verified display name and Profile directory;
+- connection-generation-scoped identity status plus optional verified Profile
+  name, account name/email, and Profile directory;
 - current total and eligible tab counts;
 - one or more bounded representative targets for routing and user recognition.
 
@@ -99,10 +100,31 @@ Protocol 1.2 adds:
 Profile summaries and representative eligible tabs. It never opens, navigates,
 attaches to, or focuses a target merely to discover a display name.
 
+## Protocol 1.3
+
+Protocol 1.3 adds `browser.profiles.identify` as an explicit, mutating identity
+operation. For each requested unidentified Profile it creates a temporary
+visible `chrome://version` target in that exact context, reads `#profile_path`,
+verifies that path as an immediate child of the connected browser's
+`userDataRoot`, reads bounded metadata from Chrome `Local State`, then detaches
+and proves the temporary target was closed. Failure to prove cleanup returns
+`unknown_outcome`; Browser Pilot never silently leaves an identity page behind.
+
+Results use `identityStatus: unidentified | verified | unavailable` plus
+optional `profileName`, `accountName`, `accountEmail`, `profileDirectory`, and a
+stable `identityErrorCode`. Identity is cached only for the current browser
+connection generation. `refresh: true` explicitly re-probes. No directory
+ordering, tab title, or raw context ID is treated as account identity.
+
+Protocol 1.3 also renames browser candidate `profile` to `userDataRoot` and tab
+inventory `active` to `selected`. The latter is the Lease's logical target, not
+Chrome foreground focus. Protocol 1.2 clients retain their legacy fields.
+
 `browser.profiles.select` accepts only a public `profileContextId`. Human CLI
-selectors such as index, neutral label, or verified display name are resolved
+selectors such as one-based index, neutral label, or verified Profile/account
+name or email are resolved
 client-side from a fresh list. The machine protocol never accepts an ambiguous
-free-form selector. Selecting a Profile clears the Lease's logical active-target
+free-form selector. Selecting a Profile clears the Lease's logical selected-target
 anchor without releasing control or changing Chrome focus, so the next new
 managed target uses that explicit Workspace selection.
 
@@ -112,7 +134,7 @@ When `browser.open` needs a new target, resolve exactly one Profile context in
 this order:
 
 1. an explicit, current-generation `profileContextId`;
-2. the current Lease's active target context;
+2. the current Lease's selected target context;
 3. the Workspace's current, valid selection;
 4. the only currently available Profile context;
 5. otherwise fail with `profile_selection_required` before browser dispatch.
@@ -161,13 +183,13 @@ candidate targets were closed.
 - Protocol 1.0/1.1 clients continue to list and control existing tabs.
 - In a single available context, their existing `browser.open` behavior remains
   automatic.
-- In multiple contexts, an active target remains an unambiguous anchor.
+- In multiple contexts, a selected target remains an unambiguous anchor.
 - With multiple contexts and no anchor, older clients receive a structured
   failure and Browser Pilot never silently chooses the first context.
 - New Profile fields on existing results are additive; raw CDP IDs remain
   private.
-- The current CLI negotiates protocol 1.2, while the Broker continues to accept
-  1.0 and 1.1.
+- The current CLI negotiates protocol 1.3, while the Broker continues to accept
+  1.0 through 1.2.
 
 ## Delivery
 
@@ -176,7 +198,7 @@ candidate targets were closed.
 - [x] P2: implement Profile context registry, target propagation, Workspace
   selection, multiple ManagedTabSets, and janitor adoption.
 - [x] P3: implement `bp profiles`, `bp profile`, and `bp open --profile`.
-- [x] P4: update stdio integration guidance, adapters, skill, and release docs.
+- [x] P4: update CLI integration guidance, skill, and release docs.
 - [x] P5: add protocol, dual-Profile, concurrency, reconnect, cleanup, and
   compatibility tests.
 - [x] P6: run real Chrome acceptance and publish `v0.3.0-rc.2`.
@@ -186,13 +208,16 @@ candidate targets were closed.
 - [x] All eligible user tabs across live Profile contexts appear in one inventory.
 - [x] Existing user tabs can be controlled without selecting a Profile first.
 - [x] No multi-context open silently selects a first Profile.
-- [x] Explicit, active-target, Workspace, and single-context resolution follow the
+- [x] Explicit, selected-target, Workspace, and single-context resolution follow the
   specified order.
 - [x] Every managed target and popup matches its ManagedTabSet Profile context.
 - [x] Two Workspaces may select different contexts and create targets concurrently
   without cross-routing.
 - [x] Reconnect invalidates old Profile IDs, target mappings, frames, and refs.
 - [x] Passive listing creates no target and never focuses or navigates a user tab.
+- [x] Explicit identity verifies Profile paths, returns structured account-aware
+  fields, cleans temporary targets, caches only within one connection
+  generation, and never guesses unavailable metadata.
 - [x] Janitor EOF/SIGKILL cleanup closes fallback-created managed windows but never
   user tabs.
 - [x] Protocol 1.1 clients retain existing-tab control and cannot open ambiguously.

package/docs/plans/universal-agent-integration.md

@@ -1,339 +1,125 @@
-# Universal Agent Integration Plan
+# Universal Agent CLI Integration Plan
 
-Status: **Complete**
-Source of truth: `docs/architecture/browser-pilot-platform-spec.md`  
-Workstream: A
+Status: implementation and local release verification complete for the
+CLI-only architecture; formal publication remains.
 
 ## Goal
 
-Deliver the executable, Broker, machine protocol, distribution contract, and
-conformance assets required for any local Agent to install or embed Browser
-Pilot. Tenon and OpenClaw are reference consumers only.
-
-## Scope Guardrails
-
-- Preserve existing one-shot CLI workflows under **FR-1**.
-- Expose only the executable protocol under **DEC-3**; do not publish a Native
-  SDK or MCP server.
-- Do not place Agent-specific lifecycle nouns or payloads in production code.
-- Do not improve page understanding in this workstream except where needed to
-  preserve the shared Observation contract.
-- Coordinate all changes to Observation/ref identity with Workstream B.
-- Keep Broker-created ManagedTabSets as the default independent task surface,
-  while including every eligible user tab in the same inventory. Never add an
-  Agent-callable raw-CDP `adopt(targetId)` shortcut.
-
-## Delivery Order
-
-### A0. Freeze the shared contract
-
-- [x] **A0.1** Publish the platform specification with stable decisions,
-  requirements, rules, and acceptance criteria.
-  - Covers: DEC-1 through DEC-7, FR-1 through FR-8.
-  - Verification: product-spec inspection and contradiction review.
-- [x] **A0.2** Encode protocol versions, capabilities, domain identifiers,
-  result envelopes, stable errors, and Artifact/Event descriptors as internal
-  TypeScript types and runtime validators.
-  - Covers: FR-2, FR-5, FR-6, FR-7.
-  - Acceptance: incompatible versions and malformed messages fail with stable
-    codes; unknown fields follow the compatibility rules.
-- [x] **A0.3** Publish the canonical machine-readable tool manifest and schema
-  snapshots used by bridge and conformance tests.
-  - Covers: FR-2, NFR-1.
-  - Acceptance: `tools/list` output is generated from the same definitions used
-    to validate `tools/call`.
-
-### A1. Extract the internal service boundary
-
-- [x] **A1.1** Move browser discovery, target operations, observations,
-  actions, capture, network, auth, and cookies out of Commander handlers into
-  `BrowserPilotService` modules.
-  - Covers: FR-1, FR-2.
-  - Acceptance: CLI handlers contain parsing and formatting only; existing CLI
-    fixture behavior remains unchanged.
-  - Complete: every Commander handler now performs only parsing, compatibility
-    formatting, and explicit client-owned file export. Browser discovery,
-    target/session/frame state, observations, actions, capture, upload, tabs,
-    dialogs, auth, cookies, and network operations execute through the same
-    canonical Broker tools used by embedded clients.
-- [x] **A1.2** Replace process exits and console/file side effects below the CLI
-  adapter with typed results, stable errors, and Artifact operations.
-  - Covers: FR-2, FR-6, NFR-1.
-  - Complete: protected screenshot/PDF/upload bytes cross the CLI boundary only
-    through Artifact import/export/release; services return typed data and
-    stable errors without console, process-exit, or destination-file effects.
-- [x] **A1.3** Make arbitrary CDP forwarding private and gate page evaluation
-  behind `developer.eval` for machine clients.
-  - Covers: DEC-5, CON-4, AC-4.
-  - Complete: public CLI and stdio clients expose only canonical high-level
-    operations. The daemon's CDP transport remains an internal implementation
-    endpoint, and public evaluation requires `developer.eval`.
-
-### A2. Build Broker domain isolation
-
-- [x] **A2.1** Implement ClientPrincipal, ClientConnection,
-  BrowserWorkspace, ManagedTabSet, ControlLease, BrowserInstance,
-  and ControlledTarget registries.
-  - Covers: FR-3, FR-4, FR-5.
-  - Complete: the daemon owns bounded in-memory Principal, Connection,
-    Workspace, default ManagedTabSet, and Lease registries. Principal identity
-    survives a bridge reconnect within one daemon lifetime; Connection-owned
-    Leases do not.
-- [x] **A2.2** Create managed targets only through the control registry and
-  validate the complete popup opener chain before adoption.
-  - Covers: BR-1, BR-2, AC-4.
-  - Progress: legacy CLI popup adoption now requires a complete opener chain
-    ending at an already controlled Pilot target. Workspace control registry and
-    Broker-only target creation remain.
-  - Progress: the Broker inventory foundation now adopts managed popups only
-    through a complete live opener chain and refuses to cross a user-tab record.
-  - Complete: machine-created targets enter through `BrowserToolService` and
-    `MemoryControlledTargetRegistry`; no public machine call accepts a raw CDP
-    target ID.
-- [x] **A2.3** Replace global target/frame/session state with Workspace and
-  Lease state; provide a compatibility Workspace for one-shot CLI calls.
-  - Covers: FR-1, FR-3, AC-1, AC-3.
-  - Complete: the CLI uses a fixed daemon-internal one-shot Connection plus
-    idempotently keyed compatibility Workspace and renewable five-minute Lease.
-    Every CLI command calls canonical tools; active targets, frames, sessions,
-    Observations, refs, auth, rules, and request identity remain only in daemon
-    memory. No `state.json` or `refs.json` compatibility mapping remains.
-- [x] **A2.4** Serialize commands through a per-target actor and implement
-  explicit control transfer.
-  - Covers: BR-5, BR-6, NFR-4.
-  - Complete: reads and mutations for one physical CDP target share the same
-    actor across Workspace-local opaque IDs, while different physical targets
-    proceed concurrently. `browser.tabs.release` provides idempotent two-step
-    handoff: the owner releases and fully retires its scoped target session,
-    then another Lease acquires through its own opaque ID. Foreign Lease IDs,
-    silent stealing, and tab closure are not part of transfer.
-- [x] **A2.5** Scope auth, network rules, request journals, downloads, and
-  cleanup to their owner.
-  - Covers: BR-3, BR-4, AC-3.
-  - Complete: Broker auth, interception rules, and bounded request journals are
-    Workspace scoped; request identity includes CDP session identity, sensitive
-    events are metadata-only, and legacy daemon handlers ignore Broker sessions.
-    Lease replacement preserves Workspace configuration while Workspace release
-    clears it. Downloads preserve each Profile's Chrome default directory;
-    Page events bind GUID ownership to controlled sessions, browser-level
-    completion paths are copied into bounded Workspace-owned Artifacts, and
-    cleanup deletes only the copy without cancelling or moving user downloads.
-- [x] **A2.6** Implement the default-unrestricted BrowserControlPolicy and
-  optional launch-time Host operation removal.
-  - Covers: FLOW-5, BR-21, BR-22, AC-4.
-  - Acceptance: no request/grant/approval lifecycle exists; every supported
-    operation is available by default; explicitly denied operations fail with
-    `capability_denied` before CDP dispatch.
-  - Complete: `createBrowserControlPolicy` exposes all eligible user tabs and
-    validates optional `deniedOperations` without any Agent-specific policy.
-- [x] **A2.7** Build eligible user-tab discovery and internal-target exclusion.
-  - Covers: CON-2, FLOW-5, BR-2, BR-25, BR-26, FR-4.
-  - Acceptance: current and future ordinary tabs are returned, while managed
-    targets, Browser Pilot internal targets, DevTools, unsupported internal
-    pages, and non-page targets are excluded.
-  - Complete: `CdpBrowserTargetCatalog` implements the CDP catalog boundary.
-- [x] **A2.8** Merge ManagedTabSets and all eligible user tabs in
-  ControlledTarget resolution, listing, switching, and popup inheritance.
-  - Covers: BR-1, BR-2, BR-23 through BR-27.
-  - Acceptance: `tabs.list` returns managed and user tabs with
-    origin metadata; conflicting control reports `target_busy`; bulk cleanup
-    closes only managed tabs; closing a user tab is explicit.
-  - Complete: `MemoryControlledTargetRegistry`, `TargetInventoryService`, and
-    `CdpBrowserTargetCatalog` now provide opaque per-Workspace target IDs,
-    immediate managed/user inventory merging, dynamic new-tab discovery,
-    physical-target Lease exclusion across Principals, ineligible-target
-    invalidation, managed-popup inheritance, and safe managed-only bulk close.
-    `tools/call` now lists, switches to, and explicitly closes both origins;
-    Workspace release closes only managed targets. The compatibility CLI
-    retains the same all-tab behavior.
-
-### A3. Add bounded runtime lifecycle and command semantics
-
-- [x] **A3.1** Add in-memory Workspace, Lease, target assignment, command,
-  idempotency, and bounded journal stores.
-  - Covers: FR-5, NFR-2, NFR-5.
-  - Complete: Workspace, Lease, target assignment, Command, idempotency, and
-    per-Workspace event stores are bounded and live in daemon memory.
-- [x] **A3.2** Implement heartbeat, expiry, release, crash recovery, and
-  idempotent cleanup for Workspaces and Leases.
-  - Covers: AC-5, NFR-5.
-  - Broker restart invalidates transient state; clients initialize, list, and
-    observe again. Do not recover stale browser state from disk.
-  - Complete: Lease heartbeat/expiry/release, EOF cleanup, idle Connection and
-    Workspace reclamation, and idempotent Workspace release are implemented.
-    Target, auth, network, frame, Observation, Artifact, and partial download
-    cleanup is connected. Browser connection loss now rejects tools, invalidates
-    sessions/refs, passively rediscovers the selected profile, and advances
-    generation only after an explicit reconnect succeeds. A private child janitor solely owns the browser-level CDP
-    connection, proxies daemon traffic over IPC, tracks verified managed popup
-    descendants, and closes them on daemon-pipe EOF, including `SIGKILL`,
-    without persisting target IDs or grouping by browser window. Process-level
-    tests prove user tabs survive and only one browser WebSocket is opened.
-- [x] **A3.3** Implement command accepted/dispatched/completed,
-  `unknown_outcome`, deadline, cancellation, and duplicate-call behavior.
-  - Covers: BR-8 through BR-12, AC-5.
-  - Complete: caller or Broker IDs, Workspace-scoped idempotency, bounded
-    terminal outcomes, pre-dispatch cancellation, best-effort post-dispatch
-    cancellation, deadlines, cached results, and no-replay unknown outcomes are
-    enforced through the public bridge.
-- [x] **A3.4** Replace dialog auto-acceptance with typed events and explicit
-  accept/dismiss commands.
-  - Covers: DEC-5, event contract.
-  - Complete: dialogs stay pending, emit opened/closed events, and can be listed
-    and explicitly accepted or dismissed through out-of-band dialog tools.
-    One-shot CLI dialogs use those same Workspace-scoped canonical tools and
-    cannot list or respond to another Workspace's dialogs.
-
-### A4. Deliver the stdio bridge
-
-- [x] **A4.1** Implement strict NDJSON framing, JSON-RPC parsing, stdout/stderr
-  separation, initialization, and graceful shutdown.
-  - Covers: FR-2, NFR-1.
-  - Complete: fatal UTF-8 decoding, bounded line assembly, strict JSON-RPC
-  envelopes, ordered normal dispatch, command-control bypass, notification
-  semantics, stdout-only protocol, EOF cleanup, bridge-only shutdown, and
-  structured framing errors are covered by black-box stream tests.
-- [x] **A4.2** Implement tool discovery/call, Workspace/Lease lifecycle,
-  cancellation, and structured errors.
-  - Covers: AC-2, FR-7.
-  - Includes direct all-tab inventory and optional Host-configured operation
-    removal. There are no browser-access approval methods.
-  - Complete: canonical `tools/list`, validated `tools/call`, Workspace/Lease
-    lifecycle, all-tab inventory, and production implementation filtering are
-    implemented. `commands/get/cancel` can overtake a pending call on the same
-    stdio connection and return structured outcomes.
-- [x] **A4.3** Implement event notifications plus cursor polling and
-  `cursor_expired` recovery.
-  - Covers: events contract, NFR-3.
-  - Complete: bounded Workspace journals, explicit initial cursors, ordered
-    replay, `cursor_expired` bounds, Principal isolation, best-effort stdio
-    notifications, and daemon notification long-polling are implemented.
-- [x] **A4.4** Add protocol backpressure, negotiated message limits, and
-  malformed-client isolation.
-  - Covers: NFR-1, NFR-5.
-  - Complete: protocol 1.1 negotiates per-Connection message/result ceilings;
-    bootstrap and pipelined framing apply them deterministically. Input/output
-    backpressure, bounded ordinary/control call queues, oversized-result
-    replacement, notification dropping with cursor recovery, and bridge-local
-    malformed-client termination prevent one client from exhausting or
-    terminating another.
-
-### A5. Deliver secure Artifacts
-
-- [x] **A5.1** Add protected Artifact storage, metadata, quotas, TTL, preview
-  relationships, retain/release, and cleanup.
-  - Covers: BR-17 through BR-20, FR-6.
-- [x] **A5.2** Return screenshot, PDF, and download results as Artifacts while
-  keeping explicit CLI export behavior compatible.
-  - Covers: AC-1, AC-6.
-  - Complete: screenshot and PDF tools return scoped Artifacts; large captures
-    produce model-sized previews with optional originals. Session-scoped Page
-    events establish download ownership, and browser-level completion events
-    copy only those files into protected `download` Artifacts without publishing
-    Chrome source paths or CDP GUIDs.
-- [x] **A5.3** Add adapter-facing file authorization and revoke access on
-  release or expiry.
-  - Covers: CON-5, NFR-5.
-  - Complete: import/get/export/retain/release require an owning active Workspace
-    and Lease. `artifacts/import` copies an absolute client-authorized path to a
-    `user_file` / `upload_input` Artifact, and `browser.upload` accepts only that
-    kind. Release, expiry, Workspace cleanup, and Broker shutdown delete Broker
-    bytes without deleting the source file.
-
-### A6. Browser discovery and multi-version operation
-
-- [x] **A6.1** Return structured browser candidates and setup remediation;
-  persist only explicit or deterministic selection.
-  - Covers: browser discovery contract.
-  - Complete: discovery enumerates installed supported product/profile candidates
-    with stable IDs and separate process, remote-debugging, and authorization
-    state. `initialize`, `browser.discover`, and `bp browsers` are passive and
-    return bounded remediation; the Broker can start before any candidate is
-    ready, connect candidates only through explicit `browser.connect`, and route ready browser instances by
-    `browserId`. Selection is explicit (`--browser`/`browserId`) or stable-order
-    deterministic and remains daemon-memory state only.
-- [x] **A6.2** Define the per-user Broker locator, socket/pipe permissions,
-  startup locking, stale process recovery, and platform-specific paths.
-  - Covers: FR-7, CON-5.
-  - Complete: a versioned, owner-only locator records the per-user endpoint and
-    Broker process identity. Unix uses a mode-`0600` domain socket with a
-    deterministic short runtime path when required; Windows uses a per-user
-    named pipe. State/runtime directories and metadata are owner-only. An
-    atomic startup lock plus a post-lock health check makes concurrent launch a
-    single-winner operation. Broker startup never requests Chrome authorization;
-    concurrent explicit connect calls share one in-flight attempt. Dead owners are
-    reclaimed without killing a PID; live but unresponsive ready Brokers fail
-    with explicit remediation and are never silently replaced.
-- [x] **A6.3** Implement executable/protocol negotiation, live-client upgrade
-  protection, rollback metadata, and deliberate version isolation.
-  - Covers: AC-7, NFR-2.
-  - Complete: compatible embedded clients negotiate and reuse the running
-    Broker, while the one-shot compatibility CLI retains exact executable
-    version semantics. Health and schema-2 locator metadata expose the current
-    service, executable installation identity, protocol range, and bounded live
-    client counts. Protected compare-and-stop shutdown rejects mismatched
-    executables and returns `broker_in_use` while embedded Connections remain.
-    Owner-only version history retains only current/previous executable metadata
-    and no transient browser state. `BROWSER_PILOT_HOME` provides explicit
-    cross-platform isolation; incompatibility never triggers hidden replacement
-    or isolation. Process tests cover reuse, incompatibility, shutdown
-    protection, crash recovery, and two intentional Broker namespaces.
-- [x] **A6.4** Preserve global npm, local npm/npx, and product-bundled launch
-  modes. Add signed/self-contained artifacts where each platform permits.
-  - Covers: FR-1, FR-2.
-  - Complete: build-time version injection and a runtime layout abstraction
-    preserve adjacent-script npm installs while allowing one Node SEA executable
-    to serve the public CLI and reserved private Broker/janitor roles. Packed
-    global npm, local npm/npx, and product-owned absolute-path launches pass
-    black-box version, bridge, Broker startup, and cleanup tests. Native bundles
-    include actual-state signature metadata, SHA-256 manifests, licenses, and
-    platform archives; macOS Developer ID/notarization and Windows Authenticode
-    hooks activate only with complete credentials, while unsigned/ad-hoc state
-    remains explicit. Release CI uses fixed official Node 22.17.0 native runners
-    and verifies every artifact before publishing it.
-
-### A7. Agent-neutral integration kit
-
-- [x] **A7.1** Publish the process adapter contract: launch, initialize,
-  manifest registration, tool calls, event handling, Artifact conversion, and
-  cleanup.
-  - Covers: AC-2, AC-6.
-- [x] **A7.2** Build a language-neutral conformance runner that treats the
-  executable as a black box.
-  - Covers: FR-2 through FR-7.
-- [x] **A7.3** Add Tenon and OpenClaw adapters as separate examples or consumer
-  changes. Keep their lifecycle mapping out of Browser Pilot production code.
-  - Covers: DEC-1, CON-3.
-  - Complete: source-only Tenon and OpenClaw adapters consume only
-    `bridge --stdio`, runtime `tools/list`, and protected Artifact files. They
-    map Thread/Turn and Agent-session/run lifecycles to transient
-    Workspace/Lease contexts, require explicit targets, derive Command identity
-    from host tool-call IDs, convert screenshots to native image content, export
-    files to host-owned absolute paths, explicitly acknowledge processed event
-    cursors, and invalidate local state on failed cleanup. Concurrent begin,
-    initialization/release failure, cursor recovery, media conversion, bounded
-    model text, structured errors, and unknown outcomes are covered by process
-    tests. The examples remain excluded from the npm package and no
-    Agent-specific concept enters production code.
-- [x] **A7.4** Update the Agent skill to teach direct one-shot use and embedded
-  stdio use without assuming a particular Agent runtime.
-  - Covers: FR-1, AC-1.
-
-## Cross-Workstream Dependencies
-
-- A0.2 and B0.1 jointly own the Observation/ref public contract.
-- A1 exposes internal service interfaces; B1-B4 implement improved behavior
-  behind those interfaces.
-- A2 target actors provide B3 action ordering and document-change cancellation.
-- A4 events depend on B4 event producers but can be tested initially with
-  synthetic Broker events.
-- A5 Artifact delivery is required before B5 screenshot guidance is complete.
-
-## Release Gate
-
-Workstream A is complete only when AC-1 through AC-7 pass, existing CLI tests
-remain green, two concurrent reference clients are isolated, all eligible user
-tabs are combined with the Agent's managed tabs without a grant step, bulk
-cleanup leaves user tabs open, Host-disabled operations fail before dispatch,
-and a client can send a screenshot Artifact to its runtime's native image
-content without an SDK or MCP dependency.
+Allow any shell-capable Agent to control the user's eligible Chrome tabs by
+installing the Browser Pilot skill and invoking the same `bp` CLI, whether the
+CLI was installed by the Agent or bundled by an Agent product.
+
+```text
+Agent -> skill -> existing shell tool -> bp CLI -> shared Broker -> Chrome
+```
+
+The integration must not require an extension, MCP, Native SDK, native Browser
+Pilot tools, a persistent adapter, or Agent-specific runtime code.
+
+## Decisions
+
+- [x] Keep one public Agent interface: skill plus CLI.
+- [x] Keep the Broker and CDP transport private.
+- [x] Use stable `BROWSER_PILOT_CLIENT_KEY` values for independent Agents.
+- [x] Preserve logical Agent state across short-lived CLI calls.
+- [x] Expose all eligible managed and user-opened tabs.
+- [x] Keep user tabs open during release and crash cleanup.
+- [x] Leave task-intent permission policy to the Agent host.
+- [x] Support product bundling by putting a pinned CLI on the Agent `PATH`.
+- [x] Support Apple Silicon macOS, x64 Linux, and x64 Windows only.
+
+## Workstream A: CLI Contract
+
+- [x] Provide stable JSON success and error results.
+- [x] Add stable error codes to parser, input, service, and browser failures.
+- [x] Make `--client-key` discoverable in top-level help.
+- [x] Add `bp status` with service, browser, selected state, command state, and
+  structured recovery.
+- [x] Add bounded `bp commands`, `bp command`, and `bp cancel` commands.
+- [x] Add global `--request-id` and deterministic idempotent recovery.
+- [x] Add global `--timeout` and best-effort cancellation on process signals.
+- [x] Add browser-visible `bp wait` conditions.
+- [x] Add download list/export commands.
+- [x] Add `BROWSER_PILOT_OUTPUT_DIR` and structured file metadata.
+- [x] Keep `bp --help` as the canonical runtime command inventory.
+
+## Workstream B: Shared State and Concurrency
+
+- [x] Replace global active-tab/ref files with Broker-owned keyed state.
+- [x] Isolate selected profile, target, frame, refs, auth, network rules,
+  downloads, and commands by Agent key.
+- [x] Serialize commands per physical tab and allow independent tabs to run in
+  parallel.
+- [x] Enforce one controlling Agent per physical user tab.
+- [x] Return stable `target_busy` rather than stealing control.
+- [x] Reclaim expired state and managed targets.
+- [x] Preserve user tabs on Agent release and crash cleanup.
+- [x] Invalidate browser-generation-scoped state after reconnect.
+
+## Workstream C: Cross-Installation Broker Reuse
+
+- [x] Negotiate compatibility by protocol rather than executable path.
+- [x] Allow compatible global and product-bundled CLIs to share one Broker.
+- [x] Keep one stable Agent principal across compatible CLI versions.
+- [x] Use separate internal client sessions when compatible versions differ.
+- [x] Let `bp disconnect` release the invoking Agent's namespace from any
+  compatible installation.
+- [x] Require exact executable identity only for whole-Broker shutdown.
+- [x] Refuse incompatible protocol clients without replacing the live Broker.
+- [x] Support explicit incompatible isolation through `BROWSER_PILOT_HOME`.
+
+## Workstream D: Product Embedding
+
+- [x] Document one generic integration for Tenon, OpenClaw, and other Agents.
+- [x] Require the complete skill and a normal command runner.
+- [x] Require a pinned native CLI or npm CLI plus pinned Node runtime.
+- [x] Put the bundled CLI directory on the Agent command environment's `PATH`.
+- [x] Inject a stable client key per logical Agent.
+- [x] Inject a task-owned absolute output directory.
+- [x] Return files by absolute path for the host's existing image/file tools.
+- [x] Avoid command-to-native-tool mapping and permanent tool-schema context.
+- [x] Keep Agent-managed and bundled installs on the same behavior path.
+
+## Workstream E: Skill and Documentation
+
+- [x] Keep the main skill focused on the browser operating loop.
+- [x] Split command, recovery, async, and embedding details into on-demand
+  references.
+- [x] Remove internal state IDs and transport concepts from Agent guidance.
+- [x] Document all eligible user tabs and explicit user-tab close behavior.
+- [x] Document Chrome profile identity and routing.
+- [x] Document tab-group control limitations without limiting grouped tabs.
+- [x] Document local screenshot, PDF, download, and network-body results.
+- [x] Document stable request recovery and uncertain mutation rules.
+
+## Workstream F: Distribution
+
+- [x] Keep CLI, plugin, skill compatibility, and marketplace versions synced
+  from the root package version.
+- [x] Publish a release index binding CLI, skill range, protocol, platforms,
+  checksums, and tested version.
+- [x] Exclude Intel Mac assets.
+- [x] Verify global, local, and product-bundled npm use.
+- [x] Verify native archives do not need system Node.
+- [x] Bump the next release version and produce local release artifacts.
+- [ ] Publish the npm package, plugin archive, native archives, checksums, and
+  release index.
+
+## Acceptance Criteria
+
+- [x] An Agent can install Browser Pilot itself and follow the skill.
+- [x] A product can bundle Browser Pilot without adding native browser tools.
+- [x] Two Agent products can share one Broker with isolated state.
+- [x] A compatible bundled CLI can use a Broker started by a global CLI.
+- [x] A compatible non-owner CLI can disconnect cleanly without stopping that
+  Broker.
+- [x] Every eligible user-opened tab can be selected and controlled.
+- [x] The same physical tab cannot be controlled by two Agents concurrently.
+- [x] Browser authorization is requested only by explicit connection.
+- [x] Stable request IDs prevent duplicate dispatch during recovery.
+- [x] Screenshots, PDFs, downloads, and saved bodies are available as local
+  files with structured metadata.
+- [x] Removed persistent adapter commands are absent from CLI help and release
+  packages.
+- [x] Full unit, Playwright, distribution, standalone, and controlled real
+  Chrome release gates pass for the new version.