hermes - 💡(How to fix) Fix [Feature]: Allow interval-based cron jobs to specify a first-run anchor (decouple cadence from registration time) [1 participants]

Problem or Use Case

When creating a recurring every Nd / every Nh cron job, the first trigger is always now + interval. There is no way to tell the scheduler "I want this every 14 days, but the cadence should start from 2026-05-06 09:00 local, not from registration time."

Concrete example: Fab's "Limited-Time Free" assets drop every 14 days on Monday 21:59 Beijing time. I want a reminder every 14 days at 09:00 Tuesday (the morning after each drop). If I register every 14d today, the scheduler fires at registration + 14d, which lands at an arbitrary time of day and is off-cadence with the real event.

Workarounds that don't work cleanly:

• Standard cron expressions (supported via croniter) have no native "every 2 weeks" semantics — 0 9 */14 * * fires on the 1st / 15th / 29th of the month, which is not a true 14-day cycle.
• every 14d correctly preserves 14-day spacing once it starts, but offers no way to pick the starting point.

The only working workaround today is to create the job, then hand-edit ~/.hermes/cron/jobs.json to overwrite next_run_at. This works (scheduler honors the value on the next tick and subsequent +interval computations preserve the new cadence), but it's undocumented and requires reaching into internal storage.

For reference, OpenClaw — a sibling project with similar ergonomics — stored this as a first-class anchorMs field on every interval schedule, so the {interval, anchor} tuple fully pinned the cadence regardless of when the job was registered.

Proposed Solution

Extend the interval schedule with an optional anchor / first-run timestamp:

cronjob(
    action="create",
    schedule="every 14d",
    first_run="2026-05-06T09:00:00+08:00",   # NEW: ISO timestamp
    prompt="...",
    name="FAB reminder",
)

CLI parity:

hermes cron create "every 14d" --first-run 2026-05-06T09:00:00+08:00 ...

Semantics:

• If first_run is in the future, the job fires at that exact time, then every N thereafter.
• If first_run is in the past, compute the next occurrence as anchor + ceil((now - anchor) / interval) * interval (so you can pin a cadence that's been running since last year without needing to update the anchor).
• Store the anchor alongside minutes in the schedule dict — e.g. {"kind": "interval", "minutes": 20160, "anchor_at": "2026-05-06T09:00:00+08:00"}. mark_job_run() can keep doing next_run_at += interval as today; the anchor is only consulted on create and (optionally) when cron run reschedules.

Alternatives Considered

1. Keep using next_run_at hand-edits. Works, but invisible to users — the docs don't mention it, and it creates an ergonomics cliff between every and cron expressions.
2. Rely on cron expressions alone. Doesn't solve it — cron grammar has no 14-day-cycle primitive (the classic Unix cron limitation).
3. Encode the anchor into a cron expression with a # week-of-month modifier. Too fragile for arbitrary cadences like every 10 / 14 / 21 days, and croniter coverage varies.

The proposed first_run / anchor_at field is the smallest change that makes the common case ("biweekly reminder that aligns with an external event") possible without workarounds.

Feature Type

CLI improvement (also touches scheduler internals)

Scope

Small — likely touches:

• cron/jobs.py — parse_schedule accepting the second param; JobSpec / create schema.
• cron/scheduler.py — anchor-aware initial next_run_at computation on create.
• The cronjob tool schema (new optional first_run field).
• Tests: add coverage in tests/cron/test_jobs.py and tests/cron/test_scheduler.py.

Contribution

I'd be happy to submit a PR if the direction is accepted.