So I tracked down the hang issue around remote CDP sessions getting stuck indefinitely when the websocket silently degrades in Docker/cloud setups.

The main problem was that a few DOMWatchdog calls were awaiting CDP responses forever with no timeout boundaries, so once the socket went half-open the event bus lock never got released and parallel browser sessions just piled up behind it.

What's working now:

• Added timeout guards around the main CDP execute paths
• Mark degraded sessions unhealthy automatically
• Added lightweight connection health verification before watchdog execution
• Prevented the watchdog from blocking the whole event loop indefinitely

One annoying thing I hit while testing was reproducing the half-open websocket state consistently. Local runs were fine because TCP teardown happens immediately on localhost. Ended up simulating packet drops inside Docker/WSL to reproduce the actual hanging behavior reliably.

Also hit a small WSL issue with pre-commit expecting python3.11 specifically, but that was just local env noise — ruff + formatting + targeted tests are all passing.

Core fix looks like this now:

result = await asyncio.wait_for(
    cdp_session.execute(
        Runtime.evaluate(
            expression="window.performance.getEntriesByType('resource')",
            await_promise=True
        )
    ),
    timeout=5.0,  # remote CDP calls shouldn't block forever
)

except asyncio.TimeoutError:
    logger.warning("CDP session timed out while fetching network requests")

    # connection probably went half-open behind proxy/load balancer
    self.browser_session._is_healthy = False

    raise ConnectionError(
        "Remote browser connection became unresponsive"
    )

I also added tests around timeout handling + connection health verification so we don't regress on this later.

Summary by cubic

Prevents remote CDP sessions from hanging by adding bounded timeouts and proactive health checks, so half‑open WebSockets in Docker/cloud no longer stall the event loop. Parallel sessions now recover or fail fast. Fixes #4579.

• Bug Fixes
  • Added _is_healthy flag that gates is_cdp_connected, plus verify_connection_health() (1.5s Browser.getVersion ping).
  • Watchdog circuit breaker verifies health before handler runs; on failure marks unhealthy and auto‑reconnects, or skips if the browser was intentionally stopped.
  • Bounded timeouts for key CDP/DOM paths (e.g., 5s around get_or_create_cdp_session, network request checks, DOM build, screenshot); on timeout mark session unhealthy and raise ConnectionError.
  • Tests in tests/ci/test_connection_health.py cover health flag lifecycle, ping success/timeout, and DOMWatchdog timeout handling.

^{Written for commit 4bc538d. Summary will update on new commits. Review in cubic}