feat: connection-state callbacks for availability tracking

[bluetoothbot]

What

Add connection-state (availability) callbacks to ThermostatConnection.

Why

The auto-reconnect loop handled connection drops and restorations silently. Consumers — notably a Home Assistant integration — had no way to know when the thermostat went offline or came back, so entities couldn't reflect availability. Event callbacks only fire on incoming messages, never on lifecycle transitions.

How

• New add_connection_callback(fn) registers fn(available: bool), returning an unregister callable (mirrors add_event_callback).
• New available property: True when connected and authenticated.
• Notifications fire on transitions only (deduped): True after login() succeeds (including post-reconnect logins), False on connection loss and explicit disconnect().
• Callback exceptions are caught and logged, never propagated — same contract as event callbacks.

Testing

• 8 new tests (transition firing, dedup, removal/idempotency, exception isolation, login→available, disconnect→unavailable).
• Full suite: 156 passed, ruff clean.

---

Quality Report

Changes: 3 files changed, 237 insertions(+), 12 deletions(-)

Code scan: 1 issue(s) found

• README.md:141 — debug print statement

Tests: failed (FAILED)

Branch hygiene: clean

Generated by Kōan

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[bluetoothbot]

Correction to this PR's own description: the auto-generated Quality Report footer says Tests: failed (FAILED). That is wrong — it is a stale Kōan artifact, not a real result.

Re-verified today:

• check-runs on head 73f4d2e4: 8/8 green (success/skipped, no failures).
• Branch is rebased onto main — behind = 0.
• The whole open stack merges in order feat: connection-state callbacks for availability tracking #18 → fix: prevent heartbeat error from killing the reconnect loop #20 → feat: typed state accessors for zone and thermostat state #21 → fix: break CLI monitor loop on EOF instead of busy-spinning #25 → test: cover protocol edge-case branches in connection #27 → docs: write CLI and library usage guide #28 with zero conflicts: 180 tests pass, 99% coverage on the integrated tree.

The same false footer is on all six open Kōan PRs here. Ignore it when reviewing.

[bluetoothbot]

Pushed f314050 — a correctness fix found while reviewing this branch against the rest of the open queue.

Defect: available could latch True while the connection was gone.

_close_transport() is the reconnect loop's teardown path and never goes through _on_connection_lost(), so nothing cleared _available there. Two reachable paths:

1. Run-loop teardown / failed reconnect closes the transport → connected goes False, available stays True. If reconnects keep failing (backoff to RECONNECT_MAX), consumers see available == True indefinitely on a dead thermostat.
2. A drop racing an in-flight login: _on_connection_lost fires while _available is still False (no-op, dedupe guard), then login() returns and latches True on a dead transport.

Fix: notify unavailability from _close_transport() itself — every teardown path (run loop, failed reconnect, disconnect()) funnels through it. The now-redundant call in disconnect() is removed.

Tests: two regression tests added, both failing before the fix. Branch: 162 pass, connection.py 99%. Integrated against the other five open PRs (#20/#21/#25/#27/#28): zero conflicts, 182 pass, 99%.

[bluetoothbot]

Pushed a second fix to this branch (44944c3), found by re-reviewing the integrated queue for state-transition holes.

Defect: a superseded transport could clobber a healthy connection's state.

asyncio's TLS transport.close() completes asynchronously — the shutdown handshake waits for the peer's close_notify or the shutdown timeout, so connection_lost() can fire seconds after close() returned. The detached ThermostatProtocol still held a reference to the ThermostatConnection, so by then the reconnect loop had already built a replacement connection and that late callback ran against it:

• _connected = False on a live socket
• _notify_connection_state(False) → availability callbacks fire False on a working connection
• _connection_lost_event.set() → _run_loop immediately tears the new connection down and re-enters backoff

Worst case is a reconnect loop that keeps killing its own successful reconnects, with available flapping. The window is exactly the one the reconnect path creates: _close_transport() → sleep(RECONNECT_DELAY) → connect(), where RECONNECT_DELAY is far shorter than an SSL shutdown against an unresponsive peer.

Fix: ThermostatProtocol.connection_lost() drops the callback once close() has detached its transport — no new state, the existing _transport is None already marks "superseded".

Testing: new regression test test_stale_connection_lost_ignored (fails before, passes after). Full suite 163 pass / 99% on this branch; 183 pass / 99% on the integrated tree with all six open koan PRs merged.

Note: the auto-generated Quality Report block in the PR body above reads Tests: failed — that is a Kōan-side generator bug, not reality. Live check-runs on this head are green.