SAFETY-79 review: margin under a banked month peak too; identity harness reaches headroom and maintenance

- quarter_target_w() is now the margin under quarter_ceiling_w(): a peak
  banked between cap - margin and the cap was aimed at exactly, so one
  overshoot crossed the cap; above the cap the same overshoot raised the bill.
- safety79_identity.py hashes charge_headroom_w() and the shaping suspension,
  and adds n1_maint/n2_maint (cheap window, forecast across cap - 50 .. cap).
  Digests re-printed on ed739d4 and pinned; margin 0 still identical.
- test_margin_under_banked_peak; DECISIONS and DOCS updated.

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

docs/img/ux13/README.md

@@ -4,6 +4,6 @@ Made from the real page by `goodwe_controller/tools/ux13_screenshots.sh`. Do not
 edit them by hand: run the script again.
 
 - `home-*.png`: Home, running, in Dutch, in shadow mode, at phone width, and in setup.
-- `settings-*.png`: Settings (Installer view), and the time-window editor with an overlap.
+- `settings-*.png`: Settings, Simple and Installer, and the time-window editor with an overlap.
+- `batteries*.png`: the Batteries screen with modes on, in Dutch, an Off battery helping the peak limit, a refusal at phone width, and modes off.
 - `setup-step-1*.png`: Setup, step 1.
-- Battery modes (the Batteries screen and the Simple view): not built yet (UX-13 P3), so no screenshot.

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

@@ -0,0 +1,32 @@
+# OPT-11 - battery modes, per battery
+
+A battery's mode (on/off, Solar first, Leftover solar) is a soft unit limit at
+`P_MODE` = 35 that always holds 0 W. A SET above 35 (a safety stop) overrides
+it; a limit above 35 (the peak guard) makes it give way only as far as that
+limit needs, and a battery its mode holds back then carries only what the
+others cannot (`arbiter._unit_modes()`, `_site_mode()`). Design and owner answers: `goodwe-session/OPT-11-design.md` (2026-09-27);
+P1 is its section 6 P1, and the pull request lists what was measured.
+
+- Off by default (`battery_modes_enabled`); off, commands are byte-identical to
+  a5dddad (`test_modes.py` part 1).
+- Off is a mode range, so the peak guard can still use an Off battery when the
+  others cannot cover the floor (design sections 2-3). Whether Off should be
+  absolute is an open owner question.
+- Review (PR #149): releasing only when the peak floor bound S let a trade won
+  above the floor keep the modes and place less than the floor, and let a
+  capped grid charge release an Off battery. Both are graded in
+  `test_arbiter.py` part 11. The loop bound leaves a side that reaches the
+  rail to the rail, so SAFETY-03 still flags a loop winding into it.
+- P2 (HA entities): a select and a switch per battery, only while modes are
+  on; commands go through `handle_action()`, the page's path. A retained
+  command is dropped, not applied: the store already holds the last choice,
+  and a replay after a restart could otherwise undo a newer one. The config
+  topics announced are kept in the store (`mqtt_mode_configs`), so turning
+  modes off removes exactly those, and an install that never turned them on
+  publishes what ed739d4 did (`test_mqtt.py` part 10). A removed topic stays
+  in that list and its empty config is re-sent on each start, so a start with
+  no broker cannot lose it; re-sending is harmless. The HA options are the
+  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.

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/UX-13-one-layout-table.md

@@ -87,6 +87,14 @@ What UX-02 made authoritative stays authoritative:
   Configuration tab. Supervisor 2026.08.0's `AppOptions` accepted all 133
   wizard blobs, 17 of them with time windows
   (`tools/ux13_wizard_blobs.py --supervisor`, run offline on 2026-09-28).
+- P3: Settings, Simple draws the fields the table marks `simple`, with an
+  optional `note` under each (words in `settings.simple.note`), plus the
+  batteries' switches and modes. Those are store state set through the
+  existing `/action` values, not options, so the table places no key for
+  them. The Batteries screen's Now, Today and Why lines are built in
+  `homeview.py` from what the add-on knows this cycle; the plan per mode is
+  OPT-11 P3/P4, so until then Today says "Not planned yet" when no block
+  is planned for the battery (`test_batteries_screen.py`).
 
 ## 4. What this costs
 

goodwe_controller/DOCS.md

@@ -183,6 +183,7 @@ The label and description each setting shows on the Configuration tab, in tab or
 | Hardware · Inverter list | Battery power sign is reversed (optional) | `inverters.batt_invert` | Switch this on if this inverter's sensor shows giving power as a negative number. |
 | Hardware · Inverter list | Usable battery capacity (kWh) (optional) | `inverters.capacity_kwh` | This battery's usable capacity from its datasheet. Fill it in on every inverter or on none. The add-on then shares the work by the energy each battery has left. |
 | Hardware | RS485 emergency stop is fitted | `estop_fitted` | Switch this on if the emergency stop is installed. It only changes a warning on the status page. |
+| Hardware | Battery modes | `battery_modes_enabled` | Give each battery an on and off switch and a mode, set on the Batteries screen. |
 | Hardware | Solar production entity (W) | `pv_entity` | Optional. Your solar inverter's power sensor, positive while producing. The add-on records it and does not use it for control. |
 | Hardware | Solar production entities, per inverter (W) | `pv_entities` | Optional. Use one row per solar inverter instead of “Solar production entity” when you have several. If one stops reporting, no total is recorded. |
 | Hardware | Reversed-sign solar entities | `pv_invert_entities` | Optional. Add each solar entity above that reads negative while producing, spelled the same way. Its sign is flipped before adding up. |
@@ -203,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. |
@@ -273,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.
@@ -512,6 +515,21 @@ two of a thing there is one of, and `P1 sample age` is a safety input. Same for
 status, the maintenance phase, the capacity-tariff peak and the three loop rows
 below.
 
+### Battery modes (`battery_modes_enabled`)
+
+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.
+
+The peak limit, the safety stops and the monthly cycle always come before a battery's mode.
+
+**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.
+
+*For installers:* commands arrive on `goodwe_ctl/unit/<battery>/mode/set` (a *Mode* option, such as `Solar first`) and `.../use/set` (`ON` or `OFF`). They go through the same checks as the Batteries screen. A refusal is logged once, and later refusals are counted in the log. A retained command is never applied, so the broker cannot replay an old choice after a restart; the add-on keeps the last choice itself.
+
+*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`.
+
 ### 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
@@ -1600,6 +1618,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 |
@@ -3233,12 +3252,29 @@ The page is in Dutch when your browser's language is Dutch, and in English
 otherwise. Status lines, alarms and the start checks' messages stay in English.
 
 Screenshots of each screen are in the add-on's repository, under
-`docs/img/ux13/`. The battery-mode screens are not built yet, so there are no
-screenshots of them.
+`docs/img/ux13/`, including the Batteries screen and Settings, Simple.
 
 *For installers: regenerate the screenshots with
 `tools/ux13_screenshots.sh`, which serves the page from test fixtures.*
 
+### The Batteries screen and Settings, Simple
+
+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.
+
+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."
+
+**Settings** opens on the **Simple** view, or on the view you last picked:
+the peak limit, the batteries' switches and modes, and shadow mode, each
+marked "Applies right away" or "Applies after a restart". **Installer** shows
+every setting.
+
 ### Setup, for a new install
 
 The **Setup** tab walks an installer through six steps: the meter, the

goodwe_controller/app/allocator.py

@@ -98,6 +98,12 @@ DROP_STALE = "stale link"
 DROP_CONTRADICTION = "contradicts itself"
 DROP_NO_INTEGER = "no integer setpoint in its interval"
 
+# OPT-11: why a unit's MODE layer was not applied this tick. Only the first is
+# a fault; the other two are the rule working.
+MODE_FAULT = "mode range leaves out 0 W"
+MODE_RELEASED = "mode released by a higher claim"
+MODE_OUTRANKED = "hard limit leaves no room for the mode"
+
 REFUSE_SCOPE = "mis-routed claim"
 REFUSE_EMPTY = "no unit available"
 REFUSE_SIGN = "opposite directions"
@@ -213,6 +219,10 @@ class Allocation:
     # that calls `plan()` for its arithmetic gets None and does not care;
     # main.py stamps every record it puts on the write path.
     tick: int | None = None
+    # OPT-11: ((unit, why), ...) for each unit whose mode range left out 0 W
+    # this tick. That mode was dropped (see `unit_interval()`); main.py logs it
+    # as a software fault. Empty on every tick without a mode.
+    mode_faults: tuple = ()
 
     @property
     def ok(self) -> bool:
@@ -290,6 +300,87 @@ class Allocation:
         return out
 
 
+def unit_interval(b, deciding_priority=None):
+    """OPT-11. `(lo, hi, note)`: the interval a unit is allocated into.
+
+    The hard limits (`b.lo`, `b.hi`) always apply. The unit's MODE range
+    (`b.mode_lo`, `b.mode_hi`) narrows them unless `deciding_priority` is
+    above the mode's own priority (arbiter._unit_modes() passes None when the
+    modes hold, and the yielding limit's priority when they give way). `note` says why the
+    mode did not apply, or is None when it did or there is none:
+
+    * MODE_FAULT: the mode range leaves out 0 W. A mode may forbid a direction
+      and never force one, so this is a software fault and the mode is dropped.
+      It is what keeps REFUSE_SIGN unreachable from a mode: the fill below
+      moves every free unit away from 0 in ONE direction, and it starts from 0
+      only while every interval holds 0.
+    * MODE_RELEASED: a higher claim (the peak floor) decided the target.
+    * MODE_OUTRANKED: the hard limits and the mode do not overlap. The hard
+      limits win, as they always do.
+
+    A unit without mode fields (`mode_priority` absent or None) gets its hard
+    limits, unchanged: that is every unit when battery modes are off.
+    """
+    lo, hi = b.lo, b.hi
+    prio = getattr(b, "mode_priority", None)
+    if prio is None:
+        return lo, hi, None
+    mlo, mhi = b.mode_lo, b.mode_hi
+    if not (mlo <= 0.0 <= mhi):
+        return lo, hi, MODE_FAULT
+    if deciding_priority is not None and deciding_priority > prio:
+        return lo, hi, MODE_RELEASED
+    nlo, nhi = max(lo, mlo), min(hi, mhi)
+    if nlo > nhi:
+        return lo, hi, MODE_OUTRANKED
+    return nlo, nhi, None
+
+
+class _Narrowed:
+    """A unit's bounds with its interval replaced by `unit_interval()`'s."""
+    __slots__ = ("lo", "hi")
+
+    def __init__(self, lo, hi):
+        self.lo, self.hi = lo, hi
+
+
+def loop_bound(bounds, live=None):
+    """OPT-11. `(lo, hi)`: what the units can place when the LOOP decides.
+
+    The sum, over live units that do not contradict themselves, of each unit's
+    interval with its mode applied (`unit_interval()` with no higher claim). A
+    pinned unit adds the span from 0 to its pin, so a probe or a maintenance
+    pin stays reachable. Every term holds 0, so the sum does too.
+
+    `compute()` keeps the site target inside this, so the loop never asks for
+    watts no battery may give: the allocator would report them as unmet and the
+    saturation freeze would park the target on them (SAFETY-73 section 1).
+    Pure, like `plan()`: it reads numbers and intervals and nothing else.
+    """
+    lo_sum, hi_sum = 0.0, 0.0
+    for u in sorted(bounds):
+        b = bounds[u]
+        if live is not None and u not in live:
+            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))
+            lo_sum += min(0.0, p)
+            hi_sum += max(0.0, p)
+            continue
+        lo, hi, _ = unit_interval(b)
+        lo, hi = _int_envelope(_Narrowed(lo, hi))
+        if lo > hi:
+            continue
+        lo_sum += min(0.0, lo)
+        hi_sum += max(0.0, hi)
+    return lo_sum, hi_sum
+
+
 def _int_envelope(b):
     """A unit's interval, narrowed to the integers a 1 W register can hold.
 
@@ -385,7 +476,8 @@ def _fill(order, weights, cap, amount):
 
 
 def plan(target_w, bounds, *, weights=None, live=None, scope_errors=(),
-         site_priority=None, site_key="site", tick=None) -> Allocation:
+         site_priority=None, site_key="site", tick=None,
+         deciding_priority=None) -> Allocation:
     """Divide the site grid target `target_w` across the units in `bounds`.
 
     `bounds`   unit name -> that unit's interval for THIS TICK (arbiter stage 1,
@@ -411,6 +503,9 @@ def plan(target_w, bounds, *, weights=None, live=None, scope_errors=(),
     `site_priority` the priority of the SITE claim that chose `target_w`. It is
                what a unit's own winning SET is weighed against - see PINS.
     `site_key` the name to use when there are no units at all.
+    `deciding_priority` OPT-11: the priority that decided `target_w`
+               (`Resolution.deciding_priority`). Each unit's mode range applies
+               only at or below it - see `unit_interval()`. None applies them.
     `tick`     an opaque token identifying the tick this record is FOR, handed
                straight back on the record. SAFETY-28's write gate compares it
                against the tick it is writing on, so that a record cannot be
@@ -497,6 +592,7 @@ def plan(target_w, bounds, *, weights=None, live=None, scope_errors=(),
     dropped = []
     ilo, ihi = {}, {}
     considered = []
+    mode_faults = []
     for u in units:
         b = bounds[u]
         if live is not None and u not in live:
@@ -512,7 +608,12 @@ def plan(target_w, bounds, *, weights=None, live=None, scope_errors=(),
             # has no interval to allocate into.
             dropped.append((u, DROP_CONTRADICTION))
             continue
-        lo, hi = _int_envelope(b)
+        # OPT-11: the mode layer, when it applies, narrows the hard limits.
+        # A unit with no mode gets exactly its hard limits, as before.
+        nlo, nhi, note = unit_interval(b, deciding_priority)
+        if note == MODE_FAULT:
+            mode_faults.append((u, MODE_FAULT))
+        lo, hi = _int_envelope(_Narrowed(nlo, nhi))
         if lo > hi:
             # An interval that contains no integer. The register is 1 W, so
             # there is no number this unit could be commanded that both bounds
@@ -526,7 +627,7 @@ def plan(target_w, bounds, *, weights=None, live=None, scope_errors=(),
         return Allocation(
             target_w=float(target_w), sum_w=sum_w, shares={}, plans=(),
             dropped=tuple(dropped), unmet_w=sum_w, quantisation_w=quant,
-            refused=why, tick=tick)
+            refused=why, tick=tick, mode_faults=tuple(mode_faults))
 
     # --- REFUSAL 2: nobody is available ------------------------------------
     if not considered:
@@ -659,4 +760,5 @@ def plan(target_w, bounds, *, weights=None, live=None, scope_errors=(),
 
     return Allocation(target_w=float(target_w), sum_w=sum_w, shares=shares,
                       plans=tuple(plans), dropped=tuple(dropped),
-                      unmet_w=int(unmet), quantisation_w=quant, tick=tick)
+                      unmet_w=int(unmet), quantisation_w=quant, tick=tick,
+                      mode_faults=tuple(mode_faults))

goodwe_controller/app/arbiter.py

@@ -86,8 +86,17 @@ P_MAINT_SHAPE = 40    # maintenance shaping the loop (charge-only)
 # because trading against the meter is the entire point - the grid-following
 # loop would otherwise cancel every charge the moment it created import.
 P_ARBITRAGE = 30      # price arbitrage - trades against the meter on purpose
+# OPT-11. A battery's mode (Solar first, Leftover solar, Off): a SOFT unit
+# limit, kept apart from the hard ones. Above arbitrage, so a trade stays inside
+# each battery's mode; below the peak guard, to which a mode gives way only as
+# far as the floor needs (`_unit_modes()`, `_site_mode()`).
+# DECISIONS/OPT-11-battery-modes.md.
+P_MODE = 35
 P_LOOP = 10           # ordinary grid-following
 
+# The one source filed at P_MODE. pre_resolve() keeps it out of the hard limits.
+MODE_SOURCE = "mode"
+
 SET = "set"
 LIMIT = "limit"
 
@@ -238,6 +247,13 @@ CLAIM_SCOPE = {
     # this pack to its floor, charge this pack to full, recalibrate this pack's
     # coulomb counter. Two packs recalibrate on their own schedules.
     "maintenance": SCOPE_UNIT,
+    # main.py: `Claim.limit("mode", P_MODE, lo, hi, ...)`, OPT-11. THIS
+    # battery's mode, chosen per battery by its owner. A unit claim that never
+    # enters a `lo > hi` test with a site limit: stage 1 keeps it apart from the
+    # hard limits, and it gives way to a site limit above P_MODE only as far as
+    # that limit needs (`_unit_modes()`). At N=1 it routes to the site, and
+    # `resolve()` takes it out of stage 2 for the same reason.
+    "mode": SCOPE_UNIT,
 }
 
 
@@ -365,6 +381,13 @@ class UnitBounds:
     pinned_w: float | None = None
     pinned_by: str | None = None
     contradiction: bool = False
+    # OPT-11: the mode layer, APART from `lo`/`hi` above, which stay the hard
+    # limits. `mode_priority` is None when no mode claim applies. Whether the
+    # mode binds is decided at stage 3 (`allocator.unit_interval()`), because it
+    # depends on the priority that decided the SITE target.
+    mode_lo: float = -inf
+    mode_hi: float = inf
+    mode_priority: int | None = None
 
     def explain(self) -> str:
         if self.contradiction:
@@ -410,6 +433,15 @@ class Resolution:
     # rules drifting apart: this is set by the same line that picks the winner
     # `explain()` names.
     winner_priority: int | None = None
+    # OPT-11. The higher of the winning set's priority and the priority of the
+    # limit that bound `target_w`. Whether the modes hold is decided from the
+    # limits themselves (`_site_mode()`, `_unit_modes()`): a mode gives way
+    # only as far as a limit above it (the peak floor) needs, so a mode `hi`
+    # never meets a site `lo`.
+    deciding_priority: int | None = None
+    # OPT-11 at N=1: why the site's mode layer was dropped this tick, or None.
+    # At N>1 the same fact is on `allocation.mode_faults`, per unit.
+    mode_fault: str | None = None
 
     def explain(self) -> str:
         """One line an operator can act on - this is the point of the module."""
@@ -433,7 +465,8 @@ def pre_resolve(unit_claims: list) -> UnitBounds:
     of the fault this card removes, and the reason `resolve()` partitions rather
     than filters twice.
     """
-    sets = sorted((c for c in unit_claims if c.kind == SET),
+    sets = sorted((c for c in unit_claims
+                   if c.kind == SET and c.source != MODE_SOURCE),
                   key=lambda c: c.priority, reverse=True)
     gate = pinned_w = pinned_by = None
     if sets:
@@ -441,19 +474,30 @@ def pre_resolve(unit_claims: list) -> UnitBounds:
 
     lo, hi = -inf, inf
     lo_src = hi_src = None
+    # OPT-11: a mode claim never joins the hard limits, so a mode cannot make a
+    # unit contradict itself or narrow a pin. A mode SET is not a thing: only
+    # limits are read. The lowest mode priority is kept (the first to release).
+    mode_lo, mode_hi, mode_priority = -inf, inf, None
     for c in unit_claims:
         if c.kind != LIMIT or (gate is not None and c.priority < gate):
             continue
+        if c.source == MODE_SOURCE:
+            mode_lo, mode_hi = max(mode_lo, c.lo), min(mode_hi, c.hi)
+            mode_priority = (c.priority if mode_priority is None
+                             else min(mode_priority, c.priority))
+            continue
         if c.lo > lo:
             lo, lo_src = c.lo, c.source
         if c.hi < hi:
             hi, hi_src = c.hi, c.source
     return UnitBounds(lo, hi, lo_src, hi_src, gate, pinned_w, pinned_by,
-                      contradiction=lo > hi)
+                      contradiction=lo > hi, mode_lo=mode_lo, mode_hi=mode_hi,
+                      mode_priority=mode_priority)
 
 
 def allocate(target_w: float, bounds: dict, *, weights=None, live=None,
-             scope_errors=(), site_priority=None) -> tuple:
+             scope_errors=(), site_priority=None,
+             deciding_priority=None) -> tuple:
     """STAGE 3. THE SEAM, AND SINCE ALLOC-01 IT IS OCCUPIED. `(shares, allocated)`.
 
     ⚠️ THE ALLOCATOR ITSELF IS `app/allocator.py` AND THE REASONING LIVES THERE.
@@ -491,11 +535,13 @@ def allocate(target_w: float, bounds: dict, *, weights=None, live=None,
     """
     return allocate_record(target_w, bounds, weights=weights, live=live,
                            scope_errors=scope_errors,
-                           site_priority=site_priority)[:2]
+                           site_priority=site_priority,
+                           deciding_priority=deciding_priority)[:2]
 
 
 def allocate_record(target_w: float, bounds: dict, *, weights=None, live=None,
-                    scope_errors=(), site_priority=None, tick=None) -> tuple:
+                    scope_errors=(), site_priority=None, tick=None,
+                    deciding_priority=None) -> tuple:
     """`allocate()` plus the record - `(shares, allocated, allocation)`.
 
     `tick` is SAFETY-28's freshness token: it identifies the tick the record is
@@ -507,7 +553,7 @@ def allocate_record(target_w: float, bounds: dict, *, weights=None, live=None,
     rec = allocator.plan(target_w, bounds, weights=weights, live=live,
                          scope_errors=scope_errors,
                          site_priority=site_priority, site_key=ACTUATOR_SITE,
-                         tick=tick)
+                         tick=tick, deciding_priority=deciding_priority)
     return rec.shares, rec.ok, rec
 
 
@@ -544,19 +590,26 @@ def site_resolve(claims: list) -> Resolution:
     considered = [f"{c.source}:{c.kind}" for c in claims]
 
     if lo > hi:
+        # OPT-11: 0 W here, and every limit that took part counts as deciding.
         return Resolution(0.0, winner.source, bound_by=None,
                           contradiction=True, considered=considered,
-                          winner_priority=winner.priority)
+                          winner_priority=winner.priority,
+                          deciding_priority=max(winner.priority,
+                                                lo_src.priority,
+                                                hi_src.priority))
 
     target = max(lo, min(hi, winner.value))
     bound_by = None
+    deciding = winner.priority
     if target != winner.value:
         binder = lo_src if target == lo else hi_src
         if binder is not None:
             bound_by = f"{binder.source}({binder.reason})" if binder.reason else binder.source
+            deciding = max(deciding, binder.priority)
 
     return Resolution(float(target), winner.source, bound_by, False, considered,
-                      winner_priority=winner.priority)
+                      winner_priority=winner.priority,
+                      deciding_priority=deciding)
 
 
 def resolve(claims: list, *, units=None, weights=None, live=None,
@@ -606,6 +659,12 @@ def resolve(claims: list, *, units=None, weights=None, live=None,
     written down.
     """
     site_claims = [c for c in claims if c.actuator == ACTUATOR_SITE]
+    # OPT-11: a mode claim on the site (N=1, where every source routes there)
+    # never enters stage 2's `lo > hi` test. It is applied after it, below, by
+    # the same release rule stage 3 uses.
+    site_modes = [c for c in site_claims if c.source == MODE_SOURCE]
+    if site_modes:
+        site_claims = [c for c in site_claims if c.source != MODE_SOURCE]
     if units is None:
         units = {c.actuator for c in claims if c.actuator != ACTUATOR_SITE}
     units = tuple(sorted(units))
@@ -617,6 +676,8 @@ def resolve(claims: list, *, units=None, weights=None, live=None,
     # STAGE 2 - the site claims become the grid target. At N=1 `site_claims` IS
     # `claims`, so this is the shipped arbiter on the shipped list.
     out = site_resolve(site_claims)
+    if site_modes:
+        _site_mode(out, site_modes, site_claims)
 
     # STAGE 3 - the seam, and since ALLOC-01 the allocator behind it.
     #
@@ -649,10 +710,125 @@ def resolve(claims: list, *, units=None, weights=None, live=None,
     # nothing. See `packshare.weights()` on the residual this leaves (the fill's
     # own direction can differ from the target's sign under a pin, in which case
     # the weighting is a worse preference and still cannot be unsafe).
+    # OPT-11: whether each unit's mode holds this tick (`_unit_modes()`).
+    # Before the weights, because a limit above the modes may move the target.
+    gate, held = _unit_modes(out, site_claims, bounds, live)
     if callable(weights):
         weights = weights(out.target_w)
+    if held:
+        weights = {u: (0.0 if u in held else
+                       (1.0 if weights is None else weights.get(u, 1.0)))
+                   for u in bounds}
     out.shares, out.allocated, out.allocation = allocate_record(
         out.target_w, bounds, weights=weights, live=live,
         scope_errors=out.scope_errors, site_priority=out.winner_priority,
-        tick=tick)
+        tick=tick, deciding_priority=gate)
     return out
+
+
+def _limits_above(site_claims: list, prio: int) -> tuple:
+    """OPT-11: `(lo, lo_src, hi, hi_src)` over the site LIMITs above `prio`.
+
+    These are what a mode may never take the site target outside of: the peak
+    guard (P_PEAK), maintenance shaping (P_MAINT_SHAPE) and the hard limits.
+    """
+    lo, hi = -inf, inf
+    lo_src = hi_src = None
+    for c in site_claims:
+        if c.kind != LIMIT or c.priority <= prio:
+            continue
+        if c.lo > lo:
+            lo, lo_src = c.lo, c
+        if c.hi < hi:
+            hi, hi_src = c.hi, c
+    return lo, lo_src, hi, hi_src
+
+
+def _yield_to(out: Resolution, t1: float, above: tuple):
+    """OPT-11: the target `t1` the modes allow, moved only as far as the limits
+    above the mode need (`_limits_above()`). Returns the claim that moved it,
+    or None when `t1` already satisfies them, and sets `out.target_w`."""
+    lo, lo_src, hi, hi_src = above
+    t2 = max(lo, min(hi, t1))
+    out.target_w = float(t2)
+    if t2 == t1:
+        return None
+    binder = lo_src if t2 == lo else hi_src
+    out.bound_by = (f"{binder.source}({binder.reason})" if binder.reason
+                    else binder.source)
+    out.deciding_priority = max(out.deciding_priority or binder.priority,
+                                binder.priority)
+    return binder
+
+
+def _site_mode(out: Resolution, modes: list, site_claims: list) -> None:
+    """OPT-11 at N=1: the one battery's mode bounds the SITE target, after stage 2.
+
+    A SET above the mode (a safety stop) decides alone. Otherwise the target is
+    clamped into the mode range and then back into the site limits above the
+    mode, so the mode gives way only as far as those limits need: a peak floor
+    of 2000 W over an Off battery asks it for 2000 W, whether a trade or the
+    loop won stage 2, and a charge the peak guard merely caps stays at 0 W. A
+    range without 0 W is a software fault that drops the mode
+    (`out.mode_fault`). Clamping one number cannot contradict anything.
+    """
+    out.considered = out.considered + [f"{c.source}:{c.kind}" for c in modes]
+    lims = [c for c in modes if c.kind == LIMIT]
+    if not lims or out.contradiction:
+        return
+    lo = max(c.lo for c in lims)
+    hi = min(c.hi for c in lims)
+    prio = min(c.priority for c in lims)
+    if not (lo <= 0.0 <= hi):
+        out.mode_fault = f"mode range [{lo:.0f}, {hi:.0f}] leaves out 0 W"
+        return
+    if out.winner_priority is not None and out.winner_priority > prio:
+        return
+    before = out.target_w
+    t1 = max(lo, min(hi, before))
+    if _yield_to(out, t1, _limits_above(site_claims, prio)) is None \
+            and t1 != before:
+        c = lims[0]
+        out.bound_by = f"{c.source}({c.reason})" if c.reason else c.source
+
+
+def _unit_modes(out: Resolution, site_claims: list, bounds: dict, live):
+    """OPT-11 at N>1: `(gate, held)` for stage 3.
+
+    `gate` is the `deciding_priority` handed to the allocator: None applies
+    every unit's mode, a number above P_MODE releases them. `held` is the set
+    of units whose mode holds them back in the target's direction; while the
+    modes are released they weigh 0, so they carry only what the other units
+    cannot (the allocator's last-resort pass).
+
+    The rule matches N=1: a SET above the mode decides alone. Otherwise the
+    target is clamped into what the units can place with their modes
+    (`allocator.loop_bound()`) and back into the site limits above the mode.
+    If that point is still placeable with the modes, they hold and the target
+    is unchanged (what they cannot place is reported unmet, as before). If a
+    limit above the mode needs more, the target moves only that far, and the
+    modes are released for it.
+    """
+    mode_units = [u for u, b in bounds.items()
+                  if getattr(b, "mode_priority", None) is not None]
+    if not mode_units or out.contradiction:
+        return out.deciding_priority, set()
+    prio = min(bounds[u].mode_priority for u in mode_units)
+    if out.winner_priority is not None and out.winner_priority > prio:
+        return out.deciding_priority, set()
+    clo, chi = allocator.loop_bound(bounds, live)
+    t1 = max(clo, min(chi, out.target_w))
+    before = out.target_w
+    binder = _yield_to(out, t1, _limits_above(site_claims, prio))
+    if binder is None:
+        out.target_w = float(before)
+        return None, set()
+    held = set()
+    for u in mode_units:
+        b = bounds[u]
+        nlo, nhi, note = allocator.unit_interval(b)
+        if note is not None:
+            continue
+        if (nhi < b.hi) if out.target_w > 0 else (nlo > b.lo):
+            held.add(u)
+    return binder.priority, held

goodwe_controller/app/control.py

@@ -17,6 +17,7 @@ exists because its absence produced a specific, observed failure.
 """
 
 import math
+from math import inf
 from dataclasses import dataclass
 
 # ---------------------------------------------------------------------------
@@ -293,6 +294,10 @@ REFUSED_BELOW_W = PROBE_ANSWER_W
 PROBE_EVERY_S = 900.0
 PROBE_S = 34.0
 
+# OPT-11. The loop's reason when the battery modes, not the meter, set the
+# command: every battery that may move this way is at its mode's limit.
+MODE_BOUND = "mode-bound"
+
 
 @dataclass(frozen=True)
 class Tuning:
@@ -475,6 +480,7 @@ def compute(
     i_w: float | None = None,
     refused: int | None = None,
     probe: bool = False,
+    bound: tuple | None = None,
 ) -> Decision:
     """One control cycle. A cycle is one meter update (~5 s on a HomeWizard P1).
 
@@ -485,8 +491,24 @@ def compute(
     `refused`  SAFETY-52's carried refused direction, or None to leave it out
                (the `i_w=None` equivalence path does)
     `probe`    the caller's clock says a refused direction may try PROBE_W now
+    `bound`    OPT-11: `(lo, hi)`, what the batteries may place this tick with
+               their modes applied (`allocator.loop_bound()`), or None. See
+               MODE_BOUND below. None is the law as it was.
     """
     reason = "tracking"
+    # OPT-11: a bound that leaves out 0 W would FORCE a direction, which no
+    # mode may do. It is dropped rather than obeyed (a software fault, and
+    # main.py never builds one: every term of `loop_bound()` holds 0).
+    if bound is not None and not (bound[0] <= 0.0 <= bound[1]):
+        bound = None
+    # ...and a side of it that reaches the rail is left to the rail, so that
+    # SAFETY-03's `i_clamped` still fires when the loop winds into it. With
+    # every battery on, the bound IS the rail, and the law is exactly as it was.
+    if bound is not None:
+        _rail = min(tuning.max_w, tuning.max_w if tuning.integrator_max_w is None
+                    else tuning.integrator_max_w)
+        bound = (float(bound[0]) if bound[0] > -_rail else -inf,
+                 float(bound[1]) if bound[1] < _rail else inf)
 
     # --- saturation, WITH the duration term -------------------------------
     # Command and actual diverging means the inverter cannot follow - it is at
@@ -589,6 +611,15 @@ def compute(
         else:
             i_w = max(moved, i_w)
 
+    # OPT-11: the integrator does not wind past what the modes let the
+    # batteries place. Only a side tighter than the rail is left in `bound`
+    # (above), so this never takes SAFETY-03's `i_clamped` away from the rail.
+    if bound is not None:
+        held = max(float(bound[0]), min(float(bound[1]), i_w))
+        if held != i_w:
+            i_w = held
+            reason = MODE_BOUND
+
     # ⚠️ Applied EVERY cycle, frozen or not: the freeze is conditional, this
     # bound is not. It is what makes the worst-case unwind time finite and
     # knowable instead of a function of how long the error happened to stand.
@@ -796,6 +827,22 @@ def compute(
             target = refused * PROBE_W if probe and wants else 0.0
             reason = PROBING if probe and wants else REFUSED
 
+    # --- OPT-11: the command stays inside what the modes allow -------------
+    # Applied after the slew limit and the freeze, so a mode that closes drops
+    # the ask at once rather than one slew step per cycle. That moves no
+    # battery further than the allocator would: it places at most this bound
+    # when the loop decides. What it removes is the unmet part, which would
+    # otherwise hold `prev_w` away from `actual_w` and trip the saturation
+    # freeze on watts no battery was allowed to give.
+    if bound is not None:
+        inside = max(float(bound[0]), min(float(bound[1]), target))
+        if inside != target:
+            target = inside
+            reason = MODE_BOUND
+        # SAFETY-48's lead cap above may pull the integrator back toward the
+        # slewed command; what is CARRIED stays inside the bound too.
+        i_w = max(float(bound[0]), min(float(bound[1]), i_w))
+
     # --- quantise ----------------------------------------------------------
     # 10 W. The register is 1 W and the inverter reports at 1 W, but its
     # response lands on a coarser ladder (~17.6 W measured at ~900 W, consistent
@@ -803,6 +850,13 @@ def compute(
     # 10 W simply avoids a visible staircase on dashboards.
     step = max(1, int(tuning.step_w))
     target = round(target / step) * step
+    if bound is not None:
+        # OPT-11: rounding must not step outside the bound. The bound holds
+        # 0 W, so one step toward 0 is always inside it.
+        if target > bound[1]:
+            target -= step
+        elif target < bound[0]:
+            target += step
 
     return Decision(float(target), sat_count, frozen, reason, float(i_w),
                     i_clamped, clamped, float(i_bound_w), float(want),

goodwe_controller/app/homeview.py

@@ -9,8 +9,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". Battery modes (OPT-11) are not
-built, so nothing here invents a mode plan. Every sentence is in the words
+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
 section at the bottom and is held to STYLE.md by test_messages.py.
 """
 
@@ -19,6 +20,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 .price import Absence, Uncertainty, brussels
 from .static_tariff import static_plan
 from .tariff import BILLING_TZ
@@ -283,6 +285,8 @@ def trade_runs(c, plan, verdict, day0, day1, now, shadow):
             continue
         hrs = (end - pt.start).total_seconds() / 3600.0
         for i, inv in enumerate(c.inverters):
+            if _off(c, inv):
+                continue            # OPT-11: an Off battery does not trade
             kwh = inv.max_w / 1000.0 * hrs
             cap = inv.capacity_kwh
             if cap:
@@ -316,8 +320,8 @@ def maintenance_runs(c, day0, day1, now, shadow):
     waiting = []
     for i, (inv, m) in enumerate(zip(c.inverters, c.maints)):
         cfg = m.cfg
-        if not cfg.enabled:
-            continue
+        if not cfg.enabled or _off(c, inv):
+            continue            # OPT-11: no monthly cycle while it is off
         cap = inv.capacity_kwh
         if m.phase != M_IDLE:
             hours = _cycle_hours(m.phase, inv.soc, cap, cfg)
@@ -376,9 +380,10 @@ def _cycle_hours(phase, soc, cap_kwh, cfg):
 
 def peak_run(c, day0, day1, now, shadow, limit_w):
     """While the batteries hold the grid under the peak limit, one block for
-    the current 15-minute period on every battery."""
+    the current 15-minute period on every battery. An Off battery gets it
+    only while it gives power (OPT-11: Off covers only the shortfall)."""
     pg = c.peak_guard
-    if pg is None or not pg.engaged:
+    if not peak_engaged(c):
         return []
     start = now - timedelta(minutes=now.minute % 15, seconds=now.second,
                             microseconds=now.microsecond)
@@ -386,15 +391,17 @@ def peak_run(c, day0, day1, now, shadow, limit_w):
     return [_run(i, "peak", start, end, day0, day1,
                  run_peak_what(pg.ceiling_w or limit_w, shadow),
                  run_peak_why(), None)
-            for i in range(len(c.inverters))]
+            for i, inv in enumerate(c.inverters)
+            if not _off(c, inv) or flow(inv.batt) == "giving"]
 
 
-def house_runs(n, day0, day1, now, shadow):
-    """"Follows the house" for the rest of the day, drawn under the others."""
+def house_runs(n, day0, day1, now, shadow, skip=()):
+    """"Follows the house" for the rest of the day, drawn under the others.
+    `skip`: the batteries that are switched off (OPT-11)."""
     return [_run(i, "house", max(now, day0), day1, day0, day1,
                  run_house_what(shadow), run_house_why(shadow),
                  run_house_amount())
-            for i in range(n)]
+            for i in range(n) if i not in skip]
 
 
 def region_of(opts):
@@ -428,7 +435,8 @@ def build_plan(c, now, shadow, running, held=False, settled=True):
     # The control cycle trades on the fresh plan only, so this does too.
     verdict, trade_why = trade_verdict(c, fresh)
     if running:
-        runs += house_runs(len(c.inverters), day0, day1, now, shadow)
+        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:
             trade, later, no_trade = trade_runs(c, fresh, verdict, day0, day1,
                                                 now, shadow)
@@ -506,16 +514,57 @@ def at_zero(inv) -> bool:
     return inv.last_write is not None and abs(inv.last_write) < 1.0
 
 
+def _off(c, inv) -> bool:
+    """OPT-11: is this battery switched off? Only with battery modes on."""
+    return bool(getattr(c, "modes_on", False)) and not c.pack_mode(inv).use
+
+
+def refusing(c, inv) -> int:
+    """SAFETY-52/73: the direction this battery refuses (+1 give, -1 charge,
+    0 none). Per inverter at two or more, the site's own at one."""
+    if len(c.inverters) > 1:
+        return int(getattr(inv, "refused", 0) or 0)
+    return int(getattr(c, "batt_refused", 0) or 0)
+
+
+def peak_engaged(c) -> bool:
+    """The peak guard asks the batteries for power this cycle. Not when it is
+    blind or floor-limited: those are engaged with a 0 W floor (no charging
+    only), so no battery gives power for it."""
+    pg = getattr(c, "peak_guard", None)
+    return bool(pg is not None and pg.engaged and (pg.floor_w or 0.0) > 0.0)
+
+
 def battery_rows(c, shadow, running, held=False):
     shares = {}
     alloc = getattr(c, "allocation", None)
     if shadow and alloc is not None and getattr(alloc, "shares", None):
         shares = dict(alloc.shares)
+    modes_on = bool(getattr(c, "modes_on", False))
+    pms = {inv.name: c.pack_mode(inv) for inv in c.inverters} \
+        if modes_on else {}
+    peak = peak_engaged(c)
     rows = []
     for i, inv in enumerate(c.inverters):
         m = c.maints[i] if i < len(c.maints) else None
         phase = m.phase if m is not None else M_IDLE
         cap = inv.capacity_kwh
+        pm = pms.get(inv.name)
+        off = pm is not None and not pm.use
+        # UX-13 P3: does a Solar first battery that is on come before this one?
+        sf_ahead = any(o.use and o.mode == SOLAR_FIRST
+                       for n, o in pms.items() if n != inv.name)
+        # ...and does another battery refuse to give power, so this one
+        # 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)
+        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)
         rows.append({
             "name": inv.name,
             "level_pct": None if inv.soc is None else float(inv.soc),
@@ -529,13 +578,79 @@ def battery_rows(c, shadow, running, held=False):
             "now": battery_now(inv.soc, inv.batt, phase=phase, shadow=shadow,
                                running=running, held=held,
                                would_w=shares.get(inv.name),
-                               settled=at_zero(inv)),
-            # Per-battery reasons arrive with battery modes (OPT-11).
-            "why": None,
+                               settled=at_zero(inv), off=off, peak=peak),
+            # 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),
         })
+        if modes_on:
+            # OPT-11 P1: the battery's switch and mode, for the Batteries
+            # screen. Only with battery modes on, so the page is unchanged
+            # without them.
+            rows[-1].update({"use": pm.use, "mode_key": pm.key,
+                             "mode_choice": pm.mode,
+                             "mode": mode_word(pm.key)})
     return rows
 
 
+def battery_why(*, modes_on, mode, off, reading, phase, shadow, running,
+                held, refused, peak, sf_ahead, giving=False,
+                other_refuses=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:
+        return "no_reading"
+    if held:
+        return "held"
+    if not running:
+        return "stopped"
+    if shadow:
+        return "shadow"
+    if phase != M_IDLE:
+        return "cycle_mode" if modes_on else "cycle"
+    if off:
+        # Off gives way to the peak limit only (OPT-11 design section 2).
+        return "off_peak" if peak and giving else "off"
+    if refused:
+        return "refuses_give" if refused > 0 else "refuses_charge"
+    if peak:
+        return "peak"
+    if giving and other_refuses:
+        return "other_refuses"
+    if not modes_on:
+        return "modes_off"
+    if giving:
+        return "covers_house"      # both modes cover the house until P3
+    if mode == LEFTOVER_SOLAR:
+        return "leftover" if sf_ahead else "leftover_alone"
+    return "solar_first"
+
+
+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."""
+    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"],
+                         "what": r["what"]} for r in mine]
+        if mine:
+            row["today_line"] = ""
+        elif held:
+            row["today_line"] = today_words("held")
+        elif not running:
+            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")
+        else:
+            row["today_line"] = today_words("house_would" if shadow
+                                            else "house")
+
+
 # Row id -> the DOCS.md heading under Notifications, where one exists.
 ATTN_DOCS = {
     "meter_frozen": messages.T_METER_FROZEN,
@@ -631,6 +746,11 @@ def _build(c, *, level, checks, now):
     running = (bool(c.auto) or shadow) and not held
     settled = all(at_zero(inv) for inv in c.inverters)
     ctl = next((r for r in checks if r.get("id") == "controller"), None)
+    rows = battery_rows(c, shadow, running, held)
+    plan = build_plan(c, now, shadow, running, held=held, settled=settled)
+    attach_today(rows, plan["runs"],
+                 modes_on=bool(getattr(c, "modes_on", False)),
+                 running=running, held=held, shadow=shadow)
     return {
         "state": {"kind": kind, "pill": pill(kind),
                   "ran": ctl.get("text", "") if ctl else "",
@@ -638,9 +758,9 @@ def _build(c, *, level, checks, now):
         "now": now_block(grid_w=c.grid, pv_w=c.pv_w, batt_w=c.site_batt_w,
                          has_solar=bool(c.pv_roster), shadow=shadow,
                          settled=settled),
-        "batteries": battery_rows(c, shadow, running, held),
-        "plan": build_plan(c, now, shadow, running, held=held,
-                           settled=settled),
+        "batteries": rows,
+        "plan": plan,
+        "modes_on": bool(getattr(c, "modes_on", False)),
         "attention": ([{"severity": INFO, "id": "shadow",
                          "title": attn_shadow(), "body": attn_shadow_body(),
                          "docs": None}] if shadow else []) + attention(checks),
@@ -723,6 +843,11 @@ def mode_house() -> str:
     return _t("mode_house")
 
 
+def mode_word(key) -> str:
+    """OPT-11: a battery's mode, or Off, in the page's language."""
+    return _t("modes." + key)
+
+
 def attn_shadow() -> str:
     return _t("attn_shadow")
 
@@ -797,7 +922,7 @@ def tile_batt(batt_w, shadow, settled=True) -> str:
 
 
 def battery_now(soc, batt_w, *, phase, shadow, running, held=False,
-                would_w=None, settled=True) -> str:
+                would_w=None, settled=True, off=False, peak=False) -> str:
     if soc is None or batt_w is None:
         return _t("now.no_reading")
     zero = _zero(settled)
@@ -814,6 +939,14 @@ def battery_now(soc, batt_w, *, phase, shadow, running, held=False,
         return _t("now." + {M_DRAIN: "cycle_drain", M_CHARGE: "cycle_charge",
                             M_HOLD: "cycle_hold"}.get(phase, "cycle"))
     st = flow(batt_w)
+    if off:
+        # OPT-11: an Off battery is asked for 0 W, but the peak limit may
+        # still need it. Say which, and never "0 W" beside a power figure.
+        if st == "resting":
+            return _t("now.off_resting")
+        if st == "giving" and peak:
+            return _t("now.off_peak", kw=_kw(batt_w))
+        return _t("now.off_going", kw=_kw(batt_w))
     if st == "giving":
         return _t("now.giving", kw=_kw(batt_w))
     if st == "charging":
@@ -821,6 +954,17 @@ def battery_now(soc, batt_w, *, phase, shadow, running, held=False,
     return _t("now.resting")
 
 
+def why_words(key, name=None) -> 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 "")
+
+
+def today_words(key) -> str:
+    """One battery's "today" line when the plan has no run for it."""
+    return _t("today." + key)
+
+
 def plan_head(key, shadow, settled=True) -> str:
     if key == "held":
         return _t("head.held" if settled else "head.held_going")
@@ -964,6 +1108,7 @@ def _samples() -> list:
     out = [("title", t) for t in words["verdict"].values()]
     out += [("title", _t("zero_going")), ("title", _t("zero_held"))]
     out += [("title", t) for t in words["attn"].values()]
+    out += [("title", mode_word(k)) for k in words["modes"]]
     out += [("title", mode_house()), ("title", attn_shadow()),
             ("line", attn_shadow_body())]
     for k in ("running", "shadow", "stopped", "alarm", "warning"):
@@ -1024,6 +1169,14 @@ def _samples() -> list:
             ("plan", line_region("flanders", 2026)),
             ("plan", line_region("own", None)),
             ("plan", line_peak_not_covered())]
+    for off in (False, True):
+        for peak in (False, True):
+            for w in (2500, -2500, 0, 500):
+                out.append(("plan", battery_now(62, w, phase=M_IDLE,
+                                                shadow=False, running=True,
+                                                off=off, peak=peak)))
+    out += [("plan", why_words(k, name="Battery A")) for k in words["why"]]
+    out += [("plan", today_words(k)) for k in words["today"]]
     out += [("plan", line_no_trade(k)) for k in
             ("not_covered", "no_prices", "peak", "not_firm", "not_worth",
              "no_level")]

goodwe_controller/app/main.py

@@ -37,9 +37,11 @@ import aiohttp
 
 from . import arbitrage
 from .arbiter import (
-    P_LOOP, P_MAINT_SHAPE, P_MAINTENANCE, P_PEAK, P_SAFETY,
-    Claim, Resolution, actuator_for, resolve,
+    P_LOOP, P_MAINT_SHAPE, P_MAINTENANCE, P_MODE, P_PEAK, P_SAFETY,
+    Claim, Resolution, actuator_for, pre_resolve, resolve,
 )
+from . import allocator
+from . import packmode
 from . import control as _ctl
 from .control import Tuning, compute, maintenance_charge_floor, peak_at_risk
 from .delivery import (
@@ -67,10 +69,12 @@ 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, arbitrate as maint_arbitrate,
+    IDLE, POWER_MOVING, MaintConfig, Maintenance, MaintResult,
+    arbitrate as maint_arbitrate,
 )
-from .mqtt import (MqttPublisher, announced_units, optional_keys, unit_slugs,
-                   unit_state_key)
+from .mqtt import (MODE_CONFIGS_KEY, MODE_LABELS, USE_OFF, USE_ON,
+                   MqttPublisher, announced_units, mode_configs,
+                   optional_keys, parse_command, unit_slugs, unit_state_key)
 from . import peakguard
 from . import packshare
 from . import pv as pv_read
@@ -890,10 +894,24 @@ 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
         self._peak_floor_limited = False
         self._maint_shape_suspended = False
+        # OPT-11. Battery modes, off by default so an install that has not
+        # turned them on behaves exactly as before (SAFETY-10 section 1). Each
+        # battery's mode and on/off switch live in the store, not in options,
+        # so a change applies at once (`pack_use`, `pack_mode` actions).
+        self.modes_on = packmode.enabled(opts)
+        # The units whose mode fault is logged already (edge-logged).
+        self._mode_faults = set()
+        # 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 = []
@@ -1813,6 +1831,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.
 
@@ -1953,7 +1976,162 @@ class Controller:
         that have nothing to do with the allocator, and a weighting held from
         construction prefers a pack that has since emptied.
         """
-        return packshare.weights(self.pack_energy, target_w)
+        base = packshare.weights(self.pack_energy, target_w)
+        if not self.modes_on:
+            return base
+        # 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)
+
+    def pack_mode(self, inv) -> "packmode.PackMode":
+        """OPT-11. This battery's on/off switch and mode, read from the store."""
+        return packmode.read(getattr(self.store, "data", None) or {}, inv.name)
+
+    def pack_modes(self) -> dict:
+        return {inv.name: self.pack_mode(inv) for inv in self.inverters}
+
+    def loop_bound(self, claims):
+        """OPT-11. `(lo, hi)`: what the batteries may place if the loop decides.
+
+        The sum over live units of each unit's hard limits with its mode
+        applied (`allocator.loop_bound()`), from THIS cycle's unit claims. At
+        one inverter every claim is on the site, so it is the mode range
+        itself, or None when no mode is filed (maintenance) or the range
+        leaves out 0 W (a fault `resolve()` reports).
+        """
+        if len(self.inverters) <= 1:
+            modes = [c for c in claims if c.source == "mode"]
+            if not modes:
+                return None
+            lo = max(c.lo for c in modes)
+            hi = min(c.hi for c in modes)
+            return (lo, hi) if lo <= 0.0 <= hi else None
+        bounds = {u: pre_resolve([c for c in claims if c.actuator == u])
+                  for u in self.units}
+        return allocator.loop_bound(bounds, live=self.live_units())
+
+    def _mode_fault_log(self, resolution) -> None:
+        """OPT-11: say once, per battery, that its mode was dropped as a fault.
+
+        A mode range without 0 W would force a direction, which no mode may do,
+        so it is never applied (allocator.unit_interval()). main.py never
+        builds one; this is the line that says so if it ever does.
+        """
+        alloc = resolution.allocation
+        now = {u for u, _ in getattr(alloc, "mode_faults", ())}
+        if resolution.mode_fault is not None and self.inverters:
+            now.add(self.inverters[0].name)
+        for inv in self.inverters:
+            if inv.name in now and inv.name not in self._mode_faults:
+                _LOG.error("Battery mode ignored for %s. Software fault "
+                           "MODE_RANGE.", inv.name)
+                self.log_event(f"battery mode ignored on {inv.name}, a "
+                               f"software fault", hint=messages.hint(
+                                   "mode_fault", unit=inv.name))
+        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.
+
+        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
+        its maintenance cycle (the owner's 2026-09-27 answer). Refused, with a
+        plain reason, while battery modes are off or for an unknown battery or
+        value.
+        """
+        if not self.modes_on:
+            return {"error": messages.pack_refused("off")}
+        inv = next((i for i in self.inverters if i.name == unit), None)
+        if inv is None:
+            return {"error": messages.pack_refused("unit")}
+        if what == "pack_use":
+            if not isinstance(value, bool):
+                return {"error": messages.pack_refused("value")}
+            inv.store_set(packmode.USE_KEY, value)
+            self.log_event(f"{inv.name} switched {'on' if value else 'off'} "
+                           f"by operator",
+                           hint=messages.hint("pack_on" if value
+                                              else "pack_off", unit=inv.name))
+            if not value:
+                self._maint_stop_off(self.maints[self.inverters.index(inv)],
+                                     now)
+        else:
+            if value not in packmode.MODES:
+                return {"error": messages.pack_refused("value")}
+            inv.store_set(packmode.MODE_KEY, value)
+            self.log_event(f"{inv.name} mode set to {value.replace('_', ' ')} "
+                           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}
+
+    def mode_values(self) -> dict:
+        """OPT-11 P2: each battery's mode and switch, for their HA state
+        topics. Read from the store, so they are right after a restart. Empty
+        while battery modes are off."""
+        if not self.modes_on:
+            return {}
+        out = {}
+        names = [inv.name for inv in self.inverters]
+        for inv, slug in zip(self.inverters, unit_slugs(names)):
+            pm = self.pack_mode(inv)
+            out[unit_state_key(slug, "mode")] = MODE_LABELS.get(pm.mode,
+                                                               pm.mode)
+            out[unit_state_key(slug, "use")] = USE_ON if pm.use else USE_OFF
+        return out
+
+    async def mqtt_command(self, topic, payload, retained) -> None:
+        """OPT-11 P2: one command from a battery's HA switch or mode list.
+
+        It goes through handle_action(), the page's /action path, so the
+        checks and the store write are the same. A retained command (one the
+        broker replays on subscribe, e.g. after a restart) is never applied:
+        the store already holds the last choice. A refusal is logged once per
+        topic and reason, at most 32, and further refusals are counted in the
+        log at 1, 10, 100 and so on. Never raises: MQTT must not reach control.
+        """
+        try:
+            slug, action, value, why = parse_command(
+                topic, payload, retained, packmode.MODES)
+            if why is None:
+                names = [inv.name for inv in self.inverters]
+                unit = dict(zip(unit_slugs(names), names)).get(slug)
+                result = await self.handle_action(action, unit=unit,
+                                                  value=value)
+                if not (isinstance(result, dict) and "error" in result):
+                    self.mqtt.publish(self.mode_values())
+                    return
+                why = result["error"]
+            else:
+                why = messages.pack_refused(why)
+            # Printable only: a topic is sender-chosen, so no log injection.
+            topic_s = "".join(c if c.isprintable() else "?"
+                              for c in str(topic)[:128])
+            _LOG.debug("Home Assistant command %s %s refused: %s", topic_s,
+                       repr(payload)[:48], why)
+            if (topic_s, why) in self._mqtt_refused \
+                    or len(self._mqtt_refused) >= 32:
+                # Not logged again, but counted: 1, 10, 100... stay visible.
+                self._mqtt_refused_more += 1
+                more = self._mqtt_refused_more
+                if str(more).rstrip("0") == "1":
+                    _LOG.warning("Home Assistant commands still ignored: %d "
+                                 "more so far.", more)
+                return
+            self._mqtt_refused.add((topic_s, why))
+            _LOG.warning("Home Assistant command on %s ignored: %s", topic_s,
+                         why)
+        except Exception:                               # noqa: BLE001
+            _LOG.exception("Home Assistant command could not be handled")
+
+    def _maint_stop_off(self, machine, now) -> None:
+        """OPT-11: stop this battery's maintenance cycle because it is off."""
+        if machine.phase == IDLE:
+            return
+        for msg in machine.abort(now, "battery switched off"):
+            self.log_event(msg, hint=messages.hint("maint_off",
+                                                   unit=machine.name))
 
     @property
     def why_words(self) -> str:
@@ -2696,9 +2874,27 @@ class Controller:
         # Calling `tick()` without the answer this produced is the
         # two-packs-draining-at-once defect with the interlock present but not
         # wired, which is why the plan is built here and not inside the loop.
-        maint_plan = maint_arbitrate(self.maints, now)
+        # OPT-11: a battery switched off starts no cycle and is left out of the
+        # slot, so it cannot hold the slot from a battery that is on. One that
+        # is mid-cycle is stopped, with a log line (the owner's 2026-09-27
+        # answer). The switch itself stops it at once (`pack_use`); this is
+        # the same rule for a store that says Off at start-up.
+        _off = ({inv.name for inv in self.inverters
+                 if not self.pack_mode(inv).use} if self.modes_on else set())
+        for inv, machine in zip(self.inverters, self.maints):
+            if inv.name in _off:
+                self._maint_stop_off(machine, now)
+        _on = [m for inv, m in zip(self.inverters, self.maints)
+               if inv.name not in _off]
+        _plan_on = iter(maint_arbitrate(_on, now) if _off
+                        else maint_arbitrate(self.maints, now))
+        maint_plan = [None if inv.name in _off else next(_plan_on)
+                      for inv, _m in zip(self.inverters, self.maints)]
         maint_results = []
         for inv, machine, blocked in zip(self.inverters, self.maints, maint_plan):
+            if blocked is None:
+                maint_results.append(MaintResult(IDLE, False, None, False, []))
+                continue
             res = machine.tick(now, inv.soc, blocked_by=blocked)
             for msg in res.events:
                 self.log_event(msg, hint=messages.hint("maintenance",
@@ -3266,6 +3462,7 @@ class Controller:
             # 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
@@ -3526,8 +3723,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.
@@ -3554,7 +3750,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 -
@@ -3564,6 +3760,23 @@ class Controller:
                                               actuator=self.actuator_of("maintenance",
                                                                         inv)))
 
+        # --- OPT-11: each battery's mode, a soft unit limit at P_MODE ---------
+        # Filed only with battery modes on, and never on a battery in any
+        # maintenance phase: maintenance at 60/40 outranks the mode. The range
+        # always holds 0 W (packmode.mode_range()). pre_resolve() keeps it
+        # 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()).
+        if self.modes_on:
+            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)
+                claims.append(Claim.limit("mode", P_MODE, lo, hi, pm.key,
+                                          actuator=self.actuator_of("mode",
+                                                                    inv)))
+
         # --- the grid-following loop -----------------------------------------
         # ⚠️ SAFETY-10: `or self.shadow`. The loop is the leg a shadow run most
         # needs and the one that is switched off by `auto_start: false`, so
@@ -3588,6 +3801,28 @@ class Controller:
             self._unit_refusals()
             _probing = {inv.name: self._unit_probe(inv)
                         for inv in self.inverters if inv.refused}
+        # --- SAFETY-73: each refusing unit's own P_SAFETY claim ---------------
+        # A hard unit limit that always intersects (OPT-11's P_MODE layer sits
+        # inside it): closed in the refused direction, so the allocator hands
+        # the share to the others within their own limits. During its probe it
+        # is a pin at PROBE_W and the others carry the rest. Filed here, before
+        # the loop, so OPT-11's loop bound sees it. Unit claims only, and still
+        # the last unit claims filed, so every unit's claim order is as before.
+        for inv in self.inverters:
+            if not inv.refused:
+                continue
+            if _probing.get(inv.name):
+                claims.append(Claim.set("refused", P_SAFETY,
+                                        inv.refused * _ctl.PROBE_W,
+                                        _ctl.PROBING,
+                                        actuator=self.actuator_of("refused",
+                                                                  inv)))
+            else:
+                claims.append(Claim.limit("refused", P_SAFETY,
+                                          *_refused_interval(inv.refused),
+                                          _ctl.REFUSED,
+                                          actuator=self.actuator_of("refused",
+                                                                    inv)))
         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
@@ -3649,6 +3884,9 @@ class Controller:
                 refused=self.batt_refused if len(self.inverters) == 1
                 else self._site_refused(),
                 probe=probe,
+                # OPT-11: None unless battery modes are on, which is the law
+                # exactly as it was.
+                bound=self.loop_bound(claims) if self.modes_on else None,
             )
             if decision.frozen and self.sat_count < self.tuning.saturation_cycles:
                 self.log_event(f"saturation freeze ({self.target:.0f} W vs "
@@ -3757,26 +3995,6 @@ class Controller:
         # ability to DELIVER rests on this argument - a weight cannot stop a
         # unit being commanded and cannot move a failing unit's load to its
         # sibling. The `pack` claim filed above is the half that constrains.
-        # --- SAFETY-73: each refusing unit's own P_SAFETY claim ---------------
-        # A hard unit limit that always intersects (OPT-11's P_MODE layer sits
-        # inside it): closed in the refused direction, so the allocator hands
-        # the share to the others within their own limits. During its probe it
-        # is a pin at PROBE_W and the others carry the rest.
-        for inv in self.inverters:
-            if not inv.refused:
-                continue
-            if _probing.get(inv.name):
-                claims.append(Claim.set("refused", P_SAFETY,
-                                        inv.refused * _ctl.PROBE_W,
-                                        _ctl.PROBING,
-                                        actuator=self.actuator_of("refused",
-                                                                  inv)))
-            else:
-                claims.append(Claim.limit("refused", P_SAFETY,
-                                          *_refused_interval(inv.refused),
-                                          _ctl.REFUSED,
-                                          actuator=self.actuator_of("refused",
-                                                                    inv)))
         _live = self.live_units()
         while True:
             resolution = resolve(claims, units=self.units, live=_live,
@@ -3796,6 +4014,8 @@ class Controller:
                     *_refused_interval(1 if claims[k].value > 0 else -1),
                     _ctl.REFUSED, actuator=claims[k].actuator)
         self.allocation = resolution.allocation
+        if self.modes_on:
+            self._mode_fault_log(resolution)
         # --- THE TWO REFUSALS, AND THEY ARE NOT THE SAME REFUSAL --------------
         # Both do the same thing - REPLACE the resolution with a 0 W failsafe
         # which is then written like any other cycle at
@@ -4996,6 +5216,8 @@ class Controller:
             values[unit_state_key(slug, "soc")] = inv.soc
             values[unit_state_key(slug, "sign_latch")] = (
                 "tripped" if inv.sign_wd.tripped else "clear")
+        # OPT-11 P2: each battery's mode and switch; nothing while modes are off.
+        values.update(self.mode_values())
         self.mqtt.publish(values)
 
     async def shutdown(self) -> None:
@@ -5743,8 +5965,10 @@ class Controller:
             out["home_error"] = True
         return out
 
-    async def handle_action(self, what: str):
+    async def handle_action(self, what: str, *, unit=None, value=None):
         now = datetime.now(timezone.utc)
+        if what in ("pack_use", "pack_mode"):
+            return self._pack_action(what, unit, value, now)
         if what == "auto_toggle":
             self.auto = not self.auto
             self.store.set("auto", self.auto)
@@ -5909,6 +6133,21 @@ class ControlTaskDied(RuntimeError):
     """The control task ended while nothing had asked it to stop."""
 
 
+def mode_announcement(opts, store) -> tuple:
+    """OPT-11 P2: `(modes, retract)` for the MQTT publisher at start-up.
+
+    The config topics announced are kept in the store, so turning modes off
+    removes exactly those (`mqtt.mode_configs()`). An install that never
+    turned modes on gets nothing, and its store is not written.
+    """
+    modes = packmode.MODES if packmode.enabled(opts) else ()
+    stored = store.data.get(MODE_CONFIGS_KEY)
+    keep, retract = mode_configs(roster_names(opts), modes, stored)
+    if keep and keep != stored:
+        store.set(MODE_CONFIGS_KEY, keep)
+    return modes, retract
+
+
 def control_task_done(task: asyncio.Task, *, controller, stop: asyncio.Event,
                       died: list) -> None:
     """Done-callback on the control task: log its death now and wake amain()
@@ -6039,6 +6278,9 @@ async def amain() -> None:
         # took the control loop down with it.
         broker = None
         try:
+            # OPT-11 P2: each battery's switch and mode list, only while
+            # battery modes are on (`mode_announcement()`).
+            _modes, _retract = mode_announcement(opts, store)
             broker = await hass.mqtt_service()
             pub = MqttPublisher(
                 broker.get("host") if broker else None,
@@ -6058,6 +6300,8 @@ async def amain() -> None:
                 # is what `build_roster()` itself reads. At a roster of one this
                 # announces nothing new - see `announced_units()`.
                 units=roster_names(opts),
+                modes=_modes,
+                retract=_retract,
             )
         except Exception as err:  # noqa: BLE001
             _LOG.warning("MQTT unavailable (%s) - continuing without status entities", err)
@@ -6071,6 +6315,8 @@ async def amain() -> None:
 
         stop = asyncio.Event()
         controller = Controller(opts, hass, store, pub, stop=stop)
+        if callable(getattr(pub, "bind", None)):
+            pub.bind(asyncio.get_running_loop(), controller.mqtt_command)
         runner = await web.start(controller, port=INGRESS_PORT)
 
         loop = asyncio.get_running_loop()

goodwe_controller/app/messages.py

@@ -919,9 +919,31 @@ HINTS = {
     "not_delivering_cleared": "{unit}: not-delivering alarm cleared",
     "maintenance": "Battery maintenance: {phase}",
     "maint_paused": "Maintenance charging paused to stay under the peak limit",
+    "pack_on": "{unit}: battery switched on",
+    "pack_off": "{unit}: battery switched off, it is asked for 0 W",
+    "pack_mode": "{unit}: battery mode changed",
+    "maint_off": "{unit}: maintenance stopped, the battery is switched off",
+    "mode_fault": "{unit}: battery mode ignored because of a software fault",
 }
 
 
+# OPT-11: why a battery switch or mode change was refused (the page shows it).
+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 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.",
+    "encoding": "That command is not plain text.",
+    "topic": "That is not a battery command.",
+}
+
+
+def pack_refused(why: str) -> str:
+    return PACK_REFUSED[why]
+
+
 def hint(key: str, **kw) -> str:
     """The plain words for one event. `w` is formatted as watts, `sw` as
     watts with their sign (positive gives power, negative charges)."""
@@ -1135,6 +1157,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/mqtt.py

@@ -7,8 +7,10 @@ That separation is deliberate; observability must never be able to take down
 control.
 """
 
+import asyncio
 import json
 import logging
+import re
 
 try:
     import paho.mqtt.client as mqtt
@@ -375,7 +377,26 @@ def _payload(name, object_id, unique_id, state_topic, device,
     return cfg
 
 
-def discovery_payloads(units=(), omit=(), include=()) -> list:
+def unit_unique_id(slug: str, key: str) -> str:
+    """One unit's entity `unique_id` (also its config topic's middle part)."""
+    return f"{BASE}_unit_{slug}_{key}"
+
+
+def _unit_places(names):
+    """`(slug, device, prefix)` for each roster name, in order."""
+    slugs = unit_slugs(names)
+    for i, (name, slug) in enumerate(zip(names, slugs)):
+        # ⚠️ `i == 0` IS THE ASYMMETRY, IN ONE LINE. The first roster entry
+        # keeps the device it already has and carries its name in the ENTITY
+        # name instead; every later one gets its own device and does not.
+        # Either way HA composes device-name + entity-name into the same
+        # string, which is why `object_id` can be written once for both.
+        device = DEVICE if i == 0 else unit_device(name, slug)
+        prefix = f"{_title(name)} " if i == 0 else ""
+        yield slug, device, prefix
+
+
+def discovery_payloads(units=(), omit=(), include=(), modes=()) -> list:
     """Every `(topic, payload)` this add-on announces, in announcement order.
 
     Split out of `_announce()` so that the acceptance criterion can be graded as
@@ -389,6 +410,8 @@ def discovery_payloads(units=(), omit=(), include=()) -> list:
     the output here (`_payload()`'s note, and test_mqtt.py part 1 asserts an
     ordered LIST precisely because a re-order is a zero-byte edit that
     re-announces every entity on a live install).
+
+    `modes` (OPT-11 P2) is the battery modes offered, empty when they are off.
     """
     omit = set(omit)
     include = [k for k in include if k not in omit]
@@ -400,19 +423,10 @@ def discovery_payloads(units=(), omit=(), include=()) -> list:
             f"homeassistant/sensor/{BASE}_{key}/config",
             _payload(name, object_id, f"{BASE}_{key}", f"{BASE}/{key}",
                      DEVICE, unit, dev_class, state_class, icon)))
-    names = announced_units(units)
-    slugs = unit_slugs(names)
     site_slug = _slug(DEVICE["name"])
-    for i, (name, slug) in enumerate(zip(names, slugs)):
-        # ⚠️ `i == 0` IS THE ASYMMETRY, IN ONE LINE. The first roster entry
-        # keeps the device it already has and carries its name in the ENTITY
-        # name instead; every later one gets its own device and does not.
-        # Either way HA composes device-name + entity-name into the same
-        # string, which is why `object_id` below can be written once for both.
-        device = DEVICE if i == 0 else unit_device(name, slug)
-        prefix = f"{_title(name)} " if i == 0 else ""
+    for slug, device, prefix in _unit_places(announced_units(units)):
         for key, oid, label, unit, dev_class, state_class, icon in UNIT_SENSORS:
-            unique_id = f"{BASE}_unit_{slug}_{key}"
+            unique_id = unit_unique_id(slug, key)
             out.append((
                 f"homeassistant/sensor/{unique_id}/config",
                 _payload(prefix + label,
@@ -427,12 +441,134 @@ def discovery_payloads(units=(), omit=(), include=()) -> list:
             f"homeassistant/sensor/{BASE}_{key}/config",
             _payload(name, object_id, f"{BASE}_{key}", f"{BASE}/{key}",
                      DEVICE, unit, dev_class, state_class, icon)))
+    # OPT-11 P2: last, and only when battery modes are on.
+    out.extend(mode_payloads(units, modes))
     return out
 
 
+# --- OPT-11 P2: each battery's switch and mode, as HA entities ---------------
+# Announced only when battery modes are on, after every other row, so no
+# existing row moves. A command goes through Controller.handle_action(), the
+# page's /action path. DECISIONS/OPT-11-battery-modes.md has the record.
+#
+# 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"}
+USE_ON, USE_OFF = "ON", "OFF"
+# A longer command payload is refused before it is decoded.
+MAX_COMMAND_BYTES = 64
+# The store key holding the mode config topics last announced, so that turning
+# modes off can remove exactly those (an empty retained config) and an install
+# that never turned them on publishes nothing new.
+MODE_CONFIGS_KEY = "mqtt_mode_configs"
+_MODE_CONFIG_RE = re.compile(
+    rf"homeassistant/(select|switch)/{BASE}_unit_[a-z0-9_]+_(mode|use)/config")
+_COMMAND_RE = re.compile(rf"{BASE}/unit/([a-z0-9_]+)/(mode|use)/set")
+# (entity key, HA component, entity name, icon)
+MODE_ENTITIES = [
+    ("mode", "select", "Mode", "mdi:battery-sync"),
+    ("use", "switch", "Use", "mdi:power"),
+]
+
+
+def mode_payloads(units, modes) -> list:
+    """The `(topic, payload)` for each battery's select and switch.
+
+    Every roster entry gets them, also at a roster of one. The device rule is
+    TEL-07's: the first battery's rows go on the site device with its name in
+    front, each later battery's on its own device. Empty when `modes` is empty.
+    """
+    if not modes:
+        return []
+    site_slug = _slug(DEVICE["name"])
+    options = [MODE_LABELS[m] for m in modes]
+    out = []
+    for slug, device, prefix in _unit_places([str(u) for u in units]):
+        for key, component, label, icon in MODE_ENTITIES:
+            unique_id = unit_unique_id(slug, key)
+            state = f"{BASE}/{unit_state_key(slug, key)}"
+            cfg = {
+                "name": prefix + label,
+                "object_id": f"{site_slug}_{slug}_{key}",
+                "unique_id": unique_id,
+                "state_topic": state,
+                "command_topic": f"{state}/set",
+            }
+            if component == "select":
+                cfg["options"] = options
+            else:
+                cfg["payload_on"] = USE_ON
+                cfg["payload_off"] = USE_OFF
+            # HA sends commands unretained; a retained one is ignored anyway.
+            cfg["retain"] = False
+            cfg["availability_topic"] = AVAILABILITY
+            cfg["device"] = device
+            cfg["icon"] = icon
+            out.append((f"homeassistant/{component}/{unique_id}/config", cfg))
+    return out
+
+
+def mode_retractions(stored, current) -> list:
+    """Config topics announced before and not now: each gets an empty
+    retained config, which removes the entity from HA. Anything in the store
+    that is not one of our mode config topics is ignored."""
+    if not isinstance(stored, list):
+        return []
+    keep = set(current)
+    return list(dict.fromkeys(t for t in stored if isinstance(t, str)
+                              and _MODE_CONFIG_RE.fullmatch(t)
+                              and t not in keep))
+
+
+def mode_configs(units, modes, stored) -> tuple:
+    """`(keep, retract)` at start-up: the mode config topics to store, and the
+    ones to remove now. A removal stays in `keep`, so a start with no broker
+    does not forget it; resending an empty config is harmless."""
+    current = [t for t, _ in mode_payloads(units, modes)]
+    retract = mode_retractions(stored, current)
+    return current + retract, retract
+
+
+def parse_command(topic, payload, retained, modes):
+    """`(slug, action, value, reject)` for one message on a command topic.
+
+    `action` is `pack_use` or `pack_mode`. `value` is what /action would be
+    sent: a bool for the switch, a mode key for the select, or None for a
+    payload that is neither (the store path then refuses it). `reject` is a
+    reason when the message is dropped here: replayed by the broker (retained),
+    too long, not UTF-8, or not a command topic.
+    """
+    m = _COMMAND_RE.fullmatch(topic) if isinstance(topic, str) else None
+    if m is None:
+        return None, None, None, "topic"
+    slug, key = m.group(1), m.group(2)
+    action = "pack_use" if key == "use" else "pack_mode"
+    if retained:
+        return slug, action, None, "retained"
+    if not isinstance(payload, (bytes, bytearray)) \
+            or len(payload) > MAX_COMMAND_BYTES:
+        return slug, action, None, "size"
+    try:
+        text = bytes(payload).decode("utf-8")
+    except UnicodeDecodeError:
+        return slug, action, None, "encoding"
+    if key == "use":
+        value = {USE_ON: True, USE_OFF: False}.get(text)
+    else:
+        value = next((k for k in modes if MODE_LABELS.get(k) == text), None)
+    return slug, action, value, None
+
+
 class MqttPublisher:
+    # OPT-11 P2. Class defaults, so a publisher built without them (and every
+    # test fixture that builds one with __new__) behaves as before.
+    modes = ()
+    retract = ()
+    _loop = None
+    _handler = None
+
     def __init__(self, host, port, username=None, password=None, omit=(),
-                 units=(), include=()):
+                 units=(), include=(), modes=(), retract=()):
         # `omit` drops sensor keys from discovery entirely. ⚠️ Announcing a
         # sensor that nothing will ever publish to is not harmless here:
         # p1_sample_age_s is a watchdog input, and an entity that exists but is
@@ -448,6 +584,10 @@ class MqttPublisher:
         # second reading of the option. Defaults to empty, so a caller that has
         # not been taught about it announces exactly what it announced before.
         self.include = [str(k) for k in include]
+        # OPT-11 P2: the modes offered (empty when battery modes are off), and
+        # the mode config topics to remove (`mode_retractions()`).
+        self.modes = tuple(modes)
+        self.retract = [str(t) for t in retract]
         self.enabled = mqtt is not None and bool(host)
         self.client = None
         if not self.enabled:
@@ -470,7 +610,8 @@ class MqttPublisher:
         # paho DROPS QoS-0 publishes when disconnected, silently. The result is
         # an add-on that logs "MQTT connected" and creates no entities at all.
         # As a bonus, this also re-announces after every reconnect.
-        self.client.on_connect = lambda *_args, **_kw: self._announce()
+        self.client.on_connect = lambda *_args, **_kw: self._on_connect()
+        self.client.on_message = self._on_message
         try:
             self.client.connect(host, int(port), keepalive=60)
             self.client.loop_start()
@@ -485,10 +626,35 @@ class MqttPublisher:
         # diffing what actually goes on the wire - and a payload built here
         # instead would be one this add-on publishes and no check has ever seen.
         for topic, cfg in discovery_payloads(self.units, self.omit,
-                                             self.include):
+                                             self.include, self.modes):
             self.client.publish(topic, json.dumps(cfg), retain=True)
+        for topic in self.retract:
+            self.client.publish(topic, "", retain=True)
         self.client.publish(AVAILABILITY, "online", retain=True)
 
+    def _on_connect(self) -> None:
+        self._announce()
+        if self.modes:
+            for key in ("mode", "use"):
+                self.client.subscribe(f"{BASE}/unit/+/{key}/set")
+
+    def bind(self, loop, handler) -> None:
+        """OPT-11 P2: hand each command to `handler(topic, payload, retained)`,
+        a coroutine function run on `loop` (the controller's)."""
+        self._loop, self._handler = loop, handler
+
+    def _on_message(self, _client, _userdata, msg) -> None:
+        # paho's network thread: nothing is done here but the handoff.
+        loop, handler = self._loop, self._handler
+        if loop is None or handler is None:
+            _LOG.debug("MQTT command before start-up ignored: %s", msg.topic)
+            return
+        try:
+            asyncio.run_coroutine_threadsafe(
+                handler(msg.topic, bytes(msg.payload), bool(msg.retain)), loop)
+        except RuntimeError as err:  # the loop has closed
+            _LOG.debug("MQTT command dropped: %s", err)
+
     def publish(self, values: dict) -> None:
         if not self.enabled or self.client is None:
             return

goodwe_controller/app/packmode.py

@@ -0,0 +1,109 @@
+"""OPT-11 P1: 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.
+DECISIONS/OPT-11-battery-modes.md has the record; OPT-11-design section 1 has
+the modes.
+
+Two rules hold for every mode, and they are what keeps modes safe:
+
+1. A mode range always holds 0 W. A mode may forbid a direction, never force
+   one, so batteries never move power in opposite directions because of a mode
+   (allocator.unit_interval() drops a range without 0 as a software fault).
+2. A mode is a limit, not a weight. A weight of 0 does not keep a battery out:
+   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.
+"""
+
+from dataclasses import dataclass
+
+from .store import unit_key
+
+SOLAR_FIRST = "solar_first"
+LEFTOVER_SOLAR = "leftover_solar"
+CHEAP_HOURS = "cheap_hours"         # reserved for P3; not accepted in P1
+
+# 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)
+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
+
+
+def enabled(opts) -> bool:
+    """Battery modes are on only when the option is exactly true. One answer,
+    read by the controller and by the MQTT announcement."""
+    return opts.get("battery_modes_enabled") is True
+
+
+@dataclass(frozen=True)
+class PackMode:
+    """One battery's choice: on or off, its mode, and (P3) selling."""
+    use: bool = True
+    mode: str = DEFAULT_MODE
+    sell: bool = False              # reserved for P3, never read in P1
+
+    @property
+    def key(self) -> str:
+        """The page's word for this state: a mode, or `off`."""
+        return self.mode if self.use else "off"
+
+
+def read(data: dict, name: str) -> PackMode:
+    """Battery `name`'s choice from the store's data. A missing or unknown
+    value falls back to the default (on, Solar first), never to Off: a store
+    written by a later version must not switch a battery off here."""
+    use = data.get(unit_key(name, USE_KEY), True)
+    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)
+
+
+def mode_range(pm: PackMode, rating_w: float) -> tuple:
+    """`(lo, hi)` in W for this battery's mode claim. 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.
+    """
+    if not pm.use:
+        return 0.0, 0.0
+    r = abs(float(rating_w))
+    return -r, r
+
+
+def charge_weights(base, modes: dict, target_w: float):
+    """The allocator's weights with the solar order applied (design 3.5).
+
+    `base` is packshare.weights()' answer (None for "all 1.0"). While the site
+    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).
+
+    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
+    order among equals stays OPT-09's rather than an equal split.
+    """
+    if float(target_w) >= 0.0 or not modes:
+        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])
+           for n in names}
+    if not any(out[n] > 0.0 for n in names if modes[n].use):
+        return base
+    return out

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"

goodwe_controller/app/static/app.css

@@ -228,3 +228,19 @@ input.txt.time{width:5.5em;text-align:center;font-variant-numeric:tabular-nums}
 .sev.bad{background:var(--bad-bg);color:var(--bad)} .sev.warn{background:var(--warn-bg);color:var(--warn)}
 .checklist li{display:flex;gap:8px;align-items:flex-start;overflow-wrap:anywhere}
 .kettle .row{margin-top:8px}
+/* UX-13 P3: the Batteries screen and the Simple settings view */
+.bcard .hd{display:flex;align-items:center;gap:10px;margin-bottom:10px}
+.bcard .name{font-weight:700;font-size:16px}
+.bcard .modebox .lbl{display:block;margin-bottom:4px}
+.bcard .modebox .help{font-size:13px;color:var(--muted);margin-top:4px}
+.bcard.off .modebox{opacity:.6}
+.bcard .kv dd{overflow-wrap:anywhere}
+.switch:disabled{opacity:.45;cursor:not-allowed}
+select.sel:disabled{opacity:.6}
+.simple .card>.row{margin-bottom:4px}
+.vhide{display:none!important}
+.simple .card>.f{border-top:0;padding-top:0}
+.simple .f>.head{display:flex;justify-content:space-between;align-items:center;gap:8px;flex-wrap:wrap}
+.simple .card .lbl{font-weight:600;font-size:15px}
+.simple .inv .hd{border-bottom:0}
+.simple .inv .f{border-top:0;padding-top:0}

goodwe_controller/app/static/app.js

@@ -78,10 +78,12 @@
     if (!r.ok) throw new Error("action " + r.status);
     return r.json();
   }
-  async function refresh() {
+  // `force`: redraw the battery cards even under a focused mode list, after
+  // the person used it (P3).
+  async function refresh(force) {
     if (busy) return;
     busy = true;
-    try { S = await getStatus(); render(); }
+    try { S = await getStatus(); render(force === true); }
     catch (e) { offline(); }
     finally { busy = false; }
   }
@@ -104,7 +106,7 @@
     $("#pill").replaceChildren(h("span", { class: "dot" + dot, "aria-hidden": "true" }), h("span", {}, words));
   }
 
-  function render() {
+  function render(force) {
     renderPill();
     const structured = S.now && S.plan && !S.home_error;
     // UX-15: setup-only mode commands nothing and has no control to offer.
@@ -114,7 +116,8 @@
     if (structured) { renderNow(); renderPlan(); renderPeak(); renderAttention(); }
     renderControl(structured, setup);
     renderDetails(!structured && !setup);
-    renderBatteries();
+    renderBatteries(force);
+    document.dispatchEvent(new CustomEvent("ux13:status"));
   }
 
   /* ---------------- Home: now ---------------- */
@@ -308,17 +311,112 @@
     if (open) $("#c-details").open = true;
   }
 
-  /* ---------------- Batteries (placeholder until P3) ---------------- */
-  function renderBatteries() {
-    if (!S.batteries) { $("#bcards").replaceChildren(); return; }
-    $("#bcards").replaceChildren(...S.batteries.map((b) => h("div", { class: "card" },
-      h("div", { class: "row spread" }, h("strong", {}, b.name), h("span", { class: "small muted" }, b.capacity_kwh ? b.capacity_kwh + " kWh" : "")),
+  /* ---------------- 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
+  // 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 say = (text, vars) => Object.keys(vars).reduce((x, k) => x.replace("{" + k + "}", vars[k]), text);
+  let packBusy = false;
+  let simpleHost = null;
+  async function packAct(what, b, value) {
+    if (packBusy) return;
+    packBusy = true;
+    try {
+      const r = await fetch("action", { method: "POST", headers: { "Content-Type": "application/json" },
+                                        body: JSON.stringify({ action: what, unit: b.name, value: value }) });
+      const j = await r.json().catch(() => ({}));
+      if (!r.ok) toast(j.error || t("toast.failed"));
+      else if (what === "pack_use") toast(say(value ? t("batteries.toast.on") : t("batteries.toast.off"), { name: b.name }));
+      else toast(say(t("batteries.toast.mode"), { name: b.name, mode: t("batteries.choice." + value + ".name") }));
+    } catch (e) { toast(t("toast.failed")); }
+    finally { packBusy = false; }
+    await refresh(true);
+  }
+  function onSwitch(b, i, where, lid) {
+    const sw = h("button", { type: "button", class: "switch", role: "switch", id: "bsw-" + where + i,
+                             "aria-checked": String(b.use), "aria-labelledby": lid,
+                             onclick: () => packAct("pack_use", b, !b.use) });
+    return h("span", { class: "swrap" }, sw, h("span", { class: "swtext", "aria-hidden": "true" }, b.use ? t("batteries.on") : t("batteries.off")));
+  }
+  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 })));
+  }
+  function todayLines(b) {
+    if (!b.today || !b.today.length) return b.today_line || "–";
+    return b.today.map((r) => h("div", {}, r.from + " " + t("plan.time_to") + " " + r.to + ": " + r.what));
+  }
+  function batteryCard(b, i) {
+    const modes = b.mode_key != null;
+    const lid = "bname-" + i;
+    const lvl = b.level_pct == null ? "–" : Math.round(b.level_pct) + " %";
+    const stored = b.stored_kwh != null ? " · " + dec(b.stored_kwh.toFixed(1)) + " kWh " + t("batteries.stored").toLowerCase() : "";
+    return h("div", { class: "card bcard" + (modes && !b.use ? " off" : "") },
+      h("div", { class: "hd" },
+        h("div", { class: "grow" }, h("div", { class: "name", id: lid }, b.name),
+          h("div", { class: "tiny muted" }, b.capacity_kwh ? dec(Number(b.capacity_kwh).toFixed(1)) + " kWh" : "")),
+        modes ? onSwitch(b, i, "c", lid) : null),
+      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,
       levelBar(b.level_pct, b.name),
       h("dl", { class: "kv" },
-        h("dt", {}, t("batteries.level")), h("dd", {}, b.level_pct == null ? "–" : Math.round(b.level_pct) + " %"),
-        b.stored_kwh != null ? [h("dt", {}, t("batteries.stored")), h("dd", {}, dec(b.stored_kwh.toFixed(1)) + " kWh")] : null,
+        h("dt", {}, t("batteries.level")), h("dd", {}, lvl + stored),
         h("dt", {}, t("batteries.now")), h("dd", {}, b.now),
-        h("dt", {}, t("batteries.mode")), h("dd", {}, b.mode)))));
+        h("dt", {}, t("batteries.today")), h("dd", {}, todayLines(b)),
+        h("dt", {}, t("batteries.why")), h("dd", { class: "muted" }, b.why || "–")));
+  }
+  function simpleRow(b, i) {
+    const lid = "bsname-" + i;
+    return h("div", { class: "inv" },
+      h("div", { class: "hd" }, h("span", { class: "grow", id: lid }, b.name), onSwitch(b, i, "s", lid)),
+      h("div", { class: "f" }, h("label", { class: "lbl", for: "bsel-s" + i }, t("batteries.mode")),
+        h("div", { class: "ctl" }, modeSelect(b, i, "s", null)),
+        h("div", { class: "help" }, b.now + " " + (b.why || ""))));
+  }
+  // Rebuild without losing the focused control, and never under an open list
+  // or a request in flight.
+  function keepFocus(fn) {
+    const id = document.activeElement && document.activeElement.id;
+    fn();
+    if (id && /^bs(w|el)-/.test(id)) { const e = document.getElementById(id); if (e) e.focus(); }
+  }
+  // The modes-off card's button opens Settings on the Installer view, where
+  // the "Battery modes" switch is (settings.js sets window.UX13.settingsView).
+  $("#batt-off a").addEventListener("click", () => { if (window.UX13.settingsView) window.UX13.settingsView("installer"); });
+  function renderBatteries(force) {
+    if (!S || !S.batteries) { $("#bcards").replaceChildren(); return; }
+    const a = document.activeElement;
+    if (!force && (packBusy || (a && a.tagName === "SELECT" && /^bsel-/.test(a.id)))) return;
+    const modes = S.modes_on === true || S.batteries.some((b) => b.mode_key != null);
+    $("#batt-off").hidden = modes;
+    $("#batt-how").hidden = !modes;
+    const docs = $("#batt-docs");
+    if (S.control && S.control.docs_url) { docs.href = S.control.docs_url; docs.hidden = false; } else docs.hidden = true;
+    if (S.state && ["shadow", "stopped", "alarm"].includes(S.state.kind)) banner($("#batt-banner"), S.level, S.state.pill, S.state.sub, S.level === "bad" ? "alert" : null);
+    else $("#batt-banner").replaceChildren();
+    keepFocus(() => {
+      $("#bcards").replaceChildren(...S.batteries.map(batteryCard));
+      if (simpleHost && simpleHost.isConnected) {
+        simpleHost.replaceChildren(...(modes ? S.batteries.map(simpleRow)
+          : [h("p", { class: "small muted", style: "margin:4px 0" }, t("batteries.modes_off.name") + ". " + t("batteries.description"))]));
+      }
+    });
   }
 
   /* ---------------- control buttons ---------------- */
@@ -352,7 +450,10 @@
   // Shared with settings.js, which loads after this file.
   // `first`: the page opened with no route, so settings.js may open the setup
   // wizard on a new install (UX-13 P4).
-  window.UX13 = { h, ask, toast, t, words: WORDS, lang: LANG, maint: (what) => ask(what, () => simple(what)), first: !location.hash };
+  window.UX13 = { h, ask, toast, t, words: WORDS, lang: LANG, maint: (what) => ask(what, () => simple(what)), first: !location.hash,
+                  // P3: the Simple settings view's battery card, drawn from /status.
+                  batteries: (host) => { simpleHost = host; if (S) renderBatteries(); refresh(); },
+                  status: () => S, kw };
 
   /* ---------------- tabs: hash routes, arrow keys ---------------- */
   const TABS = [...document.querySelectorAll(".tab")];

goodwe_controller/app/static/index.html

@@ -94,11 +94,23 @@
 </section>
 
 <section class="screen" id="s-batt" role="tabpanel" aria-labelledby="t-batt" hidden>
-  <div id="bcards"></div>
-  <div class="card">
+  <div id="batt-banner"></div>
+  <div class="card" id="batt-off" hidden>
+    <h2 data-t="batteries.modes_off.name"></h2>
     <p class="small muted" style="margin:0 0 10px" data-t="batteries.description"></p>
     <a class="btn" href="#settings" data-t="batteries.settings"></a>
   </div>
+  <div id="bcards"></div>
+  <details class="grp" id="batt-how" hidden>
+    <summary><span class="grow"><strong data-t="batteries.how.name"></strong><span class="small muted gdesc" data-t="batteries.how.description"></span></span><span class="chev" aria-hidden="true">&#8250;</span></summary>
+    <div class="body small">
+      <p data-t="batteries.how.solar_first.description"></p>
+      <p data-t="batteries.how.leftover_solar.description"></p>
+      <p data-t="batteries.how.off.description"></p>
+      <p class="muted" data-t="batteries.how.rules.description"></p>
+      <p><a id="batt-docs" hidden target="_top" rel="noopener" data-t="control.docs"></a></p>
+    </div>
+  </details>
 </section>
 
 <section class="screen" id="s-set" role="tabpanel" aria-labelledby="t-set" hidden>
@@ -106,8 +118,15 @@
     <h2 style="margin:0" data-s="name"></h2>
     <a class="small" href="config" id="set-classic" data-s="classic"></a>
   </div>
-  <p class="small muted" style="margin:0 0 10px" data-s="description"></p>
+  <div class="row" style="margin-bottom:8px">
+    <div class="seg" role="radiogroup" id="set-view" data-s-label="view.name">
+      <button type="button" role="radio" aria-checked="true" data-v="simple" data-s="view.simple"></button>
+      <button type="button" role="radio" aria-checked="false" data-v="installer" tabindex="-1" data-s="view.installer"></button>
+    </div>
+    <span class="tiny muted grow" id="set-desc"></span>
+  </div>
   <div id="set-banner" aria-live="polite"></div>
+  <div id="simple" class="simple" hidden></div>
   <div id="set-body">
     <input class="search" id="set-search" type="search" autocomplete="off" spellcheck="false" data-s-ph="search.description" data-s-label="search.name">
     <div class="card" id="set-other" hidden><h2 data-s="other"></h2><ul class="plain small" id="set-other-list"></ul></div>

goodwe_controller/app/static/settings.js

@@ -32,6 +32,10 @@
   let FILLED = {};           // field key -> the preset field that fills it
   let view = null;           // "settings" or "setup": the tab drawing V
   let STEPS = {};            // wizard step -> refusals that block it
+  // P3: "simple" (the default, for home owners) or "installer". Remembered in
+  // this browser only; a blocked storage just means Simple each time.
+  let mode = "simple";
+  try { if (localStorage.getItem("ux13.settings.view") === "installer") mode = "installer"; } catch (e) { /* no storage */ }
   let uid = 0;
   const ROWS = [];
   const OPEN = new Set();
@@ -337,7 +341,7 @@
   function fieldRow(f, card, gid) {
     if (f.control === "inverter_list") return cardList(f, gid);
     const lid = "sf" + (++uid);
-    const keys = keyText(f, card);
+    const keys = gid === "simple" ? "" : keyText(f, card);     // Simple shows no keys
     const msg = h("div", { class: "msgs" });
     const make = CONTROLS[f.control] || text;
     const row = h("div", { class: "f" + (f.control === "toggle" ? " inline" : ""), "data-key": f.key, "data-card": card },
@@ -421,10 +425,81 @@
       d.append(body);
       host.append(d);
     }
+    renderSimple();
     paint();
     window.scrollTo(0, y);
   }
 
+  /* ---------------- Settings, Simple (P3) ---------------- */
+  // The fields the layout marks `simple`, each in its own card with when it
+  // applies, and the batteries' switches and modes (runtime state, applied at
+  // once) drawn by app.js from /status. The Installer rows stay built but
+  // hidden, so the save bar counts every unsaved change in either view.
+  const chip = (applies) => h("span", { class: "chip " + (applies === "now" ? "now" : "rs") }, ROOT.applies[applies].name);
+  // A note with {kw} is filled from /status (app.js sends ux13:status).
+  function fillNotes() {
+    const st = window.UX13.status();
+    const mp = st && st.month_peak;
+    document.querySelectorAll("#simple [data-kw-note]").forEach((e) => {
+      const ok = mp && mp.peak_w != null;
+      e.hidden = !ok;
+      e.textContent = ok ? e.dataset.kwNote.replace("{kw}", window.UX13.kw(mp.peak_w) + " kW") : "";
+    });
+  }
+  document.addEventListener("ux13:status", fillNotes);
+  function simpleField(f) {
+    const row = fieldRow(f, null, "simple");
+    row.querySelector(".head").append(chip(f.applies));
+    const n = f.note && W.simple.note[f.note];
+    if (n && n.description.includes("{kw}")) {
+      row.append(h("div", { class: "small muted", "data-kw-note": n.description, hidden: true }));
+    } else if (n) {
+      // A plain note replaces the option's installer help on this view.
+      const help = row.querySelector(".help");
+      if (help) help.textContent = n.description;
+    }
+    return h("div", { class: "card" }, row);
+  }
+  function renderSimple() {
+    const host = $("#simple");
+    host.replaceChildren();
+    if (mode !== "simple") return;
+    const cards = allFields().filter((f) => f.simple).map(simpleField);
+    const batts = h("div", {});
+    cards.splice(Math.min(1, cards.length), 0, h("div", { class: "card" },
+      h("div", { class: "row spread" }, h("div", { class: "lbl" }, W.simple.batteries.name), chip("now")), batts));
+    host.append(...cards, h("p", { class: "small muted", style: "margin:4px 2px" }, W.simple.more.description + " ",
+      h("button", { type: "button", class: "btn link", onclick: () => setMode("installer", true) }, W.simple.installer)));
+    window.UX13.batteries(batts);
+    fillNotes();
+  }
+  // `remember`: only the person's own pick of a view is kept for next time;
+  // a jump to Installer (a link, a setting to fix) is not.
+  function setMode(v, redraw, remember) {
+    mode = v;
+    if (remember) try { localStorage.setItem("ux13.settings.view", v); } catch (e) { /* no storage */ }
+    document.querySelectorAll("#set-view [role=radio]").forEach((b) => {
+      const on = b.dataset.v === v;
+      b.setAttribute("aria-checked", String(on)); b.tabIndex = on ? 0 : -1;
+    });
+    $("#set-desc").textContent = v === "simple" ? W.simple.description : W.description;
+    $("#simple").hidden = v !== "simple";
+    ["#set-search", "#groups", "#set-nomatch"].forEach((id) => { $(id).classList.toggle("vhide", v === "simple"); });
+    if (redraw && M && view === "settings") render();
+  }
+  document.querySelectorAll("#set-view [role=radio]").forEach((b, i, all) => {
+    b.addEventListener("click", () => setMode(b.dataset.v, true, true));
+    b.addEventListener("keydown", (e) => {
+      const d = { ArrowRight: 1, ArrowDown: 1, ArrowLeft: -1, ArrowUp: -1 }[e.key];
+      if (!d) return;
+      e.preventDefault();
+      const j = all[(i + d + all.length) % all.length];
+      setMode(j.dataset.v, true, true); j.focus();
+    });
+  });
+  setMode(mode, false);
+  window.UX13.settingsView = (v) => setMode(v, true);
+
   /* ---------------- messages, visibility, search, badges ---------------- */
   const ICON = { bad: "×", warn: "!", info: "i" };
   const RANK = { bad: 0, warn: 1, info: 2 };
@@ -434,11 +509,13 @@
     return m.card == null ? r.card === 0 : m.card === r.card;
   }
   function paint() {
-    const q = view === "setup" ? "" : $("#set-search").value.trim().toLowerCase();
+    const q = view === "setup" || mode === "simple" ? "" : $("#set-search").value.trim().toLowerCase();
+    // A message counts as shown only beside a row of the view on screen.
+    const onScreen = (r) => view === "setup" || (mode === "simple") === (r.gid === "simple");
     const placed = new Set();
     for (const r of ROWS) {
       r.visible = visible(r.f);
-      const msgs = MSG.filter((m, i) => { const hit = mine(r, m); if (hit && r.visible) placed.add(i); return hit; })
+      const msgs = MSG.filter((m, i) => { const hit = mine(r, m); if (hit && r.visible && onScreen(r)) placed.add(i); return hit; })
         .sort((a, z) => RANK[a.tier] - RANK[z.tier]);
       r.tiers = new Set(msgs.map((m) => m.tier));
       r.msg.replaceChildren(...msgs.map((m) => h("div", { class: "msg " + m.tier },
@@ -562,7 +639,9 @@
     validate();
   }
   function firstBad() {
-    const r = ROWS.find((x) => x.tiers && x.tiers.has("bad") && x.visible);
+    if (view === "settings" && mode === "simple" && !ROWS.some((x) => x.gid === "simple" && x.tiers && x.tiers.has("bad") && x.visible)
+        && ROWS.some((x) => x.tiers && x.tiers.has("bad") && x.visible)) setMode("installer", true);
+    const r = ROWS.find((x) => x.tiers && x.tiers.has("bad") && x.visible && (view !== "settings" || (mode === "simple") === (x.gid === "simple")));
     if (!r) { if (!$("#set-other").hidden) $("#set-other").scrollIntoView({ block: "center" }); return; }
     for (let p = r.el.parentElement; p; p = p.parentElement) if (p.tagName === "DETAILS") p.open = true;
     r.el.scrollIntoView({ block: "center" });

goodwe_controller/app/ui_text/en.json

@@ -10,9 +10,10 @@
   "parts": {
     "meter.timing": {"name": "Timing"},
     "inverters.solar": {"name": "Solar"},
+    "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"}
@@ -82,7 +83,23 @@
     "toast": {"started": "Control started.", "stopped": "Control stopped.", "done": "Done.", "failed": "That did not work. Try again."},
     "offline": {"name": "Cannot reach the add-on", "description": "The page tries again every 3 seconds."},
     "setup_only": {"name": "Setup: nothing is controlled yet", "description": "Nothing is sent to any inverter until setup is saved and the add-on restarts.", "control": "Control starts after setup.", "open": "Open Setup"},
-    "batteries": {"name": "Batteries", "description": "Battery modes and on and off switches arrive in a later update.", "level": "Level", "now": "Now", "stored": "Stored", "mode": "Mode", "settings": "Change inverter settings"},
+    "batteries": {"name": "Batteries", "description": "To choose a mode for each battery, turn on battery modes in the settings.", "level": "Level", "now": "Now", "stored": "Stored", "mode": "Mode", "settings": "Change inverter settings",
+      "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."},
+        "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."},
+        "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."}},
+      "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"}
   },
   "choices_later": {
@@ -99,7 +116,13 @@
   },
   "settings": {
     "name": "Settings",
-    "description": "Every setting, grouped by task, and the simple view follows in a later update.",
+    "description": "Every setting, grouped by task.",
+    "view": {"name": "Settings view", "simple": "Simple", "installer": "Installer"},
+    "simple": {"description": "The choices a home owner makes.",
+      "note": {"month_peak": {"description": "This month's peak so far: {kw}."}, "shadow": {"description": "Use Always on while you test a new installation."}},
+      "batteries": {"name": "Batteries"},
+      "more": {"description": "Looking for the meter, inverters or prices?"},
+      "installer": "Open the installer view"},
     "classic": "Classic settings",
     "search": {"name": "Find a setting", "description": "Find a setting, for example peak or meter."},
     "no_match": {"description": "No setting matches your search."},
@@ -215,7 +238,6 @@
         "again": "Check again",
         "blocked": {"description": "Fix the items marked in red, then check again."}
       },
-      "shadow": {"name": "Start in shadow mode", "description": "Recommended, because every inverter then stays at 0 W until you turn shadow mode off under Settings."},
       "dialog": {"name": "Save and restart?", "description": "Every inverter is set to 0 W while the add-on restarts, and shadow mode keeps them at 0 W after that.", "yes": "Save and restart"},
       "dialog_live": {"name": "Save and restart?", "description": "Every inverter is set to 0 W while the add-on restarts, and then the new settings apply.", "yes": "Save and restart"},
       "dialog_setup": {"name": "Save and restart?", "description": "The add-on restarts with these settings, and shadow mode keeps every inverter at 0 W.", "yes": "Save and restart"},
@@ -228,6 +250,7 @@
   },
   "home_words": {
     "mode_house": "Follows the house",
+    "modes": {"solar_first": "Solar first", "leftover_solar": "Leftover solar", "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",
@@ -281,7 +304,37 @@
       "cycle": "Monthly cycle under way.",
       "giving": "Giving {kw} now.",
       "charging": "Charging {kw} now.",
-      "resting": "Resting now."
+      "resting": "Resting now.",
+      "off_resting": "Off. Resting now.",
+      "off_peak": "Off, but gives {kw} for the peak limit.",
+      "off_going": "Off. Still at {kw}, going to 0 W."
+    },
+    "why": {
+      "no_reading": "No reading, so the add-on cannot tell.",
+      "held": "An alarm stopped control. See Needs attention.",
+      "stopped": "Control is stopped.",
+      "shadow": "Shadow mode: the add-on only shows what it would do.",
+      "cycle": "The monthly cycle keeps its level reading right.",
+      "cycle_mode": "The monthly cycle comes first. Its mode resumes after.",
+      "off": "You switched it off.",
+      "off_peak": "The peak limit comes before Off. It rests again after.",
+      "refuses_give": "The battery refuses to give power. The add-on tries again every 15 minutes.",
+      "refuses_charge": "The battery refuses to charge. The add-on tries again every 15 minutes.",
+      "peak": "The peak limit needs power from the batteries.",
+      "modes_off": "Battery modes are off, so it follows the house.",
+      "solar_first": "Solar first: it gets spare solar before the others.",
+      "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."
+    },
+    "today": {
+      "not_planned": "Not planned yet.",
+      "off": "Off, so no monthly cycle today.",
+      "house": "Follows the house.",
+      "house_would": "Would follow the house.",
+      "stopped": "Nothing planned while control is stopped.",
+      "held": "Nothing planned until the alarm clears."
     },
     "head": {
       "held": "Every inverter is at 0 W until the alarm clears.",

goodwe_controller/app/ui_text/nl.json

@@ -10,9 +10,10 @@
   "parts": {
     "meter.timing": {"name": "Timing"},
     "inverters.solar": {"name": "Zonnepanelen"},
+    "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"}
@@ -79,7 +80,23 @@
     "toast": {"started": "Regeling gestart.", "stopped": "Regeling gestopt.", "done": "Klaar.", "failed": "Dat lukte niet. Probeer opnieuw."},
     "offline": {"name": "Add-on niet bereikbaar", "description": "De pagina probeert het elke 3 seconden opnieuw."},
     "setup_only": {"name": "Installatie: nog niets wordt geregeld", "description": "Er gaat niets naar een omvormer tot de installatie bewaard is en de add-on herstart.", "control": "De regeling start na de installatie.", "open": "Installatie openen"},
-    "batteries": {"name": "Batterijen", "description": "Batterijmodi en aan- en uitschakelaars komen in een latere update.", "level": "Laadniveau", "now": "Nu", "stored": "Opgeslagen", "mode": "Modus", "settings": "Instellingen van omvormers wijzigen"},
+    "batteries": {"name": "Batterijen", "description": "Zet batterijmodi aan in de instellingen om per batterij een modus te kiezen.", "level": "Laadniveau", "now": "Nu", "stored": "Opgeslagen", "mode": "Modus", "settings": "Instellingen van omvormers wijzigen",
+      "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."},
+        "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."},
+        "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."}},
+      "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"}
   },
   "choices_later": {"region": {"wallonia": "Wallonië, nog geen standaardwaarde", "brussels": "Brussel, nog geen standaardwaarde"}},
@@ -94,7 +111,13 @@
   },
   "settings": {
     "name": "Instellingen",
-    "description": "Elke instelling, per taak, en de eenvoudige weergave volgt in een latere update.",
+    "description": "Elke instelling, per taak.",
+    "view": {"name": "Weergave van de instellingen", "simple": "Eenvoudig", "installer": "Installateur"},
+    "simple": {"description": "De keuzes die een eigenaar maakt.",
+      "note": {"month_peak": {"description": "De piek van deze maand tot nu: {kw}."}, "shadow": {"description": "Kies Altijd aan terwijl u een nieuwe installatie test."}},
+      "batteries": {"name": "Batterijen"},
+      "more": {"description": "Zoekt u de meter, de omvormers of de prijzen?"},
+      "installer": "De installateursweergave openen"},
     "classic": "Klassieke instellingen",
     "search": {"name": "Instelling zoeken", "description": "Zoek een instelling, bijvoorbeeld piek of meter."},
     "no_match": {"description": "Geen instelling past bij uw zoekopdracht."},
@@ -189,7 +212,6 @@
         "needed": {"description": "Doe eerst de waterkokertest, of sla hem over."}
       },
       "check": {"name": "Wat de add-on nakeek", "running": {"description": "Bezig met de startcontroles van de add-on."}, "pass": {"description": "De startcontroles van de add-on zijn in orde."}, "failed": {"description": "De controle liep niet, dus probeer opnieuw."}, "again": "Opnieuw nakijken", "blocked": {"description": "Los de rood gemarkeerde punten op en kijk dan opnieuw na."}},
-      "shadow": {"name": "Starten in schaduwmodus", "description": "Aanbevolen, want dan blijft elke omvormer op 0 W tot u de schaduwmodus uitzet onder Instellingen."},
       "dialog": {"name": "Bewaren en herstarten?", "description": "Elke omvormer gaat naar 0 W terwijl de add-on herstart, en de schaduwmodus houdt ze daarna op 0 W.", "yes": "Bewaren en herstarten"},
       "dialog_live": {"name": "Bewaren en herstarten?", "description": "Elke omvormer gaat naar 0 W terwijl de add-on herstart, daarna gelden de nieuwe instellingen.", "yes": "Bewaren en herstarten"},
       "dialog_setup": {"name": "Bewaren en herstarten?", "description": "De add-on herstart met deze instellingen, en de schaduwmodus houdt elke omvormer op 0 W.", "yes": "Bewaren en herstarten"},
@@ -202,6 +224,7 @@
   },
   "home_words": {
     "mode_house": "Volgt het huis",
+    "modes": {"solar_first": "Eerst zonne-energie", "leftover_solar": "Overschot zonne-energie", "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",
@@ -223,7 +246,37 @@
       "cycle": "Maandelijkse cyclus bezig.",
       "giving": "Levert nu {kw}.",
       "charging": "Laadt nu {kw}.",
-      "resting": "Rust nu."
+      "resting": "Rust nu.",
+      "off_resting": "Uit. Rust nu.",
+      "off_peak": "Uit, maar levert {kw} voor de piekgrens.",
+      "off_going": "Uit. Nog {kw}, gaat naar 0 W."
+    },
+    "why": {
+      "no_reading": "Geen meting, dus de add-on weet het niet.",
+      "held": "Een alarm stopte de regeling. Zie Vraagt aandacht.",
+      "stopped": "De regeling is gestopt.",
+      "shadow": "Schaduwmodus: de add-on toont alleen wat hij zou doen.",
+      "cycle": "De maandelijkse cyclus houdt de meting van het laadniveau juist.",
+      "cycle_mode": "De maandelijkse cyclus gaat voor. Daarna volgt ze weer haar modus.",
+      "off": "U hebt haar uitgezet.",
+      "off_peak": "De piekgrens gaat voor op Uit. Daarna rust ze weer.",
+      "refuses_give": "De batterij weigert te leveren. De add-on probeert het elke 15 minuten opnieuw.",
+      "refuses_charge": "De batterij weigert te laden. De add-on probeert het elke 15 minuten opnieuw.",
+      "peak": "De piekgrens vraagt vermogen van de batterijen.",
+      "modes_off": "Batterijmodi staan uit, dus ze volgt het huis.",
+      "solar_first": "Eerst zonne-energie: ze krijgt het overschot vóór de andere.",
+      "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."
+    },
+    "today": {
+      "not_planned": "Nog niet gepland.",
+      "off": "Uit, dus vandaag geen maandelijkse cyclus.",
+      "house": "Volgt het huis.",
+      "house_would": "Zou het huis volgen.",
+      "stopped": "Niets gepland zolang de regeling gestopt is.",
+      "held": "Niets gepland tot het alarm weg is."
     },
     "head": {
       "held": "Elke omvormer staat op 0 W tot het alarm weg is.",

goodwe_controller/app/uilayout.py

@@ -46,6 +46,7 @@ class Field:
     wizard: int = 0             # setup wizard step 1-6, 0 = not in the wizard
     mirror: str = ""            # a choice also copied to this field, if offered
     fills: str = ""             # a preset choice fills this field (uimodel)
+    note: str = ""              # P3: a line under it on Settings, Simple
 
     @property
     def text(self) -> str:
@@ -126,6 +127,9 @@ GROUPS = (
         # pv.py reads each entity's own unit, so a kW sensor is fine here.
         Part("solar", (Field("ui.solar", SOLAR_LIST, kind="power",
                              wizard=3),)),
+        # OPT-11: the switch that turns battery modes on. Each battery's mode
+        # and on/off switch are runtime state on the Batteries screen.
+        Part("modes", (Field("battery_modes_enabled", TOGGLE),)),
     )),
     Group("tariff", (
         Part("", (
@@ -177,12 +181,14 @@ GROUPS = (
     Group("safety", (
         Part("peak", (
             Field("peak_cap_w", SLIDER, "kW", scale=1000, step=100,
-                  simple=True, wizard=5),
+                  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, "%"),
         )),
         Part("start", (
-            Field("shadow_mode", SEGMENTED, simple=True, wizard=6),
+            Field("shadow_mode", SEGMENTED, simple=True, wizard=6,
+                  note="shadow"),
             Field("auto_start", TOGGLE),
             Field("estop_fitted", TOGGLE),
             Field("stale_input_s", SLIDER, "s"),

goodwe_controller/app/uipage.py

@@ -99,7 +99,7 @@ def _field(fld, schema_ui, translations, lang, T):
            "help": text, "unit": fld.unit, "scale": fld.scale,
            "step": fld.step, "kind": fld.kind,
            "show": [list(c) for c in fld.show], "applies": fld.applies,
-           "wizard": fld.wizard,
+           "wizard": fld.wizard, "simple": fld.simple, "note": fld.note,
            "type": value_type, "optional": not node.get("required", False),
            # A choice mirrored into a field also shows (and finds) its keys.
            "writes": sorted(k for k, how in L.DERIVED.items()

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

@@ -33,6 +33,10 @@ not options is a Store key, `setup_done`, written when the wizard's save
 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
+are the only actions that name a battery; the configuration routes still reach
+none of them.
 """
 
 import io
@@ -53,6 +57,9 @@ 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")
+
 # 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
 # and, since P5, Dutch; the page picks by the browser's language). They are
@@ -146,7 +153,17 @@ def build_app(controller, selfcfg=None) -> web.Application:
             # UX-15: nothing to start or stop until setup is saved.
             return web.json_response(
                 {"ok": False, "error": messages.row_setup_only()}, status=409)
-        result = await controller.handle_action(what)
+        if what in PACK_ACTIONS:
+            # OPT-11: one battery's switch or mode. Store state for the named
+            # battery, applied on the next cycle; nothing is written here.
+            result = await controller.handle_action(
+                what, unit=body.get("unit"), value=body.get("value"))
+            if isinstance(result, dict) and "error" in result:
+                return web.json_response({"ok": False,
+                                          "error": result["error"]},
+                                         status=400)
+        else:
+            result = await controller.handle_action(what)
         if result is None:
             raise web.HTTPBadRequest(text=f"unknown action {what!r}")
         return web.json_response({"ok": True, "result": result})

goodwe_controller/config.yaml

@@ -146,6 +146,11 @@ options:
   # options blob, and the upgrade leaves an add-on that cannot start.
   inverters: []
   estop_fitted: false
+  # OPT-11: battery modes. Off by default, so an install that has not turned
+  # them on behaves exactly as before. When on, each battery gets an on/off
+  # switch and a mode on the Batteries screen, kept in the add-on's store.
+  # DECISIONS/OPT-11-battery-modes.md.
+  battery_modes_enabled: false
 
   # TEL-11 - THE SITE'S PV PRODUCTION, IN WATTS, AND IT IS READ BY NOTHING THAT
   # DECIDES ANYTHING. Optional, empty on every install that does not set it, and
@@ -285,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
@@ -943,6 +950,7 @@ schema:
       capacity_kwh: float(0.1,200)?
 
   estop_fitted: bool
+  battery_modes_enabled: bool
   # TEL-11. Optional, and OPTIONAL WITHOUT A COMPANION RULE - unlike
   # `price_now_entity`/`price_avg_entity`, which are legal only while
   # `price_provider` is `off` and make the add-on REFUSE TO START otherwise.
@@ -1013,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_alloc.py

@@ -1041,6 +1041,133 @@ check("...and the three that are NOT caught are reported as such, with the "
       all(b is False for _n, b, _w in MUT[-3:]))
 
 
+
+print()
+print("13. OPT-11: the mode layer - applied at or below 35, released above it")
+# A mode is a SOFT unit limit beside the hard ones (UnitBounds.mode_*). The
+# allocator applies it only when the site target was decided at or below the
+# mode's own priority (P_MODE, 35), drops it when its range leaves out 0 W,
+# and never lets it narrow a hard limit into nothing.
+from app.allocator import (MODE_FAULT, MODE_OUTRANKED, MODE_RELEASED,  # noqa: E402
+                           loop_bound, unit_interval)
+from app.arbiter import P_MODE                                     # noqa: E402
+
+
+def M(lo=-RATING, hi=RATING, mlo=-inf, mhi=inf, prio=P_MODE, **kw):
+    """A unit's bounds with a mode range beside its hard limits."""
+    b = B(lo, hi, **kw)
+    return UnitBounds(lo=b.lo, hi=b.hi, gate=b.gate, pinned_w=b.pinned_w,
+                      pinned_by=b.pinned_by, contradiction=b.contradiction,
+                      mode_lo=mlo, mode_hi=mhi, mode_priority=prio)
+
+
+_off = {A: M(), Bee: M(mlo=0.0, mhi=0.0)}
+_at35 = plan(3000, _off, deciding_priority=P_MODE)
+_at50 = plan(3000, _off, deciding_priority=P_PEAK)
+_at10 = plan(3000, _off, deciding_priority=P_LOOP)
+print(f"    B off, 3000 W: decided at 10 {_at10.explain()} | at 35 "
+      f"{_at35.explain()} | at 50 {_at50.explain()}")
+check("⭐ RELEASE AT 35: a target decided at P_MODE itself keeps the mode - "
+      "B (Off) is held at 0 W and A carries all 3000 W",
+      _at35.shares == {A: 3000, Bee: 0} and _at35.unmet_w == 0)
+check("...and below it too (the loop, 10): the same split",
+      _at10.shares == _at35.shares)
+check("⭐ RELEASE AT 50: a target decided by the peak floor releases the mode "
+      "and B takes its weighted half",
+      _at50.shares == {A: 1500, Bee: 1500} and _at50.unmet_w == 0)
+check("...and the boundary is exactly 35: at 36 the mode is released",
+      plan(3000, _off, deciding_priority=P_MODE + 1).shares
+      == {A: 1500, Bee: 1500})
+check("...and no deciding priority named means the mode applies (the safe "
+      "reading for a direct caller)",
+      plan(3000, _off).shares == {A: 3000, Bee: 0})
+check("unit_interval() reports why: None when applied, MODE_RELEASED above "
+      "35, and the hard limits always",
+      unit_interval(_off[Bee], P_MODE) == (0.0, 0.0, None)
+      and unit_interval(_off[Bee], P_PEAK) == (-RATING, RATING, MODE_RELEASED))
+
+# CONTAINS 0: a mode that would FORCE a direction is a software fault.
+_force = {A: M(mlo=500.0, mhi=RATING), Bee: M()}
+_f = plan(-1000, _force, deciding_priority=P_LOOP)
+print(f"    A's mode is [500, 5000] (leaves out 0 W), site charges 1000 W: "
+      f"{_f.explain()}, faults {_f.mode_faults}")
+check("⭐ CONTAINS 0: a mode range that leaves out 0 W is dropped and named "
+      "as a fault, so REFUSE_SIGN stays unreachable: both units charge and "
+      "the split is allowed",
+      _f.ok and _f.mode_faults == ((A, MODE_FAULT),)
+      and all(v <= 0 for v in _f.shares.values())
+      and sum(_f.shares.values()) == -1000)
+_f_obeyed = plan(-1000, {A: B(500.0, RATING), Bee: B(-RATING, RATING)})
+check("...and that is not a hypothetical: the same range obeyed as a hard "
+      "limit forces A to give 500 W while B charges 1500 W, which the "
+      "allocator REFUSES as circulating power",
+      not _f_obeyed.ok and REFUSE_SIGN in _f_obeyed.refused)
+check("...and a mode whose own lo is above its own hi is the same fault",
+      unit_interval(M(mlo=300.0, mhi=-300.0))[2] == MODE_FAULT)
+_out = unit_interval(M(lo=-2000.0, hi=-500.0, mlo=0.0, mhi=0.0))
+check("a hard limit that leaves the mode no room wins outright "
+      "(MODE_OUTRANKED): the unit keeps its hard interval",
+      _out == (-2000.0, -500.0, MODE_OUTRANKED))
+check("a unit with no mode (every unit with battery modes off) gets exactly "
+      "its hard limits, and plan() is the same record as before the mode "
+      "fields existed",
+      unit_interval(B(-700.0, 900.0)) == (-700.0, 900.0, None)
+      and plan(1234, TWO, deciding_priority=P_PEAK) == plan(1234, TWO))
+
+# The sweep: sum and sign kept whatever the modes, the target and the
+# deciding priority; every share inside its effective interval.
+_rng = random.Random(1135)
+_bad, _nm = [], 0
+for _ in range(20000):
+    _units = {}
+    for u in (A, Bee, "inverter-c")[:_rng.choice((2, 3))]:
+        r = _rng.choice((2000.0, 3600.0, 5000.0))
+        mlo = _rng.choice((-r, -700.0, 0.0))
+        mhi = _rng.choice((0.0, 450.0, r))
+        _units[u] = M(-r, r, mlo, mhi)
+    _d = _rng.choice((P_LOOP, P_ARBITRAGE, P_MODE, P_MODE + 1, P_PEAK, None))
+    _t = _rng.randint(-15000, 15000)
+    _p = plan(_t, _units, deciding_priority=_d)
+    _nm += 1
+    _eff = {u: unit_interval(b, _d)[:2] for u, b in _units.items()}
+    _sh = _p.shares
+    if (not _p.ok or sum(_sh.values()) + _p.unmet_w != _p.sum_w
+            or (any(v > 0 for v in _sh.values())
+                and any(v < 0 for v in _sh.values()))
+            or any(not (_eff[u][0] <= _sh[u] <= _eff[u][1]) for u in _sh)
+            or (_d is not None and _d > P_MODE
+                and any(_eff[u] != (b.lo, b.hi) for u, b in _units.items()))):
+        _bad.append((_t, _d, _p.explain()))
+for x in _bad[:5]:
+    print(f"       BAD {x}")
+check(f"over {_nm} random ticks (2-3 units, mode ranges holding 0 W, targets "
+      f"+-15 kW, deciding at 10/30/35/36/50/None) the shares sum to S with "
+      f"`unmet`, never split the sign, and each stays inside its interval - "
+      f"the mode's above 35 released, applied at or below",
+      not _bad and _nm == 20000)
+
+# loop_bound(): what the loop may ask when it decides.
+_lb = loop_bound({A: M(mlo=-3000.0, mhi=0.0), Bee: M(mlo=0.0, mhi=0.0)})
+check("loop_bound() sums each unit's interval with its mode applied: A may "
+      "only charge 3000 W, B is off, so the loop may ask [-3000, 0]",
+      _lb == (-3000.0, 0.0))
+check("...a unit that is not live adds nothing",
+      loop_bound({A: M(), Bee: M()}, live=(A,)) == (-RATING, RATING))
+check("...a PINNED unit adds the span from 0 to its pin, so a 200 W probe "
+      "(SAFETY-73: the closed limit becomes a pin) stays reachable",
+      loop_bound({A: M(gate=P_SAFETY, pin=200.0),
+                  Bee: M(mlo=0.0, mhi=0.0)}) == (0.0, 200.0))
+check("...and the pin is clamped into the hard limits first, as plan() "
+      "clamps it",
+      loop_bound({A: M(lo=-RATING, hi=0.0, gate=P_SAFETY, pin=200.0),
+                  Bee: M(mlo=0.0, mhi=0.0)}) == (0.0, 0.0))
+check("...a mode that leaves out 0 W adds the hard interval (dropped, as in "
+      "plan()), so every term holds 0 and so does the sum",
+      loop_bound({A: M(mlo=500.0, mhi=900.0), Bee: M(mlo=0.0, mhi=0.0)})
+      == (-RATING, RATING))
+check("...and a unit contradicting itself adds nothing",
+      loop_bound({A: M(contra=True), Bee: M(mlo=0.0, mhi=0.0)}) == (0.0, 0.0))
+
 print()
 if fails:
     print(f"{len(fails)} FAILED: {', '.join(fails)}")

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: twelve sources, each classified where it is BUILT")
+print("ARB-03 2. the split: thirteen 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
@@ -193,16 +193,20 @@ UNIT_SOURCES = {
     "refused":    "THIS battery's own reading gave nothing against THIS unit's "
                   "own standing command, so that direction is closed on THIS "
                   "unit and its share goes to the others. Filed at N>1 only",
+    # OPT-11, added on purpose (test_peakguard.py part 10f says why).
+    "mode":       "THIS battery's mode, chosen by its owner. A soft unit limit "
+                  "that stage 1 keeps apart from the hard ones and stage 3 "
+                  "releases when a claim above P_MODE decides the site target",
 }
 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 TWELVE claim sources are classified, and only those twelve",
+check("all THIRTEEN claim sources are classified, and only those thirteen",
       set(CLAIM_SCOPE) == set(SITE_SOURCES) | set(UNIT_SOURCES))
 check("the six 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 six that are about a PACK, a DEVICE or one write are per-inverter",
+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))
 check("a source nobody classified cannot be routed at all - actuator_for() "
       "raises rather than defaulting to the site, because defaulting to the "
@@ -220,7 +224,7 @@ check("with one inverter every source routes to the site, per-inverter ones "
       all(actuator_for(s, "inverter-a", ONE) == ACTUATOR_SITE for s in CLAIM_SCOPE))
 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 six "
+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",
       {s: actuator_for(s, "inverter-a", TWO) for s in CLAIM_SCOPE}
@@ -540,6 +544,252 @@ check("...and a correctly routed cycle is unaffected, which is what says this "
       resolve(SITE_SIDE, units=TWO).allocated is True)
 
 
+
+print()
+print("OPT-11 9. the mode layer: a unit `hi` never meets the site `lo`")
+# A battery's mode is a SOFT unit limit at P_MODE (35). Stage 1 keeps it apart
+# from the hard limits; stage 3 applies it only while the site target was
+# decided at or below P_MODE. So the peak guard's site floor (P_PEAK) releases
+# every mode and SAFETY-25 section 0a's cross-inverter contradiction - 0 W in a
+# billed period - still cannot be written down.
+from app.arbiter import MODE_SOURCE, P_MODE                     # noqa: E402
+from app.allocator import MODE_FAULT, MODE_RELEASED             # noqa: E402
+
+
+def _two(loop_w, *, peak_lo=None, modes=None, rating=2000.0, arb=None):
+    """A two-inverter cycle's claims: ratings, each unit's mode, the loop,
+    optionally the peak floor and an arbitrage set."""
+    cl = []
+    for u in TWO:
+        cl.append(Claim.limit("supervised", P_SAFETY, -rating, rating,
+                              "max_w", actuator=u))
+    for u, (lo, hi) in (modes or {}).items():
+        cl.append(Claim.limit(MODE_SOURCE, P_MODE, lo, hi, "mode", actuator=u))
+    cl.append(Claim.set("loop", P_LOOP, loop_w))
+    if arb is not None:
+        cl.append(Claim.set("arbitrage", P_ARBITRAGE, arb))
+    if peak_lo is not None:
+        cl.append(Claim.limit("peak", P_PEAK, lo=peak_lo))
+    return cl
+
+
+check("P_MODE sits between arbitrage and the peak guard, so a trade stays "
+      "inside each mode and the peak floor releases them all",
+      P_ARBITRAGE < P_MODE < P_PEAK and P_MODE < P_MAINT_SHAPE)
+_off_b = {"inverter-b": (0.0, 0.0)}
+r = resolve(_two(-500.0, peak_lo=3000.0, modes=_off_b), units=TWO)
+print(f"    peak floor 3000 W, loop asks -500 W, B off: {r.explain()}, "
+      f"deciding {r.deciding_priority}, shares {r.shares}")
+check("⭐ at N=2 a mode `hi` of 0 W on B and the peak guard's site `lo` of "
+      "3000 W do NOT contradict: no 0 W stop, the floor decides S (priority "
+      "50), the mode is released, and the shares still sum to S",
+      not r.contradiction and r.allocated and r.target_w == 3000.0
+      and r.deciding_priority == P_PEAK
+      and sum(r.shares.values()) == 3000 and r.allocation.unmet_w == 0)
+_forbidden = [c if c.source != MODE_SOURCE
+              else Claim.limit(MODE_SOURCE, P_MODE, c.lo, c.hi,
+                               actuator=ACTUATOR_SITE)
+              for c in _two(-500.0, peak_lo=3000.0, modes=_off_b)]
+_rf = site_resolve([c for c in _forbidden if c.actuator == ACTUATOR_SITE])
+check("...and the SAME mode filed as a SITE limit is exactly the fault the "
+      "layer exists to keep out: stage 2 then reads `lo` 3000 > `hi` 0 and "
+      "stops the site at 0 W (so the check above sees the difference)",
+      _rf.contradiction and _rf.target_w == 0.0)
+check("...and resolve() refuses that mis-filed mode at N=2 (a UNIT claim on "
+      "the site), rather than dividing a number that may be wrong",
+      resolve(_forbidden, units=TWO).allocated is False)
+
+# The sweep: every mode range that holds 0 W, every loop ask, every floor.
+_bad = []
+_n = 0
+_spans = [(0.0, 0.0), (-2000.0, 0.0), (0.0, 2000.0), (-2000.0, 2000.0),
+          (-700.0, 300.0)]
+for _ma in _spans:
+    for _mb in _spans:
+        for _loop in (-5000.0, -1200.0, 0.0, 800.0, 3900.0):
+            for _peak in (None, 0.0, 1500.0, 3000.0, 4000.0):
+                _n += 1
+                _r = resolve(_two(_loop, peak_lo=_peak,
+                                  modes={"inverter-a": _ma,
+                                         "inverter-b": _mb}), units=TWO)
+                _al = _r.allocation
+                _sh = list(_r.shares.values())
+                if (_r.contradiction or not _r.allocated
+                        or sum(_sh) + _al.unmet_w != _al.sum_w
+                        or (any(x > 0 for x in _sh) and any(x < 0 for x in _sh))
+                        or (_peak is not None and _r.target_w < _peak)):
+                    _bad.append((_ma, _mb, _loop, _peak, _r.explain(),
+                                 _al.explain()))
+for x in _bad[:5]:
+    print(f"       BAD {x}")
+check(f"over {_n} two-inverter cycles (5x5 mode ranges holding 0 W, 5 loop "
+      f"asks, 5 peak floors) no cycle contradicts, refuses, loses a watt of "
+      f"the sum, splits the sign, or goes under the peak floor",
+      not _bad and _n == 625)
+
+check("deciding_priority: the loop alone decides at 10",
+      resolve(_two(800.0), units=TWO).deciding_priority == P_LOOP)
+check("...a trade decides at 30, so the modes still apply to it",
+      resolve(_two(800.0, arb=-1500.0), units=TWO).deciding_priority
+      == P_ARBITRAGE)
+check("...a peak floor that does not bind leaves the loop deciding at 10",
+      resolve(_two(3500.0, peak_lo=1000.0), units=TWO).deciding_priority
+      == P_LOOP)
+check("...and a peak floor that binds decides at 50",
+      resolve(_two(500.0, peak_lo=1000.0), units=TWO).deciding_priority
+      == P_PEAK)
+_r35 = resolve(_two(3000.0, modes=_off_b), units=TWO)
+check("with the loop deciding, B's Off mode holds: B gets 0 W and A carries "
+      "what it can, the rest reported as unmet",
+      _r35.shares == {"inverter-a": 2000, "inverter-b": 0}
+      and _r35.allocation.unmet_w == 1000)
+
+_ub = pre_resolve([Claim.limit("supervised", P_SAFETY, -2000, 2000),
+                   Claim.limit(MODE_SOURCE, P_MODE, 0.0, 0.0)])
+check("stage 1 keeps the mode APART from the hard limits: the unit's own "
+      "interval is still its rating and the mode travels beside it",
+      (_ub.lo, _ub.hi, _ub.mode_lo, _ub.mode_hi, _ub.mode_priority)
+      == (-2000, 2000, 0.0, 0.0, P_MODE) and not _ub.contradiction)
+_ub2 = pre_resolve([Claim.limit("supervised", P_SAFETY, -2000, 2000),
+                    Claim.limit(MODE_SOURCE, P_MODE, 500.0, 2000.0)])
+check("...so a mode that does not hold 0 W cannot make the unit contradict "
+      "itself at stage 1; stage 3 drops it as a software fault instead",
+      not _ub2.contradiction
+      and allocate(1000.0, {"inverter-a": _ub2, "inverter-b": UnitBounds()})[1]
+      and resolve(_two(1000.0, modes={"inverter-a": (500.0, 2000.0)}),
+                  units=TWO).allocation.mode_faults
+      == (("inverter-a", MODE_FAULT),))
+_ubm = pre_resolve([Claim.limit("supervised", P_SAFETY, -2000, 2000),
+                    Claim.set("maintenance", P_MAINTENANCE, 2500.0, "drain"),
+                    Claim.limit(MODE_SOURCE, P_MODE, 0.0, 0.0)])
+check("...and a unit's own maintenance SET (60) gates the mode out, as it "
+      "gates every lower limit: maintenance outranks the mode",
+      _ubm.mode_priority is None and _ubm.pinned_by == "maintenance")
+
+print()
+print("OPT-11 10. at N=1 the mode bounds the site target, by the same rule")
+_one = [Claim.limit("supervised", P_SAFETY, -5000, 5000, "max_w"),
+        Claim.limit(MODE_SOURCE, P_MODE, 0.0, 0.0, "off")]
+_r1 = resolve(_one + [Claim.set("loop", P_LOOP, 1200.0)], units=ONE)
+check("the loop deciding: an Off battery's site target is 0 W, named as the "
+      "mode's doing, with no contradiction",
+      _r1.target_w == 0.0 and not _r1.contradiction
+      and _r1.bound_by == "mode(off)" and _r1.allocated)
+_r1p = resolve(_one + [Claim.set("loop", P_LOOP, 1200.0),
+                       Claim.limit("peak", P_PEAK, lo=2000.0)], units=ONE)
+check("...a binding peak floor releases it (2000 W, no contradiction), "
+      "which at N=1 would otherwise be `lo` 2000 > `hi` 0 and a 0 W stop",
+      _r1p.target_w == 2000.0 and not _r1p.contradiction
+      and _r1p.deciding_priority == P_PEAK)
+_r1a = resolve(_one + [Claim.set("arbitrage", P_ARBITRAGE, -3000.0)],
+               units=ONE)
+check("...a trade (30) stays inside it", _r1a.target_w == 0.0)
+_r1f = resolve([Claim.limit(MODE_SOURCE, P_MODE, 100.0, 900.0),
+                Claim.set("loop", P_LOOP, -1200.0)], units=ONE)
+check("...and a mode range without 0 W is dropped and reported, never "
+      "obeyed: the target stays the loop's -1200 W",
+      _r1f.target_w == -1200.0 and _r1f.mode_fault is not None)
+check("...and with no mode claim at all, stage 2's answer is untouched "
+      "(the N=1 path with battery modes off)",
+      resolve([Claim.set("loop", P_LOOP, 1200.0)], units=ONE).target_w
+      == 1200.0)
+
+print()
+print("OPT-11 11. a mode gives way only as far as the peak limit needs")
+# Review of PR #149. The first cut released the modes only when a limit above
+# P_MODE bound S. A trade (30) that won above the peak floor then kept the
+# modes, and the units placed less than the floor: the mode beat the peak
+# guard (a billed peak). And a peak limit that merely capped a charge released
+# the modes, so an Off battery was charged from the grid. The rule now: clamp
+# into what the modes can place, then back into the limits above the mode.
+_offb = {"inverter-b": (0.0, 0.0)}
+
+
+def _placed(r):
+    return sum(r.shares.values())
+
+
+_ra = resolve(_two(0.0, arb=3000.0, peak_lo=2000.0, rating=1500.0,
+                   modes=_offb)[:-1] + [
+    Claim.set("arbitrage", P_ARBITRAGE, 3000.0),
+    Claim.limit("peak", P_PEAK, lo=2000.0)], units=TWO)
+print(f"    trade 3000 W over a 2000 W floor, A 1500 W, B off: {_ra.shares}")
+check("⭐ a trade above the peak floor with B Off: the units still place the "
+      "floor (2000 W), A to its rating and B only the 500 W A cannot give",
+      _placed(_ra) == 2000 and _ra.shares == {"inverter-a": 1500,
+                                               "inverter-b": 500})
+_r1t = resolve(_one + [Claim.set("arbitrage", P_ARBITRAGE, 3000.0),
+                       Claim.limit("peak", P_PEAK, lo=2000.0)], units=ONE)
+check("⭐ ...and at N=1 an Off battery under a trade gives the peak floor "
+      "(2000 W), not 0 W", _r1t.target_w == 2000.0
+      and _r1t.bound_by == "peak")
+_rc = resolve(_two(0.0, arb=-3000.0, peak_lo=-1000.0, modes=_offb),
+              units=TWO)
+check("⭐ a grid charge the peak limit caps at 1000 W does not release B's "
+      "Off: A takes it all and B stays at 0 W",
+      _rc.shares == {"inverter-a": -1000, "inverter-b": 0})
+_r1c = resolve(_one + [Claim.set("arbitrage", P_ARBITRAGE, -3000.0),
+                       Claim.limit("peak", P_PEAK, lo=-1000.0)], units=ONE)
+check("...and at N=1 an Off battery is not charged from the grid under a "
+      "capped trade", _r1c.target_w == 0.0)
+_rp = resolve(_two(500.0, peak_lo=1500.0, modes=_offb), units=TWO)
+check("a peak floor A can carry alone leaves B Off at 0 W",
+      _rp.shares == {"inverter-a": 1500, "inverter-b": 0}
+      and _rp.target_w == 1500.0)
+_rall = resolve(_two(0.0, peak_lo=3000.0,
+                     modes={"inverter-a": (0.0, 0.0),
+                            "inverter-b": (0.0, 0.0)}), units=TWO)
+check("every battery Off and a 3000 W peak floor: the floor is placed, "
+      "split between them, and nothing contradicts",
+      _placed(_rall) == 3000 and not _rall.contradiction
+      and _rall.allocation.refused is None)
+
+import random as _rnd                                           # noqa: E402
+_g = _rnd.Random(149)
+_worse, _needless, _sign, _nn = [], [], [], 0
+for _ in range(20000):
+    _units = ("inverter-a", "inverter-b", "inverter-c")[:_g.choice((2, 3))]
+    _cl = []
+    for _u in _units:
+        _rt = _g.choice((1000.0, 2500.0))
+        _cl.append(Claim.limit("supervised", P_SAFETY, -_rt, _rt,
+                               actuator=_u))
+        if _g.random() < 0.2:
+            _cl.append(Claim.limit("pack", P_SAFETY,
+                                   *_g.choice(((0.0, inf), (-inf, 0.0))),
+                                   actuator=_u))
+        _cl.append(Claim.limit(MODE_SOURCE, P_MODE,
+                               _g.choice((0.0, -_rt)), _g.choice((0.0, _rt)),
+                               actuator=_u))
+    _src = _g.choice(("loop", "arbitrage"))
+    _cl.append(Claim.set(_src, P_LOOP if _src == "loop" else P_ARBITRAGE,
+                         _g.uniform(-7000.0, 7000.0)))
+    _pk = _g.uniform(-4000.0, 6000.0)
+    _cl.append(Claim.limit("peak", P_PEAK, lo=_pk))
+    _r = resolve(_cl, units=_units)
+    _r0 = resolve([c for c in _cl if c.source != MODE_SOURCE], units=_units)
+    _nn += 1
+    if _r.allocation.refused is not None:
+        _sign.append(_cl)
+        continue
+    if _placed(_r) < _pk - 1 and _placed(_r0) >= _pk - 1:
+        _worse.append(_cl)
+    # An Off unit gives power only when the peak floor is short without it.
+    _off = [c.actuator for c in _cl if c.source == MODE_SOURCE
+            and c.lo == 0.0 and c.hi == 0.0]
+    # What the units whose mode lets them give power can give, within it.
+    _on_cap = sum(max(0.0, min(_r.unit_bounds[u].hi, _r.unit_bounds[u].mode_hi))
+                  for u in _units if _r.unit_bounds[u].mode_hi > 0.0
+                  and _r.unit_bounds[u].lo <= 0.0)
+    if any(_r.shares.get(u, 0) > 0 for u in _off) and _pk <= _on_cap - 1:
+        _needless.append(_cl)
+check(f"over {_nn} random N=2/3 cycles (modes, packs, a trade or the loop, a "
+      f"peak floor): no split is refused, the placed power never falls under "
+      f"the floor where the same cycle without modes met it, and an Off "
+      f"battery gives power only when the others cannot carry the floor "
+      f"({len(_sign)}, {len(_worse)}, {len(_needless)})",
+      not _sign and not _worse and not _needless)
+
 print()
 if fails:
     print(f"{len(fails)} FAILED: {', '.join(fails)}")

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

@@ -0,0 +1,434 @@
+"""UX-13 P3: the Batteries screen and Settings, Simple.  `python3 test_batteries_screen.py`
+
+1. Each battery's Now, Today and Why lines, in English and Dutch, for the six
+   states the brief names: modes off, modes on, a battery Off, an Off battery
+   giving way to the peak limit, a refusal hold, and the monthly cycle.
+2. The OPT-11 P1 test's F2 contradictions stay gone: a battery that moves
+   power never reads "0 W" beside it, the Off help names no watts, and no
+   battery line says the peak limit "holds back" a battery it asks for power.
+3. The plan leaves an Off battery out, except for the peak limit.
+4. `battery_why()` is pure and picks the most urgent reason first.
+5. The screen's `/action` round trips over the real web app: the switch and
+   the mode list post `pack_use` and `pack_mode`, `/status` shows the result
+   in both languages, and a refused value comes back as a plain 400.
+6. The page: the cards, the Simple view and its fields come from the layout
+   table and ui_text, and the scripts post only the existing actions.
+7. The screen changes no control path: homeview.py reads the controller and
+   calls nothing that writes, and the page adds no /action value.
+The headless-browser check is in the PR, not in CI (the CI image has no
+browser). Mutating a module this file grades? Read MUTATION.md first.
+"""
+
+import ast
+import asyncio
+import io
+import json
+import os
+import re
+import socket
+import sys
+from datetime import datetime, timedelta, timezone
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.join(HERE, "tools"))
+
+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.maintenance import IDLE, DRAIN                         # noqa: E402
+
+fails = []
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+def words(lang):
+    with io.open(os.path.join(HERE, "app", "ui_text", f"{lang}.json"),
+                 encoding="utf-8") as f:
+        return json.load(f)
+
+
+EN, NL = words("en"), words("nl")
+B_NAME = D.OPTS["inverters"][1]["name"]
+LANGS = {"en": EN, "nl": NL}
+
+
+# The fixture's prices are for the day it is built, so the plan depends on
+# the hour. Pin the clock (review of #150: unpinned, this file failed every
+# morning): the fixture is built at 00:15 on 2026-09-28, Brussels time. Part 1
+# looks at 23:30, when the day's trades and cycle start are past, and part 3
+# at 00:30, with all of them ahead.
+_BUILT = datetime(2026, 9, 27, 22, 15, tzinfo=timezone.utc)
+
+
+class _Clock(datetime):
+    @classmethod
+    def now(cls, tz=None):
+        return _BUILT.astimezone(tz) if tz else _BUILT.replace(tzinfo=None)
+
+
+D.datetime = _Clock
+_DAY0 = homeview.local_day(_BUILT)[0]
+EVENING = _DAY0 + timedelta(hours=23, minutes=30)
+MORNING = _DAY0 + timedelta(minutes=30)
+
+
+def build(state, lang="en", c=None, now=None):
+    c = c or D.controller(state)
+    s = c.status_payload()
+    return homeview.build(c, level=s["level"], checks=s["checks"], lang=lang,
+                          now=now or EVENING)
+
+
+# The six states and what each battery's Why line must be.
+WANT = {
+    "running": ("modes_off", "modes_off"),
+    "modes": ("solar_first", "leftover"),
+    "off": ("solar_first", "off"),
+    "off_peak": ("peak", "off_peak"),
+    "refusal": ("refuses_give", "other_refuses"),
+    "maint": ("cycle_mode", "leftover"),
+}
+
+# ============================================================================ #
+print("1. Now, Today and Why per battery, English and Dutch")
+ROWS = {(st, lang): build(st, lang) for st in WANT for lang in LANGS}
+for st, want in WANT.items():
+    got = tuple(b["why_key"] for b in ROWS[(st, "en")]["batteries"])
+    en = ROWS[(st, "en")]["batteries"]
+    nl = ROWS[(st, "nl")]["batteries"]
+    print(f"    {st}: " + " / ".join(f"{b['now']} | {b['why']} | "
+                                     f"{b['today_line'] or b['today']}"
+                                     for b in en))
+    check(f"{st}: the Why lines are {want}, in each language's own words",
+          got == want
+          and all(b["why"] == homeview.uitext.say(
+              W["home_words"]["why"][b["why_key"]],
+              name=D.OPTS["inverters"][0]["name"])
+              for W, rows in ((EN, en), (NL, nl)) for b in rows))
+    check(f"{st}: every battery has a Now, a Why and a Today, and the Dutch "
+          f"lines differ from the English",
+          all(b["now"] and b["why"] and (b["today"] or b["today_line"])
+              for b in en + nl)
+          and all(e["why"] != n["why"] and e["now"] != n["now"]
+                  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",
+      _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"]))
+_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
+      and all("mode_key" not in b and "use" not in b
+              and b["today_line"] == EN["home_words"]["today"]["house"]
+              for b in _off["batteries"]))
+_b = ROWS[("off", "en")]["batteries"][1]
+check("a battery Off: 'Off. Resting now.', 'You switched it off.', and no "
+      "monthly cycle today", (_b["mode_key"], _b["now"], _b["why"],
+                              _b["today_line"])
+      == ("off", EN["home_words"]["now"]["off_resting"],
+          EN["home_words"]["why"]["off"], EN["home_words"]["today"]["off"]))
+_b = ROWS[("off_peak", "en")]["batteries"][1]
+_bn = ROWS[("off_peak", "nl")]["batteries"][1]
+check("Off giving way to the peak limit says so plainly, with the figure: "
+      "'Off, but gives 0.5 kW for the peak limit.'",
+      _b["now"] == "Off, but gives 0.5 kW for the peak limit."
+      and _bn["now"] == "Uit, maar levert 0,5 kW voor de piekgrens."
+      and _b["why"] == EN["home_words"]["why"]["off_peak"])
+_a, _b = ROWS[("refusal", "en")]["batteries"]
+check("a refusal hold: the refusing battery says it refuses and when it "
+      "tries again, the other says it takes over",
+      _a["why"] == EN["home_words"]["why"]["refuses_give"]
+      and _b["why"] == "Battery A refuses to give power, so this battery "
+                       "takes over.")
+_a = ROWS[("maint", "en")]["batteries"][0]
+check("maintenance: the cycle comes first, the mode resumes after, and Today "
+      "shows the cycle block", _a["maintenance"] == DRAIN
+      and _a["why"] == EN["home_words"]["why"]["cycle_mode"]
+      and [r["kind"] for r in _a["today"]] == ["cycle"])
+_sh = build("shadow")["batteries"]
+_al = build("alarm")["batteries"]
+check("shadow mode and an alarm: Why says which, and Today plans nothing "
+      "the add-on does not do",
+      all(b["why_key"] == "shadow" and b["today_line"]
+          == EN["home_words"]["today"]["house_would"] for b in _sh)
+      and all(b["why_key"] == "held" and b["today_line"]
+              == EN["home_words"]["today"]["held"] for b in _al))
+
+# ============================================================================ #
+print("\n2. the OPT-11 P1 test's F2: no line contradicts the power shown")
+ZERO = re.compile(r"\b0 W\b")
+GOING = (EN["home_words"]["zero_going"], NL["home_words"]["zero_going"],
+         "going to 0 W", "gaat naar 0 W")
+_bad = []
+for (st, lang), payload in sorted(ROWS.items()):
+    for b in payload["batteries"]:
+        moving = b["power_w"] is not None and abs(b["power_w"]) > homeview.IDLE_W
+        if moving and b.get("maintenance", IDLE) == IDLE:
+            kw = homeview._dec(f"{abs(b['power_w']) / 1000:.1f}")
+            kw = kw.replace(".", ",") if lang == "nl" else kw
+            if kw not in b["now"]:
+                _bad.append(f"{st}/{lang}/{b['name']}: no figure in {b['now']!r}")
+            for line in (b["now"], b["why"]):
+                if ZERO.search(line) and not any(g in line for g in GOING):
+                    _bad.append(f"{st}/{lang}/{b['name']}: 0 W beside power: "
+                                f"{line!r}")
+        if "held back" in b["why"] or "tegengehouden" in b["why"]:
+            _bad.append(f"{st}/{lang}/{b['name']}: {b['why']!r}")
+print(f"    {_bad}")
+check("a battery that moves power shows the figure, and no line beside it "
+      "says 0 W", not _bad)
+check("the Off help names no watts, in either language, and says the peak "
+      "limit may use the battery",
+      all(not ZERO.search(W["home"]["batteries"]["choice"]["off"]
+                          ["description"]) for W in LANGS.values())
+      and "peak limit" in EN["home"]["batteries"]["choice"]["off"]
+      ["description"])
+_going = homeview.battery_now(62, 900, phase=IDLE, shadow=False, running=True,
+                              off=True, peak=False)
+check("an Off battery still moving without the peak limit reads 'going to "
+      "0 W' with its figure, never a bare 0 W",
+      _going == "Off. Still at 0.9 kW, going to 0 W.")
+
+# ============================================================================ #
+print("\n3. the plan leaves an Off battery out, except for the peak limit")
+_c = D.controller("off")
+_c.maints[1].cfg = _c.maints[0].cfg      # both due, so both would be drawn
+_p = build("off", c=_c)
+_kinds = {i: {r["kind"] for r in _p["plan"]["runs"] if r["battery"] == i}
+          for i in (0, 1)}
+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)
+_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]
+      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 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",
+      {r["kind"] for r in _p["plan"]["runs"] if r["battery"] == 1}
+      == {"peak"})
+# Review: an Off battery that A covers alone rests, so it gets no peak block,
+# and a card never says "every battery gives" beside it.
+_c = D.controller("off_peak")
+_c.inverters[1].batt = 0.0
+_p = build("off_peak", c=_c)
+_a, _b = _p["batteries"]
+check("peak limit covered by A alone: Off B rests, has no peak block, and "
+      "A's Why does not claim every battery gives",
+      _b["why_key"] == "off" and _b["now"] == EN["home_words"]["now"]
+      ["off_resting"] and not _b["today"]
+      and {r["kind"] for r in _p["plan"]["runs"] if r["battery"] == 0}
+      >= {"peak"} and _a["why_key"] == "peak"
+      and "every" not in _a["why"] and "elke" not in
+      build("off_peak", "nl", c=_c)["batteries"][0]["why"])
+# Review: a blind or floor-limited guard is engaged with a 0 W floor. It
+# forbids charging only, so no battery gives power for it.
+_bad = []
+for _kw in (dict(blind="meter gap"), dict(floor_limited=True)):
+    _c = D.controller("off_peak")
+    _c.peak_guard = homeview.peakguard.PeakDecision(
+        engaged=True, floor_w=0.0, ceiling_w=3500.0, ceiling_from="cap",
+        projected_w=None, **_kw)
+    _c.inverters[1].batt = 300.0          # B still going to 0 W
+    _p = build("off_peak", c=_c)
+    _a, _b = _p["batteries"]
+    if (_a["why_key"] == "peak" or _b["why_key"] == "off_peak"
+            or "peak limit" in _b["now"]
+            or any(r["kind"] == "peak" for r in _p["plan"]["runs"])):
+        _bad.append((_kw, _a["why_key"], _b["why_key"], _b["now"]))
+print(f"    {_bad}")
+check("a blind or floor-limited peak guard (floor 0 W) draws no peak block "
+      "and no line says the peak limit takes power", not _bad)
+
+# ============================================================================ #
+print("\n4. battery_why(): pure, most urgent first")
+BASE = dict(modes_on=True, mode=packmode.SOLAR_FIRST, off=False, reading=True,
+            phase=IDLE, shadow=False, running=True, held=False, refused=0,
+            peak=False, giving=False, sf_ahead=False)
+
+
+def why(**kw):
+    return homeview.battery_why(**dict(BASE, **kw))
+
+
+_cases = [
+    (dict(reading=False, held=True), "no_reading"),
+    (dict(held=True, shadow=True), "held"),
+    (dict(running=False, off=True), "stopped"),
+    (dict(shadow=True, phase=DRAIN), "shadow"),
+    (dict(phase=DRAIN, off=True), "cycle_mode"),
+    (dict(phase=DRAIN, modes_on=False), "cycle"),
+    (dict(off=True, peak=True, giving=True), "off_peak"),
+    (dict(off=True, peak=True, giving=False), "off"),   # charging or resting
+    (dict(off=True, giving=True), "off"),
+    (dict(refused=1, peak=True), "refuses_give"),
+    (dict(refused=-1), "refuses_charge"),
+    (dict(peak=True, giving=True, other_refuses="B"), "peak"),
+    (dict(giving=True, other_refuses="B", modes_on=False), "other_refuses"),
+    (dict(modes_on=False, giving=True), "modes_off"),
+    (dict(giving=True, mode=packmode.LEFTOVER_SOLAR), "covers_house"),
+    (dict(mode=packmode.LEFTOVER_SOLAR, sf_ahead=True), "leftover"),
+    (dict(mode=packmode.LEFTOVER_SOLAR), "leftover_alone"),
+    ({}, "solar_first"),
+]
+_wrong = [(kw, want, why(**kw)) for kw, want in _cases if why(**kw) != want]
+print(f"    {_wrong}")
+check(f"{len(_cases)} cases, each the expected reason", not _wrong)
+check("every reason it can return has words in both languages",
+      {w for _k, w in _cases} == set(EN["home_words"]["why"])
+      == set(NL["home_words"]["why"]))
+
+# ============================================================================ #
+print("\n5. /action round trips from the screen, over the real web app")
+
+
+async def _serve(state, calls):
+    c = D.controller(state)
+    stored = dict(D.defaults(D.CONFIG), **D.OPTS)
+    runner = aioweb.AppRunner(web.build_app(c, D.Supervisor(stored)))
+    await runner.setup()
+    sock = socket.socket()
+    sock.bind(("127.0.0.1", 0))
+    port = sock.getsockname()[1]
+    sock.close()
+    await aioweb.TCPSite(runner, "127.0.0.1", port).start()
+    out = []
+    try:
+        async with aiohttp.ClientSession() as s:
+            root = f"http://127.0.0.1:{port}/"
+            for body, lang in calls:
+                if body is not None:
+                    async with s.post(root + "action", json=body) as r:
+                        out.append((r.status,
+                                    await r.json(content_type=None)))
+                async with s.get(root + "status?lang=" + lang) as r:
+                    out.append((r.status, await r.json(content_type=None)))
+    finally:
+        await runner.cleanup()
+    return out
+
+
+A, B = (i["name"] for i in D.OPTS["inverters"])
+# Exactly what app.js posts: {action, unit, value}.
+_r = asyncio.run(_serve("modes", [
+    ({"action": "pack_use", "unit": B, "value": False}, "en"),
+    ({"action": "pack_mode", "unit": A, "value": packmode.LEFTOVER_SOLAR},
+     "nl"),
+    ({"action": "pack_use", "unit": B, "value": True}, "en"),
+    ({"action": "pack_mode", "unit": A, "value": "cheap_hours"}, "en"),
+]))
+(_s1, _j1), (_, _st1), (_s2, _j2), (_, _st2), (_s3, _), (_, _st3), \
+    (_s4, _j4), (_, _st4) = _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"
+      and _st1["batteries"][1]["why"] == EN["home_words"]["why"]["off"])
+check("set A to Leftover solar: 200, and /status?lang=nl shows it in Dutch",
+      _s2 == 200 and _st2["batteries"][0]["mode_choice"]
+      == packmode.LEFTOVER_SOLAR
+      and _st2["batteries"][0]["mode"]
+      == NL["home_words"]["modes"]["leftover_solar"])
+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)
+_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, "
+      "and the batteries stay on", _r[0][0] == 400 and _r[0][1]["error"]
+      and "mode_key" not in _r[1][1]["batteries"][1])
+
+# ============================================================================ #
+print("\n6. the page")
+PAGE = web.page()
+JS = io.open(os.path.join(HERE, "app", "static", "app.js"),
+             encoding="utf-8").read()
+SJS = io.open(os.path.join(HERE, "app", "static", "settings.js"),
+              encoding="utf-8").read()
+check("the Batteries screen has its cards, the modes-off card and 'How the "
+      "modes work'", all(f'id="{i}"' in PAGE for i in
+                         ("bcards", "batt-off", "batt-how", "batt-banner")))
+check("Settings has a Simple / Installer choice as a radio group, and Simple "
+      "comes first", re.search(r'id="set-view"[^>]*>\s*<button[^>]*'
+                               r'data-v="simple"', PAGE) is not None
+      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)
+      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)
+_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"]
+           if f.get("simple")]
+check("Settings, Simple draws the fields the layout marks, and each note "
+      "has words in both languages",
+      sorted(f["key"] for f in _simple)
+      == sorted(f.key for g in L.GROUPS for p in g.parts for f in p.fields
+                if f.simple)
+      and all(f["note"] in EN["settings"]["simple"]["note"]
+              and f["note"] in NL["settings"]["simple"]["note"]
+              for f in _simple if f["note"]))
+check("settings.js picks them by the `simple` flag and names no option key",
+      "f.simple" in SJS and not any(f'"{f.key}"' in SJS for g in L.GROUPS
+                                    for p in g.parts for f in p.fields))
+
+# ============================================================================ #
+print("\n7. no control path changes: the screen reads, it does not write")
+SRC = io.open(os.path.join(HERE, "app", "homeview.py"), encoding="utf-8").read()
+WRITES = {"set_number", "store_set", "set", "set_time", "handle_action",
+          "log_event", "abort", "tick", "publish", "call", "write",
+          "_pack_action", "_maint_stop_off"}
+_calls = sorted({n.func.attr for n in ast.walk(ast.parse(SRC))
+                 if isinstance(n, ast.Call)
+                 and isinstance(n.func, ast.Attribute)
+                 and n.func.attr in WRITES})
+check(f"homeview.py calls nothing that writes state or commands an inverter "
+      f"({_calls})", not _calls)
+_imports = sorted({(n.module or "") for n in ast.walk(ast.parse(SRC))
+                   if isinstance(n, ast.ImportFrom)})
+check(f"...and imports no module that sends power requests ({_imports})",
+      not {"main", "inverter", "hass", "control", "allocator",
+           "arbiter"} & {m.lstrip(".") for m in _imports})
+_c = D.controller("off_peak")
+_before = (json.dumps(_c.store.data, sort_keys=True, default=str),
+           [(i.last_write, i.target) for i in _c.inverters])
+for lang in LANGS:
+    build("off_peak", lang, c=_c)
+check("building the screen twice leaves the store and every power request "
+      "as it was", _before
+      == (json.dumps(_c.store.data, sort_keys=True, default=str),
+          [(i.last_write, i.target) for i in _c.inverters]))
+
+print()
+if fails:
+    print(f"{len(fails)} FAILED")
+    sys.exit(1)
+print("all passed")

goodwe_controller/test_control.py

@@ -1156,6 +1156,142 @@ check("...while the GAIN does own it: 0.6 -> 0.3 -> 0.2 falls monotonically, at
       _R["gain03"]["over"] < _R["rail"]["over"]
       and _R["gain02"]["over"] < _R["gain03"]["over"])
 
+print()
+print("OPT-11: the loop is told what the battery modes allow")
+# compute(bound=(lo, hi)) is the site output bound: the sum over live units of
+# (hard limits with the mode applied), allocator.loop_bound(). Without it the
+# loop asks for watts no battery may give, the allocator reports them unmet,
+# and the saturation freeze parks the target on them (SAFETY-73 section 1).
+import random as _random                     # noqa: E402
+from app.control import MODE_BOUND           # noqa: E402
+from named_absence import present            # noqa: E402
+
+TB = Tuning(gain=0.6, max_w=5000.0, slew_w=400.0, deadband_w=15.0,
+            step_w=10, target_grid_w=-10.0)
+
+
+def closed_loop(cycles, load, *, bound=None, deliver=None, change=None):
+    """A plant that follows 94 % of the command each cycle, capped at
+    `deliver` (what the allocator can place). `change(i)` may return a new
+    bound. Rows: (command, actual, sat_count, frozen, reason, i_w)."""
+    prev, actual, sat, i_w, rows = 0.0, 0.0, 0, None, []
+    for i in range(cycles):
+        if change is not None:
+            bound = change(i, bound)
+        d = compute(prev, load - actual, actual, TB, sat, i_w, bound=bound)
+        prev, sat, i_w = d.target_w, d.sat_count, d.i_w
+        cmd = prev if deliver is None else max(deliver[0],
+                                                min(deliver[1], prev))
+        actual = actual + 0.94 * (cmd - actual)
+        rows.append((prev, actual, sat, d.frozen, d.reason, d.i_w))
+    return rows
+
+
+# (a) One battery may give 800 W (the other is Off), the house takes 3000 W.
+_with = closed_loop(40, 3000.0, bound=(-800.0, 800.0))
+_without = closed_loop(40, 3000.0, deliver=(-800.0, 800.0))
+print(f"    house 3000 W, modes allow 800 W: with the bound the command ends "
+      f"at {nth(_with, -1)[0]:.0f} W (sat {max(r[2] for r in _with)}, reason "
+      f"{nth(_with, -1)[4]}); without it {nth(_without, -1)[0]:.0f} W with "
+      f"{sum(r[3] for r in _without)} frozen cycles")
+check("⭐ THE LOOP BOUND HOLDS: every command and every integrator value "
+      "stays inside [-800, 800], and the command settles at the bound",
+      all(-800.0 <= r[0] <= 800.0 and -800.0 <= r[5] <= 800.0 for r in _with)
+      and present(nth(_with, -1)) and nth(_with, -1)[0] == 800.0
+      and nth(_with, -1)[4] == MODE_BOUND)
+_big = []
+_pv, _iw, _sat = 0.0, None, 0
+for _i in range(30):
+    _d = compute(_pv, 12000.0, _pv, TB, _sat, _iw, bound=(-800.0, 800.0))
+    _pv, _iw, _sat = _d.target_w, _d.i_w, _d.sat_count
+    _big.append(_d)
+check("...and a house far beyond what the modes allow (12 kW against 800 W) "
+      "does not read as the loop winding into its rail: SAFETY-03's flags "
+      "stay false on every cycle",
+      _big and not any(d.i_clamped or d.clamped for d in _big)
+      and all(d.target_w <= 800.0 for d in _big))
+check("⭐ NO SATURATION FREEZE from unmet watts: sat_count never reaches the "
+      "freeze and no cycle is frozen",
+      not any(r[3] for r in _with)
+      and max(r[2] for r in _with) < TB.saturation_cycles)
+check("...and the same site WITHOUT the bound is the failure it removes: the "
+      "loop asks past 800 W, the plant cannot follow and the freeze engages",
+      any(r[3] for r in _without) and max(r[0] for r in _without) > 800.0)
+
+# (b) Every battery switched off: the bound is [0, 0].
+_off = closed_loop(20, 2500.0, bound=(0.0, 0.0))
+check("all batteries off: the loop asks 0 W on every cycle, with the "
+      "integrator at 0, and never freezes",
+      all(r[0] == 0.0 and r[5] == 0.0 and not r[3] for r in _off))
+
+# (c) A mode closes while the battery gives 2000 W: the ask drops at once.
+_close = closed_loop(30, 2000.0, bound=(-5000.0, 5000.0),
+                     change=lambda i, b: (0.0, 0.0) if i >= 20 else b)
+check("a mode that closes mid-run drops the ask to 0 W on the same cycle "
+      "(no slew steps of unmet watts) and carries no integrator past it",
+      present(nth(_close, 20)) and nth(_close, 19)[0] > 1500.0
+      and nth(_close, 20)[0] == 0.0
+      and nth(_close, 20)[5] == 0.0 and not any(r[3] for r in _close[20:]))
+
+# (d) Rounding never steps outside the bound.
+_q = compute(1000.0, 3000.0, 1000.0, TB, 0, 1236.0, bound=(-5000.0, 1236.0))
+check("quantising to 10 W does not step outside the bound: 1236 W becomes "
+      "1230 W, not 1240 W", _q.target_w == 1230.0)
+_qn = compute(-1000.0, -3000.0, -1000.0, TB, 0, -1236.0,
+              bound=(-1236.0, 5000.0))
+check("...on the charge side too: -1236 W becomes -1230 W",
+      _qn.target_w == -1230.0)
+
+# (e) A bound that leaves out 0 W is a fault and is not obeyed.
+_rngc = _random.Random(1131)
+_same, _nb = True, 0
+for _ in range(4000):
+    args = (_rngc.uniform(-5000, 5000), _rngc.uniform(-4000, 4000),
+            _rngc.uniform(-5000, 5000), TB, _rngc.randint(0, 5),
+            _rngc.choice((None, _rngc.uniform(-6000, 6000))))
+    _nb += 1
+    if (compute(*args, bound=(200.0, 900.0)) != compute(*args)
+            or compute(*args, bound=None) != compute(*args)):
+        _same = False
+check(f"a bound that leaves out 0 W is ignored, and bound=None is the law as "
+      f"it was: {_nb} random cycles give the identical Decision",
+      _same and _nb == 4000)
+
+# (f) Inside the bound nothing changes: a bound wider than every command.
+_wide = True
+for _ in range(4000):
+    args = (_rngc.uniform(-4000, 4000), _rngc.uniform(-3000, 3000),
+            _rngc.uniform(-4000, 4000), TB, _rngc.randint(0, 5),
+            _rngc.choice((None, _rngc.uniform(-4000, 4000))))
+    if compute(*args, bound=(-9000.0, 9000.0)) != compute(*args):
+        _wide = False
+check("a bound wider than the rail changes no Decision (4000 random cycles)",
+      _wide)
+
+# (g) Review of PR #149: a bound EQUAL to the rail - every battery on, the
+# default once modes are on - must leave SAFETY-03 exactly as it was. Before
+# the fix the mode clamp ran first and took `i_clamped` away from the rail.
+_rail_same, _rail_hits = True, 0
+for _tb in (TB, Tuning(gain=0.6, max_w=5000.0, slew_w=400.0, deadband_w=15.0,
+                       step_w=10, target_grid_w=-10.0,
+                       integrator_max_w=7000.0)):
+    _lim = _tb.max_w
+    for _ in range(4000):
+        args = (_rngc.uniform(-5000, 5000), _rngc.uniform(-12000, 12000),
+                _rngc.uniform(-5000, 5000), _tb, _rngc.randint(0, 5),
+                _rngc.choice((None, _rngc.uniform(-8000, 8000))))
+        _d0 = compute(*args)
+        _rail_hits += _d0.i_clamped
+        if compute(*args, bound=(-_lim, _lim)) != _d0:
+            _rail_same = False
+check(f"a bound equal to the rail changes no Decision, SAFETY-03's i_clamped "
+      f"included ({_rail_hits} of 8000 random cycles wind into the rail), and "
+      f"with integrator_max_w above max_w too", _rail_same and _rail_hits > 100)
+_one_side = compute(4000.0, 12000.0, 4000.0, TB, 0, 4990.0,
+                    bound=(0.0, 5000.0))
+check("...and a bound that closes only the other side still lets the rail "
+      "flag a loop winding into it", _one_side.i_clamped)
+
 print()
 if fails:
     print(f"{len(fails)} FAILED: {', '.join(fails)}")

goodwe_controller/test_messages.py

@@ -845,7 +845,8 @@ DATA = {
     "main.py:'cancelled' if task.cancelled() else repr(exc) if exc else 'returned'",
     "main.py:EXIT_CONTROL_DIED", "main.py:first.name", "main.py:OPTIONS_PATH",
     "main.py:err", "main.py:', '.join(sorted(stranded))",
-    "main.py:sorted(on_roster)", "main.py:inv.name",
+    "main.py:sorted(on_roster)", "main.py:inv.name", "main.py:topic_s",
+    "main.py:more",
     "main.py:inv.batt_fresh.bound.release_s", "main.py:inv.batt_fresh.bound.move_w",
     "main.py:inv.batt_fresh.bound.unchanged_s", "main.py:inv.batt_fresh.held",
     "main.py:value", "main.py:float(value)",
@@ -964,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)
@@ -1058,6 +1059,8 @@ TEXT = {
     "main.py:rep.explain()": _migration_texts,
     "store.py:rep.explain()": _migration_texts,
     "main.py:plan.words": _tariff_texts,
+    # OPT-11 P2: why an MQTT command was ignored.
+    "main.py:why": lambda: list(messages.PACK_REFUSED.values()),
     # Families: every builder of the text, as a template.
     "main.py:refusal": lambda: (_static(("main.py", "return", "write_refusal"))
                                 + _static(("allocator.py", "return", "authorises"))),

goodwe_controller/test_modes.py

@@ -0,0 +1,488 @@
+"""Runnable check for OPT-11 P1, battery modes.  `python3 test_modes.py`
+
+Each battery gets an on/off switch and a mode (Solar first, Leftover solar),
+kept in the store and filed as a SOFT unit limit at P_MODE (35). Drives the
+REAL `Controller` (read_inputs + cycle) through tools/opt11_identity.py's
+harness, in simulated time. DECISIONS/OPT-11-battery-modes.md has the record.
+
+1. With battery modes off, every command is byte-identical to release/1.0
+   a5dddad, at one inverter and at two (digests measured on that tree).
+2. Solar order: surplus solar fills the Solar first battery, then spills to the
+   Leftover solar one; a full Solar first battery hands all of it on.
+3. Off: the battery is asked for 0 W, the others carry the site, the loop is
+   bounded and never freezes on watts no battery may give; all off at N=1 and
+   N=2 asks 0 W.
+4. Off stops and skips maintenance, with a log line; a battery in maintenance
+   gets no mode claim.
+5. The actions: `pack_use` and `pack_mode`, what they store, log and refuse.
+6. A mode range without 0 W is dropped as a software fault, logged once.
+7. The Batteries screen's data.
+
+Mutations (MUTATION.md, purged copies, graded over this file and the named
+tests) are listed in the pull request and DECISIONS/OPT-11-battery-modes.md.
+"""
+
+import asyncio
+import logging
+import os
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.join(HERE, "tools"))
+
+import opt11_identity as rig                                   # noqa: E402
+from named_absence import nth, present                         # noqa: E402
+import app.main as app_main                                    # noqa: E402
+from app import homeview, messages, packmode                   # noqa: E402
+from app.control import MODE_BOUND                             # noqa: E402
+from app.maintenance import DRAIN, IDLE                        # 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)
+
+
+ON = {"battery_modes_enabled": True}
+A, B = "inverter-a", "inverter-b"
+
+
+def store_with(**modes):
+    """A store where each named battery has (use, mode)."""
+    s = rig._Store()
+    for name, (use, mode) in modes.items():
+        s.data[unit_key(name, packmode.USE_KEY)] = use
+        s.data[unit_key(name, packmode.MODE_KEY)] = mode
+    return s
+
+
+def spy_claims():
+    """Record every claim list main.py's own `resolve` is handed."""
+    seen, real = [], app_main.resolve
+
+    def _spy(claims, **kw):
+        seen.append(list(claims))
+        return real(claims, **kw)
+    app_main.resolve = _spy
+    return seen, lambda: setattr(app_main, "resolve", real)
+
+
+def spy_bounds():
+    """Record the `bound` main.py hands `compute()` on every cycle."""
+    seen, real = [], app_main.compute
+
+    def _spy(*a, **kw):
+        seen.append(kw.get("bound", "absent"))
+        return real(*a, **kw)
+    app_main.compute = _spy
+    return seen, lambda: setattr(app_main, "compute", real)
+
+
+def flat(t):
+    return 0.0
+
+
+# ============================================================================ #
+print("1. battery modes off: byte-identical to release/1.0 a5dddad")
+# The digests below were printed by `python3 tools/opt11_identity.py` run on
+# the a5dddad tree (the same file copied in, nothing else changed), in the CI
+# image, on 2026-09-28. Each hashes 540 cycles: site target, every inverter's
+# written value, the loop's reason, integrator and saturation count, the
+# arbiter's sentence and the allocation record.
+A5DDDAD = {
+    "n1": "fc3bca170c46920f08d86baee62ea883954a89ea6222d6bbf7d6652877226262",
+    "n2": "a60003b1930fa3cba21f3220670d9172b9ff438347d77ba9bc3383fca1ceb15a",
+    "n1_off": "fc3bca170c46920f08d86baee62ea883954a89ea6222d6bbf7d6652877226262",
+    "n2_off": "a60003b1930fa3cba21f3220670d9172b9ff438347d77ba9bc3383fca1ceb15a",
+    # Added in review (PR #149), printed on a5dddad the same way: both
+    # batteries due for maintenance, and the arbiter alone on 6000 seeded
+    # claim lists with the peak floor, trades, maintenance and refusals.
+    "n1_maint": "5a21d43ec7cbf95a224bbb9bca13a8e62a00161101b586ae9fa68ab565992977",
+    "n2_maint": "48a1ad96121592e207a4664fb2da9f5208a49b88e5802a358873a5d30cb8c18e",
+    "resolve": "43a874216711936e14b9185bcc8d26c58fe4f3cfc3c1c8eaf89bffd95d6e81ef",
+}
+_claims, _undo_c = spy_claims()
+_bounds, _undo_b = spy_bounds()
+try:
+    _now = rig.digests()
+finally:
+    _undo_c()
+    _undo_b()
+for k in A5DDDAD:
+    print(f"    {k:7} {'same' if _now[k] == A5DDDAD[k] else 'DIFFERS'} "
+          f"{_now[k][:16]}")
+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)
+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)
+      and _bounds and set(_bounds) == {None})
+
+
+# ============================================================================ #
+print("\n2. the solar order: Solar first fills, the rest spills to Leftover")
+_surplus = (lambda t: -3200.0)          # 3200 W more solar than the house uses
+_full_a = (lambda u, t: 100.0 if (u == "a" and t >= 300) else 50.0)
+_rows, _c = rig.run(2, extra=ON, dur=600.0, load=_surplus, soc=_full_a,
+                    cut=lambda u, t: False,
+                    store=store_with(**{A: (True, packmode.SOLAR_FIRST),
+                                        B: (True, packmode.LEFTOVER_SOLAR)}))
+_room = [r for r in _rows if 200 <= r[0] < 300]
+_full = [r for r in _rows if r[0] >= 500]
+
+
+def _cmd(r):
+    """One row's written values, by battery; ABSENTs if the row is missing."""
+    return (dict(r[2]) if present(r)
+            else {"a": nth((), 0, "a"), "b": nth((), 0, "b")})
+
+
+print(f"    A has room: A {_cmd(nth(_room, -1))['a']:+.0f} W, B "
+      f"{_cmd(nth(_room, -1))['b']:+.0f} W | A full: A {_cmd(nth(_full, -1))['a']:+.0f} "
+      f"W, B {_cmd(nth(_full, -1))['b']:+.0f} W")
+check("⭐ while A (Solar first) has room it takes all it can, 2500 W, and B "
+      "(Leftover solar) gets only the spill, about 700 W",
+      present(nth(_room, -1))
+      and all(_cmd(r)["a"] == -2500.0 and -800.0 <= _cmd(r)["b"] <= -600.0
+              for r in _room))
+check("⭐ once A is full, the surplus spills to B, up to B's rating",
+      present(nth(_full, -1))
+      and all(_cmd(r)["a"] == 0.0 and _cmd(r)["b"] == -2500.0 for r in _full))
+_rows_off, _ = rig.run(2, dur=300.0, load=_surplus,
+                       soc=lambda u, t: 50.0, cut=lambda u, t: False)
+check("...and the same site with battery modes off splits 50/50, which is "
+      "what says the order above comes from the modes",
+      _cmd(_rows_off[-1])["a"] == _cmd(_rows_off[-1])["b"] < -1500.0)
+_give = rig.run(2, extra=ON, dur=300.0, load=lambda t: 3000.0,
+                soc=lambda u, t: 50.0, cut=lambda u, t: False,
+                store=store_with(**{A: (True, packmode.SOLAR_FIRST),
+                                    B: (True, packmode.LEFTOVER_SOLAR)}))[0]
+check("while giving power the modes keep OPT-09's weights: A Solar first and "
+      "B Leftover solar, both half full, share a 3000 W house equally",
+      _cmd(_give[-1])["a"] == _cmd(_give[-1])["b"] > 1400.0)
+
+
+# ============================================================================ #
+print("\n3. Off: 0 W on that battery, the loop bounded, no freeze")
+_rows, _c = rig.run(2, extra=ON, dur=600.0, load=lambda t: 4000.0,
+                    soc=lambda u, t: 50.0, cut=lambda u, t: False,
+                    store=store_with(**{B: (False, packmode.SOLAR_FIRST)}))
+_tail = _rows[40:]
+print(f"    house 4000 W, B off: A {_cmd(_tail[-1])['a']:+.0f} W, B "
+      f"{_cmd(_tail[-1])['b']:+.0f} W, site {_tail[-1][1]:+.0f} W, reason "
+      f"{_tail[-1][3]}, {_tail[-1][7]}")
+check("⭐ B (Off) is asked for 0 W on every cycle and A carries the house up "
+      "to its rating",
+      all(_cmd(r)["b"] == 0.0 for r in _rows)
+      and all(_cmd(r)["a"] == 2500.0 for r in _tail))
+check("⭐ the loop stays inside what the modes allow (2500 W) and never "
+      "freezes: no saturated-freeze reason, and the saturation count stays "
+      "below the freeze",
+      all(r[1] <= 2500.0 for r in _rows)
+      and not any(r[3] == "saturated-freeze" for r in _rows)
+      and max(r[5] for r in _rows) < _c.tuning.saturation_cycles
+      and _tail[-1][3] == MODE_BOUND)
+check("...and nothing is left unmet: the allocation places the whole target",
+      all("UNMET" not in (r[7] or "") for r in _tail))
+_bounds, _undo_b = spy_bounds()
+try:
+    rig.run(2, extra=ON, dur=100.0, load=lambda t: 4000.0,
+            soc=lambda u, t: 50.0, cut=lambda u, t: False,
+            store=store_with(**{B: (False, packmode.SOLAR_FIRST)}))
+finally:
+    _undo_b()
+check("...because main.py hands compute() the loop bound, B's 0 W included: "
+      "[-2500, 2500]", _bounds and set(_bounds) == {(-2500.0, 2500.0)})
+# Review (PR #149): a unit the allocator drops (stale link) must not count in
+# the loop bound either, or the loop asks for watts nobody live can place.
+_rows, _c = rig.run(2, extra=ON, dur=10.0, load=flat, soc=lambda u, t: 50.0,
+                    cut=lambda u, t: False)
+_both = _c.loop_bound([app_main.Claim.limit(
+    "supervised", app_main.P_SAFETY, -2500.0, 2500.0,
+    actuator=_c.actuator_of("supervised", i)) for i in _c.inverters])
+_c.live_units = lambda: (A,)
+_one_live = _c.loop_bound([app_main.Claim.limit(
+    "supervised", app_main.P_SAFETY, -2500.0, 2500.0,
+    actuator=_c.actuator_of("supervised", i)) for i in _c.inverters])
+check("the loop bound counts only live units: both live [-5000, 5000], B's "
+      "link stale [-2500, 2500]",
+      _both == (-5000.0, 5000.0) and _one_live == (-2500.0, 2500.0))
+
+for _n in (1, 2):
+    _st = store_with(**{A: (False, packmode.SOLAR_FIRST),
+                        B: (False, packmode.LEFTOVER_SOLAR)})
+    if _n == 1:
+        _st = rig._Store()
+        _st.data[unit_key(app_main.UNIT_A, packmode.USE_KEY)] = False
+    _rows, _c = rig.run(_n, extra=ON, dur=300.0, load=lambda t: 3000.0,
+                        soc=lambda u, t: 50.0, cut=lambda u, t: False,
+                        store=_st)
+    check(f"every battery off at N={_n}: every command is 0 W, the site "
+          f"target is 0 W, the integrator stays at 0 and nothing freezes",
+          all(all(v == 0.0 for _u, v in r[2]) and r[1] == 0.0 and r[4] == 0.0
+              and r[3] != "saturated-freeze" for r in _rows))
+_rows1, _ = rig.run(1, extra=ON, dur=300.0, load=lambda t: 1800.0,
+                    soc=lambda u, t: 50.0)
+_rows1o, _ = rig.run(1, dur=300.0, load=lambda t: 1800.0,
+                     soc=lambda u, t: 50.0)
+check("at N=1 a battery that is on (Solar first by default) follows the "
+      "house exactly as with battery modes off",
+      [r[:6] for r in _rows1] == [r[:6] for r in _rows1o]
+      and _cmd(_rows1[-1])["a"] > 1700.0)
+
+
+# ============================================================================ #
+print("\n4. Off stops and skips maintenance; maintenance outranks the mode")
+MAINT = {"maintenance_enabled": True, "maintenance_start_hour": 11}
+_st = store_with(**{A: (False, packmode.SOLAR_FIRST)})
+_rows, _c = rig.run(2, extra={**ON, **MAINT}, dur=60.0,
+                    load=lambda t: 500.0, soc=lambda u, t: 60.0,
+                    cut=lambda u, t: False, store=_st)
+print(f"    both due at 11:00, A off: A {_c.maints[0].phase}, "
+      f"B {_c.maints[1].phase}")
+check("⭐ a battery that is off starts no cycle, and does not hold the slot: "
+      "both are due, A (first in the roster) is off, so B starts",
+      _c.maints[0].phase == IDLE and _c.maints[1].phase == DRAIN)
+_st2 = store_with()
+_seen, _undo_c = spy_claims()
+_msgs = []
+
+
+async def _switch_b_off(c, t):
+    if t == 30.0:
+        _msgs.append(await c.handle_action("pack_use", unit=B, value=False))
+
+
+try:
+    _rows, _c = rig.run(2, extra={**ON, **MAINT}, dur=60.0,
+                        load=lambda t: 500.0, soc=lambda u, t: 60.0,
+                        cut=lambda u, t: False, store=_st2,
+                        before=_switch_b_off)
+finally:
+    _undo_c()
+_during = [cl for cl in _seen[:6]]
+print(f"    B off at 30 s while A drains: A {_c.maints[0].phase}, "
+      f"B {_c.maints[1].phase}; events: "
+      f"{[e for e in _c.events if 'switched' in str(e) or 'ABORT' in str(e)]}")
+check("while A runs its cycle it gets no mode claim (maintenance at 60/40 "
+      "outranks the mode) and B, idle, gets one",
+      all({c.actuator for c in cl if c.source == "mode"} == {B}
+          for cl in _during))
+_st3 = store_with()
+_st3.data[unit_key(B, "phase")] = DRAIN
+_st3.data["maint_schema_version"] = 1
+
+
+async def _b_off_now(c, t):
+    if t == 10.0:
+        _msgs.append(await c.handle_action("pack_use", unit=B, value=False))
+
+
+_rows, _c = rig.run(2, extra=ON, dur=30.0, load=lambda t: 500.0,
+                    soc=lambda u, t: 60.0, cut=lambda u, t: False,
+                    store=_st3, before=_b_off_now)
+_ev = [str(e) for e in _c.events]
+print(f"    B mid-drain, switched off at 10 s: B {_c.maints[1].phase}; "
+      f"{[e for e in _ev if 'switched off' in e or 'ABORT' in e]}")
+check("⭐ switching off a battery that is mid-cycle stops its cycle at once, "
+      "with a log line saying why",
+      _c.maints[1].phase == IDLE
+      and any("battery switched off" in e for e in _ev)
+      and _cmd(_rows[-1])["b"] == 0.0)
+_st4 = store_with(**{B: (False, packmode.SOLAR_FIRST)})
+_st4.data[unit_key(B, "phase")] = DRAIN
+_st4.data["maint_schema_version"] = 1
+_rows, _c = rig.run(2, extra=ON, dur=20.0, load=lambda t: 500.0,
+                    soc=lambda u, t: 60.0, cut=lambda u, t: False, store=_st4)
+check("...and a store that says Off for a battery mid-cycle (a restart) stops "
+      "it on the first cycle, and it is never asked to drain",
+      _c.maints[1].phase == IDLE
+      and all(_cmd(r)["b"] == 0.0 for r in _rows))
+
+
+# ============================================================================ #
+print("\n5. the actions: pack_use and pack_mode")
+_rows, _c = rig.run(2, extra=ON, dur=10.0, load=flat,
+                    soc=lambda u, t: 50.0, cut=lambda u, t: False)
+_r1 = asyncio.run(_c.handle_action("pack_mode", unit=B,
+                                   value=packmode.LEFTOVER_SOLAR))
+_r2 = asyncio.run(_c.handle_action("pack_use", unit=A, value=False))
+print(f"    {_r1} {_r2}")
+check("pack_mode stores the mode under the battery's own key and says what "
+      "it now is",
+      _r1 == {"unit": B, "use": True, "mode": packmode.LEFTOVER_SOLAR}
+      and _c.store.data[unit_key(B, packmode.MODE_KEY)]
+      == packmode.LEFTOVER_SOLAR)
+check("pack_use stores the switch, and both are written to the action log",
+      _r2 == {"unit": A, "use": False, "mode": packmode.SOLAR_FIRST}
+      and _c.store.data[unit_key(A, packmode.USE_KEY)] is False
+      and any("inverter-a switched off by operator" in str(e)
+              for e in _c.events)
+      and any("inverter-b mode set to leftover solar" in str(e)
+              for e in _c.events))
+_bad = [asyncio.run(_c.handle_action("pack_use", unit="inverter-z",
+                                     value=True)),
+        asyncio.run(_c.handle_action("pack_use", unit=A, value="yes")),
+        # 0 == False in Python: a stored 0 would read back as ON.
+        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)),
+        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, "
+      "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
+      and _c.store.data[unit_key(A, packmode.USE_KEY)] is False)
+_rows, _c0 = rig.run(2, dur=10.0, load=flat, soc=lambda u, t: 50.0,
+                     cut=lambda u, t: False)
+_r0 = asyncio.run(_c0.handle_action("pack_use", unit=A, value=False))
+check("with battery modes off the actions are refused and store nothing",
+      set(_r0) == {"error"}
+      and unit_key(A, packmode.USE_KEY) not in _c0.store.data)
+check("the old actions still take no battery and answer as before",
+      asyncio.run(_c0.handle_action("nonsense")) is None)
+check("a store value from a later version (an unknown mode) reads as the "
+      "default, Solar first and on, never as Off",
+      packmode.read({unit_key(A, packmode.MODE_KEY): "grid_only",
+                     unit_key(A, packmode.USE_KEY): "maybe"}, A)
+      == packmode.PackMode(True, packmode.SOLAR_FIRST))
+
+
+# ============================================================================ #
+print("\n6. a mode range without 0 W is a software fault, never obeyed")
+_real_range = packmode.mode_range
+packmode.mode_range = lambda pm, r: (100.0, 900.0)
+_log = []
+
+
+class _H(logging.Handler):
+    def emit(self, rec):
+        _log.append((rec.levelno, rec.getMessage()))
+
+
+_h = _H()
+logging.getLogger("goodwe").addHandler(_h)
+try:
+    _rows, _c = rig.run(2, extra=ON, dur=60.0, load=lambda t: -2000.0,
+                        soc=lambda u, t: 50.0, cut=lambda u, t: False)
+finally:
+    packmode.mode_range = _real_range
+    logging.getLogger("goodwe").removeHandler(_h)
+_errs = [msg for lv, msg in _log if lv >= logging.ERROR and "MODE_RANGE" in msg]
+print(f"    {_errs}")
+check("⭐ both batteries still charge from the surplus (the forced range is "
+      "dropped, so no battery is made to give power) and no split is refused",
+      all(v <= 0.0 for _u, v in _rows[-1][2])
+      and _cmd(_rows[-1])["a"] < 0.0
+      and not any("REFUSED" in (r[7] or "") for r in _rows))
+check("...and it is logged once per battery, as an ERROR naming the fault "
+      "code, not once per cycle",
+      len(_errs) == 2 and any(A in e for e in _errs) and any(B in e for e in _errs))
+
+
+# ============================================================================ #
+print("\n7. the Batteries screen's data")
+_rows, _c = rig.run(2, extra=ON, dur=10.0, load=flat, soc=lambda u, t: 50.0,
+                    cut=lambda u, t: False,
+                    store=store_with(**{B: (False, packmode.LEFTOVER_SOLAR)}))
+_bat = homeview.battery_rows(_c, False, True)
+_bat_nl = homeview.build(_c, level="ok", checks=[], lang="nl")["batteries"]
+print(f"    {[(b['name'], b['use'], b['mode_key'], b['mode']) for b in _bat]}")
+check("with battery modes on each row carries its switch, its state and its "
+      "stored mode, in the page's words",
+      [(b["use"], b["mode_key"], b["mode_choice"], b["mode"]) for b in _bat]
+      == [(True, "solar_first", "solar_first", "Solar first"),
+          (False, "off", "leftover_solar", "Off")]
+      and _bat_nl[1]["mode"] == "Uit")
+_rows, _c0 = rig.run(2, dur=10.0, load=flat, soc=lambda u, t: 50.0,
+                     cut=lambda u, t: False)
+check("...and with them off the rows are what they were: no new keys, the "
+      "mode reads as before",
+      all("mode_key" not in b and b["mode"] == homeview.mode_house()
+          for b in homeview.battery_rows(_c0, False, True)))
+
+
+# ============================================================================ #
+print("\n8. the page's route: /action and /status over the real web app")
+import socket                                                  # noqa: E402
+
+import aiohttp                                                 # noqa: E402
+from aiohttp import web as aioweb                              # noqa: E402
+
+from app import web as app_web                                 # noqa: E402
+
+_rows, _c = rig.run(2, extra=ON, dur=10.0, load=flat, soc=lambda u, t: 50.0,
+                    cut=lambda u, t: False)
+
+
+async def _page():
+    # The configuration routes are not used here; a stand-in keeps the app
+    # from building a Supervisor client.
+    app = app_web.build_app(_c, selfcfg=object())
+    runner = aioweb.AppRunner(app)
+    await runner.setup()
+    sock = socket.socket()
+    sock.bind(("127.0.0.1", 0))
+    port = sock.getsockname()[1]
+    sock.close()
+    await aioweb.TCPSite(runner, "127.0.0.1", port).start()
+    out = {}
+    try:
+        async with aiohttp.ClientSession() as s:
+            root = f"http://127.0.0.1:{port}/"
+            for key, body in (
+                    ("mode", {"action": "pack_mode", "unit": B,
+                              "value": packmode.LEFTOVER_SOLAR}),
+                    ("off", {"action": "pack_use", "unit": A,
+                             "value": False}),
+                    ("bad", {"action": "pack_mode", "unit": A,
+                             "value": "grid_only"})):
+                async with s.post(root + "action", json=body) as r:
+                    out[key] = (r.status, await r.json(content_type=None))
+            async with s.get(root + "status") as r:
+                out["status"] = (r.status, await r.json(content_type=None))
+            async with s.get(root) as r:
+                out["page"] = (r.status, await r.text())
+    finally:
+        await runner.cleanup()
+    return out
+
+
+_web = asyncio.run(_page())
+print(f"    {_web['mode']} {_web['off']} {_web['bad']}")
+check("POST /action with pack_mode and pack_use names a battery and a value, "
+      "and answers what it stored",
+      _web["mode"] == (200, {"ok": True, "result": {
+          "unit": B, "use": True, "mode": packmode.LEFTOVER_SOLAR}})
+      and _web["off"][0] == 200 and _web["off"][1]["result"]["use"] is False)
+check("...a value this release does not offer is a 400 with the plain reason "
+      "the page shows",
+      _web["bad"][0] == 400 and _web["bad"][1]["ok"] is False
+      and _web["bad"][1]["error"] == messages.pack_refused("value"))
+_sb = {b["name"]: b for b in _web["status"][1].get("batteries", [])}
+check("...and /status then shows both batteries' switch and mode for the "
+      "Batteries screen",
+      _web["status"][0] == 200
+      and (_sb.get(A, {}).get("mode_key"), _sb.get(B, {}).get("mode_key"))
+      == ("off", packmode.LEFTOVER_SOLAR))
+check("the page carries the mode names from app/ui_text for its cards",
+      _web["page"][0] == 200 and "Leftover solar" in _web["page"][1]
+      and "Overschot zonne-energie" in _web["page"][1])
+
+
+print()
+if fails:
+    print(f"{len(fails)} FAILED: {', '.join(fails)}")
+    sys.exit(1)
+print("all checks passed")

goodwe_controller/test_mqtt.py

@@ -42,6 +42,7 @@ part is a diff against it, reported as `N topics, M missing, C changed, A added`
           re-executed from mutated source, each one named with the property it
           breaks. A property nothing breaks is a property nothing is watching.
   Part 9  What these checks CANNOT see, enumerated and sized.
+  Part 10 OPT-11 P2: each battery's select and switch, commands, removal.
 
 ⚠️ THE FIXTURE GIVES A AND B DIFFERENT NAMES, DIFFERENT RATINGS, DIFFERENT SoC,
 DIFFERENT BATTERY POWER AND DIFFERENT LATCH STATES, ON PURPOSE. A fixture whose
@@ -821,8 +822,8 @@ MUTATIONS = [
     ("per-unit entities announced at a roster of ONE",
      [("PER_UNIT_MIN_ROSTER = 2", "PER_UNIT_MIN_ROSTER = 1")]),
     ("the unit is dropped from the unique_id",
-     [('unique_id = f"{BASE}_unit_{slug}_{key}"',
-       'unique_id = f"{BASE}_unit_{key}"')]),
+     [('return f"{BASE}_unit_{slug}_{key}"',
+       'return f"{BASE}_unit_{key}"')]),
     ("the unit is dropped from the state topic",
      [('return f"unit/{slug}/{key}"', 'return f"unit/{key}"')]),
     ("the slug de-collision is removed (rule 9(c) does not cover this)",
@@ -944,6 +945,536 @@ for line in [
 ]:
     print("    " + line)
 
+# ---------------------------------------------------------------------------
+print("\n10. OPT-11 P2: each battery's switch and mode as HA entities")
+# ---------------------------------------------------------------------------
+import logging     # noqa: E402
+import os          # noqa: E402
+import tempfile    # noqa: E402
+
+from app import messages, packmode    # noqa: E402
+from app.store import Store, unit_key  # noqa: E402
+
+
+def announce_p2(units=(), omit=(), include=(), modes=(), retract=(),
+                module=mqtt):
+    """What `_on_connect()` sends: the announcement, then any subscriptions."""
+    pub = module.MqttPublisher.__new__(module.MqttPublisher)
+    pub.omit, pub.units, pub.include = set(omit), [str(u) for u in units], \
+        [str(k) for k in include]
+    pub.modes, pub.retract = tuple(modes), list(retract)
+    pub.enabled, pub.client = True, FakeClient()
+    subs = []
+    pub.client.subscribe = lambda topic, *a: subs.append(topic)
+    pub._on_connect()
+    return pub.client.msgs, subs
+
+
+# --- 10a. modes off: byte-identical to ed739d4 --------------------------------
+# The digest below is GENERATED from release/1.0 at ed739d4 (the base of this
+# PR): the same matrix run through that commit's `_announce()`. Reproduce with
+# `git show ed739d4:goodwe_controller/app/mqtt.py` and this loop.
+ROSTERS = [[], ["inverter-a"], ["inverter-a", "inverter-b"], ["a", "b", "c"],
+           ["inverter-b", "Inverter B", "x", "y"], ["café"]]
+ED739D4_OFF = "501a7d93782a260b"
+_h, _n, _subs_off = hashlib.sha256(), 0, []
+for _r in ROSTERS:
+    for _om in [(), ("p1_age",), ("p1_age", "grid")]:
+        for _inc in [(), ("pv",)]:
+            _m, _s = announce_p2(_r, _om, _inc)
+            _h.update(repr(_m).encode())
+            _subs_off += _s
+            _n += 1
+print(f"    modes off, {_n} configurations: digest {_h.hexdigest()[:16]} "
+      f"(ed739d4: {ED739D4_OFF})")
+check("modes off: every configuration announces byte-for-byte what ed739d4 "
+      "announces, in the same order, and subscribes to nothing",
+      _h.hexdigest()[:16] == ED739D4_OFF and not _subs_off)
+
+
+# --- 10b. modes on: the ordered payload diff ----------------------------------
+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"]'
+MODE_N1 = [
+    ("homeassistant/select/goodwe_ctl_unit_inverter_a_mode/config",
+     '{"name": "Inverter A Mode", "object_id": "goodwe_inverter_a_mode", '
+     '"unique_id": "goodwe_ctl_unit_inverter_a_mode", '
+     '"state_topic": "goodwe_ctl/unit/inverter_a/mode", '
+     '"command_topic": "goodwe_ctl/unit/inverter_a/mode/set", '
+     '"options": ' + _opt + ', "retain": false, '
+     '"availability_topic": "goodwe_ctl/availability", "device": ' + _DEV + ', '
+     '"icon": "mdi:battery-sync"}', True),
+    ("homeassistant/switch/goodwe_ctl_unit_inverter_a_use/config",
+     '{"name": "Inverter A Use", "object_id": "goodwe_inverter_a_use", '
+     '"unique_id": "goodwe_ctl_unit_inverter_a_use", '
+     '"state_topic": "goodwe_ctl/unit/inverter_a/use", '
+     '"command_topic": "goodwe_ctl/unit/inverter_a/use/set", '
+     '"payload_on": "ON", "payload_off": "OFF", "retain": false, '
+     '"availability_topic": "goodwe_ctl/availability", "device": ' + _DEV + ', '
+     '"icon": "mdi:power"}', True),
+]
+check("modes on at a roster of one: every existing message byte-identical and "
+      "in place, then exactly the select and the switch, then availability",
+      ON1 == SITE_NOW[:-1] + MODE_N1 + SITE_NOW[-1:])
+check("...and it subscribes to the two command topics, and nothing else",
+      SUB1 == ["goodwe_ctl/unit/+/mode/set", "goodwe_ctl/unit/+/use/set"])
+
+ON2, _ = announce_p2(NAMES2, modes=MODES)
+m, c, a = report("roster of two, modes on", ON2, TWO)
+check("modes on at a roster of two: nothing missing or changed, four added, "
+      "and the modes-off list is an unchanged prefix",
+      (m, c) == ([], []) and len(a) == 4 and ON2[:len(TWO) - 1] == TWO[:-1]
+      and ON2[-1] == TWO[-1])
+_mc = cfgs(ON2)[-4:]
+check("...A's two stay on the site device with its name in front; B's two are "
+      "on B's own device, as TEL-07's rule has it",
+      [c_["name"] for c_ in _mc] == ["Inverter A Mode", "Inverter A Use",
+                                      "Mode", "Use"]
+      and _mc[0]["device"] == mqtt.DEVICE == _mc[1]["device"]
+      and _mc[2]["device"] == _mc[3]["device"]
+      == mqtt.unit_device("inverter-b", "inverter_b"))
+check("...unique_ids are stable per battery and distinct from every other id",
+      [c_["unique_id"] for c_ in _mc]
+      == ["goodwe_ctl_unit_inverter_a_mode", "goodwe_ctl_unit_inverter_a_use",
+          "goodwe_ctl_unit_inverter_b_mode", "goodwe_ctl_unit_inverter_b_use"]
+      and len({c_["unique_id"] for c_ in cfgs(ON2)}) == len(cfgs(ON2)))
+_ids = [compose(c_["device"]["name"], c_["name"]).split(".", 1)[1]
+        for c_ in _mc]
+print(f"    composed ids: {_ids}")
+check("...and HA composes the ids the design names: "
+      "goodwe_inverter_<x>_mode and goodwe_inverter_<x>_use",
+      _ids == ["goodwe_inverter_a_mode", "goodwe_inverter_a_use",
+               "goodwe_inverter_b_mode", "goodwe_inverter_b_use"])
+check("every mode has a plain label, in MODES order, and a later mode only "
+      "appends an option: no existing option or id changes",
+      all(k in mqtt.MODE_LABELS for k in MODES)
+      and len(set(mqtt.MODE_LABELS.values())) == len(mqtt.MODE_LABELS)
+      and json.loads(MODE_N1[0][1])["options"]
+      == [mqtt.MODE_LABELS[k] for k in MODES])
+# Review of #152: the HA options are what automations send, so they are kept
+# apart from the page's words on purpose. They start equal; if the page's
+# English changes, this goes red and the author decides: keep the HA option
+# (and change this pin) or rename it (a breaking change, in DECISIONS).
+_en = json.loads((HERE / "app" / "ui_text" / "en.json").read_text())
+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")
+_orig = mqtt.MODE_LABELS
+mqtt.MODE_LABELS = _later
+try:
+    _p3 = mqtt.mode_payloads(NAMES2, MODES + ("cheap_hours",))
+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)",
+      [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"}
+              for (_, x), (_, y) in zip(_p3, _p2))
+      and _p3[0][1]["options"] == _p2[0][1]["options"] + ["Cheap hours only"])
+
+
+# --- 10c. modes turned off: removal ------------------------------------------
+_cur2 = [t for t, _ in mqtt.mode_payloads(NAMES2, MODES)]
+_ret = mqtt.mode_retractions(_cur2, [])
+OFF2, _subs = announce_p2(NAMES2, retract=_ret)
+check("modes turned off: the modes-off list, then an EMPTY retained config "
+      "for each of the four, then availability, and no subscription",
+      OFF2 == TWO[:-1] + [(t, "", True) for t in _cur2] + TWO[-1:]
+      and not _subs)
+check("...the store keeps what was announced, so a roster that shrinks removes "
+      "only the battery that left",
+      mqtt.mode_retractions(_cur2, [t for t, _ in
+                                    mqtt.mode_payloads(["inverter-a"], MODES)])
+      == _cur2[2:])
+check("...and nothing from the store is removed that is not one of our mode "
+      "configs: a non-list, a number, a site sensor, another add-on's select",
+      mqtt.mode_retractions("homeassistant/select/x/config", []) == []
+      and mqtt.mode_retractions(
+          [3, None, "homeassistant/sensor/goodwe_ctl_grid/config",
+           "homeassistant/select/other_mode/config",
+           "homeassistant/select/goodwe_ctl_unit_a_mode/config/x",
+           "homeassistant/select/goodwe_ctl_unit_a_mode/config"], [])
+      == ["homeassistant/select/goodwe_ctl_unit_a_mode/config"])
+
+
+_on1 = [t for t, _ in mqtt.mode_payloads(["inverter-a"], MODES)]
+_k, _r = mqtt.mode_configs(["inverter-a"], MODES, _cur2)
+check("start-up (`mode_configs`): a battery that left is removed, and stays "
+      "in the store, so a start with no broker does not forget it",
+      _r == _cur2[2:] and _k == _on1 + _cur2[2:])
+_k, _r = mqtt.mode_configs(NAMES2, (), _cur2 + _cur2[:1])
+check("...modes turned off: all four are removed, once each, and kept",
+      _r == _cur2 and _k == _cur2)
+check("...never turned on: nothing to store and nothing to remove, so the "
+      "store is not written",
+      mqtt.mode_configs(NAMES2, (), None) == ([], []))
+_k, _r = mqtt.mode_configs(NAMES2, MODES, _cur2)
+check("...turned on again: nothing removed, and the list does not grow",
+      _r == [] and _k == _cur2)
+
+
+from app.main import mode_announcement  # noqa: E402
+_st = Store(os.path.join(tempfile.mkdtemp(), "ann.json"))
+_OPTS1M = dict(OPTS2, battery_modes_enabled=True,
+               inverters=OPTS2["inverters"][:1])
+_seen = [mode_announcement(dict(OPTS2), _st),
+         dict(_st.data)]
+_seen += [mode_announcement(dict(OPTS2, battery_modes_enabled=True), _st),
+          list(_st.data.get(mqtt.MODE_CONFIGS_KEY) or [])]
+_seen += [mode_announcement(_OPTS1M, _st),
+          list(_st.data.get(mqtt.MODE_CONFIGS_KEY) or [])]
+_seen += [mode_announcement(dict(OPTS2, battery_modes_enabled=False), _st),
+          list(_st.data.get(mqtt.MODE_CONFIGS_KEY) or [])]
+check("main's start-up, through a real Store: never on announces and stores "
+      "nothing; on stores the four; a roster of one removes B's two and keeps "
+      "them; off removes all four and the store keeps them",
+      _seen[0] == ((), []) and mqtt.MODE_CONFIGS_KEY not in _seen[1]
+      and _seen[2] == (MODES, []) and _seen[3] == _cur2
+      and _seen[4] == (MODES, _cur2[2:]) and sorted(_seen[5]) == sorted(_cur2)
+      and _seen[6] == ((), _seen[5])
+      and sorted(_seen[7]) == sorted(_cur2))
+_st = Store(os.path.join(tempfile.mkdtemp(), "ren.json"))
+mode_announcement(dict(OPTS2, battery_modes_enabled=True), _st)
+_ren = dict(OPTS2, battery_modes_enabled=True, inverters=[
+    OPTS2["inverters"][0], dict(OPTS2["inverters"][1], name="inverter-c")])
+_r = mode_announcement(_ren, _st)[1]
+_kept = list(_st.data.get(mqtt.MODE_CONFIGS_KEY) or [])
+check("...B renamed C while on: B's two are removed and stay stored beside "
+      "A's and C's, so a start with no broker does not forget them",
+      _r == _cur2[2:] and _kept[-2:] == _cur2[2:] and len(_kept) == 6
+      and mode_announcement(_ren, _st)[1] == _cur2[2:])
+check("battery modes are on only for exactly `true`: not \"true\", 1 or "
+      "\"false\"",
+      [packmode.enabled({"battery_modes_enabled": v})
+       for v in (True, "true", 1, "false", None)]
+      == [True, False, False, False, False])
+
+
+# --- 10d. state topics, from the store ----------------------------------------
+_tmp = tempfile.mkdtemp()
+OPTS2M = dict(OPTS2, battery_modes_enabled=True)
+
+
+def ctl_for(opts, path):
+    pub = _Pub()
+    pub.sent = []
+    pub.publish = lambda values, _p=pub: (_p.sent.append(dict(values)),
+                                          setattr(_p, "last", dict(values)))
+    return Controller(dict(opts), None, Store(path), pub,
+                      stop=asyncio.Event()), pub
+
+
+_path = os.path.join(_tmp, "state.json")
+ctlm, pubm = ctl_for(OPTS2M, _path)
+ctlm.publish()
+_fed = {f"{mqtt.BASE}/{k}" for k in pubm.last
+        if k.endswith("/mode") or k.endswith("/use")}
+check("every announced mode entity is fed, and nothing else is: the state "
+      "topics published are exactly the ones announced",
+      _fed == {c_["state_topic"] for c_ in _mc})
+check("...defaults with nothing in the store: both On, both Solar first",
+      [pubm.last[k] for k in ("unit/inverter_a/mode", "unit/inverter_a/use",
+                              "unit/inverter_b/mode", "unit/inverter_b/use")]
+      == ["Solar first", "ON", "Solar first", "ON"])
+_c_off, _p_off = ctl_for(dict(OPTS2, battery_modes_enabled=False),
+                         os.path.join(_tmp, "off2.json"))
+_c_off.publish()
+_c_abs, _p_abs = ctl_for(OPTS2, os.path.join(_tmp, "off3.json"))
+_c_abs.publish()
+check("modes off (false or absent): the controller publishes the same keys as "
+      "before, with no mode or switch topic",
+      set(_p_off.last) == set(_p_abs.last) == set(vals2)
+      and not [k for k in _p_off.last if k.endswith(("/mode", "/use"))])
+
+
+# --- 10e. commands: the /action path, validated -------------------------------
+class _Logs(logging.Handler):
+    def __init__(self):
+        super().__init__(logging.DEBUG)
+        self.rows = []
+
+    def emit(self, record):
+        self.rows.append((record.levelno, record.getMessage()))
+
+
+_logs = _Logs()
+logging.getLogger("goodwe").addHandler(_logs)
+logging.getLogger("goodwe").setLevel(logging.DEBUG)
+_calls = []
+_real_handle = ctlm.handle_action
+
+
+async def _spy(what, **kw):
+    _calls.append((what, kw))
+    return await _real_handle(what, **kw)
+
+
+ctlm.handle_action = _spy
+
+
+def cmd(topic, payload, retained=False, ctl=None):
+    ctl = ctl or ctlm
+    asyncio.run(ctl.mqtt_command(topic, payload, retained))
+
+
+def stored(ctl=None):
+    d = (ctl or ctlm).store.data
+    return {k: d.get(k) for k in (unit_key("inverter-a", "pack_use"),
+                                  unit_key("inverter-a", "pack_mode"),
+                                  unit_key("inverter-b", "pack_use"),
+                                  unit_key("inverter-b", "pack_mode"))}
+
+
+T_A = "goodwe_ctl/unit/inverter_a"
+T_B = "goodwe_ctl/unit/inverter_b"
+pubm.sent.clear()
+cmd(f"{T_B}/use/set", b"OFF")
+cmd(f"{T_A}/mode/set", b"Leftover solar")
+check("good commands go through handle_action() with the /action arguments",
+      _calls == [("pack_use", {"unit": "inverter-b", "value": False}),
+                 ("pack_mode", {"unit": "inverter-a",
+                                "value": "leftover_solar"})])
+check("...and reach the store under P1's keys, and nowhere else",
+      stored() == {unit_key("inverter-a", "pack_use"): None,
+                   unit_key("inverter-a", "pack_mode"): "leftover_solar",
+                   unit_key("inverter-b", "pack_use"): False,
+                   unit_key("inverter-b", "pack_mode"): None})
+check("...and the state topics say so at once, from the store",
+      pubm.sent and pubm.sent[-1] == {
+          "unit/inverter_a/mode": "Leftover solar", "unit/inverter_a/use": "ON",
+          "unit/inverter_b/mode": "Solar first", "unit/inverter_b/use": "OFF"})
+check("...and the action log records each change",
+      any("inverter-b switched off" in e for e in ctlm.events)
+      and any("inverter-a mode set to leftover solar" in e
+              for e in ctlm.events))
+
+_before = stored()
+_n_calls = len(_calls)
+BAD = [
+    (f"{T_A}/use/set", b"on"), (f"{T_A}/use/set", b"ON\n"),
+    (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"solar first"),
+    (f"{T_A}/mode/set", "Sοlar first".encode()),  # Greek omicron
+    (f"{T_A}/mode/set", b"Solar first\x00"),
+    (f"{T_A}/mode/set", b'{"action": "pack_use", "value": false}'),
+    (f"{T_A}/mode/set", b"Solar first; rm -rf /"),
+    (f"{T_A}/mode/set", b"' OR 1=1 --"),
+    (f"{T_A}/use/set", b"\xff\xfe"),              # not UTF-8
+    (f"{T_A}/mode/set", b"Solar first" * 10),     # too long
+    ("goodwe_ctl/unit/inverter_z/use/set", b"OFF"),   # no such battery
+    ("goodwe_ctl/unit/../use/set", b"OFF"),
+    ("goodwe_ctl/unit/inverter_a/soc/set", b"OFF"),
+    ("goodwe_ctl/unit/inverter_a/use/set/x", b"OFF"),
+    ("goodwe_ctl/unit/Inverter_A/use/set", b"OFF"),
+    (f"{T_A}/use/set", None),
+]
+for _t, _p in BAD:
+    cmd(_t, _p)
+check(f"all {len(BAD)} bad commands are refused: the store is unchanged",
+      stored() == _before)
+_passed = [c_ for c_ in _calls[_n_calls:]]
+check("...those that reach handle_action() carry a value /action also refuses "
+      "(None) or no known battery; nothing is coerced into a valid choice",
+      all(kw["value"] is None or kw["unit"] is None for _, kw in _passed))
+
+# Log once per topic and reason.
+_logs.rows.clear()
+for _ in range(5):
+    cmd(f"{T_B}/use/set", b"maybe")
+_warn = [r for r in _logs.rows if r[0] >= logging.WARNING]
+check("a refused command repeated 5 times is logged once at WARNING, in plain "
+      "words, and at DEBUG the other times",
+      len(_warn) == 1 and messages.pack_refused("value") in _warn[0][1]
+      and len([r for r in _logs.rows if r[0] == logging.DEBUG]) == 5)
+_logs.rows.clear()
+_flood, _ = ctl_for(OPTS2M, os.path.join(_tmp, "flood.json"))
+for _i in range(100):
+    cmd(f"goodwe_ctl/unit/x{_i}/use/set", b"OFF", ctl=_flood)
+_w = [r[1] for r in _logs.rows if r[0] >= logging.WARNING]
+_per = [w for w in _w if "still ignored" not in w]
+_more = [w for w in _w if "still ignored" in w]
+print(f"    flood: {len(_per)} per-topic WARNINGs, then {_more}")
+check("...and a flood of 100 different bad topics logs 32 WARNINGs, then the "
+      "rest only as a count, at 1 and 10 more (review of #152)",
+      len(_per) == 32 and len(_more) == 2
+      and "1 more so far" in _more[0] and "10 more so far" in _more[1])
+_logs.rows.clear()
+for _ in range(100):
+    cmd(f"{T_B}/use/set", b"maybe", ctl=_flood)
+_more = [r[1] for r in _logs.rows
+         if r[0] >= logging.WARNING and "still ignored" in r[1]]
+check("...so a repeated attack on ONE topic still shows it goes on: the count "
+      "reaches 100 in 3 lines, not 100",
+      len(_more) == 1 and "100 more so far" in _more[0])
+_logs.rows.clear()
+_inj, _ = ctl_for(OPTS2M, os.path.join(_tmp, "inj.json"))
+cmd("goodwe_ctl/unit/a\nERROR forged line\x1b[31m/use/set", b"OFF", ctl=_inj)
+_w = [r[1] for r in _logs.rows if r[0] >= logging.WARNING]
+check("...and a topic with a newline or an escape code cannot forge a log "
+      "line: it is logged printable only",
+      len(_w) == 1 and "\n" not in _w[0] and "\x1b" not in _w[0]
+      and "a?ERROR forged line?[31m" in _w[0])
+
+# Modes off: refused on the same path, even if a message arrives.
+cmd(f"{T_A}/use/set", b"OFF", ctl=_c_off)
+check("with modes off a command is refused by the same check /action makes",
+      stored(_c_off)[unit_key("inverter-a", "pack_use")] is None)
+
+
+# --- 10f. a retained command after a restart ----------------------------------
+_logs.rows.clear()
+_before = stored()
+_n_calls = len(_calls)
+cmd(f"{T_A}/use/set", b"OFF", retained=True)
+cmd(f"{T_B}/use/set", b"ON", retained=True)
+check("a RETAINED command (the broker replays it on subscribe, e.g. after a "
+      "restart) is never applied, and never reaches handle_action()",
+      stored() == _before and len(_calls) == _n_calls)
+check("...and it is logged once, in plain words",
+      any(messages.pack_refused("retained") in r[1]
+          for r in _logs.rows if r[0] >= logging.WARNING))
+ctl_r, pub_r = ctl_for(OPTS2M, _path)      # a restart: same state file
+ctl_r.publish()
+check("after a restart the state topics come from the store: A Leftover solar "
+      "and on, B off",
+      [pub_r.last[k] for k in ("unit/inverter_a/mode", "unit/inverter_a/use",
+                               "unit/inverter_b/use")]
+      == ["Leftover solar", "ON", "OFF"])
+logging.getLogger("goodwe").removeHandler(_logs)
+
+
+# --- 10g. the paho side ----------------------------------------------------------
+class _Msg:
+    def __init__(self, topic, payload, retain):
+        self.topic, self.payload, self.retain = topic, payload, retain
+
+
+_got = []
+
+
+async def _handler(*args):
+    _got.append(args)
+
+
+async def _drive():
+    pub = mqtt.MqttPublisher.__new__(mqtt.MqttPublisher)
+    pub._on_message(None, None, _Msg("t", b"x", 0))      # not bound: dropped
+    pub.bind(asyncio.get_running_loop(), _handler)
+    pub._on_message(None, None, _Msg(f"{T_A}/use/set", b"OFF", 1))
+    await asyncio.sleep(0.05)
+
+asyncio.run(_drive())
+check("paho's thread hands (topic, bytes, retained) to the controller's loop, "
+      "and drops a message that arrives before the controller exists",
+      _got == [(f"{T_A}/use/set", b"OFF", True)])
+
+_kws = {k.arg: ast.unparse(k.value) for c_ in _call for k in c_.keywords}
+_main_src = (HERE / "app" / "main.py").read_text()
+check("(source read) main() passes modes and retractions to the publisher, "
+      "and binds its commands to the controller",
+      _kws.get("modes") == "_modes" and _kws.get("retract") == "_retract"
+      and "pub.bind(asyncio.get_running_loop(), controller.mqtt_command)"
+      in _main_src
+      and "_modes, _retract = mode_announcement(opts, store)" in _main_src)
+
+
+# --- 10h. the guards, broken one at a time --------------------------------------
+def p2_properties(mod):
+    out = {}
+    try:
+        off, s_off = announce_p2(NAMES2, module=mod)
+        on1, s_on = announce_p2(["inverter-a"], modes=MODES, module=mod)
+        on2, _ = announce_p2(NAMES2, modes=MODES, module=mod)
+        out["off identical"] = off == TWO and not s_off
+        out["on payloads"] = on1 == ON1 and on2 == ON2
+        out["subscribes when on"] = s_on == SUB1
+        cur = [t for t, _ in mod.mode_payloads(NAMES2, MODES)]
+        out["retract filters store"] = mod.mode_retractions(
+            [3, "homeassistant/sensor/goodwe_ctl_grid/config",
+             "homeassistant/select/other/config"] + cur, cur) == []
+        out["retract keeps current"] = mod.mode_retractions(cur, cur) == []
+        out["retract published"] = announce_p2(
+            NAMES2, retract=cur[:1], module=mod)[0] == \
+            TWO[:-1] + [(cur[0], "", True)] + TWO[-1:]
+        pc = mod.parse_command
+        out["retained dropped"] = pc(f"{T_A}/use/set", b"OFF", True,
+                                     MODES)[3] == "retained"
+        out["size capped"] = pc(f"{T_A}/mode/set", b"Solar first" * 10,
+                                False, MODES)[3] == "size"
+        out["utf-8 only"] = pc(f"{T_A}/use/set", b"\xff", False,
+                               MODES)[3] == "encoding"
+        out["switch exact"] = (
+            pc(f"{T_A}/use/set", b"on", False, MODES)[2] is None
+            and pc(f"{T_A}/use/set", b"OFF", False, MODES)[2] is False)
+        out["select labels only"] = (
+            pc(f"{T_A}/mode/set", b"solar_first", False, MODES)[2] is None
+            and pc(f"{T_A}/mode/set", b"Leftover solar", False,
+                   MODES)[2] == "leftover_solar")
+        out["select offered only"] = pc(
+            f"{T_A}/mode/set", b"Solar first", False, ("leftover_solar",))[2] \
+            is None
+        out["topic exact"] = all(
+            pc(t, b"OFF", False, MODES)[3] == "topic"
+            for t in ("goodwe_ctl/unit/../use/set", "goodwe_ctl/unit/a/b/use/set",
+                      "goodwe_ctl/unit/a/use/set/x", "x/goodwe_ctl/unit/a/use/set"))
+    except Exception as err:  # noqa: BLE001
+        out["did not raise"] = False
+        out["__error__"] = repr(err)[:70]
+    return out
+
+
+P2_SHIPPED = p2_properties(mqtt)
+check("the shipped module has every P2 property (so a red below is the "
+      "mutation)", all(v is True for v in P2_SHIPPED.values()))
+P2_MUTATIONS = [
+    ("mode entities announced with modes off",
+     [("    if not modes:\n        return []\n", "    modes = modes or ('solar_first', 'leftover_solar')\n")]),
+    ("subscribed with modes off", [("        if self.modes:\n", "        if True:\n")]),
+    ("retained commands applied", [("    if retained:\n", "    if False:\n")]),
+    ("no payload size cap", [("or len(payload) > MAX_COMMAND_BYTES", "or False")]),
+    ("bad UTF-8 replaced, not refused",
+     [('.decode("utf-8")', '.decode("utf-8", "replace")')]),
+    ("switch payload case-folded",
+     [("{USE_ON: True, USE_OFF: False}.get(text)",
+       "{USE_ON: True, USE_OFF: False}.get(text.upper())")]),
+    ("select accepts mode keys too",
+     [("if MODE_LABELS.get(k) == text", "if text in (k, MODE_LABELS.get(k))")]),
+    ("select accepts any labelled mode, offered or not",
+     [("(k for k in modes if MODE_LABELS.get(k) == text)",
+       "(k for k in MODE_LABELS if MODE_LABELS.get(k) == text)")]),
+    ("command topic loosened", [('/([a-z0-9_]+)/(mode|use)/set")', '/(.+)/(mode|use)/set")')]),
+    ("command topic matched as a prefix",
+     [("_COMMAND_RE.fullmatch(topic)", "_COMMAND_RE.search(topic)")]),
+    ("store list not filtered",
+     [("and _MODE_CONFIG_RE.fullmatch(t)\n", "and True\n")]),
+    ("current configs also removed", [("and t not in keep))", "))")]),
+    ("commands published retained by HA", [('cfg["retain"] = False', 'cfg["retain"] = True')]),
+    ("retractions not published",
+     [('            self.client.publish(topic, "", retain=True)\n', "            pass\n")]),
+]
+_p2_surv = []
+for label, pairs in P2_MUTATIONS:
+    got = properties(load(pairs))
+    got.update(p2_properties(load(pairs)))
+    broke = sorted(k for k, v in {**SHIPPED, **P2_SHIPPED}.items()
+                   if v is True and got.get(k) is not True)
+    print(f"    {'RED ' if broke else 'GREEN'} {label}"
+          + (f"  (breaks: {', '.join(broke)})" if broke else ""))
+    if not broke:
+        _p2_surv.append(label)
+check(f"all {len(P2_MUTATIONS)} P2 mutations of app/mqtt.py are red",
+      not _p2_surv)
+
+
 # ---------------------------------------------------------------------------
 print()
 if fails:

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
@@ -1417,7 +1419,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 +1557,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 +1638,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 +1686,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 +1698,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 +1755,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 +1802,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 +1952,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 +2230,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,
@@ -2653,9 +2657,26 @@ check("...and so does the persistent notification, which outlives the page and "
 #
 # If you are here because you added a TWELFTH, that argument is what this line
 # wants from you, not an edit.
+# ⚠️ SAFETY-73 ADDED `refused` (a P_SAFETY unit limit on a measured refusal).
+# ⚠️ OPT-11 ADDED `mode`, ON PURPOSE, AND IT IS NOT THE DEFERRED RESERVE EITHER.
+# `mode` is `Claim.limit("mode", P_MODE, lo, hi)` on ONE inverter's actuator:
+# the owner's per-battery choice (on/off, Solar first, Leftover solar), filed
+# only with `battery_modes_enabled` on (default off). It is not conditioned on
+# a state of charge, and it cannot bound the site against the peak floor:
+#   1. stage 1 keeps it APART from the hard limits (UnitBounds.mode_*), so it
+#      never enters a `lo > hi` test, not even the unit's own;
+#   2. stage 3 applies it only while the site target was decided at or below
+#      P_MODE (35), so the guard's floor (P_PEAK, 50) RELEASES it, and at N=1
+#      `resolve()` applies it to the site by the same rule, after stage 2;
+#   3. its range always holds 0 W, so it can forbid a direction and never
+#      force one (a range without 0 is dropped as a software fault).
+# test_arbiter.py part 9 grades the no-contradiction claim at N=2, over 625
+# 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.
 CLAIM_SOURCES = {"device", "supervised", "failsafe", "safety", "peak",
                  "arbitrage", "maintenance", "loop", "circulation",
-                 "sign_site", "pack", "refused"}
+                 "sign_site", "pack", "refused", "mode"}
 # 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.
@@ -2697,7 +2718,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 TWELVE. THIS "
+check("...and the sources that cycle can file are EXACTLY these THIRTEEN. 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 "
@@ -2849,7 +2870,7 @@ check("...and the split is the one ARB-03 argued, with SAFETY-31's and "
       == {"loop", "peak", "arbitrage", "safety", "circulation", "sign_site"}
       and {s for s, v in CLAIM_SCOPE.items() if v == SCOPE_UNIT}
       == {"device", "supervised", "failsafe", "maintenance", "pack",
-          "refused"})
+          "refused", "mode"})
 
 # The shipped roster is ONE inverter, so §6.2's identity holds and every claim a
 # real cycle files is a site claim. Observed on the claims main.py's own resolve
@@ -2947,6 +2968,7 @@ check("⚠️ AND THIS IS THE BREAKING HALF. Give the same Controller a second "
       _routed == {"device": "inverter-a", "supervised": "inverter-a",
                   "failsafe": "inverter-a", "maintenance": "inverter-a",
                   "pack": "inverter-a", "refused": "inverter-a",
+                  "mode": "inverter-a",
                   "loop": ACTUATOR_SITE, "peak": ACTUATOR_SITE,
                   "arbitrage": ACTUATOR_SITE, "safety": ACTUATOR_SITE,
                   "circulation": ACTUATOR_SITE, "sign_site": ACTUATOR_SITE})
@@ -3028,13 +3050,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 THIRTEEN of `Controller.cycle()`'s DIRECT appends route through "
+check("all FOURTEEN 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) == 13
+      len(_direct) == 14
       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 "
@@ -3051,15 +3073,15 @@ 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. Eight of the thirteen appends are SCOPE_UNIT - `device`, "
-      "`supervised`, `failsafe`, maintenance's two, OPT-09's `pack` and "
-      "SAFETY-73's two `refused` - and all eight pass one. "
+      "share. Nine of the fourteen 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 "
       "the site, beside `circulation`, because the number that tripped it is "
       "the site target",
       _unit_sources_unrouted == []
       and len([r for r in _routing
-               if CLAIM_SCOPE.get(r[0]) == SCOPE_UNIT]) == 8)
+               if CLAIM_SCOPE.get(r[0]) == SCOPE_UNIT]) == 9)
 check("...and the only appends this pin does NOT reach are the two that file a "
       "claim BUILT ELSEWHERE - `peak_claim` and `arb_claim` - which have no "
       "`actuator=` at the call site to mis-type. Their routing is pinned where "
@@ -3068,7 +3090,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 fifteen appends account for exactly the twelve "
+check("...and between them the sixteen appends account for exactly the "
+      "thirteen "
       "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())
@@ -3129,7 +3152,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"})
+                          "refused", "mode"})
 # ⚠️ 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
@@ -5443,7 +5466,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'"))
@@ -5514,7 +5537,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 "
@@ -5944,7 +5967,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.
@@ -6023,7 +6046,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/tools/alloc_sim.py

@@ -5,6 +5,7 @@
     python3 tools/alloc_sim.py --splits      # AC 2: split-invariance at the meter
     python3 tools/alloc_sim.py --sweep       # AC 3: gain to 1.0 at every split
     python3 tools/alloc_sim.py --all
+    python3 tools/alloc_sim.py --spill       # OPT-11: surplus solar, by mode
 
     Exit 0 only if every split-invariance run HOLDS; 1 if one FAILS; 2 if no rig.
 
@@ -245,12 +246,98 @@ def sweep(sitesim, control, watchdog, cycles, load_w):
     return worst
 
 
+def spill(sitesim, control, arbiter, allocator, packmode, gain=0.6,
+          cycles=30, load_w=1000.0, pv_w=9000.0):
+    """OPT-11 P1: surplus solar spills from Solar first to Leftover solar.
+
+    The rig's two plants and the add-on's own `compute()`, `resolve()`,
+    `loop_bound()` and `packmode.charge_weights()`, with the claims main.py
+    files for this state: each unit's rating, each unit's mode, the loop, and
+    OPT-09's `pack` limit (`lo = 0`) once battery A is full. A is Solar first
+    and B Leftover solar. Three phases of `cycles` each: A has room; A is full;
+    then B is switched off. The loop is fed the site total (DEV-02).
+    Returns (rows, verdicts).
+    """
+    from plantsim import INVERTER_A, INVERTER_B, Inverter, Site
+    names = ("inverter-a", "inverter-b")
+    specs = [("A", INVERTER_A), ("B", INVERTER_B)]
+    invs = [Inverter.from_spec(n, dict(sp, **sitesim.INSTANT))
+            for n, sp in specs]
+    site = Site(invs, load=load_w, pv=pv_w)
+    tun = control.Tuning(gain=gain, max_w=sum(sp["rating_w"] for _n, sp in specs),
+                         slew_w=sitesim.EXPERIMENT_SLEW_W)
+    C = arbiter.Claim
+    prev, i_w, sat = 0.0, None, 0
+    rows = []
+    phases = (("A has room", False, True), ("A full", True, True),
+              ("A full, B off", True, False))
+    for label, a_full, b_on in phases:
+        modes = {names[0]: packmode.PackMode(True, packmode.SOLAR_FIRST),
+                 names[1]: packmode.PackMode(b_on, packmode.LEFTOVER_SOLAR)}
+        for _c in range(cycles):
+            claims = []
+            for u, (_n, sp) in zip(names, specs):
+                r = sp["rating_w"]
+                claims.append(C.limit("supervised", arbiter.P_SAFETY, -r, r,
+                                      actuator=u))
+                lo, hi = packmode.mode_range(modes[u], r)
+                claims.append(C.limit("mode", arbiter.P_MODE, lo, hi,
+                                      actuator=u))
+            if a_full:
+                claims.append(C.limit("pack", arbiter.P_SAFETY, lo=0.0,
+                                      actuator=names[0]))
+            bound = allocator.loop_bound(
+                {u: arbiter.pre_resolve([c for c in claims if c.actuator == u])
+                 for u in names})
+            d = control.compute(prev, site.grid, site.battery, tun, sat, i_w,
+                                bound=bound)
+            prev, i_w, sat = d.target_w, d.i_w, d.sat_count
+            claims.append(C.set("loop", arbiter.P_LOOP, d.target_w))
+            res = arbiter.resolve(
+                claims, units=names,
+                weights=lambda t: packmode.charge_weights(None, modes, t))
+            for inv, u in zip(invs, names):
+                inv.command(float(res.shares[u]))
+            site.settle(sitesim.CYCLE_S, dt=0.05)
+            rows.append(dict(phase=label, target=d.target_w, grid=site.grid,
+                             a=res.shares[names[0]], b=res.shares[names[1]],
+                             unmet=res.allocation.unmet_w, frozen=d.frozen,
+                             reason=d.reason, bound=bound))
+    return rows
+
+
+def spill_report(rows, cycles):
+    print("=== OPT-11 P1: surplus solar, A Solar first, B Leftover solar ===")
+    ok = True
+    for label in dict.fromkeys(r["phase"] for r in rows):
+        ph = [r for r in rows if r["phase"] == label]
+        last = ph[-1]
+        frozen = sum(r["frozen"] for r in ph)
+        print(f"  {label:15} A {last['a']:+6.0f} W  B {last['b']:+6.0f} W  "
+              f"grid {last['grid']:+7.0f} W  loop bound "
+              f"[{last['bound'][0]:.0f}, {last['bound'][1]:.0f}]  "
+              f"unmet {last['unmet']} W  frozen cycles {frozen}  "
+              f"({last['reason']})")
+        ok &= frozen == 0 and all(r["a"] <= 0 and r["b"] <= 0 for r in ph)
+        if label == "A has room":
+            ok &= last["a"] == -5000 and last["b"] < 0
+        elif label == "A full":
+            ok &= last["a"] == 0 and last["b"] == -5000
+        else:
+            ok &= last["a"] == 0 and last["b"] == 0 and last["unmet"] == 0
+    print(f"  -> spill {'HOLDS' if ok else 'FAILS'}: A fills first, the rest "
+          f"spills to B, a full A and an Off B send the surplus to the grid, "
+          f"and the loop never freezes on watts no battery may take")
+    return ok
+
+
 def main():
     ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
     ap.add_argument("--table", action="store_true")
     ap.add_argument("--splits", action="store_true")
     ap.add_argument("--sweep", action="store_true")
     ap.add_argument("--all", action="store_true")
+    ap.add_argument("--spill", action="store_true")
     ap.add_argument("--cycles", type=int, default=40)
     ap.add_argument("--load", type=float, default=2000.0)
     ap.add_argument("--gain", type=float, default=1.0)
@@ -261,7 +348,7 @@ def main():
                          "or one inverter's power (the PRE-DEV-02 sensing, "
                          "kept because the comparison is the evidence)")
     a = ap.parse_args()
-    if not (a.table or a.splits or a.sweep):
+    if not (a.table or a.splits or a.sweep or a.spill):
         a.all = True
 
     sim = find_sim()
@@ -288,6 +375,11 @@ def main():
         print()
     if a.sweep or a.all:
         sweep(sitesim, control, watchdog, a.cycles, a.load)
+        print()
+    if a.spill or a.all:
+        packmode = sitesim.load_addon("app.packmode", "alloc_sim")
+        held &= spill_report(spill(sitesim, control, arbiter, allocator,
+                                   packmode), 30)
     return 0 if held else 1
 
 

goodwe_controller/tools/opt11_identity.py

@@ -0,0 +1,289 @@
+#!/usr/bin/env python3
+"""OPT-11: with battery modes off, is every command byte-identical to before?
+
+    python3 tools/opt11_identity.py          # prints one digest per scenario
+
+Drives the REAL `Controller` (read_inputs + cycle: the freshness gate, the
+arbiter, the allocator, OPT-09's pack claim, SAFETY-73's refusal claims) in
+simulated time, and hashes, per cycle, everything a command depends on: the
+site target, each inverter's written value, the loop's reason, integrator and
+saturation count, and the allocation record. It uses only the Controller API
+that release/1.0 a5dddad already had, so the SAME file runs on the old tree and
+the new one. test_modes.py part 1 holds the new tree to the digests this file
+printed on a5dddad (they are written there, with that provenance).
+
+Scenarios: N=1 and N=2, a house that steps, a surplus of solar, a battery
+reaching its cut-out level and, at N=2, a battery that refuses (SAFETY-73) and
+is probed; the same with both batteries due for maintenance; and the arbiter
+alone on 6000 seeded claim lists (peak floor, trades, maintenance, refusals).
+"""
+
+import asyncio
+import hashlib
+import os
+import sys
+from datetime import datetime, timedelta, timezone
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+import app.main as m                                      # noqa: E402
+from app.main import Controller                           # noqa: E402
+
+TICK = 5.0
+BASE = datetime(2026, 9, 20, 11, 0, tzinfo=timezone.utc)
+
+
+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
+
+
+def house(t):
+    """A house that steps, then a solar surplus, then an evening load."""
+    if t < 300:
+        return 800.0
+    if t < 900:
+        return 3200.0
+    if t < 1500:
+        return -2600.0          # more solar than the house uses
+    if t < 2100:
+        return 1400.0
+    return 4200.0
+
+
+class _Hass:
+    """One meter, `units` batteries that follow their command unless `cut`."""
+
+    def __init__(self, units, soc, cut, load=house):
+        self.units, self.soc, self.cut, self.load = units, soc, cut, load
+        self.cmd = {u: 0.0 for u in units}
+        self.t = 0.0
+
+    def power(self, u):
+        c = self.cmd[u]
+        if self.cut(u, self.t) and c >= -4.0:
+            return -4.0
+        return float(round(c))
+
+    def grid(self):
+        return self.load(self.t) - sum(self.power(u) for u in self.units)
+
+    async def limits(self, e):
+        return (-5000.0, 5000.0, 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 self.soc(u, self.t)
+        if e.startswith("sensor.batt"):
+            return self.power(u)
+        return None
+
+    async def set_number(self, e, v):
+        self.cmd[e[-1]] = float(v)
+        return True
+
+
+def _options(n, extra):
+    common = {"meter_entity": "sensor.grid", "meter_source": "off",
+              "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}
+    if n == 1:
+        common.update({"setpoint_entity": "number.sp_a",
+                       "soc_entity": "sensor.soc_a",
+                       "batt_entity": "sensor.batt_a", "max_w": 5000,
+                       "bms_soc_floor": 10})
+    else:
+        common["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": 2500, "bms_soc_floor": 10} for u in "ab"[:n]]
+    common.update(extra or {})
+    return common
+
+
+def _soc(u, t):
+    # A empties toward its cut-out level over the run; B stays half full.
+    return max(8.0, 60.0 - t / 40.0) if u == "a" else 50.0
+
+
+def run(n, *, extra=None, dur=2700.0, store=None, on_cycle=None, load=house,
+        soc=_soc, cut=None, before=None):
+    """Cycle a real Controller; returns (rows, controller). `before(c, t)`
+    runs before each cycle, `on_cycle(c, t)` after it."""
+    units = tuple("ab"[:n])
+    if cut is None:
+        def cut(u, t):
+            return n > 1 and u == "a" and 1600.0 <= t < 2300.0
+
+    async def go():
+        hass = _Hass(units, soc, cut, load)
+        c = Controller(_options(n, extra), hass, store or _Store(), _Pub(),
+                       stop=asyncio.Event())
+        for i in c.inverters:
+            i.dev_min, i.dev_max = -5000.0, 5000.0
+        c.auto = True
+        real_dt = m.datetime
+        clock = [0.0]
+
+        class _DT(real_dt):
+            @classmethod
+            def now(cls, tz=None):
+                return BASE + timedelta(seconds=clock[0])
+
+        m.datetime = _DT
+        rows = []
+        try:
+            t = 0.0
+            while t < dur:
+                hass.t = clock[0] = t
+                if before is not None:
+                    r = before(c, t)
+                    if asyncio.iscoroutine(r):
+                        await r
+                await c.read_inputs(now_mono=t)
+                await c.cycle()
+                alloc = getattr(c, "allocation", None)
+                rows.append((t, c.target, tuple(sorted(hass.cmd.items())),
+                             c.loop_reason, round(float(c.i_w), 6),
+                             c.sat_count, c.reason,
+                             alloc.explain() if alloc is not None else None))
+                if on_cycle is not None:
+                    on_cycle(c, t)
+                t += TICK
+        finally:
+            m.datetime = real_dt
+        return rows, c
+    return asyncio.run(go())
+
+
+def digest(rows) -> str:
+    return hashlib.sha256(repr(rows).encode()).hexdigest()
+
+
+# Both batteries due for their monthly cycle at the run's first cycle, so the
+# maintenance slot, its pins and its shaping are in every row (PR #149 review:
+# the scenarios above never reach maintenance).
+_MAINT = {"maintenance_enabled": True, "maintenance_start_hour": 11}
+
+SCENARIOS = {
+    "n1": dict(n=1),
+    "n2": dict(n=2),
+    # The option present and false: what an install that saved the new
+    # option without turning it on runs. The old tree ignores the key.
+    "n1_off": dict(n=1, extra={"battery_modes_enabled": False}),
+    "n2_off": dict(n=2, extra={"battery_modes_enabled": False}),
+    "n1_maint": dict(n=1, extra=_MAINT),
+    "n2_maint": dict(n=2, extra=_MAINT),
+}
+
+
+def resolve_rows(cases=6000, seed=1149):
+    """The arbiter alone, on seeded random claim lists with no mode claim:
+    the peak floor, a trade, the loop, maintenance pins and shaping, SAFETY-73
+    refusal limits and probe pins, packs, ratings and safety stops, at one to
+    three inverters. The peak guard needs a P1 meter the cycle runs above do
+    not have, so its claim is graded here. Uses only a5dddad's API."""
+    import random
+    from math import inf
+    from app import arbiter as a
+    rnd = random.Random(seed)
+    rows = []
+    for _ in range(cases):
+        n = rnd.choice((1, 2, 3))
+        units = ("inverter-a", "inverter-b", "inverter-c")[:n]
+
+        def act(src, u):
+            return a.actuator_for(src, u, units)
+        cl = []
+        for u in units:
+            r = rnd.choice((1000.0, 2500.0, 5000.0))
+            cl.append(a.Claim.limit("supervised", a.P_SAFETY, -r, r, "max_w",
+                                    actuator=act("supervised", u)))
+            x = rnd.random()
+            if x < 0.15:
+                cl.append(a.Claim.limit("pack", a.P_SAFETY, *rnd.choice(
+                    ((0.0, inf), (-inf, 0.0))), actuator=act("pack", u)))
+            elif x < 0.25:
+                cl.append(a.Claim.limit("refused", a.P_SAFETY, *rnd.choice(
+                    ((-inf, 0.0), (0.0, inf))), "refused",
+                    actuator=act("refused", u)))
+            elif x < 0.32:
+                cl.append(a.Claim.set("refused", a.P_SAFETY,
+                                      rnd.choice((200.0, -200.0)), "probing",
+                                      actuator=act("refused", u)))
+            elif x < 0.42:
+                cl.append(a.Claim.set("maintenance", a.P_MAINTENANCE,
+                                      rnd.choice((2000.0, -2000.0)), "drain",
+                                      actuator=act("maintenance", u)))
+            elif x < 0.5:
+                cl.append(a.Claim.limit("maintenance", a.P_MAINT_SHAPE,
+                                        hi=-rnd.choice((500.0, 2000.0)),
+                                        actuator=act("maintenance", u)))
+        y = rnd.random()
+        if y < 0.8:
+            cl.append(a.Claim.set("loop", a.P_LOOP, rnd.uniform(-8000, 8000)))
+        if 0.5 < y < 0.9:
+            cl.append(a.Claim.set("arbitrage", a.P_ARBITRAGE,
+                                  rnd.uniform(-6000, 6000)))
+        if rnd.random() < 0.6:
+            cl.append(a.Claim.limit("peak", a.P_PEAK,
+                                    lo=rnd.uniform(-4000, 6000)))
+        if rnd.random() < 0.05:
+            cl.append(a.Claim.set("safety", a.P_SAFETY, 0.0, "stopped"))
+        rnd.shuffle(cl)
+        r = a.resolve(cl, units=units if n > 1 else None,
+                      weights=(None if rnd.random() < 0.5 else
+                               {u: rnd.choice((0.0, 0.5, 1.0)) for u in units}))
+        rows.append((r.target_w, r.winner, r.bound_by, r.contradiction,
+                     tuple(sorted((r.shares or {}).items())), r.allocated,
+                     r.allocation.explain() if r.allocation else None))
+    return rows
+
+
+def digests() -> dict:
+    out = {k: digest(run(**v)[0]) for k, v in SCENARIOS.items()}
+    out["resolve"] = digest(resolve_rows())
+    return out
+
+
+if __name__ == "__main__":
+    if "--summary" in sys.argv:
+        for k, v in SCENARIOS.items():
+            rows = run(**v)[0]
+            print(f"{k}: {len(rows)} cycles, loop reasons "
+                  f"{sorted({r[3] for r in rows})}, arbiter "
+                  f"{sorted({r[6].split(' ->')[0] for r in rows})}")
+        rr = resolve_rows()
+        print(f"resolve: {len(rr)} claim lists, winners "
+              f"{sorted({r[1] for r in rr})}, bound by "
+              f"{sorted({str(r[2]).split('(')[0] for r in rr})}")
+    for k, v in digests().items():
+        print(f"{k} {v}")

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/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/ux13_browser_check.py

@@ -0,0 +1,233 @@
+"""UX-13 P3: the headless-browser check of the Batteries screen and Settings,
+Simple. Run by `CHECK=1 tools/ux13_screenshots.sh`, like the screenshots.
+
+For every battery-mode fixture (tools/ux13_demo.py) it opens both screens at
+phone and desktop width, light and dark, in English and Dutch, and fails on a
+page error, a console error or a sideways scroll. Then it clicks the switch
+and the mode list on both screens and checks what was posted and what the
+cards show after.
+
+    python3 ux13_browser_check.py        # DEMO_<STATE> = the fixture's URL
+"""
+
+import json
+import os
+import sys
+
+from playwright.sync_api import sync_playwright
+
+STATES = ("running", "modes", "off", "off_peak", "refusal", "maint")
+SIZES = {"phone": {"width": 390, "height": 844},
+         "desktop": {"width": 1000, "height": 900}}
+FAILS = []
+
+
+def url(state):
+    return os.environ[f"DEMO_{state.upper()}"]
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        FAILS.append(name)
+
+
+def open_page(browser, state, route, *, size, scheme, lang):
+    ctx = browser.new_context(locale=lang, viewport=SIZES[size],
+                              color_scheme=scheme, reduced_motion="reduce")
+    page = ctx.new_page()
+    errors = []
+    page.on("pageerror", lambda e: errors.append(f"pageerror {e}"))
+    page.on("console", lambda m: errors.append(f"console {m.text}")
+            if m.type == "error" else None)
+    page.goto(url(state) + route)
+    page.wait_for_load_state("networkidle")
+    page.wait_for_timeout(1200)
+    return ctx, page, errors
+
+
+def sweep(browser):
+    n = 0
+    for state in STATES:
+        for route in ("#batteries", "#settings"):
+            for size in SIZES:
+                for scheme in ("light", "dark"):
+                    for lang in ("en-GB", "nl-BE"):
+                        ctx, page, errors = open_page(
+                            browser, state, route, size=size, scheme=scheme,
+                            lang=lang)
+                        wide = page.evaluate(
+                            "document.documentElement.scrollWidth > "
+                            "document.documentElement.clientWidth")
+                        if route == "#batteries":
+                            cards = page.locator("#bcards .bcard").count()
+                            texts = page.locator("#bcards dd").all_inner_texts()
+                            ok = cards == 2 and all(t.strip() for t in texts)
+                        else:
+                            ok = (page.locator("#simple .card").count() >= 3
+                                  and page.locator("#groups").is_hidden())
+                        where = f"{state} {route} {size} {scheme} {lang}"
+                        if errors or wide or not ok:
+                            FAILS.append(f"{where}: errors={errors} "
+                                         f"wide={wide} drawn={ok}")
+                            print(f"  FAIL {where}: {errors} wide={wide} "
+                                  f"drawn={ok}")
+                        n += 1
+                        ctx.close()
+    check(f"{n} views: 0 page errors, 0 console errors, no sideways scroll, "
+          f"every card drawn", not [f for f in FAILS if " #" in f])
+
+
+def posts(page):
+    sent = []
+    page.on("request", lambda r: sent.append(json.loads(r.post_data))
+            if r.url.endswith("/action") and r.method == "POST" else None)
+    return sent
+
+
+def actions(browser):
+    # The Batteries screen: switch B off, then set A to Leftover solar.
+    ctx, page, errors = open_page(browser, "modes", "#batteries",
+                                  size="desktop", scheme="light", lang="en-GB")
+    sent = posts(page)
+    page.locator("#bsw-c1").click()
+    page.wait_for_timeout(1500)
+    card_b = page.locator("#bcards .bcard").nth(1)
+    check("Batteries: B's switch posts pack_use false, and B's card turns Off "
+          "with its mode list greyed out",
+          sent[-1:] == [{"action": "pack_use", "unit": "Battery B",
+                         "value": False}]
+          and "off" in (card_b.get_attribute("class") or "")
+          and page.locator("#bsel-c1").is_disabled()
+          and "You switched it off." in card_b.inner_text())
+    page.locator("#bsel-c0").focus()
+    page.locator("#bsel-c0").select_option("leftover_solar")
+    page.wait_for_timeout(1500)
+    check("...A's list posts pack_mode leftover_solar and the card keeps it",
+          sent[-1:] == [{"action": "pack_mode", "unit": "Battery A",
+                         "value": "leftover_solar"}]
+          and page.locator("#bsel-c0").input_value() == "leftover_solar"
+          and "Leftover solar" in page.locator("#bcards .bcard").nth(0)
+          .inner_text())
+    check("...the cheap-hours choice and the selling switch are greyed out",
+          page.locator("#bsel-c0 option[disabled]").count() == 1
+          and page.locator("#bcards .bcard .f .switch[disabled]").count() == 2)
+    check("...and the focus stays on the control that was used",
+          page.evaluate("document.activeElement.id") == "bsel-c0")
+    check("...with 0 page errors", not errors)
+    ctx.close()
+    # Settings, Simple: the same switch, and the Installer view is one tap.
+    ctx, page, errors = open_page(browser, "modes", "#settings",
+                                  size="phone", scheme="dark", lang="nl-BE")
+    sent = posts(page)
+    page.locator("#bsw-s1").click()
+    page.wait_for_timeout(1500)
+    check("Simple (NL, phone, dark): B's switch posts pack_use true and reads "
+          "Aan", sent[-1:] == [{"action": "pack_use", "unit": "Battery B",
+                                "value": True}]
+          and page.locator("#bsw-s1").get_attribute("aria-checked") == "true")
+    page.locator("#set-view [data-v=installer]").click()
+    page.wait_for_timeout(500)
+    check("...Installer shows the groups and hides Simple",
+          page.locator("#groups").is_visible()
+          and page.locator("#simple").is_hidden())
+    check("...with 0 page errors", not errors)
+    ctx.close()
+
+
+def switching(browser):
+    # Review: an unsaved change survives the view switch both ways, the
+    # Installer's locked values still need "Change", and only the person's
+    # own pick of a view is remembered.
+    ctx, page, errors = open_page(browser, "modes", "#settings",
+                                  size="desktop", scheme="light", lang="en-GB")
+    chips = [c.locator(".chip").first.inner_text()
+             for c in page.locator("#simple > .card").all()]
+    check(f"Simple's badges: the peak limit and shadow mode need a restart, "
+          f"the batteries apply at once ({chips})",
+          chips == ["Applies after a restart", "Applies right away",
+                    "Applies after a restart"])
+    num = page.locator("#simple .card input.num").first
+    num.fill("4.2")
+    num.dispatch_event("change")
+    page.wait_for_timeout(600)
+    n1 = page.locator("#sb-text").inner_text()
+    page.locator("#set-view [data-v=installer]").click()
+    page.wait_for_timeout(600)
+    val = page.locator("#groups [data-key=peak_cap_w] input.num").input_value()
+    n2 = page.locator("#sb-text").inner_text()
+    locked = (page.locator("#groups [data-key=peak_soc_floor] input").count(),
+              page.locator("#groups [data-key=peak_soc_floor] button.link")
+              .count())
+    page.locator("#set-view [data-v=simple]").click()
+    page.wait_for_timeout(600)
+    back = page.locator("#simple .card input.num").first.input_value()
+    n3 = page.locator("#sb-text").inner_text()
+    check("an unsaved peak limit survives Simple -> Installer -> Simple, and "
+          "the save bar counts it once", n1.startswith("1 ") and n2 == n1
+          and n3 == n1 and val == "4.2" and back == "4.2"
+          and page.locator("#savebar").is_visible())
+    check("...the Installer's locked value has no input until 'Change'",
+          locked == (0, 1))
+    ctx.close()
+    ctx, page, errors = open_page(browser, "running", "#batteries",
+                                  size="desktop", scheme="light", lang="en-GB")
+    page.locator("#batt-off a").click()
+    page.wait_for_timeout(800)
+    page.reload()
+    page.wait_for_load_state("networkidle")
+    page.wait_for_timeout(1200)
+    check("a jump to Installer from a link is not remembered: Settings "
+          "opens on Simple again", page.locator("#simple").is_visible()
+          and page.locator("#groups").is_hidden() and not errors)
+    ctx.close()
+
+
+def modes_off(browser):
+    ctx, page, errors = open_page(browser, "running", "#batteries",
+                                  size="phone", scheme="light", lang="en-GB")
+    page.locator("#batt-off a").click()
+    page.wait_for_timeout(1500)
+    check("modes off: the card's button opens Settings on the Installer view",
+          page.url.endswith("#settings") and page.locator("#groups")
+          .is_visible() and not errors)
+    ctx.close()
+
+
+def month_peak(browser):
+    # The fixture has no month peak yet, so give /status one on the way in.
+    ctx = browser.new_context(locale="en-GB", viewport=SIZES["desktop"])
+    page = ctx.new_page()
+
+    def with_peak(route):
+        r = route.fetch()
+        body = r.json()
+        body["month_peak"]["peak_w"] = 2860.0
+        route.fulfill(response=r, json=body)
+    page.route("**/status*", with_peak)
+    page.goto(url("modes") + "#settings")
+    page.wait_for_load_state("networkidle")
+    page.wait_for_timeout(1500)
+    check("Simple: the peak card shows this month's peak from /status",
+          "This month's peak so far: 2.9 kW." in page.locator("#simple")
+          .inner_text())
+    ctx.close()
+
+
+def main():
+    with sync_playwright() as p:
+        b = p.chromium.launch()
+        sweep(b)
+        actions(b)
+        month_peak(b)
+        switching(b)
+        modes_off(b)
+        b.close()
+    if FAILS:
+        print(f"{len(FAILS)} FAILED")
+        sys.exit(1)
+    print("all passed")
+
+
+if __name__ == "__main__":
+    main()

goodwe_controller/tools/ux13_demo.py

@@ -2,7 +2,9 @@
 headless browser check.  `python3 tools/ux13_demo.py STATE PORT [HOST]`
 
 STATE is running, shadow, alarm, new (P4) or setup (UX-15's setup-only
-mode, P5). The controller is the shipped `Controller`
+mode, P5). P3 adds the battery-mode states in `P3`: modes (on, B on Leftover
+solar), off (B switched off), off_peak (B off but giving for the peak limit),
+refusal (A refuses to give power) and maint (A in its monthly cycle). The controller is the shipped `Controller`
 with its readings set by hand (two batteries, solar, today's prices in the
 mockup's shape, trading on). Nothing here talks to Home Assistant or to an
 inverter: `/action` changes only this fixture. Used for the P1 render check
@@ -34,8 +36,9 @@ sys.path.insert(0, os.path.join(HERE, "tools"))
 
 from aiohttp import web as aioweb                                # noqa: E402
 
-from app import homeview, web                                    # noqa: E402
+from app import homeview, packmode, web                          # noqa: E402
 from app.main import Controller                                  # noqa: E402
+from app.maintenance import DRAIN                                # noqa: E402
 from app.setuponly import SetupOnly                              # noqa: E402
 from app.peakguard import PeakDecision                           # noqa: E402
 from app.price import PricePoint, PriceProduct, PriceRead        # noqa: E402
@@ -231,8 +234,14 @@ OPTS = {"meter_entity": "sensor.grid", "meter_source": "off",
              "max_w": 2500, "capacity_kwh": 5.4}]}
 
 
+# UX-13 P3: the battery-mode states, each with battery modes on.
+P3 = ("modes", "off", "off_peak", "refusal", "maint")
+
+
 def controller(state):
     opts = dict(OPTS, shadow_mode="on" if state == "shadow" else "off")
+    if state in P3:
+        opts["battery_modes_enabled"] = True
     c = Controller(opts, Hass(), Store(), Pub(), stop=asyncio.Event())
     c.auto = True
     now = datetime.now(timezone.utc)
@@ -255,6 +264,29 @@ def controller(state):
     c.pv_w = 3900.0
     if state == "alarm":
         c.inverters[0].sign_wd.tripped = True
+    if state in P3:
+        a, b = c.inverters
+        b.store_set(packmode.MODE_KEY, packmode.LEFTOVER_SOLAR)
+        if state in ("off", "off_peak"):
+            b.store_set(packmode.USE_KEY, False)
+            b.batt = 0.0
+        if state == "off_peak":
+            # A cloudy evening: the house takes 6 kW and the peak limit needs
+            # both batteries, so B gives 0.5 kW although it is switched off.
+            c.pv_w, c.grid = 0.0, 3490.0
+            a.batt, b.batt = 2000.0, 510.0
+            c.peak_guard = PeakDecision(engaged=True, floor_w=2500.0,
+                                        ceiling_w=3500.0, ceiling_from="cap",
+                                        projected_w=3600.0)
+        if state == "refusal":
+            # A is at its cut-out level and refuses: asked 0 W, B takes over.
+            c.pv_w, c.grid = 0.0, 5.0
+            a.soc, a.batt, a.refused = 9.0, -4.0, 1
+            b.batt = 1210.0
+        if state == "maint":
+            c.maints[0].store.set("phase", DRAIN)   # MAINT-05: A's own key
+            c.pv_w, c.grid = 0.0, 0.0
+            a.batt, b.batt = 2000.0, 0.0
     return c
 
 
@@ -290,6 +322,7 @@ async def main(state, port, host="127.0.0.1"):
                   p1_net_entity="sensor.grid", price_provider="generic_dayahead",
                   peak_forecast_entity="sensor.peak_forecast",
                   shadow_mode=c.o.get("shadow_mode", "off"),
+                  battery_modes_enabled=state in P3,
                   inverters=[dict(i, bms_soc_floor=10)
                              for i in OPTS["inverters"]])
     runner = aioweb.AppRunner(web.build_app(c, Supervisor(stored)))

goodwe_controller/tools/ux13_screenshots.py

@@ -6,8 +6,8 @@ error, so a broken screen is never pictured.
 
     python3 ux13_screenshots.py OUT_DIR    # DEMO_<STATE> = the fixture's URL
 
-The battery-mode screens (P3) are not built, so there is no shot of them:
-DOCS.md says so instead of showing a mock-up.
+P3 adds the Batteries screen and Settings, Simple (the default Settings
+view), so the Installer shots click Installer first.
 """
 
 import os
@@ -48,7 +48,12 @@ def shot(browser, name, state, route, *, lang="en-GB", size=DESKTOP,
     print(f"  {name}.png")
 
 
+def installer(page):
+    page.locator("#set-view [data-v=installer]").click()
+
+
 def open_tariff(page):
+    installer(page)
     page.locator("details.grp[data-g=tariff] > summary").click()
     page.locator("details.grp[data-g=meter] > summary").click()   # close it
     # The fixture site is on a dynamic contract: its fallback gets windows.
@@ -80,8 +85,17 @@ def main():
         shot(b, "home-shadow", "shadow", "#home")
         shot(b, "home-phone", "running", "#home", size=PHONE)
         shot(b, "home-setup-only", "setup", "#home", full=False)
-        shot(b, "settings-installer", "running", "#settings")
-        shot(b, "settings-installer-nl", "running", "#settings", lang="nl-BE")
+        shot(b, "settings-installer", "running", "#settings", act=installer)
+        shot(b, "settings-installer-nl", "running", "#settings", lang="nl-BE",
+             act=installer)
+        shot(b, "batteries", "modes", "#batteries")
+        shot(b, "batteries-nl", "modes", "#batteries", lang="nl-BE")
+        shot(b, "batteries-off-peak", "off_peak", "#batteries")
+        shot(b, "batteries-phone", "refusal", "#batteries", size=PHONE,
+             full=False)
+        shot(b, "batteries-modes-off", "running", "#batteries", full=False)
+        shot(b, "settings-simple", "modes", "#settings")
+        shot(b, "settings-simple-nl", "modes", "#settings", lang="nl-BE")
         tariff = "details.grp[data-g=tariff]"
         shot(b, "settings-time-windows", "running", "#settings",
              act=windows, only=tariff)

goodwe_controller/tools/ux13_screenshots.sh

@@ -2,6 +2,7 @@
 # UX-13 P5: regenerate the DOCS screenshots in docs/img/ux13/ from the real page.
 #
 #   sh goodwe_controller/tools/ux13_screenshots.sh [OUT_DIR]
+#   CHECK=1 sh goodwe_controller/tools/ux13_screenshots.sh   # P3 browser check
 #
 # Serves tools/ux13_demo.py's fixtures (running, shadow, new, setup) in the CI
 # test image, then runs tools/ux13_screenshots.py in the Playwright image on a
@@ -14,7 +15,9 @@ HERE=$(cd "$(dirname "$0")/.." && pwd)
 OUT=${1:-$HERE/../docs/img/ux13}
 PW=mcr.microsoft.com/playwright/python:v1.55.0-noble
 NET=ux13-shots-$$
-STATES="running shadow new setup"
+STATES="running shadow new setup modes off off_peak refusal maint"
+RUN=/t/ux13_screenshots.py
+[ "${CHECK:-}" = 1 ] && RUN=/t/ux13_browser_check.py
 mkdir -p "$OUT"
 OUT=$(cd "$OUT" && pwd)
 
@@ -39,5 +42,5 @@ docker run --rm --network "$NET" --user "$(id -u):$(id -g)" -e HOME=/tmp \
     $ENVS -v "$HERE/tools:/t:ro" -v "$OUT:/out" "$PW" \
     sh -euc 'pip install -q --disable-pip-version-check --target /tmp/pw \
                  playwright==1.55.0
-             PYTHONPATH=/tmp/pw python3 /t/ux13_screenshots.py /out'
+             PYTHONPATH=/tmp/pw python3 '"$RUN"' /out'
 echo "screenshots in $OUT"

goodwe_controller/translations/en.yaml

@@ -82,6 +82,9 @@ configuration:
   estop_fitted:
     name: "Hardware · RS485 emergency stop is fitted"
     description: "Switch this on if the emergency stop is installed. It only changes a warning on the status page."
+  battery_modes_enabled:
+    name: "Hardware · Battery modes"
+    description: "Give each battery an on and off switch and a mode, set on the Batteries screen."
   pv_entity:
     name: "Hardware · Solar production entity (W)"
     description: "Optional. Your solar inverter's power sensor, positive while producing. The add-on records it and does not use it for control."
@@ -142,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

@@ -63,6 +63,9 @@ configuration:
   estop_fitted:
     name: "Hardware · RS485-noodstop is geplaatst"
     description: "Zet dit aan als de noodstop geïnstalleerd is. Het verandert alleen een waarschuwing op de statuspagina."
+  battery_modes_enabled:
+    name: "Hardware · Batterijmodi"
+    description: "Geef elke batterij een aan- en uitschakelaar en een modus, in te stellen op het scherm Batterijen."
   pv_entity:
     name: "Hardware · Entiteit zonneproductie (W)"
     description: "Optioneel. De vermogenssensor van uw zonne-omvormer, positief tijdens productie. De add-on houdt ze bij en regelt er niet mee."
@@ -123,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."