P1: Evaluate schedule cron in local timezone (config override)

Problem

Scheduled cron expressions are evaluated in UTC (Job::new_async → Utc). Users typing 0 9 * * * (or 5-field 0 9 * * *) mean 09:00 in their local time, not 09:00 UTC. For Hong Kong (UTC+8) that fires at 17:00 HKT — a product bug.

Decision (PO 2026-10-06)

P1, separate from Accept 5-field cron by padding seconds as 0 #155.
Default: system local timezone.
Config may override.
Accept 5-field cron by padding seconds as 0 #155 five-field seconds pad proceeds without waiting for this issue.

Scope (for upcoming ADR)

Document timezone source of truth (system default + config override).
Apply to portal tasks, schedule_task tool, and config crons.
Migration / display: API and portal should show which timezone the expression uses.
Tests: a 09:00 local expression fires at 09:00 local, not UTC.

Out of scope

Five-field → six-field pad (Accept 5-field cron by padding seconds as 0 #155 / ADR-0021).
Per-bot language / i18n.

Notion

P1 row: schedule uses local timezone (board).

Related: ADR-0021 on PR #165.

TL notes for the upcoming timezone ADR (research facts, 2026-10-06):

croner 4 already supports timezones: find_next_occurrence takes DateTime<Tz>. Prefer passing chrono Local or a chrono_tz::Tz rather than hand-rolling offsets. Config override should parse IANA names via chrono-tz (e.g. Asia/Hong_Kong).
"System local" is unreliable in Docker: containers without /etc/localtime (or TZ) often default to UTC and reproduce the 09:00→17:00 HKT bug. ADR should require boot log of the effective timezone, and document that Docker users must set config override and/or TZ.
DST: Hong Kong has no DST; other users do. Ambiguous/skipped local times need an explicit fire-once vs skip rule (PO lock when ADR is written).

Does not block #155 / ADR-0021.

PO locks for #166 (2026-10-06) — ready for ADR when scheduled:

DST

Skipped local time (e.g. 02:30 does not exist during spring forward): fire once immediately after the clock jump. Reminders must not disappear.
Ambiguous local time (falls back / occurs twice): fire once, using the first occurrence.

AC (UI)

Portal Tasks page must show the effective timezone currently in use. Boot log alone is not enough (non-technical users will not read logs).

Still does not block #155.

fix(portal): note that cron times are UTC until #166 (#155)

ADR-0022 (Accepted) is up for review in #168: #168

It records the PO locks from 2026-10-06: system local timezone by default, [general] timezone IANA override, a per-task timezone column with existing rows stamped UTC (option C), effective timezone shown in the boot log and on the portal Tasks page, and the DST fire-once rules. It also covers removing the temporary UTC hints in the portal and the schedule_task description. Docs only; implementation comes in a follow-up PR.

docs(adr): ADR-0022 PO Product GO condition on legacy one-shot migrat…

docs(adr): ADR-0022 legacy naive one-shots stamp system local, not UTC (

Merge pull request #168 from chinkan/docs/adr-schedule-timezone

Navigation Menu

Repository navigation

P1: Evaluate schedule cron in local timezone (config override) #166

Problem

Decision (PO 2026-10-06)

Scope (for upcoming ADR)

Out of scope

Notion

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

P1: Evaluate schedule cron in local timezone (config override) #166

Description

Problem

Decision (PO 2026-10-06)

Scope (for upcoming ADR)

Out of scope

Notion

Activity

chinkan commented on Oct 6, 2026

chinkan commented on Oct 6, 2026

chinkan commented on Oct 6, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions