browserwright 0.7.0__tar.gz → 0.7.2__tar.gz

{browserwright-0.7.0 → browserwright-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: browserwright
-Version: 0.7.0
+Version: 0.7.2
 Summary: Browserwright — let AI/code agents drive a real or isolated browser and author userscripts. Single package: the agent-facing REPL/site-skills/memory layer plus the bundled browser-resolving daemon (CDP proxy + extension/cloud backends).
 Requires-Python: >=3.11
 Requires-Dist: cdp-use==1.4.5

{browserwright-0.7.0 → browserwright-0.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "browserwright"
-version = "0.7.0"
+version = "0.7.2"
 description = "Browserwright — let AI/code agents drive a real or isolated browser and author userscripts. Single package: the agent-facing REPL/site-skills/memory layer plus the bundled browser-resolving daemon (CDP proxy + extension/cloud backends)."
 requires-python = ">=3.11"
 dependencies = [

browserwright-0.7.2/src/browserwright/daemon/_stale.py

@@ -0,0 +1,174 @@
+"""Detect + reclaim a stale / half-alive browserwright daemon (issue #15 P2).
+
+A daemon killed mid-life — or one whose serve loop failed *after* binding its
+relay/facade TCP ports — can linger holding those ports while its control
+socket is dead. Then:
+
+  - `browserwright-daemon status` lies (`not_running`) though a process holds
+    the ports (issue #15, 2.1), and
+  - a fresh `serve` crash-loops on `EADDRINUSE` because nothing reclaims the
+    ports from the zombie (issue #15, 2.2).
+
+These helpers give `status` a truthful third state and let `serve` take over
+the ports from a *confirmed* browserwright daemon. The safety rule for any
+kill: only ever signal a pid that lsof confirms is holding the port AND whose
+command line confirms it is a browserwright daemon. When lsof is unavailable we
+never auto-kill — we surface the pid-file pid for the user to handle.
+"""
+from __future__ import annotations
+
+import os
+import signal
+import socket
+import subprocess
+import sys
+import time
+
+
+def daemon_tcp_ports(cfg) -> list[int]:
+    """The relay + facade TCP ports a daemon binds, derived from ``cfg``.
+
+    Best-effort + deduped — used by both `status` (to detect a port-holding
+    zombie) and `serve` (to reclaim those ports before binding). Kept here so
+    the two paths can never disagree on which ports matter."""
+    ports: list[int] = []
+    try:
+        _, relay_port = cfg.backends.extension.resolved_host_port()
+        if relay_port:
+            ports.append(int(relay_port))
+    except Exception:  # noqa: BLE001 - best-effort
+        pass
+    try:
+        fp = cfg.resolved_facade_port()
+        if fp:
+            ports.append(int(fp))
+    except Exception:  # noqa: BLE001
+        pass
+    return list(dict.fromkeys(ports))
+
+
+def port_is_listening(host: str, port: int) -> bool:
+    """True if something already holds ``host:port`` (a fresh bind fails).
+
+    Uses a plain bind attempt (no ``SO_REUSEADDR``) so a live listener reliably
+    trips ``EADDRINUSE``. Cheap, cross-platform, no external process."""
+    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    try:
+        s.bind((host, port))
+        return False  # we could bind → nobody holds it
+    except OSError:
+        return True
+    finally:
+        s.close()
+
+
+def port_holder_pids(port: int) -> list[int]:
+    """PIDs listening on TCP ``port`` (best-effort via ``lsof``).
+
+    Returns ``[]`` when lsof is missing / errors / finds nothing — callers must
+    treat an empty list as "unknown", never as "nobody"."""
+    if sys.platform == "win32":
+        return []
+    try:
+        out = subprocess.run(
+            ["lsof", "-nP", f"-iTCP:{port}", "-sTCP:LISTEN", "-t"],
+            capture_output=True, text=True, timeout=3,
+        )
+    except (FileNotFoundError, OSError, subprocess.SubprocessError):
+        return []
+    pids: list[int] = []
+    for tok in out.stdout.split():
+        try:
+            pid = int(tok)
+        except ValueError:
+            continue
+        if pid > 0 and pid not in pids:
+            pids.append(pid)
+    return pids
+
+
+def pid_is_browserwright_daemon(pid: int) -> bool:
+    """True iff ``pid``'s command line looks like a browserwright daemon.
+
+    The safety gate before any SIGTERM — we must never signal a stranger that
+    happens to hold the port. Matches both the installed console-script
+    (``browserwright-daemon serve``) and the dev module invocation
+    (``python -m browserwright.daemon.cli serve``)."""
+    if pid <= 0 or sys.platform == "win32":
+        return False
+    try:
+        out = subprocess.run(
+            ["ps", "-p", str(pid), "-o", "command="],
+            capture_output=True, text=True, timeout=3,
+        )
+    except (FileNotFoundError, OSError, subprocess.SubprocessError):
+        return False
+    cmd = out.stdout.strip()
+    if not cmd:
+        return False
+    return "browserwright-daemon" in cmd or "browserwright.daemon" in cmd
+
+
+def pid_alive(pid: int) -> bool:
+    """True if ``pid`` exists (signal 0 probe). POSIX only."""
+    if pid <= 0 or sys.platform == "win32":
+        return False
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True  # exists, owned by someone else
+    except OSError:
+        return False
+    return True
+
+
+def confirmed_stale_holder(ports: list[int]) -> int | None:
+    """Return the pid of a *confirmed browserwright* daemon holding any of
+    ``ports`` (excluding ourselves), or None.
+
+    Confirmation = lsof says it holds the port AND its command line is a
+    browserwright daemon. Callers must have already established that the control
+    socket is dead (ping negative) before treating this as "stale". lsof
+    unavailable → None (we won't guess a kill target)."""
+    me = os.getpid()
+    for port in ports:
+        for pid in port_holder_pids(port):
+            if pid != me and pid_is_browserwright_daemon(pid):
+                return pid
+    return None
+
+
+def reclaim_ports(pid: int, ports: list[int], *, timeout: float = 5.0) -> bool:
+    """SIGTERM ``pid`` and wait until every port in ``ports`` frees; escalate to
+    SIGKILL as a last resort. Returns True once the ports are free.
+
+    The caller MUST have confirmed ``pid`` via :func:`confirmed_stale_holder`
+    (or an equivalent lsof+cmdline check) — this function does not re-verify."""
+    def _all_free() -> bool:
+        return all(not port_is_listening("127.0.0.1", p) for p in ports)
+
+    try:
+        os.kill(pid, signal.SIGTERM)
+    except ProcessLookupError:
+        return _all_free()
+    except OSError:
+        return False
+    if _wait(_all_free, timeout):
+        return True
+    # Escalate — a wedged daemon may never handle SIGTERM.
+    try:
+        os.kill(pid, signal.SIGKILL)
+    except OSError:
+        pass
+    return _wait(_all_free, 2.0)
+
+
+def _wait(pred, timeout: float) -> bool:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if pred():
+            return True
+        time.sleep(0.15)
+    return pred()

{browserwright-0.7.0 → browserwright-0.7.2}/src/browserwright/daemon/cli.py

@@ -615,9 +615,12 @@ async def _run_stats(args, cfg: Config) -> int:
 
 def _cmd_status(args, cfg: Config) -> int:
     """Report endpoint + liveness. JSON shape used by Skill for status pings."""
-    from . import _ipc
+    from . import _ipc, _stale
     pid, version = _ipc.ping_status_sync(timeout=1.0)
     probe_state = "ok" if pid is not None else "not_running"
+    # issue #15 (2.1): pid of the process holding the relay/facade ports when
+    # the control socket is dead but its file lingers — a half-alive daemon.
+    port_holder_pid = None
     if pid is None and _ipc.sock_path().exists():
         deadline = time.monotonic() + 0.6
         while time.monotonic() < deadline:
@@ -628,6 +631,20 @@ def _cmd_status(args, cfg: Config) -> int:
                 break
         else:
             probe_state = "transient_probe_failed"
+            # Still unresponsive, but its socket file is present — a half-alive
+            # daemon may be holding the relay/facade ports. Report the truth
+            # instead of a bare "not_running" that loops the user through
+            # restarts that crash on EADDRINUSE.
+            ports = _stale.daemon_tcp_ports(cfg)
+            if any(_stale.port_is_listening("127.0.0.1", p) for p in ports):
+                probe_state = "port_held_by_unresponsive_process"
+                port_holder_pid = _stale.confirmed_stale_holder(ports)
+                if port_holder_pid is None:
+                    # lsof unavailable / non-daemon holder — surface the
+                    # pid-file pid as a best-effort hint (never a kill target).
+                    fp = _ipc.read_pid()
+                    if fp and _stale.pid_alive(fp):
+                        port_holder_pid = fp
     ep = _ipc.endpoint_describe()
     facade_ws, facade_port = _ipc.read_facade_file()
     status = {
@@ -635,6 +652,10 @@ def _cmd_status(args, cfg: Config) -> int:
         "alive": pid is not None,
         "probe_state": probe_state,
         "pid": pid,
+        # issue #15 (2.1): pid of the process holding the relay/facade ports
+        # when the daemon is unresponsive. Actionable: `browserwright-daemon
+        # restart` reclaims it, or kill it manually.
+        "port_holder_pid": port_holder_pid,
         "version": version,
         "endpoint": ep,
         # Playwright facade discovery (Phase C). None when the facade is
@@ -649,7 +670,14 @@ def _cmd_status(args, cfg: Config) -> int:
         print(json.dumps(status, sort_keys=True))
     else:
         if pid is None:
-            print("daemon not running")
+            if probe_state == "port_held_by_unresponsive_process":
+                held = f" (pid {port_holder_pid})" if port_holder_pid else ""
+                print("daemon unresponsive but holding its ports"
+                      f"{held} — a half-alive daemon.")
+                print("  fix: `browserwright-daemon restart` reclaims the "
+                      "ports; or kill the pid above manually.")
+            else:
+                print("daemon not running")
         else:
             print(f"daemon alive (pid {pid})")
             if ep["transport"] == "unix":

{browserwright-0.7.0 → browserwright-0.7.2}/src/browserwright/daemon/server/listener.py

@@ -75,6 +75,61 @@ def make_context(*, backend: str, cfg: Config,
 # ---- top-level entry -------------------------------------------------------
 
 
+def _reclaim_stale_daemon_ports(cfg: Config) -> None:
+    """Reclaim the relay/facade ports from a *confirmed* stale browserwright
+    daemon (issue #15, 2.2). No-op when the ports are free or held by an
+    unconfirmed process (we never SIGTERM a stranger)."""
+    from .. import _stale
+    ports = _stale.daemon_tcp_ports(cfg)
+    held = [p for p in ports if _stale.port_is_listening("127.0.0.1", p)]
+    if not held:
+        return
+    pid = _stale.confirmed_stale_holder(held)
+    if pid is None:
+        logger.warning(
+            "ports %s are in use but no confirmed browserwright daemon holds "
+            "them; leaving them alone (bind will surface a clear error)", held)
+        return
+    logger.warning(
+        "reclaiming ports %s from stale browserwright daemon pid %d (issue #15)",
+        held, pid)
+    if _stale.reclaim_ports(pid, held):
+        logger.info("reclaimed ports %s from pid %d", held, pid)
+    else:
+        logger.warning("could not free ports %s from pid %d; bind may fail",
+                       held, pid)
+
+
+async def _control_socket_watchdog(sock_ident: tuple, stop: asyncio.Event,
+                                   *, interval: float = 2.0) -> None:
+    """Self-exit when our control socket disappears or is replaced by a
+    different inode — i.e. another daemon took over, or the socket was removed
+    (issue #15, 2.4). Setting ``stop`` runs the normal graceful shutdown, which
+    releases the relay/facade ports instead of lingering as a port-holding
+    zombie. A single stat error is ignored (transient FS hiccup); only a
+    definitive gone/replaced verdict self-exits."""
+    while not stop.is_set():
+        try:
+            await asyncio.wait_for(stop.wait(), timeout=interval)
+            return  # stop was set elsewhere (signal / another watchdog)
+        except asyncio.TimeoutError:
+            pass
+        try:
+            st = os.stat(_ipc.sock_path())
+        except FileNotFoundError:
+            logger.warning("control socket removed; self-exiting to release "
+                           "ports (issue #15)")
+            stop.set()
+            return
+        except OSError:
+            continue  # transient — don't self-exit on one error
+        if (st.st_dev, st.st_ino) != sock_ident:
+            logger.warning("control socket replaced (another daemon took over); "
+                           "self-exiting to release ports (issue #15)")
+            stop.set()
+            return
+
+
 async def run_serve(cfg: Config) -> int:
     """Run a Mode B daemon until SIGTERM / Ctrl-C / shutdown. Returns exit code.
 
@@ -100,6 +155,12 @@ async def run_serve(cfg: Config) -> int:
         )
         return 1
     _ipc.cleanup_endpoint()
+    # issue #15 (2.2): the control-socket ping above was negative, but a
+    # half-alive prior daemon can still hold the relay/facade TCP ports and
+    # crash-loop us on EADDRINUSE. Reclaim them before binding — but only from a
+    # process lsof confirms holds the port AND whose cmdline is a browserwright
+    # daemon (never a stranger).
+    _reclaim_stale_daemon_ports(cfg)
 
     # Phase 3 (C2 ephemeral): rdp Chrome processes are daemon children and die
     # with us — but a hard crash / SIGKILL can leave orphan Chrome processes
@@ -159,6 +220,19 @@ async def run_serve(cfg: Config) -> int:
     handler = _ClientHandler(daemon, cfg)
     server = await _open_server(handler)
 
+    # issue #15 (2.4): watch our own control socket. If another `serve` (or a
+    # manual `rm`) removes/replaces it, self-exit so we release the relay/facade
+    # ports instead of lingering as a port-holding zombie. POSIX only — Windows
+    # uses a port file, not a unix socket inode.
+    sock_watch_task: asyncio.Task | None = None
+    if not _ipc.IS_WINDOWS:
+        try:
+            _st = os.stat(_ipc.sock_path())
+            sock_watch_task = asyncio.create_task(
+                _control_socket_watchdog((_st.st_dev, _st.st_ino), stop))
+        except OSError:
+            pass
+
     # v0.4: for the extension shared context, start the relay ws server eagerly
     # so `browserwright-daemon doctor` can probe `__status__` even before any
     # Skill client connects. The relay belongs to the shared context's holder
@@ -173,8 +247,21 @@ async def run_serve(cfg: Config) -> int:
             port = await shared_context.holder.relay.start()
             logger.info("extension relay started on port %d", port)
         except OSError as e:
+            # issue #15 (2.2): if we still can't bind after the reclaim pass, the
+            # port is held by something we couldn't confirm as our daemon (lsof
+            # missing, or a genuine stranger). Point the user at the exact port +
+            # how to find the holder rather than a bare errno.
+            hint = ""
+            with contextlib.suppress(Exception):
+                _, rport = cfg.backends.extension.resolved_host_port()
+                hint = (
+                    f" — port {rport} is held by another process. Run "
+                    f"`lsof -nP -iTCP:{rport} -sTCP:LISTEN` to find it, then "
+                    f"`browserwright-daemon restart` (reclaims a stale "
+                    f"browserwright daemon) or kill that pid."
+                )
             print(
-                f"browserwright-daemon failed to bind extension relay: {e}",
+                f"browserwright-daemon failed to bind extension relay: {e}{hint}",
                 file=sys.stderr,
             )
             server.close()
@@ -235,6 +322,10 @@ async def run_serve(cfg: Config) -> int:
         logger.info("browserwright-daemon shutdown requested")
         await _graceful_shutdown(daemon)
     finally:
+        if sock_watch_task is not None:
+            sock_watch_task.cancel()
+            with contextlib.suppress(Exception):
+                await sock_watch_task
         if idle_task is not None:
             idle_task.cancel()
             with contextlib.suppress(Exception):

{browserwright-0.7.0 → browserwright-0.7.2}/src/browserwright/skill_runtime.md

@@ -205,6 +205,14 @@ browserwright userscript toggle <id> --enabled=false
 browserwright userscript remove <id>
 ```
 
+## Reporting browserwright bugs
+
+If browserwright itself misbehaves — a primitive, CLI verb, the daemon, the extension backend, or the Playwright facade crashes, hangs, times out, or breaks a contract this guide documents — file a bug against the upstream repo (`broven/browserwright`) on the user's behalf, so the user does not have to. This is *only* for browserwright defects; a site that changed, blocks automation, or shows a captcha is a site note (`remember(host, ...)`), and hostile page content is a trust-boundary matter, not a bug.
+
+A report is only useful if a maintainer can reproduce it. Before filing: reproduce it twice, shrink it to the smallest runnable script against a page the maintainer can reach (prefer `https://example.com` or a `data:text/html,...` fixture, never an auth-gated/private page), capture `browserwright version check` + `browserwright-daemon status --json`, record expected vs. actual, and redact secrets and private content. A GitHub issue is public and filed under the user's identity: draft it, show the user, and submit with `gh issue create --repo broven/browserwright` only after they approve.
+
+Read the installed skill's `reporting-issues.md` for the exact scope gate, reproducibility checklist, issue template, and the `gh` filing + fallback commands before you file.
+
 ## Memory
 
 Read the installed skill's `memory.md` for backend preferences and scenario decisions. When the user expresses a stable browser preference, record it there or with the memory helpers so future tasks do not re-ask.

{browserwright-0.7.0 → browserwright-0.7.2}/src/browserwright.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: browserwright
-Version: 0.7.0
+Version: 0.7.2
 Summary: Browserwright — let AI/code agents drive a real or isolated browser and author userscripts. Single package: the agent-facing REPL/site-skills/memory layer plus the bundled browser-resolving daemon (CDP proxy + extension/cloud backends).
 Requires-Python: >=3.11
 Requires-Dist: cdp-use==1.4.5

{browserwright-0.7.0 → browserwright-0.7.2}/src/browserwright.egg-info/SOURCES.txt

@@ -36,6 +36,7 @@ src/browserwright/_executor/process.py
 src/browserwright/_executor/protocol.py
 src/browserwright/daemon/__init__.py
 src/browserwright/daemon/_ipc.py
+src/browserwright/daemon/_stale.py
 src/browserwright/daemon/active_tab.py
 src/browserwright/daemon/auth.py
 src/browserwright/daemon/cli.py