SAFETY-18: a meter frozen at a wrong-but-fresh value now raises an alarm

A meter that answers 200 OK with a stale document forever is ARRIVING on every
poll, so every freshness mechanism in the stack reads it as healthy while the
loop integrates a constant error and rails: 360/135/75 s at the live install's
max_w: 5000 for a meter frozen at 350/1000/>=3000 W. Fifteen minutes of a 5 kW
unattended import sets the month's billed capaciteitstarief peak.

The detector is a conjunction, not the bare unchanged_s threshold TEL-05
measured and rejected:

    unchanged_s >= meter_freeze_s   AND   |command| within 5 % of max_w

Both terms already existed and were already on the status page, and they fail
for independent reasons: at the converged point the command is nowhere near the
rail, and at the rail against a real load the kWh registers move in seconds. At
the shipped 300 s the relation is structural rather than a margin - the slowest
a healthy 1 Wh register can tick and still look unchanged is 12 W, which is
inside the 15 W deadband, so the command there is parked at 0 W.

Notification only, deliberately: an HA persistent notification with a fixed
notification_id, an ERROR log line, a UI event and a red status row. No claim,
no latch, no 0 W. A false trip parks the battery; a false notification costs an
alert. Only meter_source: homewizard_local is covered - the status page says
NOT COVERED elsewhere rather than pretending the guard is armed.

DOCS.md states the capacity-tariff exposure this does NOT close: peak_cap_w caps
maintenance charging and nothing caps the loop. That cap is SAFETY-07.

test_freeze.py grades both directions and was verified by breaking what it
watches (six mutations, all red): silent over the committed 40-minute converged
capture, silent over an hour of TEL-05's low-power case where the rejected bare
threshold is shown to fire, alarming on a genuinely frozen meter driven over
real HTTP through the real HomeWizardLocalSource (the rig's own hwsim freeze
fault when reachable), silent on the same railed command against a meter that is
still moving, and asserting on the service call that leaves Controller.cycle()
rather than on the watchdog's own flag.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015VXjA3LWccN1rJsk3okyPC

goodwe_controller/DOCS.md

@@ -30,6 +30,10 @@ The inverter **holds its last command forever** — it has no meter-timeout. So:
 - The **optional RS485 e-stop** is the only thing that covers this machine
   dying. Without it, a failed host leaves the battery latched at its last
   command until someone intervenes.
+- This add-on **raises an alarm — and nothing more —** when the meter keeps
+  answering with a reading that never changes while the command sits at the
+  rail. See "The frozen-meter alarm" and, before you rely on it, "Capacity-tariff
+  exposure of the grid-following loop".
 
 **If anything looks wrong: stop the add-on.** That commands 0 W and the
 hardware holds it there.
@@ -433,6 +437,95 @@ under `peak_cap_w`, and if the forecast goes over the cap the charge-only clamp
 is dropped so the battery can shave the peak instead. Money outranks the
 maintenance schedule.
 
+#### Capacity-tariff exposure of the grid-following loop
+
+⚠️ **`peak_cap_w` caps MAINTENANCE charging. It does not cap the loop.** The
+grid-following loop is bounded by `max_w` and by the device rating, and by
+nothing else. That is deliberate — the loop exists to *reduce* what crosses the
+meter, so under every healthy condition it lowers the peak rather than raising
+it — but it means one thing is true and worth writing down:
+
+**If the meter lies, the loop will happily buy `max_w` from the grid for as long
+as the lie lasts, and no cap in this add-on stops it.** A meter frozen at a large
+export reads as "the house is exporting hard", the loop charges the battery to
+correct it, and the correction is a grid import. At the schema maximum
+`max_w: 5000` — which is what this house runs, and is also the device rating —
+that is a 5 kW unattended import.
+
+The bill is not the energy. In the Belgian capaciteitstarief the month is billed
+on its highest quarter-hour average, so **fifteen minutes of this sets the whole
+month's peak.** A measured case: one 4998 W quarter moved a monthly peak from
+4832 W to 5013 W, and every day of that month was billed at the higher figure.
+
+What exists today, and what does not:
+
+| | |
+|---|---|
+| `max_w` bounds the magnitude | ✅ — but the exposure IS the magnitude |
+| Maintenance charging capped under `peak_cap_w` | ✅ |
+| **Loop capped under `peak_cap_w`** | ❌ — not built. This is SAFETY-07 |
+| Frozen meter detected | ✅ on `homewizard_local` only, **alarm only** |
+| Frozen meter *stopped* | ❌ — the alarm does not command anything |
+| SoC guard on the loop | ❌ — the BMS is the only energy backstop |
+
+So the frozen-meter alarm below **narrows the window; it does not close it.** On
+a capacity-tariff site where an unattended runaway is unacceptable, the mitigation
+today is operational: set `max_w` no higher than the loop actually needs (the
+tuning was measured at 2000 W and a 1.78 kW load step is tracked fine there), fit
+the e-stop, and watch for the alarm.
+
+### The frozen-meter alarm
+
+A meter that has died is easy — it stops answering, the sample age climbs past
+`meter_max_age_s`, the reading becomes missing, and the add-on and the ESP32 both
+command 0 W. A meter that keeps answering `200 OK` with a document that never
+changes is the hard one: **every freshness mechanism in the stack reads it as
+healthy**, because it really is arriving on every poll. The loop then integrates
+a constant error and winds to the rail, in 75–360 s at `max_w: 5000`.
+
+The add-on alarms when **both** of these are true at once:
+
+- the meter's own document (power figure *and* both kWh registers) has not
+  changed for `meter_freeze_s` — 300 s by default; **and**
+- the command standing on the wire is at the rail, within 5 % of `max_w`.
+
+Neither half is usable alone. A bare "unchanged for N seconds" rule false-trips
+at the exact operating point this controller aims for — at a converged −10 W a
+1 Wh register legitimately takes about six minutes to move — and a bare "at the
+rail" rule fires on any genuinely large load. Together they are safe in both
+directions, because a real railed condition means kilowatts still crossing the
+meter, and a kilowatt advances a 1 Wh register every 3.6 s.
+
+**It is an alarm and nothing else.** It does not command 0 W, does not latch, and
+does not claim the actuator. A false trip here parks the battery; a false
+notification costs an alert. Turning it into a trip is a separate decision that
+needs data from a real install — and an answer to "what should the loop do
+instead", given that 0 W is itself an import of whatever the house is drawing.
+
+When it fires you get a Home Assistant persistent notification
+(`goodwe_meter_frozen`, replaced rather than stacked on a repeat), an `ERROR` in
+the add-on log, an entry in the UI's event list, and a red banner on the status
+page. **The loop keeps running.** If the meter really is stuck, stop control from
+the add-on UI.
+
+⚠️ **Only `meter_source: homewizard_local` is covered.** It is the only transport
+that reads the meter's own document; on `ha_dsmr`, `mqtt_p1`, `ha_signed` and
+`off` there is no signal to threshold and the status page says **NOT COVERED**
+rather than pretending the guard is armed.
+
+| option | default | meaning |
+|---|---|---|
+| `meter_freeze_s` | 300 | Seconds of an unchanged measurement, *while the command is at the rail*, before the alarm |
+
+Why 300 s: over 2399 s of this house at the converged operating point (mean grid
+−14.2 W, 1194 polls, 735 of them repeating the previous reading) the largest
+`unchanged_s` any sample sees is **8.0 s**, and the longest interval serving no
+distinct reading at all is **15.4 s**. There is also a structural reason not to
+lower it much: at 300 s the slowest a *healthy* register can tick and still look
+unchanged is 12 W, which is inside the 15 W deadband — so the command there is
+parked at 0 W and the two halves of the rule cannot both be true. At the schema
+floor of 60 s that figure is 60 W and only the margin is left.
+
 ### Site
 
 | option | meaning |