feat(websocket): add heartbeat dead-threshold watchdog

[AlexanderZ-Band]

Summary

Part of INT-1323: wires WebSocketClient up to band-sdk-core's shared SessionPolicy heartbeat/dead-threshold policy (band-ai/band-sdk-core#60, released as v2.0.0) and phoenix-channels-python-client's new on_heartbeat_ack/close_connection surface (band-ai/phoenix-channels-python-client#53).

Dead-connection detection lives in a new band.client.streaming.watchdog.HeartbeatWatchdog class, not inline in WebSocketClient:

• HeartbeatWatchdog owns the deadline, the watchdog task, and the force-close decision. WebSocketClient holds one self._watchdog and delegates start/stop/reset_deadline to it.
• heartbeat_interval_s (from SessionPolicy, default or an injected override) is passed to PHXChannelsClient; on_heartbeat_ack and on_reconnect are wired to reset the watchdog's deadline.
• HeartbeatWatchdog.start(client) takes the specific PHXChannelsClient instance as an argument (not read dynamically later), so a stale watchdog from a superseded initial-connect attempt can never act on a later instance.
• A force-close, once dead_threshold_s passes with no ack, flows into the client's own existing reconnect path — no new disconnect-handling branch.
• Reconnects reset the deadline immediately (not just acks and the initial connect) — otherwise a reconnect can inherit a stale deadline from disconnected-state polling and get force-closed before its first heartbeat cycle completes.
• The watchdog task is started only once, on a successful connect, and stopped cleanly in __aexit__.
• A close_connection failure is caught and logged rather than killing the watchdog task, and the watchdog skips warning/closing when there's no live connection to avoid misleading log spam during backoff.

Dependency floor: resolved

phoenix-channels-python-client PR #53 has since released as a real PyPI version (0.2.4) containing on_heartbeat_ack/close_connection. dependencies pins phoenix-channels-python-client>=0.2.4 — a real, verified floor — and there is no [tool.uv.sources] git override. This PR is mergeable/releasable; the packaging job's "Install from wheel" step passes.

Addressed review feedback (amit-gazal-band)

• test_aenter_restores_reconnect_after_successful_initial_connect called __aenter__ without a matching __aexit__, leaking a watchdog task against a test double with no real .connection — once dead_threshold_s elapsed, _force_close_if_stale would raise AttributeError inside that fire-and-forget task on the session-scoped event loop, polluting whichever test ran when it fired. Gave the double a no-op __aexit__ and added the matching cleanup call, same shape as the sibling retry-backoff test's own earlier fix. Checked every other bare __aenter__() call in the file: the rest all raise before reaching the watchdog-start line, so this was the only actual leak.

Review thread resolved.

Test plan

• tests/websocket/test_watchdog.py — 5 tests against HeartbeatWatchdog directly, no real socket needed: task cancels cleanly on stop(); a stale watchdog from a superseded attempt cannot close a newer connection; survives a close_connection failure and keeps enforcing the threshold; neither warns nor closes while already disconnected; a reset deadline lets a fresh socket survive a reconnect that lands late in a disconnected-state polling window.
• tests/websocket/test_client.py — real-wire tests against an in-process Phoenix-protocol peer, covering the actual wiring: ack keeps the connection alive across several heartbeat cycles; a withheld ack forces close + reconnect at ~dead_threshold_s; __aexit__ stops the watchdog; the successful-initial-connect test no longer leaks a watchdog task (-W error clean).
• uv run pytest tests/ --ignore=tests/integration/ --ignore=tests/e2e/ --all-packages — 5175 passed, 122 skipped.
• uv run pyrefly check (project-wide, matching CI) — 0 errors.
• uv run ruff check / ruff format --check — clean.
• Merged main to pick up an unrelated band-sdk-core/lockfile drift; resolved keeping this PR's band-sdk-core==2.0.0 and phoenix-channels-python-client>=0.2.4. Full CI green (20/20 checks) as of the merge commit, including packaging.

🤖 Generated with Claude Code

https://claude.ai/code/session_011EuhCwwdkV3gYphyNFkw9Y

[linear-code]

INT-1323

[amit-gazal-band]

Two test-isolation issues from the new HeartbeatWatchdog, neither blocking merge but worth a fast follow-up.

tests/websocket/test_client.py:417 (pre-existing line, not touched by this diff, so GitHub won't let me anchor an inline comment there): test_aenter_retries_unclassified_initial_connection_errors does monkeypatch.setattr("band.client.streaming.client.asyncio.sleep", fake_sleep), which patches the real asyncio module globally, not just this module's usage. The new HeartbeatWatchdog also calls asyncio.sleep internally (in _sleep_until_deadline), so it gets patched too — and since fake_sleep returns instantly, the watchdog's sleep loop busy-spins forever once it starts. Confirmed by running the test directly: it now takes ~32s instead of near-instant, and logs an unhandled Task exception was never retrieved / pytest-timeout error rooted in HeartbeatWatchdog._loop.

[AlexanderZ-Band]

@amit-gazal-band addressed the review comment in de8673a — pushed and thread resolved. Full unit suite green (5175 passed). Ready for another look.

[amit-gazal-band]

Verified Alex's fixes cover both review comments — the watchdog leak in client.py:431 and the monkeypatched asyncio.sleep spin in the retry-backoff test are both resolved (each affected test now stops the watchdog via __aexit__). Re-ran tests/websocket/test_client.py + tests/websocket/test_watchdog.py: 54 passed in 3.8s, no warnings or leaked tasks.

[amit-gazal-band]

Reviewed and confirmed: the leaked-watchdog-task fix in de8673a resolves the review comment — verified locally (tests/websocket/test_client.py, 49/49 passed, no leaked-task warnings). Note this PR is still marked not-mergeable pending the phoenix-channels-python-client dependency release per the PR description.