The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
fix(cron): per-job timezone drives schedule compute and due-scan
yliu325bfa67878cd22
diff --git a/cron/AGENTS.md b/cron/AGENTS.mdindex fa7009421bf..64a74966994 100644--- a/cron/AGENTS.md+++ b/cron/AGENTS.md@@ -13,7 +13,8 @@ schedule via the `cronjob` tool; users via `hermes cron list|add|edit|pause|resuinjected into the prompt; `no_agent=True` makes the script the whole job; always a FILE under`HERMES_HOME/scripts/`, never a command line — `script='echo hi'` is refused at creation), `context_from` (chain jobA's last output into job B's prompt), `workdir` (run with that directory's `AGENTS.md`/`CLAUDE.md`-loaded), multi-platform delivery.+loaded), `timezone` (pin the cron expression's wall clock to an IANA zone; absent = the+profile's zone), multi-platform delivery.Hardening invariants — each guards a real failure; don't weaken without answering for it:- **Inactivity watchdog** on cron agent sessions (`_cron_inactivity_seconds()`): default 600s idle,@@ -22,6 +23,15 @@ Hardening invariants — each guards a real failure; don't weaken without answeris never cut off. Attached scripts (pre-run or `no_agent`) are bounded separately by the scripttimeout (`_DEFAULT_SCRIPT_TIMEOUT`, 3600s).- Catch-up window = half the period, clamped to 120s–2h; 120s grace for missed one-shots.+- **A pinned `timezone` owns the whole path, not just the compute.** `compute_next_run` resolves+ *job pin → profile zone*, and every `next_run_at` write site must pass the pin (`cron/jobs.py`+ call sites, `quota_hold.plan_hold`, `unreachable_retry.will_retry`); one missed site is a burst+ re-run or a skipped slot. `_evaluate_due_job` normalizes the stored instant into the JOB's zone+ and **skips `_repair_timezone_shifted_cron`** for pinned jobs — that repair is for jobs that+ follow the profile zone, and on a pinned job its wall-clock predicate reads a due occurrence as+ future and re-anchors past it (job silently never fires). The knob lives in+ `cron/jobs_time.py`; `timezone` must stay in `job_definition.JOB_DEFINITION_FIELDS` or a+ profile distribution strips it.- Every recurring occurrence is accounted for: `tick()` advances `next_run_at` BEFORE dispatch(at-most-once across a mid-run crash) and stamps `pending_slot` in the same save; a scan thatfinds the stamp with a dead owner restores the instant ONCE (`cron/occurrences.py`), thediff --git a/cron/job_definition.py b/cron/job_definition.pyindex ce05ccb5acc..6e1f89c7576 100644--- a/cron/job_definition.py+++ b/cron/job_definition.py@@ -15,6 +15,7 @@ JOB_DEFINITION_FIELDS = frozenset({"script", "no_agent", "monitor_script", "monitor_url", "context_from","schedule", "schedule_display", "deliver", "origin", "enabled_toolsets","workdir", "attach_to_session", "reasoning_effort", "failure_deliver",+ "timezone", "grace_minutes",})diff --git a/cron/jobs.py b/cron/jobs.pyindex d650cee1a98..7379b764b69 100644--- a/cron/jobs.py+++ b/cron/jobs.py@@ -26,14 +26,17 @@ try:import msvcrtexcept ImportError: # pragma: no cover - non-Windowsmsvcrt = None-from datetime import datetime, timedelta, timezone, UTC+# ``datetime.timezone`` is deliberately NOT imported: the per-job ``timezone`` parameter+# (compute_next_run/create_job) would shadow it, and everything here uses ``UTC`` instead.+from datetime import datetime, timedelta, UTCfrom pathlib import Pathfrom agent.deadline import poll_untilfrom hermes_constants import get_hermes_homefrom cron.constants import CLAIM_TTL_INACTIVITY_HEADROOM, FIRE_CLAIM_SKEW_SECONDS, FIRE_CLAIM_TTL_SECONDSfrom cron.env_settings import cron_env_setting-from cron.jobs_invariants import _validate_job_mode_invariants+from cron.jobs_invariants import _validate_job_mode_invariants, validate_schedule_knobsfrom cron.jobs_model_pin import _main_model_pin+from cron import jobs_timefrom cron.scheduler_ownership import _claim_owner_is_deadfrom cron import extra_fire, store_healthfrom typing import Optional, Dict, List, Any, Callable, Set, Tuple, Union, Collection@@ -857,11 +860,15 @@ def parse_schedule(schedule: str) -> dict[str, Any]:)-def _ensure_aware(dt: datetime) -> datetime:- """Aware datetime in the configured Hermes timezone. Legacy naive values are read as- *system-local* wall time (what created them) then converted, preserving ordering across- timezone changes and avoiding false not-due results."""- target_tz = _hermes_now().tzinfo+def _ensure_aware(dt: datetime, target_tz: Optional[Any] = None) -> datetime:+ """Aware datetime in *target_tz*, defaulting to the configured Hermes timezone. Legacy naive+ values are read as *system-local* wall time (what created them) then converted, preserving+ ordering across timezone changes and avoiding false not-due results.++ The due scan passes the JOB's pinned zone here: every downstream cron predicate compares wall+ clocks, so normalizing a pinned job's instant into the profile zone makes a due occurrence+ look still-in-the-future and the repair path re-anchors past it (job lost, never fired)."""+ target_tz = target_tz or _hermes_now().tzinfoif dt.tzinfo is None:return dt.replace(tzinfo=datetime.now().astimezone().tzinfo).astimezone(target_tz)return dt.astimezone(target_tz)@@ -893,11 +900,11 @@ def _seconds_after(dt: datetime, seconds: float) -> datetime:return (dt.astimezone(UTC) + timedelta(seconds=seconds)).astimezone(dt.tzinfo)-def _parse_aware(value: Any) -> Optional[datetime]:- """``_ensure_aware(datetime.fromisoformat(value))``, or None when *value* is not a parseable ISO- string."""+def _parse_aware(value: Any, zone: Optional[Any] = None) -> Optional[datetime]:+ """``_ensure_aware(datetime.fromisoformat(value), zone)``, or None when *value* is not a+ parseable ISO string."""try:- return _ensure_aware(datetime.fromisoformat(value))+ return _ensure_aware(datetime.fromisoformat(value), zone)except Exception:return None@@ -919,13 +926,15 @@ def _stored_wall_clock_is_future(stored: datetime, current: datetime) -> bool:def _recoverable_oneshot_run_at(schedule: dict[str, Any], now: datetime, *, last_run_at: Optional[str] = None,+ zone: Optional[Any] = None,) -> Optional[str]:"""One-shot run time if still eligible: a small grace window covers jobs created just after- their minute; once run, a one-shot is never eligible again."""+ their minute; once run, a one-shot is never eligible again. *zone* is the job's pinned zone+ (an offset-less ``run_at`` is that zone's wall clock)."""if not isinstance(schedule, dict) or schedule.get("kind") != "once" or last_run_at:return Nonerun_at = schedule.get("run_at")- run_at_dt = _parse_aware(run_at) if run_at else None+ run_at_dt = jobs_time.oneshot_instant(run_at, zone) if run_at else Noneif run_at_dt is not None and _elapsed_seconds(now, run_at_dt) <= ONESHOT_GRACE_SECONDS:return run_atreturn None@@ -1172,14 +1181,22 @@ def get_timezone_migration_catchup_stats() -> dict[str, Any]:}-def compute_next_run(schedule: dict[str, Any], last_run_at: Optional[str] = None) -> Optional[str]:- """Compute the next run time for a schedule as an ISO string, or None if no more runs."""+def compute_next_run(+ schedule: dict[str, Any], last_run_at: Optional[str] = None, *, timezone: Any = None,+) -> Optional[str]:+ """Compute the next run time for a schedule as an ISO string, or None if no more runs.++ *timezone* is the job's pinned IANA zone (a job record or a bare zone name); None inherits+ the profile's configured zone. Every caller that advances a job's ``next_run_at`` must pass+ it, or a pinned job is computed in the wrong zone and jumps a slot."""now = _hermes_now()if not isinstance(schedule, dict):return Nonekind = schedule.get("kind")+ job_zone = jobs_time.zone_for_job(timezone)if kind == "once":- return _recoverable_oneshot_run_at(schedule, now, last_run_at=last_run_at)+ return _recoverable_oneshot_run_at(+ schedule, now, last_run_at=last_run_at, zone=job_zone)# Recurring kinds anchor on last_run_at so a restart doesn't re-anchor the schedule.base_time = (_parse_aware(last_run_at) if last_run_at else None) or nowif kind == "interval":@@ -1212,7 +1229,7 @@ def compute_next_run(schedule: dict[str, Any], last_run_at: Optional[str] = None# the wall-clock hour stays correct every calendar day, including DST# boundaries (morning-routine 09:00 America/Toronto).# Fall back to the base's own zone only when nothing is configured.- zone = get_timezone() or base_time.tzinfo+ zone = job_zone or get_timezone() or base_time.tzinfobase_wall = base_time.astimezone(zone).replace(tzinfo=None)it = croniter(expr, base_wall)# Strictly-after guard for the DST fall-back hour (qwen-code#11723 class):@@ -1733,6 +1750,7 @@ _CREATE_FIELD_NORMALIZERS: dict[str, Callable[[Any], Any]] = {"context_from": _normalize_context_from,"failure_deliver": _normalize_failure_deliver,"interpreter": _normalize_job_optional_text,+ "timezone": jobs_time.normalize_timezone,}_UPDATE_FIELD_NORMALIZERS: dict[str, Callable[[Any], Any]] = {# [] is an explicit zero-tool allowlist and must survive the update path as [] too (#82010).@@ -1742,6 +1760,7 @@ _UPDATE_FIELD_NORMALIZERS: dict[str, Callable[[Any], Any]] = {"monitor_url": _normalize_job_optional_text,"interpreter": _normalize_job_optional_text,"reasoning_effort": _normalize_reasoning_effort,+ "timezone": jobs_time.normalize_timezone,}@@ -1753,10 +1772,11 @@ def _oneshot_past_grace_error(run_at: Any) -> ValueError:def _next_run_or_reject_past_oneshot(parsed_schedule: dict[str, Any], label: str, fallback_run_at: Any, what: str,+ timezone: Any = None,) -> Optional[str]:"""``compute_next_run`` that raises (after a warning log) for a one-shot outside the gracewindow, so a ghost job with ``next_run_at=None`` can never be stored."""- next_run_at = compute_next_run(parsed_schedule)+ next_run_at = compute_next_run(parsed_schedule, timezone=timezone)if parsed_schedule.get("kind") == "once" and next_run_at is None:run_at = parsed_schedule.get("run_at") or fallback_run_atlogger.warning(@@ -1792,6 +1812,7 @@ def create_job(paused_reason: Optional[str] = None,pinned: bool = False,interpreter: Optional[str] = None,+ timezone: Optional[str] = None,) -> dict[str, Any]:"""Create a new cron job and return the stored record.@@ -1802,7 +1823,8 @@ def create_job(source run FIRST each tick; unchanged output suppresses the agent run (mutually exclusive,incompatible with ``no_agent``). reasoning_effort: per-job pin; capability NOT validated.interpreter: absolute/``~`` Python for ``.py`` script/monitor_script, validated at run time- (a venv can be rebuilt or moved after creation)."""+ (a venv can be rebuilt or moved after creation). timezone: IANA key pinning the schedule's+ wall clock (None/'' = inherit the profile zone)."""if not isinstance(paused, bool):raise ValueError("paused must be a boolean.")if paused_reason is not None and not isinstance(paused_reason, str):@@ -1828,6 +1850,7 @@ def create_job(normalized_reasoning_effort = _normalize_reasoning_effort(reasoning_effort)_validate_job_mode_invariants(f["monitor_script"], f["monitor_url"], f["no_agent"], f["script"])+ validate_schedule_knobs(parsed_schedule, f["timezone"])prompt_text = _coerce_job_text(prompt).strip()if not prompt_text and not f["script"] and not normalized_skills:raise ValueError(EMPTY_PAYLOAD_ERROR)@@ -1844,7 +1867,8 @@ def create_job(name = name or label_source[:50].strip()if pinned and not f["model"]:f["provider"], f["model"] = _main_model_pin()- next_run_at = _next_run_or_reject_past_oneshot(parsed_schedule, name, schedule, "")+ next_run_at = _next_run_or_reject_past_oneshot(+ parsed_schedule, name, schedule, "", f["timezone"])job = {"id": job_id,@@ -1890,6 +1914,7 @@ def create_job(for key, value in (("attach_to_session", normalized_attach), ("reasoning_effort", normalized_reasoning_effort),("failure_deliver", f["failure_deliver"]), ("interpreter", f["interpreter"]),+ ("timezone", f["timezone"]),):if value is not None:job[key] = value@@ -2043,7 +2068,8 @@ def _apply_schedule_update(updated: dict[str, Any], updates: dict[str, Any], job"schedule_display", updated_schedule.get("display", updated.get("schedule_display")))if updated.get("state") != "paused":updated["next_run_at"] = _next_run_or_reject_past_oneshot(- updated_schedule, updated.get("name", job_id), updated_schedule, "update ")+ updated_schedule, updated.get("name", job_id), updated_schedule, "update ",+ updated.get("timezone"))def _fill_missing_next_run(updated: dict[str, Any]) -> None:@@ -2055,7 +2081,7 @@ def _fill_missing_next_run(updated: dict[str, Any]) -> None:or updated.get("next_run_at")):return- next_run = compute_next_run(updated["schedule"])+ next_run = compute_next_run(updated["schedule"], timezone=updated.get("timezone"))if next_run is None and updated["schedule"].get("kind") == "once":run_at = updated["schedule"].get("run_at", "unknown")raise ValueError(@@ -2086,6 +2112,9 @@ def update_job(job_id: str, updates: dict[str, Any]) -> Optional[dict[str, Any]]_normalize_job_optional_text(updated.get("script")))if any(k in updates for k in _PAYLOAD_FIELDS) and job_payload_is_empty(updated):raise ValueError(EMPTY_PAYLOAD_ERROR)+ if "timezone" in updates:+ validate_schedule_knobs(updated.get("schedule") or {}, updated.get("timezone"))+ jobs_time.prune_inherited_timezone(updated)if "schedule" in updates:_apply_schedule_update(updated, updates, job_id)# next_run_at now follows the new schedule; a stale quota_hold_until would only shield@@ -2093,7 +2122,15 @@ def update_job(job_id: str, updates: dict[str, Any]) -> Optional[dict[str, Any]]# parked. The next fire re-parks (with a fresh notice) if the window is still closed.from cron.quota_hold import clear_state as _clear_quota_hold_clear_quota_hold(updated)- if {"schedule", "next_run_at", "enabled", "state"}.intersection(updates):+ elif "timezone" in updates and updated.get("state") != "paused":+ # The instant on file was computed in the OLD zone; leaving it would make the new+ # zone fire it at the wrong wall clock (or skip it). Only overwrite when the new+ # zone can compute one (a past one-shot keeps its recorded instant).+ recomputed = compute_next_run(+ updated["schedule"], timezone=updated.get("timezone"))+ if recomputed is not None:+ updated["next_run_at"] = recomputed+ if {"schedule", "next_run_at", "enabled", "state", "timezone"}.intersection(updates):# An explicit schedule/lifecycle rewrite supersedes any occurrence the dispatcher# left unclaimed — pause/resume/edit must not resurrect a slot from before the edit.updated.pop("pending_slot", None)@@ -2144,7 +2181,7 @@ def resume_job(job_id: str) -> Optional[dict[str, Any]]:"tick fires it (late/catch-up) or logs the skip.",job.get("name", job["id"]), stored_next)else:- next_run_at = compute_next_run(job["schedule"])+ next_run_at = compute_next_run(job["schedule"], timezone=job.get("timezone"))if next_run_at is None and job["schedule"].get("kind") == "once":run_at = job["schedule"].get("run_at", "unknown")raise ValueError(@@ -2214,7 +2251,7 @@ def rearm_oneshot(job_id: str, run_at: Any) -> Optional[dict[str, Any]]:parsed_schedule = parse_schedule(str(run_at))if parsed_schedule.get("kind") != "once":raise ValueError(_REARM_RECURRING_ERROR)- next_run_at = compute_next_run(parsed_schedule)+ next_run_at = compute_next_run(parsed_schedule, timezone=job_ref.get("timezone"))if next_run_at is None:raise _oneshot_past_grace_error(parsed_schedule.get("run_at") or run_at)@@ -2385,7 +2422,8 @@ def _advance_after_run(job: dict[str, Any], now: str, *, ladder_rung: bool = Fal_complete_job_record(job)return- job["next_run_at"] = compute_next_run(job["schedule"], now)+ job["next_run_at"] = compute_next_run(+ job["schedule"], now, timezone=job.get("timezone"))if job["next_run_at"] is not None:if job.get("state") != "paused":job["state"] = "scheduled"@@ -2612,7 +2650,8 @@ def advance_next_runs(job_ids) -> int:or extra_fire.queued(job) # the claim restores its slot; advancing erases the intent):continue- new_next = compute_next_run(job["schedule"], now)+ new_next = compute_next_run(+ job["schedule"], now, timezone=job.get("timezone"))if new_next and new_next != job.get("next_run_at"):job["next_run_at"] = new_nextadvanced += 1@@ -2690,7 +2729,8 @@ def claim_job_for_fire(instant = Noneif instant and completed_occurrence(job, instant):if job.get("schedule", {}).get("kind") in {"cron", "interval"}:- nxt = compute_next_run(job["schedule"], now.isoformat())+ nxt = compute_next_run(+ job["schedule"], now.isoformat(), timezone=job.get("timezone"))if nxt:job["next_run_at"] = nxtsave_jobs(jobs)@@ -2705,7 +2745,8 @@ def claim_job_for_fire(if slot := extra_fire.pending_slot(job, now, manual_fire):extra_fire.stamp_claim(job, slot) # off-schedule: the pending occurrence stayselif job.get("schedule", {}).get("kind") in {"cron", "interval"}:- nxt = compute_next_run(job["schedule"], now.isoformat())+ nxt = compute_next_run(+ job["schedule"], now.isoformat(), timezone=job.get("timezone"))if nxt:job["next_run_at"] = nxtsave_jobs(jobs)@@ -2877,11 +2918,13 @@ def _recover_missing_next_run(job: dict[str, Any], scan: _DueScan) -> Optional[sto 'scheduled', otherwise they would be silently skipped forever."""schedule = job.get("schedule", {})kind = schedule.get("kind")+ zone = jobs_time.zone_for_job(job)recovered_next = _recoverable_oneshot_run_at(- schedule, scan.now, last_run_at=job.get("last_run_at"))+ schedule, scan.now, last_run_at=job.get("last_run_at"), zone=zone)recovery_kind = "one-shot" if recovered_next else Noneif not recovered_next and kind in {"cron", "interval"}:- recovered_next = compute_next_run(schedule, scan.now.isoformat())+ recovered_next = compute_next_run(+ schedule, scan.now.isoformat(), timezone=job.get("timezone"))if recovered_next:recovery_kind = kindif not recovered_next:@@ -2906,7 +2949,7 @@ class _DueJob:scan: _DueScannext_run: str # stored ISO string, compared string-exact against manual_run_atraw_next_run_dt: datetime # as stored (may carry a pre-migration offset)- next_run_dt: datetime # normalized to the configured tz+ next_run_dt: datetime # normalized to the job's pinned tz, else the configured one@propertydef schedule(self) -> dict[str, Any]:@@ -2921,7 +2964,8 @@ class _DueJob:return self.job.get("name", self.job.get("id", "?"))def recompute_next(self) -> Optional[str]:- return compute_next_run(self.schedule, self.scan.now.isoformat())+ return compute_next_run(+ self.schedule, self.scan.now.isoformat(), timezone=self.job.get("timezone"))def _repair_timezone_shifted_cron(d: _DueJob) -> bool:@@ -3165,8 +3209,12 @@ def _evaluate_due_job(job: dict[str, Any], scan: _DueScan, run_claim_ttl: float)next_run = _restore_unclaimed_slot(job, scan) or job.get("next_run_at") or _recover_missing_next_run(job, scan)if not next_run:return False+ # A pinned job's stored instant must be normalized into ITS zone: the cron repair and+ # stale-lattice predicates below compare wall clocks, so the profile zone would make a due+ # occurrence look future-dated and re-anchor past it (the job then never fires).+ zone = jobs_time.zone_for_job(job)raw_next_run_dt = datetime.fromisoformat(next_run)- d = _DueJob(job, scan, next_run, raw_next_run_dt, _ensure_aware(raw_next_run_dt))+ d = _DueJob(job, scan, next_run, raw_next_run_dt, _ensure_aware(raw_next_run_dt, zone))kind = d.kindrecurring = kind in {"cron", "interval"}# Intentionally string-exact on raw stored values: trigger_job stamps the SAME isoformat string@@ -3180,7 +3228,10 @@ def _evaluate_due_job(job: dict[str, Any], scan: _DueScan, run_claim_ttl: float)if new_next:scan.persist(job["id"], next_run_at=new_next)return False- if kind == "cron" and not manual_run and _repair_timezone_shifted_cron(d):+ # The offset-repair path exists to rescue jobs that FOLLOW the profile zone across a zone+ # change. A pinned job's instant legitimately carries its own offset, so repair can only+ # misfire on it — skip it entirely.+ if kind == "cron" and not manual_run and zone is None and _repair_timezone_shifted_cron(d):return Falsed.next_run_dt = _rearm_stale_error_recurring(d)if _instant_after(d.next_run_dt, now):diff --git a/cron/jobs_invariants.py b/cron/jobs_invariants.pyindex 2936408d5be..7b822664250 100644--- a/cron/jobs_invariants.py+++ b/cron/jobs_invariants.py@@ -42,6 +42,17 @@ def _validate_job_mode_invariants(scripts_dir=display_hermes_home() + "/scripts/", script=script))+def validate_schedule_knobs(schedule: dict, timezone: Optional[str]) -> None:+ """Per-job schedule knobs are validated at BOTH doors — ``create_job`` and ``update_job`` — so+ an update cannot store a value a create would reject.++ Raises ValueError for an unknown IANA zone.+ """+ from cron.jobs_time import normalize_timezone++ normalize_timezone(timezone)++def _script_is_command_line(script: str) -> bool:"""A ``script`` with whitespace that resolves to no file is a command line (``echo hi``),not a path; run every tick it would deliver "Script not found" as the payload. A plaindiff --git a/cron/jobs_time.py b/cron/jobs_time.pynew file mode 100644index 00000000000..18293384f57--- /dev/null+++ b/cron/jobs_time.py@@ -0,0 +1,116 @@+"""Per-job ``timezone`` knob (sibling of ``cron/jobs.py``).++A job may pin its own IANA ``timezone``: its cron expression is then that zone's WALL CLOCK,+independent of the profile's configured zone. Absent/None means "inherit the profile", so a+store written before this field existed keeps byte-identical behaviour.++Behaviour lives here, not in the facade: ``cron/jobs.py`` is already past the file-lines+ratchet. The facade keeps the call sites (``compute_next_run``, the due scan, and every write+site that advances ``next_run_at``), which read the pins through this module.++Why the due scan needs the pin too: ``_ensure_aware`` normalizes a stored instant into a zone,+and the cron repair predicates then compare WALL CLOCKS. Normalizing a New-York job's instant+into a Los-Angeles profile zone makes the wall clock look like it is still in the future, so+``_repair_timezone_shifted_cron`` re-anchors to the NEXT occurrence and the due one is lost —+the "job timezone east of the profile timezone silently never fires" failure. See+``cron.jobs._evaluate_due_job``.+"""++from __future__ import annotations++import logging+from datetime import datetime+from typing import Any, Optional+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError++logger = logging.getLogger(__name__)++TIMEZONE_KEY = "timezone"++# A corrupt persisted value would otherwise log on every 60s scan. Warn once per distinct value.+_warned: set[str] = set()+++def reset_warning_state() -> None:+ """Forget which corrupt values were already warned about (tests, config reloads)."""+ _warned.clear()+++def _warn_once(kind: str, value: Any, detail: str) -> None:+ key = f"{kind}:{value!r}"+ if key in _warned:+ return+ _warned.add(key)+ logger.warning(+ "Job %s %r is invalid (%s); falling back to the profile setting. Fix or clear it with "+ "`hermes cron edit`.", kind, value, detail)+++def normalize_timezone(value: Any) -> Optional[str]:+ """Validate a job's ``timezone`` and return the canonical IANA key.++ ``None``/``""`` mean "inherit the profile timezone", stored as an ABSENT key. Anything that+ is not a resolvable IANA zone raises ValueError BEFORE the record is written, so a typo can+ never reach the tick loop.+ """+ if value is None:+ return None+ if not isinstance(value, str):+ raise ValueError(+ "timezone must be an IANA name such as 'Asia/Hong_Kong', "+ f"not {type(value).__name__}.")+ name = value.strip()+ if not name:+ return None+ try:+ return ZoneInfo(name).key+ except (ZoneInfoNotFoundError, ValueError) as exc:+ raise ValueError(+ f"Unknown timezone {name!r}. Use an IANA key from "+ f"`zoneinfo.available_timezones()`, e.g. 'Asia/Hong_Kong'.") from exc+++def zone_for_job(job_or_timezone: Any) -> Optional[ZoneInfo]:+ """The zone a job's schedule is expressed in, or None to inherit the profile's.++ Accepts a job record or a bare ``timezone`` value. Never raises: a corrupt stored value+ degrades to the profile zone (warned once per value) instead of breaking the tick it is+ read in — the 60s scan must not die on one bad record.+ """+ if isinstance(job_or_timezone, dict):+ value = job_or_timezone.get(TIMEZONE_KEY)+ else:+ value = job_or_timezone+ if not isinstance(value, str) or not value.strip():+ return None+ try:+ return ZoneInfo(value.strip())+ except (ZoneInfoNotFoundError, ValueError) as exc:+ _warn_once(TIMEZONE_KEY, value, str(exc))+ return None+++def prune_inherited_timezone(record: dict[str, Any]) -> None:+ """``timezone: ''`` / null means "inherit the profile", so the key is DROPPED, not stored as+ null — an absent optional key is this repo's spelling for "unset" (see ``cron/jobs.py``'s+ optional-field write loop) and a stored null would render as a pinned-but-blank zone."""+ if TIMEZONE_KEY in record and not record.get(TIMEZONE_KEY):+ record.pop(TIMEZONE_KEY, None)+++def oneshot_instant(value: Any, zone: Optional[ZoneInfo] = None) -> Optional[datetime]:+ """Parse a one-shot ``run_at`` into an aware instant, or None when unparseable.++ An offset-bearing value is already an instant. An offset-LESS value is the job's own wall+ clock, so a pinned zone interprets it in that zone (``2026-06-01T09:00:00`` means 09:00+ for THIS job) instead of in the host's local time.+ """+ from cron.jobs import _ensure_aware # late import: the facade owns naive normalization++ try:+ dt = datetime.fromisoformat(str(value))+ except (TypeError, ValueError):+ return None+ if dt.tzinfo is None and zone is not None:+ return dt.replace(tzinfo=zone)+ return _ensure_aware(dt, zone)diff --git a/cron/quota_hold.py b/cron/quota_hold.pyindex 4b1ddaaa472..bbd0ef04332 100644--- a/cron/quota_hold.py+++ b/cron/quota_hold.py@@ -135,7 +135,9 @@ def plan_hold(if kind == "cron" and blocked and not extra_fire.queued(job):# Coalesce cron occurrences inside the closed window to the first legal instant after it.# A queued run-now is not an occurrence: it waits for the boundary, not the next slot.- parked = compute_next_run(schedule, window_end.isoformat()) or window_end.isoformat()+ parked = compute_next_run(+ schedule, window_end.isoformat(), timezone=job.get("timezone")+ ) or window_end.isoformat()else:parked = window_end.isoformat()if recover:diff --git a/cron/unreachable_retry.py b/cron/unreachable_retry.pyindex a576ba5fe7f..92994cfc584 100644--- a/cron/unreachable_retry.py+++ b/cron/unreachable_retry.py@@ -99,7 +99,8 @@ def will_retry(job: dict[str, Any]) -> bool:from cron.jobs import _parse_aware, compute_next_runnow = _hermes_now()- natural_next = _parse_aware(compute_next_run(job.get("schedule") or {}, now.isoformat()))+ natural_next = _parse_aware(compute_next_run(+ job.get("schedule") or {}, now.isoformat(), timezone=job.get("timezone")))if natural_next is None:# The natural occurrence is uncomputable (e.g. croniter missing): _advance_after_run# leaves the record state=error — terminal — so plan_retry never runs either.diff --git a/hermes_cli/cron.py b/hermes_cli/cron.pyindex fcb794c9257..ff2365b8f7e 100644--- a/hermes_cli/cron.py+++ b/hermes_cli/cron.py@@ -246,6 +246,7 @@ def _job_rows(job: dict[str, Any]) -> list[tuple[str, str]]:("Changed", mon_state.get("last_changed_at") if monitor_source else ""),("Mode", color("no-agent", Colors.DIM) + " (script stdout delivered directly)"if job.get("no_agent") else ""),+ ("Timezone", job.get("timezone")),("Workdir", job.get("workdir")),("Python", job.get("interpreter")),("Last run", f"{job.get('last_run_at', '?')} {_last_run_display(job)}"@@ -732,6 +733,11 @@ def _cron_doctor_issues_for_job(job: dict[str, Any]) -> list[str]:workdir = str(job.get("workdir") or "").strip()if workdir and not Path(workdir).expanduser().exists():issues.append(f"workdir not found: {workdir}")+ if job.get("timezone"):+ from cron.jobs_time import zone_for_job+ if zone_for_job(job) is None:+ issues.append(f"timezone {job['timezone']!r} is not a valid IANA zone; "+ "the job falls back to the profile timezone")return issues@@ -762,7 +768,7 @@ _JOB_ARG_FIELDS = (("name", "name"), ("deliver", "deliver"), ("failure_deliver",("model", "model"), ("provider", "model_provider"), ("pinned", "pinned"),("monitor_script", "monitor_script"), ("monitor_url", "monitor_url"),("continuity", "continuity"), ("reasoning_effort", "reasoning_effort"),- ("interpreter", "interpreter"))+ ("interpreter", "interpreter"), ("timezone", "timezone"))def _job_api_kwargs(args) -> dict[str, Any]:@@ -776,6 +782,7 @@ _JOB_DETAIL_LINES = (("monitor_url", " Monitor: {} (agent runs only on output change)"),("no_agent", " Mode: no-agent (script stdout delivered directly)"),("continuity", " Continuity: on (each run sees the previous run's output)"),+ ("timezone", " Timezone: {} (schedule runs on this zone's wall clock)"),("workdir", " Workdir: {}"),("interpreter", " Python: {}"))diff --git a/hermes_cli/subcommands/cron.py b/hermes_cli/subcommands/cron.pyindex ae6115293a0..c585f5c36b3 100644--- a/hermes_cli/subcommands/cron.py+++ b/hermes_cli/subcommands/cron.py@@ -81,6 +81,10 @@ def build_cron_parser(subparsers, *, cmd_cron: Callable) -> None:help="Absolute or ~ path to a Python in your own venv (e.g. ~/venvs/report/bin/python) ""for a .py --script / --monitor-script, so it can import packages Hermes does not ""ship. .sh/.bash still run under bash. Omit to use Hermes' Python.")+ cron_create.add_argument("--timezone",+ help="IANA zone for this job's schedule (e.g. Asia/Hong_Kong), so the cron "+ "expression is read as THAT zone's wall clock whatever the profile's timezone "+ "is. Omit to inherit the profile timezone.")cron_create.add_argument("--continuity", dest="continuity", action="store_const", const=True, default=None,help="Each run wakes up with the job's own previous output injected "@@ -151,6 +155,9 @@ def build_cron_parser(subparsers, *, cmd_cron: Callable) -> None:cron_edit.add_argument("--interpreter",help="Absolute or ~ path to a Python for a .py script / monitor script. ""Pass empty string to clear (back to Hermes' Python).")+ cron_edit.add_argument("--timezone",+ help="IANA zone for this job's schedule. Pass empty string to clear the pin "+ "(back to the profile timezone); next_run_at is recomputed in the new zone.")# lifecycle actionscron_pause = cron_subparsers.add_parser("pause", help="Pause a scheduled job")diff --git a/tests/cron/test_catchup_policy.py b/tests/cron/test_catchup_policy.pyindex 7f78e1186d6..07b2a7907c1 100644--- a/tests/cron/test_catchup_policy.py+++ b/tests/cron/test_catchup_policy.py@@ -37,5 +37,5 @@ def test_default_and_uncomputable_still_catch_up(tmp_path, monkeypatch, uncomputstored[0]["next_run_at"] = (jobs._hermes_now() - timedelta(hours=4)).isoformat()jobs.save_jobs(stored)if uncomputable:- monkeypatch.setattr(jobs, "compute_next_run", lambda *args: None)+ monkeypatch.setattr(jobs, "compute_next_run", lambda *args, **kwargs: None)assert [row["id"] for row in jobs.get_due_jobs()] == [job["id"]]diff --git a/tests/cron/test_jobs.py b/tests/cron/test_jobs.pyindex ef553cb336a..7b71e942ef2 100644--- a/tests/cron/test_jobs.py+++ b/tests/cron/test_jobs.py@@ -1375,7 +1375,7 @@ class TestPerJobScanContainment:import cron.jobs as jobs_modreal_grace = jobs_mod._compute_grace_seconds- def selective_grace(schedule):+ def selective_grace(schedule, grace_minutes=None):if schedule.get("minutes") == 7:raise RuntimeError("simulated unforeseen malformed field")return real_grace(schedule)diff --git a/tests/cron/test_jobs_time.py b/tests/cron/test_jobs_time.pynew file mode 100644index 00000000000..150cef97d7b--- /dev/null+++ b/tests/cron/test_jobs_time.py@@ -0,0 +1,90 @@+"""Unit contract for the per-job ``timezone`` knob: ``cron/jobs_time.py``.++An IANA ``timezone`` pins a job's cron wall clock. The load-bearing case is the tolerant read: a+corrupt persisted zone must degrade to the profile zone, warned ONCE, never break the 60s tick.+"""++from datetime import datetime+from zoneinfo import ZoneInfo++import pytest++from cron import jobs_time++NY = ZoneInfo("America/New_York")+++class TestNormalizeTimezone:+ def test_iana_key_is_stored_canonical(self):+ assert jobs_time.normalize_timezone("America/New_York") == "America/New_York"++ def test_surrounding_whitespace_is_trimmed(self):+ assert jobs_time.normalize_timezone(" Asia/Hong_Kong ") == "Asia/Hong_Kong"++ @pytest.mark.parametrize("value", [None, "", " "])+ def test_empty_means_inherit_the_profile(self, value):+ assert jobs_time.normalize_timezone(value) is None++ @pytest.mark.parametrize("value", ["Mars/Olympus_Mons", "not a zone", "/etc/passwd"])+ def test_unknown_zone_is_rejected_before_storage(self, value):+ with pytest.raises(ValueError, match="timezone"):+ jobs_time.normalize_timezone(value)++ def test_non_string_is_rejected(self):+ with pytest.raises(ValueError, match="IANA name"):+ jobs_time.normalize_timezone(9)+++class TestZoneForJob:+ def test_absent_or_null_inherits_the_profile(self):+ assert jobs_time.zone_for_job({}) is None+ assert jobs_time.zone_for_job({"timezone": None}) is None+ assert jobs_time.zone_for_job({"timezone": ""}) is None++ def test_pinned_zone_is_returned(self):+ assert jobs_time.zone_for_job({"timezone": "America/New_York"}) == NY++ def test_accepts_a_bare_zone_name(self):+ assert jobs_time.zone_for_job("America/New_York") == NY++ def test_corrupt_value_degrades_instead_of_raising(self, monkeypatch):+ """One bad record must never abort the tick it is scanned in."""+ jobs_time.reset_warning_state()+ warnings: list[str] = []+ monkeypatch.setattr(+ jobs_time.logger, "warning",+ lambda msg, *a, **kw: warnings.append(msg % a if a else msg))+ job = {"timezone": "Mars/Olympus_Mons"}++ assert jobs_time.zone_for_job(job) is None+ assert jobs_time.zone_for_job(job) is None # scanned again a minute later+ assert jobs_time.zone_for_job({"timezone": "Mars/Olympus_Mons"}) is None++ assert len(warnings) == 1, f"a bad zone must warn ONCE, got {warnings}"+ assert "Mars/Olympus_Mons" in warnings[0]+++class TestPruneInheritedTimezone:+ def test_cleared_zone_drops_the_key(self):+ record = {"id": "a", "timezone": ""}+ jobs_time.prune_inherited_timezone(record)+ assert "timezone" not in record++ def test_pinned_zone_is_kept(self):+ record = {"timezone": "Asia/Hong_Kong"}+ jobs_time.prune_inherited_timezone(record)+ assert record["timezone"] == "Asia/Hong_Kong"+++class TestOneshotInstant:+ def test_offsetless_run_at_is_the_jobs_wall_clock(self):+ """``09:00`` for a New-York job is 09:00 in New York, not on the host."""+ instant = jobs_time.oneshot_instant("2026-06-01T09:00:00", NY)+ assert instant == datetime(2026, 6, 1, 9, 0, tzinfo=NY)++ def test_offset_bearing_run_at_is_already_an_instant(self):+ instant = jobs_time.oneshot_instant("2026-06-01T09:00:00+00:00", NY)+ assert instant.astimezone(NY) == datetime(2026, 6, 1, 5, 0, tzinfo=NY)++ def test_garbage_is_none(self):+ assert jobs_time.oneshot_instant("not-a-time", NY) is Nonediff --git a/tests/cron/test_per_job_timezone.py b/tests/cron/test_per_job_timezone.pynew file mode 100644index 00000000000..a7d878c5c8a--- /dev/null+++ b/tests/cron/test_per_job_timezone.py@@ -0,0 +1,202 @@+"""Per-job ``timezone``: one store, several zones, each job on its own wall clock.++The failing shape this pins (the reason a compute-only fix is not enough — upstream PR #137231+fixed ``compute_next_run`` but not the dispatch path): with the profile pinned to+``America/Los_Angeles`` and a job pinned to ``America/New_York`` running ``0 9 * * 1-5``, the+due scan normalized the stored New-York instant into the profile zone, so the repair predicate+``_stored_wall_clock_is_future`` compared wall clocks across zones, decided the run was still+in the future and re-anchored to the NEXT day. The due occurrence was silently dropped — the+symptom is "no error, no fire, the next_run_at just moved".++Everything here goes through the public store API (``create_job`` / ``get_due_jobs``), never by+calling the internal predicates, so the tests fail on the real symptom rather than on a+hand-built intermediate value.+"""++import logging+from datetime import datetime+from zoneinfo import ZoneInfo++import pytest++pytest.importorskip("croniter")++import hermes_time+from cron import jobs++LA = ZoneInfo("America/Los_Angeles")+NY = ZoneInfo("America/New_York")+HK = ZoneInfo("Asia/Hong_Kong")++WEEKDAY_9AM = "0 9 * * 1-5"+DAILY_9AM = "0 9 * * *"+++def la_profile(monkeypatch):+ """Configure the profile zone the way production does: ``HERMES_TIMEZONE`` + cache reset."""+ monkeypatch.setenv("HERMES_TIMEZONE", "America/Los_Angeles")+ hermes_time.reset_cache()+ yield LA+ hermes_time.reset_cache()+++def cron_store(tmp_path, monkeypatch):+ """Isolated store + a frozen clock the test moves explicitly."""+ monkeypatch.setenv("HERMES_HOME", str(tmp_path))++ class Clock:+ instant = datetime(2026, 10, 22, 12, 0, tzinfo=NY)++ def set(self, value):+ self.instant = value++ def now(self):+ # Production shape: _hermes_now() is aware in the PROFILE zone.+ return self.instant.astimezone(hermes_time.get_timezone() or LA)++ clock = Clock()+ monkeypatch.setattr(jobs, "_hermes_now", clock.now)+ with jobs.use_cron_store(tmp_path / "cron"):+ yield clock+++def _add_job(schedule, *, timezone=None, next_run_at):+ """Create a real job through the public door, then park its instant where the test needs it."""+ job = jobs.create_job(+ prompt="probe", schedule=schedule, model="fixture", deliver="local",+ timezone=timezone)+ stored = jobs.load_jobs()+ row = next(r for r in stored if r["id"] == job["id"])+ row["next_run_at"] = next_run_at.isoformat()+ jobs.save_jobs(stored)+ return job["id"]+++class TestPinnedTimezoneIsDue:+ """§0 of the design: the pinned job must be DUE, and the repair path must not touch it."""++ @pytest.mark.parametrize("job_zone", ["America/New_York", "Asia/Hong_Kong"])+ def test_job_east_of_the_profile_zone_fires_on_time(+ self, la_profile, cron_store, job_zone, caplog,+ ):+ """East of the profile zone is the direction that used to be dropped every time."""+ nine_am = datetime(2026, 10, 22, 9, 0, tzinfo=ZoneInfo(job_zone))+ cron_store.set(nine_am)+ job_id = _add_job(WEEKDAY_9AM, timezone=job_zone, next_run_at=nine_am)+ caplog.set_level(logging.INFO, logger="cron.scheduler")++ due = [j["id"] for j in jobs.get_due_jobs()]++ assert due == [job_id], "the pinned occurrence is due and must be returned"+ stored = next(r for r in jobs.load_jobs() if r["id"] == job_id)+ assert stored["next_run_at"] == nine_am.isoformat(), (+ "a pinned job's instant must never be rewritten into the profile zone")+ assert "Recomputing cron run" not in caplog.text, (+ "the offset repair only exists for jobs that FOLLOW the profile zone")++ def test_two_pinned_jobs_keep_their_own_nine_am(self, la_profile, cron_store):+ """One store, one profile zone, two jobs: each fires at ITS 09:00, not the other's."""+ ny_job = _add_job(+ WEEKDAY_9AM, timezone="America/New_York",+ next_run_at=datetime(2026, 10, 22, 9, 0, tzinfo=NY))+ hk_job = _add_job(+ WEEKDAY_9AM, timezone="Asia/Hong_Kong",+ next_run_at=datetime(2026, 10, 23, 9, 0, tzinfo=HK))++ # 09:00 New York == 21:00 Hong Kong == 06:00 Los Angeles: only the NY job is due.+ cron_store.set(datetime(2026, 10, 22, 9, 0, tzinfo=NY))+ assert [j["id"] for j in jobs.get_due_jobs()] == [ny_job]+ # The tick claims the fired job and advances it in ITS zone — the write site that would+ # otherwise jump a slot (and the claim is what retires the pending_slot stamp).+ assert jobs.claim_job_for_fire(ny_job) is True++ # A day later, 09:00 Hong Kong (== 18:00 the previous day in LA) is the HK job's turn.+ cron_store.set(datetime(2026, 10, 23, 9, 0, tzinfo=HK))+ assert [j["id"] for j in jobs.get_due_jobs()] == [hk_job]+ advanced = next(r for r in jobs.load_jobs() if r["id"] == ny_job)+ assert datetime.fromisoformat(advanced["next_run_at"]).astimezone(NY).hour == 9++ def test_unpinned_job_still_follows_the_profile_zone(self, la_profile, cron_store):+ """The default is unchanged: absent pin == profile wall clock (no migration needed)."""+ nine_la = datetime(2026, 10, 22, 9, 0, tzinfo=LA)+ cron_store.set(nine_la)+ job_id = _add_job(WEEKDAY_9AM, next_run_at=nine_la)++ assert [j["id"] for j in jobs.get_due_jobs()] == [job_id]+++class TestComputeNextRunUsesTheJobZone:+ def test_next_run_lands_on_the_job_wall_clock(self, la_profile):+ schedule = jobs.parse_schedule(WEEKDAY_9AM)+ base = datetime(2026, 10, 22, 10, 0, tzinfo=NY).isoformat()++ pinned = datetime.fromisoformat(+ jobs.compute_next_run(schedule, base, timezone="America/New_York"))+ inherited = datetime.fromisoformat(jobs.compute_next_run(schedule, base))++ assert (pinned.hour, pinned.minute) == (9, 0)+ assert pinned.astimezone(NY).date() == datetime(2026, 10, 23).date()+ # Same instant computed in the profile zone would land at 09:00 LOS ANGELES.+ assert inherited.astimezone(LA).hour == 9+ assert pinned != inherited++ def test_dst_transitions_hold_the_job_wall_clock(self, la_profile):+ """Spring-forward (Mar 8 2026) and fall-back (Nov 1 2026) days stay at 09:00 job time."""+ schedule = jobs.parse_schedule(DAILY_9AM)+ for base in ("2026-03-07T09:00:00-05:00", "2026-10-31T09:00:00-04:00"):+ nxt = datetime.fromisoformat(+ jobs.compute_next_run(schedule, base, timezone="America/New_York"))+ assert (nxt.astimezone(NY).hour, nxt.astimezone(NY).minute) == (9, 0), base++ def test_fall_back_second_occurrence_is_strictly_later(self, la_profile):+ """qwen-code#11723 class: no immediate re-fire inside the repeated autumn hour."""+ base = datetime(2026, 11, 1, 1, 15, tzinfo=NY, fold=1) # 01:15 EST (second 01:15)+ nxt = datetime.fromisoformat(+ jobs.compute_next_run({"kind": "cron", "expr": "30 1 * * *"},+ base.isoformat(), timezone="America/New_York"))+ assert nxt.timestamp() > base.timestamp()+++class TestInheritanceAndDegradation:+ def test_null_and_absent_are_the_same_job(self, la_profile, cron_store):+ explicit = jobs.create_job(+ prompt="null", schedule=WEEKDAY_9AM, model="fixture", deliver="local",+ timezone=None)+ absent = jobs.create_job(+ prompt="absent", schedule=WEEKDAY_9AM, model="fixture", deliver="local")+ rows = {r["prompt"]: r for r in jobs.load_jobs()}+ assert "timezone" not in rows["null"] and "timezone" not in rows["absent"]+ assert explicit["next_run_at"] == absent["next_run_at"]++ def test_clearing_the_pin_through_update_drops_the_key(self, la_profile, cron_store):+ job = jobs.create_job(+ prompt="p", schedule=WEEKDAY_9AM, model="fixture", deliver="local",+ timezone="Asia/Hong_Kong")+ jobs.update_job(job["id"], {"timezone": ""})+ assert "timezone" not in jobs.load_jobs()[0]++ def test_changing_the_pin_recomputes_the_stored_instant(self, la_profile, cron_store):+ job = jobs.create_job(+ prompt="p", schedule=WEEKDAY_9AM, model="fixture", deliver="local",+ timezone="America/New_York")+ before = jobs.load_jobs()[0]["next_run_at"]++ jobs.update_job(job["id"], {"timezone": "Asia/Hong_Kong"})+ after = jobs.load_jobs()[0]["next_run_at"]++ assert after != before, "the instant belongs to the old zone; it must move"+ assert datetime.fromisoformat(after).astimezone(HK).hour == 9++ def test_a_corrupt_stored_zone_does_not_break_the_scan(self, la_profile, cron_store):+ nine_la = datetime(2026, 10, 22, 9, 0, tzinfo=LA)+ cron_store.set(nine_la)+ job_id = _add_job(WEEKDAY_9AM, next_run_at=nine_la)+ stored = jobs.load_jobs()+ stored[0]["timezone"] = "Mars/Olympus_Mons" # hand-edited store+ jobs.save_jobs(stored)++ due = [j["id"] for j in jobs.get_due_jobs()]++ assert due == [job_id], "a bad zone degrades to the profile zone, it does not hide the job"diff --git a/tests/hermes_cli/test_cron_parser_builder.py b/tests/hermes_cli/test_cron_parser_builder.pyindex f78844c86e4..bb91888c9c1 100644--- a/tests/hermes_cli/test_cron_parser_builder.py+++ b/tests/hermes_cli/test_cron_parser_builder.py@@ -40,3 +40,15 @@ def test_cron_accept_hooks_flag_on_run_and_tick():assert ns.accept_hooks is Truens2 = parser.parse_args(["cron", "tick", "--accept-hooks"])assert ns2.accept_hooks is True+++def test_cron_timezone_flags():+ parser = _build()+ created = parser.parse_args(+ ["cron", "create", "0 9 * * *", "hi", "--timezone", "Asia/Hong_Kong"])+ assert created.timezone == "Asia/Hong_Kong"++ edited = parser.parse_args(["cron", "edit", "j", "--timezone", ""])+ assert edited.timezone == "", "an empty value is the documented clear"++ assert parser.parse_args(["cron", "edit", "j"]).timezone is Nonediff --git a/tests/hermes_cli/test_web_server_cron_profiles.py b/tests/hermes_cli/test_web_server_cron_profiles.pyindex 0755835f386..a972a330313 100644--- a/tests/hermes_cli/test_web_server_cron_profiles.py+++ b/tests/hermes_cli/test_web_server_cron_profiles.py@@ -367,7 +367,7 @@ def test_profile_call_cannot_retarget_ticker_store_mid_write(monkeypatch.setattr(cron_jobs,"compute_next_run",- lambda _schedule, _last_run_at=None: "2026-07-10T00:00:00+00:00",+ lambda _schedule, _last_run_at=None, **_kw: "2026-07-10T00:00:00+00:00",)ticker_loaded = threading.Event()diff --git a/tests/tools/test_cronjob_tools.py b/tests/tools/test_cronjob_tools.pyindex eefb67e804c..f06fb0f458d 100644--- a/tests/tools/test_cronjob_tools.py+++ b/tests/tools/test_cronjob_tools.py@@ -802,3 +802,43 @@ class TestGithubExemptionAbuse:assert _scan_cron_prompt("generate a keypair and explain id_rsa vs id_ed25519") == ""+++class TestScheduleKnobToolSurface:+ """The model-facing tool must expose the per-job timezone knob (§4)."""++ @pytest.fixture(autouse=True)+ def _setup_cron_dir(self, tmp_path, monkeypatch):+ monkeypatch.setattr("cron.jobs.CRON_DIR", tmp_path / "cron")+ monkeypatch.setattr("cron.jobs.JOBS_FILE", tmp_path / "cron" / "jobs.json")+ monkeypatch.setattr("cron.jobs.OUTPUT_DIR", tmp_path / "cron" / "output")++ def _stored(self):+ from cron.jobs import load_jobs+ return load_jobs()[0]++ def test_create_stores_timezone(self):+ created = json.loads(cronjob(+ action="create", prompt="HK open", schedule="0 9 * * 1-5",+ timezone="Asia/Hong_Kong"))+ assert created["success"] is True, created+ job = self._stored()+ assert job["timezone"] == "Asia/Hong_Kong"+ assert job["next_run_at"].endswith("+08:00") or job["next_run_at"].endswith("+09:00")++ def test_create_rejects_an_unknown_zone(self):+ created = json.loads(cronjob(+ action="create", prompt="x", schedule="0 9 * * *",+ timezone="Mars/Olympus_Mons"))+ assert created["success"] is False+ assert "timezone" in created["error"].lower()++ def test_update_clears_the_zone(self):+ created = json.loads(cronjob(+ action="create", prompt="x", schedule="0 9 * * *",+ timezone="Asia/Hong_Kong"))+ job_id = created["job_id"]++ updated = json.loads(cronjob(action="update", job_id=job_id, timezone=""))+ assert updated["success"] is True, updated+ assert "timezone" not in self._stored(), "'' clears the pin; the key is dropped"diff --git a/tools/cronjob_tools.py b/tools/cronjob_tools.pyindex 40bfa88e501..865ad5c5764 100644--- a/tools/cronjob_tools.py+++ b/tools/cronjob_tools.py@@ -730,6 +730,7 @@ def _action_create(a: dict[str, Any]) -> str:monitor_url=_normalize_optional_job_value(a["monitor_url"]),# CLI-only lane: absent from CRONJOB_SCHEMA and the model dispatch (models don't pick models).reasoning_effort=a["reasoning_effort"], interpreter=a["interpreter"],+ timezone=_normalize_optional_job_value(a["timezone"]),pinned=bool(a["pinned"]),failure_deliver=_resolve_cron_context_deliver(_normalize_deliver_param(a["failure_deliver"])),**({"paused": a["paused"], "paused_reason": a["paused_reason"]}@@ -959,6 +960,9 @@ def _update_run_fields(job: dict[str, Any], a: dict[str, Any], updates: dict[strrepeat_state = dict(job.get("repeat") or {})repeat_state["times"] = normalize_repeat_value(a["repeat"])updates["repeat"] = repeat_state+ if a["timezone"] is not None:+ # '' clears the pin (the job inherits the profile timezone); update_job validates the key.+ updates["timezone"] = _normalize_optional_job_value(a["timezone"]) or ""if a["schedule"] is not None:parsed_schedule = parse_schedule(a["schedule"])updates["schedule"] = parsed_schedule@@ -1048,7 +1052,8 @@ def cronjob(paused: bool = False,paused_reason: Optional[str] = None,pinned: Optional[bool] = None,- interpreter: Optional[str] = None) -> str:+ interpreter: Optional[str] = None,+ timezone: Optional[str] = None) -> str:"""Unified cron job management tool."""a = dict(locals())del a["task_id"] # unused but kept for handler signature compatibility@@ -1170,6 +1175,10 @@ Jobs run in a fresh session with no current-chat context, so prompts must be sel"type": "string","description": "Optional absolute existing path to run the job from: injects that directory's AGENTS.md/context files and anchors terminal/file tools there. On update, '' clears."},+ "timezone": {+ "type": "string",+ "description": "Optional IANA timezone for the job's schedule, e.g. 'Asia/Hong_Kong' or 'America/New_York': the cron expression is then read as THIS zone's wall clock, whatever the profile's own timezone is. Use it for a job that must fire at a fixed local time in another market. Omit to inherit the profile timezone. On update, '' clears the pin."+ },"attach_to_session": {"type": "boolean","description": "True = the job's delivery is CONTINUABLE — the user can reply and the agent has the brief in context (threads on thread-capable platforms, mirrored into the DM elsewhere). Use for conversational recurring jobs (briefings); leave unset for fire-and-forget alerts. Scope: the job's own conversation only — the origin chat, the home-channel fallback when deliver='origin' captured no origin (script-created jobs), a user-written bare platform target (deliver='slack' — that platform's home channel), or the job's single explicit platform:chat target (this flag is the only way to attach an explicit target). Broadcast targets are never attached; no effect when deliver='local'."@@ -1202,7 +1211,7 @@ def check_cronjob_requirements() -> bool:_HANDLER_FORWARDED_ARGS = ("job_id", "prompt", "schedule", "name", "repeat", "deliver", "failure_deliver", "skill", "skills", "reason","script", "context_from", "continuity", "enabled_toolsets", "workdir", "no_agent", "attach_to_session",- "paused_reason", "pinned")+ "paused_reason", "pinned", "timezone")def _cronjob_handler(args, **kw):diff --git a/website/docs/developer-guide/cron-internals.md b/website/docs/developer-guide/cron-internals.mdindex 70106b13f40..baa20bb3b9f 100644--- a/website/docs/developer-guide/cron-internals.md+++ b/website/docs/developer-guide/cron-internals.md@@ -13,6 +13,7 @@ The cron subsystem provides scheduled task execution — from simple one-shot de| File | Purpose ||------|---------|| `cron/jobs.py` | Job model, storage, atomic read/write to `jobs.json` |+| `cron/jobs_time.py` | Per-job `timezone` knob: validation, tolerant reads, due-scan zone || `cron/scheduler.py` | Scheduler loop — due-job detection, execution, repeat tracking || `tools/cronjob_tools.py` | Model-facing `cronjob_manage` tool registration and handler || `gateway/run.py` | Gateway integration — cron ticking in the long-running loop |@@ -31,6 +32,28 @@ Four schedule formats are supported:The model-facing surface is a single `cronjob_manage` tool with action-style operations: `create`, `list`, `update`, `pause`, `resume`, `run`, `remove`.+## Per-job timezone++`compute_next_run(schedule, last_run_at, *, timezone=...)` resolves the zone as *job pin → profile+`timezone` → base offset*, and **every** caller that advances `next_run_at` passes the job's pin+(the advance sites, the claim path, resume/re-arm, the recovery paths, and the quota/unreachable+planners). One missed site shows up as a burst re-run or a skipped slot, because the stored instant+and the expression would be interpreted in different zones.++The dispatch path needs the pin just as much as the compute does. `_evaluate_due_job` builds its+`_DueJob` with `_ensure_aware(raw, zone_for_job(job))`, which gives every downstream predicate the+job's clock; a job with a pinned zone **skips `_repair_timezone_shifted_cron` entirely**. That+repair exists for jobs that FOLLOW the profile zone across a zone change: for a pinned job its+stored offset legitimately differs from the profile's, and the repair's wall-clock comparison+(`_stored_wall_clock_is_future`) then reads a due occurrence as still-in-the-future and re-anchors+to the next one — the job silently never fires. This is why a fix to `compute_next_run` alone is+not enough.++`timezone` is a top-level record field (not inside `schedule`), validated by+`jobs_time.normalize_*` at both the create and update door. A corrupt persisted value degrades to+the profile zone with one warning per value — the 60s scan must not die on one bad record. No+migration is needed: the keys simply do not exist in older stores, and every reader uses `.get()`.+## Job StorageJobs are stored in `~/.hermes/cron/jobs.json` with atomic write semantics (write to temp file, then rename). Each job record contains:diff --git a/website/docs/user-guide/features/cron.md b/website/docs/user-guide/features/cron.mdindex d59dca2c3a7..de38b778a85 100644--- a/website/docs/user-guide/features/cron.md+++ b/website/docs/user-guide/features/cron.md@@ -210,6 +210,21 @@ When `workdir` is set:Each agent run binds its `workdir` to that run's unique task identity. Workdir jobs therefore use the normal parallel pool without mutating process-global terminal state or leaking paths between concurrent runs. Set `cron.max_parallel_jobs` if you want to limit total cron concurrency.:::+## Per-job timezone++By default a job's cron expression is read in your profile's timezone (`timezone:` in `config.yaml`). A job can pin its own zone instead, so one profile can serve several markets:++```bash+hermes cron create "0 9 * * 1-5" --timezone Asia/Hong_Kong "HK market open brief"+hermes cron create "0 9 * * 1-5" --timezone America/New_York "US market open brief"+```++- The expression is the pinned zone's **wall clock**: `0 9 * * *` fires at 09:00 in that zone, and stays at 09:00 across that zone's DST changes.+- Omit it (or pass `--timezone ""` on edit) to inherit the profile timezone. A job without the field behaves exactly as before.+- An offset-less one-shot timestamp (`2026-06-01T09:00:00`) is also read in the job's zone; a timestamp that carries its own offset is already an instant.+- Changing the zone recomputes `next_run_at` immediately, so the next fire happens at the new zone's wall clock.+- An `interval` job has a fixed duration and no wall clock, so a pin has no effect on it.+## Editing jobsYou do not need to delete and recreate jobs just to change them.