browser-pilot-cli 0.3.0-rc.1 → 0.3.0-rc.3

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

@@ -615,7 +615,9 @@ Artifacts. Raw CDP is never listed. `eval` requires `developer.eval`.
 - **BR-32:** Every ManagedTabSet is bound to at most one ProfileContext. Managed
   target creation verifies the returned context before public registration, and
   fallback-created targets enter janitor ownership before they become
-  addressable.
+  addressable. Fallback ownership requires the exact new URL marker plus either
+  the expected opener ID or exact readback of a per-command random window name;
+  Profile membership alone is never sufficient.
 - **BR-33:** Switching to an existing target may update the owning Workspace's
   selected ProfileContext, but never prevents inventory or control of targets
   in other Profiles. No Profile selection is a permission grant.
@@ -816,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`
 
@@ -138,11 +138,13 @@ managed-target janitor:
    varies by regular Profile context.
 3. If Chrome rejects or misroutes that call, attach to a bounded representative
    page target in the selected context, create an isolated world, and call
-   `window.open("about:blank", "_blank", <fixed popup window features>)` with a
-   debugger user gesture.
-4. Identify exactly one new target by the pre-dispatch target set, opener ID,
-   Profile context, page type, and blank URL. Ambiguous or mismatched targets are
-   closed and the operation fails.
+   `window.open(<unique blank marker>, <unique window name>, <fixed popup window
+   features>)` with a debugger user gesture.
+4. Identify exactly one new page target by the pre-dispatch target set, unique
+   URL marker, and Profile context. Prove ownership through either the expected
+   opener ID or exact readback of the per-command random `window.name`; Chrome
+   may normalize the reported opener across regular Profile tabs. Ambiguous or
+   unverified targets are closed and the operation fails.
 5. Explicitly adopt the verified target into the janitor before registering it
    publicly, so Broker crash cleanup still closes it.
 6. Read and retain its window ID, bind the ManagedTabSet, register the opaque
@@ -177,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.1`.
+- [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,49 @@
+# Browser Pilot v0.3.0 Stabilization Plan
+
+Status: **In progress**
+Candidate baseline: `v0.3.0-rc.2`; correction target: `v0.3.0-rc.3`, 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.
+- [ ] Publish the corrected release candidate and rerun the host integration
+  gate against that installed package.
+- [ ] Run one controlled user-Chrome host acceptance with explicit Profile
+  choices and a single authorization attempt.
+- [ ] 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

@@ -0,0 +1,58 @@
+# Browser Pilot 0.3.0-rc.2
+
+This release candidate fixes a real-Chrome edge case found while accepting the
+multi-Profile routing introduced in `0.3.0-rc.1`.
+
+Some regular Chrome Profile tabs create a `window.open` target whose
+`TargetInfo.openerId` differs from the page target used for the isolated-world
+dispatch. Chrome still returns the exact per-command URL marker, Profile
+context, and random window name. RC.1 correctly refused to register that target
+but could leave the unregistered blank marker visible until the caller cleaned
+up the reported `unknown_outcome`.
+
+RC.2 keeps fail-closed ownership verification without relying on opener IDs
+alone. A fallback-created target must be a new page with the exact random URL
+marker and selected Profile context, then prove ownership through either the
+expected opener ID or exact readback of the per-command random `window.name`.
+Profile membership by itself is never accepted.
+
+All marker candidates are now tracked before validation, target discovery waits
+through a bounded five-second Chrome metadata window, and failure cleanup waits
+for asynchronous target destruction to become observable. A target that fails
+both ownership proofs is closed and never registered or adopted.
+
+The regression suite covers both paths: a Chrome-normalized opener with a valid
+window-name proof succeeds, while a mismatched opener and mismatched window name
+fails closed and leaves no marker target.
+
+Automated release gates completed before tagging:
+
+- TypeScript type checking passed.
+- 266 Node unit, protocol, process, and adapter tests passed.
+- 109 isolated Playwright core, compatibility, and network tests passed.
+- The black-box stdio conformance suite passed all 13 checks.
+- npm distribution verification passed for global, local project, and
+  product-bundled executable modes.
+- The npm dry-run package contains both Profile RC notes and the Profile routing
+  plan.
+
+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.
+
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-pilot-cli",
-  "version": "0.3.0-rc.1",
+  "version": "0.3.0-rc.3",
   "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,8 +42,11 @@
     "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",
     "README.md",
     "LICENSE"
   ],