Cron is a scheduled trigger. A cron job runs an agent session at a specified time — daily at 4 AM, weekly on Monday, every 15 minutes. The schedule is the trigger. The session is the work.

Heartbeat is a faster-cadence probe. A heartbeat runs an agent session every few minutes to inspect state, detect new work, and keep cached state fresh. The heartbeat itself does not do the work; it spawns sessions that do.

How they differ

| | Cron | Heartbeat | |---|---|---| | Cadence | Hours to days | Seconds to minutes | | Purpose | Do the work | Probe for new work | | Cost | Higher (full session) | Lower (cheap probe) | | Behavior on no-op | Skip or log | Log "still alive" | | When to use | Stable rhythm | Event-driven |

When to use which

Use cron when the work has a stable rhythm — daily check-ins, weekly reviews, monthly reconciliations. Use heartbeat when the work needs to react to events that arrive between slower runs. Use both when the work has a daily rhythm but also needs to react to events.

Failure modes

  • Silent cron. The cron has been failing for days and nobody noticed. The fix is a heartbeat or a status file.
  • Heartbeat that does work. The heartbeat has grown from a probe into a worker. The fix is to refactor: the heartbeat probes; a session works.

See also