<!-- source: https://deepwiki.com/qhkm/zeptoclaw/11.2-cronservice -->

# CronService

- src/channels/manager.rs
- src/channels/types.rs
- src/cli/gateway.rs
- src/cron/mod.rs
- src/heartbeat/mod.rs
- src/heartbeat/service.rs
- src/plugins/watcher.rs

**Purpose**: `CronService` provides persistent scheduling of background agent turns via the `MessageBus`. It supports one-time, interval, and cron expression schedules with error recovery, exponential backoff, and crash-safe deduplication. [src/cron/mod.rs1-5](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L1-L5)

**Scope**: This page covers the `CronService` implementation, its schedule types, job lifecycle, persistence model, and integration with the gateway. For `HeartbeatService` (periodic `HEARTBEAT.md` monitoring), see page 11.3. For the Routines engine (event/webhook-triggered automations), see page 11.6.

## Architecture Overview

`CronService` is a background scheduler that publishes `InboundMessage` events to the `MessageBus` when jobs are due. Jobs persist to disk as JSON and survive process restarts. [src/cron/mod.rs235-242](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L235-L242)

**CronService Architecture**

```

```

Sources: [src/cron/mod.rs14-72](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L14-L72) [src/cron/mod.rs235-242](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L235-L242)

## Core Data Structures

### CronService

The service manages a persistent job store and a background tick loop. [src/cron/mod.rs235-242](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L235-L242)

Sources: [src/cron/mod.rs235-242](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L235-L242)

### CronJob

Each job contains scheduling metadata and execution state. [src/cron/mod.rs44-57](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L44-L57)

Sources: [src/cron/mod.rs44-57](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L44-L57)

### CronSchedule

Defines the timing logic for the job. [src/cron/mod.rs17-23](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L17-L23)

**CronSchedule Mapping**

```

```

Sources: [src/cron/mod.rs19-23](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L19-L23)

## Schedule Evaluation

### Resolution Logic

The `next_run_at` function computes the next execution timestamp based on the `CronSchedule` variant. [src/cron/mod.rs190-208](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L190-L208)

**Next Run Calculation**

```

```

Sources: [src/cron/mod.rs120-183](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L120-L183) [src/cron/mod.rs190-208](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L190-L208)

### Cron Expression Parsing

Cron expressions use 5 fields: `minute hour dom month dow`. [src/cron/mod.rs148-157](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L148-L157)

- * : All values. src/cron/mod.rs 121-123
- */N : Step values (e.g., */15 for every 15 minutes). src/cron/mod.rs 124-130
- N,M : List of specific values. src/cron/mod.rs 133-139

## Job Lifecycle

**Cron Job State Transitions**

```

```

Sources: [src/cron/mod.rs463-578](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L463-L578)

### Dispatch Flow

The `tick` function runs every second and processes due jobs. [src/cron/mod.rs463-470](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L463-L470) It applies a `jitter_delay` to decorrelate execution times by using system clock nanoseconds as a seed. [src/cron/mod.rs212-221](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L212-L221)

**Dispatch Sequence**

```

```

Sources: [src/cron/mod.rs463-578](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L463-L578)

## Error Handling and Backoff

Failed dispatches trigger an exponential backoff to prevent thundering herds on failing agents. [src/cron/mod.rs112-118](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L112-L118)

Sources: [src/cron/mod.rs87-93](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L87-L93)

The backoff is calculated via `error_backoff_ms` and added to the job's next run time during the rescheduling phase. [src/cron/mod.rs112-118](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L112-L118) [src/cron/mod.rs548-552](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L548-L552)

## OnMiss Policy

The `OnMiss` policy controls how jobs that were supposed to run while the service was offline are handled at startup. [src/cron/mod.rs224-232](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L224-L232)

- Skip : Missed runs are ignored; the job is rescheduled for its next future occurrence. src/cron/mod.rs 229
- RunOnce : Executes exactly one missed run immediately upon startup, then reschedules. src/cron/mod.rs 231

### Deduplication Guard

To prevent double-dispatch after a crash, the `should_skip_missed_dispatch` function checks if a job was already dispatched within a `DEDUP_WINDOW_MS` (60 seconds). [src/cron/mod.rs85](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L85-L85) [src/cron/mod.rs101-110](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L101-L110)

## Persistence Model

Jobs are persisted to a JSON file defined by `store_path`. [src/cron/mod.rs236](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L236-L236)

### Storage Format

The `CronStore` structure contains a version and a list of jobs. [src/cron/mod.rs60-63](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L60-L63)

```

```

Sources: [src/cron/mod.rs44-57](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L44-L57) [src/cron/mod.rs60-63](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L60-L63)

## Service Lifecycle

### Starting the Service

The `start` method loads the store, applies the `OnMiss` policy, and spawns the background tick loop. [src/cron/mod.rs263-351](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L263-L351)

### Tick Loop

The loop uses `tokio::time::interval` with a 1-second period. [src/cron/mod.rs331-332](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L331-L332) It uses `MissedTickBehavior::Delay` to ensure ticks do not pile up if one tick takes longer than a second. [src/cron/mod.rs333](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L333-L333)

### Stopping the Service

The `stop` method sets the `running` flag to `false`, causing the background loop to exit on its next iteration. [src/cron/mod.rs354-360](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L354-L360)

## Tool Integration: CronTool

The `CronTool` provides an LLM-accessible interface to manage scheduled jobs via the `CronService`. [src/tools/cron.rs16-18](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/cron.rs#L16-L18)

Sources: [src/tools/cron.rs91-105](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/cron.rs#L91-L105)

## Comparison with HeartbeatService

Sources: [src/cron/mod.rs1-13](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L1-L13) [src/heartbeat/service.rs1-10](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L1-L10)
