browserwright 0.17.0__tar.gz → 0.17.2__tar.gz

{browserwright-0.17.0/src/browserwright.egg-info → browserwright-0.17.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: browserwright
-Version: 0.17.0
+Version: 0.17.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).
 License-Expression: AGPL-3.0-only
 Requires-Python: >=3.11

{browserwright-0.17.0 → browserwright-0.17.2}/pyproject.toml

@@ -15,7 +15,7 @@ name = "browserwright"
 # stamping regex is `^(version\s*=\s*)["'][^"']+["']\s*$` and CI aborts unless
 # it matches exactly once. `tests/skill/test_release_versioning.py` enforces all
 # of that before a tag is ever pushed. See RELEASING.md.
-version = "0.17.0"
+version = "0.17.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"
 license = "AGPL-3.0-only"

{browserwright-0.17.0 → browserwright-0.17.2}/src/browserwright/daemon/config.py

@@ -35,6 +35,49 @@ DEFAULT_FACADE_PORT = 19990
 # interface (e.g. `0.0.0.0` or a specific tailnet IP) for remote CDP clients.
 DEFAULT_FACADE_HOST = "127.0.0.1"
 
+#: The loopback address every local client falls back to (`DEFAULT_DAEMON_URL`
+#: in `daemon_url.py` is built from it).
+LOOPBACK_HOST = "127.0.0.1"
+
+#: Hosts whose bind ALREADY covers loopback, so no second listener is needed:
+#: loopback itself, and the two wildcards.
+_LOOPBACK_COVERING_HOSTS = frozenset({
+    "", "0.0.0.0", "::", "::0", "*",
+})
+
+
+def needs_loopback_cobind(host: str) -> bool:
+    """Whether binding *host* leaves 127.0.0.1 unserved.
+
+    A bind to a **specific** address listens on that address only — binding
+    `100.72.20.32` (the documented `--facade-host <tailnet-ip>` remote-access
+    setup) means `127.0.0.1:19990` is genuinely not listening, so every local
+    client that resolves the loopback default gets ECONNREFUSED while the
+    daemon is demonstrably up. The endpoint state file is supposed to bridge
+    that, but it is a best-effort channel (an unreadable or differently-rooted
+    `XDG_RUNTIME_DIR` silently falls through to the default). Remote access
+    must not cost local access, so the facade co-binds loopback whenever this
+    returns True.
+
+    Wildcards (`0.0.0.0`, `::`) and loopback itself already serve 127.0.0.1.
+    """
+    text = (host or "").strip()
+    if text.lower() in _LOOPBACK_COVERING_HOSTS:
+        return False
+    if text.lower() in ("localhost", "localhost."):
+        return False
+    import ipaddress
+
+    try:
+        addr = ipaddress.ip_address(text.strip("[]"))
+    except ValueError:
+        # A hostname we cannot classify without resolving. Co-binding loopback
+        # is harmless (it fails soft) and is the safer default.
+        return True
+    if addr.is_loopback or addr.is_unspecified:
+        return False
+    return True
+
 
 def check_name(name: str) -> str:
     """Path-traversal guard for filesystem-bound names (e.g. `--profile`)."""

{browserwright-0.17.0 → browserwright-0.17.2}/src/browserwright/daemon/server/facade.py

@@ -64,7 +64,8 @@ import websockets
 from websockets.asyncio.server import ServerConnection, serve
 
 from .. import _ipc
-from ..config import DEFAULT_FACADE_PORT, Config
+from ..config import (DEFAULT_FACADE_PORT, LOOPBACK_HOST, Config,
+                      needs_loopback_cobind)
 from .. import __version__
 from ..errors import Unavailable
 from ..resolver import resolve as resolve_upstream
@@ -128,6 +129,14 @@ class PlaywrightFacade:
         self._port = port
         self._host = host
         self._server: Any = None
+        # A bind to a *specific* non-loopback IP (the documented remote-access
+        # setup, `--facade-host <tailnet-ip>`) does not listen on 127.0.0.1 at
+        # all, which silently breaks every LOCAL client — they resolve the
+        # loopback default when the endpoint state file is not visible to them
+        # (different XDG_RUNTIME_DIR, sandboxed /tmp, another user). Remote
+        # access must not cost local access, so we additionally bind loopback
+        # on the same port and serve both from one handler.
+        self._loopback_server: Any = None
         # PR2: for the extension backend the facade has no resolvable upstream
         # ws — it bridges through the daemon's shared RelayServer. The listener
         # passes a getter (the relay is created during run_serve startup, and
@@ -149,12 +158,12 @@ class PlaywrightFacade:
 
     # ---- lifecycle -------------------------------------------------------
 
-    async def start(self) -> int:
-        """Bind the facade ws+HTTP server. Returns the actually-bound port."""
-        self._server = await serve(
+    async def _serve_on(self, host: str, port: int) -> Any:
+        """Bind one ws+HTTP listener for this facade on ``host:port``."""
+        return await serve(
             self._handle_client,
-            self._host,
-            self._port,
+            host,
+            port,
             process_request=self._process_request,
             compression=None,
             ping_interval=20,
@@ -164,6 +173,16 @@ class PlaywrightFacade:
             # frames — see `_MAX_WS_SIZE`.
             max_size=_MAX_WS_SIZE,
         )
+
+    async def start(self) -> int:
+        """Bind the facade ws+HTTP server. Returns the actually-bound port.
+
+        When ``host`` names a specific non-loopback address, loopback is bound
+        as a SECOND listener on the same port so local clients keep working
+        (see ``_loopback_server``). That co-bind is best-effort: it must never
+        turn a working remote bind into a fatal startup failure.
+        """
+        self._server = await self._serve_on(self._host, self._port)
         for sock in self._server.sockets:
             sa = sock.getsockname()
             if isinstance(sa, tuple) and len(sa) >= 2:
@@ -171,6 +190,32 @@ class PlaywrightFacade:
                 break
         logger.info("endpoint listening on http://%s:%d (%s)",
                     self._host, self._port, ", ".join(_WS_PATHS))
+        if needs_loopback_cobind(self._host):
+            try:
+                self._loopback_server = await self._serve_on(
+                    LOOPBACK_HOST, self._port)
+                logger.info(
+                    "endpoint also listening on http://%s:%d "
+                    "(loopback co-bind so local clients keep working)",
+                    LOOPBACK_HOST, self._port)
+            except OSError as e:
+                # Someone else holds loopback:port, or the ephemeral port the
+                # primary bind won is taken on loopback. Remote clients still
+                # work; local ones need an explicit endpoint. Say so loudly —
+                # this is exactly the failure mode that reads as "the daemon
+                # is running but nothing can reach it".
+                self._loopback_server = None
+                logger.warning(
+                    "endpoint could NOT also bind %s:%d (%s) — LOCAL clients "
+                    "that resolve the loopback default will fail to connect. "
+                    "Point them at http://%s:%d via $BW_DAEMON_URL.",
+                    LOOPBACK_HOST, self._port, e, self._host, self._port)
+            logger.warning(
+                "endpoint is bound to non-loopback %s — it is reachable from "
+                "every host that can route there, and it drives a real "
+                "browser with no application-layer auth (ADR-0011). Keep it "
+                "on a trusted tunnel/tailnet only.",
+                self._host)
         if self._relay_getter is not None:
             self._reaper_task = asyncio.create_task(self._auto_reaper_loop())
         return self._port
@@ -192,10 +237,14 @@ class PlaywrightFacade:
             with contextlib.suppress(asyncio.CancelledError, Exception):
                 await task
         self._sessions.clear()
-        self._server.close()
-        with contextlib.suppress(Exception):
-            await self._server.wait_closed()
+        for srv in (self._server, self._loopback_server):
+            if srv is None:
+                continue
+            srv.close()
+            with contextlib.suppress(Exception):
+                await srv.wait_closed()
         self._server = None
+        self._loopback_server = None
 
     @property
     def port(self) -> int:

{browserwright-0.17.0 → browserwright-0.17.2}/src/browserwright/daemon/server/facade_extension.py

@@ -94,8 +94,19 @@ _RUNTIME_REENABLE_PAUSE = 0.05
 # Instead of skipping the announce permanently we re-check for a short window
 # (the binding lands milliseconds later); a tab that never becomes visible
 # (a foreign tab) expires without an announce — the scope check still gates.
-_VISIBILITY_RETRY_COUNT = 5
-_VISIBILITY_RETRY_INTERVAL = 0.1
+#
+# BUG B: this window used to be 5 x 0.1s = 0.5s, which was the real ceiling on
+# a cold bind. It has to outlast an extension MV3 service-worker wake-up (the
+# `scoped_target_infos` round trip goes to the SW), and it must not expire
+# before the CLIENT's bind budget — otherwise the daemon quietly stops trying
+# while the client is still waiting, and the tab is never announced for the
+# life of the bridge, which is exactly what surfaced as a 100%-reproducible
+# `PageBindTimeout` with a leaked tab per attempt. 30 x 0.2s = 6s sits under
+# the 10s client budget (`repl.playwright_handle._PAGE_BIND_TIMEOUT_S`) with
+# room for the round trip. Cost on the happy path is zero: the loop returns on
+# the first successful check, and a foreign tab is idle waiting, not work.
+_VISIBILITY_RETRY_COUNT = 30
+_VISIBILITY_RETRY_INTERVAL = 0.2
 
 
 # Synthetic browserContextId for synthesized page targets. The extension backend

{browserwright-0.17.0 → browserwright-0.17.2}/src/browserwright/daemon/server/listener.py

@@ -917,7 +917,9 @@ class _UpstreamHolder:
         # fallback for an adapter that reports nothing.
         await self.state.set_connected(ext.ws_url or "ext://relay")
 
-    async def _on_extension_hello(self) -> None:
+    async def _on_extension_hello(
+        self, *, install_id: str = "", first_seen: bool = False,
+    ) -> None:
         """A (auto-recovery): extension (re)connected with a fresh SW.
 
         A reloaded/updated SW reconnects with an EMPTY ``attachedTabs`` set,
@@ -957,9 +959,19 @@ class _UpstreamHolder:
                     continue
                 try:
                     await ext.recover_session(sid)
+                    # GH#79: say which of the two it was. This line used to
+                    # read "after extension reconnect" unconditionally — it
+                    # fires on EVERY hello, including the very first one from
+                    # a brand-new browser profile, and reading it in a
+                    # session-scoped e2e log is what made a fresh Chrome per
+                    # test look like a service worker churning between
+                    # commands.
                     logger.info(
-                        "auto-recovered session %s after extension reconnect",
-                        sid)
+                        "auto-recovered session %s after extension %s "
+                        "(install_id=%s)",
+                        sid,
+                        "first connect" if first_seen else "reconnect",
+                        install_id or "(unknown)")
                 except Exception:  # noqa: BLE001 - no group / empty group /
                     # still reconnecting -- the next hello retries.
                     pass

{browserwright-0.17.0 → browserwright-0.17.2}/src/browserwright/daemon/server/relay.py

@@ -236,6 +236,7 @@ class RelayServer:
         )
         self._server: Any = None
         self._extensions: dict[str, _ExtensionConn] = {}
+        self._seen_install_ids: set[str] = set()
         # Monotonic connection epoch. A fresh extension hello may represent a
         # Chrome restart, where numeric tab/group ids can be recycled. Session
         # adapters use this to demote in-memory group bindings back to
@@ -260,7 +261,16 @@ class RelayServer:
         # (fresh SW after a reload/update, or a ws reconnect). The listener
         # uses it to re-attach extension sessions whose ghost table was lost
         # with the previous connection. Set by the listener.
-        self._on_extension_hello: Callable[[], Awaitable[None]] | None = None
+        self._on_extension_hello: (
+            Callable[..., Awaitable[None]] | None) = None
+        # GH#79: install_ids that have said hello to THIS daemon before, so a
+        # reconnect can be told apart from a first connect. background.js
+        # persists the id in `chrome.storage.local`, so it survives service
+        # worker restarts and extension reloads; a genuinely new id means a new
+        # profile or a reinstall, not a churning SW. Reading a session-scoped
+        # daemon.log without that distinction is what made the e2e harness's
+        # one-fresh-Chrome-per-test look like an extension reconnecting with a
+        # new id between commands (issue #79).
 
     # ---- lifecycle -------------------------------------------------------
 
@@ -1265,11 +1275,37 @@ class RelayServer:
             )
             comparison = compare_versions(ext.browserwright_version or ext.version, __version__)
             ext.version_drift = comparison.drift.value
+            # GH#79: one live connection per install_id. A single MV3 service
+            # worker could dial the relay twice (a superseded socket's late
+            # `onclose` cleared the extension's module-level `ws`, so its
+            # `maintainLoop` opened a duplicate a tick later) and both sockets
+            # said `hello` with the same install_id. `_extensions` is keyed by
+            # install_id, so the re-key below silently evicts the older entry
+            # while its TCP connection stays ESTABLISHED — a ghost we keep
+            # app-pinging and can never route to. Close it explicitly instead.
+            # The extension-side fix is in `chrome-extension/background.js`,
+            # but it only reaches users when a new build ships to the Web
+            # Store, so the invariant is enforced here too.
+            superseded = [
+                other for other in self._extensions.values()
+                if other is not ext
+                and ext.install_id
+                and other.install_id == ext.install_id
+            ]
             # Re-key the extension by install_id (so multiple extensions don't
             # collide on temp_key collisions).
             self._extensions.pop(temp_key, None)
             self._extensions[ext.install_id or temp_key] = ext
             ext.hello_received.set()
+            for other in superseded:
+                logger.info(
+                    "superseding older relay connection for install_id=%s "
+                    "(the extension dialled twice)",
+                    ext.install_id,
+                )
+                asyncio.create_task(self._force_close_extension(
+                    other, reason="superseded by a newer connection from the "
+                                  "same install_id"))
             if ext.app_ping_task is None or ext.app_ping_task.done():
                 ext.app_ping_task = asyncio.create_task(self._app_ping_loop(ext))
             self._first_ready.set()
@@ -1298,8 +1334,14 @@ class RelayServer:
                     ext.browserwright_version or ext.version,
                     __version__,
                 )
+            first_seen = bool(
+                ext.install_id) and ext.install_id not in self._seen_install_ids
+            if ext.install_id:
+                self._seen_install_ids.add(ext.install_id)
             logger.info(
-                "extension hello: install_id=%s browser=%s version=%s protocol=%s",
+                "extension hello (%s): install_id=%s browser=%s version=%s "
+                "protocol=%s",
+                "first connect" if first_seen else "reconnect",
                 ext.install_id,
                 ext.browser,
                 ext.version,
@@ -1321,7 +1363,8 @@ class RelayServer:
             await self._maybe_reload_for_version_drift(ext)
             if self._on_extension_hello is not None:
                 try:
-                    await self._on_extension_hello()
+                    await self._on_extension_hello(
+                        install_id=ext.install_id, first_seen=first_seen)
                 except Exception as e:  # noqa: BLE001 - never break hello
                     logger.warning(
                         "extension hello callback failed: %r", e)

{browserwright-0.17.0 → browserwright-0.17.2}/src/browserwright/daemon_url.py

@@ -244,6 +244,54 @@ _SOURCE_LABEL = {
 }
 
 
+def local_unreachable_fix(ep: DaemonEndpoint) -> str:
+    """The `fix` for "nothing answered" on a NON-explicitly-configured endpoint.
+
+    The class default — "start the single global daemon: `browserwright-daemon
+    serve`" — is a dead end whenever the daemon is already running, which is
+    the common case here: the daemon bound a *specific* non-loopback host
+    (`--facade-host <tailnet-ip>`) and this client resolved something else. So
+    name the real divergence instead of guessing.
+    """
+    published = _from_state_file()
+    normalized = _normalize(published) if published else None
+
+    if ep.source == "default" and normalized and normalized != ep.url:
+        return (
+            f"a daemon published {normalized} in its endpoint state file, but "
+            f"this client resolved the built-in default {ep.url} — they "
+            f"disagree. Point the client at it (`export {ENV_VAR}="
+            f"{normalized}`), or rebind the daemon so loopback is served too "
+            "(`browserwright-daemon install --facade-host 0.0.0.0` then "
+            "`browserwright-daemon restart`)."
+        )
+    if ep.source == "state_file":
+        host_note = ""
+        if not ep.is_loopback:
+            host_note = (
+                f" That endpoint is bound to the non-loopback host "
+                f"{ep.host}, so it is only reachable over that interface — if "
+                "it is down (VPN/tailnet off), nothing local can reach the "
+                "daemon."
+            )
+        return (
+            f"the running daemon published {ep.url} but nothing answered "
+            f"there.{host_note} Check it with `browserwright-daemon status` "
+            "and `lsof -nP -iTCP:"
+            f"{ep.port} -sTCP:LISTEN`, then `browserwright-daemon restart`. "
+            "If the daemon is up, the state file is stale."
+        )
+    return (
+        f"nothing is listening on the default endpoint {ep.url}. Check "
+        f"`browserwright-daemon status`; if a daemon IS running it is bound "
+        "elsewhere (see `--facade-host`) — point this client at it with "
+        f"${ENV_VAR}. Otherwise start one: `browserwright-daemon serve`. "
+        f"Note `lsof -nP -iTCP:{ep.port} -sTCP:LISTEN` shows a foreign holder "
+        "of the port (a proxy such as Surge can answer HTTP on it without a "
+        "daemon behind it)."
+    )
+
+
 def not_ours_to_signal_message(ep: DaemonEndpoint, action: str) -> str:
     """Why a local signal-based ``action`` is refused for a remote endpoint."""
     return (

{browserwright-0.17.0 → browserwright-0.17.2}/src/browserwright/errors.py

@@ -43,9 +43,19 @@ class PageBindTimeout(BrowserwrightError):
 
     exit_code = 3
     retryable = True
+    # BUG B: `retryable` has to be honest. A retry only helps when the daemon
+    # was still going to announce the tab — a cold/reconnecting extension
+    # service worker is exactly that case, and the bind budget
+    # (`$BW_PAGE_BIND_TIMEOUT`) is the knob for it. If retries do NOT help, the
+    # extension side is not answering at all, and `session reset` will not
+    # change that — say what to check instead of looping the user.
     default_fix = (
-        "retry the same browserwright command; if it persists, run "
-        "`browserwright session reset <id>` and retry"
+        "retry the same browserwright command (a cold extension service worker "
+        "can miss the bind window; raise it with `export "
+        "BW_PAGE_BIND_TIMEOUT=30`). If EVERY retry fails, the extension is not "
+        "answering: check `browserwright doctor` and that the browserwright "
+        "extension is enabled and its Chrome window is open, then "
+        "`browserwright session reset <id>`"
     )
 
     def __init__(

{browserwright-0.17.0 → browserwright-0.17.2}/src/browserwright/health.py

@@ -183,6 +183,17 @@ def doctor_checks() -> dict:
                 "field)",
                 "update browserwright-daemon to match browserwright")
 
+    # 3b. endpoint_reachable — can a LOCAL client actually dial the endpoint?
+    #     BUG A: check 3 above only *reports* the advertised address, so a
+    #     daemon bound to a specific non-loopback host (`--facade-host
+    #     <tailnet-ip>`) read as a clean bill of health while every local
+    #     client failed with ECONNREFUSED on 127.0.0.1. Doctor has to dial, not
+    #     echo — a health check that cannot observe the reported failure is the
+    #     gap, not a passing check.
+    if not synthetic and info.get("alive") is not False:
+        for check in _endpoint_reachability_checks():
+            add(**check)
+
     # 4. schema version sanity (catches a daemon too old to speak the blob)
     sv = info.get("schema_version")
     if not synthetic:
@@ -299,3 +310,73 @@ def doctor_checks() -> dict:
         "checks": checks,
         "raw": info,
     }
+
+
+def _probe_tcp(host: str, port: int, *, timeout: float = 1.5) -> str | None:
+    """``None`` when a TCP connect succeeds, else a short reason."""
+    import socket
+
+    try:
+        with socket.create_connection((host, port), timeout=timeout):
+            return None
+    except OSError as e:
+        return e.strerror or str(e)
+
+
+def _endpoint_reachability_checks() -> list[dict]:
+    """Dial the resolved endpoint AND loopback; report the divergence.
+
+    Two distinct failures hide behind "the daemon is running":
+      - the endpoint the client resolves answers nothing at all;
+      - it answers, but loopback (what every client falls back to when the
+        endpoint state file is not visible) does not.
+    The second is BUG A, and it is invisible unless you actually connect.
+    """
+    from .daemon_url import daemon_endpoint
+
+    try:
+        ep = daemon_endpoint()
+    except Exception:  # noqa: BLE001 - doctor must never raise
+        return []
+
+    resolved_err = _probe_tcp(ep.host, ep.port)
+    if resolved_err is not None:
+        return [{
+            "name": "endpoint_reachable",
+            "status": "fail",
+            "message": (f"nothing answered at {ep.host}:{ep.port} "
+                        f"(the endpoint resolved from {ep.source})"),
+            "fix": ("check `browserwright-daemon status` and `lsof -nP -iTCP:"
+                    f"{ep.port} -sTCP:LISTEN`, then `browserwright-daemon "
+                    "restart`"),
+        }]
+
+    if ep.is_loopback:
+        return [{
+            "name": "endpoint_reachable",
+            "status": "pass",
+            "message": f"endpoint answers at {ep.host}:{ep.port}",
+            "fix": "",
+        }]
+
+    loopback_err = _probe_tcp("127.0.0.1", ep.port)
+    if loopback_err is None:
+        return [{
+            "name": "endpoint_reachable",
+            "status": "pass",
+            "message": (f"endpoint answers at {ep.host}:{ep.port} and on "
+                        "127.0.0.1"),
+            "fix": "",
+        }]
+    return [{
+        "name": "endpoint_reachable",
+        "status": "fail",
+        "message": (f"the daemon answers at {ep.host}:{ep.port} but NOT on "
+                    f"127.0.0.1:{ep.port} ({loopback_err}) — any local client "
+                    "that cannot read the endpoint state file will fail to "
+                    "connect"),
+        "fix": ("rebind so loopback is served too: `browserwright-daemon "
+                "install --facade-host 0.0.0.0` then `browserwright-daemon "
+                "restart`; or point clients at it with "
+                f"`export BW_DAEMON_URL=http://{ep.host}:{ep.port}`"),
+    }]

{browserwright-0.17.0 → browserwright-0.17.2}/src/browserwright/repl/playwright_handle.py

@@ -32,13 +32,45 @@ there is no loop conflict with Playwright's sync driver.
 """
 from __future__ import annotations
 
+import logging
 from typing import Any
 from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
 from uuid import uuid4
 
 from ..errors import BrowserwrightError, PageBindTimeout
 
-_PAGE_BIND_TIMEOUT_S = 2.0
+logger = logging.getLogger(__name__)
+
+
+def _page_bind_timeout_s() -> float:
+    """How long to wait for Playwright to expose the agent-resolved tab.
+
+    BUG B: this was a hardcoded 2.0s, which is shorter than an extension MV3
+    service worker takes to wake up. When the SW is cold — or has just
+    reconnected to the relay, which happens routinely between commands — the
+    daemon's announce lands well after the budget, the bind fails, and the
+    caller is told to retry a command whose only real problem was being asked
+    too early. A wait measured in seconds costs nothing on the happy path (the
+    announce normally lands in milliseconds and the loop returns immediately),
+    while the old budget turned a slow wake-up into a hard failure.
+
+    Override with ``BW_PAGE_BIND_TIMEOUT`` (seconds) for a very slow machine.
+    """
+    import os
+
+    raw = (os.environ.get("BW_PAGE_BIND_TIMEOUT") or "").strip()
+    if raw:
+        try:
+            value = float(raw)
+        except ValueError:
+            value = 0.0
+        if value > 0:
+            return value
+    return _PAGE_BIND_TIMEOUT_S
+
+
+#: The bind budget when nothing overrides it. Tests monkeypatch this name.
+_PAGE_BIND_TIMEOUT_S = 10.0
 _PAGE_BIND_POLL_INTERVAL_S = 0.05
 
 
@@ -250,14 +282,18 @@ def bind_current_page(context: Any, sess: Any) -> Any:
     # Resolve/create + persist the session's current tab via the agent path.
     info = resolve_current_target(sess)
     target_id = info.get("targetId") if isinstance(info, dict) else None
+    # Did THIS call open the tab? Only step 4 of `resolve_current_target` sets
+    # it, so a reused tab is never mistaken for one we may discard.
+    we_opened_it = bool(info.get("opened")) if isinstance(info, dict) else False
 
+    budget = _page_bind_timeout_s()
     if target_id:
         page = _wait_for_target_page(
             context,
             sess,
             target_id,
             info.get("url"),
-            timeout=_PAGE_BIND_TIMEOUT_S,
+            timeout=budget,
         )
         if page is not None:
             return patch_page_goto(page)
@@ -267,12 +303,50 @@ def bind_current_page(context: Any, sess: Any) -> Any:
     # second target merely because the facade has not exposed the first one to
     # Playwright yet: that splits the ledger and Playwright views and is the
     # source of duplicate user-visible tabs.
+    #
+    # BUG B: a tab THIS call opened and then failed to bind has no owner —
+    # `PageBindTimeout` is advertised as retryable, so the caller retries,
+    # `resolve_current_target` finds no usable tab again and opens another.
+    # Whether the previous one survives depends on `session end` later finding
+    # it in the session's tab group, which is precisely what is unreliable when
+    # the announce failed. No user-visible leak has been observed; this closes
+    # the window rather than fixing a confirmed one. Roll our own creation back
+    # before raising.
+    if we_opened_it and target_id:
+        _discard_unbindable_tab(sess, target_id)
     raise PageBindTimeout(
         target_id=target_id or "",
-        timeout=_PAGE_BIND_TIMEOUT_S,
+        timeout=budget,
     )
 
 
+def _discard_unbindable_tab(sess: Any, target_id: str) -> None:
+    """Close a tab we opened but could not bind, and clear its ledger binding.
+
+    Strictly best-effort: the bind already failed, and a failure to clean up
+    must not replace ``PageBindTimeout`` (which names the real problem) with a
+    teardown error. Worst case we are back to the old leak.
+
+    Clearing the durable binding matters as much as closing the tab: leaving
+    the ledger pointed at a tab that is gone makes the NEXT call take the
+    recovery path against a dead target instead of opening a clean one.
+    """
+    from ..session_runtime import close_session_tab, persist_target
+
+    try:
+        close_session_tab(sess, target_id=target_id)
+    except Exception:  # noqa: BLE001 - see docstring: never mask the bind error
+        logger.warning("could not close unbindable tab %s", target_id,
+                       exc_info=True)
+    try:
+        if getattr(sess, "current_target_id", None) == target_id:
+            sess.current_target_id = None
+        persist_target(None, sess=sess)
+    except Exception:  # noqa: BLE001 - best-effort
+        logger.warning("could not clear binding for unbindable tab %s",
+                       target_id, exc_info=True)
+
+
 def _wait_for_target_page(
     context: Any,
     sess: Any,

{browserwright-0.17.0 → browserwright-0.17.2}/src/browserwright/session.py

@@ -98,13 +98,18 @@ class Session:
             return self._cdp
 
     def _unreachable(self, url: str, cause: BaseException) -> DaemonUnavailable:
-        from .daemon_url import daemon_endpoint, unreachable_message
+        from .daemon_url import (daemon_endpoint, local_unreachable_fix,
+                                 unreachable_message)
 
         endpoint = daemon_endpoint()
         if endpoint.explicit:
             return DaemonUnavailable(f"{unreachable_message(endpoint)} ({cause})")
+        # BUG A: the class default fix ("start the daemon") is actively
+        # misleading here — the daemon is usually running, just bound to a host
+        # this client did not resolve. Diagnose the divergence instead.
         return DaemonUnavailable(
-            f"no browserwright daemon answered at {url}: {cause}")
+            f"no browserwright daemon answered at {url}: {cause}",
+            fix=local_unreachable_fix(endpoint))
 
     def _resolve_ws_url(self) -> str:
         """Ask the underlying daemon client for a CDP ws URL.

{browserwright-0.17.0 → browserwright-0.17.2}/src/browserwright/session_create.py

@@ -476,6 +476,14 @@ def end(record: dict) -> str:
             f"kept for retry.{hint}")
     if record.get("owner") == "create":
         msg = f"session {sid} ended; the browser it launched was closed."
+    elif record.get("backend") == "extension":
+        # BUG B: the `attach` wording below is a cdp story — it claims nothing
+        # in the browser was touched, while the daemon has just closed every
+        # tab in this session's tab group. Reporting "left untouched" for a
+        # teardown that closes tabs is how a leaked tab and a torn-down one
+        # became indistinguishable to the user.
+        msg = (f"session {sid} ended; its tab group was closed. Your Chrome "
+               f"is still running — only this session's tabs were touched.")
     else:
         msg = (f"session {sid} ended. The browser is still running — you "
                f"attached to it, so it was left untouched.")

{browserwright-0.17.0 → browserwright-0.17.2}/src/browserwright/session_runtime.py

@@ -388,9 +388,17 @@ def resolve_current_target(sess) -> dict:
         return {"targetId": tabs[0]["targetId"], "url": tabs[0]["url"],
                 "title": tabs[0]["title"], "accuracy": "unknown"}
     # 4. Empty session — open a fresh working tab (NOT adopt).
+    #
+    # `opened: True` marks the tab as CREATED BY THIS CALL, which is the only
+    # thing that distinguishes it from the reuse paths above. Callers that can
+    # fail after this point (`repl.playwright_handle.bind_current_page`) need
+    # it to know whether a failure of theirs leaves a user-visible tab behind
+    # that nobody else will ever claim — steps 1-3 hand back a tab the session
+    # already owned, and closing one of those on a failed bind would destroy
+    # the agent's actual working tab.
     opened = open_session_tab(sess, "about:blank",
                               skip_post_attach_commands=True)
-    return opened | {"accuracy": "unknown"}
+    return opened | {"accuracy": "unknown", "opened": True}
 
 
 def eval_js(sess, expression: str, *, await_promise: bool = False) -> Any:

{browserwright-0.17.0 → browserwright-0.17.2}/src/browserwright/skill_runtime.md

@@ -373,9 +373,42 @@ Reusable flows belong in site-skill tasks. A task's `run(args, ctx)` receives th
 
 ```bash
 browserwright list-tasks
+browserwright list-tasks --query="search the web"
 browserwright -s "$sid" task wikipedia.org/lookup --title="Browser automation"
 ```
 
+**Look before you improvise.** Run `list-tasks` before hand-writing a flow for a site. A saved task replays a known-good path instead of re-deriving it from a fresh snapshot.
+
+**Solidify when the flow repeats.** Write a task once either of these is true, without waiting to be asked:
+
+- You have driven the same site flow twice, or the user asks for something they will plainly ask for again — a recurring report, a standing search, a routine form.
+- You just spent several snapshot/click rounds working out a path that a URL template plus two selectors can now replay directly.
+
+Author it with the `Write` tool; the runtime is filesystem-driven and there is no scaffolding command. Put the file at `$BS_HOME/site-skills/<eTLD+1>/tasks/<name>.py` (default `~/.browserwright/site-skills/...`), or at `./site-skills/...` in the CWD when the user wants it version-controlled with the project. Reads consult project-local `./site-skills/` first, then `$BS_HOME/site-skills/`, then the bundled starter set — first hit per site name wins, so a project task shadows a personal one. `remember()` and `bootstrap_site()` write to `./site-skills/` when that directory already exists and to `$BS_HOME` otherwise.
+
+```python
+"""One-line description — this becomes the task's listed summary."""
+
+ARGS = {
+    "query": {"type": "str", "required": True, "desc": "Search term"},
+    "lang":  {"type": "str", "required": False, "default": "en", "desc": "Language code"},
+}
+OUTPUT = "{title: str, url: str}"
+TAGS = ["search"]
+REQUIRES_LOGIN = False
+ESTIMATED_DURATION_SEC = 5
+LAST_VERIFIED = "2026-05-25"   # ISO date you last saw this actually work
+
+def run(args, ctx=None):
+    # `page` / `context` / `snapshot` are injected — same surface as inline code.
+    page.goto(f"https://example.com/search?q={args['query']}", wait_until="load")
+    return {"title": page.title(), "url": page.url}
+```
+
+Only `ARGS` and `run` are required; the rest is metadata `list-tasks` ranks and displays. The runtime imports the file, injects `page` / `context` / `snapshot` lazily (a task that never touches them opens no browser), validates the call against `ARGS`, then calls `run(args, ctx)`. Define `OUTPUT_SCHEMA` and the return shape is validated too. `ctx.memory` is the parsed frontmatter of that site's `memory.md`, so a task can read the selectors you recorded with `remember()`.
+
+Keep the two halves in sync. The note you write with `remember()` is what makes a task cheap to repair when the site changes, and `LAST_VERIFIED` is what tells the next agent whether to trust it. Set `BROKEN_SINCE = "<ISO date>"` instead of deleting a task you found broken and could not fix.
+
 ## Non-browser Helpers
 
 These run without driving the browser:

{browserwright-0.17.0 → browserwright-0.17.2/src/browserwright.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: browserwright
-Version: 0.17.0
+Version: 0.17.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).
 License-Expression: AGPL-3.0-only
 Requires-Python: >=3.11