browser-pilot-cli 0.3.0-rc.2 → 0.3.0-rc.4

package/docs/architecture/browser-pilot-platform-spec.md

@@ -818,21 +818,30 @@ a screenshot, PDF, download, or arbitrary Broker-internal path as upload
 authorization.
 
 Downloads are event-produced Artifacts rather than a separate path-returning
-tool. The implementation must configure download behavior on the controlled
-target session only, stage bytes in a mode-`0700` per-session directory, keep
-the CDP download GUID and staging path private, and ingest a completed file as a
-Workspace-owned `download` Artifact before publishing the completed `download`
-event. Lease/session/Workspace release removes partial staging files; failed,
-cancelled, oversized, or detached downloads publish bounded metadata without a
-local path. Browser-wide `Browser.setDownloadBehavior` on the user's default
-context is forbidden because it would redirect downloads from unrelated user
-tabs. If target-session isolation is unavailable in a Chrome version, Browser
-Pilot reports download capture as unavailable and does not fall back globally.
-The implementation applies per-download, per-Workspace staging, and global
-staging bounds. An oversized or over-capacity download is cancelled by its
-private GUID without changing download behavior for the browser's default
-context. Stale staging directories from a prior Broker process are removed before
-the first new download session is configured.
+tool. CDP download behavior is browser-context scoped even when invoked through
+an attached target session, so per-session download directories cannot provide
+isolation. For each browser connection generation and Chrome Profile context,
+the Broker enables `Browser.downloadProgress` once with
+`Browser.setDownloadBehavior({ behavior: "default", eventsEnabled: true })`.
+The `default` behavior preserves Chrome's configured download directory and
+does not redirect user downloads.
+
+`Page.downloadWillBegin` on an attached controlled target binds the private CDP
+GUID to that target's Workspace and Lease. The browser-level completed event
+supplies the absolute source `filePath`; the Broker accepts it only for a GUID
+already bound by the Page event, validates a regular file, and copies it into a
+Workspace-owned `download` Artifact before publishing completion. Browser-level
+events without a controlled Page owner are ignored. GUIDs and source paths never
+appear in protocol output.
+
+The Browser Pilot copy is subject to tracking, item, Workspace, and global
+Artifact bounds. Exceeding a bound rejects only Artifact creation: it must not
+cancel, move, truncate, or delete Chrome's original download. Lease, session,
+Workspace, Artifact, and Broker cleanup stop tracking and delete only protected
+Artifact copies. The original file in the user's Chrome download directory is
+always left intact. If browser-level download events are unavailable, Browser
+Pilot reports capture as unavailable without changing Chrome's download
+behavior.
 
 ## Browser Discovery and Setup
 

package/docs/integration/stdio-bridge.md

@@ -544,10 +544,11 @@ downloads are rejected as upload inputs. Workspace cleanup deletes the imported
 copy but never deletes the client-owned source file.
 
 Downloads have no path-returning tool. Once a controlled target session is
-attached, the Broker configures target-session download capture and emits
-`download` events with one of these states:
+attached, the Broker enables browser-level completion events while preserving
+Chrome's default download behavior, and emits `download` events with one of
+these states:
 
-- `capture_unavailable`: that Chrome version rejected target-session isolation;
+- `capture_unavailable`: Chrome rejected browser-level completion events;
 - `started`: includes an opaque `downloadId`, bounded URL, and suggested filename;
 - `completed`: includes the Workspace-owned `download` Artifact descriptor;
 - `failed` or `cancelled`: includes a stable, bounded reason and byte metadata.
@@ -558,14 +559,24 @@ public `artifactId`, and terminal failures recommend inspecting the bounded
 failure reason. `capture_unavailable` is setup state and does not claim that a
 download started.
 
-The private CDP GUID and staging path never appear in protocol output. On
-`completed`, use the descriptor's `id` with `artifacts/get` or `artifacts/export`
-exactly as for screenshots and PDFs. Staging directories are separate per CDP
-session, use mode `0700`, enforce concurrency and byte quotas, and are removed on
-session, Lease, or Workspace release. The session setting is restored to
-`default` before an attached session is retired. Browser Pilot never calls browser-wide
-`Browser.setDownloadBehavior`; unsupported target-session capture remains
-unavailable instead of redirecting unrelated user downloads.
+The private CDP GUID and Chrome source path never appear in protocol output. On
+`completed`, use the descriptor's `id` with `artifacts/get` or
+`artifacts/export` exactly as for screenshots and PDFs. A session-scoped
+`Page.downloadWillBegin` event establishes Workspace/Lease/target ownership;
+the browser-level completion event is ignored unless that ownership already
+exists. Browser Pilot enables those completion events once per browser
+connection generation and Chrome Profile context with
+`Browser.setDownloadBehavior({ behavior: "default", eventsEnabled: true })`.
+It never supplies `downloadPath`, so Chrome continues to use the user's selected
+download directory.
+
+The Broker validates the completed absolute regular-file path and copies it to
+protected Artifact storage. Releasing or expiring the Artifact, Lease, or
+Workspace deletes only that copy. The original Chrome download is never moved
+or deleted. Size, concurrency, or Artifact quota failures reject only the
+Artifact copy and do not call `Browser.cancelDownload`. Downloads from tabs
+without an attached controlled session remain ordinary Chrome downloads and
+produce no Browser Pilot event.
 
 ## Cleanup
 

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

@@ -1,6 +1,6 @@
 # Profile Context Routing Plan
 
-Status: **In progress**
+Status: **Complete**
 Target: Browser Pilot `v0.3.0`, protocol `1.2`
 Source of truth: `docs/architecture/browser-pilot-platform-spec.md`
 
@@ -179,21 +179,21 @@ candidate targets were closed.
 - [x] P4: update stdio integration guidance, adapters, skill, and release docs.
 - [x] P5: add protocol, dual-Profile, concurrency, reconnect, cleanup, and
   compatibility tests.
-- [ ] P6: run real Chrome acceptance and publish `v0.3.0-rc.2`.
+- [x] P6: run real Chrome acceptance and publish `v0.3.0-rc.2`.
 
 ## Acceptance
 
-- All eligible user tabs across live Profile contexts appear in one inventory.
-- Existing user tabs can be controlled without selecting a Profile first.
-- No multi-context open silently selects a first Profile.
-- Explicit, active-target, Workspace, and single-context resolution follow the
+- [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
   specified order.
-- Every managed target and popup matches its ManagedTabSet Profile context.
-- Two Workspaces may select different contexts and create targets concurrently
+- [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.
-- Reconnect invalidates old Profile IDs, target mappings, frames, and refs.
-- Passive listing creates no target and never focuses or navigates a user tab.
-- Janitor EOF/SIGKILL cleanup closes fallback-created managed windows but never
+- [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] Janitor EOF/SIGKILL cleanup closes fallback-created managed windows but never
   user tabs.
-- Protocol 1.1 clients retain existing-tab control and cannot open ambiguously.
-- Single-Profile CLI and fixture behavior remains compatible.
+- [x] Protocol 1.1 clients retain existing-tab control and cannot open ambiguously.
+- [x] Single-Profile CLI and fixture behavior remains compatible.

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

@@ -114,9 +114,10 @@ Pilot. Tenon and OpenClaw are reference consumers only.
     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 use target-session CDP configuration, separate protected
-    staging directories, bounded concurrency/bytes, Workspace-owned Artifacts,
-    and Lease/session/Workspace cleanup without browser-wide fallback.
+    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.
@@ -226,9 +227,10 @@ Pilot. Tenon and OpenClaw are reference consumers only.
   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 download
-    events ingest completed files as protected `download` Artifacts without
-    publishing staging paths or CDP GUIDs.
+    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.

package/docs/plans/v0.3.0-stabilization.md

@@ -0,0 +1,51 @@
+# Browser Pilot v0.3.0 Stabilization Plan
+
+Status: **In progress**
+Candidate baseline: `v0.3.0-rc.3`; correction target: `v0.3.0-rc.4`, protocol `1.2`
+
+## Goal
+
+Promote protocol 1.2 to `v0.3.0` only after the published executable passes
+the same multi-host workflows that Tenon, OpenClaw, Codex, and other Agent
+products depend on. No Agent-specific behavior enters Browser Pilot.
+
+## Release gate
+
+- [x] Add a black-box host integration runner that launches two independent
+  stdio bridge clients against an exact executable command.
+- [x] Verify separate Connections, Workspaces, Leases, opaque target IDs, one
+  shared Broker, and one shared in-flight browser connection.
+- [x] Verify eligible user-tab exclusivity, `target_busy`, explicit release,
+  and handoff without navigation, editing, or closure.
+- [x] Verify concurrent CLI use and separate managed inventories.
+- [x] Verify screenshot conversion to native image content and PDF/download
+  export to host-owned absolute paths.
+- [x] Verify event replay until explicit acknowledgement.
+- [x] Verify Workspace cleanup closes only managed targets and preserves the
+  initial user-tab inventory.
+- [x] Verify isolated browser loss/restoration events and invalidate old
+  Profile and target identities after reconnect.
+- [x] Replace invalid per-session download redirection with Chrome-default
+  downloads, controlled Page-event ownership, browser-level completion paths,
+  and copy-only Artifacts. Verify unowned downloads are ignored and user source
+  files survive Artifact and Workspace cleanup.
+- [x] Pass TypeScript, 276 Node, 109 Playwright, 13 stdio conformance, three
+  distribution-mode, and 13 host integration checks on the candidate source.
+- [x] Publish `v0.3.0-rc.3` through trusted publishing and pass all 13 host
+  integration checks against the installed standalone release executable.
+- [x] Run one controlled user-Chrome host acceptance with explicit Profile
+  choices and a single authorization attempt.
+- [ ] Publish `v0.3.0-rc.4` with Broker-backed CLI browser status and verify
+  that passive discovery reports the live authorized connection.
+- [ ] Soak several real Agent tasks through the installed candidate.
+- [ ] Tag `v0.3.0`, publish npm `latest`, and verify upgrade/rollback metadata.
+
+## Stable decision
+
+The first new host gate exposed a deeper CDP constraint: target-session calls to
+`Page.setDownloadBehavior` still share download behavior across a Chrome
+Profile. One host could therefore redirect another host's download, including
+an uncontrolled user tab. `v0.3.0-rc.2` must not be promoted. RC.3 preserves
+Chrome's default download destination and creates an Artifact only after a
+session-scoped Page event proves ownership and a browser-level completion event
+provides the final path.

package/docs/releases/v0.3.0-rc.1.md

@@ -1,5 +1,10 @@
 # Browser Pilot 0.3.0-rc.1
 
+> Superseded by `0.3.0-rc.2`. Real-Chrome acceptance found that some regular
+> Profile tabs report a normalized `TargetInfo.openerId` for fallback-created
+> windows. RC.1 fails closed with `unknown_outcome` but may leave its blank
+> marker tab for caller cleanup. Upgrade to RC.2.
+
 This release candidate adds extension-free multi-Profile routing on one
 authorized Chrome endpoint. Browser Pilot now inventories eligible user tabs
 from every live Profile context and keeps those tabs directly controllable.
@@ -44,6 +49,7 @@ Automated release gates completed before tagging:
 - The npm dry-run package contains the Profile routing plan and this release
   note.
 
-The controlled real Chrome dual-Profile acceptance is performed after installing
-the published RC so it exercises the same package and Codex skill path available
-to users.
+The post-publication real Chrome run verified one-authorization Profile listing,
+cross-Profile user-tab control, ambiguity rejection, and direct managed creation.
+It then exposed the fallback issue documented above, which is fixed and accepted
+in RC.2.

package/docs/releases/v0.3.0-rc.2.md

@@ -39,5 +39,20 @@ Automated release gates completed before tagging:
 The RC.1 real-Chrome run used one authorization and verified three live Profile
 contexts, cross-Profile user-tab inventory, existing-tab control in two
 Profiles, and managed creation in the direct-create Profile before exposing this
-fallback defect. RC.2 is accepted against the same Chrome setup after installing
-the published package.
+fallback defect.
+
+The published RC.2 package then passed controlled real Chrome acceptance through
+the installed Codex CLI and skill path:
+
+- one explicit connection produced one Chrome authorization and discovered three
+  live Profile contexts;
+- five eligible user tabs across two Profiles remained listable and controllable;
+- an unanchored new-target request returned `profile_selection_required` before
+  browser dispatch and did not create a tab;
+- direct creation and isolated-world fallback creation each landed in the
+  explicitly selected Profile with the expected managed origin;
+- no marker target remained after fallback verification;
+- targeted close and managed bulk close preserved all five user tabs;
+- Profile selection, tab control, creation, and cleanup produced no additional
+  authorization prompt; and
+- reconnect generated new Profile IDs and the prior connection's ID was rejected.

package/docs/releases/v0.3.0-rc.3.md

@@ -0,0 +1,56 @@
+# Browser Pilot 0.3.0-rc.3
+
+This release candidate adds a black-box integration gate for real Agent hosts
+and replaces the previous download-capture model after that gate exposed a CDP
+isolation flaw.
+
+`Page.setDownloadBehavior` is not truly target-session isolated inside one
+Chrome Profile. Assigning a private directory for Host B can overwrite Host A's
+setting and redirect downloads from an uncontrolled user tab. RC.3 therefore:
+
+- preserves Chrome's configured download directory with browser-context
+  `Browser.setDownloadBehavior({ behavior: "default", eventsEnabled: true })`;
+- uses session-scoped `Page.downloadWillBegin` only to bind a private GUID to a
+  Workspace, Lease, and target;
+- accepts browser-level completion paths only for already-owned GUIDs and
+  ignores unrelated browser downloads;
+- copies a completed regular file into the Workspace's protected Artifact
+  storage without exposing its source path; and
+- never cancels, moves, or deletes the user's original download when tracking,
+  size, quota, Artifact, Lease, or Workspace cleanup ends.
+
+The host integration acceptance suite launches two independent stdio clients
+against an exact executable command and verifies:
+
+- separate Connections, Workspaces, Leases, and opaque target IDs reuse one
+  per-user Broker;
+- concurrent browser connect calls share the Broker connection path;
+- Profile routing and managed inventories remain isolated;
+- one user tab reports `target_busy`, then transfers through explicit release;
+- a one-shot CLI remains usable while both embedded hosts are live;
+- screenshots become native image content while PDFs and downloads export to
+  host-owned absolute paths;
+- Chrome's original downloaded file survives Artifact and Workspace cleanup;
+- event polling replays until the host explicitly acknowledges its cursor;
+- Workspace shutdown removes only managed targets and preserves user tabs; and
+- an isolated Chrome restart emits lost/restored events and invalidates old
+  Profile and target identities.
+
+RC.3 also closes a Broker startup race: the `starting` PID record is now
+published only after exit and signal cleanup handlers are installed, so a
+SIGTERM during browser authorization cannot leave a stale owner record.
+
+Automated gates completed for the candidate source:
+
+- TypeScript type checking passed.
+- 276 Node unit, protocol, process, adapter, and runner tests passed.
+- 109 isolated Playwright core, compatibility, and network tests passed.
+- The stdio conformance suite passed all 13 checks.
+- The host integration suite passed all 13 isolated checks, including original
+  Chrome download preservation.
+- npm distribution verification passed for global, local project, and
+  product-bundled executable modes.
+
+RC.3 keeps protocol 1.2 and the RC.2 Profile routing contract unchanged. It
+adds no Native SDK, MCP server, browser extension, approval layer, or
+Agent-specific production behavior.

package/docs/releases/v0.3.0-rc.4.md

@@ -0,0 +1,28 @@
+# Browser Pilot 0.3.0-rc.4
+
+This release candidate fixes a connection-status inconsistency found during
+controlled user-Chrome acceptance of RC.3.
+
+When a Broker already held an authorized Chrome connection, `bp profiles` and
+browser operations worked, but `bp browsers` performed a separate local endpoint
+scan and could report the same browser as `disconnected`. An Agent following
+that result could unnecessarily call `bp connect` and cause another Chrome
+authorization prompt.
+
+RC.4 makes `bp browsers` use the Broker-owned `browser.discover` operation when
+a compatible Broker is running. Local discovery remains the passive fallback
+when no Broker exists. The command still never starts a Broker or requests
+Chrome authorization.
+
+The RC.3 controlled user-Chrome acceptance passed with two independent Agent
+hosts routed to two live Profiles. It verified user-tab handoff, concurrent CLI
+use, native screenshot content, PDF and download export, event replay, managed
+cleanup, and preservation of all existing user tabs. Chrome's original
+download was also confirmed in its default download directory.
+
+RC.4 keeps protocol 1.2, browser control behavior, Profile routing, and the
+Agent-neutral stdio integration contract unchanged.
+
+Automated candidate gates passed with 276 Node tests, 109 isolated Playwright
+tests, all 13 stdio conformance checks, all 13 host integration checks, and npm
+distribution verification in global, local-project, and product-bundled modes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-pilot-cli",
-  "version": "0.3.0-rc.2",
+  "version": "0.3.0-rc.4",
   "description": "CLI tool to control your browser via Chrome DevTools Protocol",
   "repository": "https://github.com/relixiaobo/browser-pilot",
   "type": "module",
@@ -22,6 +22,7 @@
     "test:capabilities": "tsup && node --test tests/browser-capability-fixtures.test.mjs",
     "test:protocol": "tsup && node --test tests/protocol.test.mjs",
     "test:stdio-conformance": "tsup && node scripts/run-isolated-stdio-conformance.mjs",
+    "test:host-acceptance": "tsup && node scripts/run-isolated-host-integration-acceptance.mjs",
     "test:distribution": "tsup && node scripts/verify-npm-distribution.mjs",
     "test:canary": "tsup && node scripts/run-real-site-canaries.mjs",
     "test:canary:strict": "tsup && node scripts/run-real-site-canaries.mjs --strict",
@@ -41,9 +42,12 @@
     "docs/integration/stdio-conformance.md",
     "docs/plans/browser-capability-evolution.md",
     "docs/plans/profile-context-routing.md",
+    "docs/plans/v0.3.0-stabilization.md",
     "docs/plans/universal-agent-integration.md",
     "docs/releases/v0.3.0-rc.1.md",
     "docs/releases/v0.3.0-rc.2.md",
+    "docs/releases/v0.3.0-rc.3.md",
+    "docs/releases/v0.3.0-rc.4.md",
     "README.md",
     "LICENSE"
   ],