Merge release/1.0 into safety-78-drain-at-two

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

goodwe_controller/DECISIONS/MAINT-05-per-pack-maintenance.md

@@ -285,32 +285,11 @@ cross-inverter `lo > hi` contradiction at `arbiter.py:114`. The only line this
 card changed there is **which** roster entry the claim is filed on: the one whose
 state machine produced the result, rather than `inverters[0]`.
 
-## 6. FOUND AND NOT FIXED: the site loop still contradicts a drain at N>=2
+## 6. FIXED BY SAFETY-78: the site loop contradicted a drain at N>=2
 
-Measured while wiring this card, and **pre-existing on `release/1.0` at
-`2d025ee`** — the same drain filed on `inverters[0]` produces the identical
-refusal with the two unit names swapped.
-
-The maintenance SET **pins** its pack. The loop's target is a **site** claim.
-When the site target is *below* the pin — a 2000 W drain while the house imports
-less than that, which is most of a night — the only split that sums to the site
-target asks the sibling to **charge** while the maintained pack **discharges**,
-and `allocator.plan()` refuses it by name as circulating power. The refusal is
-correct and fails safe: the whole site goes to 0 W with an `ARBITER: REFUSED`
-line in the action log.
-
-**The consequence an operator would see is a misdiagnosis.** The pack is held at
-0 W while its state machine believes it is draining, so after 12 h the DRAIN
-timeout fires and reports *"drain stuck"* — §12's words for a battery that is not
-following commands. The battery is fine; the site refused to allocate.
-
-**Why it is not fixed here.** The fix is to change what the site loop's target
-*means* while a unit is pinned — regulate the meter using only the unpinned
-packs — which is loop and allocator territory and changes the integrator's
-subject. MAINT-05 moves which pack is pinned and nothing else about it. It is
-pinned as a running check (`test_maintenance.py` part 12) rather than left as a
-comment, so it cannot be forgotten or quietly tuned away, and it wants a card of
-its own.
+Found here and pre-existing: below the pin the other pack had to charge, the
+allocator refused it and the site sat at 0 W. Fixed by a site `drain` floor;
+see [[SAFETY-78]] (`DECISIONS/SAFETY-78-drain-at-two.md`).
 
 ## 7. FOUND AND NOT FIXED: `migrate_unit_keys()` has the same hole, and it is a LATCH
 

goodwe_controller/DECISIONS/OPT-11-battery-modes.md

@@ -29,4 +29,49 @@ P1 is its section 6 P1, and the pull request lists what was measured.
   page's English names, pinned by a test, and are not renamed with the page:
   automations send them.
 - In P1 only Off closes a direction; Leftover solar differs by charging last.
-  Price runs, selling (`pack_sell`, reserved) and the forecast are P3/P4.
+- P3 (price runs, `priceruns.py`, `modetrade.py`): each battery's range is
+  narrowed by its role this tick (hold, give, charge, rest, sell); main.py
+  files the intersection with the switch, so it still holds 0 W. With modes on
+  the site trade is filed by the modes, sized from the loop bound (so no
+  battery a mode or a refusal holds is asked for watts, P1's unmet share) and
+  the guard's headroom; `arbitrage.decide()` runs only with modes off, which
+  stays byte-identical to 7a00f12 (`test_modes_p3.py` part 1).
+- SAFETY-46 item 2 is decided as the owner answered (2026-09-25): a trade is
+  a run of consecutive firm slots. It applies with battery modes on; the
+  modes-off trade keeps its one-period shape, because that path must not move.
+- Choices that were measured, not assumed (tools/opt11p3_replay.py):
+  - a sale needs the guard to have measured the quarter, not to be clear: a
+    5 kW discharge alone reads "engaged" on export and flipped the sale every
+    5 s;
+  - a grid charge makes the others rest, so it starts only at 500 W and, once
+    the guard or the headroom stops it, stays off for that 15-minute period
+    (without: 13 flips in 4 minutes under a 3.5 kW house);
+  - stored energy is valued at the last cheap run for 12 h, and a charge
+    needs its own run to clear the spread (without: a night charge was spent
+    on flat morning prices, then charging went on at them);
+  - a run edge reseeds the loop at the house's level (a 3 kW import spike
+    removed; about 0.1 x rating still overshoots as export).
+- Replay (tools/opt11p3_replay.py, 16 recorded days, EPEX hourly prices a
+  year earlier, modelled batteries), net EUR, lower is better: P2 19.33, P3
+  Solar first + Leftover solar 19.57, with a sale 19.60, the old one-period
+  trade 18.14. Review of #153 (same model, with a per-action split):
+  - the cheapest hours were at midday on 15 of 16 days, so Leftover solar (acting
+    as Cheap hours until P4) bought 12.2 kWh there that the sun would have
+    given: 7 kWh more exported, 12 kWh less solar stored. Holding for the
+    expensive hours saved 4 kWh of import, not enough. With no grid charge on
+    Leftover solar: 19.44;
+  - the old trade charged one hour, so the afternoon sun still fit;
+  - a sale earned the wholesale price (2.27 EUR for 11.4 kWh) and the house
+    then bought the same energy back (2.29 EUR): a wash before wear. It pays
+    only when the sale hour's wholesale price beats the later import price,
+    levies included (about 0.13 EUR/kWh above that hour's wholesale here);
+  - valuing the charge left at the end, wear and real Flemish levies make
+    selling worse and do not change the order.
+- Owner decision 2026-09-29 (option A): selling is off until it can be judged
+  on the price the grid pays (`packmode.SELLING_ENABLED`, code kept), and
+  Leftover solar takes solar only until P4's forecast
+  (`packmode.GRID_CHARGE_MODES`); Cheap hours only still charges from the grid. Replayed
+  (16 days, as above): Solar first + Leftover solar 19.44 EUR net against
+  P2's 19.33; Solar first + Cheap hours only 19.57.
+- Not done in P3: the forecast (P4), and a headroom too short for the run
+  moving the rest to the next cheap periods.

goodwe_controller/DECISIONS/SAFETY-78-drain-at-two.md

@@ -0,0 +1,44 @@
+# SAFETY-78 - a maintenance drain at two inverters
+
+**Status: DECIDED 2026-09-29.** Fixes MAINT-05 §6 (OPT-11 P1 F1, UX-13 P3
+check 5, OPT-11 P3 F4). Tests: `test_safety78.py`.
+
+**The defect.** At N>=2 the drain pins its pack (a unit SET at
+`P_MAINTENANCE`) and the site target is split around the pin. Whenever the
+site target was below the pin, the other pack had to charge. The allocator
+refuses opposite directions (SAFETY-25 §0a, SAFETY-31), so the site went to
+0 W and logged `ARBITER: REFUSED` every cycle. That covers a house below the
+drain rate, a grid-charge trade, and a house above it too: after a refusal the
+loop restarts from 0 W and its 400 W slew step is below the pin again.
+
+**The fix.** While a pack drains at N>=2, main.py files a site limit
+`drain`, `lo` = what the pin really places (`allocator.pin_w()`: the drain
+rate inside that pack's own hard limits), at `P_MAINTENANCE`. So the site
+target is never below the pin and the other pack only adds power in the same
+direction. Opposite splits stay forbidden.
+
+- The order is the arbiter's own: a safety SET (100) outranks the limit and
+  the pin, so everything parks; the peak floor (50) and the drain floor are
+  both applied, so the higher wins; a trade or the loop below the drain is
+  lifted to it.
+- Below the drain rate the drained pack exports the rest, as the drain does at
+  N=1 (`maintenance.py`: "forced discharge, exports the surplus"). Holding it
+  to the house load would make N=2 drain differently from N=1; that is an
+  owner question, not this fix.
+- A draining pack that can place nothing (a refusal, a stale link) adds no
+  floor, and the wait is logged once per episode.
+- With battery modes on, no pack is a grid charger while another drains
+  (`modetrade.decide(draining=)`, why `cycle`), and the other battery's card
+  says why (`other_cycle`). Not while the drain waits: no floor is filed
+  then, so the other battery may charge from solar.
+- Not filed at N=1, where the drain is the site SET itself: byte-identical
+  (`tools/safety78_identity.py`, which hashes the claims too).
+
+**Not changed (measured in the PR #154 review, follow-ups).**
+- At N=1 a drain (60) outranks the peak floor (50), so the guard does not add
+  to it: a 5000 W house imports 3000 W against a 2500 W limit, a 6000 W house
+  4000 W. Pre-existing, kept by the N=1 identity.
+- At N=2 a maintenance CHARGE in a cheap window has the same stall: the
+  charging pack's `hi = -floor` against the loop asking the other to give is
+  refused on 141 of 261 cycles. The mirror fix is a site `hi`, which can meet
+  the peak floor's `lo` (0 W), so it is not this card.

goodwe_controller/DECISIONS/SAFETY-79-peak-margin.md

@@ -0,0 +1,41 @@
+# SAFETY-79 — the peak guard keeps a margin below the peak limit
+
+**Status: DECIDED 2026-09-28 (owner decision).**
+
+## Decision
+
+The peak guard aims `peak_margin_w` under the limit it holds: under
+`peak_cap_w`, or under a month peak already banked above it
+(`quarter_target_w()`). `peak_margin_w` is a setting: default 50 W, range
+0-500 W, whole watts. An install without the key gets 50.
+
+**Why (owner):** the guard aimed exactly at the cap, and in the OPT-11 P1 test
+a quarter banked 3501.9 W against a 3500 W limit (OPT-11-P1-test-report.md,
+check 4). A peak even 1 W over still sets the billed peak. It is a setting and
+not a constant because the add-on is sold to several sites.
+
+**Banked peak (review, 2026-09-29):** the PR first aimed at a banked month
+peak as it stood. That can bank a few W over it, which raises the bill the
+same way; and a peak banked between cap - margin and the cap (common in the
+month an install upgrades, since the old guard held quarters at the cap) was
+aimed at exactly, so one overshoot went over the cap. The margin now applies
+under it too. Cost: up to `peak_margin_w` of a peak already paid for goes
+unused (more discharge, less charge headroom); no bill cost. Undo is one line
+in `quarter_target_w()`.
+
+## What uses which number
+
+- **the aim:** `peakguard.decide()` (the claim's floor, and so arbitrage's
+  `charge_headroom_w()` and OPT-11's give-way, which read it), and, as cap -
+  margin, `shaping_suspended()` and `maintenance_charge_floor()` (the forecast
+  checks, via `Controller.peak_aim_w()`).
+- **the real cap (reporting and billing):** `PeakTracker` (month peak,
+  headroom, 80 % warning), the decision's `ceiling_w` and every notice and
+  status row built from it, Home's limit, and `validate.config_notes()`.
+
+## Checks
+
+`peak_margin_w: 0` is byte-identical to ed739d4 (test_peak_margin.py part 1,
+digests from tools/safety79_identity.py, which also runs a maintenance charge
+with a forecast). validate.py rule 12 refuses a value outside 0-500, not
+whole, or not below `peak_cap_w`.

goodwe_controller/DECISIONS/SAFETY-81-load-too-high.md

@@ -0,0 +1,63 @@
+# SAFETY-81 — no false "Load too high for battery" alarms
+
+**Status: 2026-09-29, owner go for the card. Review kept the 10 W tolerance
+as a constant and added the 10 s hold.**
+
+## Defect
+
+The SAFETY-79 test (SAFETY-79-test-report.md, F1/F2) saw 6 false alarms in 7.
+The alarm fired whenever `decide()` clamped its floor to the rating
+(`saturated`). Three things set that while the quarter landed on target:
+
+- **Double count.** `decide()` sizes from the held meter reading plus the
+  battery reading. When the meter sample predates the battery's last increase,
+  the increase is counted twice. It happens under noise, and at each quarter
+  start, where the battery is back while the held sample is still the spike.
+- **The aim, not the cap.** `saturated` is graded against cap − margin, so at
+  margin 50 noise needs 50 W less to trip it (F2).
+- **Last seconds.** The gain 900 / remaining turns a few W over the aim into
+  thousands of W wanted, with the battery far from its rating.
+
+## Decision
+
+The alarm needs `saturated` and `peakguard.load_too_high()`: with the battery
+at full power from now on, the quarter still ends more than `ALARM_MISS_W`
+(10 W) over the real limit (`ceiling_w`). That is the miss itself, without the
+gain. The battery reading it uses is the lower of this cycle's and the last
+one's. It must hold for `ALARM_HOLD_S` (10 s). At most one notification per
+quarter, because near the threshold the test flickers with the meter; the
+ERROR log line is written for every episode.
+
+**Why 10 W:** at margin 0 the guard itself lands up to +5.7 W over (SAFETY-79
+test, check 5), and those misses are real but tiny; the alarm would fire in
+the last second of most guarded quarters. The margin (default 50) is the fix
+for them. Cost: a real miss of 10 W or less is not alarmed; at a capacity
+tariff of the order of EUR 50 per kW a year, 10 W in one month is cents.
+Review measured +13 W on a 10 kW two-unit site at margin 0, not saturated, so
+no alarm: the tolerance only matters when the battery is at its rating. A
+constant, not an option: `peak_margin_w` is the owner's knob.
+
+**Why the hold (review):** the test assumes the load now lasts the rest of
+the quarter. A load over cap + battery for ~5 s every 30 s (`sine4500_fast`,
+a cycling hob or heater) alarmed at each quarter start while the quarter
+landed under the aim. The hold stops that.
+
+**Cost:** a real alarm comes 10-12 s later than on 5a4cdc2 (`step6500` at
+1211 s, not 1201 s); a slow ramp 20 s later (`ramp6500`), as it waits for the
+real cap. While the battery refuses or its reading is lost, the alarm waits
+until the quarter is lost even at full battery (27-60 s later in review runs);
+those faults have their own alarms. A load over cap + battery for more than
+10 s still alarms even if the quarter later lands under. `ALARM_HOLD_S = 0`
+removes the hold.
+
+## Not changed: the 1 s spike itself
+
+The cycle after a quarter boundary and before the new quarter's first meter
+sample still sees 0 s left, files no claim, and an Off battery drops to 0 W for
+one cycle. That is the same edge tick as OPT-15 F1, so it is left to OPT-15.
+Control is unchanged here: every command in `tools/safety81_sim.py` is
+byte-identical to 5a4cdc2 (test_safety81.py part 1).
+
+The double count also moves control, not only the alarm: on a late sample the
+guard asks for the full rating for one cycle (edge4600 at 902 s: 2000 W where
+1150 W holds the aim). Left to a follow-up card.

goodwe_controller/DOCS.md

@@ -204,6 +204,7 @@ The label and description each setting shows on the Configuration tab, in tab or
 | Limits | Inverter rating (W) | `max_w` | Your own number: the most power the add-on may ever ask of the inverter. Start low and raise it after commissioning. |
 | Limits | Battery cut-out level (%) | `bms_soc_floor` | The level where the battery's own management system stops giving power. Read it off your battery rather than copying a figure. |
 | Limits | Peak limit (W) | `peak_cap_w` | Your own number: the 15-minute average power the add-on keeps the grid under. Take it from your grid contract. |
+| Limits | Margin below the peak limit (W) | `peak_margin_w` | The add-on aims this much below the peak limit, so a 15-minute period that ends a little high still stays under it. |
 | Limits | 15-minute demand forecast entity (W) | `peak_forecast_entity` | Optional. A forecast of this 15-minute period's average power. Leave it empty and there is no peak limit. |
 | Limits | Peak reserve (%) | `peak_soc_floor` | Peak limiting will not draw the battery below this level, but ordinary use can. Derived value, leave it unchanged. |
 | Tariff | Dynamic price source | `price_provider` | Where prices come from. Choosing a source starts the price fetch, even with trading off. |
@@ -274,6 +275,7 @@ When the add-on refuses to start, each reason names the setting by its label and
 - **Inverter rating** (`max_w`): your own number, not a derived one. It is not read when the inverter list is filled in, since each entry carries its own and the site limit is their sum. Several safety thresholds must stay below it, and the add-on refuses to start if one does not.
 - **Battery cut-out level** (`bms_soc_floor`, `inverters.bms_soc_floor`): measured, not chosen. Register 0x0560 reads 10 % on the reference GW5000S-BP. It exists so the add-on can refuse a “Peak reserve” at or below it, which could never take effect. Each inverter entry states its own, because one default for two different batteries protects the shallower one with the deeper one's number.
 - **Peak limit** (`peak_cap_w`): your own number, from your grid contract. In Belgium it is the capacity-tariff peak your distribution charge is billed on.
+- **Margin below the peak limit** (`peak_margin_w`): 50 W by default, 0 to 500 W (SAFETY-79). Peak limiting aims at the peak limit minus this margin, because a 15-minute period aimed exactly at the limit can end a watt or two over it (3501.9 W against 3500 W in a test), and even 1 W over sets the billed peak. Once this month's peak is already above the limit, it aims the same margin below that peak. The bill, this month's peak and the warnings still compare against the peak limit itself. 0 aims at the limit, as before.
 - **Peak reserve** (`peak_soc_floor`): derived, not picked (SAFETY-24). The reference battery holds 13.8 kWh usable and the worst modelled peak day asks for 878 Wh, or 6.4 %. 20 % sits ten points above the cut-out level and leaves about 1.6 worst days of room. It bounds peak limiting only: ordinary use goes on down to the cut-out level. It must stay above “Battery cut-out level”.
 - **Dynamic price source** (`price_provider`): selecting a provider is what starts the fetch, every half hour, whether or not trading is on. It may not be combined with the two older price entities. engie_dynamic, totalenergies_dynamic and eneco_eddy are withdrawn and refuse to start: their endpoints never existed. They stay in the list only so such a site gets that explanation.
 - **Supplier markup** (`price_markup_eur_kwh`): under manual_csv, whose prices are all in, it is ignored and logged as ignored.
@@ -518,9 +520,27 @@ below.
 Off by default. Turn it on, restart the add-on, and the Batteries screen (and Settings, Simple) gives each battery two controls. They apply at once, with no restart.
 
 - **On or off.** Off asks the battery for 0 W and starts no monthly cycle on it. A cycle that is running stops, and the add-on log says so. The peak limit may still use it, but only for what the other batteries cannot cover.
-- **Mode.** *Solar first* charges from spare solar before the other batteries. *Leftover solar* charges from the solar they cannot take. Both cover the house at any hour. Charging from the grid in cheap hours, and selling, come in a later update.
+- **Mode.**
+  - *Solar first* charges from spare solar before the other batteries and covers the house at any hour. It never charges from the grid and never sells.
+  - *Leftover solar* charges from the solar the others cannot take, never from the grid (until the solar forecast arrives). It saves its power for the expensive hours and covers the house then.
+  - *Cheap hours only* charges from the grid in the cheapest hours, saves its power for the expensive hours and covers the house then.
+- **Selling** is off until it can be judged on the price the grid pays (owner decision 2026-09-29, option A).
 
-The peak limit, the safety stops and the monthly cycle always come before a battery's mode.
+With battery modes on, these choices replace the *Charging and selling on price* switch (`arbitrage_enabled`); that switch is only read with modes off.
+
+**Cheap and expensive hours.** They come from the published day-ahead prices, as runs of consecutive 15-minute periods, not a single period.
+- The cheap run is the cheapest stretch long enough to fill the batteries that may charge, at their power.
+- An expensive hour costs at least *Battery cycle cost* (`cycle_cost_threshold_eur`, widened as for trading) more than the cheap run. The batteries hold their power until then.
+- The sale uses the most expensive stretch inside those hours, and never a period below 0.
+- A carried (not yet published) price is never used. A run that has started runs to its end.
+- With no prices, or too small a gap, every battery follows the house.
+
+**What always comes first.**
+- The peak limit, the safety stops and the monthly cycle come before a battery's mode.
+- A grid charge is sized so the 15-minute period stays under the peak limit less its margin (`peak_margin_w`). It starts only at 500 W or more. Once the peak limit stops it, it stays off for the rest of that 15-minute period.
+- While one battery charges from the grid, the others rest, and the house uses the grid.
+- While one battery empties for its monthly cycle, no battery charges from the grid.
+- A battery that refuses to charge or give power takes no part in a run in that direction.
 
 **In Home Assistant.** With MQTT set up, each battery also gets a *Mode* list and a *Use* switch, for example `select.goodwe_inverter_a_mode` and `switch.goodwe_inverter_a_use`. They do the same as the Batteries screen. Turn battery modes off and restart, and they are removed.
 
@@ -528,6 +548,8 @@ The peak limit, the safety stops and the monthly cycle always come before a batt
 
 *For installers:* a mode is a limit at priority 35, kept apart from the hard limits. It gives way only as far as a limit above it (the peak guard) needs. A mode range always holds 0 W, so a mode can forbid a direction and never force one. With one inverter the mode also bounds the loop. The record is `DECISIONS/OPT-11-battery-modes.md`.
 
+*For installers:* when a charge or sale ends, the loop restarts at the house's own level rather than at the trade's watts. On the replay model that removes a ~3 kW import spike after a 2.5 kW charge and halves the settling time; about 0.1 × the battery's power still overshoots as export. The *Mode* list gains *Cheap hours only* in Home Assistant, at the end.
+
 ### Reading the grid-following loop: `Loop integrator`, `Loop integrator lead`, `Loop reason`
 
 The control law is a bounded integrator: an accumulator that is **not** the
@@ -1616,6 +1638,7 @@ help - see "Why the tuning is what it is".
 |---|---|
 | `peak_forecast_entity` | Quarter-hour demand forecast, for capacity-tariff markets. Empty = no cap |
 | `peak_cap_w` | The site's capacity-tariff target |
+| `peak_margin_w` (50) | Watts the peak guard aims under `peak_cap_w` (SAFETY-79). Reports and the bill use `peak_cap_w` itself |
 | `peak_soc_floor` (20) | **The percent below which the capacity-peak guard will not discharge the battery.** ⚠️ It bounds **the peak guard only** — it is **not a pack-wide reserve**, and ordinary self-consumption discharges straight past it (SAFETY-25, see below). Not optional and not the same thing as `maintenance_soc_floor` |
 | `bms_soc_floor` (10) | The pack's **own** cut-out percent, the number the BMS enforces whatever you set above. `peak_soc_floor` must be **strictly above** it or the add-on refuses to start. ⚠️ **At a declared `inverters:` roster this key moves INTO each entry and is REQUIRED there** (SAFETY-32): it describes a battery, and two packs of different models have different cut-outs, so one number for both protects the shallower pack with the deeper pack's BMS. Nothing is inherited — an entry that omits it is refused **by name** at startup, and the flat key below is then not read at all |
 | `price_now_entity`, `price_avg_entity` | Dynamic tariff. Empty = never force a paid grid top-up |
@@ -1625,6 +1648,10 @@ 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.
 
+With two or more batteries, the one being emptied gives its drain rate and the
+others only add power when the house needs more; none charges while it drains
+(SAFETY-78). Below the drain rate the rest is exported, as with one battery.
+
 #### Capacity-tariff exposure of the grid-following loop
 
 ⚠️ **This section described the exposure BEFORE SAFETY-07. The loop is now
@@ -1717,7 +1744,8 @@ control action and goes to the action log and the status page. A *saturated*
 guard — asking for everything the inverter has while the quarter is still
 projected over — raises one notification (`goodwe_peak_saturated`), because that
 is the one state where the money will be spent and shedding load is the only
-thing left that changes the bill.
+thing left that changes the bill. SAFETY-81 keeps a 1 s meter spike, noise and
+a quarter's last seconds from raising it: see `peakguard.load_too_high()`.
 
 **And it sizes a price-driven charge, not only a forced discharge (SAFETY-45).**
 The same arithmetic read the other way answers *"how hard may this site charge
@@ -3189,9 +3217,12 @@ reason code `OUTPUT_CLAMP`.
 **Load too high for battery.** The capacity-peak guard (SAFETY-07) asks for
 everything the inverter can discharge and the running 15-minute average is
 still projected over the peak limit, so the month's billed peak
-(capaciteitstarief) goes up. In shadow mode the guard's projection is made on a
-plant that did not respond (SAFETY-47), and the text says so. See *The
-capacity-peak guard*.
+(capaciteitstarief) goes up. It fires only when, for 10 s, the period would
+still end more than 10 W over the real limit (not the margin's aim) with the
+battery at full power. It notifies at most once per period; later overloads
+in the same period go to the log (SAFETY-81). In shadow mode the
+guard's projection is made on a plant that did not respond (SAFETY-47), and
+the text says so. See *The capacity-peak guard*.
 
 **Battery stopped limiting the peak.** The peak guard may not discharge below
 `peak_soc_floor` (label “Peak reserve”, SAFETY-24). It also stops when the
@@ -3260,9 +3291,8 @@ The **Batteries** tab has a card per battery: its level, and three lines.
 **Now** says what it does, **Today** lists the blocks planned for it (price
 trades, the monthly cycle, the peak limit), and **Why** says the reason. With
 battery modes on, each card also has the On/Off switch and the mode list; both
-apply at once. Charging in cheap hours and selling are greyed out until a later
-update, and Today reads "Not planned yet" when nothing is planned for the
-battery.
+apply at once. Today reads "Not planned yet" until the add-on has made the
+day's price runs.
 
 An Off battery that the peak limit still needs says so, with the power it
 gives: "Off, but gives 0.5 kW for the peak limit."

goodwe_controller/app/allocator.py

@@ -344,6 +344,16 @@ class _Narrowed:
         self.lo, self.hi = lo, hi
 
 
+def pin_w(b):
+    """The watts a unit's own SET places once held inside its hard limits,
+    as `plan()` places a standing pin, or None when the unit has no SET."""
+    pv = getattr(b, "pinned_w", None)
+    if getattr(b, "gate", None) is None or pv is None:
+        return None
+    lo, hi = _int_envelope(b)
+    return float(pv) if lo > hi else float(_clamp_int(round(float(pv)), lo, hi))
+
+
 def loop_bound(bounds, live=None):
     """OPT-11. `(lo, hi)`: what the units can place when the LOOP decides.
 
@@ -364,11 +374,8 @@ def loop_bound(bounds, live=None):
             continue
         if getattr(b, "contradiction", False):
             continue
-        pv = getattr(b, "pinned_w", None)
-        if getattr(b, "gate", None) is not None and pv is not None:
-            lo, hi = _int_envelope(b)
-            p = float(pv) if lo > hi else float(_clamp_int(round(float(pv)),
-                                                            lo, hi))
+        p = pin_w(b)
+        if p is not None:
             lo_sum += min(0.0, p)
             hi_sum += max(0.0, p)
             continue

goodwe_controller/app/arbiter.py

@@ -184,6 +184,12 @@ CLAIM_SCOPE = {
     # the banner and the claim an install has had since SAFETY-02 shipped.
     # `Controller.cycle()` does not even arm the site detector there.
     "sign_site": SCOPE_SITE,
+    # main.py: `Claim.limit("drain", P_MAINTENANCE, lo=...)`, SAFETY-78. At
+    # N>=2, while a pack's maintenance drain is pinned, the site target may
+    # not go below what that pin places: below it a sibling would have to
+    # charge against the drain (circulation, refused, 0 W). A site `lo`,
+    # never filed at N=1. DECISIONS/SAFETY-78-drain-at-two.md.
+    "drain": SCOPE_SITE,
 
     # --- UNIT: about one pack, one inverter, one device -------------------
     # main.py: `Claim.limit("device", P_SAFETY, self.dev_min, self.dev_max,

goodwe_controller/app/homeview.py

@@ -10,8 +10,9 @@ note, section 3.3.
 The plan shows only what the add-on does today: trading on price (the
 arbitrage verdict, the same call the control cycle makes), the monthly battery
 cycle, the peak limit and "follows the house". OPT-11 P1 adds each battery's
-switch and mode to its row; the mode plan arrives with P3/P4, so nothing here
-invents one. Every sentence is in the words
+switch and mode to its row; P3 adds each battery's price runs and its role this
+cycle (`Controller.mode_runs`, `mode_tick`), read as the control cycle left
+them, so nothing here invents a plan. Every sentence is in the words
 section at the bottom and is held to STYLE.md by test_messages.py.
 """
 
@@ -20,7 +21,7 @@ from datetime import datetime, timedelta, timezone
 from . import arbitrage, messages, peakguard, uitext
 from .maintenance import CHARGE as M_CHARGE, DRAIN as M_DRAIN, HOLD as M_HOLD
 from .maintenance import IDLE as M_IDLE
-from .packmode import LEFTOVER_SOLAR, SOLAR_FIRST
+from .packmode import CHEAP_HOURS, GRID_CHARGE_MODES, LEFTOVER_SOLAR, SOLAR_FIRST
 from .price import Absence, Uncertainty, brussels
 from .static_tariff import static_plan
 from .tariff import BILLING_TZ
@@ -312,6 +313,75 @@ def trade_runs(c, plan, verdict, day0, day1, now, shadow):
     return runs, later, None
 
 
+PRICE_MODES = (LEFTOVER_SOLAR, CHEAP_HOURS)
+
+
+def mode_runs(c, day0, day1, now, shadow):
+    """OPT-11 P3: each battery's price runs today, as the control cycle keeps
+    them (`c.mode_runs`): the cheap run on the batteries that may charge
+    from the grid, the give runs on Leftover solar and Cheap hours, and the
+    sell run on those with selling on. Amounts are upper bounds ("up to"),
+    from the battery's own room, rating and the run's length. Returns
+    `(runs, no_trade_key)`."""
+    rp = getattr(c, "mode_runs", None)
+    if getattr(c, "mode_tick", None) is None:
+        return [], None             # no cycle yet: nothing is known
+    if rp is None:
+        return [], "no_prices"
+    if not rp.on:
+        return [], "not_worth"
+    floor, ceiling = arbitrage.soc_bounds(c.o)
+    out = []
+    for i, inv in enumerate(c.inverters):
+        pm = c.pack_mode(inv)
+        if not pm.use or pm.mode not in PRICE_MODES:
+            continue
+        soc, cap = inv.soc, inv.capacity_kwh
+
+        def room(kind, hrs):
+            kwh = inv.max_w / 1000.0 * hrs
+            if cap and soc is not None:
+                kwh = min(kwh, max(0.0, (ceiling - soc) if kind == "grid"
+                                   else (soc - floor)) / 100.0 * cap)
+            return kwh
+        blocks = []
+        if rp.charge_useful() and pm.mode in GRID_CHARGE_MODES:
+            blocks.append(("grid", rp.cheap))
+        sell = rp.sell if pm.sell and pm.can_sell else None
+        for g in rp.give:
+            if sell is not None and g.start <= sell.start < g.end:
+                blocks.append(("sell", sell))
+            else:
+                blocks.append(("give", g))
+        for kind, run in blocks:
+            if run.end <= now or not (run.start < day1 and run.end > day0):
+                continue
+            hrs = (run.end - run.start).total_seconds() / 3600.0
+            kwh = room(kind, hrs)
+            if kwh < MIN_KWH:
+                continue
+            price = run.mean_eur_kwh
+            if kind == "grid":
+                what, why, amount = (run_grid_what(kwh, shadow),
+                                     run_cheap_why(price),
+                                     run_grid_amount(kwh * price))
+            elif kind == "sell":
+                # No money line: the price is what the house pays, and a sale
+                # earns the lower injection price (OPT-11 P3 review).
+                what, why, amount = (run_sell_what(kwh, shadow),
+                                     run_dear_why(price), None)
+            else:
+                what, why, amount = (run_give_what(kwh, shadow),
+                                     run_dear_why(price),
+                                     run_give_amount(kwh * price))
+            out.append(_run(i, "give" if kind == "sell" else kind,
+                            max(run.start, day0), min(run.end, day1), day0,
+                            day1, what, why, amount, kwh=kwh,
+                            eur=None if kind == "sell" else kwh * price,
+                            price=price))
+    return out, None
+
+
 def maintenance_runs(c, day0, day1, now, shadow):
     """The monthly battery cycle: under way now, or starting later today.
     The cycle starts in the hour `maintenance_start_hour` names, read as the
@@ -434,10 +504,17 @@ def build_plan(c, now, shadow, running, held=False, settled=True):
     runs, lines = [], []
     # The control cycle trades on the fresh plan only, so this does too.
     verdict, trade_why = trade_verdict(c, fresh)
+    modes_on = bool(getattr(c, "modes_on", False))
     if running:
         off = {i for i, inv in enumerate(c.inverters) if _off(c, inv)}
         runs += house_runs(len(c.inverters), day0, day1, now, shadow, off)
-        if verdict is not None:
+        if modes_on:
+            # OPT-11 P3: with battery modes on, each battery's price runs.
+            mine, no_trade = mode_runs(c, day0, day1, now, shadow)
+            runs += mine
+            if no_trade:
+                lines.append(line_no_trade(no_trade))
+        elif verdict is not None:
             trade, later, no_trade = trade_runs(c, fresh, verdict, day0, day1,
                                                 now, shadow)
             runs += trade
@@ -544,6 +621,11 @@ def battery_rows(c, shadow, running, held=False):
     pms = {inv.name: c.pack_mode(inv) for inv in c.inverters} \
         if modes_on else {}
     peak = peak_engaged(c)
+    # OPT-11 P3: each battery's role this cycle and the price runs, as the
+    # control cycle left them.
+    tick = getattr(c, "mode_tick", None) if modes_on else None
+    rp = getattr(c, "mode_runs", None)
+    now = datetime.now(timezone.utc)
     rows = []
     for i, inv in enumerate(c.inverters):
         m = c.maints[i] if i < len(c.maints) else None
@@ -558,13 +640,31 @@ def battery_rows(c, shadow, running, held=False):
         # carries its share (SAFETY-73)?
         other = next((o.name for o in c.inverters if o is not inv
                       and refusing(c, o) > 0 and not _off(c, o)), None)
+        # SAFETY-78: another battery drains for its monthly cycle, so this
+        # one never charges now. Not while that drain waits: it files no
+        # floor then, so this battery may charge from solar.
+        waits = getattr(c, "_drain_waits", ())
+        cycling = next((o.name for j, o in enumerate(c.inverters)
+                        if o is not inv and j < len(c.maints)
+                        and c.maints[j].phase == M_DRAIN
+                        and o.name not in waits), None)
+        role = None if tick is None else tick.roles.get(inv.name)
+        # Only once a cycle has run with modes on (`tick`): before that
+        # nothing is known, so nothing is claimed about the prices.
+        plan = (None if tick is None or pm.mode not in PRICE_MODES
+                else "no_prices" if rp is None
+                else "no_spread" if not rp.on else None)
+        nxt = rp.next_give(now) if rp is not None and rp.on else None
+        at = "" if nxt is None else (
+            f"{hhmm(nxt.start)} - {hhmm(nxt.end)}")
         why = battery_why(
             modes_on=modes_on, mode=None if pm is None else pm.mode, off=off,
             reading=inv.soc is not None and inv.batt is not None,
             phase=phase, shadow=shadow, running=running, held=held,
             refused=refusing(c, inv), peak=peak,
             giving=flow(inv.batt) == "giving", other_refuses=other,
-            sf_ahead=sf_ahead)
+            sf_ahead=sf_ahead, role=role, plan=plan, has_at=bool(at),
+            other_cycle=cycling)
         rows.append({
             "name": inv.name,
             "level_pct": None if inv.soc is None else float(inv.soc),
@@ -582,7 +682,8 @@ def battery_rows(c, shadow, running, held=False):
             # UX-13 P3: why it does what "now" says, from what the add-on
             # knows this cycle. Price and forecast reasons are OPT-11 P3/P4.
             "why_key": why,
-            "why": why_words(why, name=other),
+            "why": why_words(why, name=cycling if why == "other_cycle"
+                             else other, at=at),
         })
         if modes_on:
             # OPT-11 P1: the battery's switch and mode, for the Batteries
@@ -590,13 +691,18 @@ def battery_rows(c, shadow, running, held=False):
             # without them.
             rows[-1].update({"use": pm.use, "mode_key": pm.key,
                              "mode_choice": pm.mode,
-                             "mode": mode_word(pm.key)})
+                             "mode": mode_word(pm.key),
+                             # P3: selling, for Leftover solar and Cheap
+                             # hours only (Solar first never sells).
+                             "sell": pm.sell, "can_sell": pm.can_sell,
+                             "role": role})
     return rows
 
 
 def battery_why(*, modes_on, mode, off, reading, phase, shadow, running,
                 held, refused, peak, sf_ahead, giving=False,
-                other_refuses=None) -> str:
+                other_refuses=None, role=None, plan=None,
+                has_at=False, other_cycle=None) -> str:
     """The key of one battery's "why" line (`home_words.why`), most urgent
     first. Pure, so every branch is tested without a controller."""
     if not reading:
@@ -616,22 +722,37 @@ def battery_why(*, modes_on, mode, off, reading, phase, shadow, running,
         return "refuses_give" if refused > 0 else "refuses_charge"
     if peak:
         return "peak"
+    if other_cycle:
+        return "other_cycle"
     if giving and other_refuses:
         return "other_refuses"
     if not modes_on:
         return "modes_off"
+    # OPT-11 P3: the battery's role in the price runs this cycle.
+    if role in ROLE_WHY:
+        if role == "hold" and not has_at:
+            return "saves_later"
+        return ROLE_WHY[role]
+    if plan in ("no_prices", "no_spread"):
+        return plan
     if giving:
-        return "covers_house"      # both modes cover the house until P3
-    if mode == LEFTOVER_SOLAR:
+        return "covers_house"
+    if mode in PRICE_MODES:
         return "leftover" if sf_ahead else "leftover_alone"
     return "solar_first"
 
 
+# OPT-11 P3: a role (modetrade) -> its Why key.
+ROLE_WHY = {"charge": "grid_charge", "rest": "rests_charge",
+            "sell": "selling", "give": "expensive", "hold": "saves"}
+
+
 def attach_today(rows, runs, *, modes_on, running=True, held=False,
                  shadow=False) -> None:
     """UX-13 P3: each battery's runs today from the plan (the same blocks as
-    Home's chart), or one line saying there are none. With battery modes on
-    and no run, the mode's own plan is OPT-11 P3/P4, so it says so."""
+    Home's chart), or one line saying there are none. With battery modes on,
+    a Leftover solar or Cheap hours battery with no price run left today
+    says so; the others follow the house."""
     for i, row in enumerate(rows):
         mine = [r for r in runs if r["battery"] == i and r["kind"] != "house"]
         row["today"] = [{"from": r["from"], "to": r["to"], "kind": r["kind"],
@@ -644,8 +765,11 @@ def attach_today(rows, runs, *, modes_on, running=True, held=False,
             row["today_line"] = today_words("stopped")
         elif row.get("use") is False:
             row["today_line"] = today_words("off")
-        elif modes_on:
-            row["today_line"] = today_words("not_planned")
+        elif modes_on and row.get("mode_choice") in PRICE_MODES:
+            # OPT-11 P3: a price mode with no run left today, or no plan
+            # made yet (no cycle has run with modes on).
+            row["today_line"] = today_words("no_runs" if row.get("role")
+                                            else "not_planned")
         else:
             row["today_line"] = today_words("house_would" if shadow
                                             else "house")
@@ -954,10 +1078,11 @@ def battery_now(soc, batt_w, *, phase, shadow, running, held=False,
     return _t("now.resting")
 
 
-def why_words(key, name=None) -> str:
+def why_words(key, name=None, at="") -> str:
     """One battery's "why" line (UX-13 P3), from `battery_why()`'s key.
-    `name`: the battery that refuses, for `other_refuses`."""
-    return _t("why." + key, name=name or "")
+    `name`: the battery that refuses, for `other_refuses`; `at`: the
+    give run's time, for `saves`."""
+    return _t("why." + key, name=name or "", at=at)
 
 
 def today_words(key) -> str:
@@ -989,6 +1114,18 @@ def run_grid_amount(eur) -> str:
     return _t("run.grid_amount", eur=_eur(eur))
 
 
+def run_sell_what(kwh, shadow) -> str:
+    return _w(shadow, "run.sell_what", kwh=_kwh(kwh))
+
+
+def run_cheap_why(price) -> str:
+    return _t("run.cheap_why", eur=_eur(price))
+
+
+def run_dear_why(price) -> str:
+    return _t("run.dear_why", eur=_eur(price))
+
+
 def run_give_what(kwh, shadow) -> str:
     return _w(shadow, "run.give_what", kwh=_kwh(kwh))
 

goodwe_controller/app/main.py

@@ -37,11 +37,13 @@ import aiohttp
 
 from . import arbitrage
 from .arbiter import (
-    P_LOOP, P_MAINT_SHAPE, P_MAINTENANCE, P_MODE, P_PEAK, P_SAFETY,
-    Claim, Resolution, actuator_for, pre_resolve, resolve,
+    ACTUATOR_SITE, P_LOOP, P_MAINT_SHAPE, P_MAINTENANCE, P_MODE, P_PEAK,
+    P_SAFETY, SET, Claim, Resolution, actuator_for, pre_resolve, resolve,
 )
 from . import allocator
+from . import modetrade
 from . import packmode
+from . import priceruns
 from . import control as _ctl
 from .control import Tuning, compute, maintenance_charge_floor, peak_at_risk
 from .delivery import (
@@ -69,7 +71,7 @@ from .hass import HomeAssistant
 from .inverter import (LINK_STALE_S, UNIT_A, build_roster,
                        roster_entries, roster_names)
 from .maintenance import (
-    IDLE, POWER_MOVING, MaintConfig, Maintenance, MaintResult,
+    DRAIN, IDLE, POWER_MOVING, MaintConfig, Maintenance, MaintResult,
     arbitrate as maint_arbitrate,
 )
 from .mqtt import (MODE_CONFIGS_KEY, MODE_LABELS, USE_OFF, USE_ON,
@@ -80,7 +82,9 @@ from . import packshare
 from . import pv as pv_read
 from . import shadow
 from .p1 import P1Ingest, build_source, is_enabled
-from .price import Uncertainty, brussels, price_option, provider_configured
+from .price import Absence, Uncertainty, brussels, price_option, provider_configured
+from .price import required_spread as price_required_spread
+from .price import uncertainty_of as price_uncertainty_of
 from .price_history import PriceHistory
 from .static_tariff import resolve_tariff, static_status
 from .tariff import PeakStore, PeakTracker
@@ -226,6 +230,24 @@ def load_options() -> dict:
 
 
 
+# OPT-11 P3: how long the last cheap run stays the price stored energy is
+# valued at (`priceruns.plan(ref_eur_kwh=)`): the rest of that day.
+REF_CHEAP_KEEP = timedelta(hours=12)
+
+
+def why_raised(resolution, claims) -> bool:
+    """F2 (OPT-11 P1 test): did the limit that bound the site target push it
+    ABOVE what the winner asked (the peak floor asking for more power)? Then
+    the Why line must not say "held back". False when nothing bound it."""
+    if not resolution.bound_by or resolution.contradiction:
+        return False
+    asked = next((c.value for c in sorted(
+        (c for c in claims if c.kind == SET
+         and c.actuator == ACTUATOR_SITE and c.source == resolution.winner),
+        key=lambda c: c.priority, reverse=True)), None)
+    return asked is not None and resolution.target_w > float(asked)
+
+
 def pack_energy_of(inv):
     """OPT-09. ONE roster entry as the view `packshare` consumes.
 
@@ -894,8 +916,17 @@ class Controller:
         # every option family this file builds: no numeric fallback in main.py
         # that config.yaml has not shipped.
         self.peak_guard = None
+        # SAFETY-79. The guard aims this far under `peak_cap_w`; the bill and
+        # every report keep the real cap (`self.peak.cap_w`).
+        self.peak_margin_w = float(opts.get(
+            "peak_margin_w", peakguard.PEAK_OPTION_DEFAULTS["peak_margin_w"]))
         self._peak_engaged = False
         self._peak_saturated = False
+        # SAFETY-81: what the alarm is graded on, beside the guard's decision.
+        self._peak_proj = None
+        self._peak_batt_prev = None
+        self._peak_alarm_block = None
+        self._peak_high_since = None
         self._peak_floor_limited = False
         self._maint_shape_suspended = False
         # OPT-11. Battery modes, off by default so an install that has not
@@ -905,12 +936,26 @@ class Controller:
         self.modes_on = packmode.enabled(opts)
         # The units whose mode fault is logged already (edge-logged).
         self._mode_faults = set()
+        # OPT-11 P3: the price runs (`priceruns.RunPlan`, or None), the key
+        # they were built for, this tick's roles (`modetrade.Tick`), the
+        # batteries that left a run (full, or at the floor) keyed by the run,
+        # and whether last tick filed a mode trade (a run edge reseeds).
+        self.mode_runs = None
+        self._runs_key = None
+        self.mode_tick = None
+        self._run_done = {}
+        self._mode_trade_was = False
+        self._charge_blocked_q = None
+        self._ref_cheap = None
         # OPT-11 P2: (topic, reason) of MQTT commands refused and logged once.
         self._mqtt_refused = set()
         self._mqtt_refused_more = 0
         # [(pack name, why)] for packs that are due and waiting their turn.
         # Empty at a roster of one, where nothing can defer anything.
         self._maint_deferred = []
+        # SAFETY-78: names of draining packs that cannot give power now, so
+        # the "waits" line is logged once, not every cycle.
+        self._drain_waits = set()
         # Set by amain() once the transport is built, so the status page can show
         # what only the transport knows (homewizard_local's unchanged_s). Stays
         # None when P1 is off, or under a transport that has no such counter.
@@ -1827,6 +1872,11 @@ class Controller:
         """
         return float(sum(inv.rating_w() for inv in self.inverters))
 
+    def peak_aim_w(self) -> float:
+        """SAFETY-79. `peak_cap_w` less `peak_margin_w`: what the forecast
+        checks aim at. Reports and the bill use the real cap."""
+        return float(self.o.get("peak_cap_w", 3500)) - self.peak_margin_w
+
     def site_dev_bound(self, which: str):
         """The roster's summed device floor / ceiling, or None if unknown.
 
@@ -1973,7 +2023,11 @@ class Controller:
         # OPT-11: the solar order. While the site charges, Leftover solar
         # batteries weigh 0, so Solar first batteries fill first. A comfort
         # choice like the rest of this method: permission is the mode claim.
-        return packmode.charge_weights(base, self.pack_modes(), target_w)
+        w = packmode.charge_weights(base, self.pack_modes(), target_w)
+        # P3: in a price run, the batteries whose run it is carry it first.
+        tick = self.mode_tick
+        return w if tick is None else modetrade.weights(tick.roles, w,
+                                                        target_w)
 
     def pack_mode(self, inv) -> "packmode.PackMode":
         """OPT-11. This battery's on/off switch and mode, read from the store."""
@@ -2002,6 +2056,215 @@ class Controller:
                   for u in self.units}
         return allocator.loop_bound(bounds, live=self.live_units())
 
+    # --- OPT-11 P3: price runs, per battery -------------------------------
+    def _mode_packs(self, maint_results=None) -> list:
+        """Each battery as `modetrade.Pack`, in roster order."""
+        live = set(self.live_units())
+        out = []
+        for i, inv in enumerate(self.inverters):
+            pm = self.pack_mode(inv)
+            idle = (maint_results is None
+                    or maint_results[i].phase == IDLE)
+            refused = (inv.refused if len(self.inverters) > 1
+                       else self.batt_refused) or 0
+            out.append(modetrade.Pack(
+                inv.name, pm.use, pm.mode, pm.sell and pm.can_sell,
+                float(inv.max_w), inv.soc, inv.capacity_kwh,
+                live=inv.name in live, idle=idle, refused=int(refused)))
+        return out
+
+    def _price_runs(self, now, packs, floor_pct, ceiling_pct):
+        """The kept run plan, rebuilt at most once per price slot (15 min) or
+        when the prices or a battery's choice change; a run under way is
+        kept to its end (`priceruns.keep_started()`). None with no fresh
+        firm prices: then no battery holds or trades (design section 5)."""
+        plan = self.fresh_tariff_plan(now)
+        if plan is None or not plan.has_prices:
+            self.mode_runs, self._runs_key = None, None
+            return None
+        slot = int(now.timestamp() // 900)
+        key = (id(plan), slot, tuple((p.name, p.use, p.mode, p.sell)
+                                     for p in packs))
+        if key != self._runs_key:
+            done_c = self._run_done.get("charge", (None, set()))[1]
+            done_s = self._run_done.get("sell", (None, set()))[1]
+            e = modetrade.energy(packs, floor_pct, ceiling_pct, done_c,
+                                 done_s)
+            required = price_required_spread(
+                arbitrage.threshold_eur_kwh(self.o),
+                price_uncertainty_of(plan.read.product)
+                | {Uncertainty.NO_WEATHER})
+            ref = self._ref_cheap
+            if ref is not None and now - ref.end > REF_CHEAP_KEEP:
+                ref = self._ref_cheap = None
+            new = priceruns.plan(
+                plan.read.points, now, required_eur_kwh=required,
+                charge_kwh=e[0], charge_kw=e[1], sell_kwh=e[2],
+                sell_kw=e[3],
+                ref_eur_kwh=None if ref is None else ref.mean_eur_kwh)
+            self.mode_runs = priceruns.keep_started(self.mode_runs, new, now)
+            self._runs_key = key
+        runs = self.mode_runs
+        # The cheapest cheap run under way lately is the price the stored
+        # energy was bought at; it stays the reference for REF_CHEAP_KEEP
+        # after it ends, unless a cheaper one comes.
+        ref = self._ref_cheap
+        if runs is not None and runs.cheap is not None \
+                and runs.cheap.holds(now) and (
+                    ref is None or now - ref.end > REF_CHEAP_KEEP
+                    or runs.cheap.mean_eur_kwh <= ref.mean_eur_kwh):
+            self._ref_cheap = runs.cheap
+        return runs
+
+    def _mode_roles(self, now, maint_results):
+        """OPT-11 P3: each battery's role and range this tick. Grid charging
+        and selling need a fresh plan that `TariffPlan.arbitrage()` allows
+        with the MEASURED peak guard (None refuses: nothing measures the
+        quarter), exactly the gate `arbitrage.decide()` has."""
+        floor_pct, ceiling_pct = arbitrage.soc_bounds(self.o)
+        packs = self._mode_packs(maint_results)
+        runs = self._price_runs(now, packs, floor_pct, ceiling_pct)
+        guard = arbitrage.guard_state(self.peak_guard)
+        plan = self.fresh_tariff_plan(now)
+        charge_ok = sell_ok = False
+        trade_why = "not_covered"
+
+        def allowed(active):
+            return plan.arbitrage(
+                peak_guard_active=active,
+                min_spread_eur_kwh=arbitrage.threshold_eur_kwh(self.o),
+                uncertainty=frozenset({Uncertainty.NO_WEATHER})).match(
+                    allowed=lambda _v: True, refused=lambda _v: False)
+        if guard is not None and plan is not None and runs is not None:
+            # A charge asks the guard (section 9.1 interlock); a sell only
+            # needs it to have measured the quarter, since discharge is never
+            # capped by it (a big discharge alone engages it on export).
+            sell_ok = allowed(False)
+            charge_ok = sell_ok and allowed(guard)
+            trade_why = (None if charge_ok else "peak" if sell_ok
+                         else "not_worth")
+        price_now = None
+        if plan is not None:
+            try:
+                pt = plan.read.match(series=lambda r: r.at(now),
+                                     no_data=lambda _r: None)
+                price_now = (None if pt is None or pt.provisional
+                             else float(pt.eur_per_kwh))
+            except Absence:
+                price_now = None
+        house = (None if self.grid is None or self.site_batt_w is None
+                 else float(self.grid) + float(self.site_batt_w))
+        done_c = self._run_mark("charge", runs and runs.cheap, packs,
+                                lambda p: p.soc is not None
+                                and p.soc >= ceiling_pct)
+        done_s = self._run_mark("sell", runs and runs.sell, packs,
+                                lambda p: p.soc is not None
+                                and p.soc <= floor_pct)
+        quarter = int(now.timestamp() // 900)
+        was = self.mode_tick is not None and \
+            self.mode_tick.action == modetrade.CHARGE
+        self.mode_tick = modetrade.decide(
+            runs, now, packs, charge_ok=charge_ok, sell_ok=sell_ok,
+            trade_why=trade_why, price_now=price_now,
+            headroom_w=self.arb_headroom_w, floor_pct=floor_pct,
+            ceiling_pct=ceiling_pct, house_w=house, charging_now=was,
+            blocked=self._charge_blocked_q == quarter,
+            done_charge=done_c, done_sell=done_s,
+            draining=any(r.phase == DRAIN for r in maint_results or ()))
+        # A charge the guard or the headroom stopped stays off this period.
+        if was and self.mode_tick.action != modetrade.CHARGE and \
+                self.mode_tick.why in ("peak", "headroom"):
+            self._charge_blocked_q = quarter
+        return self.mode_tick
+
+    def _run_mark(self, kind, run, packs, out) -> set:
+        """The batteries that left run `run` (full, or at the floor); they
+        stay out until it ends, so a level edge does not re-arm them."""
+        key = None if not run else (run.start, run.end)
+        was_key, done = self._run_done.get(kind, (None, set()))
+        if key != was_key:
+            done = set()
+        if key is not None:
+            done |= {p.name for p in packs if out(p)}
+        self._run_done[kind] = (key, done)
+        return done
+
+    def _mode_trade(self, claims, now) -> bool:
+        """OPT-11 P3: file the site trade the roles ask for, sized inside the
+        modes and the hard limits (the loop bound) and, for a charge, the
+        billed quarter's headroom (SAFETY-45, aim cap - margin, SAFETY-79).
+        So no battery that its mode or a refusal holds is asked for watts it
+        may not give (P1's unmet share). Returns True when a trade is filed.
+        """
+        tick = self.mode_tick
+        if tick is None:
+            return False
+        size = modetrade.size(tick, self.loop_bound(claims)
+                              if tick.action else None, self.arb_headroom_w)
+        runs = self.mode_runs
+        if tick.action and (size == 0.0 or runs is None):
+            # Nothing the batteries may place (a refusal, a hard limit): no
+            # trade, and the roles say so rather than "charging".
+            back = {modetrade.CHARGE: modetrade.HOLD,
+                    modetrade.REST: modetrade.HOUSE,
+                    modetrade.SELL: modetrade.GIVE}
+            tick = self.mode_tick = modetrade.Tick(
+                tick.ranges, {n: back.get(r, r) for n, r in tick.roles.items()},
+                None, 0.0, "size")
+        if size == 0.0 or runs is None:
+            reason = ("battery modes: no price run now" if tick.why is None
+                      else f"battery modes: no trade ({tick.why})")
+            self.arb = arbitrage.ArbitrageDecision(
+                action=None, power_w=None, reason=reason,
+                spread_eur_kwh=None, required_eur_kwh=None,
+                price_now_eur_kwh=None)
+        else:
+            charge = tick.action == modetrade.CHARGE
+            run = runs.cheap if charge else runs.sell
+            who = ", ".join(n for n, r in sorted(tick.roles.items())
+                            if r == tick.action)
+            act = arbitrage.CHARGE if charge else arbitrage.DISCHARGE
+            self.arb = arbitrage.ArbitrageDecision(
+                action=act, power_w=size,
+                reason=(f"{act}: battery modes, "
+                        f"{'cheap' if charge else 'sell'} run "
+                        f"{run.start.isoformat()} to {run.end.isoformat()} "
+                        f"at {run.mean_eur_kwh:.4f} EUR/kWh; "
+                        f"{abs(size):.0f} W on {who}"),
+                spread_eur_kwh=None, required_eur_kwh=runs.level_eur_kwh,
+                price_now_eur_kwh=None)
+            claims.append(arbitrage.claim(self.arb))
+        if self.arb.action != self._arb_action:
+            self._arb_action = self.arb.action
+            self.log_event(self.arb.explain(), hint=messages.hint(
+                "trade_charge" if self.arb.action == arbitrage.CHARGE else
+                "trade_give" if self.arb.action == arbitrage.DISCHARGE
+                else "trade_off"))
+        return self.arb.action is not None
+
+    def _reseed_run_edge(self, claims) -> None:
+        """OPT-11 P3: a mode trade just ended, so the loop takes over from a
+        command no loop chose. Start it at the house's own point E, the
+        command that brings the grid to its target now (`site battery + grid
+        - target`, inside the loop bound), instead of at the trade's watts
+        (the trade began with the same unslewed step). This tick's error still
+        measures the trade's command (it is exactly E - battery), so the
+        integrator is seeded that much short and lands on E after its step.
+        Measured (tools/opt11p3_replay.py, lagged battery, 2.5 kW charge
+        ending under an 800 W house): no reseed -258 W export then a 2976 W
+        import, settled in 55 s; this -257 W / +615 W, settled in 20 s.
+        """
+        batt = self.site_batt_w
+        if batt is None or self.grid is None:
+            return
+        want = float(batt) + float(self.grid) - self.tuning.target_grid_w
+        bound = self.loop_bound(claims)
+        if bound is not None:
+            want = max(bound[0], min(bound[1], want))
+        want = float(round(max(-self.site_max_w, min(self.site_max_w, want))))
+        self.target = want
+        self.i_w = want - self.tuning.gain * (want - float(batt))
+
     def _mode_fault_log(self, resolution) -> None:
         """OPT-11: say once, per battery, that its mode was dropped as a fault.
 
@@ -2023,7 +2286,8 @@ class Controller:
         self._mode_faults = now
 
     def _pack_action(self, what, unit, value, now) -> dict:
-        """OPT-11: switch one battery on or off, or set its mode.
+        """OPT-11: switch one battery on or off, set its mode, or (P3) turn
+        its selling on or off.
 
         Store state, not an option, so it applies on the next cycle with no
         restart. Written to the action log. Switching a battery off also stops
@@ -2047,6 +2311,15 @@ class Controller:
             if not value:
                 self._maint_stop_off(self.maints[self.inverters.index(inv)],
                                      now)
+        elif what == "pack_sell":
+            if not packmode.SELLING_ENABLED:
+                return {"error": messages.pack_refused("sell_off")}
+            if not isinstance(value, bool):
+                return {"error": messages.pack_refused("value")}
+            inv.store_set(packmode.SELL_KEY, value)
+            self.log_event(f"{inv.name} selling switched "
+                           f"{'on' if value else 'off'} by operator",
+                           hint=messages.hint("pack_sell", unit=inv.name))
         else:
             if value not in packmode.MODES:
                 return {"error": messages.pack_refused("value")}
@@ -2055,7 +2328,10 @@ class Controller:
                            f"by operator",
                            hint=messages.hint("pack_mode", unit=inv.name))
         pm = self.pack_mode(inv)
-        return {"unit": inv.name, "use": pm.use, "mode": pm.mode}
+        out = {"unit": inv.name, "use": pm.use, "mode": pm.mode}
+        if what == "pack_sell":
+            out["sell"] = pm.sell
+        return out
 
     def mode_values(self) -> dict:
         """OPT-11 P2: each battery's mode and switch, for their HA state
@@ -2116,6 +2392,42 @@ class Controller:
         except Exception:                               # noqa: BLE001
             _LOG.exception("Home Assistant command could not be handled")
 
+    def _drain_floor(self, claims, maint_results):
+        """SAFETY-78: the site `lo` for a pinned maintenance drain, or None.
+
+        At N>=2 the drain pins its pack and the site target is split around
+        the pin. Below the pin a sibling would have to charge (opposite
+        directions, refused, 0 W, and the drain never moves). So the site
+        target may not go below what the pin places: the drained pack covers
+        the house up to its drain rate and exports the rest, as at N=1, and
+        a sibling only ever adds power in the same direction. At N=1 the
+        drain is the site SET itself, so nothing is filed.
+        A draining pack whose own limits leave it nothing to give (a refusal,
+        a stale link) adds no floor, and that is logged once.
+        """
+        if len(self.inverters) < 2:
+            return None
+        live = set(self.live_units())
+        floor, waits = 0.0, set()
+        for inv, res in zip(self.inverters, maint_results):
+            if res.phase != DRAIN or not res.owns_setpoint \
+                    or not (res.setpoint_w or 0.0) > 0.0:
+                continue
+            u = self.actuator_of("maintenance", inv)
+            b = pre_resolve([c for c in claims if c.actuator == u])
+            p = (None if u not in live or b.contradiction
+                 or b.pinned_by != "maintenance" else allocator.pin_w(b))
+            if p is not None and p > 0.0:
+                floor += p
+            else:
+                waits.add(inv.name)
+        for name in sorted(waits - self._drain_waits):
+            self.log_event(f"maintenance: {name} cannot give power now, so "
+                           f"its monthly cycle waits",
+                           hint=messages.hint("maint_waits", unit=name))
+        self._drain_waits = waits
+        return floor if floor > 0.0 else None
+
     def _maint_stop_off(self, machine, now) -> None:
         """OPT-11: stop this battery's maintenance cycle because it is off."""
         if machine.phase == IDLE:
@@ -3445,14 +3757,17 @@ class Controller:
         # is not measured on that path, and the honest report is NOT COVERED -
         # the same answer, for the same reason, that the status page already
         # gives for SAFETY-18 on a transport that cannot see `unchanged_s`.
+        self._peak_proj = (None if not self.p1_enabled
+                           else self.peak.project(self.p1.averager, now))
         self.peak_guard = None if not self.p1_enabled else peakguard.decide(
-            self.peak.project(self.p1.averager, now),
+            self._peak_proj,
             # ⚠️ THE SITE SUM. The guard sizes a floor from what the battery is
             # ALREADY removing from the meter, and the meter sees every
             # inverter. One unit's power here would size the floor from a
             # fraction of the discharge already happening.
             batt_w=self.site_batt_w,
             cap_w=float(self.o.get("peak_cap_w", 3500)),
+            margin_w=self.peak_margin_w,
             reading=self.peak.peak(now),
             # ⚠️ SUMMED FROM THE PER-UNIT CONJUNCTION, WHICH IS AC 4. Each
             # unit contributes `min(its max_w, |its own device bounds|)`, so
@@ -3569,15 +3884,20 @@ class Controller:
         # decision presented as current.
         self.arb, self.arb_at = None, now
         self.arb_headroom_w = None
-        if arbitrage.enabled(self.o):
-            floor_pct, ceiling_pct = arbitrage.soc_bounds(self.o)
-            charge_w, discharge_w = self.trade_power_w(floor_pct, ceiling_pct)
+        # OPT-11 P3: with battery modes on, each battery's mode decides who
+        # trades (`_mode_roles()`, `_mode_trade()`, below, which read the
+        # same headroom), and this site-wide trade is not run.
+        site_trade = arbitrage.enabled(self.o) and not self.modes_on
+        if site_trade or self.modes_on:
             # SAFETY-47. HOISTED OUT OF THE CALL, NOT COPIED. One evaluation of
             # the shipped expression feeds both the sizing below and
             # `arbitrage.sized_from_meter()` in `_shadow_settle()`, so the
             # caveat on the recorded watts can never be answered from a
             # different cycle's guard than the watts were.
             self.arb_headroom_w = peakguard.charge_headroom_w(self.peak_guard)
+        if site_trade:
+            floor_pct, ceiling_pct = arbitrage.soc_bounds(self.o)
+            charge_w, discharge_w = self.trade_power_w(floor_pct, ceiling_pct)
             self.arb = arbitrage.decide(
                 self.fresh_tariff_plan(now), now,
                 peak_guard_active=arbitrage.guard_state(self.peak_guard),
@@ -3713,8 +4033,7 @@ class Controller:
                 # charge together, this flag would have to become per-pack - and
                 # so would the reasoning above it.
                 if peakguard.shaping_suspended(
-                        self.peak_guard, self.peak_fc,
-                        float(self.o.get("peak_cap_w", 3500))):
+                        self.peak_guard, self.peak_fc, self.peak_aim_w()):
                     # Edge-logged: level-logging here would write one line per
                     # cycle for as long as the event lasts and flush the 40-line
                     # action log of the very context that explains it.
@@ -3741,7 +4060,7 @@ class Controller:
                         # rate the pack in front of us is charging at.
                         floor = maintenance_charge_floor(
                             self.maint.cfg.charge_w,
-                            self.peak_fc, float(self.o.get("peak_cap_w", 3500)))
+                            self.peak_fc, self.peak_aim_w())
                         if floor > 0:
                             hi, reason = -floor, "cheap-window charge"
                     # PER-INVERTER, like the SET above and for the same reason -
@@ -3758,12 +4077,17 @@ class Controller:
         # apart from the hard limits, and it gives way to the peak guard's
         # site floor (P_PEAK) only as far as the floor needs, so the two never
         # meet in a `lo > hi` (arbiter._unit_modes()).
+        # P3: the range is the switch's, narrowed by the battery's role in
+        # the price runs this tick (`modetrade.decide()`); both hold 0 W.
         if self.modes_on:
+            tick = self._mode_roles(now, maint_results)
             for inv, result in zip(self.inverters, maint_results):
                 if result.phase != IDLE:
                     continue
                 pm = self.pack_mode(inv)
                 lo, hi = packmode.mode_range(pm, inv.max_w)
+                rlo, rhi = tick.ranges.get(inv.name, (lo, hi))
+                lo, hi = max(lo, rlo), min(hi, rhi)
                 claims.append(Claim.limit("mode", P_MODE, lo, hi, pm.key,
                                           actuator=self.actuator_of("mode",
                                                                     inv)))
@@ -3814,6 +4138,20 @@ class Controller:
                                           _ctl.REFUSED,
                                           actuator=self.actuator_of("refused",
                                                                     inv)))
+        # --- SAFETY-78: a pinned drain is a floor under the site target -----
+        # After every unit claim, so the floor is what the pin really places.
+        drain = self._drain_floor(claims, maint_results)
+        if drain is not None:
+            claims.append(Claim.limit("drain", P_MAINTENANCE, lo=drain,
+                                      reason="maintenance drain",
+                                      actuator=self.actuator_of("drain")))
+        # --- OPT-11 P3: the site trade, after every unit claim --------------
+        # Sized from what the batteries may place with their modes and hard
+        # limits (the loop bound), so none is asked for watts it may not give.
+        mode_trade, trade_was = False, self._mode_trade_was
+        if self.modes_on:
+            mode_trade = self._mode_trade(claims, now)
+        self._mode_trade_was = mode_trade
         if (self.auto or self.shadow) and self.inputs_ok:
             # ⚠️ prev is the ARBITER's last output, not the loop's own last
             # wish. If something outranked the loop, that is what the hardware
@@ -3831,6 +4169,9 @@ class Controller:
             # stale period as power.
             if self.loop_w is None or self.target != self.loop_w:
                 self.i_w = self.target
+            # OPT-11 P3: a run edge (a mode trade ended) reseeds the loop.
+            if trade_was and not mode_trade:
+                self._reseed_run_edge(claims)
             # SAFETY-52: another writer overrode the loop, so a refusal learned
             # against the loop's own ask no longer describes the wire. A gap
             # (`loop_w` None: blind or stopped) keeps it: the stale-reading stop
@@ -4163,7 +4504,8 @@ class Controller:
         else:
             self.why_words = messages.why(
                 _why, resolution.target_w, resolution.bound_by,
-                contradiction=resolution.contradiction)
+                contradiction=resolution.contradiction,
+                raised=why_raised(resolution, claims))
         # --- DEV-02: EACH INVERTER IS TOLD ITS OWN SHARE ---------------------
         # ⚠️ ITS OWN SHARE, NEVER THE SITE TARGET. `resolution.shares` is the
         # allocator's answer and `sum(shares) + unmet_w == round(target_w)` is
@@ -4528,22 +4870,56 @@ class Controller:
         available to it. That is the one state where the money is going to be
         spent and a human is the only remaining actuator.
 
+        SAFETY-81: `g.saturated` alone is not enough. It is graded against the
+        aim, and a 1 s meter spike, noise or the last seconds of a quarter set
+        it while the quarter lands on target; `peakguard.load_too_high()` must
+        agree too, for `ALARM_HOLD_S`. The battery reading it gets is the lower
+        of this cycle's and the last one's - see there.
+
         Edge-triggered, and de-asserting arms it again - the same shape as
         FreezeWatchdog's `evaluate()`, and for the same reason: one notification
-        per episode, not one per cycle.
+        per episode, not one per cycle. SAFETY-81: the notification and action
+        log line at most once per quarter; the ERROR line once per episode.
         """
         g = self.peak_guard
-        saturated = bool(g is not None and g.saturated)
+        batt, prev = self.site_batt_w, self._peak_batt_prev
+        if batt is None:
+            # Unknown, not "fine": the hold below neither grows nor restarts.
+            return
+        self._peak_batt_prev = batt
+        if prev is not None:
+            batt = min(float(batt), float(prev))
+        p = self._peak_proj
+        high = bool(
+            g is not None and g.saturated and p is not None
+            and p.block_start is not None
+            and peakguard.load_too_high(
+                p, batt_w=batt, ceiling_w=g.ceiling_w,
+                achievable_w=self.site_rating_w))
+        # SAFETY-81: and for ALARM_HOLD_S, on the projection's clock.
+        saturated = False
+        if high:
+            t = p.block_start + timedelta(seconds=float(p.elapsed_s))
+            if self._peak_high_since is None:
+                self._peak_high_since = t
+            saturated = ((t - self._peak_high_since).total_seconds()
+                         >= peakguard.ALARM_HOLD_S)
+        else:
+            self._peak_high_since = None
         was, self._peak_saturated = self._peak_saturated, saturated
         if not saturated or was:
             return
-        self.log_event("PEAK_GUARD_SATURATED - " + g.reason,
-                       hint=messages.hint("peak_saturated"))
         _LOG.error(
             "Switch off large loads, the battery alone cannot keep this "
             "15-minute period under the peak limit: %s.",
             messages.reason_code(g.reason))
         _LOG.debug("Evidence: %s.", g.reason)
+        # SAFETY-81: notified once per quarter; a later episode is logged only.
+        if p.block_start == self._peak_alarm_block:
+            return
+        self._peak_alarm_block = p.block_start
+        self.log_event("PEAK_GUARD_SATURATED - " + g.reason,
+                       hint=messages.hint("peak_saturated"))
         # A fixed notification_id, and a DIFFERENT one from every other alarm
         # here - check_meter_frozen() gives the reasoning. A saturated peak guard
         # is not a frozen meter and is not an out-of-range setpoint.
@@ -5925,8 +6301,11 @@ class Controller:
             # instead of inferring it, and separates "trading is off" from "no
             # decision was reached this cycle"; `cycle_at` and `arb_at` are what
             # make the second one an observation rather than a guess.
+            # OPT-11 P3: with battery modes on the modes trade, whatever the
+            # switch says, so the row reports their decision.
             ("Arbitrage", arbitrage_row(
-                on=arbitrage.enabled(self.o), decision=self.arb,
+                on=arbitrage.enabled(self.o) or self.modes_on,
+                decision=self.arb,
                 decided_at=self.arb_at, cycle_at=self.cycle_at,
                 now=datetime.now(timezone.utc), why=self.why_words)),
         ]
@@ -5958,7 +6337,7 @@ class Controller:
 
     async def handle_action(self, what: str, *, unit=None, value=None):
         now = datetime.now(timezone.utc)
-        if what in ("pack_use", "pack_mode"):
+        if what in ("pack_use", "pack_mode", "pack_sell"):
             return self._pack_action(what, unit, value, now)
         if what == "auto_toggle":
             self.auto = not self.auto

goodwe_controller/app/messages.py

@@ -839,17 +839,22 @@ WHY_LIMIT = {
 }
 
 
-def why(winner, target_w, bound_by=None, *, contradiction=False) -> str:
+def why(winner, target_w, bound_by=None, *, contradiction=False,
+        raised=False) -> str:
     """`winner` is the arbiter's winning source, or its reason for the two
     that share a source ("stopped", "inputs missing", "no claim was made").
-    `bound_by` is `Resolution.bound_by`, e.g. "peak(quarter peak)"."""
+    `bound_by` is `Resolution.bound_by`, e.g. "peak(quarter peak)".
+    `raised` is True when that limit pushed the power UP (the peak limit
+    asking for more): then it did not hold anything back (OPT-11 P1 test F2).
+    """
     if contradiction:
         return "Two limits clash, so every inverter is set to 0 W"
     out = f"{WHY_WINNER.get(winner, 'Other')}: {signed_watts(target_w)}"
     if bound_by:
         limit = WHY_LIMIT.get(bound_by) or WHY_LIMIT.get(
             str(bound_by).split("(")[0], "another limit")
-        out += f", held back by {limit}"
+        out += f", raised for {limit}" if raised else \
+            f", held back by {limit}"
     return out
 
 
@@ -922,7 +927,9 @@ HINTS = {
     "pack_on": "{unit}: battery switched on",
     "pack_off": "{unit}: battery switched off, it is asked for 0 W",
     "pack_mode": "{unit}: battery mode changed",
+    "pack_sell": "{unit}: selling switched",
     "maint_off": "{unit}: maintenance stopped, the battery is switched off",
+    "maint_waits": "{unit} cannot give power now, so its monthly cycle waits",
     "mode_fault": "{unit}: battery mode ignored because of a software fault",
 }
 
@@ -932,6 +939,8 @@ PACK_REFUSED = {
     "off": "Battery modes are off. Turn on “Battery modes” first.",
     "unit": "There is no battery with that name.",
     "value": "That choice is not possible for this battery.",
+    # OPT-11 P3, owner decision 2026-09-29: selling is off for now.
+    "sell_off": "Selling is off for now.",
     # OPT-11 P2: a Home Assistant command dropped before it reaches a battery.
     "retained": "An old saved command is not used.",
     "size": "That command is too long.",
@@ -1157,6 +1166,7 @@ LABELS = {
     "integrator_max_w": "Catch-up limit",
     "maintenance_discharge_w": "Draw-down rate",
     "peak_cap_w": "Peak limit",
+    "peak_margin_w": "Margin below the peak limit",
     "peak_forecast_entity": "15-minute demand forecast entity",
     "meter_entity": "Grid power entity",
     "soc_entity": "Battery level entity",

goodwe_controller/app/modetrade.py

@@ -0,0 +1,237 @@
+"""OPT-11 P3: each battery's role this tick, from its mode and the price runs.
+
+Pure: no I/O, no clock. main.py hands in the run plan (`priceruns`), each
+battery's state and the peak guard's answers, files each battery's range as
+its `mode` claim (P_MODE), and files the site trade as the `arbitrage` claim
+(P_ARBITRAGE), sized inside the modes (`size()`), only with battery modes on.
+With them off, `arbitrage.decide()` runs exactly as before.
+
+Roles (the page's Why line names them):
+  off      Off: [0, 0].
+  house    follows the house: charges from spare solar, gives power at any
+           hour (Solar first always; the other modes when there is no plan).
+  hold     Leftover solar / Cheap hours outside a give run: may charge from
+           spare solar, gives nothing, so its energy is kept for the run.
+  give     the same inside a give run: covers the house.
+  sell     inside the sell run, with selling on: gives its rating, to the
+           house first and the rest to the grid.
+  charge   inside the cheap run: charges from the grid.
+  rest     another battery charges from the grid, so this one may not charge
+           (the owner's 2026-09-27 answer 3: while one battery charges from the
+           grid the others cannot give power either; the allocator never
+           splits a target both ways).
+
+Rules that keep this safe (tests: test_modes_p3.py):
+  * every range holds 0 W (a mode may forbid a direction, never force one);
+  * a Solar first battery never charges from the grid (no forecast yet, P4);
+  * grid charging needs a measured peak guard that is clear and a measured
+    headroom (SAFETY-45); the trade is sized to that headroom, whose aim is
+    `peak_cap_w - peak_margin_w` (SAFETY-79). It starts only at START_W or
+    more, and once the guard or the headroom stops it, it stays stopped for
+    the rest of that 15-minute period (`blocked`): a charge makes the other
+    batteries stop giving power, so a few watts of charge flipping on and
+    off would swing the house between them and the grid (measured on the
+    2026-09-09 replay: 13 flips in 4 minutes at a 3.5 kW house);
+  * selling needs selling on for that battery, the sell run, a price >= 0
+    now, and the battery above `arbitrage_soc_floor`; it stops there. The
+    peak guard never stops a sell (section 9.1: discharge is never capped);
+    it must only have measured the quarter;
+  * a battery out of a run (full, or at the floor) stays out until the run
+    ends, so the ceiling and the floor do not re-arm within one run;
+  * a battery that refuses a direction (SAFETY-52/73) takes no part in a
+    run in that direction: the refusal wins over the run;
+  * no grid charge while another battery drains for its monthly cycle
+    (`draining`, SAFETY-78): it would charge against the drain.
+"""
+
+from dataclasses import dataclass
+
+from .packmode import (CHEAP_HOURS, GRID_CHARGE_MODES, LEFTOVER_SOLAR,
+                       SOLAR_FIRST)
+
+OFF, HOUSE, HOLD, GIVE, SELL, CHARGE, REST = (
+    "off", "house", "hold", "give", "sell", "charge", "rest")
+PRICE_MODES = (LEFTOVER_SOLAR, CHEAP_HOURS)
+
+# The smallest grid charge worth starting, in W. Under it the other batteries
+# would stop covering the house for less than they give.
+START_W = 500.0
+
+
+@dataclass(frozen=True)
+class Pack:
+    """One battery as this module needs it."""
+    name: str
+    use: bool
+    mode: str
+    sell: bool
+    rating_w: float
+    soc: float | None
+    capacity_kwh: float | None
+    live: bool = True
+    idle: bool = True           # not in a maintenance phase
+    refused: int = 0            # SAFETY-52/73: +1 refuses to give, -1 to charge
+
+
+@dataclass(frozen=True)
+class Tick:
+    ranges: dict                # name -> (lo, hi), only for idle batteries
+    roles: dict                 # name -> role
+    action: str | None          # "charge" | "sell" | None
+    ask_w: float                # signed site ask before sizing (0 if none)
+    why: str | None             # why no trade when a run is on, else None
+
+
+def _room_kwh(p: Pack, pct: float) -> float:
+    """kWh to `pct` (charging) or above it (selling); a battery with no
+    capacity set counts one hour at its rating, so a run is still sized."""
+    if p.capacity_kwh is None or p.soc is None:
+        return abs(p.rating_w) / 1000.0
+    return max(0.0, abs(pct - p.soc)) / 100.0 * float(p.capacity_kwh)
+
+
+def chargers(packs, ceiling_pct, done=()) -> list:
+    """Batteries that may charge from the grid in a cheap run: the modes in
+    `packmode.GRID_CHARGE_MODES` (Cheap hours only until P4's forecast)."""
+    return [p for p in packs
+            if p.use and p.idle and p.live and p.mode in GRID_CHARGE_MODES
+            and p.soc is not None and p.soc < ceiling_pct
+            and p.refused >= 0 and p.name not in done]
+
+
+def sellers(packs, floor_pct, done=()) -> list:
+    """Batteries that may sell in the sell run. Solar first never sells."""
+    return [p for p in packs
+            if p.use and p.idle and p.live and p.sell
+            and p.mode in PRICE_MODES
+            and p.soc is not None and p.soc > floor_pct
+            and p.refused <= 0 and p.name not in done]
+
+
+def energy(packs, floor_pct, ceiling_pct, done_charge=(), done_sell=()):
+    """`(charge_kwh, charge_kw, sell_kwh, sell_kw)` for `priceruns.plan()`."""
+    ch = chargers(packs, ceiling_pct, done_charge)
+    se = sellers(packs, floor_pct, done_sell)
+    return (sum(_room_kwh(p, ceiling_pct) for p in ch),
+            sum(abs(p.rating_w) for p in ch) / 1000.0,
+            sum(_room_kwh(p, floor_pct) for p in se),
+            sum(abs(p.rating_w) for p in se) / 1000.0)
+
+
+def decide(runs, now, packs, *, charge_ok, sell_ok, trade_why, price_now,
+           headroom_w, floor_pct, ceiling_pct, house_w, charging_now=False,
+           blocked=False, done_charge=(), done_sell=(),
+           draining=False) -> Tick:
+    """This tick's ranges, roles and site ask.
+
+    `runs` is the kept `priceruns.RunPlan` or None (no fresh prices).
+    `charge_ok` is True only when `TariffPlan.arbitrage()` allowed a trade
+    this tick with the MEASURED peak guard clear; `sell_ok` when it allowed
+    one with the guard measured (either state); else `trade_why` says why.
+    `headroom_w` is `peakguard.charge_headroom_w()` (None: unmeasured).
+    `house_w` is the measured house (grid + batteries), or None.
+    `charging_now` says last tick charged (then any headroom above 0 keeps
+    it going); `blocked` that the guard or the headroom stopped a charge in
+    this 15-minute period. `draining` says a battery drains for its
+    monthly cycle, so none may charge from the grid (why "cycle").
+    """
+    plan_on = runs is not None and runs.on
+    in_cheap = plan_on and runs.cheap.holds(now) and runs.charge_useful()
+    in_give = plan_on and runs.give_at(now) is not None
+    in_sell = plan_on and runs.sell is not None and runs.sell.holds(now)
+
+    why = None
+    ch = chargers(packs, ceiling_pct, done_charge) if in_cheap else []
+    if ch and draining:
+        ch, why = [], "cycle"
+    charging = False
+    if ch:
+        need = 0.0 if charging_now else START_W
+        if blocked:
+            why = "headroom"
+        elif not charge_ok:
+            why = trade_why
+        elif headroom_w is None or not headroom_w > need:
+            why = "headroom"
+        else:
+            charging = True
+    se = sellers(packs, floor_pct, done_sell) if in_sell and not charging \
+        else []
+    selling = False
+    if se:
+        if not sell_ok:
+            why = why or trade_why
+        elif price_now is None or price_now < 0.0 or house_w is None:
+            why = why or "negative"
+        else:
+            selling = True
+
+    ranges, roles = {}, {}
+    ch_names = {p.name for p in ch} if charging else set()
+    se_names = {p.name for p in se} if selling else set()
+    for p in packs:
+        r = abs(float(p.rating_w))
+        if not p.use:
+            role, lo, hi = OFF, 0.0, 0.0
+        elif p.name in ch_names:
+            role, lo, hi = CHARGE, -r, 0.0
+        elif charging:
+            # Another battery charges from the grid: this one may not charge
+            # (it would be grid charging too), and cannot give (one sign).
+            role, lo, hi = REST, 0.0, (r if p.mode == SOLAR_FIRST
+                                       or not plan_on or in_give else 0.0)
+        elif p.name in se_names:
+            role, lo, hi = SELL, -r, r
+        elif p.mode == SOLAR_FIRST or not plan_on:
+            role, lo, hi = HOUSE, -r, r
+        elif in_give:
+            role, lo, hi = GIVE, -r, r
+        else:
+            role, lo, hi = HOLD, -r, 0.0
+        roles[p.name] = role
+        if p.idle:
+            ranges[p.name] = (lo, hi)
+
+    if charging:
+        ask = -sum(abs(p.rating_w) for p in ch)
+        return Tick(ranges, roles, CHARGE, ask, None)
+    if selling:
+        ask = sum(abs(p.rating_w) for p in se) + max(0.0, float(house_w))
+        return Tick(ranges, roles, SELL, ask, None)
+    return Tick(ranges, roles, None, 0.0,
+                why if (in_cheap or in_sell) else None)
+
+
+def size(tick: Tick, bound, headroom_w) -> float:
+    """The site trade in W, inside what the batteries may place with their
+    modes (`bound` = main's loop bound) and, for a charge, the billed
+    quarter's headroom. 0.0 means no trade (a 0 W trade is a park order and
+    is never filed)."""
+    if tick.action is None or bound is None:
+        return 0.0
+    lo, hi = bound
+    if tick.action == CHARGE:
+        cap = min(-float(tick.ask_w), -float(lo),
+                  float(headroom_w) if headroom_w is not None else 0.0)
+        return -max(0.0, cap)
+    return max(0.0, min(float(tick.ask_w), float(hi)))
+
+
+def weights(roles: dict, base, target_w: float):
+    """Who carries the site target first (design 3.5). Selling: the sellers.
+    Giving power: batteries in a give run before Solar first. Charging from
+    the grid: only the chargers. Otherwise `base` unchanged. Comfort only;
+    the ranges above are the permission."""
+    names = sorted(roles)
+    first = None
+    if target_w > 0 and any(r == SELL for r in roles.values()):
+        first = {n for n in names if roles[n] == SELL}
+    elif target_w > 0 and any(r == GIVE for r in roles.values()):
+        first = {n for n in names if roles[n] in (GIVE, SELL)}
+    elif target_w < 0 and any(r == CHARGE for r in roles.values()):
+        first = {n for n in names if roles[n] == CHARGE}
+    if not first:
+        return base
+    w = {n: (1.0 if base is None else float(base.get(n, 1.0))) for n in names}
+    out = {n: (w[n] if n in first else 0.0) for n in names}
+    return out if any(v > 0.0 for v in out.values()) else base

goodwe_controller/app/mqtt.py

@@ -453,7 +453,8 @@ def discovery_payloads(units=(), omit=(), include=(), modes=()) -> list:
 #
 # The select's options are these labels, in `packmode.MODES` order. A new mode
 # (P3) is a new entry here and a new option at the end; no id changes.
-MODE_LABELS = {"solar_first": "Solar first", "leftover_solar": "Leftover solar"}
+MODE_LABELS = {"solar_first": "Solar first", "leftover_solar": "Leftover solar",
+               "cheap_hours": "Cheap hours only"}         # OPT-11 P3
 USE_ON, USE_OFF = "ON", "OFF"
 # A longer command payload is refused before it is decoded.
 MAX_COMMAND_BYTES = 64

goodwe_controller/app/packmode.py

@@ -1,4 +1,4 @@
-"""OPT-11 P1: each battery's mode and on/off switch, as limits and weights.
+"""OPT-11: each battery's mode and on/off switch, as limits and weights.
 
 Pure: no I/O, no clock. main.py reads the store, calls these, and files the
 result as a `mode` claim (arbiter.P_MODE) and as the charge weights.
@@ -14,13 +14,11 @@ Two rules hold for every mode, and they are what keeps modes safe:
    allocator._fill()'s last-resort pass still uses it. So "may not" is a range,
    and weights only set the order among batteries that may.
 
-P1 has no price runs and no forecast (P3, P4). So both modes give power to the
-house at any hour, and the only mode that closes a direction is Off. What P1
-changes is the solar order: while the site charges, Leftover solar batteries
-weigh 0, so they get solar only once the Solar first batteries are full or at
-their power limit. Selling (the owner's 2026-09-27 answer) is a per-battery
-choice that arrives with the price runs in P3; `PackMode.sell` and the
-`pack_sell` store key are reserved for it and read by nothing yet.
+`mode_range()` is the switch alone (Off is [0, 0]). P3 adds the price runs:
+`modetrade.decide()` narrows each battery's range by its role this tick
+(hold for the expensive hours, charge from the grid, sell), and main.py files
+the intersection. Selling is a per-battery choice (`pack_sell`, the owner's
+2026-09-27 answer), for Leftover solar and Cheap hours only.
 """
 
 from dataclasses import dataclass
@@ -29,17 +27,29 @@ from .store import unit_key
 
 SOLAR_FIRST = "solar_first"
 LEFTOVER_SOLAR = "leftover_solar"
-CHEAP_HOURS = "cheap_hours"         # reserved for P3; not accepted in P1
+CHEAP_HOURS = "cheap_hours"         # OPT-11 P3
 
-# The modes a battery may be set to in this release, in the order the page
-# lists them. The first is the default when the store has no value.
-MODES = (SOLAR_FIRST, LEFTOVER_SOLAR)
+# The modes a battery may be set to, in the order the page and the HA select
+# list them. The first is the default when the store has no value. A new mode
+# is appended, never inserted: automations send the HA labels (P2).
+MODES = (SOLAR_FIRST, LEFTOVER_SOLAR, CHEAP_HOURS)
 DEFAULT_MODE = SOLAR_FIRST
 
 # Store keys, per battery: `unit/<name>/<key>` (store.unit_key()).
 USE_KEY = "pack_use"
 MODE_KEY = "pack_mode"
-SELL_KEY = "pack_sell"              # reserved for P3
+SELL_KEY = "pack_sell"              # OPT-11 P3: sell in the sell run
+
+# Owner decision 2026-09-29 (option A): selling is off until it can be judged
+# on the price the grid pays. While False, `read()` answers `sell=False`
+# whatever the store holds, the page shows no switch and `pack_sell` is
+# refused; the sell code in modetrade/priceruns stays, unreachable.
+SELLING_ENABLED = False
+
+# The modes that may charge from the grid in a cheap run. Leftover solar joins
+# when the solar forecast exists (P4); until then it takes solar only (owner
+# decision 2026-09-29, option A).
+GRID_CHARGE_MODES = (CHEAP_HOURS,)
 
 
 def enabled(opts) -> bool:
@@ -50,10 +60,16 @@ def enabled(opts) -> bool:
 
 @dataclass(frozen=True)
 class PackMode:
-    """One battery's choice: on or off, its mode, and (P3) selling."""
+    """One battery's choice: on or off, its mode, and selling."""
     use: bool = True
     mode: str = DEFAULT_MODE
-    sell: bool = False              # reserved for P3, never read in P1
+    sell: bool = False
+
+    @property
+    def can_sell(self) -> bool:
+        """Selling applies to the price modes only; Solar first never sells.
+        False for every battery while SELLING_ENABLED is False."""
+        return SELLING_ENABLED and self.mode in (LEFTOVER_SOLAR, CHEAP_HOURS)
 
     @property
     def key(self) -> str:
@@ -69,15 +85,15 @@ def read(data: dict, name: str) -> PackMode:
     mode = data.get(unit_key(name, MODE_KEY), DEFAULT_MODE)
     return PackMode(use=use is not False,
                     mode=mode if mode in MODES else DEFAULT_MODE,
-                    sell=data.get(unit_key(name, SELL_KEY)) is True)
+                    sell=SELLING_ENABLED
+                    and data.get(unit_key(name, SELL_KEY)) is True)
 
 
 def mode_range(pm: PackMode, rating_w: float) -> tuple:
-    """`(lo, hi)` in W for this battery's mode claim. Always holds 0 W.
+    """`(lo, hi)` in W for this battery's switch. Always holds 0 W.
 
-    Off asks for 0 W both ways. In P1 both modes may charge and give power up
-    to the battery's rating: Leftover solar holds back its power only in the
-    planned expensive hours, and there are none before P3.
+    Off asks for 0 W both ways; On allows the rating both ways. main.py files
+    this intersected with the role range from `modetrade.decide()`.
     """
     if not pm.use:
         return 0.0, 0.0
@@ -92,7 +108,7 @@ def charge_weights(base, modes: dict, target_w: float):
     charges (`target_w < 0`), a Leftover solar battery weighs 0 and a Solar
     first battery keeps its weight, so the fill gives the Solar first batteries
     everything they can take before the last-resort pass reaches the others.
-    Giving power keeps `base` (P3 adds the expensive-run order).
+    Giving power keeps `base`; `modetrade.weights()` adds the run order.
 
     When no battery that is on would keep a positive weight (all Leftover
     solar, or every Solar first one at 0), `base` is returned unchanged, so the
@@ -102,7 +118,8 @@ def charge_weights(base, modes: dict, target_w: float):
         return base
     names = sorted(modes)
     w = {n: (1.0 if base is None else float(base.get(n, 1.0))) for n in names}
-    out = {n: (0.0 if modes[n].mode == LEFTOVER_SOLAR else w[n])
+    out = {n: (0.0 if modes[n].mode in (LEFTOVER_SOLAR, CHEAP_HOURS)
+               else w[n])
            for n in names}
     if not any(out[n] > 0.0 for n in names if modes[n].use):
         return base

goodwe_controller/app/peakguard.py

@@ -143,6 +143,10 @@ because the money is spent on `max(month's peak so far, this quarter)`:
 
     ceiling_w = max(peak_cap_w, the month's banked peak)
 
+SAFETY-79: the guard AIMS `peak_margin_w` under that ceiling
+(`quarter_target_w()`), so a quarter that lands a little high still stays under
+it. `ceiling_w` stays the real limit for reports and the bill.
+
 Once a month's peak already stands at 5013 W, holding every later quarter to
 3500 W buys nothing - the bill for that month is already 5013 W - while the
 holding itself costs real charging the site wanted. Raising the ceiling to a peak
@@ -453,7 +457,13 @@ PEAK_OPTION_DEFAULTS = {
     # and it is consistent with DoD 90 on a full pack. It exists so validate.py
     # rule 8 can refuse a `peak_soc_floor` at or below it - see that rule.
     "bms_soc_floor": 10,
+    # SAFETY-79. Watts the guard aims under `peak_cap_w`, so a quarter that
+    # lands a little high still stays under the cap. Owner decision 2026-09-28.
+    "peak_margin_w": 50,
 }
+# SAFETY-79. config.yaml's schema range for `peak_margin_w`, mirrored so
+# validate.py can refuse it in words; test_peakguard.py pins it to the file.
+PEAK_MARGIN_RANGE_W = (0, 500)
 
 
 @dataclass(frozen=True)
@@ -474,6 +484,7 @@ class PeakDecision:
     projected_w: float | None = None
     excess_w: float = 0.0
     wanted_w: float | None = None    # the floor before `achievable_w` clamped it
+    target_w: float | None = None    # SAFETY-79: what the guard aims at
     saturated: bool = False
     # SAFETY-24. True when a forced discharge WAS wanted and the EMS-side SoC
     # floor refused to size it. Mutually exclusive with `saturated` by
@@ -524,6 +535,15 @@ def quarter_ceiling_w(cap_w, reading) -> tuple[float, str]:
     return cap, CEILING_CAP
 
 
+def quarter_target_w(cap_w, margin_w, reading) -> float:
+    """SAFETY-79. The average the guard AIMS at: `margin_w` under
+    `quarter_ceiling_w()`, so under a month peak already banked as well as
+    under the cap. Aiming AT a banked peak can bank a few W over it, which
+    raises the bill as surely as going over the cap. Reports and the bill keep
+    the real limit (`ceiling_w`)."""
+    return quarter_ceiling_w(cap_w, reading)[0] - float(margin_w)
+
+
 def excess_w(projection, ceiling_w) -> float:
     """Watts that must come off the meter NOW to land the quarter on the ceiling.
 
@@ -713,8 +733,8 @@ def binding_soc_floor(packs, soc_floor):
     return max(floors)
 
 
-def decide(projection, *, batt_w, cap_w, reading, achievable_w, soc, soc_floor,
-           max_hold_s=None, frozen: bool = False) -> PeakDecision:
+def decide(projection, *, batt_w, cap_w, margin_w, reading, achievable_w, soc,
+           soc_floor, max_hold_s=None, frozen: bool = False) -> PeakDecision:
     """The whole guard. Pure: no clock, no I/O, no state carried between calls.
 
     `batt_w`       MEASURED battery power, positive = discharge. None when the
@@ -732,8 +752,13 @@ def decide(projection, *, batt_w, cap_w, reading, achievable_w, soc, soc_floor,
                    the pack for money. REQUIRED, and deliberately without a
                    default: a default here would be CFG-03's fourth defaults
                    site and TEST-14's quiet fallback in one line.
+    `margin_w`     SAFETY-79. Watts to aim under `cap_w` (`peak_margin_w`).
+                   REQUIRED for the same reason. `ceiling_w` stays the real
+                   limit for every report; only `excess_w` uses the target.
     """
     ceiling, from_where = quarter_ceiling_w(cap_w, reading)
+    target = quarter_target_w(cap_w, margin_w, reading)
+    aim = "" if target == ceiling else f", aiming at {target:.0f} W"
     ceil_top = abs(float(achievable_w))
 
     blind = blindness(projection, max_hold_s, frozen)
@@ -743,7 +768,7 @@ def decide(projection, *, batt_w, cap_w, reading, achievable_w, soc, soc_floor,
         # see", which is one-directional and cannot cost pack energy.
         return PeakDecision(
             engaged=True, floor_w=0.0, ceiling_w=ceiling, ceiling_from=from_where,
-            blind=blind, projected_w=None,
+            target_w=target, blind=blind, projected_w=None,
             reason=(f"PEAK_GUARD_BLIND: {blind}. The battery may not charge "
                     f"while this 15-minute period cannot be measured, so it "
                     f"is asked for no charging, floor 0 W"))
@@ -755,7 +780,7 @@ def decide(projection, *, batt_w, cap_w, reading, achievable_w, soc, soc_floor,
         # measurement that is not there is a made-up number.
         return PeakDecision(
             engaged=False, floor_w=None, ceiling_w=ceiling,
-            ceiling_from=from_where, projected_w=projected,
+            ceiling_from=from_where, target_w=target, projected_w=projected,
             reason="no battery measurement to size a floor from")
     if QUARTER_S - float(projection.elapsed_s) <= 0.0:
         # A block with no seconds left cannot be influenced. This is degenerate
@@ -763,10 +788,10 @@ def decide(projection, *, batt_w, cap_w, reading, achievable_w, soc, soc_floor,
         # the battery's own current output would be a claim that says nothing.
         return PeakDecision(
             engaged=False, floor_w=None, ceiling_w=ceiling,
-            ceiling_from=from_where, projected_w=projected,
+            ceiling_from=from_where, target_w=target, projected_w=projected,
             reason="the quarter has no seconds left to influence")
 
-    ex = excess_w(projection, ceiling)
+    ex = excess_w(projection, target)
     wanted = float(batt_w) + ex
     if wanted <= 0.0:
         # ⚠️ THE TEST IS ON THE FLOOR, NOT ON `excess > 0`, AND THE REPLAY IS WHY.
@@ -787,7 +812,8 @@ def decide(projection, *, batt_w, cap_w, reading, achievable_w, soc, soc_floor,
         # the quantity being thresholded is simply the right one.
         return PeakDecision(
             engaged=False, floor_w=None, ceiling_w=ceiling,
-            ceiling_from=from_where, projected_w=projected, excess_w=ex,
+            ceiling_from=from_where, target_w=target, projected_w=projected,
+            excess_w=ex,
             wanted_w=wanted,
             reason="the load is under the level this quarter can afford")
 
@@ -805,7 +831,8 @@ def decide(projection, *, batt_w, cap_w, reading, achievable_w, soc, soc_floor,
         # not the grid-following loop, which still has no SoC guard.
         return PeakDecision(
             engaged=True, floor_w=0.0, ceiling_w=ceiling,
-            ceiling_from=from_where, projected_w=projected, excess_w=ex,
+            ceiling_from=from_where, target_w=target, projected_w=projected,
+            excess_w=ex,
             wanted_w=wanted, floor_limited=True, soc=soc, soc_floor=soc_floor,
             soc_floor_reason=denied,
             # UX-10: plain sentences, every figure kept (test_messages.py
@@ -813,8 +840,8 @@ def decide(projection, *, batt_w, cap_w, reading, achievable_w, soc, soc_floor,
             reason=(
                 f"PEAK_GUARD_FLOOR_LIMITED: this 15-minute period heads for "
                 f"{projected:.0f} W against a {ceiling:.0f} W limit "
-                f"({from_where}), and {wanted:+.0f} W from the battery would "
-                f"hold it. But {denied}"
+                f"({from_where}){aim}, and {wanted:+.0f} W from the battery "
+                f"would hold it. But {denied}"
                 + ("" if soc is None else f", at {float(soc):.0f} %")
                 + ("" if soc is None or soc_floor is None
                    else f" against {float(soc_floor):.0f} %")
@@ -825,11 +852,11 @@ def decide(projection, *, batt_w, cap_w, reading, achievable_w, soc, soc_floor,
     saturated = floor < wanted
     return PeakDecision(
         engaged=True, floor_w=floor, ceiling_w=ceiling, ceiling_from=from_where,
-        blind=None, projected_w=projected, excess_w=ex, wanted_w=wanted,
-        saturated=saturated, soc=soc, soc_floor=soc_floor,
+        target_w=target, blind=None, projected_w=projected, excess_w=ex,
+        wanted_w=wanted, saturated=saturated, soc=soc, soc_floor=soc_floor,
         reason=(
             f"PEAK_GUARD: this 15-minute period heads for {projected:.0f} W "
-            f"against a {ceiling:.0f} W limit ({from_where}), with "
+            f"against a {ceiling:.0f} W limit ({from_where}){aim}, with "
             f"{QUARTER_S - projection.elapsed_s:.0f} s left, so {ex:.0f} W must "
             f"come off the meter. The battery measured {float(batt_w):+.0f} W "
             f"and is asked for {floor:+.0f} W"
@@ -839,6 +866,40 @@ def decide(projection, *, batt_w, cap_w, reading, achievable_w, soc, soc_floor,
                if saturated else "")))
 
 
+# SAFETY-81. A quarter must end this many W over the real limit before
+# "Load too high for battery" fires. Above the guard's own landing error at
+# margin 0 (up to +5.7 W, SAFETY-79 test check 5), which margin 0 accepts.
+ALARM_MISS_W = 10.0
+# ...and for this long without a break, so a load that peaks for a few seconds
+# (a hob or heater cycling) is not read as the rest of the quarter.
+ALARM_HOLD_S = 10.0
+
+
+def load_too_high(projection, *, batt_w, ceiling_w, achievable_w) -> bool:
+    """SAFETY-81. May "Load too high for battery" fire? Only if, with the
+    battery at full power from now on, the quarter still ends more than
+    `ALARM_MISS_W` over the real limit (`ceiling_w`, not the aim).
+
+    This is the miss itself, in W of the quarter average, so it does not have
+    `decide()`'s gain (900 / remaining): near a quarter's end that gain turns
+    a watt over the aim into thousands of W wanted.
+
+    The load is the held meter reading plus `batt_w`. The caller passes the
+    lower of this cycle's and the last cycle's battery reading, so a meter
+    sample taken before the battery's last increase is not counted twice
+    (DECISIONS/SAFETY-81-load-too-high.md). A real overload shows on the meter
+    before the battery moves, so that filter costs it no cycle.
+    """
+    remaining = QUARTER_S - float(projection.elapsed_s)
+    if batt_w is None or remaining <= 0.0:
+        return False
+    rest = float(projection.held_w) + float(batt_w) - float(achievable_w)
+    done_ws = (QUARTER_S * float(projection.projected_w)
+               - max(float(projection.held_w), 0.0) * remaining)
+    ends_w = (done_ws + max(rest, 0.0) * remaining) / QUARTER_S
+    return ends_w - float(ceiling_w) > ALARM_MISS_W
+
+
 def charge_headroom_w(decision) -> float | None:
     """SAFETY-45. The hardest this SITE may charge without putting the billed
     quarter over the ceiling, in W, positive - or None when nothing measured it.

goodwe_controller/app/priceruns.py

@@ -0,0 +1,203 @@
+"""OPT-11 P3: price runs. Which consecutive firm price slots are cheap, which
+are expensive, and which one a battery may sell in.
+
+Pure: prices, the time and a few energy figures in, a `RunPlan` out. No I/O,
+no clock. `modetrade.py` turns the plan into each battery's range and the
+site's trade; main.py rebuilds the plan at most once per 15 minutes and keeps
+a run that has started until its end (`keep_started()`).
+
+The owner's SAFETY-46 answer (2026-09-25): a trade is a run of consecutive
+slots, not one 15-minute interval. OPT-11-design section 2 ("Prices") and
+DECISIONS/OPT-11-battery-modes.md have the record.
+
+* The CHEAP run is the cheapest consecutive firm window long enough to put
+  the planned energy in at the chargers' combined rating.
+* A slot is EXPENSIVE when its price is above the cheap run's mean by at
+  least the required spread (`cycle_cost_threshold_eur`, widened as
+  `TariffPlan.arbitrage()` widens it). Give runs are the maximal consecutive
+  expensive slots. Holding batteries cover the house in them. The mean is
+  the lower of the next cheap run's and `ref_eur_kwh`, the cheap run the
+  batteries last filled in (main.py keeps it for 12 h): energy bought at
+  03:00 is still worth that price at 08:00, when the next cheap run in sight
+  is today's dearer midday (measured: without it a Cheap hours battery spent
+  its night charge on flat morning prices, then had nothing at 19:00).
+* The SELL run is the dearest consecutive window inside one give run long
+  enough to sell the sellers' energy at their rating, with no slot below 0
+  (section 17 of the spec: never export at a negative price).
+* A provisional (carried) price is never part of any run (section 8.3).
+"""
+
+import math
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+
+from .price import _cover_table
+
+# How far ahead runs are looked for. A day: tonight's cheap hours and the next
+# evening's expensive ones, without holding a battery for a peak two days out.
+HORIZON = timedelta(hours=24)
+
+# No plan, and why (the page words are in homeview / ui_text).
+NO_PRICES = "no_prices"           # fewer than two firm slots ahead
+NOT_WORTH = "not_worth"           # no slot clears the required spread
+
+
+@dataclass(frozen=True)
+class Run:
+    start: datetime
+    end: datetime
+    mean_eur_kwh: float
+
+    def holds(self, when: datetime) -> bool:
+        return self.start <= when < self.end
+
+
+@dataclass(frozen=True)
+class RunPlan:
+    """What the prices say for the next day. `reason` is None when there is
+    a plan (a cheap run and at least one give run), else why there is none."""
+    cheap: Run | None
+    give: tuple
+    sell: Run | None
+    level_eur_kwh: float | None
+    reason: str | None
+    # A slot after the cheap run clears the spread over the CHEAP RUN'S OWN
+    # price (not the reference): only then is buying in it worth a cycle.
+    charge_worth: bool = False
+
+    @property
+    def on(self) -> bool:
+        return self.reason is None
+
+    def give_at(self, when):
+        return next((g for g in self.give if g.holds(when)), None)
+
+    def next_give(self, when):
+        """The give run under way at `when`, else the next one, else None."""
+        return next((g for g in self.give if g.end > when), None)
+
+    def charge_useful(self) -> bool:
+        """Charging in the cheap run pays only if, after it, a slot clears
+        the spread over the cheap run's own price."""
+        return self.cheap is not None and self.charge_worth
+
+
+def firm_slots(points, now: datetime, horizon: timedelta = HORIZON) -> list:
+    """`[(start, end, eur_kwh)]`, ascending: the firm slots that have not
+    ended and start within the horizon. A slot's span is TARIFF-14's rule
+    (`price._cover_table()`), so 15-minute and hourly series both work."""
+    out = []
+    for start, end, p in _cover_table(points):
+        if p.provisional or end <= now or start >= now + horizon:
+            continue
+        if end > start:
+            out.append((start, end, float(p.eur_per_kwh)))
+    return out
+
+
+def _segments(slots) -> list:
+    """Split slots into runs of consecutive ones (each starts where the last
+    ended). A gap or a provisional slot breaks a run."""
+    segs, cur = [], []
+    for s in slots:
+        if cur and s[0] != cur[-1][1]:
+            segs.append(cur)
+            cur = []
+        cur.append(s)
+    if cur:
+        segs.append(cur)
+    return segs
+
+
+def _hours(s) -> float:
+    return (s[1] - s[0]).total_seconds() / 3600.0
+
+
+def _mean(win) -> float:
+    h = sum(_hours(s) for s in win)
+    return sum(_hours(s) * s[2] for s in win) / h
+
+
+def _windows(segs, need_h):
+    """Every consecutive window that lasts at least `need_h` hours, shortest
+    such from each start. If no segment is that long, each whole segment."""
+    out = []
+    for seg in segs:
+        for i in range(len(seg)):
+            h, j = 0.0, i
+            while j < len(seg) and h < need_h - 1e-9:
+                h += _hours(seg[j])
+                j += 1
+            if h >= need_h - 1e-9:
+                out.append(seg[i:j])
+    return out or [seg for seg in segs]
+
+
+def need_hours(kwh, kw, slots) -> float:
+    """How long a run must last: `kwh` at `kw`, and at least one slot."""
+    one = min((_hours(s) for s in slots), default=1.0)
+    if not (kwh and kw) or kwh <= 0 or kw <= 0:
+        return one
+    return max(one, float(kwh) / float(kw))
+
+
+def plan(points, now: datetime, *, required_eur_kwh: float, charge_kwh,
+         charge_kw, sell_kwh, sell_kw, horizon: timedelta = HORIZON,
+         ref_eur_kwh=None) -> RunPlan:
+    """The run plan for the next `horizon`. Ties go to the earliest window."""
+    if not (isinstance(required_eur_kwh, (int, float))
+            and math.isfinite(required_eur_kwh) and required_eur_kwh >= 0):
+        raise ValueError("required_eur_kwh must be a finite number >= 0")
+    slots = firm_slots(points, now, horizon)
+    if len(slots) < 2:
+        return RunPlan(None, (), None, None, NO_PRICES)
+    segs = _segments(slots)
+    wins = _windows(segs, need_hours(charge_kwh, charge_kw, slots))
+    best = min(wins, key=lambda w: (round(_mean(w), 9), w[0][0]))
+    cheap = Run(best[0][0], best[-1][1], _mean(best))
+    base = cheap.mean_eur_kwh if ref_eur_kwh is None else min(
+        cheap.mean_eur_kwh, float(ref_eur_kwh))
+    level = base + float(required_eur_kwh)
+    # Expensive: clears the spread, strictly dearer than the cheap mean, and
+    # not part of the cheap run itself (a threshold of 0 must not overlap).
+    dear = [s for s in slots
+            if s[2] >= level and s[2] > cheap.mean_eur_kwh
+            and not (cheap.start <= s[0] < cheap.end)]
+    give_segs = _segments(dear)
+    give = tuple(Run(g[0][0], g[-1][1], _mean(g)) for g in give_segs)
+    worth = any(s[0] >= cheap.end and s[2] >= cheap.mean_eur_kwh
+                + float(required_eur_kwh) for s in dear)
+    if not give:
+        return RunPlan(cheap, (), None, level, NOT_WORTH)
+    # Sell: inside one give run, never over a slot priced below 0.
+    sellable = [part for g in give_segs
+                for part in _segments([s for s in g if s[2] >= 0.0])]
+    sell = None
+    if sellable:
+        sw = _windows(sellable, need_hours(sell_kwh, sell_kw, slots))
+        top = max(sw, key=lambda w: (round(_mean(w), 9),
+                                     -w[0][0].timestamp()))
+        sell = Run(top[0][0], top[-1][1], _mean(top))
+    return RunPlan(cheap, give, sell, level, None, worth)
+
+
+def keep_started(old: RunPlan | None, new: RunPlan, now: datetime) -> RunPlan:
+    """A run under way keeps going to its end (no flapping on a new plan): the
+    cheap run, the give run and the sell run each come from `old` while `old`
+    holds `now` in it. The rest is `new`. A safety or peak rule can still stop
+    a run at any tick; that is not decided here."""
+    if old is None or not old.on:
+        return new
+    cheap = old.cheap if old.cheap and old.cheap.holds(now) else new.cheap
+    sell = old.sell if old.sell and old.sell.holds(now) else new.sell
+    g_old = old.give_at(now)
+    give = new.give
+    if g_old is not None:
+        give = (g_old,) + tuple(g for g in new.give
+                                if g.start >= g_old.end)
+    if cheap is new.cheap and sell is new.sell and g_old is None:
+        return new
+    worth = old.charge_worth if cheap is old.cheap else new.charge_worth
+    return RunPlan(cheap, give, sell, new.level_eur_kwh if new.on
+                   else old.level_eur_kwh, None if give else new.reason,
+                   worth)

goodwe_controller/app/static/app.js

@@ -314,11 +314,11 @@
   /* ---------------- Batteries (UX-13 P3) ---------------- */
   // One card per battery. With battery modes on (`mode_key` in /status) each
   // card has an On/Off switch and a mode list, sent as `pack_use` and
-  // `pack_mode` through /action (OPT-11 P1). Selling and cheap-hours charging
-  // are shown greyed out until OPT-11 P3. The Now, Today and Why lines are
+  // `pack_mode` through /action (OPT-11 P1). Selling has no switch while it
+  // is off (owner decision 2026-09-29). The Now, Today and Why lines are
   // homeview.py's sentences. The Simple settings view draws the same switch
   // and list into its own card (simpleHost).
-  const MODES = ["solar_first", "leftover_solar"];
+  const MODES = ["solar_first", "leftover_solar", "cheap_hours"];
   const say = (text, vars) => Object.keys(vars).reduce((x, k) => x.replace("{" + k + "}", vars[k]), text);
   let packBusy = false;
   let simpleHost = null;
@@ -345,15 +345,7 @@
   function modeSelect(b, i, where, lid) {
     return h("select", { class: "sel", id: "bsel-" + where + i, "aria-labelledby": lid, disabled: !b.use,
                          onchange: (e) => packAct("pack_mode", b, e.target.value) },
-      ...MODES.map((k) => h("option", { value: k, selected: b.mode_choice === k }, t("batteries.choice." + k + ".name"))),
-      h("option", { value: "", disabled: true }, t("batteries.later")));
-  }
-  function sellRow(i, where) {
-    const lid = "bsl-" + where + i;
-    return h("div", { class: "f inline" },
-      h("div", {}, h("div", { class: "lbl", id: lid }, t("batteries.sell.name")), h("div", { class: "help" }, t("batteries.sell.description"))),
-      h("div", { class: "ctl" }, h("button", { type: "button", class: "switch", role: "switch", "aria-checked": "false",
-                                               "aria-labelledby": lid, disabled: true })));
+      ...MODES.map((k) => h("option", { value: k, selected: b.mode_choice === k }, t("batteries.choice." + k + ".name"))));
   }
   function todayLines(b) {
     if (!b.today || !b.today.length) return b.today_line || "–";
@@ -372,8 +364,7 @@
       modes ? h("div", { class: "modebox" },
         h("label", { class: "lbl small", for: "bsel-c" + i }, t("batteries.mode")),
         modeSelect(b, i, "c", null),
-        h("div", { class: "help" }, t("batteries.choice." + b.mode_key + ".description")),
-        sellRow(i, "c")) : null,
+        h("div", { class: "help" }, t("batteries.choice." + b.mode_key + ".description"))) : null,
       levelBar(b.level_pct, b.name),
       h("dl", { class: "kv" },
         h("dt", {}, t("batteries.level")), h("dd", {}, lvl + stored),

goodwe_controller/app/ui_text/en.json

@@ -13,7 +13,7 @@
     "inverters.modes": {"name": "Battery modes"},
     "tariff.selling": {"name": "Charging and selling on price"},
     "tariff.feed": {"name": "Price feed details"},
-    "safety.peak": {"name": "Peak limit"},
+    "safety.peak": {"name": "Peak limit", "description": "The add-on aims a little below your limit, to be safe."},
     "safety.start": {"name": "Starting and stopping"},
     "safety.stops": {"name": "Safety stops", "description": "Measured on real hardware, so leave them unchanged."},
     "maintenance.support": {"name": "Support"}
@@ -87,18 +87,18 @@
       "on": "On", "off": "Off",
       "choice": {
         "solar_first": {"name": "Solar first", "description": "Charges from solar before the other batteries and covers the house."},
-        "leftover_solar": {"name": "Leftover solar", "description": "Charges from solar the other batteries cannot take, and covers the house."},
+        "leftover_solar": {"name": "Leftover solar", "description": "Gets solar the others cannot take, and gives power in expensive hours."},
+        "cheap_hours": {"name": "Cheap hours only", "description": "Charges in the cheapest hours and gives power in the expensive ones."},
         "off": {"name": "Off", "description": "Rests, and helps only when the peak limit needs it."}
       },
-      "later": "Cheap hours only, coming later",
       "today": "Today", "why": "Why",
-      "sell": {"name": "Sell in expensive hours", "description": "Selling comes in a later update."},
       "modes_off": {"name": "Battery modes are off"},
       "how": {"name": "How the modes work", "description": "Which battery gets solar first, and when each gives power.",
         "solar_first": {"description": "Solar first gets spare solar before the other batteries, and covers the house at any hour."},
-        "leftover_solar": {"description": "Leftover solar gets the solar the Solar first batteries cannot take, and also covers the house."},
+        "leftover_solar": {"description": "Leftover solar gets the solar the Solar first batteries cannot take, and saves its power for expensive hours."},
+        "cheap_hours": {"description": "Cheap hours only charges in the cheapest hours and gives power in the expensive ones."},
         "off": {"description": "Off rests the battery and starts no monthly cycle, but the peak limit may still use it."},
-        "rules": {"description": "The peak limit and the safety stops always come first, and charging from the grid and selling come later."}},
+        "rules": {"description": "The peak limit and the safety stops come first, and while one battery charges from the grid the others rest."}},
       "toast": {"on": "{name} is on.", "off": "{name} is off.", "mode": "{name}: {mode}."}},
     "settings": {"name": "Settings", "description": "The settings are grouped by task below.", "open": "Open the settings page"}
   },
@@ -209,7 +209,7 @@
         "5": {"name": "Peak limit", "description": "The grid stays under this limit, averaged over each 15-minute period."},
         "6": {"name": "Check and start", "description": "The add-on checks everything with its own start checks, then restarts."}
       },
-      "modes_later": {"description": "Choosing a mode for each battery comes in a later update."},
+      "modes_later": {"description": "After setup, turn on battery modes to choose a mode for each battery on the Batteries screen."},
       "kettle": {
         "name": "Check the direction",
         "description": "Read the meter, switch on a kettle, then read the meter again.",
@@ -250,7 +250,7 @@
   },
   "home_words": {
     "mode_house": "Follows the house",
-    "modes": {"solar_first": "Solar first", "leftover_solar": "Leftover solar", "off": "Off"},
+    "modes": {"solar_first": "Solar first", "leftover_solar": "Leftover solar", "cheap_hours": "Cheap hours only", "off": "Off"},
     "attn_shadow": "Shadow mode is on",
     "attn_shadow_body": "The add-on decides everything, but every inverter stays at 0 W.",
     "zero_held": "Held at 0 W",
@@ -326,10 +326,20 @@
       "leftover": "It gets the solar that Solar first batteries cannot take.",
       "leftover_alone": "No Solar first battery is on, so it gets solar first.",
       "covers_house": "It gives power to cover the house.",
-      "other_refuses": "{name} refuses to give power, so this battery takes over."
+      "other_refuses": "{name} refuses to give power, so this battery takes over.",
+      "other_cycle": "{name} is emptying for its monthly cycle. This one does not charge.",
+      "grid_charge": "Prices are low, so it charges from the grid.",
+      "rests_charge": "Another battery charges from the grid, so it rests.",
+      "selling": "Prices are high, so it sells to the grid.",
+      "expensive": "Prices are high, so it covers the house.",
+      "saves": "Saves its power for {at}.",
+      "saves_later": "Saves its power for higher prices.",
+      "no_prices": "No prices, so it follows the house.",
+      "no_spread": "Prices differ too little, so it follows the house."
     },
     "today": {
       "not_planned": "Not planned yet.",
+      "no_runs": "No cheap or expensive hours left today.",
       "off": "Off, so no monthly cycle today.",
       "house": "Follows the house.",
       "house_would": "Would follow the house.",
@@ -356,6 +366,10 @@
       "give_what": "Gives up to {kwh}, to the house first.",
       "give_what_would": "Would give up to {kwh}, to the house first.",
       "give_why": "Highest published price, {eur} per kWh.",
+      "sell_what": "Sells up to {kwh}, to the house first.",
+      "sell_what_would": "Would sell up to {kwh}, to the house first.",
+      "cheap_why": "Cheapest hours, about {eur} per kWh.",
+      "dear_why": "Expensive hours, about {eur} per kWh.",
       "give_amount": "Worth up to {eur} at that price.",
       "cycle_start": "Starts the monthly battery cycle.",
       "cycle_start_would": "Would start the monthly battery cycle.",

goodwe_controller/app/ui_text/nl.json

@@ -13,7 +13,7 @@
     "inverters.modes": {"name": "Batterijmodi"},
     "tariff.selling": {"name": "Laden en verkopen op prijs"},
     "tariff.feed": {"name": "Details van de prijsfeed"},
-    "safety.peak": {"name": "Piekgrens"},
+    "safety.peak": {"name": "Piekgrens", "description": "De add-on mikt iets onder uw grens, voor de zekerheid."},
     "safety.start": {"name": "Starten en stoppen"},
     "safety.stops": {"name": "Veiligheidsstops", "description": "Gemeten op echte hardware, dus laat ze zoals ze zijn."},
     "maintenance.support": {"name": "Support"}
@@ -84,18 +84,18 @@
       "on": "Aan", "off": "Uit",
       "choice": {
         "solar_first": {"name": "Eerst zonne-energie", "description": "Laadt met zonne-energie vóór de andere batterijen en dekt het huis."},
-        "leftover_solar": {"name": "Overschot zonne-energie", "description": "Laadt met zonne-energie die de andere batterijen niet opnemen, en dekt het huis."},
+        "leftover_solar": {"name": "Overschot zonne-energie", "description": "Krijgt zonne-energie die de andere niet opnemen, en levert in dure uren."},
+        "cheap_hours": {"name": "Alleen goedkope uren", "description": "Laadt in de goedkoopste uren en levert in de dure uren."},
         "off": {"name": "Uit", "description": "Rust, en helpt alleen als de piekgrens haar nodig heeft."}
       },
-      "later": "Alleen goedkope uren, volgt later",
       "today": "Vandaag", "why": "Waarom",
-      "sell": {"name": "Verkopen in dure uren", "description": "Verkopen komt in een latere update."},
       "modes_off": {"name": "Batterijmodi staan uit"},
       "how": {"name": "Zo werken de modi", "description": "Welke batterij eerst zonne-energie krijgt, en wanneer elke batterij levert.",
         "solar_first": {"description": "Eerst zonne-energie krijgt het overschot vóór de andere batterijen, en dekt het huis op elk uur."},
-        "leftover_solar": {"description": "Overschot zonne-energie krijgt wat de batterijen met Eerst zonne-energie niet opnemen, en dekt ook het huis."},
+        "leftover_solar": {"description": "Overschot zonne-energie krijgt wat de batterijen met Eerst zonne-energie niet opnemen, en spaart haar stroom voor dure uren."},
+        "cheap_hours": {"description": "Alleen goedkope uren laadt in de goedkoopste uren en levert in de dure uren."},
         "off": {"description": "Uit laat de batterij rusten en start geen maandelijkse cyclus, maar de piekgrens mag haar nog gebruiken."},
-        "rules": {"description": "De piekgrens en de veiligheidsstops gaan altijd voor, en laden van het net en verkopen volgen later."}},
+        "rules": {"description": "De piekgrens en de veiligheidsstops gaan voor, en terwijl een batterij van het net laadt rusten de andere."}},
       "toast": {"on": "{name} staat aan.", "off": "{name} staat uit.", "mode": "{name}: {mode}."}},
     "settings": {"name": "Instellingen", "description": "De instellingen staan hieronder per taak.", "open": "Instellingen openen"}
   },
@@ -190,7 +190,7 @@
         "5": {"name": "Piekgrens", "description": "Het net blijft onder deze grens, gemiddeld over elk kwartier."},
         "6": {"name": "Nakijken en starten", "description": "De add-on kijkt alles na met zijn eigen startcontroles en herstart dan."}
       },
-      "modes_later": {"description": "Een modus kiezen per batterij komt in een latere update."},
+      "modes_later": {"description": "Zet na de installatie batterijmodi aan om per batterij een modus te kiezen op het scherm Batterijen."},
       "kettle": {
         "name": "Richting nakijken",
         "description": "Lees de meter af, zet een waterkoker aan en lees de meter opnieuw af.",
@@ -224,7 +224,7 @@
   },
   "home_words": {
     "mode_house": "Volgt het huis",
-    "modes": {"solar_first": "Eerst zonne-energie", "leftover_solar": "Overschot zonne-energie", "off": "Uit"},
+    "modes": {"solar_first": "Eerst zonne-energie", "leftover_solar": "Overschot zonne-energie", "cheap_hours": "Alleen goedkope uren", "off": "Uit"},
     "attn_shadow": "Schaduwmodus staat aan",
     "attn_shadow_body": "De add-on beslist alles, maar elke omvormer blijft op 0 W.",
     "zero_held": "Op 0 W gehouden",
@@ -268,10 +268,20 @@
       "leftover": "Ze krijgt de zonne-energie die de batterijen met Eerst zonne-energie niet opnemen.",
       "leftover_alone": "Geen batterij met Eerst zonne-energie staat aan, dus zij krijgt eerst zonne-energie.",
       "covers_house": "Ze levert stroom om het huis te dekken.",
-      "other_refuses": "{name} weigert te leveren, dus deze batterij neemt het over."
+      "other_refuses": "{name} weigert te leveren, dus deze batterij neemt het over.",
+      "other_cycle": "{name} loopt leeg voor haar maandelijkse cyclus. Deze laadt niet.",
+      "grid_charge": "De prijs is laag, dus ze laadt van het net.",
+      "rests_charge": "Een andere batterij laadt van het net, dus deze rust.",
+      "selling": "De prijs is hoog, dus ze verkoopt aan het net.",
+      "expensive": "De prijs is hoog, dus ze dekt het huis.",
+      "saves": "Spaart haar stroom voor {at}.",
+      "saves_later": "Spaart haar stroom voor hogere prijzen.",
+      "no_prices": "Geen prijzen, dus ze volgt het huis.",
+      "no_spread": "De prijzen verschillen te weinig, dus ze volgt het huis."
     },
     "today": {
       "not_planned": "Nog niet gepland.",
+      "no_runs": "Vandaag geen goedkope of dure uren meer.",
       "off": "Uit, dus vandaag geen maandelijkse cyclus.",
       "house": "Volgt het huis.",
       "house_would": "Zou het huis volgen.",
@@ -298,6 +308,10 @@
       "give_what": "Levert tot {kwh}, eerst aan het huis.",
       "give_what_would": "Zou tot {kwh} leveren, eerst aan het huis.",
       "give_why": "Hoogste gepubliceerde prijs, {eur} per kWh.",
+      "sell_what": "Verkoopt tot {kwh}, eerst aan het huis.",
+      "sell_what_would": "Zou tot {kwh} verkopen, eerst aan het huis.",
+      "cheap_why": "Goedkoopste uren, ongeveer {eur} per kWh.",
+      "dear_why": "Dure uren, ongeveer {eur} per kWh.",
       "give_amount": "Tot {eur} waard aan die prijs.",
       "cycle_start": "Start de maandelijkse batterijcyclus.",
       "cycle_start_would": "Zou de maandelijkse batterijcyclus starten.",

goodwe_controller/app/uilayout.py

@@ -182,6 +182,7 @@ GROUPS = (
         Part("peak", (
             Field("peak_cap_w", SLIDER, "kW", scale=1000, step=100,
                   simple=True, wizard=5, note="month_peak"),
+            Field("peak_margin_w", SLIDER, "W", step=10),   # SAFETY-79
             Field("peak_forecast_entity", ENTITY, kind="power_w", wizard=5),
             Field("peak_soc_floor", LOCKED, "%"),
         )),

goodwe_controller/app/validate.py

@@ -243,6 +243,9 @@ NOT READY banner already names the problem, (b) does not apply.
      note below on `gain`, which is the term that owns that and which SAFETY-39
      measured and did not change.
 
+ 12. `peak_margin_w` outside 0-500 W, not whole, or not below `peak_cap_w`.
+     SAFETY-79; the Supervisor checks the range too, but not for sim/inject.py.
+
 WHAT IS DELIBERATELY *NOT* REFUSED, because it is untidy rather than unsafe:
 
   - `integrator_max_w` above `max_w`. DOCS.md is right that the only thing the
@@ -333,7 +336,7 @@ from .inverter import roster_entries
 from .maintenance import MAINT_OPTION_DEFAULTS
 from .p1 import (
     SOURCE_HA, SOURCE_HA_SIGNED, is_enabled, validate_meter_options)
-from .peakguard import PEAK_OPTION_DEFAULTS
+from .peakguard import PEAK_MARGIN_RANGE_W, PEAK_OPTION_DEFAULTS
 from .price import (
     PRICE_OPTION_DEFAULTS, PROVIDERS, RETIRED_PROVIDERS,
     SUPERSEDED_TAXES_DEFAULTS_EUR_KWH)
@@ -1194,6 +1197,9 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None,
                 f"reserve above {bms_floor:.0f} %, or correct the cut-out "
                 "level.")
 
+    # --- 12. SAFETY-79: the margin the peak guard keeps under the limit -----
+    problems += _margin_problems(opts)
+
     # --- warnings: real, but not worth refusing over -------------------------
     integ = opts.get("integrator_max_w")
     integ_w = None if not integ else _number(opts, "integrator_max_w", None)
@@ -2022,6 +2028,23 @@ def _price_check(notes, opts, running, prices_known) -> None:
                 "Prices are fetched after the restart, and Home shows them.")
 
 
+def _margin_problems(opts: dict) -> list[str]:
+    """Rule 12: `peak_margin_w` is a whole number in the schema's range, and
+    below the peak limit, which would leave nothing to aim at."""
+    raw = opts.get("peak_margin_w")
+    margin = _number(opts, "peak_margin_w",
+                     PEAK_OPTION_DEFAULTS["peak_margin_w"])
+    lo, hi = PEAK_MARGIN_RANGE_W
+    if margin is None or margin != int(margin) or not lo <= margin <= hi:
+        return [f"{S('peak_margin_w')} must be a whole number from {lo} to "
+                f"{hi} W. It is {messages.shown(raw)}."]
+    cap = _number(opts, "peak_cap_w", None)
+    if cap is not None and margin >= cap:
+        return [f"{S('peak_margin_w')} is {margin:.0f} W, not below the "
+                f"{S('peak_cap_w')} of {cap:.0f} W. Lower the margin."]
+    return []
+
+
 def _number(opts: dict, key, default):
     raw = opts.get(key, default)
     if raw is None or raw == "":

goodwe_controller/app/web.py

@@ -34,7 +34,8 @@ succeeds, so the page stops opening the wizard by itself (uipage.setup_needed).
 UX-15's setup-only mode serves these routes from `setuponly.SetupOnly`, which
 commands nothing; there `/action` answers 409.
 OPT-11 P1 adds two `/action` values, `pack_use` and `pack_mode`, which set one
-battery's on/off switch or mode in the store (Controller._pack_action). They
+battery's on/off switch or mode in the store (Controller._pack_action); P3 adds
+`pack_sell`, that battery's selling switch. They
 are the only actions that name a battery; the configuration routes still reach
 none of them.
 """
@@ -58,7 +59,7 @@ from .uimodel import DeriveError, options_to_ui
 _LOG = logging.getLogger("goodwe.web")
 
 # OPT-11: the per-battery actions, which name a battery and a value.
-PACK_ACTIONS = ("pack_use", "pack_mode")
+PACK_ACTIONS = ("pack_use", "pack_mode", "pack_sell")
 
 # UX-13 P1: the page lives in app/static/ as three files - index.html,
 # app.css, app.js - plus the page words from app/ui_text/<lang>.json (English

goodwe_controller/config.yaml

@@ -290,6 +290,8 @@ options:
   # protects the shallower pack with the deeper pack's number.
   bms_soc_floor: 10
   peak_cap_w: 3500
+  # SAFETY-79: the peak guard aims this many watts under peak_cap_w.
+  peak_margin_w: 50
   peak_forecast_entity: ""
 
   # The peak guard can COMMAND a discharge to hold a billed quarter under
@@ -1019,6 +1021,7 @@ schema:
   max_w: int(100,5000)
   bms_soc_floor: int(0,50)
   peak_cap_w: int(500,15000)
+  peak_margin_w: int(0,500)
   peak_forecast_entity: str?
 
   # SAFETY-24. No "off" value: a guard that can command a discharge does not get

goodwe_controller/test_arbiter.py

@@ -149,7 +149,7 @@ check("...and `source` is still the first positional argument, which is what "
       Claim.limit("device", P_SAFETY, -1, 1).source == "device")
 
 print()
-print("ARB-03 2. the split: thirteen sources, each classified where it is BUILT")
+print("ARB-03 2. the split: fourteen sources, each classified where it is BUILT")
 # The classification is graded against what each claim is ABOUT, restated here
 # so that the table in arbiter.py and the expectation in a test are not the same
 # sentence read twice. test_peakguard.py part 10f pins this set against main.py's
@@ -171,6 +171,10 @@ SITE_SOURCES = {
                  "offending number is the SITE target, which no single "
                  "inverter owns - parking one of them would leave the rest "
                  "pushing the same way with the guard satisfied",
+    # SAFETY-78.
+    "drain":     "the site target may not go below a pinned maintenance "
+                 "drain, or a sibling would charge against it. Filed at N>1 "
+                 "only",
 }
 UNIT_SOURCES = {
     "device":     "one inverter's own reported min/max rating",
@@ -202,9 +206,9 @@ for _src, _why in sorted(SITE_SOURCES.items()):
     print(f"    site  {_src:<11} {_why}")
 for _src, _why in sorted(UNIT_SOURCES.items()):
     print(f"    unit  {_src:<11} {_why}")
-check("all THIRTEEN claim sources are classified, and only those thirteen",
+check("all FOURTEEN claim sources are classified, and only those fourteen",
       set(CLAIM_SCOPE) == set(SITE_SOURCES) | set(UNIT_SOURCES))
-check("the six that are about the GRID CONNECTION are site claims",
+check("the seven that are about the GRID CONNECTION are site claims",
       {s for s, v in CLAIM_SCOPE.items() if v == SCOPE_SITE} == set(SITE_SOURCES))
 check("the seven that are about a PACK, a DEVICE or one write are per-inverter",
       {s for s, v in CLAIM_SCOPE.items() if v == SCOPE_UNIT} == set(UNIT_SOURCES))
@@ -225,8 +229,8 @@ check("with one inverter every source routes to the site, per-inverter ones "
 check("...and with none configured at all, likewise",
       all(actuator_for(s, "inverter-a", ()) == ACTUATOR_SITE for s in CLAIM_SCOPE))
 check("with TWO the identity breaks and the split becomes real: the seven "
-      "per-inverter sources route to the unit this controller drives, the six "
-      "site sources stay on the grid connection",
+      "per-inverter sources route to the unit this controller drives, the "
+      "seven site sources stay on the grid connection",
       {s: actuator_for(s, "inverter-a", TWO) for s in CLAIM_SCOPE}
       == {**{s: "inverter-a" for s in UNIT_SOURCES},
           **{s: ACTUATOR_SITE for s in SITE_SOURCES}})

goodwe_controller/test_arbitrage.py

@@ -1039,7 +1039,7 @@ def s45_loop(*, sized: bool, cap_w=S45_CAP_W, load_w=S45_LOAD_W,
             now = t0 + timedelta(seconds=t)
             claims = []
             pk = _pg.decide(PeakTracker.project(avg, now), batt_w=batt,
-                            cap_w=cap_w, reading=None, achievable_w=MAX_W,
+                            cap_w=cap_w, margin_w=0.0, reading=None, achievable_w=MAX_W,
                             soc=50.0, soc_floor=20.0, max_hold_s=900.0,
                             frozen=False)
             pc = _pg.claim(pk)
@@ -1380,7 +1380,7 @@ def _s47_headroom(*, meter_w, batt_w, elapsed_s=450.0):
         t += 5.0
     pk = _pg.decide(
         PeakTracker.project(avg, S45_T0 + timedelta(seconds=elapsed_s)),
-        batt_w=batt_w, cap_w=S45_CAP_W, reading=None, achievable_w=MAX_W,
+        batt_w=batt_w, cap_w=S45_CAP_W, margin_w=0.0, reading=None, achievable_w=MAX_W,
         soc=50.0, soc_floor=20.0, max_hold_s=900.0, frozen=False)
     return _pg.charge_headroom_w(pk)
 

goodwe_controller/test_batteries_screen.py

@@ -36,7 +36,7 @@ import aiohttp                                                  # noqa: E402
 from aiohttp import web as aioweb                               # noqa: E402
 
 import ux13_demo as D                                           # noqa: E402
-from app import homeview, packmode, uilayout as L, uipage, web  # noqa: E402
+from app import homeview, messages, packmode, uilayout as L, uipage, web  # noqa
 from app.maintenance import IDLE, DRAIN                         # noqa: E402
 
 fails = []
@@ -93,7 +93,8 @@ WANT = {
     "off": ("solar_first", "off"),
     "off_peak": ("peak", "off_peak"),
     "refusal": ("refuses_give", "other_refuses"),
-    "maint": ("cycle_mode", "leftover"),
+    # SAFETY-78: the other battery says why it does not charge.
+    "maint": ("cycle_mode", "other_cycle"),
 }
 
 # ============================================================================ #
@@ -120,13 +121,15 @@ for st, want in WANT.items():
                   for e, n in zip(en, nl)))
 
 _modes = ROWS[("modes", "en")]
-check("modes on: each row carries its switch and mode, and Today says the "
-      "mode's plan is not made yet (OPT-11 P3/P4), without inventing one",
+check("modes on: each row carries its switch and mode; Today says Solar "
+      "first follows the house and, before any cycle has made the price "
+      "runs (OPT-11 P3), that Leftover solar is not planned yet",
       _modes["modes_on"] is True
       and [(b["use"], b["mode_key"]) for b in _modes["batteries"]]
       == [(True, "solar_first"), (True, "leftover_solar")]
-      and all(b["today_line"] == EN["home_words"]["today"]["not_planned"]
-              for b in _modes["batteries"]))
+      and [b["today_line"] for b in _modes["batteries"]]
+      == [EN["home_words"]["today"]["house"],
+          EN["home_words"]["today"]["not_planned"]])
 _off = ROWS[("running", "en")]
 check("modes off: no switch, no mode, and Today and Why say it follows the "
       "house", _off["modes_on"] is False
@@ -212,16 +215,25 @@ print(f"    {_kinds}")
 check("Off: no 'follows the house', no trade, no monthly cycle for B",
       not _kinds[1] and "house" in _kinds[0])
 _p = build("off", now=MORNING)
-_m = build("modes", now=MORNING)
+# OPT-11 P3: with modes on the plan shows each battery's price runs, which a
+# control cycle makes; make them as the cycle does (`_mode_roles()`).
+_mc = D.controller("modes")
+_mc._mode_roles(MORNING, None)
+_m = build("modes", c=_mc, now=MORNING)
 _kinds = {i: {r["kind"] for r in _p["plan"]["runs"] if r["battery"] == i}
           for i in (0, 1)}
 print(f"    morning: {_kinds}, lines {_p['plan']['lines']}")
-check("in the morning, with trades and a cycle ahead: A has them, Off B has "
-      "no block and waits for no cycle (with B on, it does)",
-      {"house", "grid", "give", "cycle"} <= _kinds[0] and not _kinds[1]
+check("in the morning, with trades and a cycle ahead: Solar first A follows "
+      "the house and has its cycle but no price block (OPT-11 P3: Solar first "
+      "never trades), Off B has no block and waits for no cycle; with B on "
+      "(Leftover solar) B has its expensive run but no grid block (it takes "
+      "solar only until the forecast, owner decision 2026-09-29) and waits",
+      {"house", "cycle"} == _kinds[0] and not _kinds[1]
       and not any(B_NAME in x for x in _p["plan"]["lines"])
-      and {"grid", "give"} <= {r["kind"] for r in _m["plan"]["runs"]
-                               if r["battery"] == 1}
+      and "give" in {r["kind"] for r in _m["plan"]["runs"]
+                     if r["battery"] == 1}
+      and "grid" not in {r["kind"] for r in _m["plan"]["runs"]
+                         if r["battery"] == 1}
       and any(B_NAME in x for x in _m["plan"]["lines"]))
 _p = build("off_peak")
 check("...but the peak block stays on it while the peak limit needs it",
@@ -290,6 +302,30 @@ _cases = [
     (dict(mode=packmode.LEFTOVER_SOLAR, sf_ahead=True), "leftover"),
     (dict(mode=packmode.LEFTOVER_SOLAR), "leftover_alone"),
     ({}, "solar_first"),
+    # OPT-11 P3: the battery's role in the price runs, and no plan.
+    (dict(mode=packmode.CHEAP_HOURS, role="charge"), "grid_charge"),
+    (dict(role="rest"), "rests_charge"),
+    (dict(mode=packmode.CHEAP_HOURS, role="sell", giving=True), "selling"),
+    (dict(mode=packmode.LEFTOVER_SOLAR, role="give", giving=True),
+     "expensive"),
+    (dict(mode=packmode.LEFTOVER_SOLAR, role="hold", has_at=True), "saves"),
+    (dict(mode=packmode.CHEAP_HOURS, role="hold"), "saves_later"),
+    (dict(mode=packmode.CHEAP_HOURS, role="house", plan="no_prices"),
+     "no_prices"),
+    (dict(mode=packmode.LEFTOVER_SOLAR, role="house", plan="no_spread",
+          giving=True), "no_spread"),
+    # ...and the urgent reasons still come first.
+    (dict(role="charge", refused=-1), "refuses_charge"),
+    (dict(role="sell", peak=True), "peak"),
+    (dict(role="hold", off=True), "off"),
+    # SAFETY-78: another battery drains for its monthly cycle.
+    (dict(other_cycle="A"), "other_cycle"),
+    (dict(other_cycle="A", modes_on=False, giving=True), "other_cycle"),
+    (dict(other_cycle="A", mode=packmode.CHEAP_HOURS, role="charge"),
+     "other_cycle"),
+    (dict(other_cycle="A", peak=True), "peak"),
+    (dict(other_cycle="A", refused=-1), "refuses_charge"),
+    (dict(other_cycle="A", off=True), "off"),
 ]
 _wrong = [(kw, want, why(**kw)) for kw, want in _cases if why(**kw) != want]
 print(f"    {_wrong}")
@@ -336,9 +372,13 @@ _r = asyncio.run(_serve("modes", [
      "nl"),
     ({"action": "pack_use", "unit": B, "value": True}, "en"),
     ({"action": "pack_mode", "unit": A, "value": "cheap_hours"}, "en"),
+    ({"action": "pack_sell", "unit": A, "value": True}, "en"),
+    ({"action": "pack_sell", "unit": A, "value": "yes"}, "en"),
+    ({"action": "pack_mode", "unit": A, "value": "sell_only"}, "en"),
 ]))
 (_s1, _j1), (_, _st1), (_s2, _j2), (_, _st2), (_s3, _), (_, _st3), \
-    (_s4, _j4), (_, _st4) = _r
+    (_s4, _j4), (_, _st4), (_s5, _j5), (_, _st5), (_s6, _j6), (_, _st6), \
+    (_s7, _j7), (_, _st7) = _r
 check("switch B off: 200, and /status shows B Off with 'You switched it off.'",
       _s1 == 200 and _j1["result"]["use"] is False
       and _st1["batteries"][1]["mode_key"] == "off"
@@ -351,9 +391,18 @@ check("set A to Leftover solar: 200, and /status?lang=nl shows it in Dutch",
 check("switch B back on: its stored mode returns",
       _s3 == 200 and _st3["batteries"][1]["mode_key"]
       == packmode.LEFTOVER_SOLAR)
-check("a mode the list only shows greyed out is refused with a plain 400, and "
-      "nothing changes", _s4 == 400 and _j4["ok"] is False and _j4["error"]
-      and _st4["batteries"][0]["mode_choice"] == packmode.LEFTOVER_SOLAR)
+check("OPT-11 P3: Cheap hours only is a mode now: 200, and /status shows it",
+      _s4 == 200 and _st4["batteries"][0]["mode_choice"]
+      == packmode.CHEAP_HOURS)
+check("owner decision 2026-09-29 (option A): selling is off, so a posted "
+      "pack_sell is refused with the plain reason 'Selling is off for now.', "
+      "and /status says no battery sells or can",
+      _s5 == 400 and _j5["error"] == messages.pack_refused("sell_off")
+      and _s6 == 400 and all(b["sell"] is False and b["can_sell"] is False
+                             for b in _st5["batteries"] + _st6["batteries"]))
+check("...a mode that does not exist is refused with a plain 400, and "
+      "nothing changes", _s7 == 400 and _j7["error"]
+      and _st7["batteries"][0]["mode_choice"] == packmode.CHEAP_HOURS)
 _r = asyncio.run(_serve("running", [
     ({"action": "pack_use", "unit": B, "value": False}, "en")]))
 check("with battery modes off the switch is refused with the plain reason, "
@@ -376,14 +425,19 @@ check("Settings has a Simple / Installer choice as a radio group, and Simple "
       and PAGE.count('role="radio"') >= 2 and 'id="simple"' in PAGE)
 _acts = set(re.findall(r'packAct\("(\w+)"', JS))
 check(f"the cards post only the existing actions ({sorted(_acts)}), as "
-      f"{{action, unit, value}}", _acts == set(web.PACK_ACTIONS)
+      f"{{action, unit, value}}; selling has no control while it is off",
+      _acts == set(web.PACK_ACTIONS) - {"pack_sell"}
+      and packmode.SELLING_ENABLED is False
       and "action: what, unit: b.name, value: value" in JS)
-check("the switch is a real switch and the list names cheap hours as coming "
-      "later, not choosable", 'role: "switch"' in JS and '"aria-checked"' in JS
-      and 'h("option", { value: "", disabled: true }, t("batteries.later"))'
-      in JS)
-check("the selling switch is greyed out until OPT-11 P3 (no pack_sell is "
-      "posted)", "pack_sell" not in JS and "disabled: true })" in JS)
+check("the switch is a real switch and the list offers the three modes, "
+      "cheap hours included, with nothing greyed out",
+      'role: "switch"' in JS and '"aria-checked"' in JS
+      and 'const MODES = ["solar_first", "leftover_solar", "cheap_hours"];'
+      in JS and "batteries.later" not in JS)
+check("no selling switch anywhere on the page or in Settings, and no words "
+      "for one", "pack_sell" not in JS and "sell" not in SJS
+      and "batteries.sell" not in JS
+      and all("sell" not in W["home"]["batteries"] for W in LANGS.values()))
 _T = uipage.ui_text("en")
 _lay = uipage.layout(D.schema_ui(D.CONFIG), {"en": {}})
 _simple = [f for g in _lay["groups"] for p in g["parts"] for f in p["fields"]

goodwe_controller/test_maintenance.py

@@ -1363,50 +1363,24 @@ check("...while the second pack's write reaches only its own namespace",
 
 # --------------------------------------------------------------------------- #
 print()
-print("12. RECORDED, NOT FIXED: the site loop still contradicts a drain at N>=2")
+print("12. FIXED (SAFETY-78): a drain at N>=2 no longer parks the site")
 
-# ⚠️ THIS IS A DEFECT THIS CARD FOUND AND DELIBERATELY DID NOT FIX, AND IT IS
-# WRITTEN DOWN AS A RUNNING CHECK RATHER THAN AS A COMMENT SO IT CANNOT BE
-# FORGOTTEN OR QUIETLY "FIXED" BY A TUNING CHANGE.
-#
-# WHAT IT IS. The maintenance SET is a per-unit claim and PINS its pack. The
-# loop's target is a SITE claim. When the site target is BELOW the pin - a
-# drain of 2000 W while the house is importing less than that, which is most of
-# a night - the only split that sums to the site target asks the sibling to
-# CHARGE while the maintained pack DISCHARGES, and `allocator.plan()` refuses it
-# by name as circulating power. The refusal is correct and fails safe: the whole
-# site goes to 0 W with an ARBITER line in the action log.
-#
-# WHY IT IS NOT THIS CARD'S. It is PRE-EXISTING - measured on release/1.0 at
-# 2d025ee, where the same drain filed on `inverters[0]` produces the identical
-# refusal with the two unit names swapped - and fixing it means changing what
-# the site loop's target MEANS while a unit is pinned (regulate the meter using
-# only the unpinned packs), which is loop and allocator territory, not
-# maintenance's. MAINT-05 moves which pack is pinned and nothing else about it.
-#
-# ⚠️ AND THE CONSEQUENCE AN OPERATOR WOULD SEE IS A MISDIAGNOSIS, WHICH IS WHY
-# IT MATTERS ENOUGH TO PIN. The pack is held at 0 W while its FSM believes it is
-# draining, so after 12 h the DRAIN timeout fires and reports "drain stuck" -
-# §12's words for "the battery is not following commands, a fault". The battery
-# is fine; the site refused to allocate. That is the same class of wrong story
-# this card's own notes warn about for the deferral.
+# This section used to pin the defect: with the house below the drain, the
+# only split summing to the site target asked the sibling to CHARGE, the
+# allocator refused it and the site sat at 0 W while the FSM believed it was
+# draining. SAFETY-78 files a site `drain` floor at the pin, so the sibling
+# only ever adds power the same way. test_safety78.py grades it in full.
 _cX, _ = controller(TWO_OPTS, grid=0.0)
 _cX.maints[1].force_start(_now)
 one_cycle(_cX)
 print(f"    house at 0 W, B draining 2000 W -> reason {_cX.reason!r}; "
       f"{_cX.allocation.explain()}")
-check("a maintenance drain BELOW the site target is refused by the allocator "
-      "and the site parks at 0 W - recorded here so the next card can find it, "
-      "not asserted as desirable",
-      _cX.target == 0.0 and _cX.allocation.refused
-      and "circulating power" in _cX.allocation.explain())
-check("...and the pack that is supposedly draining is commanded 0 W, so its "
-      "12 h DRAIN timeout would eventually report 'drain stuck' - a fault "
-      "message about a healthy battery",
-      _cX.maints[1].phase == DRAIN and _cX.inverters[1].target == 0.0)
-check("...while the SAME site with the house importing more than the drain "
-      "allocates cleanly, which is what makes this a CONDITION rather than "
-      "'maintenance does not work at two inverters'",
+check("a maintenance drain above the loop's site target is allocated, not "
+      "refused: B drains at its rate and A is held at 0 W",
+      _cX.allocation.refused is None and _cX.target == 2000.0
+      and _cX.inverters[1].target == 2000.0 and _cX.inverters[0].target == 0.0)
+check("...and the SAME site with the house importing more than the drain "
+      "still allocates cleanly",
       _cB.allocation.refused is None and _cB.inverters[1].target == 2000.0)
 
 

goodwe_controller/test_messages.py

@@ -965,7 +965,7 @@ def _peak_texts():
     proj = Projection(projected_w=4338.0, elapsed_w=4338.0, elapsed_s=799.0,
                       covered_frac=1.0, complete=False, block_start=_T0,
                       held_w=0.0)
-    kw = dict(cap_w=3500.0, reading=None, soc_floor=30.0, max_hold_s=30.0)
+    kw = dict(cap_w=3500.0, margin_w=0.0, reading=None, soc_floor=30.0, max_hold_s=30.0)
     sat = _pg.decide(proj, batt_w=1500.0, achievable_w=5000.0, soc=80.0, **kw)
     low = _pg.decide(proj, batt_w=1500.0, achievable_w=5000.0, soc=20.0, **kw)
     unread = _pg.decide(proj, batt_w=1500.0, achievable_w=5000.0, soc=None, **kw)

goodwe_controller/test_modes.py

@@ -112,6 +112,11 @@ try:
 finally:
     _undo_c()
     _undo_b()
+# SAFETY-78 changes n2_maint ON PURPOSE: on a5dddad and 5a4cdc2 its N=2 drain
+# was refused on 392 of 540 cycles (site at 0 W); now none is. Printed on the
+# SAFETY-78 tree the same way. Every other digest is unchanged.
+SAFETY78_N2_MAINT = \
+    "cd4d9cb5b7e29ff4ab4fe65dab5106683d8a599f09323fbdee4018ad9b28fcd1"
 for k in A5DDDAD:
     print(f"    {k:7} {'same' if _now[k] == A5DDDAD[k] else 'DIFFERS'} "
           f"{_now[k][:16]}")
@@ -119,8 +124,13 @@ check("⭐ at N=1 and N=2, with the option absent and with it false, every "
       "command, reason and allocation record over 540 cycles each is "
       "byte-identical to a5dddad (house steps, a solar surplus, a battery "
       "at its cut-out level, at N=2 a refusal with probes, both batteries "
-      "due for maintenance), and so is the arbiter on 6000 claim lists",
-      _now == A5DDDAD)
+      "due for maintenance; n2_maint apart, below), and so is the arbiter "
+      "on 6000 claim lists",
+      {k: v for k, v in _now.items() if k != "n2_maint"}
+      == {k: v for k, v in A5DDDAD.items() if k != "n2_maint"})
+check("...and n2_maint is the SAFETY-78 digest: the N=2 drain that a5dddad "
+      "refused on 392 of 540 cycles now runs (test_safety78.py)",
+      _now["n2_maint"] == SAFETY78_N2_MAINT != A5DDDAD["n2_maint"])
 check("...and no cycle in those runs filed a `mode` claim or handed "
       "`compute()` a bound",
       _claims and not any(c.source == "mode" for cl in _claims for c in cl)
@@ -335,11 +345,11 @@ _bad = [asyncio.run(_c.handle_action("pack_use", unit="inverter-z",
         asyncio.run(_c.handle_action("pack_use", unit=A, value=0)),
         asyncio.run(_c.handle_action("pack_use", unit=A, value=1)),
         asyncio.run(_c.handle_action("pack_mode", unit=A,
-                                     value=packmode.CHEAP_HOURS)),
+                                     value="sell_only")),
         asyncio.run(_c.handle_action("pack_mode", unit=A, value=None))]
 check("an unknown battery, a switch that is not true or false (0 and 1 "
       "included), and a mode "
-      "this release does not offer (Cheap hours arrives in P3) are refused, "
+      "that does not exist are refused, "
       "with a plain reason, and store nothing",
       all(isinstance(x, dict) and set(x) == {"error"} for x in _bad)
       and unit_key(A, packmode.MODE_KEY) not in _c.store.data

goodwe_controller/test_modes_p3.py

@@ -0,0 +1,722 @@
+"""Runnable check for OPT-11 P3, price runs per battery.  `python3 test_modes_p3.py`
+
+Drives the pure modules (priceruns, modetrade) and the REAL Controller
+(tools/opt11p3_replay.py: read_inputs + cycle on a P1 meter, the arbiter, the
+allocator and the peak guard, with two lagged model batteries), in simulated
+time. DECISIONS/OPT-11-battery-modes.md has the record.
+
+1. With battery modes off, every command and trade is byte-identical to
+   release/1.0 7a00f12 on the trade path P3 changed (digests measured there),
+   and the harness would see a change there.
+2. Price runs: consecutive, firm, sized by energy; give runs clear the spread;
+   the sell run sits in a give run with no slot below 0; a started run is kept.
+3. Roles: a fuzz of modetrade.decide() and size() against the invariants.
+4. The real controller over a day: no opposite-direction split, no grid
+   charge on Solar first, the quarter never above the aim while charging, no
+   sell below the floor or the spread, holding outside the expensive hours.
+5. A refusal wins over a run.
+6. No prices or too small a gap: the price modes follow the house; Solar first
+   alone never trades.
+7. A run edge reseeds the loop (handover measured with and without).
+8. The site Why row: a limit that pushes power up does not "hold it back" (F2).
+9. Selling is off (owner, 2026-09-29): `pack_sell` refused, read as false.
+10. The Batteries screen: Why and Today lines from the roles and runs.
+11. Review additions: modes on ignore the site trade switch, a battery in
+    maintenance takes no part, the headroom stop latches for the period.
+
+12. Option A: no sale in a day; Leftover solar never grid-charges (P4).
+
+Mutations (MUTATION.md, purged copies, graded over this file and the named
+tests) are listed in the pull request.
+"""
+
+import asyncio
+import logging
+import os
+import random
+import sys
+from datetime import datetime, timedelta, timezone
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, HERE)
+sys.path.insert(0, os.path.join(HERE, "tools"))
+logging.disable(logging.WARNING)
+
+from named_absence import nth, present                         # noqa: E402
+import opt11p3_identity as ident                               # noqa: E402
+import opt11p3_replay as rp                                    # noqa: E402
+from app import homeview, messages, modetrade, packmode, priceruns  # noqa
+from app import arbitrage                                      # noqa: E402
+from app.arbiter import Claim, P_ARBITRAGE, P_LOOP, P_PEAK, Resolution  # noqa
+from app.main import Controller, why_raised                    # noqa: E402
+from app.price import PricePoint, brussels                     # noqa: E402
+from app.store import unit_key                                 # noqa: E402
+
+fails = []
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+L = timezone(timedelta(hours=2))
+A, B = "inverter-a", "inverter-b"
+
+# ============================================================================ #
+print("1. modes off: byte-identical to 7a00f12 on the trade path")
+# Printed by tools/opt11p3_identity.py on release/1.0 7a00f12 (2026-09-29),
+# goodwe-addon-checks:1. 1080 cycles each; the trade CHARGEs and DISCHARGEs.
+AT_7A00F12 = {
+    "n1": "71245b227ca40bada4f71f57ea6154475f4b0bd60239c9ad4f80bffb0094514c",
+    "n2": "56cf28010b06765c29e5479abb815d7503d570b39240d82dfc818efa90c93722",
+    "n1_off": "71245b227ca40bada4f71f57ea6154475f4b0bd60239c9ad4f80bffb0094514c",
+    "n2_off": "56cf28010b06765c29e5479abb815d7503d570b39240d82dfc818efa90c93722",
+}
+_rows = {k: ident.run(**v)[0] for k, v in ident.SCENARIOS.items()}
+_got = {k: ident.digest(v) for k, v in _rows.items()}
+for k in AT_7A00F12:
+    print(f"    {k} {'same' if _got[k] == AT_7A00F12[k] else 'DIFFERS'} "
+          f"{_got[k][:16]}")
+check("with battery modes off (option absent or false), every command, "
+      "integrator, allocation and trade sentence equals 7a00f12's, at one "
+      "inverter and at two", _got == AT_7A00F12)
+_acts = {r[-1][0] for r in _rows["n2"] if r[-1]}
+check("...and the runs reach the trade P3 now skips with modes on: a charge "
+      "and a sale", {arbitrage.CHARGE, arbitrage.DISCHARGE} <= _acts)
+
+
+def _moved(scn, patch):
+    """Does `patch` (applied before each cycle) move scenario `scn`?"""
+    real = ident._feed
+
+    def feed(c, t):
+        patch(c)
+        real(c, t)
+    ident._feed = feed
+    try:
+        return ident.digest(ident.run(**ident.SCENARIOS[scn])[0]) \
+            != AT_7A00F12[scn]
+    finally:
+        ident._feed = real
+
+
+def _as_if_trade_ended(c):
+    c._mode_trade_was = True        # the run-edge reseed, leaking to modes off
+
+
+def _moved_headroom(scn):
+    """Does an unmeasured headroom (the expression P3 hoisted) move it?"""
+    from app import peakguard
+    real = peakguard.charge_headroom_w
+    peakguard.charge_headroom_w = lambda g: None
+    try:
+        return ident.digest(ident.run(**ident.SCENARIOS[scn])[0]) \
+            != AT_7A00F12[scn]
+    finally:
+        peakguard.charge_headroom_w = real
+
+
+check("non-vacuous: a run-edge reseed leaking into modes off moves n2, and so "
+      "does the headroom P3 hoisted, if it went unmeasured",
+      _moved("n2", _as_if_trade_ended) and _moved_headroom("n1"))
+
+# ============================================================================ #
+print("\n2. price runs")
+D0 = datetime(2026, 9, 9, 0, 0, tzinfo=L)
+
+
+def pts(prices, start=D0, minutes=15, provisional=()):
+    return [PricePoint(start=brussels(start + timedelta(minutes=minutes * i)),
+                       eur_per_kwh=p, provisional=i in provisional)
+            for i, p in enumerate(prices)]
+
+
+# 24 h of quarters: cheap 02:00-04:00 (and one cheaper single quarter at
+# 05:00), dear 18:00-20:00 with a peak quarter at 19:00, flat otherwise.
+DAY = [0.30] * 96
+for i in range(8, 16):
+    DAY[i] = 0.10
+DAY[20] = 0.05
+for i in range(72, 80):
+    DAY[i] = 0.50
+DAY[76] = 0.70
+P = pts(DAY)
+NOW = D0 + timedelta(minutes=5)
+r1 = priceruns.plan(P, NOW, required_eur_kwh=0.25, charge_kwh=5.0,
+                    charge_kw=2.5, sell_kwh=0.0, sell_kw=0.0)
+r2 = priceruns.plan(P, NOW, required_eur_kwh=0.25, charge_kwh=0.0,
+                    charge_kw=0.0, sell_kwh=2.5, sell_kw=2.5)
+print(f"    2 h need: {r1.cheap}; give {r1.give}")
+check("the cheap run lasts what the energy needs at the rating (5 kWh at "
+      "2.5 kW = 2 h) and is the cheapest such consecutive window, not the "
+      "cheapest single quarter",
+      r1.cheap.start == D0 + timedelta(hours=2)
+      and r1.cheap.end == D0 + timedelta(hours=4)
+      and abs(r1.cheap.mean_eur_kwh - 0.10) < 1e-9)
+check("...with nothing to charge, one quarter: the cheapest one",
+      r2.cheap.start == D0 + timedelta(hours=5)
+      and r2.cheap.end == D0 + timedelta(hours=5, minutes=15))
+check("give runs are the consecutive quarters at least the required spread "
+      "above the cheap run (0.10 + 0.25): 18:00-20:00, one run",
+      r1.on and len(r1.give) == 1
+      and r1.give[0].start == D0 + timedelta(hours=18)
+      and r1.give[0].end == D0 + timedelta(hours=20))
+check("the sell run is the dearest window inside a give run, sized by the "
+      "sellers' energy (2.5 kWh at 2.5 kW = 1 h)",
+      r2.sell.end - r2.sell.start == timedelta(hours=1)
+      and r1.give[0].start <= r2.sell.start < r2.sell.end <= r1.give[0].end
+      and r2.sell.start <= D0 + timedelta(hours=19) < r2.sell.end)
+_flat = priceruns.plan(pts([0.3] * 96), NOW, required_eur_kwh=0.1,
+                       charge_kwh=5, charge_kw=2.5, sell_kwh=0, sell_kw=0)
+_thr0 = priceruns.plan(pts([0.3] * 96), NOW, required_eur_kwh=0.0,
+                       charge_kwh=5, charge_kw=2.5, sell_kwh=0, sell_kw=0)
+check("a flat day has no plan (`not_worth`), even with a threshold of 0: the "
+      "cheap run never counts as its own expensive run",
+      _flat.reason == priceruns.NOT_WORTH and not _flat.give
+      and _thr0.reason == priceruns.NOT_WORTH)
+_prov = priceruns.plan(pts(DAY, provisional=set(range(74, 96))), NOW,
+                       required_eur_kwh=0.25, charge_kwh=5, charge_kw=2.5,
+                       sell_kwh=2.5, sell_kw=2.5)
+check("a provisional (carried) price is never part of a run (section 8.3)",
+      all(g.end <= D0 + timedelta(hours=18, minutes=30) for g in _prov.give)
+      and (_prov.sell is None
+           or _prov.sell.end <= D0 + timedelta(hours=18, minutes=30)))
+_neg = list(DAY)
+_neg[76] = -0.05
+_rn = priceruns.plan(pts(_neg), NOW, required_eur_kwh=0.25, charge_kwh=0,
+                     charge_kw=0, sell_kwh=10.0, sell_kw=2.5)
+check("the sell run never spans a quarter priced below 0 (section 17)",
+      _rn.sell is not None and not (_rn.sell.start <= D0 + timedelta(
+          hours=19) < _rn.sell.end))
+# All prices below 0 but one: the give run holds negative quarters (they
+# clear the spread over an even lower cheap run), and the sale must skip them.
+_allneg = [-0.30] * 96
+for i in range(8, 16):
+    _allneg[i] = -0.40
+for i in range(72, 80):
+    _allneg[i] = -0.05
+_allneg[76] = 0.10
+_rneg = priceruns.plan(pts(_allneg), NOW, required_eur_kwh=0.15,
+                       charge_kwh=0, charge_kw=0, sell_kwh=2.5, sell_kw=2.5)
+check("...even when the whole give run is below 0 but one quarter: the sale "
+      "is that quarter only",
+      _rneg.on and _rneg.sell is not None
+      and _rneg.sell.start == D0 + timedelta(hours=19)
+      and _rneg.sell.end == D0 + timedelta(hours=19, minutes=15))
+# A spike inside the cheap run clears the spread over the run's own mean:
+# it must not also be a give run (charge and give would overlap).
+_sp = [0.50] * 96
+for i in range(8, 16):
+    _sp[i] = 0.02
+_sp[15] = 0.20
+_rsp = priceruns.plan(pts(_sp), NOW, required_eur_kwh=0.05, charge_kwh=5.0,
+                      charge_kw=2.5, sell_kwh=0, sell_kw=0)
+check("no give run overlaps the cheap run, even a quarter inside it that "
+      "clears the spread over the run's mean",
+      _rsp.cheap.start == D0 + timedelta(hours=2)
+      and all(g.end <= _rsp.cheap.start or g.start >= _rsp.cheap.end
+              for g in _rsp.give))
+_few = priceruns.plan(pts([0.1]), NOW, required_eur_kwh=0.1, charge_kwh=1,
+                      charge_kw=1, sell_kwh=0, sell_kw=0)
+check("fewer than two firm slots: no plan (`no_prices`)",
+      _few.reason == priceruns.NO_PRICES)
+_mid = D0 + timedelta(hours=3)
+_new = priceruns.plan(P, _mid, required_eur_kwh=0.25, charge_kwh=0.0,
+                      charge_kw=0.0, sell_kwh=0.0, sell_kw=0.0)
+_kept = priceruns.keep_started(r1, _new, _mid)
+check("a run under way is kept to its end when a new plan would move it "
+      "(no flapping), and a run not yet started is not",
+      _new.cheap != r1.cheap and _kept.cheap == r1.cheap
+      and priceruns.keep_started(r1, _new, NOW).cheap == _new.cheap)
+_late = priceruns.plan(P, D0 + timedelta(hours=20, minutes=5),
+                       required_eur_kwh=0.25, charge_kwh=5, charge_kw=2.5,
+                       sell_kwh=0, sell_kw=0)
+check("a run that has ended is not planned again, and nothing beyond the "
+      "firm prices is invented",
+      all(g.start >= D0 + timedelta(hours=20) for g in _late.give)
+      and not _late.on)
+
+# ============================================================================ #
+print("\n3. roles: modetrade.decide() fuzz")
+rnd = random.Random(311)
+_bad = []
+_seen = set()
+for _ in range(20000):
+    n = rnd.choice((1, 2, 3))
+    packs = []
+    for k in range(n):
+        packs.append(modetrade.Pack(
+            f"inv-{k}", rnd.random() > 0.15,
+            rnd.choice(packmode.MODES), rnd.random() > 0.5,
+            rnd.choice((1000.0, 2500.0, 5000.0)),
+            rnd.choice((None, 5.0, 19.0, 20.0, 21.0, 60.0, 95.0, 99.0)),
+            rnd.choice((None, 5.0, 10.0)), live=rnd.random() > 0.1,
+            idle=rnd.random() > 0.1, refused=rnd.choice((0, 0, 0, 1, -1))))
+    t = D0 + timedelta(minutes=rnd.randrange(0, 24 * 60))
+    runs = rnd.choice((None, r1, r2, _flat))
+    ok_s = rnd.random() > 0.3
+    ok_c = ok_s and rnd.random() > 0.3
+    hr = rnd.choice((None, 0.0, 100.0, 499.0, 501.0, 3000.0))
+    price = rnd.choice((None, -0.1, 0.0, 0.5))
+    house = rnd.choice((None, -500.0, 800.0))
+    was = rnd.random() > 0.7
+    blocked = rnd.random() > 0.8
+    tk = modetrade.decide(runs, t, packs, charge_ok=ok_c, sell_ok=ok_s,
+                          trade_why="x", price_now=price, headroom_w=hr,
+                          floor_pct=20.0, ceiling_pct=95.0, house_w=house,
+                          charging_now=was, blocked=blocked)
+    _seen.add(tk.action)
+    by = {p.name: p for p in packs}
+    for name, (lo, hi) in tk.ranges.items():
+        if not lo <= 0.0 <= hi:
+            _bad.append(("range without 0", name, lo, hi))
+    for name, role in tk.roles.items():
+        p = by[name]
+        if role == modetrade.CHARGE and (p.mode != packmode.CHEAP_HOURS
+                                         or p.refused < 0 or not p.use
+                                         or p.soc is None or p.soc >= 95.0):
+            _bad.append(("bad charger", p))
+        if role == modetrade.SELL and (not p.sell or p.refused > 0
+                                       or p.mode == packmode.SOLAR_FIRST
+                                       or p.soc is None or p.soc <= 20.0):
+            _bad.append(("bad seller", p))
+        if not p.use and tk.ranges.get(name, (0.0, 0.0)) != (0.0, 0.0):
+            _bad.append(("off not 0", p))
+    if tk.action == modetrade.CHARGE:
+        need = 0.0 if was else modetrade.START_W
+        if not (ok_c and hr is not None and hr > need and not blocked
+                and runs is not None and runs.cheap.holds(t)):
+            _bad.append(("charge without leave", ok_c, hr, blocked))
+        for name, (lo, hi) in tk.ranges.items():
+            if tk.roles[name] != modetrade.CHARGE and lo < 0.0:
+                _bad.append(("grid charge on a non-charger", by[name]))
+        s = modetrade.size(tk, (-7000.0, 7000.0), hr)
+        if not (s < 0 and -s <= min(-tk.ask_w, hr) + 1e-9):
+            _bad.append(("charge size", s, tk.ask_w, hr))
+        if modetrade.size(tk, (-300.0, 300.0), hr) < -300.0:
+            _bad.append(("charge over the bound",))
+    if tk.action == modetrade.SELL:
+        if not (ok_s and price is not None and price >= 0.0 and runs
+                is not None and runs.sell.holds(t) and house is not None):
+            _bad.append(("sell without leave", ok_s, price))
+        s = modetrade.size(tk, (-7000.0, 2000.0), hr)
+        if not 0.0 < s <= 2000.0:
+            _bad.append(("sell size", s))
+    if tk.action is None and modetrade.size(tk, (-1e4, 1e4), hr) != 0.0:
+        _bad.append(("no action but a size",))
+print(f"    actions seen {sorted(map(str, _seen))}; {len(_bad)} bad: {_bad[:3]}")
+check("20000 random ticks: every range holds 0 W; Off is [0, 0]; no Solar "
+      "first, refusing, full or unknown battery charges; no Solar first, "
+      "refusing or at-floor battery sells; while one charges no other may "
+      "charge; a charge needs the guard, the headroom (500 W to start) and "
+      "no stop this period, and is sized under the headroom; a sale needs a "
+      "price >= 0 in the sell run", not _bad
+      and {modetrade.CHARGE, modetrade.SELL, None} <= _seen)
+
+# ============================================================================ #
+print("\n4. the real controller over a day (A Solar first, B Cheap hours + sell)")
+# Wholesale; all-in (x + 0.12) x 1.06: cheap 0.148, flat 0.339, dear 0.551.
+# With a cycle cost of 0.20 (0.30 widened) only 19:00-20:00 clears it.
+DAYW = [0.20] * 96 * 2
+for i in list(range(4, 12)) + list(range(100, 108)):
+    DAYW[i] = 0.02                           # 01:00-03:00 wholesale
+for i in list(range(76, 80)) + list(range(172, 176)):
+    DAYW[i] = 0.40                           # 19:00-20:00
+UTC0 = D0.astimezone(timezone.utc)
+WPTS = [(UTC0 + timedelta(minutes=15 * i), 900, p) for i, p in enumerate(DAYW)]
+
+
+def house_flat(w):
+    return [(UTC0.timestamp() - 10, float(w))]
+
+
+AIM = rp.PEAK_CAP - 50
+
+
+def run_day(variant, *, house_w=2600.0, start_h=0.75, hours=21.0,
+            soc0=None, choice=None, refuse=(), n=2, check_cb=None,
+            patch=None, house=None, limits=None):
+    rows = []
+
+    def cb(c, h, now, pr):
+        sh = dict(c.allocation.shares) if c.allocation is not None and \
+            c.allocation.shares else {}
+        rows.append(dict(
+            now=now, grid=h.grid(), shares=sh,
+            action=getattr(c.arb, "action", None),
+            winner=c.reason.split(" ->")[0],
+            roles=dict(c.mode_tick.roles) if c.mode_tick else {},
+            soc={u: p.soc for u, p in h.plants.items()},
+            p={u: p.p for u, p in h.plants.items()},
+            runs=c.mode_runs, price=pr, why=c.why_words,
+            unmet=getattr(c.allocation, "unmet_w", 0) or 0))
+        if check_cb:
+            check_cb(c, h, now, pr)
+    st, c = rp.run(variant, house or house_flat(house_w), WPTS,
+                   UTC0 + timedelta(hours=start_h), 3600 * hours, check=cb,
+                   soc0=soc0, choice=choice, refuse=refuse, n=n, patch=patch,
+                   extra={"cycle_cost_threshold_eur": 0.20}, limits=limits)
+    return rows, st, c
+
+
+# Selling is off (owner, 2026-09-29, option A). Its code is kept behind
+# packmode.SELLING_ENABLED, and these checks turn it on to hold that code to
+# its invariants; part 12 checks it is unreachable with the flag as shipped.
+_SELL_SHIPPED = packmode.SELLING_ENABLED
+packmode.SELLING_ENABLED = True
+ROWS, ST, _c4 = run_day("p3_ch_sell", soc0={"a": 60.0, "b": 30.0})
+charge = [r for r in ROWS if r["action"] == arbitrage.CHARGE]
+sell = [r for r in ROWS if r["action"] == arbitrage.DISCHARGE]
+print(f"    {len(ROWS)} cycles, {len(charge)} charging, {len(sell)} selling; "
+      f"{rp.summary(ST)}")
+check("B charged from the grid in the cheap run and sold in the dear one, "
+      "and A never took part in either",
+      charge and sell
+      and all(r["roles"][A] in (modetrade.REST, modetrade.HOUSE)
+              for r in charge + sell)
+      and all(r["now"].astimezone(L).hour in (0, 1, 2, 3) for r in charge)
+      and all(r["runs"].cheap.holds(r["now"]) for r in charge)
+      and all(r["now"].astimezone(L).hour == 19 for r in sell))
+_mixed = [r for r in ROWS if any(v > 0 for v in r["shares"].values())
+          and any(v < 0 for v in r["shares"].values())]
+check("no opposite-direction split on any cycle (every share one sign)",
+      not _mixed)
+check("no grid charge on Solar first: while the site charges from the grid, "
+      "A's share is never below 0 W",
+      all(r["shares"].get(A, 0) >= 0 for r in charge))
+# The quarters the add-on itself banked (the P1 blocks, as the bill reads).
+_chq = {int(r["now"].timestamp() // 900) for r in charge}
+_qc = [b.offtake_avg_w for b in _c4.p1.blocks
+       if int(b.start.timestamp() // 900) in _chq]
+print(f"    banked quarters with a grid charge: {len(_qc)}, highest "
+      f"{max(_qc):.2f} W, aim {AIM} W")
+check("never above the SAFETY-79 aim while grid charging: every banked "
+      "15-minute period with a grid charge is at most cap - margin",
+      _qc and max(_qc) <= AIM + 0.5)
+check("...and the charge is sized to the headroom, not the rating: under a "
+      "2.6 kW house B charges well under its 2.5 kW",
+      max(-r["shares"].get(B, 0) for r in charge) < 1200)
+_sold = [r for r in sell]
+check("no sale below the floor or the spread: every sale cycle has B above "
+      "arbitrage_soc_floor (20 %) and a price at least cheap + required",
+      all(r["soc"]["b"] > 19.9 for r in _sold)
+      and all(r["price"] is not None and rp.all_in(r["price"])
+              >= r["runs"].cheap.mean_eur_kwh + 0.30 - 1e-9 for r in _sold))
+_hold = [r for r in ROWS if r["roles"].get(B) == modetrade.HOLD]
+check("outside the expensive hours B holds its power: never gives while "
+      "holding", _hold and all(r["shares"].get(B, 0) <= 0 for r in _hold))
+_give = [r for r in ROWS if r["roles"].get(B) in (modetrade.GIVE,
+                                                  modetrade.SELL)]
+check("...and gives only in the expensive hours (19:00-20:00)",
+      all(r["now"].astimezone(L).hour == 19 for r in _give))
+
+
+def starts(rows, kind):
+    return sum(1 for a, b in zip(rows, rows[1:])
+               if a["action"] != kind and b["action"] == kind)
+
+
+check("the sale starts once and runs to its end: no on-off while the two "
+      "batteries' 5 kW discharge makes the peak guard read 'engaged'",
+      starts(ROWS, arbitrage.DISCHARGE) == 1)
+
+# B's inverter can only take 1000 W: the trade asks for that, not its rating.
+ROWS_U, _, _ = run_day("p3_ch_sell", hours=1.0, house_w=800.0,
+                       soc0={"a": 60.0, "b": 30.0},
+                       limits={"b": (-1000.0, 1000.0)})
+_cu = [r for r in ROWS_U if r["action"] == arbitrage.CHARGE]
+print(f"    B limited to 1 kW: charge {min(r['shares'].get(B, 0) for r in _cu)}"
+      f" W, unmet {max(abs(r['unmet']) for r in _cu)} W")
+check("SAFETY-45 sizing inside the modes: the charge is sized to what the "
+      "batteries may place, so none of it is left unmet (P1's gap)",
+      _cu and all(abs(r["unmet"]) < 1 for r in _cu)
+      and min(r["shares"].get(B, 0) for r in _cu) >= -1000)
+
+# A house that swings over the limit every minute during the cheap run.
+_sw = [(UTC0.timestamp() + 60 * k, 2000.0 if k % 2 else 3900.0)
+       for k in range(0, 200)]
+ROWS_W, _, _ = run_day("p3_ch_sell", hours=1.5, house=_sw,
+                       soc0={"a": 60.0, "b": 30.0})
+_per_q = {}
+for a_, b_ in zip(ROWS_W, ROWS_W[1:]):
+    if a_["action"] != arbitrage.CHARGE and b_["action"] == arbitrage.CHARGE:
+        q = int(b_["now"].timestamp() // 900)
+        _per_q[q] = _per_q.get(q, 0) + 1
+print(f"    house swinging 2.0/3.9 kW each minute: charge starts per period "
+      f"{sorted(_per_q.values())}")
+check("a charge the peak guard or the headroom stopped stays off for the "
+      "rest of that 15-minute period (at most one start per period)",
+      _per_q and max(_per_q.values()) == 1)
+
+# At the floor: B starts the sale just above it.
+ROWS_F, _, _ = run_day("p3_ch_sell", start_h=18.75, hours=1.5,
+                       soc0={"a": 60.0, "b": 24.0})
+_sf = [r for r in ROWS_F if r["action"] == arbitrage.DISCHARGE]
+_after = [r for r in ROWS_F if r["now"].astimezone(L).hour == 19
+          and r["soc"]["b"] <= 20.0]
+_lastf = nth(ROWS_F, -1, "the last cycle")
+print(f"    from 24 %: sold {len(_sf)} cycles, B ends at "
+      f"{_lastf['soc']['b'] if present(_lastf) else _lastf} %")
+check("the sale stops at arbitrage_soc_floor and does not re-arm in the run",
+      _sf and _after and all(r["action"] != arbitrage.DISCHARGE
+                             for r in _after))
+packmode.SELLING_ENABLED = _SELL_SHIPPED
+
+# N=1: one Cheap hours battery.
+ROWS1, _, _ = run_day("p3_ch_sell", n=1, soc0={"a": 30.0},
+                      choice={"a": (True, "cheap_hours", False)},
+                      hours=3.0)
+_c1 = [r for r in ROWS1 if r["action"] == arbitrage.CHARGE]
+check("at one inverter the same rules: it charges in the cheap run, sized "
+      "under the aim", _c1 and max(r["grid"] for r in _c1) < AIM + 400)
+
+# ============================================================================ #
+print("\n5. a refusal wins over a run")
+ROWS_R, _, _ = run_day("p3_ch_sell", hours=1.0, soc0={"a": 60.0, "b": 30.0},
+                       refuse=("b",))
+_first = nth(ROWS_R, 0, "the first cycle")
+_ref = [r for r in ROWS_R if present(_first)
+        and r["now"] > _first["now"] + timedelta(minutes=3)]
+print(f"    B refuses to charge; after 3 min: trades "
+      f"{sorted({str(r['action']) for r in _ref})}, B roles "
+      f"{sorted({r['roles'].get(B) for r in _ref})}")
+check("B refusing to charge: no grid trade is filed after the refusal is "
+      "learned, B's role is no longer 'charge', and A covers the house",
+      _ref and all(r["action"] is None for r in _ref)
+      and all(r["roles"].get(B) != modetrade.CHARGE for r in _ref)
+      and sum(r["shares"].get(A, 0) > 0 for r in _ref) > len(_ref) / 2)
+
+# ============================================================================ #
+print("\n6. no prices, no gap, Solar first alone")
+
+
+def _no_plan(c):
+    c.tariff_plan = None
+    c.fresh_tariff_plan = lambda now: None
+
+
+ROWS_N, _, _ = run_day("p3_ch_sell", hours=1.0, patch=_no_plan,
+                       soc0={"a": 60.0, "b": 60.0}, house_w=1500.0)
+check("no prices: no trade, and Leftover solar / Cheap hours follow the "
+      "house (they give power, not held forever)",
+      all(r["action"] is None for r in ROWS_N)
+      and all(r["roles"].get(B) == modetrade.HOUSE for r in ROWS_N)
+      and any(r["shares"].get(B, 0) > 0 for r in ROWS_N))
+ROWS_S, _, _ = run_day("p3_ch_sell", hours=21.0,
+                       choice={"a": (True, "solar_first", False),
+                               "b": (True, "solar_first", True)})
+check("both batteries Solar first: never a grid charge or a sale all day, "
+      "even with selling switched on",
+      all(r["action"] is None for r in ROWS_S))
+
+# ============================================================================ #
+print("\n7. a run edge reseeds the loop")
+
+
+def _no_reseed(c):
+    c._reseed_run_edge = lambda claims: None
+
+
+def edge(rows, kind):
+    for i in range(1, len(rows)):
+        if rows[i - 1]["action"] == kind and rows[i]["action"] != kind:
+            w = [r["grid"] for r in rows[i:i + 36]]
+            return min(w), max(w)
+    return None
+
+
+_e_on = edge(run_day("p3_ch_sell", hours=3.0, house_w=800.0,
+                     soc0={"a": 60.0, "b": 70.0})[0], arbitrage.CHARGE)
+_e_off = edge(run_day("p3_ch_sell", hours=3.0, house_w=800.0,
+                      soc0={"a": 60.0, "b": 70.0}, patch=_no_reseed)[0],
+              arbitrage.CHARGE)
+print(f"    grid in the 3 min after a 2.5 kW charge ends, 800 W house: "
+      f"reseeded {_e_on}, not reseeded {_e_off}")
+check("reseeded, the loop takes over without the import spike the trade's "
+      "watts leave behind (and exports no more than without)",
+      _e_on and _e_off and _e_on[1] < 1000 and _e_off[1] > 2000
+      and _e_on[0] > _e_off[0] - 100)
+
+# ============================================================================ #
+print("\n8. the site Why row (OPT-11 P1 test, F2)")
+_cl = [Claim.set("loop", P_LOOP, 1200.0), Claim.limit("peak", P_PEAK,
+                                                      lo=2500.0)]
+_up = Resolution(2500.0, "loop", bound_by="peak(quarter peak)")
+_dn = Resolution(800.0, "loop", bound_by="peak(quarter peak)")
+check("a peak floor that raised the power reads 'raised for the peak limit', "
+      "never 'held back'",
+      why_raised(_up, _cl) is True and "held back" not in messages.why(
+          "loop", 2500.0, "peak(quarter peak)", raised=True)
+      and "raised for the peak limit" in messages.why(
+          "loop", 2500.0, "peak(quarter peak)", raised=True))
+check("...a limit that lowered it still reads 'held back'",
+      why_raised(_dn, _cl) is False
+      and "held back by" in messages.why("loop", 800.0, "pack"))
+check("...and a trade the peak floor raised reads the same way",
+      why_raised(Resolution(2000.0, "arbitrage", bound_by="peak"),
+                 [Claim.set("arbitrage", P_ARBITRAGE, -1000.0)]) is True)
+
+# ============================================================================ #
+print("\n9. the selling switch is off (owner decision 2026-09-29, option A)")
+_st = rp._Store()
+_st.data[unit_key(B, packmode.SELL_KEY)] = True     # an old stored "on"
+_st.data[unit_key(B, packmode.MODE_KEY)] = packmode.CHEAP_HOURS
+_ctl = Controller(dict(rp.options(True, False)), rp.Hass(("a", "b"),
+                  lambda t: 0.0), _st, rp._Pub(), stop=asyncio.Event())
+_r9 = [asyncio.run(_ctl.handle_action("pack_sell", unit=B, value=v))
+       for v in (True, False, "yes")]
+check("pack_sell is refused with the plain reason 'Selling is off for now.' "
+      "and stores nothing",
+      all(x == {"error": messages.pack_refused("sell_off")} for x in _r9)
+      and _st.data[unit_key(B, packmode.SELL_KEY)] is True
+      and not any("selling switched" in str(e) for e in _ctl.events))
+check("...a stored 'on' reads as false: no battery sells or can, whatever "
+      "the store holds", packmode.SELLING_ENABLED is False
+      and packmode.read(_st.data, B).sell is False
+      and packmode.read(_st.data, B).can_sell is False
+      and all(p.sell is False for p in _ctl._mode_packs()))
+
+# ============================================================================ #
+print("\n10. the Batteries screen")
+_keys = set(homeview.ROLE_WHY.values()) | {"saves_later", "no_prices",
+                                             "no_spread"}
+_en, _nl = homeview.uitext.words("en"), homeview.uitext.words("nl")
+check("every role's Why line has words in English and Dutch, and they differ",
+      all(k in _en["home_words"]["why"] and k in _nl["home_words"]["why"]
+          and _en["home_words"]["why"][k] != _nl["home_words"]["why"][k]
+          for k in _keys))
+packmode.SELLING_ENABLED = True      # the kept sell code, as in part 4
+_c10 = run_day("p3_ch_sell", start_h=18.0, hours=0.5,
+               soc0={"a": 60.0, "b": 80.0})[2]
+_now10 = D0 + timedelta(hours=18, minutes=30)
+_plan = homeview.mode_runs(_c10, *homeview.local_day(_now10.astimezone(
+    timezone.utc)), _now10.astimezone(timezone.utc), False)
+packmode.SELLING_ENABLED = _SELL_SHIPPED
+print(f"    plan blocks for B at 18:30: "
+      f"{[(r['from'], r['to'], r['kind'], r['what']) for r in _plan[0]]}")
+check("the plan draws B's expensive run, the sale inside it, and nothing "
+      "for Solar first A", _plan[0]
+      and {r["battery"] for r in _plan[0]} == {1}
+      and any(r["kind"] == "give" for r in _plan[0]))
+_sale = [r for r in _plan[0] if r["what"].startswith("Sells")]
+check("a sale block shows no money: the price shown is what the house pays, "
+      "and a sale earns the lower injection price",
+      _sale and all(r["amount"] is None and r["eur"] is None for r in _sale))
+_why = homeview.battery_why(
+    modes_on=True, mode=packmode.CHEAP_HOURS, off=False, reading=True,
+    phase="idle", shadow=False, running=True, held=False, refused=0,
+    peak=False, sf_ahead=True, role="hold", has_at=True)
+check("a holding battery's Why names when it gives power",
+      _why == "saves" and "18:00 - 19:00" in homeview.why_words(
+          _why, at="18:00 - 19:00"))
+
+# ============================================================================ #
+print("\n11. review additions (PR #153): gaps four mutants survived")
+import types                                                   # noqa: E402
+import app.main as _main                                       # noqa: E402
+
+# Modes on with the site switch on: only the modes trade (R13).
+ROWS_X, _, _ = run_day("p2_arb", hours=3.0, soc0={"a": 30.0, "b": 30.0},
+                       choice={"a": (True, "solar_first", False),
+                               "b": (True, "solar_first", False)})
+check("modes on, 'Trade on the price spread' on, both batteries Solar first: "
+      "no trade all through the cheap hours (the site trade is not run)",
+      ROWS_X and all(r["action"] is None for r in ROWS_X)
+      and all(v >= 0 for r in ROWS_X for v in r["shares"].values())
+      and not any(r["winner"].startswith("arbitrage") for r in ROWS_X))
+
+# A battery in a maintenance phase takes no part in a run (R10).
+ROWS_M, _, _cm = run_day("p3_ch_sell", hours=0.6, house_w=800.0,
+                         soc0={"a": 60.0, "b": 30.0})
+_lm = nth(ROWS_M, -1, "the last cycle")
+_nm = _lm["now"] if present(_lm) else None
+_tm = _cm._mode_roles(_nm, [types.SimpleNamespace(phase=_main.IDLE),
+                            types.SimpleNamespace(phase="CHARGE")]) \
+    if _nm is not None else None
+check("a battery in its monthly cycle is not a charger: no range, no charge "
+      "role, and no grid charge when it is the only price battery",
+      _tm is not None and B not in _tm.ranges
+      and _tm.roles.get(B) != modetrade.CHARGE and _tm.action is None)
+
+# The headroom stopping a charge latches it off for the period (R8).
+_cm2 = run_day("p3_ch_sell", hours=0.6, house_w=800.0,
+               soc0={"a": 60.0, "b": 30.0})[2]
+_ok8 = False
+if _nm is not None and _cm2.mode_tick is not None \
+        and _cm2.mode_tick.action == modetrade.CHARGE:
+    _q = int(_nm.timestamp() // 900)
+    _cm2.arb_headroom_w = 0.0
+    _t1 = _cm2._mode_roles(_nm, None)
+    _cm2.arb_headroom_w = 3000.0
+    _t2 = _cm2._mode_roles(_nm + timedelta(seconds=5), None)
+    _nq = datetime.fromtimestamp((_q + 1) * 900 + 5, timezone.utc)
+    _cm2.tariff_at = _nq
+    _t3 = _cm2._mode_roles(_nq, None)
+    _ok8 = (_t1.why == "headroom" and _cm2._charge_blocked_q in (_q, _q + 1)
+            and _t2.action is None and _t3.action == modetrade.CHARGE)
+check("a charge the headroom stopped stays off for the rest of the period, "
+      "even when the headroom comes back, and may start in the next one", _ok8)
+
+# ============================================================================ #
+print("\n12. option A: no sale, and Leftover solar takes solar only (P4)")
+ROWS_A, _, _ = run_day("p3_ch_sell", soc0={"a": 60.0, "b": 30.0},
+                       choice={"a": (True, "solar_first", False),
+                               "b": (True, "cheap_hours", True)})
+print(f"    Cheap hours B with a stored sell 'on': "
+      f"{sum(r['action'] == arbitrage.CHARGE for r in ROWS_A)} charging, "
+      f"{sum(r['action'] == arbitrage.DISCHARGE for r in ROWS_A)} selling")
+check("with selling on in the store, a whole day has no sale and no sell "
+      "role, while Cheap hours only still charges from the grid",
+      all(r["action"] != arbitrage.DISCHARGE for r in ROWS_A)
+      and all(modetrade.SELL not in r["roles"].values() for r in ROWS_A)
+      and any(r["action"] == arbitrage.CHARGE for r in ROWS_A))
+ROWS_L, _, _c12 = run_day("p3_ch_sell", soc0={"a": 60.0, "b": 30.0},
+                          choice={"a": (True, "solar_first", False),
+                                  "b": (True, "leftover_solar", True)})
+_lh = [r for r in ROWS_L if r["roles"].get(B) == modetrade.HOLD]
+_lg = [r for r in ROWS_L if r["roles"].get(B) == modetrade.GIVE]
+print(f"    Leftover solar B: {len(_lh)} holding, {len(_lg)} giving, "
+      f"grid trades {sorted({str(r['action']) for r in ROWS_L})}")
+check("Leftover solar never charges from the grid before the forecast: no "
+      "grid trade and no charge role all day, in the same cheap run",
+      all(r["action"] is None for r in ROWS_L)
+      and all(r["roles"].get(B) != modetrade.CHARGE for r in ROWS_L))
+check("...it still saves its power and gives it in the expensive hours",
+      _lh and _lg and all(r["now"].astimezone(L).hour == 19 for r in _lg))
+_pk = [modetrade.Pack("x", True, m, False, 2500.0, 30.0, 10.0)
+       for m in packmode.MODES]
+check("...only Cheap hours only is a grid charger (packmode.GRID_CHARGE_MODES)",
+      [p.mode for p in modetrade.chargers(_pk, 95.0)]
+      == [packmode.CHEAP_HOURS])
+_c12b = run_day("p3_ch_sell", start_h=0.75, hours=0.25,
+                soc0={"a": 60.0, "b": 30.0},
+                choice={"a": (True, "solar_first", False),
+                        "b": (True, "leftover_solar", True)})[2]
+_n12 = UTC0 + timedelta(hours=1)
+_plan12 = homeview.mode_runs(_c12b, *homeview.local_day(_n12), _n12,
+                             False)[0]
+print(f"    Leftover solar plan at 01:00: "
+      f"{[(r['from'], r['to'], r['kind']) for r in _plan12]}")
+check("...and the plan draws no grid block for it, only its expensive run",
+      _plan12 and all(r["kind"] != "grid" for r in _plan12))
+_enw, _nlw = homeview.uitext.words("en"), homeview.uitext.words("nl")
+check("...and its help text promises no grid charging (EN and NL)",
+      all("cheap" not in t.lower() and "goedkop" not in t.lower()
+          for t in (_enw["home"]["batteries"]["choice"]["leftover_solar"]
+                    ["description"],
+                    _nlw["home"]["batteries"]["choice"]["leftover_solar"]
+                    ["description"],
+                    _enw["home"]["batteries"]["how"]["leftover_solar"]
+                    ["description"],
+                    _nlw["home"]["batteries"]["how"]["leftover_solar"]
+                    ["description"])))
+
+print()
+if fails:
+    print(f"{len(fails)} FAILED:")
+    for f in fails:
+        print(f"  - {f}")
+    sys.exit(1)
+print("all checks passed")

goodwe_controller/test_mqtt.py

@@ -996,7 +996,8 @@ check("modes off: every configuration announces byte-for-byte what ed739d4 "
 MODES = packmode.MODES
 ON1, SUB1 = announce_p2(["inverter-a"], modes=MODES)
 m, c, a = report("roster of one, modes on", ON1)
-_opt = '["Solar first", "Leftover solar"]'
+# P2 announced the first two; OPT-11 P3 appended "Cheap hours only".
+_opt = '["Solar first", "Leftover solar", "Cheap hours only"]'
 MODE_N1 = [
     ("homeassistant/select/goodwe_ctl_unit_inverter_a_mode/config",
      '{"name": "Inverter A Mode", "object_id": "goodwe_inverter_a_mode", '
@@ -1062,16 +1063,19 @@ check("each HA mode option is the page's English name for that mode, in "
       "both places the page names it",
       all(mqtt.MODE_LABELS[k] == _en["home_words"]["modes"][k]
           == _en["home"]["batteries"]["choice"][k]["name"] for k in MODES))
-_later = dict(mqtt.MODE_LABELS, cheap_hours="Cheap hours only")
+# OPT-11 P3 added `cheap_hours`: against P2's two modes (7a00f12), only the
+# options list changes, by one entry at its end; no topic, id or label moves.
+_p3 = mqtt.mode_payloads(NAMES2, MODES)
 _orig = mqtt.MODE_LABELS
-mqtt.MODE_LABELS = _later
+mqtt.MODE_LABELS = {k: v for k, v in _orig.items() if k != "cheap_hours"}
 try:
-    _p3 = mqtt.mode_payloads(NAMES2, MODES + ("cheap_hours",))
+    _p2 = mqtt.mode_payloads(NAMES2, MODES[:2])
 finally:
     mqtt.MODE_LABELS = _orig
-_p2 = mqtt.mode_payloads(NAMES2, MODES)
-check("...(simulated P3: adding `cheap_hours` changes only the options list, "
-      "by one entry at its end)",
+check("...P3 appended `cheap_hours`: against P2's list only the options "
+      "change, by one entry at the end, and P2's two labels are unchanged",
+      MODES[:2] == ("solar_first", "leftover_solar")
+      and _p2[0][1]["options"] == ["Solar first", "Leftover solar"] and
       [t for t, _ in _p3] == [t for t, _ in _p2]
       and all({k: v for k, v in x.items() if k != "options"}
               == {k: v for k, v in y.items() if k != "options"}
@@ -1261,7 +1265,7 @@ BAD = [
     (f"{T_A}/use/set", b"true"), (f"{T_A}/use/set", b"1"),
     (f"{T_A}/use/set", b""),
     (f"{T_A}/mode/set", b"solar_first"),          # a key, not the option
-    (f"{T_A}/mode/set", b"Cheap hours only"),     # not offered before P3
+    (f"{T_A}/mode/set", b"Sell only"),            # not an offered mode
     (f"{T_A}/mode/set", b"solar first"),
     (f"{T_A}/mode/set", "Sοlar first".encode()),  # Greek omicron
     (f"{T_A}/mode/set", b"Solar first\x00"),

goodwe_controller/test_peak_margin.py

@@ -0,0 +1,298 @@
+"""Runnable check for SAFETY-79, the margin under the peak limit.
+`python3 test_peak_margin.py`
+
+The peak guard aims at `peak_cap_w - peak_margin_w` (default 50 W); the bill
+and every report keep the real `peak_cap_w`. DECISIONS/SAFETY-79-peak-margin.md
+has the record. Drives the REAL Controller through tools/safety79_identity.py.
+
+1. `peak_margin_w: 0` is byte-identical to release/1.0 ed739d4.
+2. The guard aims at cap - margin at N=1 and N=2, and with OPT-11 modes on an
+   Off battery covers the shortfall to cap - margin.
+3. The bill and the reports still use the real cap.
+4. Each call site in main.py passes the value its side needs.
+5. The setting: default, range, refusals in plain words.
+
+Mutations (MUTATION.md, purged copies) are listed in the pull request.
+"""
+
+import ast
+import os
+import re
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.join(HERE, "tools"))
+
+import safety79_identity as rig                               # noqa: E402
+from named_absence import nth, present                        # noqa: E402
+from style_rules import text_problems                         # noqa: E402
+from app import messages, peakguard                 # noqa: E402
+from app.control import maintenance_charge_floor              # noqa: E402
+from app.peakguard import (PEAK_MARGIN_RANGE_W,               # noqa: E402
+                           PEAK_OPTION_DEFAULTS, quarter_target_w)
+from app.validate import config_notes, validate_startup_config  # noqa: E402
+
+fails = []
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+CAP = float(rig.CAP_W)
+
+# ============================================================================ #
+print("1. peak_margin_w 0: byte-identical to release/1.0 ed739d4")
+# Printed by `python3 tools/safety79_identity.py 0` on the ed739d4 tree (the
+# tool copied in, nothing else changed; that tree ignores the key), in the CI
+# image; re-printed 2026-09-29 (review) after adding the charge headroom, the
+# shaping suspension and the two maintenance scenarios. 540 cycles each.
+ED739D4 = {
+    "n1": "82316f7d4362fae4c035a1bed5e7907cf362faba994c634d0b1c356c501f53e5",
+    "n2": "0dc24e16a8390ec42edacf735eaf20273847b33b9c67d7cdc536df0ca739e421",
+    "n1_off": "eed44f058f3fcc6e7651c5c84c6fa6313e7520035ad7cac282012cf6909668a0",
+    "n2_off": "69796c107b9f78892e04d282b754f889590acf9fe1b96f09525f5ea2005e9c0a",
+    "n1_maint":
+        "bd4a88a10aa840a360ac781ac04e30b040a5aac5426fabba1fb259d71dfeba67",
+    "n2_maint":
+        "0656bc5a4a2fa3a7455822fdd7da5f68f57fd9593f374e869a0d30ba7e429275",
+}
+_zero = rig.digests(0)
+_default = rig.digests()
+for k in ED739D4:
+    print(f"    {k:7} margin 0 {'same' if _zero[k] == ED739D4[k] else 'DIFFERS'}"
+          f" {_zero[k][:16]}, default {_default[k][:16]}")
+check("⭐ at N=1 and N=2, with and without battery modes and with a "
+      "maintenance charge, margin 0 is "
+      "byte-identical to ed739d4", _zero == ED739D4)
+check("...and the default (key absent) changes every scenario, so the "
+      "scenarios do reach the margin", all(_default[k] != ED739D4[k]
+                                          for k in ED739D4))
+
+# ============================================================================ #
+print("\n2. the guard aims at cap - margin")
+_runs = {}
+for name, spec in rig.SCENARIOS.items():
+    for m in (None, 0, 120):
+        _runs[name, m] = rig.run(**spec, margin=m, dur=3600.0)
+for name in rig.SCENARIOS:
+    g = _runs[name, None][1].peak_guard
+    print(f"    {name}: margin {_runs[name, None][1].peak_margin_w:.0f} W, "
+          f"aims at {g.target_w:.0f} W, limit {g.ceiling_w:.0f} W")
+check("test_target_is_cap_minus_margin: with the key absent every scenario "
+      "(N=1, N=2, modes on and off) aims at cap - 50 and reports the cap",
+      all(_runs[n, None][1].peak_margin_w == 50.0
+          and _runs[n, None][1].peak_guard.target_w == CAP - 50
+          and _runs[n, None][1].peak_guard.ceiling_w == CAP
+          for n in rig.SCENARIOS))
+check("...and a margin of 120 moves the aim to cap - 120, a margin of 0 to "
+      "the cap", all(_runs[n, 120][1].peak_guard.target_w == CAP - 120
+                     and _runs[n, 0][1].peak_guard.target_w == CAP
+                     for n in rig.SCENARIOS))
+
+
+def banked(ctl):
+    return {b.start.strftime("%H:%M"): round(b.offtake_avg_w, 2)
+            for b in ctl.p1.blocks}
+
+
+_b = {m: banked(_runs["n1_off", m][1]) for m in (0, None, 120)}
+print(f"    N=1, the battery Off: quarters banked {_b}")
+check("test_off_battery_n1: at N=1 with the battery Off, the guard makes it "
+      "give just enough to bank the 11:30 quarter at cap - margin (2500, "
+      "2450, 2380 W for margins 0, 50, 120)",
+      [_b[m]["11:30"] for m in (0, None, 120)]
+      == [CAP, CAP - 50, CAP - 120])
+
+
+def meter_at(rows, t):
+    row = next((r for r in rows if r[0] == t), None)
+    if row is None:
+        return None, {}
+    return rig.load(t) - sum(w for _u, w in row[2]), dict(row[2])
+
+
+_g0, _c0 = meter_at(_runs["n2_off", 0][0], 1800.0)
+_g50, _c50 = meter_at(_runs["n2_off", None][0], 1800.0)
+print(f"    N=2, B Off, 6000 W house: margin 0 -> {_c0}, meter {_g0} W; "
+      f"margin 50 -> {_c50}, meter {_g50} W")
+check("test_off_battery_n2: at N=2 with B Off and A at its rating, B covers "
+      "the shortfall to cap - margin, not to the cap",
+      _c0["b"] == 1000.0 and _g0 == CAP
+      and _c50["b"] == 1050.0 and _g50 == CAP - 50)
+
+def _peak(w, observed=True):
+    return type("R", (), {"is_observed": observed, "peak_w": w})()
+
+
+# Review (SAFETY-79 point 2): the margin applies under a month peak already
+# banked, too. Aiming AT it can bank a few W over it, which raises the bill;
+# and a banked peak between cap - margin and the cap (a quarter the old guard
+# held at the cap, say) was aimed at exactly, so one overshoot crossed the cap.
+check("test_margin_under_banked_peak: the aim is the margin under the limit "
+      "that holds - the cap, or a month peak already banked above it",
+      quarter_target_w(CAP, 50, _peak(2499.0)) == CAP - 50
+      and quarter_target_w(CAP, 50, _peak(3000.0)) == 2950.0
+      and quarter_target_w(CAP, 50, _peak(3000.0, observed=False)) == CAP - 50
+      and quarter_target_w(CAP, 50, None) == CAP - 50
+      and quarter_target_w(CAP, 0, _peak(3000.0)) == 3000.0)
+
+
+def _decide(banked_w, projected_w):
+    """Half a quarter at `projected_w`, battery idle, a month peak banked."""
+    from datetime import datetime, timezone
+    from app.tariff import Projection
+    pr = Projection(projected_w, projected_w, 450.0, 1.0, False,
+                    datetime(2026, 9, 1, 12, 0, tzinfo=timezone.utc),
+                    projected_w)
+    return peakguard.decide(pr, batt_w=0.0, cap_w=CAP, margin_w=50,
+                            reading=_peak(banked_w), achievable_w=5000.0,
+                            soc=60.0, soc_floor=20.0)
+
+
+_d1, _d2 = _decide(2499.0, 2600.0), _decide(3000.0, 3100.0)
+print(f"    banked 2499 W: floor {_d1.floor_w}, limit {_d1.ceiling_w}; "
+      f"banked 3000 W: floor {_d2.floor_w}, limit {_d2.ceiling_w}")
+check("...and decide() sizes the floor to land the quarter 50 W under it "
+      "(2449 and 2950 W), while the reported limit stays the cap or the peak",
+      _d1.floor_w == 2 * (2600.0 - 2450.0) and _d1.ceiling_w == CAP
+      and _d2.floor_w == 2 * (3100.0 - 2950.0) and _d2.ceiling_w == 3000.0)
+
+# ============================================================================ #
+print("\n3. the bill and the reports keep the real cap")
+_c = _runs["n1_off", None][1]
+_pk = _c.peak.peak().peak_w
+print(f"    month peak {_pk:.0f} W, tracker cap {_c.peak.cap_w:.0f} W, "
+      f"warning {_c.peak.warning_frac():.3f}, headroom "
+      f"{_c.peak.headroom_w():.0f} W")
+check("test_billing_uses_cap: the month-peak tracker (bill, headroom, 80 % "
+      "warning) is built on the real cap, not cap - margin",
+      _c.peak.cap_w == CAP and _c.peak.warning_frac() == _pk / CAP
+      and _c.peak.headroom_w() == CAP - _pk)
+_eng = [g for r in _runs["n1_off", None][0] for g in (r[-1][1],)
+        if g and g[0] and g[1]]
+print(f"    {len(_eng)} engaged cycles; one: {_eng[0][4] if _eng else None}")
+check("test_reports_use_cap: every engaged sentence names the real limit and "
+      "the aim beside it", _eng and all(
+          g[2] == CAP and "against a 2500 W limit (peak_cap_w), aiming at "
+          "2450 W" in g[4] for g in _eng))
+check("...and the settings note compares the month peak with the real cap: "
+      "a 2480 W peak under a 2500 W cap is no warning, 2520 W is",
+      config_notes({"peak_cap_w": 2500, "peak_margin_w": 50},
+                   month_peak_w=2480) == []
+      and [n.keys for n in config_notes({"peak_cap_w": 2500,
+                                         "peak_margin_w": 50},
+                                        month_peak_w=2520)]
+      == [("peak_cap_w",)])
+_lim = _eng[0][2] if _eng else 0.0
+_notice = messages.peak_saturated(_lim)
+check("...and the user-facing peak notice built from the decision's limit "
+      "says the cap", messages.watts(CAP) in _notice.body
+      and messages.watts(CAP - 50) not in _notice.body)
+
+# ============================================================================ #
+print("\n4. each call site in main.py")
+with open(os.path.join(HERE, "app", "main.py"), encoding="utf-8") as f:
+    _src = f.read()
+_tree = ast.parse(_src)
+
+
+def calls(name):
+    return [n for n in ast.walk(_tree) if isinstance(n, ast.Call)
+            and isinstance(n.func, (ast.Attribute, ast.Name))
+            and getattr(n.func, "attr", getattr(n.func, "id", "")) == name]
+
+
+def kw(call, key):
+    if not present(call):
+        return "absent"
+    return next((ast.get_source_segment(_src, k.value) for k in call.keywords
+                 if k.arg == key), "absent")
+
+
+def arg(call, i):
+    if not present(call) or len(call.args) <= i:
+        return "absent"
+    return ast.get_source_segment(_src, call.args[i])
+
+
+_dec = [c for c in calls("decide")
+        if getattr(c.func, "value", None) is not None
+        and getattr(c.func.value, "id", "") == "peakguard"]
+_shape = calls("shaping_suspended")
+_maint = calls("maintenance_charge_floor")
+_tracker = calls("PeakTracker")
+_d, _s, _m, _t = (nth(_dec, 0, "peakguard.decide()"),
+                  nth(_shape, 0, "shaping_suspended()"),
+                  nth(_maint, 0, "maintenance_charge_floor()"),
+                  nth(_tracker, 0, "PeakTracker()"))
+print(f"    decide(cap_w={kw(_d, 'cap_w')}, margin_w={kw(_d, 'margin_w')})")
+print(f"    shaping_suspended(..., {arg(_s, 2)})")
+print(f"    maintenance_charge_floor(..., {arg(_m, 2)})")
+print(f"    PeakTracker(cap_w={kw(_t, 'cap_w')})")
+check("test_call_sites: the guard gets the real cap AND the margin; the "
+      "forecast checks get cap - margin; the month-peak tracker gets the "
+      "real cap",
+      len(_dec) == 1 and "peak_cap_w" in kw(_d, "cap_w")
+      and kw(_d, "margin_w") == "self.peak_margin_w"
+      and len(_shape) == 1 and len(_maint) == 1
+      and arg(_s, 2) == "self.peak_aim_w()"
+      and arg(_m, 2) == "self.peak_aim_w()"
+      and len(_tracker) == 1
+      and kw(_t, "cap_w") == 'float(opts.get("peak_cap_w", 3500))')
+check("test_aim_w: `peak_aim_w()` is cap - margin, and the forecast sizing "
+      "gives a maintenance charge only what is left under it",
+      _c.peak_aim_w() == CAP - 50
+      and maintenance_charge_floor(2000.0, 2400.0, _c.peak_aim_w()) == 50.0
+      and peakguard.shaping_suspended(None, 2470.0, _c.peak_aim_w())
+      and not peakguard.shaping_suspended(None, 2470.0, CAP))
+
+# ============================================================================ #
+print("\n5. the setting")
+
+
+with open(os.path.join(HERE, "config.yaml"), encoding="utf-8") as f:
+    _hits = re.findall(r"^  peak_margin_w:\s*(\S+)", f.read(), re.M)
+print(f"    config.yaml: {_hits}")
+check("config.yaml ships 50, int(0,500), and the in-code mirror matches",
+      _hits == ["50", "int(0,500)"]
+      and PEAK_OPTION_DEFAULTS["peak_margin_w"] == 50
+      and PEAK_MARGIN_RANGE_W == (0, 500))
+
+BASE = {"setpoint_entity": "number.sp", "meter_entity": "sensor.grid",
+        "max_w": 2000, "peak_cap_w": 3500}
+_base_problems = validate_startup_config(BASE)
+
+
+def refused(value, **more):
+    opts = dict(BASE, peak_margin_w=value, **more)
+    return [p for p in validate_startup_config(opts)
+            if p not in _base_problems]
+
+
+_ok = {v: refused(v) for v in (0, 50, 500)}
+_bad = {v: refused(v) for v in (-1, 501, 12.5, "abc")}
+for v, p in _bad.items():
+    print(f"    {v!r}: {p}")
+check("test_margin_range: 0, 50 and 500 are accepted, and so is the key "
+      "absent", not any(_ok.values()) and _base_problems == [])
+check("...and below 0, above 500, not whole, or not a number is refused, "
+      "once, naming the setting and the range",
+      all(len(p) == 1 and "“Margin below the peak limit” (peak_margin_w)"
+          in p[0] and "from 0 to 500 W" in p[0] for p in _bad.values()))
+_high = refused(500, peak_cap_w=500)
+print(f"    500 under a 500 W limit: {_high}")
+check("...and a margin that leaves nothing under the limit is refused",
+      len(_high) == 1 and "not below" in _high[0])
+_style = [text_problems(p[0], keys=("peak_margin_w", "peak_cap_w"),
+                        entities=False) for p in list(_bad.values()) + [_high]]
+check(f"...in plain words (STYLE.md): {_style}", not any(_style))
+
+
+print()
+if fails:
+    print(f"{len(fails)} FAILED: {', '.join(fails)}")
+    sys.exit(1)
+print("all checks passed")

goodwe_controller/test_peakguard.py

@@ -368,7 +368,7 @@ check("...and it grows monotonically through the quarter, so the guard is at "
 BATT_NOW = 400.0
 a_edge = averager_at(CEIL, 450.0)
 p_edge = PeakTracker.project(a_edge, B + timedelta(seconds=450))
-d_edge = decide(p_edge, batt_w=BATT_NOW, cap_w=CAP_W, reading=None,
+d_edge = decide(p_edge, batt_w=BATT_NOW, cap_w=CAP_W, margin_w=0.0, reading=None,
                 achievable_w=LIVE_MAX_W, max_hold_s=MAX_HOLD_S, soc=SOC_OK, soc_floor=SOC_FLOOR)
 e_edge = excess_w(p_edge, CEIL)
 print(f"    held exactly AT the ceiling for 450 s: projected "
@@ -383,7 +383,7 @@ check("at the engagement boundary the excess is zero, so the floor is exactly "
 # than on the excess. Re-derived here rather than described: a guard that
 # released as soon as `excess <= 0` hands the actuator back at the exact instant
 # it is working, and the load springs straight back.
-released = decide(p_edge, batt_w=BATT_NOW, cap_w=CAP_W, reading=None,
+released = decide(p_edge, batt_w=BATT_NOW, cap_w=CAP_W, margin_w=0.0, reading=None,
                   achievable_w=LIVE_MAX_W, max_hold_s=MAX_HOLD_S, soc=SOC_OK, soc_floor=SOC_FLOOR)
 would_release_on_excess = excess_w(p_edge, CEIL) <= 0.0
 # ⚠️ `floor_w` IS FORMATTED DEFENSIVELY, AND MUTATION.md's OWN LEDGER IS WHY.
@@ -404,7 +404,7 @@ check("...and the claim is held there, not released. `excess` falls to zero as "
       "arithmetic read as a level", would_release_on_excess and released.engaged)
 d_gone = decide(PeakTracker.project(averager_at(500.0, 450.0),
                                     B + timedelta(seconds=450)),
-                batt_w=BATT_NOW, cap_w=CAP_W, reading=None,
+                batt_w=BATT_NOW, cap_w=CAP_W, margin_w=0.0, reading=None,
                 achievable_w=LIVE_MAX_W, max_hold_s=MAX_HOLD_S, soc=SOC_OK, soc_floor=SOC_FLOOR)
 check("...and it DOES release once the load falls under what the quarter can "
       "afford, so 'threshold the floor' is not 'never let go'",
@@ -413,7 +413,7 @@ check("...and it DOES release once the load falls under what the quarter can "
 # A hair over, and the floor is the battery plus the excess. Not a constant.
 a_over = averager_at(CEIL + 200.0, 450.0)
 p_over = PeakTracker.project(a_over, B + timedelta(seconds=450))
-d_over = decide(p_over, batt_w=BATT_NOW, cap_w=CAP_W, reading=None,
+d_over = decide(p_over, batt_w=BATT_NOW, cap_w=CAP_W, margin_w=0.0, reading=None,
                 achievable_w=LIVE_MAX_W, max_hold_s=MAX_HOLD_S, soc=SOC_OK, soc_floor=SOC_FLOOR)
 print(f"    200 W over for 450 s: {d_over.explain()}")
 check("a quarter projected over the ceiling engages, and the floor is the "
@@ -422,7 +422,7 @@ check("a quarter projected over the ceiling engages, and the floor is the "
       and near(d_over.floor_w, BATT_NOW + excess_w(p_over, CEIL), 1e-6))
 check("...and the floor moves with the battery measurement, so it is a claim "
       "about delivered power rather than a fixed setpoint",
-      not near(decide(p_over, batt_w=BATT_NOW + 250.0, cap_w=CAP_W, reading=None,
+      not near(decide(p_over, batt_w=BATT_NOW + 250.0, cap_w=CAP_W, margin_w=0.0, reading=None,
                       achievable_w=LIVE_MAX_W, max_hold_s=MAX_HOLD_S, soc=SOC_OK, soc_floor=SOC_FLOOR).floor_w,
                d_over.floor_w, 1.0))
 
@@ -433,7 +433,7 @@ intent = 0.0
 delivered_floor = []
 intent_floor = []
 for _ in range(5):
-    d_del = decide(p_over, batt_w=stuck_batt, cap_w=CAP_W, reading=None,
+    d_del = decide(p_over, batt_w=stuck_batt, cap_w=CAP_W, margin_w=0.0, reading=None,
                    achievable_w=LIVE_MAX_W, max_hold_s=MAX_HOLD_S, soc=SOC_OK, soc_floor=SOC_FLOOR)
     delivered_floor.append(d_del.floor_w)
     intent = intent + excess_w(p_over, CEIL)     # what the intent form would do
@@ -516,7 +516,7 @@ check(f"a loop already discharging harder ({BIG:.0f} W) than the floor is not "
 absurd = averager_at(LIVE_MAX_W * 4, 870.0)
 p_absurd = PeakTracker.project(absurd, B + timedelta(seconds=870))
 DEV_MAX = LIVE_MAX_W - 500.0        # a device rating tighter than max_w
-d_absurd = decide(p_absurd, batt_w=1000.0, cap_w=CAP_W, reading=None,
+d_absurd = decide(p_absurd, batt_w=1000.0, cap_w=CAP_W, margin_w=0.0, reading=None,
                   achievable_w=min(LIVE_MAX_W, DEV_MAX), max_hold_s=MAX_HOLD_S, soc=SOC_OK, soc_floor=SOC_FLOOR)
 r6 = resolve([Claim.limit("device", P_SAFETY, -DEV_MAX, DEV_MAX, "rating"),
               Claim.limit("supervised", P_SAFETY, -LIVE_MAX_W, LIVE_MAX_W, "max_w"),
@@ -599,7 +599,7 @@ print(f"    a real PeakStore on a missing volume: state={rd_broken.state}, "
       f"headroom_w()={tr_broken.headroom_w(B)}")
 check("the real store answers NOT_OBSERVED rather than a peak of 0 W",
       rd_broken.state == NOT_OBSERVED and rd_broken.peak_w is None)
-d_broken = decide(p_over, batt_w=BATT_NOW, cap_w=CAP_W, reading=rd_broken,
+d_broken = decide(p_over, batt_w=BATT_NOW, cap_w=CAP_W, margin_w=0.0, reading=rd_broken,
                   achievable_w=LIVE_MAX_W, max_hold_s=MAX_HOLD_S, soc=SOC_OK, soc_floor=SOC_FLOOR)
 print(f"    {d_broken.explain()}")
 check("AND THE GUARD STILL ENGAGES ON IT. An unreadable peak must not disarm "
@@ -627,7 +627,7 @@ print("4. blindness: three ways a projection is not evidence")
 # (a) NO OPEN BLOCK. A fresh averager projects 0 W - under every ceiling.
 fresh = QuarterAverager(phases=1, max_hold_s=MAX_HOLD_S)
 p_fresh = PeakTracker.project(fresh, B)
-d_fresh = decide(p_fresh, batt_w=0.0, cap_w=CAP_W, reading=None,
+d_fresh = decide(p_fresh, batt_w=0.0, cap_w=CAP_W, margin_w=0.0, reading=None,
                  achievable_w=LIVE_MAX_W, max_hold_s=MAX_HOLD_S, soc=SOC_OK, soc_floor=SOC_FLOOR)
 print(f"    fresh averager: projected {p_fresh.projected_w:.0f} W, "
       f"block_start={p_fresh.block_start}; {d_fresh.explain()}")
@@ -655,7 +655,7 @@ p_frozen = PeakTracker.project(frozen_av, B + timedelta(seconds=600))
 RAILED = LIVE_MAX_W                          # the loop has wound to the rail
 is_frozen = looks_frozen(FREEZE_S + 1.0, -RAILED, LIVE_MAX_W,
                          FreezeWatchdogConfig(hold_s=FREEZE_S))
-d_frozen = decide(p_frozen, batt_w=-RAILED, cap_w=CAP_W, reading=None,
+d_frozen = decide(p_frozen, batt_w=-RAILED, cap_w=CAP_W, margin_w=0.0, reading=None,
                   achievable_w=LIVE_MAX_W, max_hold_s=MAX_HOLD_S, soc=SOC_OK, soc_floor=SOC_FLOOR,
                   frozen=is_frozen)
 print(f"    meter stuck at -4000 W with the command at {-RAILED:+.0f} W: "
@@ -680,7 +680,7 @@ check("...and the same command NOT frozen is left alone, so the blind branch is
       "not simply always on",
       near(resolve(SAFE + [Claim.set("loop", P_LOOP, -RAILED, "grid"),
                            peakguard.claim(decide(
-                               p_frozen, batt_w=-RAILED, cap_w=CAP_W,
+                               p_frozen, batt_w=-RAILED, cap_w=CAP_W, margin_w=0.0,
                                reading=None, achievable_w=LIVE_MAX_W,
                                max_hold_s=MAX_HOLD_S, soc=SOC_OK, soc_floor=SOC_FLOOR, frozen=False))
                            or Claim.limit("noop", P_PEAK)]).target_w,
@@ -692,7 +692,7 @@ gapped = averager_at(4200.0, 600.0, gap_at=200.0, gap_s=GAP)
 p_gap = PeakTracker.project(gapped, B + timedelta(seconds=600))
 clean = averager_at(4200.0, 600.0)
 p_clean = PeakTracker.project(clean, B + timedelta(seconds=600))
-d_gap = decide(p_gap, batt_w=0.0, cap_w=CAP_W, reading=None,
+d_gap = decide(p_gap, batt_w=0.0, cap_w=CAP_W, margin_w=0.0, reading=None,
                achievable_w=LIVE_MAX_W, max_hold_s=MAX_HOLD_S, soc=SOC_OK, soc_floor=SOC_FLOOR)
 print(f"    a {GAP:.0f} s hole at 4200 W: uncovered {uncovered_s(p_gap):.0f} s, "
       f"projected {p_gap.projected_w:.0f} W vs {p_clean.projected_w:.0f} W with "
@@ -756,7 +756,7 @@ check("a renamed held value now raises AttributeError on the first cycle. The "
 OLD = (p_held.partial_ws if hasattr(p_held, "partial_ws")
        else HELD * 300.0)   # acc, which the old form would still have had
 old_projected = (HELD * 300.0 + 0.0 * (QUARTER_S - 300.0)) / QUARTER_S
-d_true = decide(p_held, batt_w=0.0, cap_w=CAP_W, reading=None,
+d_true = decide(p_held, batt_w=0.0, cap_w=CAP_W, margin_w=0.0, reading=None,
                 achievable_w=LIVE_MAX_W, max_hold_s=MAX_HOLD_S, soc=SOC_OK, soc_floor=SOC_FLOOR)
 print(f"    same fixture: shipped projection {p_held.projected_w:.0f} W "
       f"(engaged={d_true.engaged}), the defaulted form's "
@@ -832,7 +832,7 @@ def replay(path, *, guarded: bool, cap_w=CAP_W, max_w=LIVE_MAX_W, pack=None,
         next_cycle = t + timedelta(seconds=CYCLE_S)
         cycles += 1
         d = decide(PeakTracker.project(ing.averager, t),
-                   batt_w=batt, cap_w=cap_w, reading=tracker.peak(t),
+                   batt_w=batt, cap_w=cap_w, margin_w=0.0, reading=tracker.peak(t),
                    achievable_w=max_w, max_hold_s=MAX_HOLD_S, soc=soc,
                    soc_floor=floor_pct, frozen=False)
         if d.floor_w is not None and d.floor_w < 0.0:
@@ -1175,7 +1175,9 @@ def wired_over_limit(db, want_floor_w, opts=None, store=None, batt_w=0.0,
             int(now.timestamp() // QUARTER_S) * QUARTER_S, timezone.utc)
         span = int((now - blk).total_seconds())
         remaining = max(1.0, QUARTER_S - (now - blk).total_seconds())
-        net_w = CAP_W + want_floor_w * remaining / QUARTER_S
+        # SAFETY-79: sized against what the guard aims at, cap - margin.
+        net_w = (CAP_W - ctl.peak_margin_w
+                 + want_floor_w * remaining / QUARTER_S)
         for i in range(0, span + 1, 5):
             ctl.p1.submit(sample(blk + timedelta(seconds=i), net_w))
         # ⚠️ AND ONE TELEGRAM AT `now` ITSELF. The averager credits a sample's
@@ -1257,6 +1259,13 @@ check(f"the saturating fixture ({NET2:.0f} W) is a load the real ingest "
       f"accepts, not one it rejects as implausible", NET2 < PLAUSIBLE_MAX_W)
 print(f"    saturated case: {c2.peak_guard.explain()}")
 check("a load larger than the inverter saturates the guard", c2.peak_guard.saturated)
+# SAFETY-81 review: the alarm must hold ALARM_HOLD_S first. The fixture runs on
+# the wall clock, so the start of the hold is moved back instead of waited out.
+check("...but not on its first cycle: it must hold peakguard.ALARM_HOLD_S "
+      "(SAFETY-81)", hass2.notifications.count("goodwe_peak_saturated") == 0
+      and c2._peak_high_since is not None)
+c2._peak_high_since -= timedelta(seconds=peakguard.ALARM_HOLD_S)
+asyncio.get_event_loop_policy().new_event_loop().run_until_complete(c2.cycle())
 check("...and THAT raises exactly one notification, with its own id - the one "
       "state where the money will be spent and a human is the only remaining "
       "actuator", hass2.notifications.count("goodwe_peak_saturated") == 1)
@@ -1417,7 +1426,8 @@ check("B3: main.py sizes the floor from the MEASURED battery power, not from "
 # `datetime.now()`. Every number below therefore comes from ONE instant, and the
 # tolerances that used to absorb the wall clock are gone.
 _proj3 = _seen["projection"]
-_kw = dict(cap_w=CAP_W, reading=b3.peak.peak(), achievable_w=LIVE_MAX_W,
+_kw = dict(cap_w=CAP_W, margin_w=b3.peak_margin_w, reading=b3.peak.peak(),
+           achievable_w=LIVE_MAX_W,
            max_hold_s=b3.p1.averager.max_hold_s, soc=SOC_OK,
            soc_floor=SOC_FLOOR)
 _intent = _shipped_decide(_proj3, batt_w=STANDING, **_kw)
@@ -1554,7 +1564,8 @@ check("SAFETY-24 adds exactly the two keys it names and no more: §14's kW/W "
       "trap `capacity_peak_limit_kw` stays declined, and no speculative "
       "`peak_guard`/`peak_shave` block appeared beside it",
       _peak_keys == []
-      and sorted(PEAK_OPTION_DEFAULTS) == ["bms_soc_floor", "peak_soc_floor"])
+      and sorted(PEAK_OPTION_DEFAULTS) == ["bms_soc_floor", "peak_margin_w",
+                                           "peak_soc_floor"])   # + SAFETY-79
 # Graded on the parsed call syntax, not on the text: the module docstring names
 # `peak_cap_w` while arguing that it does not read it, so a grep would be
 # satisfied by deleting the explanation and would fail on writing one.
@@ -1634,13 +1645,13 @@ check("...and the defaulting form that was ACTUALLY shipped once in this "
       discharge_permitted(float(None or 100), SOC_FLOOR) is None)
 
 # --- the decision -----------------------------------------------------------
-d_ok = decide(p_hungry, batt_w=BATT_NOW, cap_w=CAP_W, reading=None,
+d_ok = decide(p_hungry, batt_w=BATT_NOW, cap_w=CAP_W, margin_w=0.0, reading=None,
               achievable_w=LIVE_MAX_W, max_hold_s=MAX_HOLD_S, soc=SOC_OK,
               soc_floor=SOC_FLOOR)
-d_lim = decide(p_hungry, batt_w=BATT_NOW, cap_w=CAP_W, reading=None,
+d_lim = decide(p_hungry, batt_w=BATT_NOW, cap_w=CAP_W, margin_w=0.0, reading=None,
                achievable_w=LIVE_MAX_W, max_hold_s=MAX_HOLD_S,
                soc=SOC_FLOOR, soc_floor=SOC_FLOOR)
-d_unread = decide(p_hungry, batt_w=BATT_NOW, cap_w=CAP_W, reading=None,
+d_unread = decide(p_hungry, batt_w=BATT_NOW, cap_w=CAP_W, margin_w=0.0, reading=None,
                   achievable_w=LIVE_MAX_W, max_hold_s=MAX_HOLD_S, soc=None,
                   soc_floor=SOC_FLOOR)
 print(f"    with battery:  {d_ok.explain()}")
@@ -1682,7 +1693,7 @@ check("floor-limited and saturated are MUTUALLY EXCLUSIVE, by construction: the
 # notification that matters.
 d_quiet = decide(PeakTracker.project(averager_at(500.0, 450.0),
                                      B + timedelta(seconds=450)),
-                 batt_w=BATT_NOW, cap_w=CAP_W, reading=None,
+                 batt_w=BATT_NOW, cap_w=CAP_W, margin_w=0.0, reading=None,
                  achievable_w=LIVE_MAX_W, max_hold_s=MAX_HOLD_S,
                  soc=SOC_FLOOR - 5.0, soc_floor=SOC_FLOOR)
 print(f"    an EMPTY pack on a quiet quarter: {d_quiet.explain()}")
@@ -1694,7 +1705,7 @@ check("an empty pack on a quarter that does not need shaving is IDLE, not "
       and d_quiet.floor_w is None)
 # And the BLIND branch is untouched: it never forces a discharge, so there is
 # nothing for an energy floor to bound there.
-d_blind_low = decide(p_frozen, batt_w=-RAILED, cap_w=CAP_W, reading=None,
+d_blind_low = decide(p_frozen, batt_w=-RAILED, cap_w=CAP_W, margin_w=0.0, reading=None,
                      achievable_w=LIVE_MAX_W, max_hold_s=MAX_HOLD_S,
                      soc=SOC_FLOOR - 5.0, soc_floor=SOC_FLOOR, frozen=True)
 check("...and an empty pack does not disturb the BLIND branch either: SAFETY-"
@@ -1751,7 +1762,7 @@ for load in (0.0, CEIL - 500.0, CEIL, CEIL + 300.0, CEIL + 3000.0,
         for bw in (-2000.0, 0.0, 400.0, 4000.0):
             for sc in (None, 0.0, BMS_FLOOR, SOC_FLOOR, SOC_FLOOR + 0.5, 100.0):
                 for fl in (SOC_FLOOR, BMS_FLOOR + 1.0, 55.0):
-                    _d = decide(_pr, batt_w=bw, cap_w=CAP_W, reading=None,
+                    _d = decide(_pr, batt_w=bw, cap_w=CAP_W, margin_w=0.0, reading=None,
                                 achievable_w=LIVE_MAX_W,
                                 max_hold_s=MAX_HOLD_S, soc=sc, soc_floor=fl)
                     SWEEP_N += 1
@@ -1798,8 +1809,8 @@ check("`soc` and `soc_floor` are REQUIRED keyword-only arguments of decide() "
       "with no default. A default on either is TEST-14's exact shape and would "
       "be the quiet fallback this card exists to remove - and a default on "
       "`soc_floor` would additionally be CFG-03's fourth defaults site",
-      _required_kw == {"batt_w", "cap_w", "reading", "achievable_w", "soc",
-                       "soc_floor"})
+      _required_kw == {"batt_w", "cap_w", "margin_w", "reading",
+                       "achievable_w", "soc", "soc_floor"})
 _req_fields = tuple(f.name for f in dataclasses.fields(PeakDecision)
                     if f.default is dataclasses.MISSING
                     and f.default_factory is dataclasses.MISSING)
@@ -1948,7 +1959,7 @@ check("...and it reaches the action log too", any("FLOOR_LIMITED" in e
                                                   for e in c24.events))
 # A missing SoC sensor, through the same real cycle. `inputs_ok` stops the loop
 # at 0 W in that state, so the guard's own answer is what is graded here.
-d_nosoc = decide(p_hungry, batt_w=0.0, cap_w=CAP_W, reading=None,
+d_nosoc = decide(p_hungry, batt_w=0.0, cap_w=CAP_W, margin_w=0.0, reading=None,
                  achievable_w=LIVE_MAX_W, max_hold_s=MAX_HOLD_S,
                  soc=None, soc_floor=SOC_FLOOR)
 check("decide() handed soc=None answers floor-limited rather than a full "
@@ -2226,7 +2237,7 @@ def replay_loop(window, *, start_soc, soc_floor, usable_wh=REF_PACK_WH):
         next_cycle = t + timedelta(seconds=CYCLE_S)
         cycles += 1
         d = decide(PeakTracker.project(ing.averager, t), batt_w=batt,
-                   cap_w=CAP_W, reading=tracker.peak(t),
+                   cap_w=CAP_W, margin_w=0.0, reading=tracker.peak(t),
                    achievable_w=LOOP_MAX_W, max_hold_s=MAX_HOLD_S, soc=soc,
                    soc_floor=soc_floor, frozen=False)
         dec = compute(prev_w, w - batt, batt, LOOP_TUNING, sat_count=sat,
@@ -2670,9 +2681,15 @@ check("...and so does the persistent notification, which outlives the page and "
 # cycles with the floor, and part 10 at N=1. The sweeps below never reach it:
 # their fixtures leave battery modes off, so they still see {device,
 # supervised, loop}. DECISIONS/OPT-11-battery-modes.md.
+# ⚠️ SAFETY-78 ADDED `drain`, AND IT IS NOT THE DEFERRED RESERVE. It is a
+# site `lo` at P_MAINTENANCE, filed only at N>=2 while a pack's maintenance
+# drain is pinned, equal to what that pin places. It is not conditioned on a
+# state of charge, it never closes discharge (a `lo`, not a `hi`), and it is
+# never filed at N=1, so the sweeps below still see {device, supervised,
+# loop}. DECISIONS/SAFETY-78-drain-at-two.md.
 CLAIM_SOURCES = {"device", "supervised", "failsafe", "safety", "peak",
                  "arbitrage", "maintenance", "loop", "circulation",
-                 "sign_site", "pack", "refused", "mode"}
+                 "sign_site", "pack", "refused", "mode", "drain"}
 # The two appends that file a claim BUILT ELSEWHERE in the method. Named here so
 # that a THIRD such indirection reads as an unrecognised append rather than as a
 # silent gap in the scan.
@@ -2714,7 +2731,7 @@ check("every `claims.append(...)` in main.py's cycle is one this scan can READ "
       "- a claim filed through a shape it cannot parse has to fail here rather "
       "than be counted as nothing, which is how a scan like this goes quietly "
       "vacuous", len(_appends) >= 10 and None not in _filed)
-check("...and the sources that cycle can file are EXACTLY these THIRTEEN. THIS "
+check("...and the sources that cycle can file are EXACTLY these FOURTEEN. THIS "
       "is what makes part 10 a tripwire: replay_loop() hand-builds the claim "
       "list, so it cannot see a claim main.py adds - and a loop-side SoC "
       "reserve is a new source. Filing one takes this line red on the line it "
@@ -2854,7 +2871,7 @@ print("    site: " + ", ".join(sorted(s for s, v in CLAIM_SCOPE.items()
       + "  |  per-inverter: "
       + ", ".join(sorted(s for s, v in CLAIM_SCOPE.items() if v == SCOPE_UNIT)))
 check("...and the split is the one ARB-03 argued, with SAFETY-31's and "
-      "SAFETY-30's and OPT-09's additions: the six about the GRID CONNECTION "
+      "SAFETY-30's, OPT-09's and SAFETY-78's additions: the seven about the GRID CONNECTION "
       "are site claims and the five about a pack, a device or one write are "
       "per-inverter. `circulation` is a site claim because its quantity is "
       "defined over the roster and is identically zero for any one unit; "
@@ -2863,7 +2880,8 @@ check("...and the split is the one ARB-03 argued, with SAFETY-31's and "
       "per-inverter because since SAFETY-30 it grades one unit's command "
       "against that unit's OWN measured power",
       {s for s, v in CLAIM_SCOPE.items() if v == SCOPE_SITE}
-      == {"loop", "peak", "arbitrage", "safety", "circulation", "sign_site"}
+      == {"loop", "peak", "arbitrage", "safety", "circulation", "sign_site",
+          "drain"}
       and {s for s, v in CLAIM_SCOPE.items() if v == SCOPE_UNIT}
       == {"device", "supervised", "failsafe", "maintenance", "pack",
           "refused", "mode"})
@@ -2967,7 +2985,8 @@ check("⚠️ AND THIS IS THE BREAKING HALF. Give the same Controller a second "
                   "mode": "inverter-a",
                   "loop": ACTUATOR_SITE, "peak": ACTUATOR_SITE,
                   "arbitrage": ACTUATOR_SITE, "safety": ACTUATOR_SITE,
-                  "circulation": ACTUATOR_SITE, "sign_site": ACTUATOR_SITE})
+                  "circulation": ACTUATOR_SITE, "sign_site": ACTUATOR_SITE,
+                  "drain": ACTUATOR_SITE})
 check("...and the roster it was restored to is the shipped one, so nothing "
       "below inherits a two-inverter Controller",
       c_src.units == (app_main.UNIT_A,) and len(c_src.inverters) == 1)
@@ -3046,13 +3065,13 @@ _unit_sources_unrouted = [
     if CLAIM_SCOPE.get(r[0]) == SCOPE_UNIT and "," not in r[1]]
 print(f"    {len(_direct)} direct appends, each read at its own line: "
       + ", ".join(f"main.py:{ln} {s} -> {a}" for s, a, ln in _routing))
-check("all FOURTEEN of `Controller.cycle()`'s DIRECT appends route through "
+check("all FIFTEEN of `Controller.cycle()`'s DIRECT appends route through "
       "`self.actuator_of(<string literal>)`, so this scan can read the routing "
       "of EVERY one of them. An append that computed its actuator, or omitted "
       "the argument, or hand-wrote a string, fails HERE rather than being "
       "silently skipped - which is how a scan like this goes quietly vacuous, "
       "and 10f is in this file because that already happened once",
-      len(_direct) == 14
+      len(_direct) == 15
       and all(a is not None and a.startswith("self.actuator_of('")
               for _s, a, _ln in _routing))
 check("⚠️ AND AT EVERY ONE OF THE ELEVEN THE LITERAL IT ROUTES THROUGH IS THE "
@@ -3069,7 +3088,7 @@ check("⚠️ AND EVERY PER-INVERTER APPEND NAMES THE INVERTER IT IS ABOUT. "
       "site-scoped sources and is the whole defect for a per-inverter one: a "
       "`device` limit built inside the roster loop and routed without `inv` "
       "files inverter B's rating on inverter A, where it binds the wrong "
-      "share. Nine of the fourteen appends are SCOPE_UNIT - `device`, "
+      "share. Nine of the fifteen appends are SCOPE_UNIT - `device`, "
       "`supervised`, `failsafe`, maintenance's two, OPT-09's `pack`, "
       "SAFETY-73's two `refused` and OPT-11's `mode` - and all nine pass one. "
       "SAFETY-30's `sign_site` is deliberately NOT one of them: it is filed on "
@@ -3086,8 +3105,8 @@ check("...and the only appends this pin does NOT reach are the two that file a "
       "arbitrage.claim() by test_arbitrage.py",
       sorted(_indirect) == sorted(CLAIM_BUILDERS)
       and len(_direct) + len(_indirect) == len(_appends))
-check("...and between them the sixteen appends account for exactly the "
-      "thirteen "
+check("...and between them the seventeen appends account for exactly the "
+      "fourteen "
       "sources 10f pins, so the routing pin and the source set are one scan "
       "and neither can drift from the other",
       {s for s, _a, _ln in _routing} | set(CLAIM_BUILDERS.values())
@@ -3148,7 +3167,7 @@ check("...and naming those three is not an accident of this fixture but the "
       {c.source for c in _cl2}
       == CLAIM_SOURCES - {"failsafe", "safety", "maintenance", "peak",
                           "arbitrage", "circulation", "sign_site",
-                          "refused", "mode"})
+                          "refused", "mode", "drain"})
 # ⚠️ AND NOW THE HALF THAT WAS EVIDENCE-SHAPED AND OBSERVED NOTHING. The three
 # checks above grade WHICH ACTUATOR each claim lands on. They say nothing about
 # WHOSE NUMBERS the bound is built from - and those are two different defects
@@ -5462,7 +5481,7 @@ MUT.append(("blindness() returns None - the degenerate 0 W projection is graded"
 
 # 2. the frozen term dropped from the guard's inputs.
 MUT.append(("frozen=False - SAFETY-18's term dropped",
-            not decide(p_frozen, batt_w=-RAILED, cap_w=CAP_W, reading=None,
+            not decide(p_frozen, batt_w=-RAILED, cap_w=CAP_W, margin_w=0.0, reading=None,
                        achievable_w=LIVE_MAX_W, max_hold_s=MAX_HOLD_S, soc=SOC_OK, soc_floor=SOC_FLOOR,
                        frozen=False).engaged and d_frozen.engaged,
             "part 4: 'THE BACKSTOP: SAFETY-18's runaway ... cut to 0 W'"))
@@ -5533,7 +5552,7 @@ _early = sum(1 for _t in (500.0, 1000.0, 2000.0)
              if discharge_permitted(SOC_FLOOR - 1.0, SOC_FLOOR) is not None
              and not decide(PeakTracker.project(
                  averager_at(_t, 450.0), B + timedelta(seconds=450)),
-                 batt_w=BATT_NOW, cap_w=CAP_W, reading=None,
+                 batt_w=BATT_NOW, cap_w=CAP_W, margin_w=0.0, reading=None,
                  achievable_w=LIVE_MAX_W, max_hold_s=MAX_HOLD_S,
                  soc=SOC_FLOOR - 1.0, soc_floor=SOC_FLOOR).engaged)
 MUT.append((f"the SoC gate moved above the `wanted > 0` test ({_early} quiet "
@@ -5963,7 +5982,7 @@ print("13. SAFETY-38 round 4: the ORDERED PAIR inside PeakDecision.explain()")
 _S38_PROJ = PeakTracker.project(averager_at(CAP_W - 1200.0, 450.0),
                                 B + timedelta(seconds=450))
 _S38_CEIL_W, _S38_CEIL_FROM = quarter_ceiling_w(CAP_W, obs_hi)
-_S38_IDLE = decide(_S38_PROJ, batt_w=0.0, cap_w=CAP_W, reading=obs_hi,
+_S38_IDLE = decide(_S38_PROJ, batt_w=0.0, cap_w=CAP_W, margin_w=0.0, reading=obs_hi,
                    achievable_w=LIVE_MAX_W, max_hold_s=MAX_HOLD_S,
                    soc=SOC_OK, soc_floor=SOC_FLOOR)
 # UX-08 2d: the row is in plain words now, and the pair is still ordered.
@@ -6042,7 +6061,7 @@ def _proj_at(net_w, elapsed):
 
 def _decide_on(projection, *, batt_w, soc=SOC_OK, cap_w=CAP_W,
                achievable_w=LIVE_MAX_W, reading=None, frozen=False):
-    return decide(projection, batt_w=batt_w, cap_w=cap_w, reading=reading,
+    return decide(projection, batt_w=batt_w, cap_w=cap_w, margin_w=0.0, reading=reading,
                   achievable_w=achievable_w, soc=soc, soc_floor=SOC_FLOOR,
                   max_hold_s=MAX_HOLD_S, frozen=frozen)
 

goodwe_controller/test_safety78.py

@@ -0,0 +1,424 @@
+"""Runnable check for SAFETY-78: a maintenance drain at N=2 no longer stalls.
+`python3 test_safety78.py`
+
+At two inverters the drain pins its battery at the drain rate and the site
+target is split around the pin. Below the pin the other battery had to charge,
+the allocator refused the opposite directions, the site sat at 0 W and the
+drain never moved (OPT-11 P1 F1, UX-13 P3 check 5, OPT-11 P3 F4). Now a site
+`lo` (`drain`, P_MAINTENANCE) keeps the site target at or above what the pin
+places. Drives the REAL Controller (tools/opt11_identity.py's harness).
+DECISIONS/SAFETY-78-drain-at-two.md has the record.
+
+1. N=2, house below, at and above the drain rate, a solar surplus: the drain
+   runs at its rate, no opposite split, no refusal, no log spam, and it ends.
+2. A drain that cannot give power waits with ONE log line.
+3. Battery modes on, a Cheap hours battery in a cheap run during the drain:
+   no grid charge, and its card says why.
+4. The peak guard binds during a drain, and the arbiter's order holds.
+5. N=1 is byte-identical to release/1.0 5a4cdc2, and the harness bites.
+6. A seeded sweep of the floor against the loop, trades, the peak floor, a
+   safety stop, refusals and an Off battery.
+
+Mutations (MUTATION.md, purged copies, graded over this file and the named
+tests) are listed in the pull request.
+"""
+
+import functools
+import logging
+import os
+import random
+import sys
+import tempfile
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, HERE)
+sys.path.insert(0, os.path.join(HERE, "tools"))
+logging.disable(logging.WARNING)
+
+import opt11_identity as rig                                   # noqa: E402
+import opt11p3_identity as p3                                  # noqa: E402
+import safety78_identity as s78                                # noqa: E402
+import safety79_identity as s79                                # noqa: E402
+from app import allocator, arbitrage, homeview, packmode       # noqa: E402
+from app.arbiter import (Claim, P_ARBITRAGE, P_LOOP, P_MAINTENANCE,  # noqa
+                         P_MODE, P_PEAK, P_SAFETY, pre_resolve, resolve)
+from app.main import Controller                                # noqa: E402
+from app.maintenance import CHARGE, DRAIN                      # noqa: E402
+from app.store import unit_key                                 # noqa: E402
+
+fails = []
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+M = {"maintenance_enabled": True, "maintenance_start_hour": 11}
+A, B = "inverter-a", "inverter-b"
+
+
+def cmd(r):
+    return dict(r[2])
+
+
+def refused(rows):
+    return sum(1 for r in rows if r[7] and "REFUSED" in r[7])
+
+
+def opposite(rows):
+    return sum(1 for r in rows if cmd(r)["a"] * cmd(r)["b"] < 0)
+
+
+def drain_run(house, dur=600.0, soc=lambda u, t: 50.0, cut=None, **kw):
+    return rig.run(2, extra=dict(M, **kw.pop("extra", {})), dur=dur,
+                   load=lambda t: house(t) if callable(house) else house,
+                   soc=soc, cut=cut or (lambda u, t: False), **kw)
+
+
+def with_peak_db(fn):
+    """Run `fn()` with the Controller's peak store in a temporary file."""
+    db = os.path.join(tempfile.mkdtemp(prefix="s78t-"), "tariff.db")
+    real = rig.Controller
+    rig.Controller = functools.partial(real, peak_db_path=db)
+    try:
+        return fn()
+    finally:
+        rig.Controller = real
+
+
+# ============================================================================ #
+print("1. N=2: the drain runs whatever the house uses")
+RUNS = {h: drain_run(h) for h in (1200.0, 2000.0, 3000.0, -1500.0)}
+for h, (rows, c) in RUNS.items():
+    print(f"    house {h:+.0f} W: last A {cmd(rows[-1])['a']:+.0f} W, B "
+          f"{cmd(rows[-1])['b']:+.0f} W, grid {h - sum(cmd(rows[-1]).values()):+.0f}"
+          f" W; {rows[-1][6]}; refusals {refused(rows)}")
+check("⭐ below, at and above the drain rate and under a solar surplus, "
+      "battery A is commanded its 2000 W drain on EVERY cycle, so the drain "
+      "moves (it used to sit at 0 W from the first cycle)",
+      all(cmd(r)["a"] == 2000.0 for rows, _c in RUNS.values() for r in rows)
+      and all(c.maints[0].phase == DRAIN for _r, c in RUNS.values()))
+check("⭐ no cycle splits the site both ways and the allocator refuses "
+      "nothing: battery B never charges while A drains",
+      all(opposite(rows) == 0 and refused(rows) == 0
+          and all(cmd(r)["b"] >= 0.0 for r in rows)
+          for rows, _c in RUNS.values()))
+check("...and nothing is logged per cycle: no ARBITER line in the action log",
+      not any("ARBITER" in e for _r, c in RUNS.values() for e in c.events))
+_r3 = RUNS[3000.0][0]
+check("above the drain rate, B covers the rest of the house in the SAME "
+      "direction and the grid settles at the loop's aim",
+      990.0 <= cmd(_r3[-1])["b"] <= 1030.0
+      and abs(3000.0 - sum(cmd(_r3[-1]).values()) + 10.0) <= 30.0)
+check("at or below the drain rate, B is held at 0 W and A exports the rest, "
+      "as the drain does at one inverter ('exports the surplus')",
+      all(cmd(RUNS[h][0][-1])["b"] == 0.0 for h in (1200.0, 2000.0, -1500.0))
+      and all(RUNS[h][0][-1][6].startswith("loop -> 2000 W")
+              for h in (1200.0, 2000.0, -1500.0)))
+check("...and where the loop alone would ask less, the Why names the drain",
+      "limited by drain" in RUNS[1200.0][0][-1][6])
+
+# The drain ends: A's level falls to the floor, and the cycle moves on.
+_end_rows, _end = drain_run(1200.0, dur=500.0,
+                            soc=lambda u, t: max(5.0, 50.0 - t / 10.0)
+                            if u == "a" else 50.0)
+check("⭐ and the drain ENDS: A reaches the 11 % floor and the cycle moves "
+      "to its charge phase, with no refusal on the way",
+      _end.maints[0].phase == CHARGE and refused(_end_rows) == 0)
+
+# The check bites: without the floor, the same site stalls as it did.
+_real = Controller._drain_floor
+Controller._drain_floor = lambda self, claims, results: None
+try:
+    _bite, _bc = drain_run(1200.0, dur=120.0)
+finally:
+    Controller._drain_floor = _real
+print(f"    without the drain floor: refusals {refused(_bite)}/{len(_bite)}, "
+      f"last A {cmd(_bite[-1])['a']:+.0f} W")
+check("non-vacuous: with the floor taken out, the same fixture refuses every "
+      "cycle and parks A at 0 W (the reported defect)",
+      refused(_bite) == len(_bite) and cmd(_bite[-1])["a"] == 0.0
+      and any("ARBITER" in e for e in _bc.events))
+
+# ============================================================================ #
+print("\n2. a drain that cannot give power waits, with one log line")
+_w_rows, _w = drain_run(1500.0, cut=lambda u, t: u == "a")
+_waits = [e for e in _w.events if "cannot give power now" in e]
+print(f"    A refuses to give: {_waits}; last {_w_rows[-1][2]}")
+check("⭐ A refuses to give power (SAFETY-73): the cycle waits, the line is "
+      "logged ONCE over 120 cycles, and nothing is refused",
+      len(_waits) == 1 and _w.inverters[0].refused == 1
+      and refused(_w_rows) == 0 and _w.maints[0].phase == DRAIN)
+check("...and B covers the house on its own meanwhile",
+      1400.0 <= cmd(_w_rows[-1])["b"] <= 1600.0)
+
+# PR #154 review: one line per episode, across a probe and a second episode.
+_pr_rows, _pr = drain_run(1500.0, dur=1300.0, cut=lambda u, t: u == "a")
+check("the SAFETY-73 probe (A pinned at 200 W, not by maintenance) does not "
+      "end the wait: still ONE line over 1300 s with a probe in it",
+      any(cmd(r)["a"] == 200.0 for r in _pr_rows)
+      and sum("cannot give power now" in e for e in _pr.events) == 1)
+_e2_rows, _e2 = drain_run(1500.0, dur=2600.0, cut=lambda u, t: u == "a" and (
+    t < 600.0 or t >= 1400.0))
+check("...and a second episode, after the probe ends the first, logs again",
+      sum("cannot give power now" in e for e in _e2.events) == 2)
+_cw_rows, _cw = drain_run(-1500.0, dur=300.0, cut=lambda u, t: u == "a")
+_cw_cards = homeview.battery_rows(_cw, False, True)
+check("while A waits, B may take the solar surplus, so its card does not "
+      "say 'This one does not charge'",
+      cmd(_cw_rows[-1])["b"] < 0.0 and _cw_cards[1]["why_key"] != "other_cycle")
+
+
+def reject_a(c, t):
+    """Every write to A is rejected, so A's link goes stale (not live)."""
+    if not getattr(c.hass, "_rej", False):
+        real = c.hass.set_number
+
+        async def set_number(e, v):
+            return False if e == "number.sp_a" else await real(e, v)
+        c.hass.set_number, c.hass._rej = set_number, True
+
+
+_l_rows, _l = drain_run(1500.0, dur=400.0, before=reject_a)
+print(f"    A's writes rejected: {_l_rows[-1][2]}, {_l_rows[-1][7][-40:]}")
+check("⭐ a draining battery that is dropped (stale link) adds no floor: B "
+      "covers the 1500 W house, not the 2000 W drain rate, and the wait is "
+      "logged once",
+      "dropped inverter-a" in _l_rows[-1][7]
+      and cmd(_l_rows[-1])["b"] == 1500.0
+      and sum("cannot give power now" in e for e in _l.events) == 1)
+
+# ============================================================================ #
+print("\n3. battery modes on: no grid charge during the drain")
+
+
+def cheap_b():
+    s = rig._Store()
+    s.data[unit_key(A, packmode.MODE_KEY)] = packmode.SOLAR_FIRST
+    s.data[unit_key(B, packmode.MODE_KEY)] = packmode.CHEAP_HOURS
+    return s
+
+
+def modes_run(maint):
+    extra = dict(s79.P1, **p3.ARB, battery_modes_enabled=True,
+                 **(M if maint else {}))
+    ticks = []
+
+    def on_cycle(c, t):
+        ticks.append(c.mode_tick)
+    rows, c = with_peak_db(lambda: rig.run(
+        2, extra=extra, dur=1800.0, load=lambda t: 800.0,
+        soc=lambda u, t: 50.0, cut=lambda u, t: False, before=p3._feed,
+        on_cycle=on_cycle, store=cheap_b()))
+    cheap = [(r, k) for r, k in zip(rows, ticks) if 900.0 <= r[0] < 1800.0]
+    return rows, c, cheap
+
+
+_base_rows, _base_c, _base_cheap = modes_run(False)
+_m_rows, _m_c, _m_cheap = modes_run(True)
+check("baseline: with no drain, B (Cheap hours only) charges from the grid "
+      "in the cheap run, so the fixture reaches the charge",
+      any(cmd(r)["b"] < 0.0 for r, _k in _base_cheap)
+      and all(k.roles[B] == "charge" for _r, k in _base_cheap))
+check("⭐ with A draining, B never charges in that run: its role is not "
+      "'charge', no trade is filed, and the modes say why ('cycle')",
+      all(cmd(r)["b"] >= 0.0 and k.roles[B] != "charge" and k.action is None
+          and k.why == "cycle" for r, k in _m_cheap)
+      and _m_c.maints[0].phase == DRAIN)
+check("...and the drain runs through the run: A at 2000 W, nothing refused",
+      all(cmd(r)["a"] == 2000.0 for r in _m_rows) and refused(_m_rows) == 0)
+
+# Battery modes off: the site trade (`arbitrage.decide()`) buys in the cheap
+# period. It is a site SET at P_ARBITRAGE, below the drain floor.
+_t_trades = []
+_t_rows, _t_c = with_peak_db(lambda: rig.run(
+    2, extra=dict(s79.P1, **p3.ARB, **M), dur=1800.0, load=lambda t: 800.0,
+    soc=lambda u, t: 50.0, cut=lambda u, t: False, before=p3._feed,
+    on_cycle=lambda c, t: _t_trades.append(c.arb and c.arb.action)))
+print(f"    modes off, trades seen: {sorted({str(a) for a in _t_trades})}")
+check("⭐ battery modes off: the site trade still asks to buy in the cheap "
+      "period, and the drain floor keeps it from charging B against the drain: "
+      "A drains at 2000 W, B never charges, nothing is refused",
+      arbitrage.CHARGE in _t_trades
+      and all(cmd(r)["a"] == 2000.0 and cmd(r)["b"] >= 0.0 for r in _t_rows)
+      and refused(_t_rows) == 0)
+_cards = homeview.battery_rows(_m_c, False, True)
+print(f"    cards: {[(b['name'], b['now'], b['why']) for b in _cards]}")
+check("⭐ B's card tells the truth: it names the draining battery and says "
+      "it does not charge (it said 'charges from the grid' while resting)",
+      _cards[1]["why_key"] == "other_cycle" and A in _cards[1]["why"]
+      and _cards[0]["why_key"] == "cycle_mode")
+
+# ============================================================================ #
+print("\n4. the peak guard during a drain, and the order of the claims")
+
+
+def off_b():
+    s = rig._Store()
+    s.data[unit_key(B, packmode.USE_KEY)] = False
+    return s
+
+
+_p_rows, _p = with_peak_db(lambda: rig.run(
+    2, extra=dict(s79.P1, battery_modes_enabled=True, **M), dur=600.0,
+    load=lambda t: 6000.0, soc=lambda u, t: 60.0, cut=lambda u, t: False,
+    before=s79._feed, store=off_b()))
+print(f"    house 6000 W, limit {s79.CAP_W} W, B Off: {_p_rows[-1][2]}, "
+      f"{_p_rows[-1][6]}")
+check("⭐ the peak guard binds during the drain: the site goes above the "
+      "drain to the guard's floor, A keeps draining at 2000 W and B (Off) "
+      "gives only the shortfall, in the same direction",
+      _p.peak_guard.engaged and _p_rows[-1][1] >= _p.peak_guard.floor_w > 2000.0
+      and all(cmd(r)["a"] == 2000.0 and cmd(r)["b"] >= 0.0 for r in _p_rows)
+      and "limited by peak" in _p_rows[-1][6] and refused(_p_rows) == 0)
+
+
+
+def blind_at(t0):
+    """The site meter stops answering at `t0`: a safety SET at P_SAFETY."""
+    def before(c, t):
+        if t >= t0 and not getattr(c.hass, "_blind", False):
+            real = c.hass.number
+
+            async def number(e, invert=False):
+                return None if e == "sensor.grid" else await real(e, invert)
+            c.hass.number, c.hass._blind = number, True
+    return before
+
+
+_s_rows, _s = drain_run(3000.0, dur=300.0, before=blind_at(150.0))
+print(f"    meter lost at 150 s: {_s_rows[-1][2]}, {_s_rows[-1][6]}")
+check("⭐ a safety stop outranks the drain at N=2: with the meter gone the "
+      "safety SET parks both batteries at 0 W, and the drain ran before",
+      cmd(_s_rows[20])["a"] == 2000.0
+      and all(cmd(r) == {"a": 0.0, "b": 0.0} for r in _s_rows if r[0] >= 175.0)
+      and _s_rows[-1][6].startswith("safety -> 0 W"))
+
+UNITS = (A, B)
+_drain = [Claim.set("maintenance", P_MAINTENANCE, 2000.0, "drain", actuator=A),
+          Claim.limit("drain", P_MAINTENANCE, lo=2000.0, reason="drain")]
+_order = {
+    "loop under the drain": ([Claim.set("loop", P_LOOP, 500.0)], 2000.0),
+    "a grid charge (trade)": ([Claim.set("arbitrage", P_ARBITRAGE, -2500.0)],
+                              2000.0),
+    "a sale bigger than the drain": ([Claim.set("arbitrage", P_ARBITRAGE,
+                                                3000.0)], 3000.0),
+    "a peak floor above the drain": ([Claim.set("loop", P_LOOP, 500.0),
+                                      Claim.limit("peak", P_PEAK, lo=3500.0)],
+                                     3500.0),
+    "a safety stop": ([Claim.set("loop", P_LOOP, 500.0),
+                       Claim.set("safety", P_SAFETY, 0.0, "stopped")], 0.0),
+}
+_got = {}
+for k, (extra, want) in _order.items():
+    r = resolve(_drain + extra, units=UNITS)
+    _got[k] = (r.target_w, dict(r.shares), r.allocated)
+    print(f"    {k}: target {r.target_w:+.0f} W, shares {dict(r.shares)}")
+check("⭐ the order holds: a safety stop parks everything; the peak floor "
+      "above the drain wins; a sale above it runs; a grid charge and the "
+      "loop below it are lifted to it; never an opposite split",
+      all(_got[k][0] == want and _got[k][2]
+          and not (min(_got[k][1].values()) < 0 < max(_got[k][1].values()))
+          for k, (_e, want) in _order.items())
+      and _got["a safety stop"][1] == {A: 0, B: 0}
+      and _got["a grid charge (trade)"][1] == {A: 2000, B: 0})
+
+# ============================================================================ #
+print("\n5. N=1: byte-identical to release/1.0 5a4cdc2")
+# Printed by `python3 tools/safety78_identity.py` on release/1.0 5a4cdc2 (the
+# same file copied in, nothing else changed), goodwe-addon-checks:1,
+# 2026-09-29. 480 cycles each, draining throughout, every claim and the
+# newest action-log line hashed.
+AT_5A4CDC2 = {
+    "n1_drain":
+        "55fcfc4a0b9251746f315cfdea607a33640d3a81faf6604c4718a04bbc7dd776",
+    "n1_drain_modes":
+        "93867eb4ee4132b47c030668bd7f07587a353bced2461524e09421125c3c4edf",
+}
+_now = s78.digests()
+for k in AT_5A4CDC2:
+    print(f"    {k} {'same' if _now[k] == AT_5A4CDC2[k] else 'DIFFERS'} "
+          f"{_now[k][:16]}")
+check("⭐ at one inverter a drain under a house below, at and above its "
+      "rate, a surplus and a load over the peak limit, with battery modes "
+      "off and on, is byte-identical to 5a4cdc2: commands, reasons, roles, "
+      "trades and every claim",
+      _now == AT_5A4CDC2)
+Controller._drain_floor = lambda self, claims, results: (
+    2000.0 if any(r.phase == DRAIN for r in results) else None)
+try:
+    _leak = s78.digest(s78.run(**s78.SCENARIOS["n1_drain"], dur=60.0)[0])
+    _same = s78.digest(s78.run(**s78.SCENARIOS["n1_drain"], dur=60.0)[0])
+finally:
+    Controller._drain_floor = _real
+_ref = s78.digest(s78.run(**s78.SCENARIOS["n1_drain"], dur=60.0)[0])
+check("non-vacuous: filing the drain floor at N=1 (which moves no watt "
+      "there) moves the digest, because the harness hashes the claims",
+      _leak != _ref and _leak == _same)
+
+# ============================================================================ #
+print("\n6. the floor against every other claim (PR #154 review, seeded sweep)")
+_rnd = random.Random(78)
+_bad, _peak_above, _off_gave = [], 0, 0
+for _i in range(20000):
+    ma, mb = _rnd.choice((2500., 3000., 5000.)), _rnd.choice((1500., 2500.))
+    ua = [Claim.limit("supervised", P_SAFETY, -ma, ma, actuator=A),
+          Claim.set("maintenance", P_MAINTENANCE,
+                    _rnd.choice((500., 2000., 6000.)), "drain", actuator=A)]
+    if _rnd.random() < .2:
+        ua.append(Claim.limit("pack", P_SAFETY, -ma,
+                              _rnd.choice((0., 800.)), actuator=A))
+    ub = [Claim.limit("supervised", P_SAFETY, -mb, mb, actuator=B)]
+    _offb = _rnd.random() < .4
+    if _offb:
+        ub.append(Claim.limit("mode", P_MODE, 0., 0., "off", actuator=B))
+    if _rnd.random() < .15:
+        ub.append(Claim.limit("refused", P_SAFETY, -mb, 0., actuator=B))
+    pin = allocator.pin_w(pre_resolve(ua))
+    site = [Claim.set("loop", P_LOOP, _rnd.uniform(-6000., 8000.))]
+    if pin is not None and pin > 0.0:
+        site.append(Claim.limit("drain", P_MAINTENANCE, lo=pin))
+    if _rnd.random() < .3:
+        site.append(Claim.set("arbitrage", P_ARBITRAGE,
+                              _rnd.choice((-3000., 1000., 4000.))))
+    pk = _rnd.uniform(0., 8000.) if _rnd.random() < .4 else None
+    if pk is not None:
+        site.append(Claim.limit("peak", P_PEAK, lo=pk))
+    stop = _rnd.random() < .05
+    if stop:
+        site.append(Claim.set("safety", P_SAFETY, 0.0, "stopped"))
+    r = resolve(ua + ub + site, units=UNITS)
+    s = dict(r.shares)
+    why = []
+    if min(s.values()) < 0 < max(s.values()) or r.contradiction:
+        why.append("opposite or contradiction")
+    if stop and (r.target_w != 0.0 or any(s.values())):
+        why.append("stop not parked")
+    if not stop and pin is not None and pin > 0.0:
+        if r.target_w < pin or s[B] < 0:
+            why.append("below the floor, or B charges")
+        if pk is not None and pk > pin:
+            _peak_above += 1
+            if r.allocated and r.target_w < min(pk, pin + mb):
+                why.append("peak floor not honoured")
+        if _offb and s[B] > 0:
+            _off_gave += 1
+            if not (pk is not None and pk > pin):
+                why.append("Off B used for the drain")
+    if why:
+        _bad.append((_i, why, r.target_w, s, pin, pk))
+print(f"    {_bad[:3]}; peak above the drain {_peak_above}, Off B gave for "
+      f"the peak {_off_gave}")
+check("⭐ over 20000 seeded claim lists: never an opposite split or a "
+      "contradiction; a safety stop parks both; the site never goes below "
+      "the pin and B never charges; a peak floor above the drain is met; an "
+      "Off battery gives only for the peak floor, never for the drain",
+      not _bad and _peak_above > 1000 and _off_gave > 100)
+
+print()
+if fails:
+    print(f"{len(fails)} FAILED: {', '.join(fails)}")
+    sys.exit(1)
+print("all checks passed")

goodwe_controller/test_safety81.py

@@ -0,0 +1,171 @@
+"""Runnable check for SAFETY-81, no false "Load too high for battery" alarms.
+`python3 test_safety81.py`
+
+Drives the REAL Controller through tools/safety81_sim.py (a 1 s cycle on a
+plant shaped like the SAFETY-79 rig, one sample in ten late).
+DECISIONS/SAFETY-81-load-too-high.md has the record.
+
+1. Every command is byte-identical to release/1.0 5a4cdc2.
+2. No alarm on the quarter-edge spike, the last seconds, noise (margin 50
+   and 0) or a burst the quarter absorbs.
+3. Real overloads still alarm, ALARM_HOLD_S after 5a4cdc2.
+4. peakguard.load_too_high() on its own.
+5. The hold across a cycle with no battery reading (review).
+
+Mutations (MUTATION.md, purged copies) are listed in the pull request.
+"""
+
+import asyncio
+import os
+import sys
+from datetime import datetime, timedelta, timezone
+from types import SimpleNamespace
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.join(HERE, "tools"))
+
+import safety81_sim as sim                                    # noqa: E402
+from app.main import Controller                               # noqa: E402
+from app.peakguard import load_too_high                       # noqa: E402
+
+fails = []
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+# Printed by `python3 tools/safety81_sim.py` on release/1.0 5a4cdc2 (the tool
+# copied in, nothing else changed), in the CI image: (alarm times, digest).
+BASE = {
+    "const4500": ([2699.0], "6ba6b8634f0df9526adc04f03c82db7d083973268deda0d1f07c5519bc2e5e9d"),
+    "const4500_m0": ([2699.0], "2bede28f3ea6ba9294be134c9b9733e43d22a7c24deac3bf8210bbbbe09b2039"),
+    "sine4500": ([2699.0], "bf70c2c23a0eede40c34478d1354b7daa1858e0a0f920693e2dd15fb5046120f"),
+    "edge4600": ([2.0, 902.0, 1802.0, 2699.0], "3cc0c6fec0c70f138530955babc2b416fe7307373037c1b2e927b6ccdaad3a4d"),
+    "edge4600_m0": ([2.0, 902.0, 1802.0, 2699.0], "ba9ba2c042ee42b043315b996ece38b3478dc9866aaf833256c9c29c02f0fe9f"),
+    "burst_end": ([881.0, 1781.0, 2681.0], "5f70e1eb4244820f1d44b494cb80e51f1a4486dee03357c9a8e8f7d371c5d9af"),
+    "noise5000_m50": ([292.0, 2551.0, 2698.0], "48b446e1a78e6d6032b31cb68a4eadb0f74e3aec4cc1e184162e9c65449bfdc5"),
+    "noise5000_m0": ([292.0, 2552.0, 2698.0], "1a0527dee6c2b03dc95a90b4682858c7bf5edf7205c2aced249112f04328c960"),
+    "step6500": ([1201.0, 1801.0], "95e5c90e4a6814526cb4f3bea76286063b449d86a420f888c014531fb6e913a3"),
+    "miss5560": ([1201.0, 1801.0], "cd991cfe1685750598236701a5a2f2f0342d66645609c536d42ab7ba07216e6c"),
+    "ramp6500": ([1296.0, 1801.0], "8db7675535f1a01abf38bd6bfb996a6fe57711d3ecca53541bb1c0870748c46b"),
+    "step7500_reserve": ([], "21eb9c07a4582f47f347084d1c75a28a5d767bc068bc3f74f32433d3239e9ccb"),
+    # Added in review, printed the same way.
+    "sine4500_fast": (["112, about one per 30 s"], "710008fd8f2d33a0e2cbb9a626bedafd6d87bc23712bbc5b74a4af9b3ec21897"),
+    "twice7000": ([1001.0, 1502.0, 2699.0], "1cddda8cf35859efb2ad503f1683f744cb812a6325a390c4fa3df19d717af043"),
+    "step6500_gap": ([1201.0, 1801.0], "95e5c90e4a6814526cb4f3bea76286063b449d86a420f888c014531fb6e913a3"),
+}
+OUT = {k: sim.run(**v) for k, v in sim.SCENARIOS.items()}
+RUN = {k: v[:2] for k, v in OUT.items()}
+ERR = {k: v[4] for k, v in OUT.items()}
+
+# ============================================================================ #
+print("1. every command byte-identical to release/1.0 5a4cdc2")
+check("the same scenarios as 5a4cdc2", set(RUN) == set(BASE))
+for k, (alarms, digest) in RUN.items():
+    check(f"{k}: digest {digest[:12]}", digest == BASE[k][1])
+
+# ============================================================================ #
+print("2. no false alarm (5a4cdc2's are listed)")
+for k in ("edge4600", "edge4600_m0", "const4500", "const4500_m0", "sine4500",
+          "noise5000_m50", "noise5000_m0", "burst_end", "sine4500_fast"):
+    check(f"{k}: none (5a4cdc2: {BASE[k][0]})", RUN[k][0] == [])
+
+# ============================================================================ #
+print("3. real overloads still alarm, ALARM_HOLD_S after 5a4cdc2")
+# ALARM_HOLD_S (10 s) plus up to 2 s of late meter samples; at 1800 s the
+# quarter-edge tick restarts the hold.
+for k, want in (("step6500", [1211.0, 1813.0]),
+                ("miss5560", [1213.0, 1813.0])):
+    print(f"    {k}: load steps up at 1200 s; alarms at {RUN[k][0]}, "
+          f"5a4cdc2 {BASE[k][0]}")
+    check(f"{k}: after the hold, and again only at the next quarter",
+          RUN[k][0] == want)
+check("step6500_gap: cycles stopped by a lost battery reading do not "
+      "restart the hold",
+      RUN["step6500_gap"][0] == [1215.0, 1813.0])
+check("twice7000: notified once in the quarter (5a4cdc2: "
+      f"{BASE['twice7000'][0]})", RUN["twice7000"][0] == [1011.0])
+check("twice7000: the ERROR line for both overloads",
+      ERR["twice7000"] == [1011.0, 1512.0])
+# By design: until 1306 s (then the hold) this quarter would end at most
+# ALARM_MISS_W over the real 3500 W cap; 5a4cdc2 alarmed at the aim (cap - 50).
+print(f"    ramp6500: alarms at {RUN['ramp6500'][0]}, "
+      f"5a4cdc2 {BASE['ramp6500'][0]}")
+check("ramp6500: alarms once the quarter will end over the real cap by "
+      "more than ALARM_MISS_W",
+      RUN["ramp6500"][0] == [1316.0, 1813.0])
+check("step7500 under the peak reserve: not this alarm (the guard is not "
+      "allowed to discharge)", RUN["step7500_reserve"][0] == [])
+
+# ============================================================================ #
+print("4. load_too_high()")
+
+
+def proj(elapsed, done_avg, held):
+    """A projection `elapsed` s in, averaging `done_avg` so far."""
+    r = 900.0 - elapsed
+    return SimpleNamespace(elapsed_s=elapsed, held_w=held,
+                           projected_w=(done_avg * elapsed + max(held, 0) * r)
+                           / 900.0)
+
+
+def ltl(p, batt, cap=3500.0, rail=2000.0):
+    return load_too_high(p, batt_w=batt, ceiling_w=cap, achievable_w=rail)
+
+
+check("load 6000 W vs 3500 + 2000: yes", ltl(proj(300, 3450, 4000), 2000))
+check("already over, the battery can carry the load but not catch up: yes",
+      ltl(proj(450, 7200, 7200), 0, rail=5000))
+check("the last second, a 7 W miss (under ALARM_MISS_W): no",
+      not ltl(proj(899, 3509, 2500), 1000))
+check("a miss of exactly ALARM_MISS_W: no",
+      not ltl(proj(450, 3520, 3500), 2000))
+check("...and 1 W more: yes", ltl(proj(450, 3522, 3500), 2000))
+check("over cap + battery, but the quarter lands under the cap: no",
+      not ltl(proj(880, 3450, 4000), 2000))
+check("...and when it does not: yes", ltl(proj(700, 3450, 4000), 2000))
+check("no battery reading: no", not ltl(proj(300, 3450, 5000), None))
+check("no seconds left: no", not ltl(proj(900, 4000, 5000), 2000))
+check("a quarter already over is not won back by export: yes",
+      ltl(proj(800, 3950, 1000), 0))
+
+# ============================================================================ #
+print("5. the hold across a cycle with no battery reading")
+# A reading the stale detector drops (STALE_READING) reaches the alarm as None
+# while the cycle still runs. Unknown is not "fine": it must not restart the
+# hold. Driven on Controller.check_peak_saturated() itself, with stubs.
+Q0 = datetime(2026, 9, 20, 11, 0, tzinfo=timezone.utc)
+notes = []
+
+
+async def _call(domain, service, data):
+    notes.append(data.get("notification_id"))
+
+
+stub = SimpleNamespace(
+    peak_guard=SimpleNamespace(saturated=True, ceiling_w=3500.0,
+                               reason="PEAK_GUARD: fixture"),
+    site_rating_w=2000.0, shadow=False, events=[],
+    _peak_batt_prev=None, _peak_alarm_block=None, _peak_high_since=None,
+    _peak_saturated=False, hass=SimpleNamespace(call=_call),
+    log_event=lambda msg, hint=None: None)
+first = None
+for sec in range(0, 30):
+    stub.site_batt_w = None if 4 <= sec < 8 else 2000.0
+    p = proj(300 + sec, 3450, 6000)
+    p.block_start = Q0
+    stub._peak_proj = p
+    asyncio.run(Controller.check_peak_saturated(stub))
+    if notes and first is None:
+        first = sec
+check(f"a 4 s gap in the battery reading: alarm at {first} s, not 18 s",
+      first == 10)
+
+print()
+if fails:
+    print(f"FAILED: {len(fails)} check(s)")
+    sys.exit(1)
+print("all checks passed")

goodwe_controller/test_setup.py

@@ -76,8 +76,8 @@ check("the mockup's six steps: meter, inverters, solar, prices, peak limit, "
       and [WS["steps"][str(n)]["name"] for n in range(1, 7)]
       == ["Your meter", "Inverters and batteries", "Solar", "Prices",
           "Peak limit", "Check and start"])
-check("battery modes are not a step yet (OPT-11): step 5 says they come later",
-      "later update" in WS["modes_later"]["description"]
+check("battery modes are not a wizard step (OPT-11): step 5 points to the Batteries screen",
+      "Batteries screen" in WS["modes_later"]["description"]
       and not any("mode" in k for k in BY_STEP[5]))
 SPEC = uipage.setup_spec()
 check("the spec the page reads is the table's",

goodwe_controller/tools/opt11p3_identity.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""OPT-11 P3: with battery modes off, is every command byte-identical to
+release/1.0 7a00f12, on the paths P3 changed?
+
+    python3 tools/opt11p3_identity.py          # prints one digest per scenario
+
+tools/safety79_identity.py's harness (the REAL Controller on a P1 meter, so
+the peak guard runs) plus a day-ahead price series and `arbitrage_enabled`,
+so the site trade P3 now skips with modes on (`arbitrage.decide()`, its
+claim, the sizing to the guard's headroom) runs on every cycle, with a buy
+period, a sell period and periods in between, and a house that goes over the
+limit. Each row hashes safety79's fields plus the trade's action, watts and
+sentence. Uses only the API 7a00f12 has, so the same file runs on both trees;
+test_modes_p3.py part 1 holds this tree to the digests printed on 7a00f12.
+"""
+
+import functools
+import hashlib
+import os
+import sys
+import tempfile
+from datetime import timedelta
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+import opt11_identity as rig                               # noqa: E402
+import safety79_identity as s79                            # noqa: E402
+from app.price import PricePoint, PriceProduct, PriceRead, brussels  # noqa
+from app.static_tariff import TariffPlan                   # noqa: E402
+
+DUR = 5400.0
+
+
+def prices():
+    """15-minute firm prices: the cheapest period 15-30 min into the run,
+    the dearest 75-90 min in, and ones in between."""
+    pts = []
+    for i in range(-8, 40):
+        s = rig.BASE + timedelta(minutes=15 * i)
+        p = 0.08 if i == 1 else 0.52 if i == 5 else 0.20 + 0.003 * (i % 7)
+        pts.append(PricePoint(start=brussels(s), eur_per_kwh=p,
+                              provisional=False))
+    return TariffPlan(PriceRead.series(pts, PriceProduct.DAY_AHEAD,
+                                       "generic_dayahead", rig.BASE), None,
+                      "provider")
+
+
+PLAN = prices()
+
+
+def _feed(c, t):
+    c.tariff_plan, c.tariff_at = PLAN, rig.BASE + timedelta(seconds=t)
+    s79._feed(c, t)
+
+
+def load(t):
+    """Under the limit, over it, a surplus, a big evening load."""
+    k = int(t // 600) % 5
+    return (900.0, 3200.0, -2200.0, 1500.0, 4200.0)[k]
+
+
+def soc(u, t):
+    return 55.0 if u == "a" else 45.0
+
+
+ARB = {"arbitrage_enabled": True, "cycle_cost_threshold_eur": 0.05}
+SCENARIOS = {
+    "n1": dict(n=1),
+    "n2": dict(n=2),
+    # The option present and false: an install that saved it off.
+    "n1_off": dict(n=1, extra={"battery_modes_enabled": False}),
+    "n2_off": dict(n=2, extra={"battery_modes_enabled": False}),
+}
+
+
+def run(n, *, extra=None, dur=DUR):
+    opts = dict(s79.P1, **ARB, **(extra or {}))
+    trade = []
+
+    def on_cycle(c, t):
+        a = c.arb
+        trade.append(None if a is None else (a.action, a.power_w, a.reason))
+    db = os.path.join(tempfile.mkdtemp(prefix="p3id-"), "tariff.db")
+    real = rig.Controller
+    rig.Controller = functools.partial(real, peak_db_path=db)
+    try:
+        rows, c = rig.run(n, extra=opts, dur=dur, load=load, soc=soc,
+                          cut=lambda u, t: False, before=_feed,
+                          on_cycle=on_cycle)
+    finally:
+        rig.Controller = real
+    return [r + (x,) for r, x in zip(rows, trade)], c
+
+
+def digest(rows) -> str:
+    return hashlib.sha256(repr(rows).encode()).hexdigest()
+
+
+def digests() -> dict:
+    return {k: digest(run(**v)[0]) for k, v in SCENARIOS.items()}
+
+
+if __name__ == "__main__":
+    if "--summary" in sys.argv:
+        for k, v in SCENARIOS.items():
+            rows = run(**v)[0]
+            acts = sorted({str(r[-1][0]) if r[-1] else "None" for r in rows})
+            print(f"{k}: {len(rows)} cycles, trade actions {acts}")
+    for k, v in digests().items():
+        print(f"{k} {v}")

goodwe_controller/tools/opt11p3_replay.py

@@ -0,0 +1,394 @@
+#!/usr/bin/env python3
+"""OPT-11 P3: replay days of recorded house load and real prices through the
+REAL Controller (read_inputs + cycle, the arbiter, the allocator, the peak
+guard on a P1 meter), with two modelled batteries, and report energy, cycles
+and money, plus the P3 invariants on every tick.
+
+    python3 tools/opt11p3_replay.py --days 16 --variant p3_ls
+    python3 tools/opt11p3_replay.py --captured          # 2026-09-09/10
+
+The same file runs on release/1.0 7a00f12 (the P2 baseline) and on this
+branch: it uses only the Controller API 7a00f12 has, and sets the batteries'
+choices through the store keys P1 defined (`pack_sell` was reserved there).
+
+REAL: the house (grid + battery power recorded 2026-09-02..17 on the live
+install, scenarios/loop-2026-09-02_2026-09-17: the house's own net demand,
+solar included), the prices (EPEX BE day-ahead, hourly, same weekday one year
+earlier (364 days), or the captured quarter-hourly energy-charts bodies for
+2026-09-09/10), the decision code.
+MODELLED: the batteries (a first-order lag, 3 s, 800 W/s ramp, SoC
+integrated, 95 % each way, a reading that jitters by a few watts, and
+optionally a device limit or a refusal to charge), the all-in price (the EPEX file's own stated
+assumption: (wholesale + 0.02 + 0.10) x 1.06), export paid at the wholesale
+price, tomorrow's prices known from 13:00 local. The absolute money is
+therefore an estimate; the comparison between variants is the point.
+"""
+
+import argparse
+import asyncio
+import gzip
+import json
+import math
+import os
+import sys
+import time
+from datetime import datetime, timedelta, timezone
+
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, HERE)
+
+import app.main as m                                      # noqa: E402
+from app.main import Controller                           # noqa: E402
+from app.p1 import make_sample, split_signed               # noqa: E402
+from app.price import PricePoint, PriceProduct, PriceRead, brussels  # noqa
+from app.static_tariff import TariffPlan                  # noqa: E402
+from app.store import unit_key                            # noqa: E402
+
+LOOP = os.path.join(HERE, "scenarios", "loop-2026-09-02_2026-09-17")
+EPEX = os.path.join(HERE, "scenarios",
+                    "epex-be-dayahead-2025-09-01_2026-09-01.json")
+QH = os.path.join(HERE, "scenarios",
+                  "energy-charts-be-price-2026-09-09_2026-09-10-twoday.json")
+TICK = 5.0
+CAP_KWH = 10.0
+RATING = 2500.0
+PEAK_CAP = 3500
+
+
+def all_in(wholesale_kwh):
+    return round((wholesale_kwh + 0.02 + 0.10) * 1.06, 6)
+
+
+def load_house(days):
+    """[(t_utc_epoch, house_w)] from the recording: grid + battery power."""
+    out = []
+    for d in days:
+        def rd(kind):
+            f = os.path.join(LOOP, f"{d}-{kind}.jsonl.gz")
+            rows = []
+            with gzip.open(f, "rt") as fh:
+                for line in fh:
+                    r = json.loads(line)
+                    try:
+                        v = float(r["v"])
+                    except ValueError:
+                        continue
+                    rows.append((datetime.fromisoformat(r["t"]).timestamp(),
+                                 v))
+            return rows
+        g, b = rd("grid"), rd("batt")
+        j = 0
+        for t, gw in g:
+            while j + 1 < len(b) and b[j + 1][0] <= t:
+                j += 1
+            bw = b[j][1] if b and b[j][0] <= t else 0.0
+            out.append((t, gw + bw))
+    out.sort()
+    return out
+
+
+def epex_points(shift_days=364):
+    d = json.load(open(EPEX))["prices"]
+    pts = []
+    for r in d:
+        s = datetime.fromisoformat(r["start"]) + timedelta(days=shift_days)
+        pts.append((s.astimezone(timezone.utc), 3600,
+                    float(r["eur_per_kwh"])))
+    return pts
+
+
+def qh_points():
+    d = json.load(open(QH))
+    return [(datetime.fromtimestamp(t, timezone.utc), 900, p / 1000.0)
+            for t, p in zip(d["unix_seconds"], d["price"])
+            if p is not None]
+
+
+class Plant:
+    def __init__(self, soc, refuse_charge=False):
+        self.cmd, self.p, self.soc = 0.0, 0.0, float(soc)
+        self.refuse_charge = refuse_charge
+
+    def step(self, dt, floor):
+        c = self.cmd
+        if c > 0 and self.soc <= floor:
+            c = 0.0
+        if c < 0 and (self.soc >= 100.0 or self.refuse_charge):
+            c = 0.0
+        want = self.p + (c - self.p) * (1 - math.exp(-dt / 3.0))
+        dp = max(-800.0 * dt, min(800.0 * dt, want - self.p))
+        self.p += dp
+        e = self.p * dt / 3600.0 / 1000.0            # kWh, + = out
+        eff = 1 / 0.95 if e > 0 else 0.95
+        self.soc -= e * eff / CAP_KWH * 100.0
+        self.soc = max(0.0, min(100.0, self.soc))
+
+
+class Hass:
+    def __init__(self, units, house_at, soc0=None, refuse=(), limits=None):
+        self.units = units
+        self.lim = limits or {}
+        self.plants = {u: Plant((soc0 or {}).get(u, 50.0), u in refuse)
+                       for u in units}
+        self.house_at = house_at
+        self.t = 0.0
+
+    def grid(self):
+        return self.house_at(self.t) - sum(p.p for p in self.plants.values())
+
+    async def limits(self, e):
+        lo, hi = self.lim.get(e[-1], (-5000.0, 5000.0))
+        return (lo, hi, 1.0)
+
+    async def call(self, *a):
+        return True
+
+    async def number(self, e, invert=False):
+        if e == "sensor.grid":
+            return self.grid()
+        u = e[-1]
+        if e.startswith("sensor.soc"):
+            return round(self.plants[u].soc, 1)
+        if e.startswith("sensor.batt"):
+            # A real reading jitters by a few watts; a dead-flat one is a
+            # stale register to the add-on (SAFETY-37), which is not modelled.
+            j = (ord(u) * 31 + int(self.t)) % 7 - 3
+            return float(round(self.plants[u].p) + j)
+        return None
+
+    async def set_number(self, e, v):
+        self.plants[e[-1]].cmd = float(v)
+        return True
+
+
+class _Store:
+    def __init__(self):
+        from app.store import DEFAULTS
+        self.data = dict(DEFAULTS)
+
+    def set(self, k, v):
+        self.data[k] = v
+
+    def get_time(self, k):
+        v = self.data.get(k)
+        return datetime.fromisoformat(v) if v else None
+
+    def set_time(self, k, when):
+        self.data[k] = when.isoformat() if when else None
+
+
+class _Pub:
+    enabled = False
+
+    def publish(self, *a, **k):
+        pass
+
+    def close(self):
+        pass
+
+
+VARIANTS = {
+    # (modes on, arbitrage_enabled, {unit: (use, mode, sell)})
+    "modes_off": (False, False, {}),
+    "arb_only": (False, True, {}),
+    "p2_sf_ls": (True, False, {"a": (True, "solar_first", False),
+                               "b": (True, "leftover_solar", False)}),
+    "p2_arb": (True, True, {"a": (True, "solar_first", False),
+                            "b": (True, "leftover_solar", False)}),
+    "p3_ls": (True, False, {"a": (True, "solar_first", False),
+                            "b": (True, "leftover_solar", False)}),
+    "p3_ch_sell": (True, False, {"a": (True, "solar_first", False),
+                                 "b": (True, "cheap_hours", True)}),
+    "p3_both_ch": (True, False, {"a": (True, "cheap_hours", False),
+                                 "b": (True, "cheap_hours", True)}),
+}
+
+
+def options(modes, arb, n=2):
+    o = {"meter_entity": "sensor.grid", "meter_source": "ha_signed",
+         "p1_net_entity": "sensor.net", "meter_phases": 1,
+         "peak_cap_w": PEAK_CAP, "gain": 0.6, "slew_w": 400,
+         "target_grid_w": -10, "deadband_w": 15, "step_w": 10,
+         "heartbeat_s": 10, "stale_input_s": 15, "auto_start": True,
+         "battery_modes_enabled": modes, "arbitrage_enabled": arb,
+         "cycle_cost_threshold_eur": 0.10,
+         "inverters": [{"name": f"inverter-{u}",
+                        "setpoint_entity": f"number.sp_{u}",
+                        "soc_entity": f"sensor.soc_{u}",
+                        "batt_entity": f"sensor.batt_{u}",
+                        "max_w": int(RATING), "bms_soc_floor": 10,
+                        "capacity_kwh": CAP_KWH} for u in "ab"[:n]]}
+    return o
+
+
+def plan_at(now, pts):
+    """The firm day-ahead points a site holds at `now`: today, and tomorrow
+    once published (13:00 local)."""
+    loc = brussels(now)
+    day0 = loc.replace(hour=0, minute=0, second=0, microsecond=0)
+    end = day0 + timedelta(days=2 if loc.hour >= 13 else 1)
+    sel = [PricePoint(start=brussels(s), eur_per_kwh=all_in(p),
+                      provisional=False)
+           for s, span, p in pts if day0 <= s < end]
+    if len(sel) < 2:
+        return None
+    return TariffPlan(PriceRead.series(sel, PriceProduct.DAY_AHEAD,
+                                       "generic_dayahead", now), None,
+                      "provider")
+
+
+def run(variant, house, pts, start, dur, *, check=None, stride=1, n=2,
+        soc0=None, refuse=(), extra=None, choice=None, patch=None,
+        limits=None):
+    modes, arb, var_choice = VARIANTS[variant]
+    choice = var_choice if choice is None else choice
+    units = tuple("ab"[:n])
+    import bisect
+    ts = [h[0] for h in house]
+
+    def house_at(t):
+        i = bisect.bisect_right(ts, start.timestamp() + t) - 1
+        return house[max(0, i)][1]
+
+    wholesale = {s: (span, p) for s, span, p in pts}
+    starts = sorted(wholesale)
+
+    def price_at(now):
+        i = bisect.bisect_right(starts, now) - 1
+        if i < 0:
+            return None
+        s = starts[i]
+        span, p = wholesale[s]
+        return p if now < s + timedelta(seconds=span) else None
+
+    store = _Store()
+    for u, (use, mode, sell) in choice.items():
+        store.data[unit_key(f"inverter-{u}", "pack_use")] = use
+        store.data[unit_key(f"inverter-{u}", "pack_mode")] = mode
+        store.data[unit_key(f"inverter-{u}", "pack_sell")] = sell
+    stats = dict(imp_kwh=0.0, exp_kwh=0.0, cost=0.0, exp_rev=0.0,
+                 out_kwh={u: 0.0 for u in "ab"[:n]},
+                 in_kwh={u: 0.0 for u in "ab"[:n]},
+                 ticks=0, quarters={}, trade_ticks=0)
+
+    async def go():
+        hass = Hass(units, house_at, soc0, refuse, limits)
+        import tempfile
+        db = os.path.join(tempfile.mkdtemp(prefix="p3r-"), "tariff.db")
+        c = Controller(dict(options(modes, arb, n), **(extra or {})), hass,
+                       store, _Pub(), stop=asyncio.Event(), peak_db_path=db)
+        for i in c.inverters:
+            i.dev_min, i.dev_max = (limits or {}).get(i.name[-1],
+                                                      (-5000.0, 5000.0))
+        if patch is not None:
+            patch(c)
+        c.auto = True
+        real_dt = m.datetime
+        clock = [start]
+
+        class _DT(real_dt):
+            @classmethod
+            def now(cls, tz=None):
+                return clock[0] if tz is None else clock[0].astimezone(tz)
+
+        m.datetime = _DT
+        plan_hour = None
+        try:
+            t = 0.0
+            while t < dur:
+                now = start + timedelta(seconds=t)
+                hass.t = t
+                clock[0] = now
+                if plan_hour != now.replace(minute=0, second=0,
+                                            microsecond=0):
+                    plan_hour = now.replace(minute=0, second=0,
+                                            microsecond=0)
+                    c.tariff_plan, c.tariff_at = plan_at(now, pts), now
+                else:
+                    c.tariff_at = now
+                imp, exp = split_signed(hass.grid())
+                c.p1.submit(make_sample("ha_signed", imp, exp, phases=1,
+                                        ingest_ts=now,
+                                        ingest_mono=time.monotonic()))
+                await c.read_inputs(now_mono=t)
+                await c.cycle()
+                for p in hass.plants.values():
+                    p.step(TICK, 10.0)
+                g = hass.grid()
+                pr = price_at(now)
+                dt_h = TICK / 3600.0
+                if g > 0:
+                    stats["imp_kwh"] += g / 1000 * dt_h
+                    stats["cost"] += g / 1000 * dt_h * (all_in(pr) if pr
+                                                         is not None else 0)
+                else:
+                    stats["exp_kwh"] += -g / 1000 * dt_h
+                    stats["exp_rev"] += -g / 1000 * dt_h * (pr or 0.0)
+                for u, p in hass.plants.items():
+                    if p.p > 0:
+                        stats["out_kwh"][u] += p.p / 1000 * dt_h
+                    else:
+                        stats["in_kwh"][u] -= p.p / 1000 * dt_h
+                q = int(now.timestamp() // 900)
+                acc = stats["quarters"].setdefault(q, [0.0, 0, False])
+                acc[0] += max(0.0, g)
+                acc[1] += 1
+                if (getattr(c.arb, "action", None) or "").endswith("CHARGE"):
+                    acc[2] = True
+                    stats["trade_ticks"] += 1
+                stats["ticks"] += 1
+                if check is not None:
+                    check(c, hass, now, pr)
+                t += TICK
+        finally:
+            m.datetime = real_dt
+        return c
+    c = asyncio.run(go())
+    return stats, c
+
+
+def summary(stats):
+    qs = stats["quarters"]
+    worst = max((a[0] / a[1] for a in qs.values()), default=0.0)
+    worst_trade = max((a[0] / a[1] for a in qs.values() if a[2]),
+                      default=0.0)
+    cyc = {u: round(v / CAP_KWH, 2) for u, v in stats["out_kwh"].items()}
+    return {"import_kwh": round(stats["imp_kwh"], 2),
+            "export_kwh": round(stats["exp_kwh"], 2),
+            "import_eur": round(stats["cost"], 2),
+            "export_eur": round(stats["exp_rev"], 2),
+            "net_eur": round(stats["cost"] - stats["exp_rev"], 2),
+            "cycles": cyc, "worst_quarter_w": round(worst, 1),
+            "worst_charge_quarter_w": round(worst_trade, 1),
+            "charge_ticks": stats["trade_ticks"]}
+
+
+LOOP_DAYS = [f"2026-09-{d:02d}" for d in range(2, 18)]
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--variant", default="p3_ls")
+    ap.add_argument("--days", type=int, default=16)
+    ap.add_argument("--captured", action="store_true")
+    a = ap.parse_args()
+    if a.captured:
+        days = ["2026-09-09", "2026-09-10"]
+        pts = qh_points()
+    else:
+        days = LOOP_DAYS[:a.days]
+        pts = epex_points()
+    house = load_house(days)
+    start = datetime.fromisoformat(days[0] + "T00:00:00+02:00") \
+        .astimezone(timezone.utc)
+    dur = 86400.0 * len(days)
+    t0 = time.time()
+    stats, _c = run(a.variant, house, pts, start, dur)
+    out = summary(stats)
+    out["variant"], out["days"] = a.variant, len(days)
+    out["wall_s"] = round(time.time() - t0, 1)
+    print(json.dumps(out))
+
+
+if __name__ == "__main__":
+    main()

goodwe_controller/tools/replay_ac3.py

@@ -176,7 +176,7 @@ def replay(paths, *, guarded: bool, cap_w, max_w, max_hold_s, cycle_s,
             next_cycle = t + timedelta(seconds=cycle_s)
             cycles += 1
             d = decide(PeakTracker.project(ing.averager, t), batt_w=batt,
-                       cap_w=cap_w, reading=tracker.peak(t),
+                       cap_w=cap_w, margin_w=0.0, reading=tracker.peak(t),
                        achievable_w=max_w, max_hold_s=max_hold_s, soc=soc,
                        soc_floor=soc_floor, frozen=False)
             if d.engaged:

goodwe_controller/tools/safety78_identity.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""SAFETY-78: at one inverter, is a maintenance drain byte-identical to before?
+
+    python3 tools/safety78_identity.py          # prints one digest per scenario
+
+tools/safety79_identity.py's harness (the REAL Controller on a P1 meter, so
+the peak guard runs) with the battery draining for its monthly cycle from the
+first cycle, under a house below, at and above the drain rate, a solar
+surplus and a load over the peak limit. Each row hashes safety79's fields,
+the modes' roles and the trade, the action log's newest line, and every claim
+main.py hands `resolve()`, so a claim or a log line added at N=1 that changes
+no watt still moves the digest. The `_modes` scenarios run battery modes on,
+Cheap hours only, over opt11p3_identity's prices. Uses only the API release/1.0 5a4cdc2 has, so the same file runs on
+both trees; test_safety78.py part 5 holds this tree to the digests printed
+there.
+"""
+
+import functools
+import hashlib
+import os
+import sys
+import tempfile
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+import opt11_identity as rig                               # noqa: E402
+import opt11p3_identity as p3                              # noqa: E402
+import safety79_identity as s79                            # noqa: E402
+import app.main as m                                       # noqa: E402
+from app import packmode                                  # noqa: E402
+from app.store import unit_key                            # noqa: E402
+
+DUR = 2400.0
+DRAIN = {"maintenance_enabled": True, "maintenance_start_hour": 11}
+
+
+def load(t):
+    """Below the 2000 W drain, at it, above it, a surplus, over the limit."""
+    k = int(t // 480)
+    return (1200.0, 2000.0, 3000.0, -1500.0, 6000.0)[min(k, 4)]
+
+
+def store_cheap(n):
+    s = rig._Store()
+    for u in ("inverter-a", "inverter-b")[:n]:
+        s.data[unit_key(u, packmode.MODE_KEY)] = packmode.CHEAP_HOURS
+    return s
+
+
+SCENARIOS = {
+    "n1_drain": dict(n=1),
+    "n1_drain_modes": dict(n=1, modes=True),
+}
+
+
+def run(n, *, modes=False, dur=DUR):
+    extra = dict(s79.P1, **DRAIN)
+    if modes:
+        extra.update(p3.ARB, battery_modes_enabled=True)
+    seen, extra_rows = [], []
+    real_resolve = m.resolve
+
+    def spy(claims, **kw):
+        seen.append(tuple((c.source, c.priority, c.kind, c.value, c.lo, c.hi,
+                           c.reason, c.actuator) for c in claims))
+        return real_resolve(claims, **kw)
+
+    def on_cycle(c, t):
+        g, tick, a = c.peak_guard, c.mode_tick, c.arb
+        extra_rows.append((
+            seen[-1] if seen else None,
+            None if g is None else (g.engaged, g.floor_w, g.reason),
+            None if tick is None else (tuple(sorted(tick.roles.items())),
+                                       tick.action, tick.why),
+            None if a is None else (a.action, a.power_w, a.reason),
+            [mm.phase for mm in c.maints],
+            len(c.events), c.events[0] if c.events else None))
+    db = os.path.join(tempfile.mkdtemp(prefix="s78-"), "tariff.db")
+    real = rig.Controller
+    rig.Controller = functools.partial(real, peak_db_path=db)
+    m.resolve = spy
+    try:
+        rows, c = rig.run(n, extra=extra, dur=dur, load=load, soc=s79.soc,
+                          cut=lambda u, t: False,
+                          before=p3._feed if modes else s79._feed,
+                          on_cycle=on_cycle,
+                          store=store_cheap(n) if modes else None)
+    finally:
+        rig.Controller = real
+        m.resolve = real_resolve
+    return [r + (x,) for r, x in zip(rows, extra_rows)], c
+
+
+def digest(rows) -> str:
+    return hashlib.sha256(repr(rows).encode()).hexdigest()
+
+
+def digests() -> dict:
+    return {k: digest(run(**v)[0]) for k, v in SCENARIOS.items()}
+
+
+if __name__ == "__main__":
+    if "--summary" in sys.argv:
+        for k, v in SCENARIOS.items():
+            rows = run(**v)[0]
+            print(f"{k}: {len(rows)} cycles, phases "
+                  f"{sorted({str(r[-1][-1]) for r in rows})}, targets "
+                  f"{sorted({r[1] for r in rows})[:6]}")
+    for k, v in digests().items():
+        print(f"{k} {v}")

goodwe_controller/tools/safety79_identity.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""SAFETY-79: with `peak_margin_w: 0`, is every command byte-identical to before?
+
+    python3 tools/safety79_identity.py          # prints one digest per scenario
+
+tools/opt11_identity.py's harness (the REAL Controller, read_inputs + cycle, in
+simulated time) with a P1 meter, so the peak guard runs, and a peak limit the
+house goes over. Each row hashes opt11_identity's fields plus the guard's floor,
+limit and sentence, its charge headroom (what arbitrage is sized to) and the
+maintenance shaping's suspension. The two `_maint` scenarios run a maintenance
+charge in a cheap window with a demand forecast that crosses cap - 50 .. cap,
+so `shaping_suspended()` and `maintenance_charge_floor()` are both reached.
+It uses only the API release/1.0 ed739d4 already had, so
+the same file runs on the old tree (which ignores `peak_margin_w`) and the new.
+test_peak_margin.py part 1 holds the new tree to the digests printed on ed739d4.
+"""
+
+import functools
+import hashlib
+import os
+import sys
+import tempfile
+import time
+from datetime import timedelta
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+import opt11_identity as rig                               # noqa: E402
+from app import packmode, peakguard                       # noqa: E402
+from app.p1 import make_sample, split_signed              # noqa: E402
+from app.store import unit_key                            # noqa: E402
+
+CAP_W = 2500
+
+
+def load(t):
+    """A house under the limit, over it, a solar surplus, far over, over."""
+    if t < 300:
+        return 800.0
+    if t < 900:
+        return 3200.0
+    if t < 1500:
+        return -2600.0
+    if t < 2100:
+        return 6000.0
+    return 4200.0
+
+
+def soc(u, t):
+    return 60.0         # above the peak reserve: the guard may discharge
+
+
+def _feed(c, t):
+    """One P1 telegram per cycle: the meter reads what the house and the
+    batteries' measured power leave."""
+    imp, exp = split_signed(c.hass.grid())
+    c.p1.submit(make_sample("ha_signed", imp, exp, phases=1,
+                            ingest_ts=rig.BASE + timedelta(seconds=t),
+                            ingest_mono=time.monotonic()))
+
+
+def store_off(name):
+    """A store where battery `name` is switched Off (OPT-11)."""
+    s = rig._Store()
+    s.data[unit_key(name, packmode.USE_KEY)] = False
+    return s
+
+
+def forecast(t):
+    """A demand forecast that sweeps 2300-2600 W every 10 minutes: across
+    cap - 50 and the cap, so the margin moves the forecast checks."""
+    return 2300.0 + (t % 600) / 600 * 300
+
+
+def _feed_maint(c, t):
+    """`_feed`, plus the forecast and a cheap price (now under average)."""
+    if not getattr(c.hass, "_s79", False):
+        read = c.hass.number
+        fixed = {"sensor.pnow": 0.05, "sensor.pavg": 0.20}
+
+        async def number(e, invert=False):
+            if e == "sensor.fc":
+                return forecast(c.hass.t)
+            if e in fixed:
+                return fixed[e]
+            return await read(e, invert)
+        c.hass.number, c.hass._s79 = number, True
+    _feed(c, t)
+
+
+def store_charging(n):
+    """A store where the first battery is in its maintenance CHARGE phase."""
+    s = rig._Store()
+    for k in ("phase", "phase_started"):
+        s.data[k if n == 1 else unit_key("inverter-a", k)] = (
+            "charge" if k == "phase" else rig.BASE.isoformat())
+    return s
+
+
+P1 = {"meter_source": "ha_signed", "p1_net_entity": "sensor.net",
+      "meter_phases": 1, "peak_cap_w": CAP_W}
+MODES = {"battery_modes_enabled": True}
+MAINT = {"maintenance_enabled": True, "maintenance_start_hour": 11,
+         "peak_forecast_entity": "sensor.fc", "price_now_entity": "sensor.pnow",
+         "price_avg_entity": "sensor.pavg"}
+
+SCENARIOS = {
+    "n1": dict(n=1),
+    "n2": dict(n=2),
+    # OPT-11: the only battery Off, so only the peak guard makes it give.
+    "n1_off": dict(n=1, modes=True, off="inverter-a"),
+    # OPT-11: B Off, so B covers what A cannot.
+    "n2_off": dict(n=2, modes=True, off="inverter-b"),
+    # A maintenance charge in a cheap window, with a demand forecast.
+    "n1_maint": dict(n=1, maint=True),
+    "n2_maint": dict(n=2, maint=True),
+}
+
+
+def run(n, *, margin=None, modes=False, off=None, maint=False, dur=2700.0):
+    """Rows for one scenario; `margin=None` leaves the key out."""
+    extra = dict(P1, **(MODES if modes else {}), **(MAINT if maint else {}))
+    if margin is not None:
+        extra["peak_margin_w"] = margin
+    guard = []
+
+    def on_cycle(c, t):
+        g = c.peak_guard
+        guard.append((c._maint_shape_suspended, None if g is None else (
+            g.engaged, g.floor_w, g.ceiling_w, g.ceiling_from, g.reason,
+            peakguard.charge_headroom_w(g))))
+    db = os.path.join(tempfile.mkdtemp(prefix="s79-"), "tariff.db")
+    real = rig.Controller
+    rig.Controller = functools.partial(real, peak_db_path=db)
+    try:
+        rows, c = rig.run(n, extra=extra, dur=dur, load=load, soc=soc,
+                          cut=lambda u, t: False,
+                          before=_feed_maint if maint else _feed,
+                          on_cycle=on_cycle,
+                          store=(store_off(off) if off else
+                                 store_charging(n) if maint else None))
+    finally:
+        rig.Controller = real
+    return [r + (g,) for r, g in zip(rows, guard)], c
+
+
+def digest(rows) -> str:
+    return hashlib.sha256(repr(rows).encode()).hexdigest()
+
+
+def digests(margin=None) -> dict:
+    return {k: digest(run(**v, margin=margin)[0]) for k, v in SCENARIOS.items()}
+
+
+if __name__ == "__main__":
+    m = None if len(sys.argv) < 2 else int(sys.argv[1])
+    for k, v in digests(m).items():
+        print(f"{k} {v}")

goodwe_controller/tools/safety81_sim.py

@@ -0,0 +1,229 @@
+#!/usr/bin/env python3
+"""SAFETY-81: when does "Load too high for battery" fire?
+
+    python3 tools/safety81_sim.py            # alarms and a control digest per run
+
+The REAL Controller (read_inputs + cycle) at a 1 s cycle, on a plant shaped
+like the SAFETY-79 test rig: one battery switched Off (so only the peak guard
+makes it give, max 2000 W), a 3500 W cap, and a P1 meter that publishes
+0.3 s before each cycle. The battery reaches a new command 0.5 s after it is
+written. One meter sample in ten arrives late (the add-on still holds the one
+before), so the held meter reading can predate the battery's last change:
+the double count behind the rig's false alarms. The cycle on a quarter
+boundary, before the new quarter's first sample, files no peak claim, which
+is the rig's 1 s grid spike at each quarter change. Each run returns the
+alarm times and a digest of every command, so the same runs show both what
+changed and what did not.
+"""
+
+import asyncio
+import hashlib
+import logging
+import os
+import random
+import sys
+import tempfile
+import time
+from datetime import timedelta
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+import opt11_identity as rig                               # noqa: E402
+import app.main as m                                       # noqa: E402
+from app import packmode                                   # noqa: E402
+from app.main import Controller                            # noqa: E402
+from app.p1 import make_sample, split_signed               # noqa: E402
+from app.store import unit_key                             # noqa: E402
+
+TICK = 1.0
+SAMPLE_LEAD_S = 0.3     # the meter publishes this long before each cycle
+RESPONSE_S = 0.5        # a new command reaches the battery this much later
+LATE_P = 0.1            # share of meter samples that arrive late
+ALARM = "goodwe_peak_saturated"
+
+
+def constant(w):
+    return lambda t: w
+
+
+def noisy(mean, amp, seed=81):
+    """`mean` +/- `amp`, a new uniform value every second."""
+    rnd = random.Random(seed)
+    table = {}
+
+    def f(t):
+        k = int(t)
+        if k not in table:
+            table[k] = mean + rnd.uniform(-amp, amp)
+        return table[k]
+    return f
+
+
+def sine(mean, amp, period=120.0, noise=50.0):
+    import math
+    n = noisy(0.0, noise, seed=79)
+    return lambda t: mean + amp * math.sin(2 * math.pi * t / period) + n(t)
+
+
+def step(before, after, at):
+    return lambda t: before if t < at else after
+
+
+def ramp(before, after, at, secs):
+    return lambda t: before + (after - before) * min(max(t - at, 0.0) / secs, 1.0)
+
+
+class _Plant:
+    """One battery that reaches its command RESPONSE_S after the write."""
+
+    def __init__(self, load, rating, soc, batt_gap=()):
+        self.load, self.rating, self.soc = load, rating, soc
+        self.batt_gap = batt_gap      # (from, to): the battery reading is lost
+        self.t = 0.0
+        self.hist = [(-1e9, 0.0)]     # (time the command takes effect, W)
+        self.notes = []
+        self.meter = 0.0              # the last meter reading delivered
+
+    def batt(self, at):
+        w = 0.0
+        for when, v in self.hist:
+            if when <= at:
+                w = v
+        return max(-self.rating, min(self.rating, float(round(w))))
+
+    def grid(self, at):
+        return self.load(at) - self.batt(at)
+
+    async def limits(self, e):
+        return (-5000.0, 5000.0, 1.0)
+
+    async def call(self, domain, service, data):
+        if service == "create":
+            self.notes.append((self.t, data.get("notification_id")))
+        return True
+
+    async def number(self, e, invert=False):
+        if e in ("sensor.grid", "sensor.net"):
+            return self.meter
+        if e.startswith("sensor.soc"):
+            return self.soc
+        if e.startswith("sensor.batt"):
+            if self.batt_gap and self.batt_gap[0] <= self.t < self.batt_gap[1]:
+                return None
+            return self.batt(self.t)
+        return None
+
+    async def set_number(self, e, v):
+        self.hist.append((self.t + RESPONSE_S, float(v)))
+        return True
+
+
+def run(load, *, margin=50, dur=2700.0, rating=2000.0, cap=3500.0,
+        late_at=(), soc=60.0, batt_gap=()):
+    """Alarm times (s from the start of the first quarter), a digest of every
+    cycle's target and written command, the Controller, the rows, and the
+    times of the ERROR log line. A sample is also late at each `t % 900` in
+    `late_at`."""
+    opts = rig._options(1, {
+        "meter_source": "ha_signed", "p1_net_entity": "sensor.net",
+        "meter_phases": 1, "peak_cap_w": cap, "peak_margin_w": margin,
+        "battery_modes_enabled": True, "max_w": rating})
+    store = rig._Store()
+    store.data[unit_key("inverter-a", packmode.USE_KEY)] = False
+    store.data[packmode.USE_KEY] = False
+    db = os.path.join(tempfile.mkdtemp(prefix="s81-"), "tariff.db")
+
+    async def go():
+        plant = _Plant(load, rating, soc, batt_gap)
+        c = Controller(opts, plant, store, rig._Pub(), stop=asyncio.Event(),
+                       peak_db_path=db)
+        for i in c.inverters:
+            i.dev_min, i.dev_max = -5000.0, 5000.0
+        c.auto = True
+        real_dt, clock = m.datetime, [0.0]
+
+        class _DT(real_dt):
+            @classmethod
+            def now(cls, tz=None):
+                return rig.BASE + timedelta(seconds=clock[0])
+        m.datetime = _DT
+        rows, late = [], random.Random(8100)
+        errors = []
+
+        class _Err(logging.Handler):
+            def emit(self, r):
+                if "battery alone cannot keep" in r.getMessage():
+                    errors.append(plant.t)
+        h = _Err()
+        logging.getLogger("goodwe").addHandler(h)
+        try:
+            t = 0.0
+            while t < dur:
+                plant.t = clock[0] = t
+                ts = t - SAMPLE_LEAD_S
+                if late.random() >= LATE_P and t % 900 not in late_at:
+                    plant.meter = plant.grid(ts)
+                    imp, exp = split_signed(plant.meter)
+                    c.p1.submit(make_sample(
+                        "ha_signed", imp, exp, phases=1,
+                        ingest_ts=rig.BASE + timedelta(seconds=ts),
+                        ingest_mono=time.monotonic()))
+                await c.read_inputs(now_mono=t)
+                await c.cycle()
+                rows.append((t, c.target, round(plant.hist[-1][1], 6)))
+                t += TICK
+        finally:
+            m.datetime = real_dt
+            logging.getLogger("goodwe").removeHandler(h)
+        return plant, c, rows, errors
+    plant, c, rows, errors = asyncio.run(go())
+    alarms = [t for t, nid in plant.notes if nid == ALARM]
+    return (alarms, hashlib.sha256(repr(rows).encode()).hexdigest(), c, rows,
+            errors)
+
+
+# Three quarters each (2700 s); a new quarter starts at 900 s and 1800 s.
+SCENARIOS = {
+    # F1: constant and sine loads the battery carries, across quarter edges.
+    "const4500": dict(load=constant(4500.0)),
+    "const4500_m0": dict(load=constant(4500.0), margin=0),
+    "sine4500": dict(load=sine(4500.0, 400.0)),
+    # F1 at the start of a quarter: the sample after the battery's return
+    # is late, so the held reading is the 1 s spike (the battery at 0 W).
+    "edge4600": dict(load=constant(4600.0), late_at=(2.0,)),
+    "edge4600_m0": dict(load=constant(4600.0), margin=0, late_at=(2.0,)),
+    # 6000 W in a quarter's last 20 s: over cap + battery, but the quarter
+    # still lands between the aim and the cap.
+    "burst_end": dict(load=lambda t: 6000.0 if t % 900 >= 880 else 4500.0),
+    # F2: a noisy load the battery carries, at margin 50 and 0.
+    "noise5000_m50": dict(load=noisy(5000.0, 150.0)),
+    "noise5000_m0": dict(load=noisy(5000.0, 150.0), margin=0),
+    # Real: from 1200 s the house needs 1000 W more than cap + battery.
+    "step6500": dict(load=step(4500.0, 6500.0, 1200.0)),
+    # Real, small: from 1200 s, 60 W (+/- 20 W noise) more than cap + battery.
+    "miss5560": dict(load=lambda t: step(4500.0, 5560.0, 1200.0)(t)
+                     + noisy(0.0, 20.0)(t)),
+    # Real, slow: 4500 -> 6500 W over 200 s from 1200 s, through the band
+    # between the aim (cap - 50) and the real cap.
+    "ramp6500": dict(load=ramp(4500.0, 6500.0, 1200.0, 200.0)),
+    # The pack under its peak reserve (20 %), and a load far over cap +
+    # battery: that is "Battery stopped limiting the peak", not this alarm.
+    "step7500_reserve": dict(load=step(4500.0, 7500.0, 1200.0), soc=15.0),
+    # Review: a load swinging 4500 +/- 1200 W every 30 s (a hob or heater
+    # cycling). It tops cap + battery for about 5 s a swing, and the quarter
+    # still lands under the aim.
+    "sine4500_fast": dict(load=sine(4500.0, 1200.0, period=30.0, noise=200.0)),
+    # Review: two real overloads in one quarter, 1000-1100 s and 1500-1700 s.
+    "twice7000": dict(load=lambda t: 7000.0 if (1000 <= t < 1100
+                                                or 1500 <= t < 1700)
+                      else 4500.0),
+    # Review: step6500, and the battery reading is lost 1203-1215 s.
+    "step6500_gap": dict(load=step(4500.0, 6500.0, 1200.0),
+                         batt_gap=(1203.0, 1215.0)),
+}
+
+
+if __name__ == "__main__":
+    for k, v in SCENARIOS.items():
+        a, d, _, _, _ = run(**v)
+        print(f"{k:16s} alarms at {a} digest {d}")

goodwe_controller/translations/en.yaml

@@ -145,6 +145,9 @@ configuration:
   peak_cap_w:
     name: "Limits · Peak limit (W)"
     description: "Your own number: the 15-minute average power the add-on keeps the grid under. Take it from your grid contract."
+  peak_margin_w:
+    name: "Limits · Margin below the peak limit (W)"
+    description: "The add-on aims this much below the peak limit, so a 15-minute period that ends a little high still stays under it."
   peak_forecast_entity:
     name: "Limits · 15-minute demand forecast entity (W)"
     description: "Optional. A forecast of this 15-minute period's average power. Leave it empty and there is no peak limit."

goodwe_controller/translations/nl.yaml

@@ -126,6 +126,9 @@ configuration:
   peak_cap_w:
     name: "Grenzen · Piekgrens (W)"
     description: "Uw eigen getal: het gemiddelde vermogen per kwartier waaronder de add-on de afname houdt. Neem het over uit uw netcontract."
+  peak_margin_w:
+    name: "Grenzen · Marge onder de piekgrens (W)"
+    description: "De add-on mikt zoveel onder de piekgrens, zodat een kwartier dat iets hoger uitvalt er toch onder blijft."
   peak_forecast_entity:
     name: "Grenzen · Entiteit kwartierprognose (W)"
     description: "Optioneel. Een prognose van het gemiddelde vermogen in het lopende kwartier. Laat u dit leeg, dan is er geen piekgrens."