browserwright 0.17.2__tar.gz → 0.17.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: browserwright
-Version: 0.17.2
+Version: 0.17.4
 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.2 → browserwright-0.17.4}/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.2"
+version = "0.17.4"
 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"
@@ -94,6 +94,7 @@ asyncio_mode = "auto"
 testpaths = ["tests"]
 markers = [
     "real_chrome: end-to-end test that launches a real Chrome + extension (skipped unless explicitly selected)",
+    "slow: long-running diagnostic/experiment; not part of the fast gate",
     "launchd: loads throwaway LaunchAgents to measure real launchd behaviour; macOS-only, skipped unless explicitly selected (issue #57)",
 ]
 

{browserwright-0.17.2 → browserwright-0.17.4}/src/browserwright/_executor/process.py

@@ -41,7 +41,7 @@ from contextlib import contextmanager, redirect_stdout
 from typing import Any
 
 from .._text import spill_text, truncate_hard
-from ..errors import BrowserwrightError, serialize
+from ..errors import BrowserwrightError, TabRebindFailed, serialize
 from .protocol import (
     MAX_TEXT_CHARS,
     TERMINAL_DEADLINE_EXCEEDED,
@@ -78,6 +78,16 @@ def _is_target_closed_family(exc: BaseException) -> bool:
     re-attaches the session (B, target-closed self-heal)."""
     if type(exc).__name__ == "TargetClosedError":
         return True
+    # Issue #86: `page.goto` is wrapped by `repl._smart_goto`, which TRANSLATES
+    # the underlying TargetClosedError into `PageLoadFailed(reason=
+    # "target-closed")` — a BrowserwrightError. `_execute` catches
+    # BrowserwrightError in an EARLIER branch than the raw-exception one this
+    # predicate used to guard, so the whole self-heal was unreachable for the
+    # single most common way a session meets a dead tab: navigating. Read the
+    # classifier's own bucket rather than hoping its rendered message still
+    # carries the original marker text (it is bounded to 300 chars).
+    if getattr(exc, "reason", None) == "target-closed":
+        return True
     msg = str(exc).lower()
     return any(marker in msg for marker in _TARGET_CLOSED_MARKERS)
 
@@ -244,6 +254,16 @@ class _Worker:
         self._page_target_id: str | None = None
         # Re-entrancy guard for target-changed rebinds (issue #21).
         self._rebinding_page = False
+        # Issue #86: how many dead-tab rebinds this call has already spent.
+        # The bound is ONE. A second dead tab inside a single call is not a
+        # tab that needs rebinding, it is a browser that cannot hold one, and
+        # answering it with another rebind is how a bug turns into a loop.
+        self._rebinds_this_call = 0
+        # Issue #86: set when a call failed with a target-closed-family error,
+        # so the next call re-enters the bind discipline even if Playwright has
+        # not yet processed the target's destruction (its `pages` cache is fed
+        # by channel events that only drain while a sync call is in flight).
+        self._page_maybe_dead = False
         # The globals dict of the CURRENTLY executing heredoc, so a mid-call
         # rebind can swap its ``page`` name (issue #21 same-call visibility).
         self._active_globals: dict[str, Any] | None = None
@@ -506,7 +526,7 @@ class _Worker:
         finally:
             self._rebinding_page = False
 
-    def _rebind_page(self, sess=None) -> None:
+    def _rebind_page(self, sess=None, *, strict: bool = False) -> None:
         """Rebind ``self._page`` (and the running heredoc's ``page`` name) to
         the session's current target, re-resolving through the same
         reuse/recover/adopt/open discipline the cold-start bind uses.
@@ -514,19 +534,29 @@ class _Worker:
         ``sess`` is the session whose binding changed (the hook passes the
         one ``bind_target`` / ``open_session_tab`` / ``close_session_tab``
         received); falls back to ``current_session()`` for the pre-execute
-        reconcile path."""
+        reconcile path.
+
+        ``strict=True`` is the issue #86 dead-tab path: RAISE
+        ``TabRebindFailed`` instead of warning and keeping the old page. The
+        lenient behaviour is right when the old page is still usable (a
+        ``switch_tab`` whose destination could not be resolved); it is exactly
+        wrong when the old page IS the corpse being replaced, because "keep the
+        old page and warn" is how this failure became permanent."""
         from ..repl import playwright_handle as ph
         from ..repl.snapshot import make_snapshot
 
         if sess is None:
             from ..session import current_session
             sess = current_session()
-        try:
-            page = ph.bind_current_page(self._context, sess)
-        except Exception as e:  # noqa: BLE001 - keep the old page + warn
-            self._call_warnings.append(
-                f"page rebind to the session's current tab failed: {e}")
-            return
+        if strict:
+            page = ph.rebind_dead_page(self._context, sess)
+        else:
+            try:
+                page = ph.bind_current_page(self._context, sess)
+            except Exception as e:  # noqa: BLE001 - keep the old page + warn
+                self._call_warnings.append(
+                    f"page rebind to the session's current tab failed: {e}")
+                return
         self._page = page
         self._page_target_id = sess.current_target_id
         self._live_page_holder.page = page
@@ -542,15 +572,82 @@ class _Worker:
         if self._active_globals is not None:
             self._active_globals["page"] = page
 
+    # ---- issue #86: a session whose tab died must rebind, not fail forever --
+
+    def _live_page_is_dead(self) -> bool:
+        """Is the held ``page`` a handle to a tab that no longer exists?
+
+        Drains queued channel events first: the executor sits in ``queue.get``
+        between calls, so a tab that died while it was idle has not been
+        reported to ``page.is_closed()`` yet. Without the drain the probe is
+        blind to exactly the case issue #86 is about.
+        """
+        from ..repl.playwright_handle import drain_page_events, page_is_dead
+
+        if self._context is not None:
+            drain_page_events(self._context)
+        return page_is_dead(self._page)
+
+    def _rebind_dead_page(self) -> bool:
+        """Issue #86: re-enter the bind discipline for a dead tab. ONE attempt.
+
+        The executor holds ``self._page`` for its whole life, so a tab that
+        dies under it used to make EVERY later call in that session fail in
+        1-4ms with ``TargetClosedError`` — for good. Nothing was wrong with the
+        session, the browser, or the URL; the binding was simply never
+        revisited.
+
+        Recovery goes through ``bind_current_page`` →
+        ``resolve_current_target``, never ``context.new_page()``: only the
+        agent path opens the replacement tab INSIDE this session's tab group,
+        which is what keeps the ledger and the Playwright view on one tab (see
+        ``bind_current_page``'s docstring — an un-grouped tab is ledger drift
+        and tab explosion).
+
+        Returns True when a live page is bound, False when this call has
+        already spent its one attempt (or a rebind is already in flight).
+        Raises ``TabRebindFailed`` (a DIFFERENT error from the dead-tab
+        condition, on purpose) when the rebind itself fails — the caller turns
+        either outcome into a terminal response, so a browser that genuinely
+        cannot hold a tab open never turns into a rebind loop.
+        """
+        from ..session import current_session
+
+        # Armed BEFORE the attempt and cleared only on success, so a rebind
+        # that could not even run (re-entrancy, budget spent) still leaves the
+        # next call knowing the binding is suspect.
+        self._page_maybe_dead = True
+        if self._rebinding_page or self._rebinds_this_call >= 1:
+            return False
+        self._rebinds_this_call += 1
+        self._rebinding_page = True
+        try:
+            self._rebind_page(current_session(), strict=True)
+        finally:
+            self._rebinding_page = False
+        self._page_maybe_dead = False
+        return True
+
     def _reconcile_page_binding(self) -> None:
         """Before each execute, rebind the live page if the session's DURABLE
         current target (ledger) moved — e.g. an in-process CLI heredoc called
         ``bind_target`` / ``close_session_tab`` without touching the page
-        surface, or a previous call left the ledger ahead of this executor."""
+        surface, or a previous call left the ledger ahead of this executor.
+
+        Issue #86 rides on the same pre-call hook: a page whose tab is GONE is
+        rebound here too. The ledger comparison below cannot see that case —
+        when a tab dies without anyone telling browserwright, the ledger still
+        names the dead target, so it matches ``_page_target_id`` and the
+        reconcile returned early. Checking liveness is what makes the dead
+        binding recoverable instead of permanent, and it is cheap: both probes
+        in ``page_is_dead`` are local, with no CDP round-trip."""
         if not self._connected or self._context is None or self._page is None:
             return
         if self._rebinding_page:
             return
+        if self._page_maybe_dead or self._live_page_is_dead():
+            self._rebind_dead_page()
+            return
         try:
             from .. import session_registry as reg
             rec = reg.get(self._session_id)
@@ -629,6 +726,7 @@ class _Worker:
         the facade is up); `_connected` stays False so the next execute retries."""
         self._call_warnings = []
         self._call_screenshots = []
+        self._rebinds_this_call = 0
         try:
             self._ensure_cold_started()
         except BrowserwrightError as e:
@@ -651,8 +749,19 @@ class _Worker:
         # running heredoc's `page` name too, not just the next call's.
         # Also reconcile the live page against the session's DURABLE current
         # target before running this call (a separate process may have moved
-        # the ledger binding without this executor noticing).
-        self._reconcile_page_binding()
+        # the ledger binding without this executor noticing) — and, issue #86,
+        # rebind if the tab the live page points at is gone.
+        try:
+            self._reconcile_page_binding()
+        except TabRebindFailed as e:
+            # The tab is gone AND opening a replacement failed. This is the
+            # bound on issue #86's recovery: escalate to the pre-existing
+            # cold-restart (terminal recycle) instead of attempting another
+            # rebind, and answer with the DISTINCT error so the caller can tell
+            # "the tab died" from "the browser cannot give me a tab at all".
+            return self._finish(
+                io.StringIO(), error=serialize(e), exit_code=e.exit_code,
+                terminal_reason=TERMINAL_TARGET_CLOSED)
         self._active_globals = globals_ = self._build_globals()
         buf = io.StringIO()
         return_value: str | None = None
@@ -689,6 +798,16 @@ class _Worker:
                         terminal_reason=TERMINAL_RESET_REQUESTED,
                     )
                 except BrowserwrightError as e:
+                    # Issue #86: `page.goto` failures arrive here, not in the
+                    # raw-exception branch below — `repl._smart_goto` has
+                    # already translated the underlying TargetClosedError into
+                    # `PageLoadFailed(reason="target-closed")`. That is why the
+                    # target-closed recovery under this branch's sibling was
+                    # unreachable for the most common way a session meets a
+                    # dead tab, and why a dead tab stayed dead forever.
+                    if _is_target_closed_family(e):
+                        return self._target_closed_response(
+                            buf, serialize(e), e.exit_code)
                     return self._finish(
                         buf, error=serialize(e), exit_code=e.exit_code)
                 except SystemExit as e:
@@ -708,35 +827,9 @@ class _Worker:
                     fix = playwright_error_fix(e)
                     if fix:
                         error["fix"] = fix
-                    terminal_reason = None
                     if _is_target_closed_family(e):
-                        # B (target-closed self-heal): the session's tab
-                        # binding died under us (extension SW reload/update,
-                        # daemon restart, user closed the tab). The page is a
-                        # zombie and the facade connection still holds the
-                        # daemon's single-attacher slot, which deadlocks every
-                        # recovery path until this executor is reaped. So flush
-                        # this (hint-carrying) response and exit: the next
-                        # command cold-starts, re-attaches the session's tab
-                        # group (title-keyed recoverSession) and releases the
-                        # slot. The hint must NOT teach `session new` -- the
-                        # session itself is fine; only the executor is not.
-                        sid = self._session_id or "<id>"
-                        error["fix"] = (
-                            "the session's tab binding is gone (extension "
-                            "reloaded/updated, daemon restarted, or the tab was "
-                            "closed). The executor recycled itself; the NEXT "
-                            "command re-attaches the session automatically. If "
-                            "the tab is gone for good, run `browserwright "
-                            f"session reset -s {sid}` first, or `browserwright "
-                            f"session attach-active -s {sid}` to adopt the tab "
-                            "you are looking at, then retry."
-                        )
-                        terminal_reason = TERMINAL_TARGET_CLOSED
-                    return self._finish(
-                        buf, error=error, exit_code=3,
-                        terminal_reason=terminal_reason,
-                    )
+                        return self._target_closed_response(buf, error, 3)
+                    return self._finish(buf, error=error, exit_code=3)
         finally:
             self._active_globals = None
         return self._finish(
@@ -746,6 +839,57 @@ class _Worker:
             exit_code=0,
         )
 
+    def _target_closed_response(
+        self, buf: io.StringIO, error: dict[str, Any], exit_code: int,
+    ) -> ExecuteResponse:
+        """Answer a call that died because the session's tab is gone.
+
+        Issue #86 changed what "answer" means here. The old behaviour was
+        terminal-only: flush the error and exit the executor so the NEXT
+        command cold-starts and re-attaches. That was correct but never
+        reached for `page.goto` (see the BrowserwrightError branch), and even
+        where it was reached it threw away the executor's `state`.
+
+        Now: try ONE in-place rebind first. It goes through
+        ``resolve_current_target``, so the replacement tab lands in this
+        session's tab group and the ledger stays in step. If it works, the
+        session is usable again on the very next statement and the error says
+        so — retry, do NOT create a new session. If it does not, fall back to
+        exactly the old terminal recycle. One attempt, two clearly different
+        outcomes, no loop.
+        """
+        sid = self._session_id or "<id>"
+        failure: str | None = None
+        try:
+            if not self._rebind_dead_page():
+                failure = (
+                    "the tab died again after this call already rebound once")
+        except BaseException as rebind_exc:  # noqa: BLE001 - fall back, never raise
+            failure = str(rebind_exc)
+        if failure is not None:
+            error["fix"] = (
+                "the session's tab binding is gone (extension "
+                "reloaded/updated, daemon restarted, or the tab was closed) "
+                f"and re-binding a fresh tab failed ({failure}). The "
+                "executor recycled itself; the NEXT command re-attaches the "
+                "session automatically. If the tab is gone for good, run "
+                f"`browserwright session reset -s {sid}` first, or "
+                f"`browserwright session attach-active -s {sid}` to adopt the "
+                "tab you are looking at, then retry."
+            )
+            return self._finish(
+                buf, error=error, exit_code=exit_code,
+                terminal_reason=TERMINAL_TARGET_CLOSED,
+            )
+        error["fix"] = (
+            "the tab this session was bound to is gone (closed by the page, "
+            "by the user, or by a renderer crash). A fresh tab has been opened "
+            "in THIS session's tab group and `page` is bound to it — RETRY the "
+            "call. The session does not need to be recreated; if this keeps "
+            "happening on the same URL, that page is closing its own tab."
+        )
+        return self._finish(buf, error=error, exit_code=exit_code)
+
     @staticmethod
     def _exec_with_return(code: str, globals_: dict[str, Any]) -> str | None:
         """Exec ``code``; if the LAST statement is a bare expression, return its

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

@@ -33,9 +33,22 @@ class PageLoadFailed(BrowserwrightError):
         "check the URL and network with http_get(url)"
     )
 
-    def __init__(self, url: str = "", reason: str = "", fix: str = ""):
-        self.url, self.reason = url, reason
-        super().__init__(f"page load failed: {url} ({reason})", fix=fix)
+    def __init__(
+        self,
+        url: str = "",
+        reason: str = "",
+        fix: str = "",
+        detail: str = "",
+    ):
+        # `detail` carries the ORIGINAL exception type + message. Without it a
+        # caller only ever sees our own coarse `reason` bucket, which is how a
+        # whole batch of CDP/relay failures once got reported as "network" with
+        # no way left to tell what actually broke. Never drop it.
+        self.url, self.reason, self.detail = url, reason, detail
+        message = f"page load failed: {url} ({reason})"
+        if detail:
+            message = f"{message}: {detail}"
+        super().__init__(message, fix=fix)
 
 
 class PageBindTimeout(BrowserwrightError):
@@ -73,6 +86,39 @@ class PageBindTimeout(BrowserwrightError):
         )
 
 
+class TabRebindFailed(BrowserwrightError):
+    """The session's bound tab died AND re-binding a replacement failed.
+
+    Issue #86: a session whose tab dies used to answer every later call in
+    1-4ms with ``TargetClosedError``, forever, because the bind was performed
+    once and never revisited. The bind is now re-entered when the bound page
+    is dead — but that recovery has to be *bounded*: exactly one attempt, and
+    a failure that is TELLABLE APART from the dead-tab condition it was trying
+    to repair. Without a distinct error a genuinely unusable browser would
+    look like a tab that is merely closed, and the caller would keep asking
+    for a rebind that cannot ever succeed.
+
+    So: ``TargetClosedError`` (or ``PageLoadFailed(reason="target-closed")``)
+    means "the tab is gone, recovery is being attempted"; THIS error means
+    "the tab is gone and recovery itself failed" — a different next action.
+    """
+
+    exit_code = 3
+    default_fix = (
+        "the session's tab is gone and re-opening one failed; the browser or "
+        "the extension relay is likely unusable. Check `browserwright doctor` "
+        "and the daemon log, then `browserwright session reset <id>` (or start "
+        "a new session) — retrying the same call will NOT help"
+    )
+
+    def __init__(self, reason: str = "", fix: str = ""):
+        self.reason = reason
+        message = "the session's tab is gone and re-binding a new one failed"
+        if reason:
+            message = f"{message}: {reason}"
+        super().__init__(message, fix=fix)
+
+
 class ElementNotFound(BrowserwrightError):
     exit_code = 3
     default_fix = (

{browserwright-0.17.2 → browserwright-0.17.4}/src/browserwright/repl/_smart_goto.py

@@ -162,29 +162,136 @@ def _bounded_timeout(total_ms: int, cap_ms: int) -> int:
     return max(1, min(int(total_ms), cap_ms))
 
 
-def _page_load_failed(url: str, phase: str, exc: BaseException) -> PageLoadFailed:
-    msg = str(exc)
-    exc_type = type(exc).__name__
-    lower = msg.lower()
-    if "timeout" in lower or exc_type == "TimeoutError":
-        return PageLoadFailed(
-            url,
-            phase,
-            fix="site did not respond at commit; verify it with http_get(url) or retry",
-        )
-    if "net::" in msg or "ssl" in lower or "name_not_resolved" in lower:
-        return PageLoadFailed(
-            url,
-            "network",
-            fix="check the URL and network; use http_get(url) to verify the site is reachable",
+# Navigation failure buckets. These are the `reason` field of PageLoadFailed —
+# an agent reads it to decide what to do next, so every bucket must point at a
+# DIFFERENT next action. Two buckets that share a fix are a bug: this table
+# used to collapse everything non-timeout into "network", which told users to
+# check their connection while the real failure was in the CDP/relay layer.
+#
+# The concrete accident this replaces: the extension caps every
+# `chrome.debugger.sendCommand` at 9000ms (`DEBUGGER_COMMAND_TIMEOUT_MS` in
+# chrome-extension/background.js) and reports the breach as "... timed out
+# after 9000ms ...". That string contains "timed out" but NOT "timeout", so it
+# missed the timeout check and fell into the second, identical branch —
+# `network`. A whole crawl's worth of "the extension's navigate budget expired
+# on a slow page" was reported to the operator as "check your network".
+_REASON_TIMEOUT = "timeout"
+_REASON_NETWORK = "network"
+_REASON_EXT_BUDGET = "extension-budget"
+_REASON_NAV_INTERRUPTED = "navigation-interrupted"
+_REASON_TARGET_CLOSED = "target-closed"
+_REASON_FRAME_DETACHED = "frame-detached"
+_REASON_CDP = "cdp-transport"
+_REASON_UNKNOWN = "unknown"
+
+_DETAIL_MAX = 300
+
+# Ordered most-specific-first; the first entry whose needle appears in the
+# lowercased message wins. Transport buckets deliberately sit ABOVE the generic
+# timeout bucket: a relay/extension budget that expires is NOT the site failing
+# to respond, and saying so sends the operator to the wrong layer.
+_CLASSIFIERS: tuple[tuple[str, str, tuple[str, ...]], ...] = (
+    (
+        _REASON_EXT_BUDGET,
+        "NOT a network problem: the browserwright extension caps every "
+        "chrome.debugger command at 9s (DEBUGGER_COMMAND_TIMEOUT_MS in "
+        "chrome-extension/background.js — a constant, not an env var), and "
+        "this navigation took longer to commit. The navigation may still be "
+        "completing in Chrome. Heavy SPAs routinely exceed it; navigate from a "
+        "fresh tab (context.new_page()) instead of reusing one parked on a "
+        "heavy page, and retry",
+        ("chrome.debugger.sendcommand timed out", "-32001",
+         "chrome.debugger.attach timed out", "chrome.debugger.detach timed out"),
+    ),
+    (
+        # net::ERR_ABORTED is NOT a network condition: Chrome emits it when a
+        # navigation is cancelled — superseded by another goto, turned into a
+        # download, or killed by the page itself. Bucketing it as "network"
+        # sends the user to check their connection for a race they own.
+        _REASON_NAV_INTERRUPTED,
+        "navigation was cancelled or superseded (download, redirect, or a "
+        "competing goto on the same page); ensure only one navigation runs per "
+        "page at a time, then retry page.goto(url)",
+        ("net::err_aborted", "interrupted by another navigation",
+         "navigation was cancel"),
+    ),
+    (
+        _REASON_NETWORK,
+        "check the URL and network; use http_get(url) to verify the site is "
+        "reachable",
+        ("net::", "ssl", "name_not_resolved", "err_internet_disconnected"),
+    ),
+    (
+        _REASON_TARGET_CLOSED,
+        "the tab/context backing this session went away mid-navigation; "
+        "re-acquire the page (page() / `session reset <id>`) before retrying, "
+        "and check whether the tab was closed by hand or by another session",
+        ("target closed", "target page, context or browser has been closed",
+         "browser has been closed", "page has been closed", "page was closed",
+         "session closed", "has been closed"),
+    ),
+    (
+        _REASON_FRAME_DETACHED,
+        "the frame was detached mid-navigation (usually a same-page rewrite or "
+        "an iframe teardown); retry page.goto(url) on a freshly acquired frame",
+        ("frame was detached", "frame has been detached", "detached frame",
+         "execution context was destroyed"),
+    ),
+    (
+        _REASON_CDP,
+        "the CDP path between the daemon, the extension relay and Chrome "
+        "failed — a transport fault, NOT the site. Check `browserwright "
+        "doctor` and the daemon log; if it repeats, recycle the session",
+        ("relay send failed", "extension relay", "extension reconnected",
+         "protocol error", "websocket", "ws closed", "no close frame",
+         "connection closed", "chrome.debugger", "debugger is not attached"),
+    ),
+)
+
+
+def _detail_for(exc: BaseException) -> str:
+    """Original exception type + first message line, bounded.
+
+    Playwright appends a multi-line call log to most errors; the first line is
+    the part that identifies the failure. Everything below it is noise, but the
+    type name never is — a bare message loses the difference between a
+    TimeoutError and a transport error that happens to mention a timeout.
+    """
+    lines = str(exc).strip().splitlines()
+    head = lines[0].strip() if lines else ""
+    if len(head) > _DETAIL_MAX:
+        head = head[: _DETAIL_MAX - 1] + "\u2026"
+    return f"{type(exc).__name__}: {head}" if head else type(exc).__name__
+
+
+def _classify(exc: BaseException) -> tuple[str, str]:
+    """Map a navigation exception to (reason, fix)."""
+    lower = str(exc).lower()
+    for reason, fix, needles in _CLASSIFIERS:
+        if any(needle in lower for needle in needles):
+            return reason, fix
+    if "timeout" in lower or "timed out" in lower or type(exc).__name__ == "TimeoutError":
+        return (
+            _REASON_TIMEOUT,
+            "site did not respond at commit; verify it with http_get(url) or retry",
         )
-    return PageLoadFailed(
-        url,
-        "network",
-        fix="check the URL and network; use http_get(url) to verify the site is reachable",
+    return (
+        _REASON_UNKNOWN,
+        "unrecognised navigation failure — do NOT assume it is the network; "
+        "read the exception detail in this message, then retry page.goto(url) "
+        "once and check the daemon log if it repeats",
     )
 
 
+def _page_load_failed(url: str, phase: str, exc: BaseException) -> PageLoadFailed:
+    reason, fix = _classify(exc)
+    # `phase` ("commit") is only meaningful for the timeout bucket, where it
+    # says how far the navigation got. Every other bucket names its own cause.
+    if reason == _REASON_TIMEOUT:
+        reason = phase or _REASON_TIMEOUT
+    return PageLoadFailed(url, reason, fix=fix, detail=_detail_for(exc))
+
+
 class _NetworkMonitor:
     def __init__(self, page: Any) -> None:
         self.page = page

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

@@ -37,7 +37,7 @@ from typing import Any
 from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
 from uuid import uuid4
 
-from ..errors import BrowserwrightError, PageBindTimeout
+from ..errors import BrowserwrightError, PageBindTimeout, TabRebindFailed
 
 logger = logging.getLogger(__name__)
 
@@ -320,6 +320,119 @@ def bind_current_page(context: Any, sess: Any) -> Any:
     )
 
 
+def page_is_dead(page: Any) -> bool:
+    """Is this bound ``Page`` a handle to a tab that no longer exists?
+
+    Issue #86. The bind used to be a one-shot: once a handle had a ``page``, it
+    never asked again, so a tab that died mid-session left every later call
+    failing in 1-4ms with ``TargetClosedError`` — forever, for the life of that
+    session. Detecting the dead handle is what lets the (already correct)
+    ``resolve_current_target`` recovery path be re-entered.
+
+    The probe is ``page.is_closed()`` — the flag Playwright sets when it
+    processes the target's destruction. It is LOCAL (no CDP round-trip), so it
+    is cheap enough to run before every call, and it is authoritative: it does
+    not fire for a page that is merely slow, busy, or in another context.
+
+    It is deliberately the ONLY probe. Inspecting ``context.pages`` instead
+    (empty, or missing this page) reads on the same condition — the field repro
+    left ``context.pages == []`` behind — but both spellings have false
+    positives a bare flag does not: a page can legitimately belong to a second
+    context, and a context can legitimately be observed before its pages
+    materialize. A false "dead" is expensive (it opens a replacement tab in the
+    user's browser and abandons a working one); a false "alive" costs nothing,
+    because the call then fails with the real ``TargetClosedError`` and the
+    reactive path rebinds from there. So anything unrecognised — a unit-test
+    double without the method, a probe that raises differently — is reported
+    ALIVE, and the reactive path is the backstop.
+    """
+    if page is None:
+        return True
+    is_closed = getattr(page, "is_closed", None)
+    if not callable(is_closed):
+        return False
+    try:
+        return bool(is_closed())
+    except Exception:  # noqa: BLE001 - a probe that raises means gone
+        return True
+
+
+def drain_page_events(context: Any, *, timeout: float = 0.001) -> None:
+    """Let Playwright process target events that queued while we were idle.
+
+    Issue #86's second half. ``page.is_closed()`` is fed by a channel event,
+    and the sync API only dispatches channel events while a sync call is in
+    flight — between two ``browserwright -s <id> -e ...`` invocations the
+    resident executor is parked in ``queue.get`` and nothing pumps. So a tab
+    that died while the session was idle leaves ``is_closed()`` reading False,
+    the pre-call probe sees a healthy page, and the caller eats one
+    ``TargetClosedError`` before the reactive path can rebind.
+
+    Draining first turns that lost call into a clean one. The budget is
+    deliberately ~1ms: this runs before EVERY executed call, and the queued
+    events are already sitting in the driver — the wait is only there to yield
+    to the dispatcher, not to wait for anything to arrive. Best-effort by
+    construction (``_pump_page_events`` swallows the timeout it is guaranteed
+    to hit on a quiet session).
+    """
+    _pump_page_events(context, timeout=timeout)
+
+
+def rebind_dead_page(context: Any, sess: Any) -> Any:
+    """Re-enter the bind discipline for a session whose tab died. ONE attempt.
+
+    Goes through :func:`bind_current_page` — i.e. ``resolve_current_target`` —
+    and NOT ``context.new_page()``, for exactly the reason the first bind does:
+    ``new_page`` opens a tab outside the session's tab group, which the agent
+    path cannot track (ledger drift → tab explosion). See
+    :func:`bind_current_page`'s docstring.
+
+    Raises :class:`~browserwright.errors.TabRebindFailed` when the rebind
+    itself fails, or when it hands back a page that is *also* already dead.
+    That second check is the loop bound: a browser that cannot hold a tab open
+    reports a distinct, terminal error instead of inviting another rebind.
+
+    The dead binding is DROPPED first — in memory and in the ledger — because
+    ``resolve_current_target`` would otherwise hand it straight back. Its step 2
+    (``ensure_session_target``'s ledger fast path) trusts ``cdp.attach(tid)`` to
+    fail for a closed tab; over the extension backend it does not, so recovery
+    returned the very target we are here to replace and the bind then timed out
+    against a tab that no longer exists. Measured, not reasoned: the e2e repro
+    resolved the same ``ext-tab-<id>`` that had just been removed. We know this
+    target is gone — that is the precondition of this function — so forgetting
+    it is not a guess. Everything below step 2 then does the right thing:
+    another live tab of the session if there is one, else a fresh tab opened in
+    the session's own group.
+    """
+    _forget_dead_binding(sess)
+    try:
+        page = bind_current_page(context, sess)
+    except Exception as e:  # noqa: BLE001 - re-raised as the distinct error
+        raise TabRebindFailed(f"{type(e).__name__}: {e}") from e
+    if page_is_dead(page):
+        raise TabRebindFailed(
+            "the replacement tab was already gone when it was bound")
+    return page
+
+
+def _forget_dead_binding(sess: Any) -> None:
+    """Drop the session's current-tab binding, in memory and in the ledger.
+
+    Best-effort by design: this runs on a recovery path, and a ledger write
+    that fails must not replace the rebind's own outcome with a bookkeeping
+    error. The worst case of a failed clear is the pre-existing behaviour —
+    recovery re-proposes the dead target and the bind times out.
+    """
+    try:
+        from ..session_runtime import persist_target
+
+        sess.current_target_id = None
+        persist_target(None, sess=sess)
+    except Exception:  # noqa: BLE001 - see docstring
+        logger.warning("could not clear the dead tab binding before rebinding",
+                       exc_info=True)
+
+
 def _discard_unbindable_tab(sess: Any, target_id: str) -> None:
     """Close a tab we opened but could not bind, and clear its ledger binding.
 
@@ -568,11 +681,15 @@ class PlaywrightHandle:
         self._context: Any = None     # bound BrowserContext
         self._page: Any = None        # bound Page
         self._connected = False
+        # Issue #86 re-entrancy guard: `rebind_dead_page` resolves the tab
+        # through the agent path, which can touch `page`/`context` again.
+        self._rebinding = False
 
     # ---- lazy connect + bind --------------------------------------------
 
     def _ensure_connected(self) -> None:
         if self._connected:
+            self._rebind_if_dead()
             return
         try:
             from playwright.sync_api import sync_playwright
@@ -605,6 +722,32 @@ class PlaywrightHandle:
         self._page = bind_current_page(self._context, sess)
         self._connected = True
 
+    def _rebind_if_dead(self) -> None:
+        """Issue #86: revisit the bind when the bound tab has died.
+
+        ``_connected`` used to be set once and never cleared, so ``_page`` was
+        never re-resolved: a tab that went away left this handle answering
+        every call with ``TargetClosedError`` in 1-4ms for the rest of its
+        life. The recovery already existed one layer down
+        (``resolve_current_target`` reuses / recovers via the tab group / opens
+        a fresh tab in THIS session's group) — it was simply never re-entered.
+
+        Bounded by construction rather than by a counter: a rebind only runs
+        while the current page reads as dead, and `rebind_dead_page` refuses to
+        hand back a page that is dead on arrival. So a successful rebind ends
+        the condition, and an unsuccessful one raises ``TabRebindFailed``
+        instead of arming another attempt.
+        """
+        if self._rebinding or not page_is_dead(self._page):
+            return
+        from ..session import current_session
+
+        self._rebinding = True
+        try:
+            self._page = rebind_dead_page(self._context, current_session())
+        finally:
+            self._rebinding = False
+
     # ---- accessors (trigger the lazy connect) ---------------------------
 
     @property

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: browserwright
-Version: 0.17.2
+Version: 0.17.4
 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