browser-workspace 0.4.0

package/src/browser_harness/daemon.py

@@ -0,0 +1,894 @@
+"""CDP WS holder + IPC relay (Unix socket on POSIX, TCP loopback on Windows). One daemon per BU_NAME."""
+import asyncio, json, os, platform, socket, sys, time, urllib.error, urllib.request
+from urllib.parse import urlparse
+from collections import deque
+from pathlib import Path
+
+from . import _ipc as ipc
+from . import auth
+from . import paths
+from cdp_use.client import CDPClient
+
+
+def _load_env():
+    repo_root = Path(__file__).resolve().parents[2]
+    workspace = paths.workspace_dir()
+    for p in (repo_root / ".env", workspace / ".env"):
+        if not p.exists():
+            continue
+        _load_env_file(p)
+
+
+def _load_env_file(p):
+    for line in p.read_text(encoding="utf-8-sig", errors="replace").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        k, v = line.split("=", 1)
+        os.environ.setdefault(k.strip(), v.strip().strip('"').strip("'"))
+
+
+_load_env()
+
+NAME = os.environ.get("BU_NAME", "default")
+SOCK = ipc.sock_addr(NAME)
+LOG = str(ipc.log_path(NAME))
+PID = str(ipc.pid_path(NAME))
+BUF = 500
+_MAC_PROFILES = (
+    "Library/Application Support/Google/Chrome",
+    "Library/Application Support/Google/Chrome Canary",
+    "Library/Application Support/Comet",
+    "Library/Application Support/Arc/User Data",
+    "Library/Application Support/Dia/User Data",
+    "Library/Application Support/Microsoft Edge",
+    "Library/Application Support/Microsoft Edge Beta",
+    "Library/Application Support/Microsoft Edge Dev",
+    "Library/Application Support/Microsoft Edge Canary",
+    "Library/Application Support/BraveSoftware/Brave-Browser",
+    "Library/Application Support/BraveSoftware/Brave-Origin",
+)
+_LINUX_PROFILES = (
+    ".config/google-chrome",
+    ".config/chromium",
+    ".config/chromium-browser",
+    ".config/microsoft-edge",
+    ".config/microsoft-edge-beta",
+    ".config/microsoft-edge-dev",
+    ".var/app/org.chromium.Chromium/config/chromium",
+    ".var/app/com.google.Chrome/config/google-chrome",
+    ".var/app/com.brave.Browser/config/BraveSoftware/Brave-Browser",
+    ".var/app/com.microsoft.Edge/config/microsoft-edge",
+)
+_WINDOWS_PROFILES = (  # relative to %LOCALAPPDATA%; SxS = Canary channel
+    "Google/Chrome/User Data",
+    "Google/Chrome SxS/User Data",
+    "Google/Chrome Beta/User Data",
+    "Google/Chrome Dev/User Data",
+    "Chromium/User Data",
+    "Microsoft/Edge/User Data",
+    "Microsoft/Edge Beta/User Data",
+    "Microsoft/Edge Dev/User Data",
+    "Microsoft/Edge SxS/User Data",
+    "BraveSoftware/Brave-Browser/User Data",
+)
+
+
+def _publish_own_pid(path=PID, pid=None):
+    """Atomically retain or publish this daemon's PID record.
+
+    The parent may already have published a process-start fingerprint while
+    holding the spawn lock. Never truncate that record: another cold caller
+    must not observe an empty PID file and start a sibling daemon.
+    """
+    pid = pid or os.getpid()
+    target = Path(path)
+    try:
+        published = target.read_text()
+        try:
+            published_pid = int(json.loads(published)["pid"])
+        except (json.JSONDecodeError, TypeError, KeyError):
+            published_pid = int(published.split()[0])
+    except (FileNotFoundError, OSError, ValueError, IndexError):
+        published = str(pid)
+        published_pid = pid
+    if published_pid != pid:
+        published = str(pid)
+    tmp = target.with_name(f"{target.name}.{pid}.tmp")
+    tmp.write_text(published)
+    os.replace(tmp, target)
+
+
+def profile_dirs(system=None):
+    system = system or platform.system()
+    if system == "Windows":
+        local = Path(os.environ.get("LOCALAPPDATA") or Path.home() / "AppData/Local")
+        return [local / p for p in _WINDOWS_PROFILES]
+    if system == "Darwin":
+        return [Path.home() / p for p in _MAC_PROFILES]
+    return [Path.home() / p for p in _LINUX_PROFILES]
+
+
+PROFILES = profile_dirs()
+INTERNAL = ("chrome://", "chrome-untrusted://", "devtools://", "chrome-extension://", "about:")
+BU_API = "https://api.browser-use.com/api/v3"
+REMOTE_ID = os.environ.get("BU_BROWSER_ID")
+_REMOTE_STOPPED = False
+BROWSER_KIND = "cloud" if REMOTE_ID else ("cdp" if (os.environ.get("BU_CDP_WS") or os.environ.get("BU_CDP_URL")) else "local")
+# Chrome 144+ shows a per-connection popup, and the connection that raised it is
+# the only thing keeping it on screen. There is deliberately no approval
+# deadline: expiry would drop the sheet and make a later attempt create another
+# connection and another prompt. Chrome/process death and explicit cancellation
+# still terminate the pending connection.
+LOCAL_HANDSHAKE_TIMEOUT = None
+# How long get_ws_url() keeps waiting for DevToolsActivePort before giving up
+NO_TOGGLE_GRACE = 3
+TOGGLE_BOOT_GRACE = 12
+# Cancellation should make an in-flight CDP call finish immediately. Keep the
+# drain bounded anyway so shutdown fails closed if a client ignores cancellation.
+RECOVERY_CANCEL_DRAIN_TIMEOUT = 2
+TAB_MARKER_JS = "if(!document.title.startsWith('\U0001F434'))document.title='\U0001F434 '+document.title"
+
+
+def tab_marker_enabled():
+    """Whether the cosmetic controlled-tab title marker should be added."""
+    return os.environ.get("BH_TAB_MARKER", "").strip().lower() not in {"0", "false", "no", "off"}
+
+
+def _devtools_port_live(base):
+    """True when something is listening on the profile's DevToolsActivePort port.
+
+    A stale file left behind by a closed browser must not count as a running
+    instance — it would route recovery to "click Allow" on a popup that can't
+    exist."""
+    try:
+        port = int((base / "DevToolsActivePort").read_text(encoding="utf-8", errors="replace").splitlines()[0].strip())
+    except (OSError, ValueError, IndexError):
+        return False
+    try:
+        socket.create_connection(("127.0.0.1", port), timeout=0.5).close()
+        return True
+    except OSError:
+        return False
+
+
+def remote_debugging_user_enabled():
+    """chrome://inspect's "Allow remote debugging" toggle
+
+    True only when a toggle-on profile also has a live DevTools port.
+    False if a profile records it off, None when no profile records it."""
+    seen = None
+    for base in PROFILES:
+        try:
+            state = json.loads((base / "Local State").read_text(encoding="utf-8", errors="replace"))
+            enabled = ((state.get("devtools") or {}).get("remote_debugging") or {}).get("user-enabled")
+        except (OSError, ValueError, AttributeError):
+            continue
+        if enabled is True and _devtools_port_live(base):
+            return True
+        if enabled is False:
+            seen = False
+    return seen
+
+
+def remote_debugging_toggle_profiles():
+    """Profile dirs whose chrome://inspect toggle is recorded on in Local State"""
+    out = []
+    for base in PROFILES:
+        try:
+            state = json.loads((base / "Local State").read_text(encoding="utf-8", errors="replace"))
+            if ((state.get("devtools") or {}).get("remote_debugging") or {}).get("user-enabled") is True:
+                out.append(base)
+        except (OSError, ValueError, AttributeError):
+            continue
+    return out
+
+
+def browser_running_for_profile(base):
+    """True when a running browser instance holds this user-data-dir (POSIX)"""
+    try:
+        target = os.readlink(str(base / "SingletonLock"))
+    except OSError:
+        return False
+    try:
+        pid = int(target.rsplit("-", 1)[-1])
+    except ValueError:
+        return False
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except OSError:
+        return True  # pid exists but belongs to another user
+
+
+def supported_browser_running():
+    """Is any browser whose profile we scan actually running?"""
+    if platform.system() == "Windows":
+        # Chromium on Windows uses a named mutex instead of SingletonLock —
+        import subprocess
+        try:
+            out = subprocess.check_output(["tasklist"], text=True, errors="replace", timeout=5).lower()
+        except Exception:
+            return True  # can't tell — assume running so recovery stays on the popup/toggle path
+        return any(n in out for n in ("chrome.exe", "msedge.exe", "chromium.exe", "brave.exe", "helium.exe"))
+    return any(browser_running_for_profile(base) for base in PROFILES)
+
+
+def log(msg):
+    open(LOG, "a", encoding="utf-8", errors="replace").write(f"{msg}\n")
+
+
+def _safe_connection_label(url):
+    """Log only endpoint topology, never CDP credentials or provider session paths."""
+    try:
+        parsed = urlparse(url)
+        if not parsed.scheme or not parsed.hostname:
+            return "<redacted-cdp-endpoint>"
+        host = f"[{parsed.hostname}]" if ":" in parsed.hostname else parsed.hostname
+        port = f":{parsed.port}" if parsed.port else ""
+        return f"{parsed.scheme}://{host}{port}"
+    except (TypeError, ValueError):
+        return "<redacted-cdp-endpoint>"
+
+
+async def _silent(coro):
+    try:
+        await coro
+    except Exception:
+        pass
+
+
+def _ws_from_devtools_active_port(http_url: str) -> str | None:
+    """When /json/version returns 404 (Chrome 147+ default profile), match DevToolsActivePort by port."""
+    p = urlparse(http_url)
+    want_port = str(p.port) if p.port else ""
+    if not want_port:
+        return None
+    host = p.hostname or "127.0.0.1"
+    if ":" in host:  # urlparse strips IPv6 brackets; restore them for the ws:// URL
+        host = f"[{host}]"
+    for base in PROFILES:
+        try:
+            active = (base / "DevToolsActivePort").read_text(encoding="utf-8", errors="replace").splitlines()
+        except (FileNotFoundError, NotADirectoryError):
+            continue
+        port = active[0].strip() if active else ""
+        ws_path = active[1].strip() if len(active) > 1 else ""
+        if port == want_port and ws_path:
+            return f"ws://{host}:{port}{ws_path}"
+    return None
+
+
+def get_ws_url():
+    if url := os.environ.get("BU_CDP_WS"):
+        return url
+    if url := os.environ.get("BU_CDP_URL"):
+        # HTTP DevTools endpoint (e.g. http://127.0.0.1:9333) — resolve to ws via /json/version.
+        # Use this for a dedicated automation Chrome on a non-default profile, which avoids the
+        # M144 "Allow remote debugging" dialog and the M136 default-profile lockdown.
+        deadline = time.time() + 30
+        last_err = None
+        base_url = url.rstrip("/")
+        while time.time() < deadline:
+            try:
+                return json.loads(urllib.request.urlopen(f"{base_url}/json/version", timeout=5).read())["webSocketDebuggerUrl"]
+            except urllib.error.HTTPError as e:
+                last_err = e
+                if e.code == 403:
+                    raise RuntimeError("permission-blocked: Chrome is reachable, but the per-session Allow remote debugging popup has not been accepted")
+                if e.code == 404 and (ws := _ws_from_devtools_active_port(url)):
+                    return ws
+                time.sleep(1)
+            except Exception as e:
+                last_err = e
+                time.sleep(1)
+        hint = "is the dedicated automation Chrome running? Launch it with --remote-debugging-port=<port> --user-data-dir=<dedicated dir>"
+        if platform.system() == "Windows":
+            hint += "; on Windows also check that a firewall/antivirus isn't blocking localhost connections"
+        raise RuntimeError(f"BU_CDP_URL={url} unreachable after 30s: {last_err} -- {hint}")
+    deadline = time.time() + 30
+    next_liveness_check = 0.0
+    while time.time() < deadline:
+        for base in PROFILES:
+            try:
+                active = (base / "DevToolsActivePort").read_text(encoding="utf-8", errors="replace").splitlines()
+            except (FileNotFoundError, NotADirectoryError):
+                continue
+            port = active[0].strip() if active else ""
+            ws_path = active[1].strip() if len(active) > 1 else ""
+            if not port:
+                continue
+            # Resolve the live WS URL via /json/version instead of trusting the path stored
+            # alongside the port in DevToolsActivePort: if Chrome was previously launched
+            # with a different --user-data-dir on the same port, that file is left behind
+            # with a stale browser UUID and the WS upgrade returns 404.
+            try:
+                return json.loads(urllib.request.urlopen(f"http://127.0.0.1:{port}/json/version", timeout=1).read())["webSocketDebuggerUrl"]
+            except urllib.error.HTTPError as e:
+                if e.code == 403:
+                    raise RuntimeError("permission-blocked: Chrome is reachable, but the per-session Allow remote debugging popup has not been accepted")
+                # Chrome 147+ disables /json/* HTTP discovery on the default user-data-dir;
+                # the ws path Chrome wrote to DevToolsActivePort still works.
+                if e.code == 404 and ws_path:
+                    return f"ws://127.0.0.1:{port}{ws_path}"
+            except (OSError, KeyError, ValueError):
+                pass
+        # Closed browser leaves stale DevToolsActivePort files
+        now = time.time()
+        if now >= next_liveness_check:
+            if not supported_browser_running():
+                raise RuntimeError(
+                    "chrome-not-running: no supported Chromium-family browser is running -- start Chrome, then retry"
+                )
+            next_liveness_check = now + 2
+        # The browser is running but the port isn't up; waiting 30s
+        grace = TOGGLE_BOOT_GRACE if remote_debugging_toggle_profiles() else NO_TOGGLE_GRACE
+        if now > deadline - 30 + grace:
+            break
+        time.sleep(0.2)
+    for probe_port in (9222, 9223):
+        try:
+            with urllib.request.urlopen(f"http://127.0.0.1:{probe_port}/json/version", timeout=1) as r:
+                return json.loads(r.read())["webSocketDebuggerUrl"]
+        except urllib.error.HTTPError as e:
+            if e.code == 403:
+                raise RuntimeError("permission-blocked: Chrome is reachable, but the per-session Allow remote debugging popup has not been accepted")
+        except (OSError, KeyError, ValueError):
+            continue
+    if remote_debugging_user_enabled() is False:
+        raise RuntimeError('remote debugging is turned off for this browser instance — enable chrome://inspect/#remote-debugging (tick "Allow remote debugging for this browser instance")')
+    raise RuntimeError(f"DevToolsActivePort not found in {[str(p) for p in PROFILES]} — enable chrome://inspect/#remote-debugging, or set BU_CDP_WS for a remote browser")
+
+
+def stop_remote(strict=False):
+    global _REMOTE_STOPPED
+    if not REMOTE_ID:
+        return True
+    if _REMOTE_STOPPED:
+        return True
+    last_error = None
+    for attempt in range(3):
+        try:
+            key = auth.get_browser_use_api_key()
+            req = urllib.request.Request(
+                f"{BU_API}/browsers/{REMOTE_ID}",
+                data=json.dumps({"action": "stop"}).encode(),
+                method="PATCH",
+                headers={"X-Browser-Use-API-Key": key, "Content-Type": "application/json"},
+            )
+            urllib.request.urlopen(req, timeout=15).read()
+            _REMOTE_STOPPED = True
+            log(f"stopped remote browser {REMOTE_ID}")
+            return True
+        except Exception as e:
+            last_error = e
+            log(f"stop_remote attempt {attempt + 1}/3 failed ({REMOTE_ID}): {e}")
+            if attempt < 2:
+                time.sleep(0.5 * (attempt + 1))
+    if strict:
+        raise RuntimeError(f"failed to stop remote browser {REMOTE_ID}: {last_error}")
+    return False
+
+
+def is_real_page(t):
+    return t["type"] == "page" and not t.get("url", "").startswith(INTERNAL)
+
+
+def is_reusable_blank_page(t):
+    """A plain about:blank tab that is safe to attach to and navigate"""
+    url = t.get("url", "")
+    return (
+        t["type"] == "page"
+        and (url == "about:blank" or url.startswith("about:blank#"))
+        and not t.get("title", "").startswith("Starting agent ")
+    )
+
+
+def is_inspect_tab(t):
+    """A chrome://inspect tab — normally the one the permission flow opened"""
+    return t["type"] == "page" and t.get("url", "").startswith("chrome://inspect")
+
+
+def harness_opened_inspect():
+    """True when admin's recovery flow opened a chrome://inspect tab that is
+    still awaiting cleanup (the marker survives until the next connect)."""
+    try:
+        return paths.inspect_marker().exists()
+    except OSError:
+        return False
+
+
+def is_reusable_new_tab_page(t):
+    """The browser's own New Tab Page, ex: from a fresh launch"""
+    return t["type"] == "page" and t.get("url", "").startswith(
+        ("chrome://newtab", "chrome://new-tab-page", "edge://newtab", "about:newtab")
+    )
+
+
+class _PatientCDPClient(CDPClient):
+    """CDPClient whose local Chrome approval handshake has no deadline."""
+
+    async def start(self):
+        import websockets
+        if self.ws is not None:
+            raise RuntimeError("Client is already started")
+        connect_kwargs = {"max_size": self.max_ws_frame_size, "open_timeout": LOCAL_HANDSHAKE_TIMEOUT}
+        if self.additional_headers:
+            connect_kwargs["additional_headers"] = self.additional_headers
+        self.ws = await websockets.connect(self.url, **connect_kwargs)
+        self._message_handler_task = asyncio.create_task(self._handle_messages())
+
+
+class Daemon:
+    def __init__(self):
+        self.cdp = None
+        self.session = None
+        self.target_id = None
+        self.dedicated_target_id = None
+        self._dedicated_target_lock = asyncio.Lock()
+        self._session_state_lock = asyncio.Lock()
+        self._active_recoveries = 0
+        self._recovery_tasks = set()
+        self._recoveries_idle = asyncio.Event()
+        self._recoveries_idle.set()
+        self._shutting_down = False
+        self._session_replacements = {}
+        self.events = deque(maxlen=BUF)
+        self.dialog = None
+        self.stop = None  # asyncio.Event, set inside start()
+
+    async def attach_first_page(self, replaces_session=None, enable_domains=True):
+        """Attach to a real page (or any page). Sets self.session. Returns attached target or None."""
+        targets = (await self.cdp.send_raw("Target.getTargets"))["targetInfos"]
+        # Named daemons (BU_NAME != "default") share one browser with other
+        # daemons — attaching to the first page makes parallel daemons fight
+        # over a single tab (navigations clobber each other). Give each named
+        # daemon its own dedicated tab instead. REMOTE_ID (cloud) browsers are
+        # already exclusive to this daemon, so first-page attach stays.
+        if NAME != "default" and not REMOTE_ID:
+            # The permission recovery flow can leave chrome://inspect open.
+            # Clean it up before returning from this early path as well.
+            if BROWSER_KIND == "local":
+                await self._close_inspect_tabs(targets)
+            pages_by_id = {t["targetId"]: t for t in targets if t["type"] == "page"}
+            # A stale CDP session does not necessarily mean its tab disappeared.
+            # Reattach to the current tab first, then the daemon's dedicated tab.
+            page = pages_by_id.get(self.target_id) or pages_by_id.get(self.dedicated_target_id)
+            if page is None:
+                # Two stale IPC requests can recover concurrently. Recheck
+                # inside a narrow lock so they share one replacement tab.
+                async with self._dedicated_target_lock:
+                    refreshed = (await self.cdp.send_raw("Target.getTargets"))["targetInfos"]
+                    pages_by_id = {t["targetId"]: t for t in refreshed if t["type"] == "page"}
+                    page = pages_by_id.get(self.target_id) or pages_by_id.get(self.dedicated_target_id)
+                    if page is None:
+                        tid = (await self.cdp.send_raw(
+                            "Target.createTarget", {"url": "about:blank", "background": True}
+                        ))["targetId"]
+                        self.dedicated_target_id = tid
+                        log(f"named daemon {NAME}: created dedicated tab ({tid})")
+                        page = {"targetId": tid, "url": "about:blank", "type": "page"}
+            tid = page["targetId"]
+            self.session = (await self.cdp.send_raw(
+                "Target.attachToTarget", {"targetId": tid, "flatten": True}
+            ))["sessionId"]
+            self._record_session_replacement(replaces_session, self.session)
+            self.target_id = tid
+            log(f"attached {tid} ({page.get('url','')[:80]}) session={self.session}")
+            if enable_domains:
+                await self._enable_default_domains(self.session)
+            return page
+
+        pages = [t for t in targets if is_real_page(t)]
+        if not pages:
+            # Fresh browser (ex: BU cloud) starts w about:blank; reuse it
+            pages = [t for t in targets if is_reusable_blank_page(t)]
+        if not pages:
+            # Freshly launched browser (ex: harness relaunching closed Chrome)
+            # starts with just the New Tab Page. Reuse it — creating about:blank
+            pages = [t for t in targets if is_reusable_new_tab_page(t)]
+        take_over = None
+        if not pages and harness_opened_inspect():
+            # After perms granted, only tab is often chrome://inspect
+            # Attach to it instead of creating a new about:blank
+            inspect_tabs = [t for t in targets if is_inspect_tab(t)]
+            if inspect_tabs:
+                pages = [inspect_tabs[0]]
+                take_over = inspect_tabs[0]["targetId"]
+        if not pages:
+            # No usable pages - create one instead of attaching to omnibox popup.
+            tid = (await self.cdp.send_raw(
+                "Target.createTarget", {"url": "about:blank", "background": True}
+            ))["targetId"]
+            log(f"no real pages found, created about:blank ({tid})")
+            pages = [{"targetId": tid, "url": "about:blank", "type": "page"}]
+        self.session = (await self.cdp.send_raw(
+            "Target.attachToTarget", {"targetId": pages[0]["targetId"], "flatten": True}
+        ))["sessionId"]
+        self._record_session_replacement(replaces_session, self.session)
+        self.target_id = pages[0]["targetId"]
+        log(f"attached {pages[0]['targetId']} ({pages[0].get('url','')[:80]}) session={self.session}")
+        if take_over:
+            try:
+                await self.cdp.send_raw("Page.navigate", {"url": "about:blank"}, session_id=self.session)
+                log(f"took over inspect tab {take_over} -> about:blank")
+            except Exception as e:
+                log(f"take over inspect tab {take_over}: {e}")
+        if BROWSER_KIND == "local":
+            await self._close_inspect_tabs(targets)
+        if enable_domains:
+            await self._enable_default_domains(self.session)
+        return pages[0]
+
+    async def _close_inspect_tabs(self, targets):
+        """Close chrome://inspect tabs left open by the permission recovery flow"""
+        if not harness_opened_inspect():
+            return
+        for t in targets:
+            if t["targetId"] != self.target_id and is_inspect_tab(t):
+                try:
+                    await self.cdp.send_raw("Target.closeTarget", {"targetId": t["targetId"]})
+                    log(f"closed leftover chrome://inspect tab {t['targetId']}")
+                except Exception as e:
+                    log(f"close inspect tab {t['targetId']}: {e}")
+        try:
+            paths.inspect_marker().unlink()
+        except OSError:
+            pass
+
+    async def _enable_default_domains(self, session_id):
+        """Enable Page/DOM/Runtime/Network on a CDP session.
+
+        Used by both initial attach and set_session (called after switch_tab/
+        new_tab). Without this, helpers that depend on Network.* events —
+        notably wait_for_network_idle() — silently stop receiving events
+        after a tab switch, because each fresh CDP session starts with all
+        domains disabled.
+
+        Runs the four enables in parallel via gather so the worst-case time is
+        bounded by a single CDP round trip rather than four sequential ones —
+        important on the set_session path, where the helper's IPC socket has
+        a 5s read timeout.
+        """
+        async def enable_one(d):
+            try:
+                await asyncio.wait_for(
+                    self.cdp.send_raw(f"{d}.enable", session_id=session_id),
+                    timeout=4,
+                )
+            except Exception as e:
+                log(f"enable {d} on {session_id}: {e}")
+        await asyncio.gather(*(enable_one(d) for d in ("Page", "DOM", "Runtime", "Network")))
+
+    def _record_session_replacement(self, stale_session, replacement_session):
+        """Remember which recovered session still controls the same tab."""
+        if not stale_session or not replacement_session or stale_session == replacement_session:
+            return
+        # Preserve chains so requests delayed across multiple recoveries still
+        # land on their original tab, never whichever tab is current now.
+        for source, replacement in list(self._session_replacements.items()):
+            if replacement == stale_session:
+                self._session_replacements[source] = replacement_session
+        self._session_replacements[stale_session] = replacement_session
+        while len(self._session_replacements) > 32:
+            self._session_replacements.pop(next(iter(self._session_replacements)))
+
+    def _begin_recovery(self):
+        """Register the current IPC handler unless shutdown has started."""
+        if self._shutting_down:
+            return None
+        task = asyncio.current_task()
+        if task is None:
+            return None
+        self._recovery_tasks.add(task)
+        self._active_recoveries += 1
+        self._recoveries_idle.clear()
+        return task
+
+    def _finish_recovery(self, task):
+        self._recovery_tasks.discard(task)
+        self._active_recoveries -= 1
+        if self._active_recoveries == 0:
+            self._recoveries_idle.set()
+
+    async def _cancel_and_drain_recoveries(self):
+        """Cancel active stale-session handlers and wait a bounded time."""
+        current = asyncio.current_task()
+        tasks = [
+            task for task in self._recovery_tasks
+            if task is not current and not task.done()
+        ]
+        for task in tasks:
+            task.cancel()
+        if tasks:
+            _done, pending = await asyncio.wait(
+                tasks, timeout=RECOVERY_CANCEL_DRAIN_TIMEOUT
+            )
+            if pending:
+                return False
+        return self._recoveries_idle.is_set()
+
+    def _schedule_tab_marker(self, session_id):
+        """Mark the controlled tab without extending the synchronous IPC path."""
+        if not tab_marker_enabled():
+            return None
+        return asyncio.create_task(_silent(asyncio.wait_for(
+            self.cdp.send_raw(
+                "Runtime.evaluate",
+                {"expression": TAB_MARKER_JS},
+                session_id=session_id,
+            ),
+            timeout=2,
+        )))
+
+    def _record_event(self, method, params, session_id=None):
+        self.events.append({"method": method, "params": params, "session_id": session_id})
+        if method == "Page.javascriptDialogOpening":
+            self.dialog = params
+        elif method == "Page.javascriptDialogClosed":
+            self.dialog = None
+        elif method in ("Page.loadEventFired", "Page.domContentEventFired"):
+            self._schedule_tab_marker(self.session)
+
+    async def start(self):
+        self.stop = asyncio.Event()
+        url = get_ws_url()
+        log(f"connecting to {_safe_connection_label(url)}")
+        self.cdp = _PatientCDPClient(url) if BROWSER_KIND == "local" else CDPClient(url)
+        if BROWSER_KIND == "local":
+            # Allow while this handshake is still parked on the popup
+            log("handshake-wait: if Chrome shows an 'Allow remote debugging?' popup, click Allow")
+        try:
+            await self.cdp.start()
+        except Exception as e:
+            if os.environ.get("BU_CDP_WS"):
+                raise RuntimeError(
+                    f"CDP WS handshake failed: {e} -- remote browser WebSocket connection failed. "
+                    "This can happen when network policy blocks the connection, the WS URL is wrong or expired, or the remote endpoint is down. "
+                    "If you use Browser Use cloud, verify auth and get a fresh URL via start_remote_daemon()."
+                )
+            if BROWSER_KIND == "local" and ("timed out" in str(e).lower() or "403" in str(e)) and remote_debugging_user_enabled():
+                raise RuntimeError(
+                    "permission-blocked: Chrome did not approve the remote debugging connection; "
+                    "browser-harness did not retry or create another connection"
+                )
+            raise RuntimeError(f"CDP WS handshake failed: {e} -- click Allow in Chrome if prompted, then retry")
+        await self.attach_first_page()
+        orig = self.cdp._event_registry.handle_event
+        async def tap(method, params, session_id=None):
+            self._record_event(method, params, session_id)
+            return await orig(method, params, session_id)
+        self.cdp._event_registry.handle_event = tap
+
+    async def handle(self, req):
+        # Token guard for Windows TCP loopback: any local process can otherwise
+        # connect and issue CDP commands. expected_token() is None on POSIX so
+        # this check is a no-op there (AF_UNIX + chmod 600 is the boundary).
+        expected = ipc.expected_token()
+        if expected is not None and req.get("token") != expected:
+            return {"error": "unauthorized"}
+        meta = req.get("meta")
+        # Liveness probe — lets clients confirm the listener is actually this
+        # daemon and not an unrelated process that reused our port post-crash.
+        # `pid` lets restart_daemon() verify the live daemon's identity before
+        # signaling — protects against SIGTERM-by-stale-pid-file after PID reuse.
+        if meta == "ping":        return {"pong": True, "pid": os.getpid(), "browser_kind": BROWSER_KIND}
+        if meta == "drain_events":
+            out = list(self.events); self.events.clear()
+            return {"events": out}
+        if meta == "session":     return {"session_id": self.session}
+        if meta == "current_tab":
+            # Resolve the attached page's target info server-side. Helpers can't
+            # send Target.getTargetInfo themselves: daemon strips session_id for
+            # any Target.* method (browser-level call), and without a targetId
+            # Chrome silently returns the *browser* target.
+            if not self.target_id:
+                return {"error": "not_attached"}
+            try:
+                info = (await self.cdp.send_raw("Target.getTargetInfo", {"targetId": self.target_id}))["targetInfo"]
+            except Exception:
+                return {"error": "cdp_disconnected"}
+            return {"targetId": info.get("targetId"), "url": info.get("url", ""), "title": info.get("title", "")}
+        if meta == "connection_status":
+            if not self.target_id:
+                return {"error": "not_attached"}
+            try:
+                info = (await self.cdp.send_raw("Target.getTargetInfo", {"targetId": self.target_id}))["targetInfo"]
+            except Exception:
+                return {"error": "cdp_disconnected"}
+            page = None
+            if is_real_page(info):
+                page = {
+                    "targetId": info.get("targetId"),
+                    "title": info.get("title") or "(untitled)",
+                    "url": info.get("url") or "",
+                }
+            return {"target_id": self.target_id, "session_id": self.session, "page": page}
+        if meta == "set_session":
+            async with self._session_state_lock:
+                old_session = self.session
+                self.session = req.get("session_id")
+                self.target_id = req.get("target_id") or self.target_id
+                new_session = self.session
+            # Run the old-session Network.disable (defense in depth — keeps
+            # background-tab traffic out of the global event buffer; the
+            # consumer-side filter in wait_for_network_idle is the actual
+            # correctness gate) in parallel with the four enables on the new
+            # session. Different sessions, independent CDP requests. Keeps
+            # the synchronous reply under the helper's 5s IPC read timeout
+            # even on a remote daemon — sequentially these would have stacked
+            # to ~22s worst case.
+            tasks = []
+            if old_session and old_session != new_session:
+                async def disable_old():
+                    try:
+                        await asyncio.wait_for(
+                            self.cdp.send_raw("Network.disable", session_id=old_session),
+                            timeout=2,
+                        )
+                    except Exception: pass
+                tasks.append(disable_old())
+            tasks.append(self._enable_default_domains(new_session))
+            await asyncio.gather(*tasks)
+            # 🐴 tab-marker title prefix is purely cosmetic — fire-and-forget so
+            # it doesn't add to the synchronous IPC budget.
+            self._schedule_tab_marker(new_session)
+            return {"session_id": new_session}
+        if meta == "pending_dialog": return {"dialog": self.dialog}
+        if meta == "shutdown":
+            # Flip the barrier synchronously with recovery registration, then
+            # cancel/drain existing handlers. In particular, a CDP replay that
+            # never answers must not prevent Cloud cleanup from being attempted.
+            if self._shutting_down:
+                return {"error": "shutdown already in progress"}
+            self._shutting_down = True
+            if not await self._cancel_and_drain_recoveries():
+                # Preserve the daemon as a retryable cleanup authority. The
+                # strict caller will leave its endpoint and PID file intact.
+                self._shutting_down = False
+                return {"error": "stale-session recovery did not stop"}
+            try:
+                stop_remote(strict=True)
+            except Exception as e:
+                # A failed Cloud stop must leave the daemon usable so a later
+                # shutdown request can retry the billable-browser cleanup.
+                async with self._session_state_lock:
+                    self._shutting_down = False
+                return {"error": str(e)}
+            self.stop.set()
+            return {"ok": True}
+
+        method = req["method"]
+        params = req.get("params") or {}
+        # Browser-level Target.* calls must not use a session (stale or otherwise).
+        # For everything else, explicit session in req wins; else default.
+        sid = None if method.startswith("Target.") else (req.get("session_id") or self.session)
+        try:
+            return {"result": await self.cdp.send_raw(method, params, session_id=sid)}
+        except Exception as e:
+            msg = str(e)
+            if "Session with given id not found" in msg and sid:
+                # Explicit session callers asked for that exact session; do not
+                # silently redirect them to the daemon's current tab.
+                if req.get("session_id"):
+                    return {"error": msg}
+                recovery_task = self._begin_recovery()
+                if recovery_task is None:
+                    return {"error": "daemon is shutting down"}
+                try:
+                    recovered_here = False
+                    async with self._session_state_lock:
+                        if self._shutting_down:
+                            return {"error": "daemon is shutting down"}
+                        replacement_session = self._session_replacements.get(sid)
+                        if replacement_session is None and sid == self.session:
+                            log(f"stale session {sid}, re-attaching")
+                            if not await self.attach_first_page(
+                                replaces_session=sid, enable_domains=False
+                            ):
+                                return {"error": msg}
+                            replacement_session = self._session_replacements.get(sid)
+                            recovered_here = replacement_session is not None
+                    if recovered_here:
+                        await self._enable_default_domains(replacement_session)
+                    # Retry only on a session known to replace this exact stale
+                    # session. self.session may instead have changed because the
+                    # user deliberately switched tabs while this request waited.
+                    if replacement_session:
+                        try:
+                            return {"result": await self.cdp.send_raw(
+                                method, params, session_id=replacement_session
+                            )}
+                        except Exception as retry_error:
+                            return {"error": str(retry_error)}
+                finally:
+                    self._finish_recovery(recovery_task)
+            return {"error": msg}
+
+
+async def serve(d):
+    async def handler(reader, writer):
+        try:
+            line = await reader.readline()
+            if not line: return
+            resp = await d.handle(json.loads(line))
+            writer.write((json.dumps(resp, default=str) + "\n").encode())
+            await writer.drain()
+        except Exception as e:
+            log(f"conn: {e}")
+            try:
+                writer.write((json.dumps({"error": str(e)}) + "\n").encode())
+                await writer.drain()
+            except Exception:
+                pass
+        finally:
+            writer.close()
+
+    serve_task = asyncio.create_task(ipc.serve(NAME, handler))
+    stop_task = asyncio.create_task(d.stop.wait())
+    await asyncio.sleep(0.05)  # let serve() bind so sock_addr() resolves to the live endpoint
+    log(f"listening on {ipc.sock_addr(NAME)} (name={NAME}, remote={REMOTE_ID or 'local'})")
+    try:
+        await asyncio.wait({serve_task, stop_task}, return_when=asyncio.FIRST_COMPLETED)
+        if serve_task.done(): await serve_task  # surfaces a serve crash
+    finally:
+        for t in (serve_task, stop_task):
+            t.cancel()
+            try: await t
+            except (asyncio.CancelledError, Exception): pass
+        # A server crash/cancellation does not pass through meta=shutdown.
+        # Establish the same recovery barrier before touching owned targets.
+        d._shutting_down = True
+        recoveries_drained = await d._cancel_and_drain_recoveries()
+        # Named non-cloud daemons create one dedicated background tab. Shutdown
+        # has blocked new recovery and drained active recovery before setting
+        # d.stop (or finalization established the barrier after a server crash).
+        # Take the same locks, in the same order as recovery, so cleanup closes
+        # exactly the final daemon-owned target and never races creation.
+        if recoveries_drained:
+            async with d._session_state_lock:
+                async with d._dedicated_target_lock:
+                    if d.dedicated_target_id and d.cdp:
+                        try:
+                            await d.cdp.send_raw(
+                                "Target.closeTarget", {"targetId": d.dedicated_target_id}
+                            )
+                            d.dedicated_target_id = None
+                        except Exception as e:
+                            log(f"close dedicated tab on shutdown: {e}")
+        else:
+            log("skip dedicated-tab cleanup: stale-session recovery did not stop")
+        ipc.cleanup_endpoint(NAME)
+
+
+async def main():
+    d = Daemon()
+    await d.start()
+    await serve(d)
+
+
+def already_running():
+    # Ping handshake (not a bare connect) so a stale .port file + port reuse
+    # after a daemon crash doesn't make us mistake an unrelated listener for ours.
+    return ipc.ping(NAME, timeout=1.0)
+
+
+if __name__ == "__main__":
+    if already_running():
+        print(f"daemon already running on {SOCK}", file=sys.stderr)
+        sys.exit(0)
+    open(LOG, "w").close()
+    _publish_own_pid()
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        pass
+    except Exception as e:
+        log(f"fatal: {e}")
+        sys.exit(1)
+    finally:
+        stop_remote()
+        try: os.unlink(PID)
+        except FileNotFoundError: pass