fix(cron): record the timezone a cron schedule is evaluated in

[JoaoMarcos44]

Summary

A cron expression is local wall-clock intent ("run at 14:30"), but next_run_at is persisted as an absolute instant. Which zone that wall clock belonged to was never recorded — every process re-resolved it from HERMES_TIMEZONE / config.yaml at the moment it read or wrote the job.

That makes a persisted next_run_at ambiguous the instant two readers disagree. hermes_time cached the resolved zone for the whole process lifetime, so a gateway that booted before timezone: Asia/Shanghai was added kept running on server-local time, while every freshly spawned CLI / web worker picked the new zone up immediately. The same string then meant two different instants, and the due check silently flipped between "absolute instant" and "naive wall clock" semantics depending on an offset comparison — moving the job by the whole UTC offset (8h) at the next gateway restart, firing it early and swallowing the genuine run.

Fixes #88220.

%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#8b0000', 'mainBkg': '#0a0204', 'primaryTextColor': '#ffccd5', 'primaryBorderColor': '#ff0038', 'lineColor': '#ff0038'}}}%%
graph TD
    subgraph BEFORE["Before - the zone is implicit"]
        A1["Gateway process<br/>booted before timezone: was set<br/>resolves server-local"] -->|writes / reads| S1[("jobs.json<br/>next_run_at: 2026-08-17T14:30+08:00")]
        A2["CLI / web worker<br/>resolves Asia/Shanghai"] -->|writes / reads| S1
        S1 --> D1{"Due check<br/>offset label == my offset?"}
        D1 -->|"no - reinterpret as wall clock"| X1["Fires 8h early<br/>real run swallowed"]
        D1 -->|"yes - absolute instant"| X2["Different answer<br/>same file, other process"]
    end

    subgraph AFTER["After - the schedule carries its own zone"]
        B1["Gateway process"] --> S2[("jobs.json<br/>schedule.tz: Asia/Shanghai<br/>next_run_at: 2026-08-17T14:30+08:00")]
        B2["CLI / web worker"] --> S2
        S2 --> C1["croniter evaluated on the<br/>naive wall clock of schedule.tz"]
        C1 --> R1["One instant, every reader"]
        S2 --> Z{"configured zone<br/>!= schedule.tz ?"}
        Z -->|"yes - operator changed timezone:"| Z1["Re-anchor once to the same<br/>wall clock in the new zone, re-stamp"]
        Z -->|"no - DST only moved the offset"| R1
    end

Loading

Is it really a bug?

Yes, and it is two bugs. Reproduced with a virtual-clock ticker simulation that drives the real get_due_jobs() / mark_job_run() pair minute by minute and compares the fire log against the cron expression evaluated independently in the job's own zone.

Scenario group	Cases	Fail on main	Fail with this PR
Daily job, reader in the same zone	13	0	0
Daily job, reader with no configured zone (the #88220 gateway)	13	13	0
5 cron expressions x 3 zones, zone-less reader	15	12	0
DST boundaries, north + south, no timezone change at all	6	5	0
Restarts that flip the reader's resolved zone	3	3	0
Total	47	31	0

Sample from main, Asia/Shanghai, 30 14 * * *: fired at 14:30Z for five days running; the correct instants (06:30Z) were all missed — the exact 8-hour shift in the report.

Second bug this surfaced

croniter walks a fixed UTC offset taken from its base datetime, so handing it a zone-aware base drifts by the DST delta across a transition:

>>> croniter("0 9 * * *", datetime(2026, 3, 28, 9, 0, tzinfo=ZoneInfo("Europe/Berlin"))).get_next(datetime)
datetime.datetime(2026, 3, 29, 8, 0, tzinfo=zoneinfo.ZoneInfo(key='Europe/Berlin'))   # an hour early

In the simulation this costs a daily job an extra fire on every spring-forward day and a lost fire on every fall-back day, with no timezone divergence involved. It affects every DST-observing install today.

Root cause fix

1. The schedule records the zone it is evaluated in. parse_schedule stamps schedule["tz"] with the configured IANA zone; compute_next_run anchors croniter to it, evaluating the expression on that zone's naive wall clock and localizing the result. Gateway, CLI and web UI now compute the same instant regardless of what each of them resolves — and 09:00 stays 09:00 across a DST boundary.

2. Zone-identity rebase replaces the offset-delta heuristic. When timezone: genuinely changes, the job is re-anchored once to the same wall clock in the new zone and re-stamped (the #28934 intent, now triggered exactly). Zone identity does not change across DST, so DST no longer masquerades as a migration and no longer skips a pending occurrence.

3. hermes_time stops pinning the zone for the process lifetime. It re-resolves at most once a minute, so a config edit no longer needs a gateway restart to take effect and divergent processes converge instead of drifting apart.

Why not the alternatives

f1f36b3bae (#28934) already rejected normalize-to-UTC (#28951) and rebase-and-match (#28985), and shipped the offset-delta heuristic with an explicit trade-off comment: "this cannot distinguish a config/host TZ migration from a legitimate DST offset change". Both rejected approaches, and the heuristic that won, share one blind spot — none of them record the zone, so all three have to guess from an offset. This PR removes the guess instead of tuning it; the heuristic's four regression tests still pass unchanged because unstamped jobs still take it.

Backward compatibility

• schedule.tz is additive and optional; parse_schedule is the only place that builds a schedule dict, and nothing validates its keys strictly.
• Installs with no timezone: set store no tz and behave byte for byte as before.
• Legacy jobs adopt the configured zone the first time the scheduler sees them; the old heuristic still repairs a foreign offset on that same pass, so no job can slip through unrepaired.
• Interval and one-shot schedules are untouched — they are already absolute instants.
• An unknown/removed IANA name degrades to the previous behaviour with a warning instead of wedging the ticker.

Performance

Measurement	main	This PR
hermes_time.now()	0.238 us/call	0.357 us/call
now() forced to re-resolve every call (TTL = 0)	—	0.618 us/call
get_due_jobs(), 1000 stamped cron jobs	11.19 ms	10.27 ms

The configured zone is resolved once per due scan, not per job, so the ticker's per-job cost is a string comparison.

Test plan

• tests/cron/test_cron_schedule_timezone_88220.py — 48 new tests: zone stamping, cross-process determinism, the Cron jobs fire 8 hours early after gateway restart (next_run_at persisted with +08:00 label on UTC wall-clock) #88220 reproducer end to end, zone-change rebase + idempotence, DST tick simulations (Berlin / Auckland / Los Angeles, both directions), a 13-zone i18n matrix including +05:30, +05:45, +08:45, +14:00 and -11:00, and legacy-job adoption. 43 of 48 fail on main.
• tests/cron + tests/test_timezone.py: 790 passed, 34 skipped. The 7 failures are the pre-existing Windows-only POSIX-permission / tilde-expansion tests — identical on a clean checkout.
• tests/tools: 36 pre-existing Windows-only failures on both main and this branch (unchanged).
• ruff check clean on every changed file.

Infographic :