[abrainwood]

Closes #11.

What

A failed MQTT reconnect during the scheduled credential refresh could cancel itself and leave no retry armed. MQTT then stayed down until the next refresh, about 55 minutes later, with REST polling hourly in between. This PR makes that path always end with exactly one recovery attempt in flight.

• One failure, one signal. connect() no longer fires the reconnect-failed callback as well as raising. The raise owns recovery; the callback serves only the connection-resumed path.
• The credential refresh hands off to the single-flight retry slot. _async_refresh_credentials_after calls _trigger_mqtt_reconnect(name="exo_pool_credential_refresh"), and the reconnect task is created with eager_start=False, so it can't run inside its caller's frame and cancel itself.
• A refresh that finds an attempt already running waits for it, and doesn't cancel it. It uses asyncio.wait({in_flight}) rather than awaiting the attempt directly. So cancelling the refresh, whether by a reschedule or by HA stopping, never cancels the attempt, and the refresh's own cancel isn't swallowed. After the attempt ends, the refresh triggers its own reconnect. If the entry was unloaded in the meantime, it exits without recreating the entry store.
• Setup failures arm a retry. An MQTT failure at setup falls back to REST polling and arms the retry chain. That gives exactly one WARNING, carrying the reason, with no traceback.
• Reasons are always readable. _format_error_reason falls back to the exception type name, so a bare TimeoutError() logs "TimeoutError" instead of an empty or wrong reason. Every exception that can reach a reason string was traced, and none can carry a credential.
• Partial subscribe failure is visible. If only some topics subscribe, one WARNING lists the failed topics, on both connect and resume. The per-topic failures stay at DEBUG.
• Preempting a sleeping backoff clears the sleeping flag right away, so two triggers in the same tick log no false "Preempting".
• get_coordinator was split to clear Sonar S3776.
• The credential-refresh timer task is now named exo_pool_credential_refresh_timer, so HA's task listings and shutdown logs can tell it apart from the reconnect handoff task (exo_pool_credential_refresh). Nothing in production matches on task names.

No shared "in progress" flag is used. That was tried twice during review, and both times it broke recovery.

Tests

276 passing, stable across 20 runs with -n 4. The earlier round was also stable across 20 runs with -n 8 under CPU contention.

• Real-chain tests. These use the real trigger and a gated real attempt, and cover:
  • the refresh deferring to an in-flight attempt
  • cancellation, both by a reschedule and by HA stop without unload
  • the lost-refresh case, where a deferred refresh reconnects after the attempt fails
  • unload while waiting
• Mutation testing. Reviewers ran roughly 60 mutants, including the original Credential-refresh reconnect can cancel itself and leave MQTT with no retry #11 self-cancel shape. A few survive, all harmless or behaviour-equivalent:
  • polling instead of asyncio.wait
  • the no-reason branch, which production can't reach
  • pop vs get on the stored reason
  • arm-then-REST order, tracked in MQTT retry orphaned when setup's first REST refresh fails #17
  • The one mutant that leaves a loop which never yields is caught only by the global pytest timeout, because no assertion can observe a loop that never gives up control. A per-test timeout(2) mark was tried and then removed: it raced the test's own 2-second wait, so a regression could hang the run instead of failing it.
• Setup shadow wait. The wait for MQTT shadow data at setup is pinned from three sides: data already there, data arriving partway through the wait, and data never arriving. Its attempt count and interval are module constants.
• Helper hardening. Where a test depends on work in the executor, _settle() now waits on a real condition, bounded by wait_for, instead of a fixed number of yields. The three plain calls still yield a fixed number of times; that's deterministic, because nothing on those paths touches the executor.
• Stub removed. The Wake writes held behind a REST cooldown on MQTT reconnect #12 workaround stub for the late reconnect-failed callback is gone. test_a_fully_failed_subscribe_does_not_reset_the_backoff now runs deterministically on the real path.
• Deduplication. Duplicated setup was moved into shared fixtures in tests/conftest.py. make lint-dup was added; note that it does not see every block Sonar flags.

Not in this PR

• Reconnect edge cases: same-tick double trigger, and unload during an in-executor connect #14 covers the other reconnect edge cases: a double trigger in the same tick, unload during a connect running in an executor thread, and _connect_mqtt recreating the entry store after unload.
• MQTT retry orphaned when setup's first REST refresh fails #17 covers an MQTT retry left orphaned when setup's first REST refresh fails. HA never unloads an entry that is stuck in setup-retry.

🤖 Generated with Claude Code

https://claude.ai/code/session_019FJHinb3pMJEwTKrnMXMcG

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud