feat: surface link health in the slot suspension repair

[raman325]

Proposed change

The slot suspension repair currently guesses between two very different causes:

The lock may be rejecting the code silently or experiencing communication issues.

Lock Code Manager has no reliable way to tell those apart from the lock's behaviour alone — both present identically from the slot: a code that was written and never reads back.

Providers that can measure their own transport do know. This adds an optional describe_link_health() hook on BaseLock (default None) whose sentence is appended to that repair.

Descriptive only — nothing reads it to make a decision, no new state, no thresholds, no control-flow change. A provider that cannot measure anything returns None and the repair keeps its wording verbatim. Every implementation reports measurements, never a verdict, states the semantics of what it reports, and never lets a failed read cost the caller its repair.

Z-Wave JS

Z-Wave link, counted since Z-Wave JS started or the statistics were last reset: 256 commands reached this lock, 4 could not be sent at all, and 126 read requests went unanswered; recent round trips averaged 1072 ms.

Three counters side by side rather than one ratio, because node-zwave-js counts them over different populations (verified against NodeStatistics.ts): commandsTX counts only commands successfully sent (:47) — an out-of-range lock increments commandsDroppedTX (:54) instead — while timeoutResponse counts only Get-type commands (:55). Any ratio built from these distorts in the exact case the feature exists for. rtt is an exponential moving average (:59-61), so it is reported as an average, and the window wording covers resets as well as restarts (:44).

ZHA

Zigbee link, from the last frame this lock sent: signal quality 12 of 255, -89 dBm, last heard from 3 hours ago.

Zigbee has no per-node failure counters — zigpy keeps counters on the radio application, not per device — so ZHA reports the other honest signal. Staleness carries most of the weight: a lock unheard-from for hours while LCM is actively writing to it is the Zigbee equivalent of an unanswered-command count, and it stays meaningful on radios reporting no signal metrics. lqi/rssi are overwritten from each received packet, so the wording says "the last frame this lock sent" rather than implying an average.

Matter (Thread)

Thread link, from the lock's own radio counters since it last restarted: 3608185 of 3611401 transmissions that asked to be acknowledged were acknowledged, and the lock has dropped off the Thread network 228 times.

Validated against real hardware (an Aqara Smart Lock U300 on Thread) after the mock fixture showed every Thread Network Diagnostics counter as zero, leaving it unclear whether they are ever populated. They are — that lock reports a feature map of 15, all four counter features present.

The acknowledgement pair is safe to state as a proportion because both counters are drawn from the same population, unlike most pairs in this cluster. Every counter is optional, so each is read independently and omitted when absent, which avoids modelling which feature bit governs which attribute. The wording is explicit that these are the lock's own view of its radio rather than the hub's view of reaching it.

Thread only: a Wi-Fi or Ethernet Matter lock exposes a different diagnostics cluster whose semantics are unverified against hardware.

Providers with nothing to report

• zigbee2mqtt — publishes linkquality, but the provider does not retain it; capturing it would mean new per-lock state for a point-in-time value with no staleness signal.
• Schlage / Akuvox — cloud APIs with no radio telemetry.
• virtual — nothing to measure.

Type of change

• Dependency upgrade
• Bugfix (non-breaking change which fixes an issue)
• New feature (which adds functionality)
• Breaking change (fix/feature causing existing functionality to break)
• Code quality improvements to existing code or addition of tests

Additional information

• This PR is related to issue: [ISSUE] Sync attempts exceeded #1397

Motivated by #1397, where the reporter's lock left ~49% of the commands sent to it unanswered (126 of 256 cumulative; 19 of 39 during a controlled test). The write reached the lock — the PIN works on the keypad — but the driver's post-write verification read timed out, so the value database kept serving a stale userIdStatus = Available and the slot could never confirm. It looked exactly like a silently rejected code.

This does not close #1397: the reporter's underlying problem is their Z-Wave mesh, not integration logic. It makes the next report of this shape self-diagnosing.

Coverage remains at 100%.

🤖 Generated with Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.96%. Comparing base (988a5fb) to head (4dcc050).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1410   +/-   ##
=======================================
  Coverage   98.95%   98.96%           
=======================================
  Files          53       53           
  Lines        6611     6668   +57     
  Branches      470      470           
=======================================
+ Hits         6542     6599   +57     
  Misses         69       69           

Flag	Coverage Δ
python	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
custom_components/lock_code_manager/domain/sync.py	100.00% <100.00%> (ø)
...om_components/lock_code_manager/providers/_base.py	100.00% <100.00%> (ø)
...m_components/lock_code_manager/providers/matter.py	100.00% <100.00%> (ø)
...stom_components/lock_code_manager/providers/zha.py	100.00% <100.00%> (ø)
...components/lock_code_manager/providers/zwave_js.py	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.