> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strait.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Scheduling

> Managing when jobs and workflows execute.

Strait provides several mechanisms to control the timing of job and workflow executions, from recurring cron schedules to delayed one-off runs.

## Cron Scheduling

Jobs and workflows can be configured with a `cron` expression for automatic, recurring execution.

* **Syntax**: Standard 5-field cron syntax (e.g., `0 * * * *` for every hour).
* **Timezone Support**: Schedules can be pinned to a specific timezone (e.g., `America/Los_Angeles`) via the `timezone` (for jobs) or `cron_timezone` (for workflows) fields.
* **Implementation**: Handled by the `CronScheduler` using the `robfig/cron/v3` library.

<Note>
  If a job is disabled (`enabled: false`), its cron schedule is ignored by the scheduler.
</Note>

## Delayed Execution

Runs can be scheduled to execute at a specific point in the future.

* **Mechanism**: When a run is triggered with a `scheduled_at` timestamp in the future, it is created with a `delayed` status.
* **Delayed Poller**: A background component periodically checks for `delayed` runs whose `scheduled_at` time has passed and transitions them to `queued`.

## Stale Run Reaper

To ensure system reliability, the `Reaper` background component monitors for runs that have become "stale."

* **Heartbeat Monitoring**: Executing runs are expected to send periodic heartbeats. If a run's `heartbeat_at` timestamp exceeds a configurable threshold, the reaper identifies it as stale.
* **Stale Dequeued Runs**: Runs that were claimed (`dequeued`) but never transitioned to `executing` are also reaped.
* **Actions**: Stale runs may be transitioned to `crashed` or `system_failed`, allowing them to be retried if attempts remain.

## Retention Policies

The `RetentionWorker` manages the cleanup of old run data to prevent database bloat.

* **Short Retention (30 days)**: Applied to terminal runs in `completed`, `failed`, `canceled`, or `expired` states.
* **Long Retention (90 days)**: Applied to terminal runs in `timed_out`, `crashed`, or `system_failed` states, providing a longer window for debugging critical failures.

## Execution Windows

Jobs can define an `execution_window_cron`. This restricts the job from being dequeued unless the current time matches the provided cron-like expression.

<Example>
  `0 9-17 * * 1-5` restricts a job to only run during business hours (9 AM - 5 PM, Monday through Friday).
</Example>

## Cron Overlap Policies

### Jobs

Jobs support a `cron_overlap_policy` field that controls what happens when a cron tick fires while previous runs for the same job are still active.

| Policy            | Behavior                                                                                                                           |
| :---------------- | :--------------------------------------------------------------------------------------------------------------------------------- |
| `allow` (default) | Always create a new queued run, regardless of active runs.                                                                         |
| `skip`            | If any run is in an active state (queued, dequeued, executing, waiting, or delayed), skip the cron tick entirely.                  |
| `cancel_running`  | Cancel all active runs for the job, then create a new queued run. Managed containers are stopped and child runs are also canceled. |

<CodeGroup>
  ```json Skip overlapping runs theme={null}
  {
    "cron": "*/5 * * * *",
    "cron_overlap_policy": "skip"
  }
  ```

  ```json Cancel and replace theme={null}
  {
    "cron": "*/5 * * * *",
    "cron_overlap_policy": "cancel_running"
  }
  ```
</CodeGroup>

### Workflows

Workflows support a `skip_if_running` flag. If enabled, the scheduler will skip triggering a new run if an instance of that workflow is already in a `running` state. This is useful for preventing overlapping executions of long-running maintenance tasks.