Offset Sync reliability + HomeKit recovery fixes

Two issues surfaced on beta.15 this week — @apilone reported a zone state desync that turned out to hide a second, bigger problem draining his daily API quota, and @simonotter's Offset Sync chart kicked off a cache-poisoning audit that found three related bugs in the offset write path. This release fixes all of them, plus a smaller regression caught while auditing other caches in the integration.

⚠️ Upgrade Notes

• Requires Home Assistant 2025.11+ (unchanged from beta.15).
• Upgrading from v3.5.3 or any v4.0.0 beta — data migration is automatic.
• No Options Flow changes — settings from beta.15 carry over as-is.

Bug Fixes

• Fixed zone state not updating when changed from the Tado app while OFF (#261 - @apilone) — Flipping a zone from OFF to HEAT (or setting a temperature on an OFF zone) via the Tado phone app now reflects in the HA climate entity in real time. Previously the integration waited for the next cloud poll (up to 12 minutes on default settings) to pick up the change. The root cause was a state-level gate added in beta.15 that correctly blocked stale bridge echoes but also swallowed legitimate user actions — the reconciler now distinguishes the two by checking when the bridge value last actually changed, not just whether the value was recently observed.
• Fixed API calls looping after a HomeKit bridge disconnects (#261 - @apilone) — If the HomeKit bridge went unreachable, Home Assistant would retry the Tado CE setup in a back-off loop, and each retry re-downloaded every zone's schedule from the cloud — chewing through hundreds of API calls overnight on a quiet home. Schedules are now reused from the local cache on retry, and the fetch is skipped entirely when the API quota is low. Affected users will see the integration recover on its own as the bridge reconnects rather than exhausting the daily quota.
• Fixed Offset Sync getting stuck at ±10°C when a write fails (#262 - @simonotter) — If a device offset write failed (API rate-limit, temporary server error, or queue overflow), the integration's cached offset was updated to the value we tried to write even though the TRV never received it. Subsequent correction cycles then calculated from the wrong baseline and could peg at the ±10°C clamp while the TRV's actual offset drifted elsewhere. The integration now reads the offset back from Tado after every write and only updates the cache when Tado confirms the value — matching the pattern the Set Temperature Offset service has used since v3.
• Fixed Offset Sync drifting to the ±10°C limit when Tado's adaptive calibration changes the offset (#262 - @simonotter) — Same symptom as the entry above, different cause. If Tado's own learning loop (or a manual edit in the Tado app) changed the stored offset, the integration had no way to find out until the next restart, so the next Offset Sync evaluation calculated from a stale baseline and could march the cached offset to ±10°C even when no write had failed. The integration now re-reads each TRV's stored offset from Tado every 30 minutes and reconciles the local cache, so a drift between the two values is corrected within at most one refresh interval. The refresh is skipped when API quota is low — the per-write readback gate keeps the cache safe in the meantime.
• Fixed Early Start and Child Lock switches not rolling back on failed writes — If the Tado API rejected a switch write (e.g. during a rate-limit window), the switch would stay in the optimistic new state on the dashboard until the next successful refresh. The switch now rolls back to the previous state when the underlying API call reports failure.
• Fixed Presence Mode "Auto" briefly showing "Home" when the home was actually away — Switching to Auto used to overwrite the cached home presence with "Home" until the next cloud poll, so the climate card's Home/Away preset chip showed the wrong value for one poll cycle when you picked Auto while physically away. The integration now leaves the cached presence alone when you switch to Auto and lets the next poll fill in the real value from geofencing.

Improvements

• More reliable HomeKit freshness tracking — The bridge's 2-minute keepalive poll no longer masquerades as a real value change. Target temperature and HVAC mode now correctly fall back to cloud when the bridge hasn't actually seen an event in the last 5 minutes, even if keepalive is still refreshing the cache.
• Climate entity now signals when Offset Sync hits Tado's ±10°C limit (#262 - @simonotter) — When the gap between your external sensor and the TRV reading needs a correction larger than ±10°C, Tado can't store it and clamps the value at the limit. Previously the entity silently showed +10.0 with no indication the real gap was bigger. The climate entity now exposes offset_clamped: true and offset_clamp_direction: hit_max | hit_min as extra attributes, plus a warning in the log when the clamp fires. If you see this, the cause is usually a draught on the TRV, a cold external wall behind it, or the external sensor in a warmer pocket than the TRV.

How to Update

HACS → Tado CE → ⋮ → Redownload → tick "Need a different version?" → select v4.0.0-beta.16 → Restart HA

---

Thanks to everyone who supported the project through Buy Me a Coffee — it genuinely helps.

Full Changelog: CHANGELOG.md