fix(output): classify plan-table charge state against the real limit, not the predicted end-of-window SoC (#4445)

[chalfontchubby]

Posted by Claude on behalf of @chalfontchubby.

Fixes #4445.

Problem

output.py decided a charge window's plan-table state (Chrg/HoldChrg) by comparing the row's SoC with charge_window_best[n]["target"]. That is the SoC the window is predicted to reach by its end, stamped by plan.py's discard_unused_charge_slots() and clip_charge_slots() when a charge can't complete within the window. It is not the real charge_limit_best[n] instruction that execute.py sends to the inverter.

So a genuine full-rate charge that can't finish within one window could display HoldChrg -> (predicted %) whenever the row's SoC sat above that prediction. Confirmed live: charge_limit_best[0] was 100% (both in the optimiser's own output and in the GivTCP command actually sent), while the plan displayed HoldChrg -> 60% for the same window.

Fix

Following the direction agreed on #4445, the fix is narrow:

• Chrg vs HoldChrg is decided from the real limit (charge_limit_best), the same way execute.py decides "Hold charging" live (SoC at or above the target).
• A Chrg row keeps displaying the predicted SoC in the Limit cell, the reason text and state_target, as before. That predicted figure is what PR Add textual plan, levels rate fix when no charge/export windows exist #2358 added target to show. Showing the instruction instead would make every window that clip_charge_slots raises to a full charge read 100%, even when the plan only expects it to reach a lower SoC.
• A HoldChrg row displays the limit it is held at. Otherwise its reason ("already at or above the X% target") could quote a prediction that contradicts the row. Where the prediction equals the limit (the usual hold case), this is the same figure as before.
• The plan_debug bracket still follows the displayed figure with the limit (e.g. 60 (80) on a Chrg row). On a HoldChrg row both are now the limit (80 (80)), so the prediction is no longer shown there. The predbat.status summary text and export rows are unchanged.

One consequence: when PV is predicted to carry the SoC past a charge limit, a row already above the limit now shows HoldChrg at the limit instead of Chrg towards the higher prediction. That matches what the inverter is doing, since it is not grid-charging.

Known limit, not addressed here: the mismatch behind #4445 looks like a stale target. The final discard_unused_charge_slots() (plan.py ~2196) runs after clip_charge_slots() but recalculates target from self.predict_soc, which was simulated before the limits were raised. The published plan (predict_soc_best) comes from a later prediction with the clipped limits, and in low-power charge mode that later prediction can charge faster. So a Chrg row can still display a predicted figure below its own SoC (e.g. Chrg -> 60 at 70%). Refreshing target from the final prediction would fix the display too, but that is a planner change and would be better as a separate issue.

Testing

New cases in test_plan_why_reason.py:

• The Plan shows 'Hold Charge' for windows that are actually issuing a full-rate charge #4445 symptom: SoC 70%, between a 60% prediction and an 80% limit, now shows Chrg (displaying 60), not HoldChrg. This fails on main with hold_charge_at_target.
• A real hold: SoC above the limit still shows HoldChrg and reports the 80% limit.
• PV overshoot: the prediction (95%) is above the limit (80%) and the SoC (85%) is between them. The row shows HoldChrg at 80%.
• plan_debug Limit cell: reads 60 (80) (predicted SoC, then limit).
• get_charge_export_text() (previously untested): reports the predicted SoC, or the limit when there is no prediction.

--quick suite and pre-commit green.

🤖 Generated with Claude Code

[Copilot]

🔵 Needs a closer look

The regression test setup does not reproduce the prior misclassification and should be adjusted before approval.

0 open findings

What changed in this PR

Fixes charge-state reporting to use the real inverter charge limit while preserving predicted SoC details.

Changes:

• Corrects plan-table classification and debug output.
• Updates textual charge summaries.
• Adds regression and summary-text tests.

File	Reviewed changes
apps/​predbat/​tests/​test_plan_why_reason.py	Adds regression coverage for charge display behavior.
apps/​predbat/​output.py	Uses real charge limits for classification and summaries.

🧠 Review effort: Lite

---

Give feedback about Copilot approvals in this survey to enter a drawing for a $150 gift card.