browser-workspace 0.4.1 → 0.4.5

package/src/browser_workspace_app/interaction-skills/connection.md

@@ -0,0 +1,52 @@
+# Connection & Tab Visibility
+
+## The omnibox popup problem
+
+When Chrome opens fresh, the only CDP `type: "page"` targets are `chrome://inspect` and `chrome://omnibox-popup.top-chrome/` (a 1px invisible viewport). If the daemon attaches to the omnibox popup, all subsequent work — including `new_tab()` and `goto_url()` — happens on tabs that exist in CDP but may not be visible in the Chrome UI.
+
+The daemon's `attach_first_page()` handles this by creating an `about:blank` tab when no real pages exist. If you still end up on an invisible tab, use `switch_tab()` to attach to the real tab. Call `activate_tab()` only when the user explicitly asks Chrome to visibly show it.
+
+## Startup sequence
+
+1. Check if a daemon is already running with `daemon_alive()`
+2. If stale sockets exist but daemon is dead, clean them up
+3. List open tabs with `list_tabs()` to see what's available
+4. `ensure_real_tab()` attaches to a real page
+5. `switch_tab(target_id)` attaches without changing the visible Chrome tab; use `activate_tab(target_id)` only for a user-requested visible switch
+
+```python
+if not daemon_alive():
+    import os, ipc
+    ipc.cleanup_endpoint("default")
+    pid = ipc.pid_path("default")
+    if pid.exists(): pid.unlink()
+    ensure_daemon()
+
+tabs = list_tabs()
+for t in tabs:
+    print(t["url"][:60])
+
+tab = ensure_real_tab()
+```
+
+## Bringing Chrome to front
+
+If Chrome is behind other windows or on another desktop and the user explicitly wants it shown:
+
+```python
+import subprocess
+subprocess.run(["osascript", "-e", 'tell application "Google Chrome" to activate'])
+```
+
+For normal agent work, do not activate Chrome. Screenshots and CDP input work
+on the attached background tab; activate only for a page that demonstrably
+pauses visibility-dependent rendering while hidden.
+
+## Navigating
+
+Prefer navigating an existing tab over `new_tab()`. Harness-created tabs open in the background.
+
+```python
+tab = ensure_real_tab()
+goto_url("https://example.com")
+```

package/src/browser_workspace_app/interaction-skills/cookies.md

@@ -0,0 +1,3 @@
+# Cookies
+
+Document how to get cookies, save cookies, and set cookies without confusing browser state with page state.

package/src/browser_workspace_app/interaction-skills/cross-origin-iframes.md

@@ -0,0 +1,3 @@
+# Cross-Origin Iframes
+
+Focus on `iframe_target(...)`, target attachment, and when compositor-level coordinate clicks are lower-friction than cross-target DOM work.

package/src/browser_workspace_app/interaction-skills/dialogs.md

@@ -0,0 +1,64 @@
+# Dialogs
+
+Browser dialogs (`alert`, `confirm`, `prompt`, `beforeunload`) freeze the JS thread. Two approaches depending on timing.
+
+## Detection
+
+`page_info()` auto-surfaces any open dialog: if one is pending it returns `{"dialog": {"type", "message", ...}}` instead of the usual viewport dict (because the page's JS is frozen anyway). So if you call `page_info()` after an action and see a `dialog` key, handle it before doing anything else.
+
+## Reactive: dismiss via CDP (preferred)
+
+Works even when JS is frozen. Handles all dialog types including `beforeunload`.
+
+```python
+# Dismiss and read the message
+cdp("Page.handleJavaScriptDialog", accept=True)   # accept / click OK
+cdp("Page.handleJavaScriptDialog", accept=False)  # cancel / click Cancel
+
+# Read what the dialog said (from buffered CDP events)
+events = drain_events()
+for e in events:
+    if e["method"] == "Page.javascriptDialogOpening":
+        print(e["params"]["type"])     # "alert", "confirm", "prompt", "beforeunload"
+        print(e["params"]["message"])  # the dialog text
+```
+
+Undetectable by antibot — no JS injected into the page.
+
+## Proactive: stub via JS
+
+Prevents dialogs from ever appearing. Good when you expect multiple `alert()`/`confirm()` calls in sequence.
+
+```python
+js("""
+window.__dialogs__=[];
+window.alert=m=>window.__dialogs__.push(String(m));
+window.confirm=m=>{window.__dialogs__.push(String(m));return true;};
+window.prompt=(m,d)=>{window.__dialogs__.push(String(m));return d||'';};
+""")
+# ... do actions that trigger dialogs ...
+msgs = js("window.__dialogs__||[]")
+```
+
+Tradeoffs:
+- Stubs are lost on page navigation -- must re-run the snippet
+- `confirm()` always returns `true` (auto-approves)
+- Detectable by antibot (`window.alert.toString()` reveals non-native code)
+- Does NOT handle `beforeunload`
+
+## beforeunload specifically
+
+Fires when navigating away from a page with unsaved changes (forms, editors, upload pages). The page freezes until the user clicks Leave/Stay.
+
+```python
+# Option A: dismiss after navigating (CDP-level, safe)
+goto_url("https://new-url.com")
+try:
+    cdp("Page.handleJavaScriptDialog", accept=True)  # click "Leave"
+except:
+    pass  # no dialog — normal
+
+# Option B: prevent before navigating (JS injection, detectable)
+js("window.onbeforeunload=null")
+goto_url("https://new-url.com")
+```

package/src/browser_workspace_app/interaction-skills/downloads.md

@@ -0,0 +1,3 @@
+# Downloads
+
+Separate browser-triggered downloads from direct `http_get(...)` fetches, and document the minimal signals that prove a download actually started.

package/src/browser_workspace_app/interaction-skills/drag-and-drop.md

@@ -0,0 +1,3 @@
+# Drag And Drop
+
+Focus on when drag-and-drop can be driven with low-level input events versus when the site really expects a file upload or DOM-specific drag sequence.

package/src/browser_workspace_app/interaction-skills/dropdowns.md

@@ -0,0 +1,3 @@
+# Dropdowns
+
+Split dropdowns into native selects, custom overlays, searchable comboboxes, and virtualized menus, and always re-measure after opening because option geometry often appears late.

package/src/browser_workspace_app/interaction-skills/iframes.md

@@ -0,0 +1,3 @@
+# Iframes
+
+Cover same-origin iframe traversal through `contentDocument` / `contentWindow`, and keep the frame-local versus page-coordinate warning explicit for clicks.

package/src/browser_workspace_app/interaction-skills/network-requests.md

@@ -0,0 +1,3 @@
+# Network Requests
+
+Document how to watch or infer network activity when page state is ambiguous, especially for submit flows, downloads, and SPA actions that succeed without obvious DOM changes.

package/src/browser_workspace_app/interaction-skills/print-as-pdf.md

@@ -0,0 +1,3 @@
+# Print As PDF
+
+Cover both direct PDF generation via CDP and sites that only expose a visible "Print" button which must be clicked before handling the browser print flow.

package/src/browser_workspace_app/interaction-skills/profile-sync.md

@@ -0,0 +1,90 @@
+# Profile sync
+
+Make a remote Browser Use browser start already logged in, by uploading cookies from a local Chrome profile.
+
+## One-time install
+
+```bash
+curl -fsSL https://browser-use.com/profile.sh | sh
+```
+
+Downloads `profile-use` (macOS / Linux, x64 / arm64). The Python helpers shell out to it; you don't run `profile-use` directly.
+
+## Python API (pre-imported in a Browser Workspace session)
+
+```python
+list_cloud_profiles()
+# [{id, name, userId, cookieDomains, lastUsedAt}, ...] — every profile under this API key
+
+list_local_profiles()
+# [{BrowserName, ProfileName, DisplayName, ProfilePath, ...}, ...] — detected on this machine
+
+sync_local_profile(profile_name, browser=None,
+                   cloud_profile_id=None,      # update an existing cloud profile instead of creating new
+                   include_domains=None,       # only these domains (and subdomains); leading dot optional
+                   exclude_domains=None)       # drop these domains; applied before include
+# Shells out to `profile-use sync`. Returns the cloud profile UUID
+# (the existing one if cloud_profile_id was passed, else the newly-created one).
+
+start_remote_daemon("work", profileName="my-work")   # name→id resolved client-side
+start_remote_daemon("work", profileId="<uuid>")      # or pass UUID directly
+
+stop_remote_daemon("work")                           # shut the daemon and PATCH the cloud browser to stop — billing ends
+```
+
+`sync_local_profile` prints `♻️  Using existing cloud profile` when `cloud_profile_id` is accepted, or `📝  Creating remote profile...` → `✓ Profile created: <uuid>` when it creates a new one. Check that line if you want to confirm which path ran.
+
+## Chat-driven flow (don't guess — ask the user)
+
+Cookies are real auth. Don't sync or pick a profile unilaterally.
+
+```python
+# 1. Show what's already in the cloud.
+for p in list_cloud_profiles():
+    print(f"{p['name']:25}  {len(p['cookieDomains']):3} domains  {p['id']}")
+```
+→ Agent: *"You have these cloud profiles (<N> domains each). Want to reuse one, sync a local profile, or start clean?"*
+
+```python
+# 2a. Reuse cloud → one call.
+start_remote_daemon("work", profileName="browser-use.com")
+
+# 2b. Sync local first. Show the options:
+for lp in list_local_profiles():
+    print(lp["DisplayName"])
+```
+→ Agent: *"Which local profile?"* → user picks → before syncing, inspect domain-level cookie counts with `profile-use inspect --profile <name>` (or `--verbose` for individual cookies) and report the summary; never dump 500 cookies into chat.
+
+```python
+# 3. Sync + use. Returns the cloud UUID.
+uuid = sync_local_profile("browser-use.com")
+start_remote_daemon("work", profileId=uuid)
+
+# 3b. Refresh that same cloud profile later (idempotent — no duplicate profiles).
+sync_local_profile("browser-use.com", cloud_profile_id=uuid)
+
+# 3c. Scoped: push *only* Stripe cookies into a dedicated cloud profile.
+sync_local_profile("browser-use.com",
+                   cloud_profile_id=uuid,
+                   include_domains=["stripe.com"])
+```
+
+## What actually gets synced
+
+**Cookies only.** No localStorage, no IndexedDB, no extensions. Enough for session-cookie sites (Google, GitHub, Stripe, most SaaS); not for sites that store auth in localStorage.
+
+Cookies mutated during a remote session only persist on a clean `PATCH /browsers/{id} {"action":"stop"}` — the daemon does this on shutdown when `BU_BROWSER_ID` + `BROWSER_USE_API_KEY` are set (default for remote daemons). Sessions that hit the timeout lose in-session state.
+
+## Cloud profile CRUD
+
+- UI: https://cloud.browser-use.com/settings?tab=profiles
+- API: `GET /profiles`, `GET/PATCH/DELETE /profiles/{id}` (paths are relative to `BU_API = "https://api.browser-use.com/api/v3"` in `admin.py`). Fields: `id`, `name`, `userId`, `lastUsedAt`, `cookieDomains[]`. `list_cloud_profiles()` wraps this.
+- Name → UUID: `profileName=` on `start_remote_daemon` resolves client-side; no API change needed.
+- Need the UUID for an existing profile? `matches = [p["id"] for p in list_cloud_profiles() if p["name"] == "<name>"]` — then verify `len(matches) == 1` before using it. Profile names are not unique; syncs create duplicates unless you pass `cloud_profile_id=`.
+- Lower-level raw calls: `from browser_harness.admin import _browser_use; _browser_use("/profiles/<id>", "DELETE")`. Pass the path *without* the `/api/v3` prefix — it's already on `BU_API`.
+
+## Traps
+
+- **Default proxy (`proxyCountryCode="us"`) blocks some destinations** with `ERR_TUNNEL_CONNECTION_FAILED` (e.g. `cloud.browser-use.com` itself). `proxyCountryCode=None` disables the BU proxy; a different country code picks a different exit.
+- **Prefer a dedicated work profile over your personal one.** Especially while testing.
+- **Older than `profile-use` v1.0.5?** Pre-1.0.5 the sync needed the Chrome profile to be closed (exclusive SQLite lock on the `Cookies` DB). v1.0.5+ copies the profile dir to a temp and syncs from the copy — Chrome can stay open.

package/src/browser_workspace_app/interaction-skills/screenshots.md

@@ -0,0 +1,17 @@
+# Screenshots
+
+`capture_screenshot()` writes a PNG of the current viewport. The file is in **device pixels** — on a 2× display a 2296×1143 CSS viewport produces a 4592×2286 PNG.
+
+That matters for two reasons:
+
+1. **Click coordinates are CSS pixels.** Don't read a target off the image and pass it to `click_at_xy()` directly without dividing by `devicePixelRatio`. The simplest workflow is to take the screenshot, look at it in a viewer that shows CSS coordinates, or measure relative positions and use `js("window.devicePixelRatio")` to convert.
+
+2. **Some LLMs reject images > 2000 px per side.** Long sessions on 2× displays will eventually hit this. Pass `max_dim=1800` to downscale the file before it gets into the conversation:
+
+```python
+capture_screenshot("/tmp/shot.png", max_dim=1800)
+```
+
+The downscale only happens when the image actually exceeds `max_dim`, so it's safe to leave on for every shot.
+
+Use full-page screenshots (`full=True`) only when you need to see content below the fold — they are much larger and slower than viewport-only.

package/src/browser_workspace_app/interaction-skills/scrolling.md

@@ -0,0 +1,22 @@
+# Scrolling
+
+Separate page scroll, nested containers, virtualized lists, and dropdown menus, and identify which element is actually consuming wheel events before scrolling.
+
+## Hidden tabs
+
+Start with the normal `scroll(...)` helper. Chrome on Windows can leave a
+mouse-wheel command unanswered when the attached tab is not visible. If that
+scroll times out:
+
+1. Do not call `activate_tab()`; a timeout is not permission to foreground
+   Chrome.
+2. Temporarily call
+   `cdp("Emulation.setFocusEmulationEnabled", enabled=True)`, retry the same
+   `scroll(...)` once, and re-read the page or container scroll position.
+3. Disable focus emulation in a `finally` block.
+
+If background scrolling still fails, stop and name that exact limitation.
+Call `activate_tab()` only when the user explicitly asks to see or visibly
+switch to the tab. Do not replace wheel input with custom `Runtime.evaluate`
+scrolling or a cross-frame JavaScript walker; those paths change page semantics
+and require context the agent does not have.

package/src/browser_workspace_app/interaction-skills/shadow-dom.md

@@ -0,0 +1,3 @@
+# Shadow DOM
+
+Focus on recursive `shadowRoot` traversal, and note when coordinate clicking is simpler than piercing deeply nested component trees.

package/src/browser_workspace_app/interaction-skills/tabs.md

@@ -0,0 +1,73 @@
+# Tabs
+
+Use **CDP for control**, **UI automation for user-visible order**.
+
+## Pure CDP (portable: macOS / Linux / Windows)
+
+```python
+tabs = list_tabs()                    # includes chrome:// pages too
+real_tabs = list_tabs(include_chrome=False)
+tid = new_tab("https://example.com")  # create + attach in the background
+switch_tab(tid)                       # attach harness, move the horse marker
+activate_tab(tid)                     # optional: explicitly show it in Chrome
+print(current_tab())
+print(page_info())
+```
+
+What CDP is good at:
+- attach to a tab
+- open a tab
+- activate a known target
+- inspect URL/title/viewport
+- capture the attached tab's screenshot even if another tab is visibly frontmost
+
+What CDP is bad at:
+- matching the **left-to-right tab strip order** the user sees
+- telling whether the attached target is an omnibox popup / internal page without URL filtering
+
+## Visible order (platform UI)
+
+### macOS
+
+```applescript
+tell application "Google Chrome"
+  set out to {}
+  set i to 1
+  repeat with t in every tab of front window
+    set end of out to {tab_index:i, tab_title:(title of t), tab_url:(URL of t)}
+    set i to i + 1
+  end repeat
+  return out
+end tell
+```
+
+```applescript
+tell application "Google Chrome"
+  set active tab index of front window to 2
+  activate
+end tell
+```
+
+### Linux
+
+No AppleScript. Same split still applies:
+- use CDP for `new_tab`, attach, inspect, activate known targets
+- use window-manager / browser UI automation when the user means visible order
+
+Typical tools:
+- `xdotool`
+- `wmctrl`
+- desktop-environment scripting (`gdbus`, KWin, GNOME Shell extensions, etc.)
+
+## Rules that held up in practice
+
+- `switch_tab()` intentionally does **not** change Chrome's visible tab.
+- Static screenshots and normal CDP input work on the attached background tab.
+- `activate_tab()` is only for a user-requested visible switch. Rendering or
+  input trouble is not permission to foreground Chrome; use background CDP and
+  temporary focus emulation first.
+- `Target.activateTarget` is the CDP-side "show this tab".
+- `list_tabs()` includes `chrome://newtab/` by default; ask for `include_chrome=False` when you want only real pages.
+- `chrome://omnibox-popup.top-chrome/` can appear as a fake page target; ignore it for user-facing tab lists.
+- If a page has `w=0 h=0`, you may be attached to the wrong target or a non-window surface.
+- For dynamic UIs, re-read element rects after opening dropdowns / modals before coordinate-clicking.

package/src/browser_workspace_app/interaction-skills/uploads.md

@@ -0,0 +1 @@
+# Uploads

package/src/browser_workspace_app/interaction-skills/viewport.md

@@ -0,0 +1,16 @@
+# Viewport
+
+Cover how viewport size changes affect layout, coordinate clicks, and any workflow that depends on stable geometry.
+
+## Touch emulation
+
+`maxTouchPoints` is optional, but Chrome validates it as 1–16 even when touch
+emulation is being disabled. Omit it when disabling:
+
+```python
+cdp("Emulation.setTouchEmulationEnabled", enabled=True, maxTouchPoints=5)
+cdp("Emulation.setTouchEmulationEnabled", enabled=False)
+```
+
+Do not pass `maxTouchPoints=0`; Chrome rejects the supplied value before acting
+on `enabled=False`.

package/src/browser_workspace_app/licenses/browser-harness-MIT.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Browser Use
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/browser_workspace_app/managed_chrome.py

@@ -0,0 +1,244 @@
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import platform
+import re
+import shutil
+import socket
+import subprocess
+import time
+import urllib.request
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+# Chrome identity is machine-global for Browser Workspace. Runtime/config overrides
+# may move sockets/caches, but must never create another browser instance.
+SINGLETON_ROOT = Path.home() / ".config/browser-workspace"
+PROFILE_DIR = SINGLETON_ROOT / "chrome"
+STATE_FILE = SINGLETON_ROOT / "managed-chrome.json"
+LOCK_FILE = SINGLETON_ROOT / "managed-chrome.lock"
+LOG_FILE = SINGLETON_ROOT / "managed-chrome.log"
+DEFAULT_PORT = int(os.environ.get("BROWSER_WORKSPACE_CDP_PORT", "9222"))
+PORT_CANDIDATES = int(os.environ.get("BROWSER_WORKSPACE_CDP_PORT_CANDIDATES", "20"))
+
+
+def _endpoint(port: int) -> str:
+    return f"http://127.0.0.1:{port}"
+
+
+def _endpoint_live(port: int, timeout: float = 0.5) -> bool:
+    try:
+        with urllib.request.urlopen(f"{_endpoint(port)}/json/version", timeout=timeout) as response:
+            payload = json.loads(response.read())
+        return bool(payload.get("webSocketDebuggerUrl"))
+    except Exception:
+        return False
+
+
+def _port_available(port: int) -> bool:
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    try:
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        sock.bind(("127.0.0.1", port))
+        return True
+    except OSError:
+        return False
+    finally:
+        sock.close()
+
+
+def _pid_alive(pid: int | None) -> bool:
+    if not pid:
+        return False
+    try:
+        os.kill(int(pid), 0)
+        return True
+    except (OSError, ValueError, TypeError):
+        return False
+
+
+def _load_state() -> dict:
+    try:
+        return json.loads(STATE_FILE.read_text())
+    except (OSError, ValueError, TypeError):
+        return {}
+
+
+def _write_state(payload: dict) -> None:
+    SINGLETON_ROOT.mkdir(parents=True, exist_ok=True)
+    tmp = STATE_FILE.with_suffix(".tmp")
+    tmp.write_text(json.dumps(payload, indent=2, sort_keys=True))
+    os.replace(tmp, STATE_FILE)
+
+
+@contextlib.contextmanager
+def _singleton_lock():
+    SINGLETON_ROOT.mkdir(parents=True, exist_ok=True)
+    handle = open(LOCK_FILE, "a+")
+    try:
+        if platform.system() == "Windows":
+            import msvcrt
+            handle.seek(0)
+            msvcrt.locking(handle.fileno(), msvcrt.LK_LOCK, 1)
+        else:
+            import fcntl
+            fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+        yield
+    finally:
+        try:
+            if platform.system() == "Windows":
+                import msvcrt
+                handle.seek(0)
+                msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
+            else:
+                import fcntl
+                fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+        finally:
+            handle.close()
+
+
+def _chrome_path() -> str:
+    configured = os.environ.get("BROWSER_WORKSPACE_CHROME_PATH") or os.environ.get("BH_CHROME_PATH")
+    if configured:
+        return configured
+    system = platform.system()
+    if system == "Darwin":
+        candidates = [
+            "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+            "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
+            "/Applications/Chromium.app/Contents/MacOS/Chromium",
+        ]
+    elif system == "Windows":
+        local = Path(os.environ.get("LOCALAPPDATA", ""))
+        program_files = [Path(os.environ.get("PROGRAMFILES", "")), Path(os.environ.get("PROGRAMFILES(X86)", ""))]
+        candidates = [
+            str(local / "Google/Chrome/Application/chrome.exe"),
+            *(str(p / "Google/Chrome/Application/chrome.exe") for p in program_files if str(p)),
+        ]
+    else:
+        candidates = ["google-chrome-stable", "google-chrome", "chromium", "chromium-browser"]
+    for candidate in candidates:
+        if os.path.isabs(candidate):
+            if Path(candidate).exists():
+                return candidate
+        elif resolved := shutil.which(candidate):
+            return resolved
+    raise RuntimeError("Browser Workspace could not find Chrome; set BROWSER_WORKSPACE_CHROME_PATH")
+
+
+def _discover_existing_managed_chrome() -> dict | None:
+    """Recover the singleton even if its state file was deleted or became stale."""
+    if platform.system() == "Windows":
+        return None
+    try:
+        output = subprocess.check_output(["ps", "-axo", "pid=,command="], text=True)
+    except Exception:
+        return None
+    profile_arg = f"--user-data-dir={PROFILE_DIR}"
+    for line in output.splitlines():
+        if profile_arg not in line:
+            continue
+        match = re.match(r"\s*(\d+)\s+(.+)", line)
+        if not match:
+            continue
+        pid = int(match.group(1))
+        command = match.group(2)
+        if "--type=" in command:
+            continue
+        port_match = re.search(r"--remote-debugging-port=(\d+)", command)
+        if not port_match:
+            continue
+        port = int(port_match.group(1))
+        if _pid_alive(pid) and _endpoint_live(port):
+            return {
+                "pid": pid,
+                "port": port,
+                "profile_dir": str(PROFILE_DIR),
+                "chrome_path": command.split(" --user-data-dir=", 1)[0],
+            }
+    return None
+
+
+def _live_singleton() -> dict | None:
+    state = _load_state()
+    port = state.get("port")
+    pid = state.get("pid")
+    if isinstance(port, int) and _pid_alive(pid) and _endpoint_live(port):
+        return state
+    recovered = _discover_existing_managed_chrome()
+    if recovered:
+        _write_state(recovered)
+        return recovered
+    return None
+
+
+def _choose_port() -> int:
+    for port in range(DEFAULT_PORT, DEFAULT_PORT + max(1, PORT_CANDIDATES)):
+        if _port_available(port):
+            return port
+    raise RuntimeError(
+        f"Browser Workspace could not find a free CDP port in "
+        f"{DEFAULT_PORT}..{DEFAULT_PORT + max(1, PORT_CANDIDATES) - 1}"
+    )
+
+
+def _as_result(state: dict, reused: bool) -> dict:
+    endpoint = _endpoint(int(state["port"]))
+    os.environ["BU_CDP_URL"] = endpoint
+    return {**state, "mode": "managed", "endpoint": endpoint, "reused": reused}
+
+
+def ensure_managed_chrome() -> dict:
+    """Return the one machine-wide Browser Workspace Chrome, starting it only if absent."""
+    with _singleton_lock():
+        # Strong invariant: an existing Browser Workspace Chrome always wins.
+        if existing := _live_singleton():
+            return _as_result(existing, True)
+
+        # Advanced external endpoint is only considered when no managed singleton exists.
+        if os.environ.get("BU_CDP_WS"):
+            return {"mode": "override", "endpoint": "BU_CDP_WS"}
+        if url := os.environ.get("BU_CDP_URL"):
+            return {"mode": "override", "endpoint": url}
+
+        PROFILE_DIR.mkdir(parents=True, exist_ok=True)
+        port = _choose_port()
+        chrome = _chrome_path()
+        log = open(LOG_FILE, "ab", buffering=0)
+        command = [
+            chrome,
+            f"--user-data-dir={PROFILE_DIR}",
+            f"--remote-debugging-port={port}",
+            "--no-first-run",
+            "--no-default-browser-check",
+            "about:blank",
+        ]
+        process = subprocess.Popen(
+            command,
+            stdin=subprocess.DEVNULL,
+            stdout=log,
+            stderr=log,
+            start_new_session=True,
+            close_fds=True,
+        )
+        log.close()
+
+        deadline = time.time() + float(os.environ.get("BROWSER_WORKSPACE_CHROME_START_TIMEOUT", "20"))
+        while time.time() < deadline:
+            if process.poll() is not None:
+                raise RuntimeError(
+                    f"Browser Workspace managed Chrome exited with code {process.returncode}; see {LOG_FILE}"
+                )
+            if _endpoint_live(port):
+                payload = {
+                    "pid": process.pid,
+                    "port": port,
+                    "profile_dir": str(PROFILE_DIR),
+                    "chrome_path": chrome,
+                }
+                _write_state(payload)
+                return _as_result(payload, False)
+            time.sleep(0.1)
+        raise RuntimeError(f"Browser Workspace managed Chrome did not expose CDP on port {port}; see {LOG_FILE}")