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

# Scheduler v0

> One-shot, interval, cron scheduling semantics and misfire policy.

# Scheduler v0

## Scope

Defines v0 scheduling types, trigger behavior, misfire policy, and execution gating against lifecycle/lease constraints.

## Terminology

* **Schedule types**: `one-shot`, `interval`, `cron`.
* **Misfire**: missed schedule window.
* **Defer-once**: one-time delayed execution after a miss.

## Normative Spec

### Schedule Types

Scheduler v0 MUST support:

* `one-shot`
* `interval`
* `cron`

### Target Binding

Schedule target MUST bind stable identity:

* `workspace_id`
* `agent_id`

`session_id` MUST NOT be used as schedule identity.

### Misfire Policy

* Default misfire policy: `skip`.
* `defer_once` MAY be used only for `interval` and `cron`.
* `one-shot` uses `skip` only.

### Concurrency

Default `max_concurrent_runs` SHOULD be `1` for a single schedule.

### Trigger Gate

Scheduler triggers intent only; execution still requires Gateway command + valid lease.

Recommended allowed states for execution: `running`, `ready`.

### Event Requirements

Scheduler SHOULD emit:

* `SCHEDULE_CREATED`
* `SCHEDULE_UPDATED`
* `SCHEDULE_TRIGGERED`
* `MISFIRED_SKIPPED`
* `MISFIRED_DEFERRED`
* `SCHEDULE_PAUSED`
* `SCHEDULE_RESUMED`
* `SCHEDULE_DISABLED`

## Examples

```json theme={null}
{
  "type": "one-shot",
  "spec": {"run_at": "2026-03-25T09:00:00Z"},
  "target": {"workspace_id": "ws-001", "agent_id": "codex"},
  "policy": {"misfire": "skip", "max_concurrent_runs": 1}
}
```

```json theme={null}
{
  "type": "cron",
  "spec": {"expr": "*/15 * * * *"},
  "target": {"workspace_id": "ws-001", "agent_id": "opencode"},
  "policy": {"misfire": "defer_once", "max_concurrent_runs": 1}
}
```

## Error & Recovery

* Invalid type/spec mismatch: reject schedule.
* Invalid misfire policy for `one-shot`: reject.
* Missing target identity (`workspace_id + agent_id`): reject.

Recovery of failed task execution is handled by self-heal/task policy, not by scheduler replay loops.

## Security & Audit

* Schedule updates and triggers MUST be auditable via metadata events.
* Production actions remain subject to platform approval policies.

## Status

Current status: `draft`

Source discussions:

* `docs/maintainers/conversation-records/agent-platform/2026-03-24-scheduler-v0-draft.md`
* `docs/maintainers/conversation-records/agent-platform/2026-03-24-p0-freeze-result-accepted.md`

## Changelog

* 2026-03-24: Initial skeleton created.
* 2026-03-24: Added schedule types, misfire rules, and target-binding constraints.

## Related Pages

* [DevBox Lifecycle v0](/en/agent-platform/architecture/devbox-lifecycle/index)
* [Gateway to Probe Command Contract v0](/en/agent-platform/contracts/gateway-to-probe-command-v0/index)
* [Self-heal Policy v0](/en/agent-platform/operations/self-heal-v0/index)