escarp 1.0.0__py3-none-any.whl

escarp/__init__.py

@@ -0,0 +1,13 @@
+"""Escarp -- identity-aware runtime for parallel coding agents.
+
+Public surface is the `escarp` and `escarp-mcp` CLIs and the broker's HTTP
+API on http://127.0.0.1:7878. See README.md for the quick-start.
+
+For programmatic access, import directly from the submodules:
+    from escarp.broker import claim_slot, ports_for_slot
+    from escarp.broker.lease import Broker
+    from escarp.broker.discovery import discover_pool
+"""
+
+__version__ = "1.0.0"
+__all__ = ["__version__"]

escarp/broker/__init__.py

@@ -0,0 +1,8 @@
+"""Escarp v2 broker: control-plane daemon for the worktree browser pool.
+
+See V2_PLAN.md for the design. Public surface lives in `daemon` and `cli`.
+"""
+
+from escarp.broker.slots import SlotLease, claim_slot, ports_for_slot
+
+__all__ = ["SlotLease", "claim_slot", "ports_for_slot"]

escarp/broker/api.py

@@ -0,0 +1,135 @@
+"""HTTP layer for the broker daemon.
+
+Bind-and-shift on EADDRINUSE per V2_PLAN.md locked decision #6. Three verbs
+plus one read endpoint:
+
+    GET  /status                 -> pool snapshot (no lease tokens leaked)
+    POST /acquire {holder, slot?, dev_port?}  -> LeaseRecord incl. token
+    POST /heartbeat {lease_token}             -> LeaseRecord (refreshed expiry)
+    POST /release {lease_token}               -> LeaseRecord (now free)
+    GET  /reaped                              -> last-50 reap log (debugging)
+
+Returns 409 for pool_exhausted / slot_leased, 404 for unknown_slot /
+unknown_lease, 400 for malformed payloads. The MCP shim translates these
+into model-readable errors; the LLM never sees raw HTTP status codes.
+"""
+
+from __future__ import annotations
+
+import errno
+import socket
+from dataclasses import asdict
+
+from aiohttp import web
+
+from escarp.broker.lease import (
+    Broker,
+    PoolExhausted,
+    SlotLeased,
+    UnknownLease,
+    UnknownSlot,
+)
+
+DEFAULT_PORT = 7878
+
+
+def build_app(broker: Broker) -> web.Application:
+    routes = web.RouteTableDef()
+
+    @routes.get("/status")
+    async def status(_request: web.Request) -> web.Response:
+        return web.json_response(
+            {
+                "pool_size": broker.pool_size(),
+                "lease_ttl_s": broker.lease_ttl_s,
+                "slots": broker.snapshot(),
+            }
+        )
+
+    @routes.post("/acquire")
+    async def acquire(request: web.Request) -> web.Response:
+        try:
+            body = await request.json()
+        except Exception:
+            return web.json_response({"error": "bad_json"}, status=400)
+        holder = body.get("holder")
+        if not holder or not isinstance(holder, str):
+            return web.json_response({"error": "missing_holder"}, status=400)
+        slot = body.get("slot")
+        dev_port = body.get("dev_port")
+        try:
+            rec = await broker.acquire(holder=holder, slot=slot, dev_port=dev_port)
+        except PoolExhausted:
+            return web.json_response(
+                {"error": "pool_exhausted", "snapshot": broker.snapshot()},
+                status=409,
+            )
+        except SlotLeased as exc:
+            return web.json_response({"error": "slot_leased", "message": str(exc)}, status=409)
+        except UnknownSlot as exc:
+            return web.json_response({"error": "unknown_slot", "message": str(exc)}, status=404)
+        # The acquire response is the ONLY place we return the lease token.
+        return web.json_response(asdict(rec))
+
+    @routes.post("/heartbeat")
+    async def heartbeat(request: web.Request) -> web.Response:
+        try:
+            body = await request.json()
+        except Exception:
+            return web.json_response({"error": "bad_json"}, status=400)
+        token = body.get("lease_token")
+        if not token:
+            return web.json_response({"error": "missing_lease_token"}, status=400)
+        try:
+            rec = await broker.heartbeat(lease_token=token)
+        except UnknownLease as exc:
+            return web.json_response({"error": "unknown_lease", "message": str(exc)}, status=404)
+        return web.json_response(asdict(rec))
+
+    @routes.post("/release")
+    async def release(request: web.Request) -> web.Response:
+        try:
+            body = await request.json()
+        except Exception:
+            return web.json_response({"error": "bad_json"}, status=400)
+        token = body.get("lease_token")
+        if not token:
+            return web.json_response({"error": "missing_lease_token"}, status=400)
+        try:
+            rec = await broker.release(lease_token=token)
+        except UnknownLease as exc:
+            return web.json_response({"error": "unknown_lease", "message": str(exc)}, status=404)
+        return web.json_response(rec.to_public())
+
+    @routes.get("/reaped")
+    async def reaped(_request: web.Request) -> web.Response:
+        return web.json_response({"reaped": broker.reaped_log()})
+
+    app = web.Application()
+    app.add_routes(routes)
+    return app
+
+
+def bind_with_shift(host: str, preferred_port: int, *, max_attempts: int = 10) -> tuple[socket.socket, int]:
+    """Bind a TCP socket atomically; on EADDRINUSE shift by +10 and retry.
+
+    Per V2_PLAN.md locked decision #6: bind() is the atomic test, no
+    pre-check race. Returns (bound socket, actual port).
+    """
+    last_error: OSError | None = None
+    for i in range(max_attempts):
+        port = preferred_port + i * 10
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        try:
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            sock.bind((host, port))
+            sock.listen(128)
+            return sock, port
+        except OSError as exc:
+            sock.close()
+            if exc.errno not in (errno.EADDRINUSE, errno.EACCES):
+                raise
+            last_error = exc
+    raise OSError(
+        f"could not bind {host}:{preferred_port} after {max_attempts} attempts: {last_error}"
+    )

escarp/broker/browser.py

@@ -0,0 +1,220 @@
+"""Chrome for Testing launcher and CDP discovery.
+
+Phase 2 minimal: detached subprocess + HTTP /json/version discovery. No lease
+state, no reset logic — that's Phase 3. This module owns "how do we make a
+CfT window exist on the user's monitor and surface its CDP websocket URL."
+
+Discovery contract (per Phase 0 smoke test, see V2_PLAN.md §9):
+- Primary: GET http://127.0.0.1:<cdp_port>/json/version -> webSocketDebuggerUrl.
+  Empirically confirmed working in CfT 149.0.7827.54 on macOS arm64.
+- The DevToolsActivePort file the original plan called for does NOT appear in
+  macOS profile dirs in our testing.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import signal
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+import httpx
+
+# Locked launch flags, per V2_PLAN.md §7 Phase 2.
+_BASE_FLAGS: tuple[str, ...] = (
+    "--no-first-run",
+    "--no-default-browser-check",
+    "--disable-backgrounding-occluded-windows",
+    "--disable-renderer-backgrounding",
+    "--disable-background-timer-throttling",
+    "--disable-extensions",
+)
+
+
+class BrowserLaunchError(RuntimeError):
+    pass
+
+
+@dataclass
+class ManagedBrowser:
+    slot: int
+    cdp_port: int
+    cdp_ws_url: str
+    profile_dir: Path
+    process: subprocess.Popen[bytes]
+
+    @property
+    def pid(self) -> int:
+        return self.process.pid
+
+    def is_alive(self) -> bool:
+        return self.process.poll() is None
+
+
+def launch_cft(
+    *,
+    slot: int,
+    binary: Path,
+    profile_dir: Path,
+    cdp_port: int,
+    initial_url: str = "about:blank",
+    discovery_timeout: float = 10.0,
+) -> ManagedBrowser:
+    """Launch a detached Chrome for Testing process and resolve its CDP URL.
+
+    The process is started in a new session (`start_new_session=True`) so that
+    when our parent shell or the daemon exits, the browser is reparented to
+    launchd/init rather than being killed. This is the load-bearing detail
+    for the "browsers outlive every agent" persistence contract.
+    """
+    if not binary.exists():
+        raise BrowserLaunchError(f"Chrome for Testing binary not found at {binary}")
+
+    profile_dir.mkdir(parents=True, exist_ok=True)
+
+    args = [
+        str(binary),
+        f"--remote-debugging-port={cdp_port}",
+        f"--user-data-dir={profile_dir}",
+        *_BASE_FLAGS,
+        initial_url,
+    ]
+
+    process = subprocess.Popen(
+        args,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        stdin=subprocess.DEVNULL,
+        start_new_session=True,
+        close_fds=True,
+    )
+
+    try:
+        ws_url = _resolve_ws_url(cdp_port, timeout=discovery_timeout)
+    except Exception:
+        # Discovery failed; don't leak the process.
+        _terminate(process)
+        raise
+
+    return ManagedBrowser(
+        slot=slot,
+        cdp_port=cdp_port,
+        cdp_ws_url=ws_url,
+        profile_dir=profile_dir,
+        process=process,
+    )
+
+
+def _resolve_ws_url(cdp_port: int, *, timeout: float) -> str:
+    """Poll /json/version until we get a webSocketDebuggerUrl or time out."""
+    deadline = time.monotonic() + timeout
+    last_error: Exception | None = None
+    while time.monotonic() < deadline:
+        try:
+            resp = httpx.get(
+                f"http://127.0.0.1:{cdp_port}/json/version",
+                timeout=1.0,
+            )
+            resp.raise_for_status()
+            ws_url = resp.json().get("webSocketDebuggerUrl")
+            if ws_url:
+                return ws_url
+        except Exception as exc:
+            last_error = exc
+        time.sleep(0.1)
+    raise BrowserLaunchError(
+        f"CDP discovery timed out after {timeout}s on port {cdp_port}"
+        + (f" (last error: {last_error})" if last_error else "")
+    )
+
+
+def _terminate(process: subprocess.Popen[bytes], *, grace: float = 3.0) -> None:
+    if process.poll() is not None:
+        return
+    try:
+        process.send_signal(signal.SIGTERM)
+        process.wait(timeout=grace)
+    except subprocess.TimeoutExpired:
+        process.kill()
+        process.wait(timeout=grace)
+
+
+def shutdown(browser: ManagedBrowser, *, grace: float = 3.0) -> None:
+    _terminate(browser.process, grace=grace)
+
+
+async def reset_browser_state(cdp_port: int, *, target_url: str = "about:blank") -> int:
+    """Reset a leased browser to a clean slate.
+
+    Per V2_PLAN.md §7 Phase 2: "on lease release, reset -- never close." Closes
+    every page-type tab except a freshly-created one navigated to target_url.
+    Internal target types (browser_ui, service_worker, etc.) are left alone --
+    those are chrome's own plumbing, not user-visible tabs.
+
+    Uses only the CfT /json HTTP endpoints (verified working in 149) -- no
+    websocket dance, no extra deps beyond httpx.
+
+    Returns the number of stale tabs closed (zero on a pristine browser).
+    """
+    import httpx  # local import keeps the sync launch_cft path light
+
+    async with httpx.AsyncClient(timeout=5.0) as client:
+        # Order matters: create the new clean tab FIRST so we never close down
+        # to zero tabs (which would close the only window and kill the process).
+        new_resp = await client.put(f"http://127.0.0.1:{cdp_port}/json/new?{target_url}")
+        new_resp.raise_for_status()
+        new_id = new_resp.json()["id"]
+
+        list_resp = await client.get(f"http://127.0.0.1:{cdp_port}/json/list")
+        list_resp.raise_for_status()
+        tabs = list_resp.json()
+
+        closed = 0
+        for tab in tabs:
+            if tab.get("type") != "page" or tab.get("id") == new_id:
+                continue
+            try:
+                close_resp = await client.get(
+                    f"http://127.0.0.1:{cdp_port}/json/close/{tab['id']}"
+                )
+                if close_resp.status_code < 400:
+                    closed += 1
+            except httpx.HTTPError:
+                # Best-effort: a tab that vanished mid-loop isn't a problem.
+                pass
+        return closed
+
+
+def find_cft_binary() -> Path | None:
+    """Best-effort discovery for the Chrome for Testing binary.
+
+    Order: $ESCARP_CFT_BINARY env, ~/.escarp/chrome/**, ./chrome/** (repo-local
+    dev install). Returns None if nothing usable is found.
+    """
+    env = os.environ.get("ESCARP_CFT_BINARY")
+    if env:
+        path = Path(env)
+        if path.exists():
+            return path
+    candidates = [
+        Path.home() / ".escarp" / "chrome",
+        Path.cwd() / "chrome",
+    ]
+    for root in candidates:
+        if not root.exists():
+            continue
+        # @puppeteer/browsers layout: chrome/<platform>-<ver>/chrome-<plat>/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing
+        for app in root.rglob("Google Chrome for Testing.app"):
+            macos = app / "Contents" / "MacOS" / "Google Chrome for Testing"
+            if macos.exists():
+                return macos
+        # Linux layout: chrome/<platform>-<ver>/chrome-linux64/chrome
+        for binary in root.rglob("chrome"):
+            if binary.is_file() and os.access(binary, os.X_OK) and "chrome-" in str(binary.parent):
+                return binary
+    # Last resort: PATH lookup
+    which = shutil.which("chrome-for-testing")
+    return Path(which) if which else None

escarp/broker/daemon.py

@@ -0,0 +1,214 @@
+"""Broker daemon: discovers already-running browsers, brokers leases, runs reaper.
+
+**Does NOT own chrome lifecycles.** Per V2_PLAN.md's persistence contract,
+chromes are infrastructure that exists independently. To start the chromes,
+run `escarp launch-pool` (or launchd, systemd, docker, manual shell, whatever).
+This daemon's only relationship to a chrome is "discover via /json/version,
+talk to it over CDP, never kill it."
+
+End-to-end shape:
+
+    [user] $ escarp launch-pool          # one-shot, exits, chromes persist
+    [user] $ escarp daemon               # discovers chromes, brokers leases
+        |
+        +-- claim N slot locks (flock)   <- "I am the broker for this pool"
+        +-- discover each slot via /json/version
+        +-- Broker.register() each discovered browser
+        +-- reset each browser to about:blank (state hygiene at boot)
+        +-- aiohttp server starts on 127.0.0.1:7878
+        +-- reaper task starts (sweeps every 2s)
+        +-- ^C -> cancel reaper, close server, release locks. CHROMES STAY ALIVE.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import signal
+import sys
+
+from aiohttp import web
+
+from escarp.broker.api import DEFAULT_PORT, bind_with_shift, build_app
+from escarp.broker.browser import reset_browser_state
+from escarp.broker.discovery import DiscoveredBrowser, discover_pool
+from escarp.broker.lease import Broker, reaper_loop
+from escarp.broker.slots import SlotBusy, SlotLease, claim_slot
+
+DEFAULT_POOL_SIZE = 4
+DEFAULT_CDP_BASE_PORT = 9222
+
+
+def _env_int(name: str, default: int) -> int:
+    raw = os.environ.get(name)
+    if raw is None:
+        return default
+    try:
+        return int(raw)
+    except ValueError as exc:
+        raise SystemExit(f"{name} must be an integer, got {raw!r}") from exc
+
+
+def _format_table(leases: list[SlotLease], browsers: list[DiscoveredBrowser]) -> str:
+    rows = [f"{'slot':<6}{'cdp':<8}{'frontend':<10}{'backend':<10}cdp_ws_url"]
+    for lease, browser in zip(leases, browsers, strict=True):
+        rows.append(
+            f"{lease.slot:<6}"
+            f"{lease.ports.cdp:<8}"
+            f"{lease.ports.frontend:<10}"
+            f"{lease.ports.backend:<10}"
+            f"{browser.cdp_ws_url}"
+        )
+    return "\n".join(rows)
+
+
+async def _serve_http(broker: Broker, api_port: int) -> tuple[web.AppRunner, int]:
+
+    app = build_app(broker)
+    runner = web.AppRunner(app)
+    await runner.setup()
+    sock, actual_port = bind_with_shift("127.0.0.1", api_port)
+    site = web.SockSite(runner, sock)
+    await site.start()
+    return runner, actual_port
+
+
+async def run_daemon(
+    *,
+    pool_size: int,
+    cdp_base_port: int,
+    api_port: int,
+    lease_ttl_s: float,
+    discovery_wait_s: float,
+) -> int:
+    leases: list[SlotLease] = []
+    browsers: list[DiscoveredBrowser] = []
+
+    async def reset_for_port(cdp_port: int) -> None:
+        try:
+            closed = await reset_browser_state(cdp_port)
+            print(f"[reset] cdp_port={cdp_port} closed {closed} stale tab(s)", flush=True)
+        except Exception as exc:
+            print(f"[reset] cdp_port={cdp_port} failed: {exc}", file=sys.stderr, flush=True)
+
+    broker = Broker(lease_ttl_s=lease_ttl_s, reset_fn=reset_for_port)
+    runner: web.AppRunner | None = None
+    reaper_task: asyncio.Task[None] | None = None
+    stop_event = asyncio.Event()
+
+    try:
+        # 1. Discover whatever's already running.
+        print(
+            f"discovering pool: slots [0, {pool_size}) on cdp_ports "
+            f"{cdp_base_port}..{cdp_base_port + pool_size - 1}",
+            flush=True,
+        )
+        discovered, missing = await discover_pool(
+            pool_size=pool_size,
+            cdp_base_port=cdp_base_port,
+            wait_for_each=discovery_wait_s,
+        )
+        for slot in missing:
+            print(
+                f"[slot {slot}] no chrome on cdp_port {cdp_base_port + slot}. "
+                f"Run `escarp launch-pool` (or start a chrome there) first.",
+                file=sys.stderr,
+                flush=True,
+            )
+        if not discovered:
+            print("nothing to broker. exiting.", file=sys.stderr, flush=True)
+            return 1
+
+        # 2. Claim slot locks for whatever's discovered; register into the broker.
+        for browser in discovered:
+            try:
+                lease = claim_slot(browser.slot)
+            except SlotBusy as exc:
+                print(
+                    f"[slot {browser.slot}] another broker holds the lock for this slot. {exc}",
+                    file=sys.stderr,
+                    flush=True,
+                )
+                continue
+            leases.append(lease)
+            browsers.append(browser)
+            broker.register(
+                slot=browser.slot,
+                cdp_port=browser.cdp_port,
+                cdp_ws_url=browser.cdp_ws_url,
+                pid=-1,  # we don't own this process
+            )
+            try:
+                stale_closed = await reset_browser_state(browser.cdp_port)
+            except Exception as exc:
+                stale_closed = -1
+                print(f"[slot {browser.slot}] startup reset failed: {exc}", file=sys.stderr)
+            print(
+                f"[slot {browser.slot}] discovered  ws={browser.cdp_ws_url}"
+                f"  (reset closed {stale_closed} stale tab(s))",
+                flush=True,
+            )
+
+        if not browsers:
+            print("no slots brokered. exiting.", file=sys.stderr, flush=True)
+            return 1
+
+        # 3. HTTP + reaper.
+        runner, actual_port = await _serve_http(broker, api_port)
+        reaper_task = asyncio.create_task(reaper_loop(broker, stop=stop_event))
+
+        print()
+        print(_format_table(leases, browsers))
+        print()
+        print(f"broker http api:  http://127.0.0.1:{actual_port}")
+        print(f"lease ttl:        {lease_ttl_s}s   reaper interval: 2s")
+        print(f"try: curl http://127.0.0.1:{actual_port}/status | jq")
+        print(
+            f"\npool of {len(browsers)} brokered. chromes are NOT owned by this daemon "
+            f"and will survive ctrl-c.",
+            flush=True,
+        )
+        print("ctrl-c to release the slot locks and stop brokering.\n", flush=True)
+
+        loop = asyncio.get_running_loop()
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            loop.add_signal_handler(sig, stop_event.set)
+
+        await stop_event.wait()
+        print("\nshutdown signal received. releasing slot locks; chromes left alive.")
+        return 0
+    finally:
+        stop_event.set()
+        if reaper_task is not None:
+            try:
+                await asyncio.wait_for(reaper_task, timeout=3.0)
+            except (TimeoutError, asyncio.CancelledError):
+                reaper_task.cancel()
+        if runner is not None:
+            await runner.cleanup()
+        for lease in leases:
+            lease.release()
+        # NOTE: intentionally do NOT touch chromes. They are infrastructure.
+
+
+def main(argv: list[str] | None = None) -> int:
+    pool_size = _env_int("ESCARP_POOL_SIZE", DEFAULT_POOL_SIZE)
+    if pool_size < 1:
+        raise SystemExit(f"ESCARP_POOL_SIZE must be >= 1, got {pool_size}")
+    cdp_base_port = _env_int("ESCARP_CDP_BASE", DEFAULT_CDP_BASE_PORT)
+    api_port = _env_int("ESCARP_API_PORT", DEFAULT_PORT)
+    lease_ttl_s = float(os.environ.get("ESCARP_LEASE_TTL_S", "60"))
+    discovery_wait_s = float(os.environ.get("ESCARP_DISCOVERY_WAIT_S", "0"))
+
+    try:
+        return asyncio.run(
+            run_daemon(
+                pool_size=pool_size,
+                cdp_base_port=cdp_base_port,
+                api_port=api_port,
+                lease_ttl_s=lease_ttl_s,
+                discovery_wait_s=discovery_wait_s,
+            )
+        )
+    except KeyboardInterrupt:
+        return 0

escarp/broker/discovery.py

@@ -0,0 +1,94 @@
+"""Discover already-running Chrome for Testing instances by cdp_port.
+
+Escarp v2's persistence contract: the broker does NOT own chrome lifecycles.
+Chromes are infrastructure that exists independently of escarp. The daemon's
+job is to discover what's listening on the per-slot cdp_ports and broker
+leases against those, full stop. If a chrome dies, that's somebody else's
+problem (or a launchd/systemd auto-restart's job).
+
+How to start chromes:
+  - `escarp launch-pool` (dev convenience, one-shot)
+  - launchd/systemd unit
+  - manual: `chrome-for-testing --remote-debugging-port=9222 --user-data-dir=...`
+  - docker
+  - whatever you want -- as long as cdp_ports 9222..9222+N-1 are listening.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+
+import httpx
+
+
+@dataclass(frozen=True)
+class DiscoveredBrowser:
+    slot: int
+    cdp_port: int
+    cdp_ws_url: str
+    browser_version: str
+
+
+async def probe(cdp_port: int, *, timeout: float = 2.0) -> dict | None:
+    """GET /json/version on cdp_port. Returns the json dict or None if nothing
+    is listening / response unparseable. Per Phase 0 findings, /json/version
+    is the right discovery primitive on CfT 149+."""
+    try:
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            resp = await client.get(f"http://127.0.0.1:{cdp_port}/json/version")
+            resp.raise_for_status()
+            return resp.json()
+    except (httpx.HTTPError, ValueError):
+        return None
+
+
+async def discover_pool(
+    *,
+    pool_size: int,
+    cdp_base_port: int = 9222,
+    wait_for_each: float = 0.0,
+) -> tuple[list[DiscoveredBrowser], list[int]]:
+    """Walk slots [0, pool_size). For each slot, probe cdp_base_port+slot.
+
+    Returns (discovered, missing_slots). `missing_slots` is the list of slot
+    indices whose cdp_port wasn't responding -- the caller decides what to do
+    about that (warn, retry, error out).
+    """
+    discovered: list[DiscoveredBrowser] = []
+    missing: list[int] = []
+    for slot in range(pool_size):
+        port = cdp_base_port + slot
+        info = await _probe_with_retry(port, wait_for_each=wait_for_each)
+        if info is None:
+            missing.append(slot)
+            continue
+        ws = info.get("webSocketDebuggerUrl")
+        if not ws:
+            missing.append(slot)
+            continue
+        discovered.append(
+            DiscoveredBrowser(
+                slot=slot,
+                cdp_port=port,
+                cdp_ws_url=ws,
+                browser_version=str(info.get("Browser", "")),
+            )
+        )
+    return discovered, missing
+
+
+async def _probe_with_retry(cdp_port: int, *, wait_for_each: float) -> dict | None:
+    """Best-effort: probe once; if missing and wait_for_each > 0, keep trying
+    up to that many seconds. Useful right after `escarp launch-pool` since
+    chrome can take a couple seconds to bind its CDP port."""
+    info = await probe(cdp_port)
+    if info is not None or wait_for_each <= 0:
+        return info
+    deadline = asyncio.get_running_loop().time() + wait_for_each
+    while asyncio.get_running_loop().time() < deadline:
+        await asyncio.sleep(0.2)
+        info = await probe(cdp_port)
+        if info is not None:
+            return info
+    return None