goodwe-addon/goodwe_controller/DECISIONS/SAFETY-61-control-task-death.md

SAFETY-61 — the control task's death ends the process

0. The defect

amain() started run_control() as a bare task and waited on stop. Nothing watched the task. An uncaught exception in read_inputs(), cycle() or publish() ended the task silently, and stop was never set. The web UI, P1 and tariff tasks kept running, and the Supervisor saw a healthy container. The traceback appeared only at shutdown. The ESP32's layer-1 veto zeroed the inverter about 30 s later, so the hardware was safe. The pack then sat at 0 W indefinitely while the add-on showed green.

test_control_task.py reproduces this on the pre-fix tree. The child process reaches its 40 s deadline, has written no 0 W, and has logged nothing.

1. Decision: exit with status 70 after the ordinary wind-down

A done-callback on the control task (control_task_done()) handles the death. It logs the traceback at CRITICAL at the moment of death, then sets stop. amain() then runs the same wind-down that SIGTERM runs (shutdown() → command_site_zero(), then cancel, then clean up). After that it raises ControlTaskDied, and main() turns that into SystemExit(70) (sysexits EX_SOFTWARE). A normal stop and run_control()'s own refusal path both set stop before the task ends, so the callback ignores them. The refusal still exits with 78.

Why not restart the loop in the same process:

• cycle() writes controller state before its awaits: cycle_at, peak_guard, allocation, then target/reason, then the writes. An exception between those steps leaves the controller half-updated. A loop restarted in the same process would continue from a state that no boot ever produces. A process restart rebuilds the controller from the Store, which is the path every boot already runs.
• An unbounded retry is the invisible spin the card forbids. A bounded retry would reimplement the Supervisor watchdog's own throttle: 10 restarts per 30 min, and 5 attempts with backoff (apps/const.py).

2. What happens after the exit, verified rather than assumed

• Exit status reaches Docker. The add-on image (s6-overlay, init: false, CMD /run.sh) was run with exec python3 -c 'raise SystemExit(70)'. docker inspect gave ExitCode 70. The same test with exit 0 gave 0, and an uncaught exception gave 1.
• Supervisor 2026.08.0 (ghcr.io/home-assistant/amd64-hassio-supervisor, source read from the image):
  • A non-zero container exit is recorded as ContainerState.FAILED (docker/monitor.py). The Supervisor logs "App … exited with non-zero exit code 70" at ERROR (apps/app.py container_state_changed).
  • The Supervisor restarts the add-on only if the per-install Watchdog toggle is on. watchdog_container() returns when not self.watchdog. The toggle defaults to off (apps/validate.py: vol.Optional(ATTR_WATCHDOG, default=False)).
  • Add-on containers get no Docker restart policy. The only restart_policy= in the Supervisor belongs to the observer.
  • boot: auto in config.yaml only controls starting at host boot. The watchdog: key in config.yaml is a health-check URL, not a restart policy, and this add-on does not set it.
• So on a default install the add-on stays stopped after this exit. The UI shows it as stopped, its log holds the traceback, and the Supervisor log holds an ERROR line. The pack is at 0 W, which is the same physical state as before this card. The difference is that 0 W is written immediately instead of after the ~30 s veto, and the add-on no longer shows green. With the Watchdog toggle on, the Supervisor restarts the add-on.
• Not verified: an actual restart by a running Supervisor. That would need a live Supervisor, and the only one available is the live house.

3. Left open for the owner

• Whether DOCS.md should tell installers to enable Watchdog. DOCS.md is not this card's file.
• Setting the Watchdog toggle from inside the add-on (/addons/self/options) was rejected here, because it would change a user setting without the user knowing.

4. Scope: the siblings, and why they are not supervised

• run_tariff_refresh() and the P1 HTTP and HA transports already catch Exception inside their loops by design, and the values they feed are age-bounded downstream.
• The P1 MQTT source returns on purpose when it is misconfigured. Making every long-lived task's end exit the process would turn that deliberate fail-safe into a restart loop.
• Only the control task is supervised.

5. hass.py: an undecodable body is an absence

A non-JSON 200 served as text/html was already treated as an absence, because aiohttp's ContentTypeError is a ClientError. The reads that actually escaped were these three:

• a malformed body labelled application/json, which raises JSONDecodeError (a ValueError);
• a JSON body that is not an object, which raises AttributeError in number() and limits();
• an undecodable error body in call(), which raises UnicodeDecodeError.

All three were measured against aiohttp 3.13.5. The first two now read as None, and the third is now a failed write (False).

6. Status row

checks() now starts with a control loop row showing how long ago the loop last completed a pass. The row turns red once that age exceeds FIRMWARE_INGEST_VETO_S. The heartbeat is sent from this loop, so past that age layer 1 has zeroed the inverter.