refactor: integrate band-sdk-core Session into BandLink

[AlexanderZ-Band]

Summary

Implements INT-1303: replaces band-sdk-python's hand-rolled reconnect/backoff/disconnect-classification logic in WebSocketClient/BandLink with band_sdk_core's Session state machine, per the ticket's attached implementation plan. All 5 migration steps shipped, squashed into 5 commits matching the plan's own step boundaries:

1. Extract the duplicated _fast_session_policy test helper into tests/websocket/conftest.py (prep, test-only)
2. Wire Session into WebSocketClient.__init__/__aexit__ (no behavior change)
3. Replace __aenter__'s retry loop with Session-driven backoff
4. Route agent_control:supersede through Session.on_supersede
5. Extend the CI wheel-smoke step with a Session/SessionPolicy call

Design decisions (from the plan) — all 4 shipped as specified

1. 429/503 upgrade rejections on the initial-connect path are now retried automatically via Session.on_upgrade_rejected (using Retry-After as a delay floor), instead of raised immediately as before.
2. Session.on_supersede's Reconnecting branch is implemented in BandLink._on_supersede, even though the platform hardcodes retryable=False on every real supersede today (only a synthetic regression test exercises it) — keeps the SDK correct about not treating it as terminal if that ever changes. It does not yet drive actual reconnect timing off that decision — see below.
3. WebSocketDisconnectReason gained dead_reason/stale_reason fields.
4. Those fields are populated from both the supersede path and __aenter__'s terminal-failure path (a new _disconnect_reason_from_exception, since there's no platform wire payload for that case) — widening BandLink.last_disconnect_reason's trigger scenarios to include a permanently-failed initial connect, not just a supersede.

Out of scope (per the ticket, untouched): taking ownership of the vendored PHXChannelsClient's internal auto_reconnect loop — separate, larger follow-up work, tracked as INT-1355 (filed during review: a retryable supersede's retry_after_s is classified but not enforced without that ownership change; not reachable today since the platform always sends retryable=False).

Other real, intentional behavior change from Step 3: the initial-connect give-up bound is now a rolling 5-minute rapid-disconnect window (10 by default) instead of a fixed 11-attempt cap.

INT-1303: https://linear.app/thenvoi/issue/INT-1303/integrate-band-sdk-core-session-connection-reliability-into-band-sdk

Review history

Two rounds of external review, both verified and closed out:

• /code-review high: confirmed a real exception-chaining regression (raise raise_exc had dropped from exc for the classified-upgrade-error case) — fixed, with a regression assertion. A comment-style finding (narrating removed mechanisms) — fixed.
• /my-here-is-a-review (2 rounds) on the retryable-supersede retry_after_s gap: confirmed real but architecturally out of scope (needs the deferred auto_reconnect-ownership work) — filed as INT-1355, PR thread resolved.

Test plan

• uv run ruff check . / uv run ruff format . / uv run pyrefly check / full unit suite (uv run pytest tests/ --ignore=tests/integration/ --ignore=tests/e2e/) — clean
• Every ticket-listed acceptance regression test passes explicitly (test_aenter_restores_reconnect_after_successful_initial_connect, test_uses_retry_after_header_for_429_upgrade_error, test_supersede_event_records_terminal_reason_and_disables_reconnect, test_watchdog_forces_close_and_reconnect_when_ack_withheld, test_cancelled_connect_closes_the_half_opened_client_and_allows_retry, test_disconnect_after_supersede_still_cleans_up_websocket, test_close_without_supersede_leaves_disconnect_reason_empty, all of tests/websocket/test_watchdog.py)
• New tests added per the plan's test plan: rapid-disconnect-ladder trip to Dead, 429 upgrade rejection retried via the probe fallback then succeeding, retryable supersede leaves the connection non-terminal, connect() propagates a terminal initial-connect failure onto last_disconnect_reason, exception-chaining regression guards
• All CI checks green (lint, packaging, full test matrix, CodeQL)

🤖 Generated with Claude Code

https://claude.ai/code/session_01FuwaxzwGje1eq94W7V8zrW

[linear-code]

INT-1303

[amit-gazal-band]

Requesting changes on two correctness issues that undermine this PR's core "fail fast on rapid disconnects" guarantee, plus two smaller robustness gaps worth closing in the same pass. Everything else from the fuller review (efficiency/maintainability/style/test-coverage) is lower stakes and fine as follow-up.

[AlexanderZ-Band]

Found one correctness issue in the initial-connect retry cache.

[Copilot]

🟡 Changes recommended

There is at least one correctness issue in exception re-raising (traceback loss) plus a few naming/type issues in newly introduced shared test helpers that should be fixed before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR refactors the SDK’s WebSocket connection lifecycle by integrating band_sdk_core.Session into WebSocketClient/BandLink, replacing the prior hand-rolled retry/backoff and supersede classification logic while expanding disconnect-reason reporting.

Changes:

• Drive initial-connect retry/backoff and terminal classification via Session (including upgrade-rejection retry semantics and rolling rapid-disconnect window behavior).
• Route agent_control:supersede through Session.on_supersede, and record richer terminal/stale disconnect metadata.
• Consolidate websocket test helpers in tests/websocket/conftest.py and extend CI wheel-smoke to exercise Session/SessionPolicy.

File summaries

File	Description
tests/websocket/test_watchdog.py	Switch watchdog tests to use the shared fast_session_policy helper.
tests/websocket/test_client.py	Add/adjust tests for Session-driven initial-connect retries, probe caching behavior, and richer disconnect reason propagation.
tests/websocket/conftest.py	Introduce shared scripted-connect/probe helpers, a no-real-sleep fixture, and fast_session_policy.
tests/platform/test_link.py	Update link tests to reflect Session-driven supersede handling and initial-connect terminal reason propagation.
src/band/platform/link.py	Integrate Session-aware supersede handling and propagate terminal initial-connect disconnect reason to BandLink.
src/band/client/streaming/errors.py	Replace initial-upgrade classification helper with a probe-based upgrade-error recovery function.
src/band/client/streaming/client.py	Replace initial-connect retry loop with Session state machine integration; add disconnect reason synthesis and supersede routing.
.github/workflows/ci.yml	Extend wheel-smoke to validate Session/SessionPolicy are callable from the built wheel.

Review details

Suppressed comments (1)

tests/websocket/conftest.py:31

• After renaming _Script to Script, update this call site so ScriptedPHXClient constructs the renamed helper type.

    def __init__(self, *script: Exception | object):
        self._script = _Script(script)
        self.auto_reconnect: bool | None = None

• Files reviewed: 8/8 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.