Monday morning, you open your laptop and realize last night’s scheduled job never ran — and it has been silently dead for three days. hermes cron list still shows the job, hermes cron status reports no error, but there is no output, no message, no log telling you what went wrong. This kind of quiet failure is worse than an error: the job “looks healthy” while actually being dead. The new command hermes cron doctor, merged on August 31, exists exactly for this scenario: one read-only command that checks your entire cron fleet end to end, tells you explicitly what is wrong, and uses its exit code so you can wire it into automated alerts.

Why “looks fine” while nothing runs

This command was born from a real production incident: on a fleet running 60 cron jobs, one job had been dead for 5 days (a content-filter failure) and two watchdog jobs were silently not firing — and no single existing surface (list, status, incidents) showed the problem at a glance. The jobs were still in the list, so everything “looked normal”; their next_run_at had expired long ago, but nobody was checking.

That is the classic cron disease: the scheduler does not complain unless you go look at “when was it supposed to run, and did it actually run?”

hermes cron doctor: one checkup, seven checks

hermes cron doctor is a new subcommand of the hermes cron family (hermes cron [list|create|edit|pause|resume|run|remove|status|runs|doctor|tick]). It is read-only — it never mutates job config, it simply walks every enabled job and reports findings. Against the source (_cron_doctor_issues_for_job in hermes_cli/cron.py), here is what it checks:

• Last run failed: when the job’s recorded last_status is not ok, it reports the concrete last_error;
• Last delivery failed: it reports last_delivery_error, e.g. a message that never reached your chat platform;
• Enabled job with no next_run_at: an active job that cannot schedule its next run is itself a symptom;
• next_run_at overdue: with a 15-minute ticker grace; an overdue timestamp prints “next_run_at is Xm/h overdue — job is not firing (is the scheduler running?)” — the signal for a silently non-firing job;
• No-agent job with no script: a script-only job (no_agent: true) that has no script configured;
• Script health issues: the script’s own health check (for example, the file not existing);
• Dead workdir: the job’s workdir no longer exists on disk.

Any job hitting any of these is listed — and these traces are exactly the only residue a “lying in the list but actually dead” job leaves behind.

What the output looks like

When everything is healthy, it is pleasantly terse:

✓ Cron doctor found no issues
  Checked 12 active job(s).

When problems exist, it lists every issue per job and exits with code 1:

Cron doctor found 3 issue(s) across 2 job(s):

  cron_daily_report
    - last run failed: content filter rejected output
    - next_run_at is 26.4h overdue — job is not firing (is the scheduler running?)
  nightly_backup
    - workdir not found: /data/backups

Next: fix the listed job config, then run `hermes cron doctor` again.

Using it: the exit code is the point

A health check only earns its keep when it feeds automation. The exit code is deliberately simple: 0 = all healthy, 1 = something needs action. So you can drop it straight into a monitoring script:

# One-line fleet checkup every morning; alert when something is wrong
if ! hermes cron doctor; then
  hermes send -t telegram "cron fleet has a job in trouble — go check!"
fi

Or just run hermes cron doctor manually whenever you want a quick audit. It is read-only, so it is always safe to run.

When you can use it

PR #99479 merged on August 31, 2026 and is on main only — v0.20.6 (released August 27) does not have this subcommand yet. Update to latest main to use it now, or wait for the next release. The official docs (cron feature guide and CLI reference) already document it.

Scheduled jobs earn their keep only when they run reliably with nobody watching, and reliability starts with knowing they actually run. hermes cron doctor turns that “knowing” into one command. For a fuller automation setup, see our complete cron automation guide and cron monitoring & preflight checks; if your jobs keep failing quietly at 3am, the gateway loop-watchdog tuning guide is worth a read too. Command reference: hermes cron.