refactor(clock): drop the host-timezone clock, measure everything from now_utc

[springfall2008]

_Posted by Claude on behalf of @springfall2008 _

Follow-up to #5054, which fixed ComponentBase.midnight_utc reading a calculate_yesterday()-rewound value. Trying to give minutes_now the same treatment surfaced why it could not simply be derived: it is measured from a different clock.

Problem

update_time() kept two clocks:

self.now_utc = datetime.now(self.local_tz)   # the configured `timezone:` setting → midnight_utc
self.now     = datetime.now()                # whatever timezone the container is in → midnight, minutes_now

minutes_now and the time_abs_str/time_now_str renderings came off the second one. They agree only while the container's timezone matches the timezone: setting.

When they do not:

• minutes_now indexes rate and forecast arrays that are keyed in minutes from midnight_utc, so Predbat reads "now" at the wrong point in its own rates.
• time_abs_str(minute) renders midnight_utc-keyed offsets against a differently-offset midnight, so every timestamp it publishes - the plan table included - is shifted from the data it labels.

A test run on a UTC+3 host with timezone: Europe/London shows the two 120 minutes apart.

Fix

Measure everything from now_utc, and delete self.now / self.midnight.

now_utc and the midnight derived from it share a tzinfo (replace() keeps it), so the subtractions stay wall-clock differences - identical to the naive arithmetic they replace. Checked on both 2026 DST changeover days plus a control date.

The one caller that genuinely needs the host clock is the scheduler in initialize(): its run times are handed to run_every(), and hass.py's timer_tick compares them against datetime.now(). It now computes that locally rather than two instance fields existing for its sake.

Also in scope, because they shared the fields:

• minutes_since_yesterday() built its comparison point with datetime.combine(), which drops tzinfo - replace() instead, same answer for the same wall clock.
• fetch.py's date: overrides are parsed naive from apps.yaml, so they take midnight_utc's offset before the subtraction; day_of_week now reads the configured timezone's weekday.
• futurerate's cache-age arithmetic stays on the host clock - its stamps are host-naive and persisted to storage by earlier versions, so an upgrade must keep reading them. It just computes its own midnight rather than borrowing Predbat's.
• predheat carried its own copy of the same split and gets the same treatment.

Behaviour change

Confined to setups where the container timezone differs from the timezone: setting: their minutes_now and rendered timestamps move to the configured timezone, which is the fix. Matched setups - the normal HA addon case - see nothing move.

Testing

New tests/test_clock.py pins a configured timezone that deliberately disagrees with the host (Pacific/Kiritimati, UTC+14, no DST). That disagreement is the only thing that makes the two clocks separable - on a machine where they agree, the old and new code are indistinguishable, which is why nothing caught this before.

Mutation-tested: restoring the host clock fails the new tests (minutes_now 930 against a configured-timezone 150) and nothing else.

• ./run_all --quick green (314 tests) under both a mismatched host timezone and TZ=Europe/London
• ./run_pre_commit green

Follow-up, not in this PR

now_utc/midnight_utc are misnamed - they are timezone-aware local time for the inverter system, never UTC. Worth renaming now that they are the only clock.

🤖 Generated with Claude Code

[chalfontchubby]

Hmm. That's not a pr I thought I'd pushed. Need to check what Claude has been up to.

[Copilot]

🟡 Changes recommended

Unresolved moderate clock-consistency findings remain in predbat.py and test_clock.py, plus a PredHeat regression-test gap.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

This PR refactors Predbat and PredHeat to use the configured timezone clock consistently while preserving host-time handling for scheduling and legacy cache timestamps.

Changes:

• Consolidates configured-time clock calculations and updates date/rate handling.
• Preserves host-clock compatibility for scheduling and FutureRate caches.
• Adds mismatched-timezone regression coverage and updates affected tests and documentation.

File summaries

File	Reviewed changes and final review notes
apps/predbat/utils.py	Updates timezone-aware elapsed-time calculations.
apps/predbat/unit_test.py	Registers clock tests.
apps/predbat/tests/test_rate_replicate_missing_slots.py	Updates timezone-aware fixtures.
apps/predbat/tests/test_manual_times.py	Removes obsolete clock restoration.
apps/predbat/tests/test_manual_soc.py	Removes obsolete clock restoration.
apps/predbat/tests/test_manual_soc_max.py	Removes obsolete clock restoration.
apps/predbat/tests/test_clock.py	Adds mismatched-timezone regression tests. Moderate, 1 vote: the midnight comparison can falsely fail due to rounding and separate clock reads; use cyclic distance or capture the wall clock before updating.
apps/predbat/tests/test_basic_rates.py	Updates clock fixtures.
apps/predbat/tests/test_basic_rates_utc.py	Removes obsolete host-clock fixtures.
apps/predbat/predheat.py	Aligns prediction calculations with configured time. Nit, 1 vote: add regression coverage for differing configured and host timezones.
apps/predbat/predbat.py	Consolidates clock calculations and scheduler timing. Moderate, 2 votes: update TeslemetryAPI._local_today_weekday() to use the base configured clock or preserve a compatibility alias. Moderate, 1 vote: avoid rendering current-time strings from rewound midnight_utc during calculate_yesterday().
apps/predbat/futurerate.py	Preserves host-naive cache timestamp compatibility.
apps/predbat/fetch.py	Uses configured timezone for date overrides and weekdays.
apps/predbat/annual_tariff.py	Updates clock-origin documentation.
.cspell/custom-dictionary-workspace.txt	Adds Kiritimati to the dictionary.

Review details

Suppressed comments (3)

apps/predbat/predbat.py:291

• calculate_yesterday() temporarily rewinds the shared self.midnight_utc (output.py:3296), while inverter/component threads can call base.time_now_str() (for example inverter.py:1917). This change makes a live notification render with yesterday's date during that window; the old self.midnight snapshot was not rewound. Render this current-time string from stable self.now_utc (or synchronize the rewind).

        return (self.midnight_utc + timedelta(minutes=self.minutes_now)).strftime("%H:%M:%S")

apps/predbat/predheat.py:537

• Please add a regression test for this new PredHeat.update_pred() clock calculation with a configured timezone different from the host. The existing Predheat test replaces update_pred with a lambda (apps/predbat/tests/test_predheat.py:31-34), so this changed code is never executed and a regression back to the host clock would still pass the suite.

        # Measured against now_utc like the rest of Predbat, rather than a second naive clock
        # taken from the host's timezone - see update_time() in predbat.py.
        self.minutes_now = int((now_utc - self.midnight_utc).total_seconds() / 60 / PREDICT_STEP) * PREDICT_STEP

apps/predbat/tests/test_clock.py:93

• This comparison treats midnight as a discontinuity. If update_time() runs at 23:59:xx, it rounds minutes_now to 23:55, then the separate datetime.now() can already be 00:00; the absolute difference is 1435 and the test fails even though the configured clock is correct. Compare the cyclic distance between the two minute values (or capture the wall clock before the update).

    if abs(clock["minutes_now"] - wall_minutes) > PREDICT_STEP:

• Files reviewed: 15/15 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[springfall2008]

Hmm. That's not a pr I thought I'd pushed. Need to check what Claude has been up to.

No this is a new one from me to follow up the solcast time fix

[chalfontchubby]

Makes sense, seen a few with related time stuff that implied a refactor might be good.  Sent from Yahoo Mail for iPhone On Monday, September 14, 2026, 1:51 pm, Trefor Southwell ***@***.***> wrote: springfall2008 left a comment (springfall2008/batpred#5084) Hmm. That's not a pr I thought I'd pushed. Need to check what Claude has been up to. No this is a new one from me to follow up the solcast time fix — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.Message ID: ***@***.***>

[springfall2008]

Posted by Claude on behalf of @springfall2008.

Worked through the Copilot review. Three findings held up and are fixed in 5f05735; one does not.

1. TeslemetryAPI._local_today_weekday() read base.now — real, and the nastiest of the four.

It reads through getattr(base, "now", None) with a fallback, so deleting the field did not break it: it silently dropped to the live wall clock, losing clock_skew and any pinned clock. Worse, the test doubles pinned base.now as well, so the suite stayed green through exactly the change that broke it. Now reads base.now_utc, doubles moved over, and a new test pins the weekday against a fixed Thursday so a fallback fails on six days in seven. Mutation-tested: reverting gives Expected Thursday (3), got 0.

2. PredHeat coverage gap — real. Confirmed test_predheat.py replaces update_pred with a lambda, so the changed line never executed. Rather than add a heavyweight test around update_pred, both callers now share utils.minutes_since_midnight(), which is tested directly — including both 2026 DST changeover days. That also removes the duplicated formula that made drift possible.

3. test_clock.py midnight discontinuity — real flake. At 23:59 update_time() floors to 23:55 while the later read is already 00:00: five minutes apart, 1435 by subtraction. Compares cyclic distance now.

4. time_now_str() rendering yesterday's date during calculate_yesterday() — does not hold.

Three separate reasons:

• time_now_str() renders "%H:%M:%S". There is no date in it, and midnight_utc - 1 day has the same time-of-day, so the rewind cannot change its output.
• calculate_yesterday() fakes minutes_now to 0 for the same window, so that string rendered 00:00:00 both before and after this PR.
• The concurrency premise is wrong: ComponentBase does not expose time_now_str/time_abs_str at all, so no component thread can reach them. The cited caller (inverter.py:1917) runs on the main update loop, and load_axle_slot — the only other base.time_abs_str caller outside the base mixins — is called from fetch.py on that same thread.

Worth noting the related effect that is real and intended: time_abs_str is now anchored to midnight_utc, so yesterday's plan HTML renders yesterday's dates. It previously rendered them against today's naive midnight, i.e. a day out.

./run_all --quick green (314 tests), pre-commit clean.