browser-pilot-cli 0.4.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

@@ -198,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`.

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

@@ -1,352 +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 derives a stable one-shot Connection identity from
-    `BROWSER_PILOT_CLIENT_KEY`/`--client-key`, plus an idempotently keyed
-    compatibility Workspace and renewable five-minute Lease. The default key
-    preserves single-Agent compatibility; distinct stable keys isolate Agents.
-    Every CLI command calls canonical tools; selected 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 or any
-    active Lease remains.
-    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. The supported native
-    matrix is Apple Silicon macOS, x64 Linux, and x64 Windows; Intel Mac is not
-    supported. A versioned release index binds these assets to the npm package,
-    exact Agent plugin/skill version, protocol range, and checksums, and GitHub
-    Release publication waits for npm publication.
-
-### 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.
-  - Complete: the main skill is a bounded operating guide with progressive
-    command/stdio references, version-range CLI compatibility checking, stable
-    one-shot error recovery, explicit user-tab/Profile/tab-group boundaries,
-    local capture semantics, and generated Codex UI metadata. Release
-    verification and a machine-readable skill compatibility manifest prevent
-    silent CLI/skill version drift.
-
-## 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.

package/docs/releases/v0.5.0.md

@@ -0,0 +1,93 @@
+# Browser Pilot 0.5.0
+
+Browser Pilot 0.5.0 establishes one public integration model for every Agent:
+the Browser Pilot skill invokes the short-lived `bp` CLI through the Agent's
+existing shell tool. Agent-installed and product-bundled copies now use the
+same commands, state model, and recovery behavior.
+
+## One Agent interface
+
+- The public `bridge --stdio` command, JSON-RPC adapter, reference host
+  adapters, conformance suites, and adapter documentation have been removed.
+- Browser Pilot does not require an MCP server, Native SDK, Browser Pilot
+  native tools, Agent-specific runtime, or browser extension.
+- Tenon, OpenClaw, Codex, Claude Code, and other shell-capable Agents integrate
+  by bundling a compatible CLI on the Agent `PATH`, installing the same skill,
+  and assigning a stable `BROWSER_PILOT_CLIENT_KEY` per independent Agent.
+- The internal Broker remains shared and long-lived. Individual CLI processes
+  remain short-lived and do not expose the Broker protocol as a public API.
+
+## Stateful CLI recovery
+
+- `bp status` returns bounded browser, profile, tab, active-command,
+  uncertain-command, and structured recovery state for the current Agent.
+- `bp commands`, `bp command <id>`, and `bp cancel <id>` expose command
+  inspection and best-effort cancellation without a persistent client.
+- Global `--request-id` provides deterministic deduplication for recovery of
+  one intended operation. Global `--timeout` sets its command deadline.
+- `SIGINT` and `SIGTERM` request cancellation of an active command. Mutations
+  that may already have reached Chrome still return `unknown_outcome` and must
+  be inspected before retry.
+- `bp wait` waits for one browser-visible URL, text, selector, dialog,
+  download, or popup condition and returns stable `wait_timeout` on expiry.
+  Terminating the wait CLI returns `command_cancelled` without releasing its
+  Agent browser state.
+- `bp status` queries active and uncertain command states independently, so a
+  long condition wait cannot hide an older `unknown_outcome` behind its polling
+  reads.
+
+## Files and downloads
+
+- `BROWSER_PILOT_OUTPUT_DIR` provides a task-owned default destination for
+  screenshots, PDFs, exported downloads, and saved network bodies.
+- Capture and download results return an absolute file path, MIME type, byte
+  size, and image dimensions when available.
+- `bp downloads` lists completed downloads retained for the current Agent;
+  `bp download <index> [filename]` copies one result without moving or deleting
+  Chrome's original file.
+- Artifact exports and saved network bodies are written with private file
+  permissions.
+
+## Shared Broker and Agent isolation
+
+- The private Broker RPC envelope is versioned independently from the public
+  CLI. A 0.5 CLI detects a pre-0.5 Broker before sending RPC and returns
+  `protocol_incompatible` with explicit stop-or-isolate remediation.
+- Compatible global, Agent-installed, and product-bundled CLI versions reuse
+  one per-user Broker through protocol negotiation rather than executable-path
+  equality.
+- A stable Agent key preserves selected profile, tab, frame, refs, auth,
+  network rules, downloads, and command history across CLI calls. Different
+  keys remain isolated.
+- Commands are serialized per physical target. A second Agent receives
+  `target_busy` instead of taking control of a tab already leased by another
+  Agent.
+- `bp disconnect` releases only the invoking Agent's state and managed tabs.
+  A compatible CLI that does not own the Broker executable cannot stop the
+  shared Broker.
+- All eligible Browser Pilot-created and user-opened tabs remain available;
+  user tabs stay open during Agent release and crash cleanup.
+
+## Skill and distribution
+
+- The skill uses progressive disclosure: the main operating loop links to
+  separate command, asynchronous recovery, failure recovery, and product
+  embedding references.
+- `bp --help` is the canonical runtime command inventory. The plugin no longer
+  publishes a permanent native-tool manifest.
+- CLI, skill, plugin, marketplace metadata, compatibility range, checksums,
+  and release index are versioned together at 0.5.0.
+- Native release targets remain Apple Silicon macOS, x64 Linux, and x64
+  Windows. Intel Mac is not supported.
+
+## Migration from 0.4.x
+
+Remove any `browser-pilot bridge --stdio` process and Browser Pilot-specific
+tool mapping. Keep the Agent's normal shell tool, install the complete
+`browser-pilot` skill, make a compatible `bp` executable available on `PATH`,
+and inject `BROWSER_PILOT_CLIENT_KEY` plus an absolute
+`BROWSER_PILOT_OUTPUT_DIR`. Use `bp status`, command recovery, and `bp wait`
+when the host previously depended on a persistent adapter for state or events.
+If a pre-0.5 Broker is still running, stop it once with the older executable's
+`bp disconnect` before starting 0.5; Browser Pilot never replaces a live
+incompatible process automatically.