web: cron triggers match server-local time, not UTC; v0.9.51

[cymoo]

Bug

A schedule described as "每晚 22:00（北京时间）" showed 触发时间：每天 14:00 in the detail modal while actually firing at 22:00 Beijing time (下次运行 / run history both 22:00).

Root cause: _croniter_next passed a bare epoch float to croniter, which then matches cron fields against UTC wall time. Everything else promises server-local semantics — the UI's hand-rolled cron humanizer (每天 {t}), crontab convention, and the at trigger's documented "a bare time is read in the server's timezone". So the model had to write a UTC-compensated 0 14 * * * to hit 22:00 Beijing, and the modal then humanized that expression at face value: 14:00.

croniter('0 22 * * *', time.time()).get_next(float)   # → 06:00 +08:00  (UTC match)
croniter('0 22 * * *', datetime.now().astimezone())…  # → 22:00 +08:00  (local match)

Fix

• scheduler.py: _croniter_next converts the epoch to an aware local datetime before handing it to croniter — cron fields now mean the server's local wall clock.
• scheduling.py: schedule_run's trigger_expr description states cron is matched against the server's LOCAL wall clock and tells the model not to convert to UTC.
• Docs (en/zh): cron trigger row notes local-time matching.
• Regression test test_cron_fields_mean_local_wall_time — TZ-independent (asserts the fired slot's local hour/minute equals the cron fields); fails on the old code in any non-UTC timezone.
• v0.9.51 in pyproject / __init__ / uv.lock.

Behavior change

Existing cron schedules whose expressions were written to compensate for the UTC matching will shift by the server's UTC offset — e.g. the task above (0 14 * * *) would now fire at 14:00 local. Edit such expressions once to the intended local hour (0 22 * * *). No migration is attempted: intent isn't recoverable from the stored expression.

every/at triggers are unaffected (pure epoch math).

Verification

• Full suite: 2310 passed, 42 skipped; ruff, mypy, check_docs.py all clean.
• initial_next_fire('cron', '0 22 * * *', now=…) → 2026-08-12T22:00:00+08:00 ✓

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adjusts the web scheduler’s cron trigger semantics so cron fields are interpreted against the server’s local wall clock (crontab convention), aligning the scheduler’s behavior with the web UI’s cron humanization and the documented scheduling contract.

Changes:

• Fix _croniter_next to pass an aware local datetime into croniter, eliminating unintended UTC-based matching for cron fields.
• Clarify schedule_run’s trigger_expr guidance and update docs (EN/ZH) to state cron matching is based on server-local time.
• Add a regression test covering the local-wall-clock contract; bump version to v0.9.51.

Reviewed changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
lovia/web/scheduler.py	Passes a timezone-aware local datetime to croniter so cron fields match server-local wall time.
lovia/web/scheduling.py	Updates tool guidance to explicitly state cron is matched against server-local wall clock.
tests/web/test_scheduler.py	Adds a regression test asserting cron hour/minute fields match local time.
docs/en/web-server.md	Documents that cron expressions are matched against server local time.
docs/zh/web-server.md	Documents that cron expressions are matched against server local time (中文).
pyproject.toml	Bumps project version to 0.9.51.
lovia/__init__.py	Bumps __version__ to 0.9.51.
uv.lock	Updates locked package version to 0.9.51.

---

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

[cymoo]

Good catch — the test only guarded non-UTC environments, and CI is UTC. Fixed in 9412074: the test now pins TZ=Asia/Shanghai (no DST, deterministic) via tzset for its duration and restores the previous zone after. Verified it fails against the old bare-epoch implementation and passes against the fix. (Also skips on platforms without time.tzset.)