Skip to content

fix(cron): keep a job's next run at its wall time across a dst change - #32403

Merged
bolichen97 merged 1 commit into
mainfrom
fix/24853-cron-dst-next-run
Nov 7, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/24853-cron-dst-next-run

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A cron job's "Next run" and its timer wake name the wall time the job is configured for, also when the next run falls after a daylight-saving change.

A job 0 3 * * * in America/Los_Angeles, looked at on 2026-10-31, shows its next run as 2026-11-01 04:00 PST instead of 03:00, and is_due refuses that advertised instant. A 0 22 * * 1-5 job read on the Friday before the fall-back shows Monday 23:00 PST instead of 22:00; the day before the spring-forward a 0 22 * * * job shows 21:00 PDT.

Why it matters

Every user whose zone observes daylight saving sees a wrong "Next run" for every cron job whose next run lies past the change, twice a year, and the timer arms on that wrong instant. Runs still happen only because the timer also polls every 30 seconds.

Not a goal

  • Changing when a job is due: is_due, skip dates, backoff and the poll cap are untouched.
  • The repeated fall-back hour after its first pass: stepping the wall clock does not revisit it (01:50 PDT steps to 02:00 PST for */15), as before; the poll still runs those slots.
  • _cron_occurrence_ts (the occurrence a run belonged to, for the same-occurrence and zone-change checks): it spans a minute or one run, not a DST change.
  • Upgrading croniter or changing cron syntax.

What changed (motivation → approach → change)

A cron job's "Next run", and the instant its timer wakes on, now read the wall time the job is set for when that run falls after a daylight-saving change: 03:00 PST, not 04:00. When the job actually runs does not change.

The wrong time came from how the next run was asked for. compute_next_run_ts and the timer boundary _next_cron_boundary_ts handed croniter a start carrying the job's zone, and croniter 2 then moves any run past a DST change by the offset change a second time. The schedule label already avoided this by stepping the plain wall clock.

Both paths now go through one small helper, _next_wall_clock_ts: croniter steps the zone's wall clock with no zone attached, and the zone is attached to the wall time it names. When the fall-back repeats that wall time and its first instant is not after now, the second instant is taken, so the result is never in the past. A wall time the spring-forward skips resolves as before (02:30 runs at 03:30 PDT). The cron spec (learn-cron-dashboard.md, Per-Job Timezone) says this.

Builds on #24864 by @leonlaiyc.

Backwards compatibility

Compatible: no stored field, payload shape or due decision changes; only the next-run instant across a DST change moves to the configured wall time.

Removes nothing: the diff only changes how an existing next-run instant is computed.

Tests

test/test_cron_dst_next_run.py checks, for the day before the fall-back, a Friday before it, the day before the spring-forward, a spring-forward gap time and the second pass of the repeated hour, that compute_next_run_ts and _next_cron_boundary_ts both name the configured wall time and that is_due is true at it. All rows use fixed instants and an explicit zone.

The spring-forward gap row pins the existing resolution and passes on main too; the other four fail there.

Determinism: 20/20 runs at -n0, 10/10 at -n 4 --dist loadgroup --max-worker-restart=2 beside test_cron_dst_double_fire.py and test_cron_next_wake_boundary.py, and a shuffled order (seed 24853) of this file with test_cron_dst_double_fire.py, all green.

Proof: PROVEN test/test_cron_dst_next_run.py::test_the_next_run_is_the_configured_wall_time[0 3 * * *-now0-expected0], test/test_cron_dst_next_run.py::test_the_next_run_is_the_configured_wall_time[0 22 * * 1-5-now1-expected1], test/test_cron_dst_next_run.py::test_the_next_run_is_the_configured_wall_time[0 22 * * *-now2-expected2], test/test_cron_dst_next_run.py::test_the_next_run_is_the_configured_wall_time[30 1 * * *-now4-expected4] (head 55e3d3317d99)

Manual verification

N/A — unit coverage sufficient: the change is pure date arithmetic, pinned at fixed instants on both functions that read it.

Related Issues

Closes #24853

Sibling sweep

Swept: git grep -n "croniter(" -- src/
Sibling: src/kiro_crew/cron_service/schedule.py:946 -- not affected -- the other croniter calls in this file step UTC (117), a naive clock (146, and the schedule label at 179), or span one minute or one run with an aware start (_cron_occurrence_ts, 946), never a DST change

Pattern harvest

Rule candidate: review-prompt
Pattern: croniter iterated from an aware zoneinfo start shifts a run past a DST change twice; step the naive wall clock and attach the zone

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license.

A cron job's advertised next run and its timer boundary were computed
by handing croniter an aware start in the job's zone. croniter 2 then
shifts any run that lies past a DST change by the offset change a
second time: a 03:00 job read 04:00 PST the day before the fall-back,
a 22:00 job 21:00 PDT the day before the spring-forward, and is_due
refused the advertised instant.

Step the zone's naive wall clock instead and attach the zone to the
result, as the schedule label already does. A repeated wall time whose
first instant is not after now takes its second; a spring-forward gap
resolves as fold=0 does, as before.

Builds on #24864.

Closes #24853
@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 7, 2026 15:08
@bolichen97
bolichen97 enabled auto-merge (squash) November 7, 2026 15:14
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 7, 2026
@github-actions

github-actions Bot commented Nov 7, 2026

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 35ea1d5a9b5dce5b2ac424a638376f6e2915dcd8 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 7, 2026

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 35ea1d5a9b5dce5b2ac424a638376f6e2915dcd8 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

No design-level concerns. Both next-run callers now go through one helper that steps the zone's wall clock, the same way the schedule label already did. The due decision is unchanged, and nothing is taken away.

[DESIGN-REVIEWED] 35ea1d5

Description read

[DESCRIPTION-READ] 4e4cd6db3f643da93c0df21946f091222ba058caa7cac80886575f43d59fc380

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 7, 2026

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 35ea1d5a9b5dce5b2ac424a638376f6e2915dcd8 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks: this is a fix for linked issue #24853, and four of the new test rows fail on base. It works on the code that computes the next run, and both next-run paths now share one helper.

Notes

  • Item 2 — rides along, duplicate of src/kiro_crew/cron_service/schedule.py:178-179 (_humanize_cron still steps the naive wall clock and attaches the zone inline). That makes 1 of the 3 sites that follow this pattern sit outside the new _next_wall_clock_ts. I counted the sites by grepping croniter( under src/, which gave 7 calls. Subtraction: replace the inline pair at 178-179 with _next_wall_clock_ts, so the pattern is written once.

What this change ships

Inventory (4 items) — 3 justified

Intent: a DST-zone user sees, and the timer wakes on, the wall time their cron job is set for. This is a FIX.

  1. "Next run" shows the configured wall time after a DST change (03:00 PST, not 04:00) — justified
  2. New shared helper _next_wall_clock_ts; the schedule label keeps its own inline copy — rides along, duplicate of cron_service/schedule.py:178
  3. The timer arms on the corrected instant, and in the repeated fall-back hour it takes the second instant — justified
  4. Spec Per-Job Timezone paragraph describes the stepping — justified

[FIRST-PRINCIPLES-REVIEWED] 35ea1d5

Description read

[DESCRIPTION-READ] b86f70deb8b6d6ac80f75afb90e0b0e5aa6e5e4efa263f2ccab3e6936f4a2961

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 7, 2026

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 35ea1d5a9b5dce5b2ac424a638376f6e2915dcd8 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 35ea1d5

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 35ea1d5a9b5dce5b2ac424a638376f6e2915dcd8 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 7, 2026

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 35ea1d5a9b5dce5b2ac424a638376f6e2915dcd8 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 35ea1d5

Verdict parsed from the review's SHA-scoped output markers for commit 35ea1d5a9b5dce5b2ac424a638376f6e2915dcd8.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 35ea1d5a9b5dce5b2ac424a638376f6e2915dcd8 false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 7, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tier 1 auto-approve: fix (3 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, security checklist all-NO, no reviewer-lane findings, readiness signal fresh for this head SHA, declared category matches the diff. Category: bug fix: cron next-run is stepped on the zone wall clock before the zone is attached, so a DST change no longer shifts it twice; tests added. Spec files changed as a ride-along (a minority of the diff on both file count and changed lines), not reviewed as a design decision: docs/system-specs/modules/learn-cron-dashboard.md.

@bolichen97
bolichen97 merged commit 83ec532 into main Nov 7, 2026
98 of 106 checks passed
@bolichen97
bolichen97 deleted the fix/24853-cron-dst-next-run branch November 7, 2026 18:10
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 7, 2026
buluoray pushed a commit that referenced this pull request Nov 7, 2026
…#32403)

A cron job's advertised next run and its timer boundary were computed
by handing croniter an aware start in the job's zone. croniter 2 then
shifts any run that lies past a DST change by the offset change a
second time: a 03:00 job read 04:00 PST the day before the fall-back,
a 22:00 job 21:00 PDT the day before the spring-forward, and is_due
refused the advertised instant.

Step the zone's naive wall clock instead and attach the zone to the
result, as the schedule label already does. A repeated wall time whose
first instant is not after now takes its second; a spring-forward gap
resolves as fold=0 does, as before.

Builds on #24864.

Closes #24853

(cherry picked from commit 83ec532)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Cron next-run timestamps shift off the configured wall time across DST

2 participants