[flowcool]

Summary

Add retained MQTT controls so a sleeping device can enter an acknowledged OTA window or seasonal Storage mode.

retained request -> Maintenance > Storage > Normal
                    battery + panel checks
                    bounded watchdog or deep sleep

Maintenance acknowledges ON only after a finite battery reading at or above the configurable threshold and an observed panel refresh. Storage persists across boots, samples battery daily, and returns to fresh plant acquisition on exit. Duplicate retained commands do not restart completed work. The API profile clears a restored MQTT Storage latch and remains broker-free.

The common recovery path keeps one total BUSY budget and cancels stale work before a new refresh. Normal and emergency sleep preserve low-battery priority and explicit OTA confirmation. This includes the shared-core recovery mechanism also under review in #31; that PR separately updates the standalone example. Merge order can require refreshing the overlapping core and test helper.

Evidence

• Before: the MQTT profile has no acknowledged mode-request protocol.
  After: 52 tests pass, with no skips, on refreshed upstream V2R1. They execute actual package actions and native C++ lambdas for admission, arbitration, watchdog, OTA cleanup, retained echoes, fresh acquisition, profile changes, BUSY oscillation, cancellation and sleep-duration priority.
• Tests use the merged soil_voltage acquisition source and retain the existing median/cadence/calibration. The native library helper includes the Windows DLL cleanup and UTF-8 handling requested in Bring bounded display recovery and safe rendering to the standalone example #31. A native Windows run is not claimed.
• Isolated firmware builds with ESPHome 2026.9.0 pass: API 0xc8eb5eec, MQTT 0x152aa56c. Inputs use synthetic credentials, local replacement fonts and a public sample background; no live service, device, NAS or build server is contacted.
• YAML, original line endings and whitespace checks pass. Tests and compilation do not prove physical panel or network behavior. Recovery bounds end at the sleep action; native shutdown hooks remain active.

Merge Danger

Door: two-way. Revert this contribution through a PR before reverting prerequisites. A source revert does not deploy firmware.

Blast Radius: firmware. Affects users who later adopt these packages. No deployment is included. Keep core and transport from the same revision and wait for the accepted Maintenance status before OTA.

AI assistance: Codex prepared and validated this isolated contribution. Upstream review is requested; local tests do not constitute maintainer approval.

[JGAguado]

Good design: battery-gated admission, an acknowledgement only after an observed panel refresh, a bounded watchdog, and the latest request wins. This restores a practical OTA path that the single-cycle sleep removed. Approving.

Note: it overlaps with #31 in smart_plant_core.yaml and tests/display_automation.py, so please merge #31 first and rebase this one onto it. Native-API users still have no Maintenance window, so a short line in the programming guide pointing OTA users to the MQTT profile would help.