# Schedule operations reference

> Outpost schedules are durable definitions that create independent agents. The same ScheduleDefinition is validated by the Kin tool, TUI editor, protocol leaf, store, and scheduler.

Outpost schedules are durable definitions that create independent agents. The
same `ScheduleDefinition` is validated by the Kin tool, TUI editor, protocol
leaf, store, and scheduler.

<!-- SOURCE: src/kin/outpost_protocol/types.py, src/kin/outpost_service/scheduler.py, src/kin/outpost_service/store.py, src/kin/harness/tools/schedule.py -->

## Definition and authority

A definition contains name, self-contained brief, canonical repository,
relative workdir, source ref, timing, enabled/archive state, revision, optional
model limits, frozen authority, and notification policy. Timing is exactly one
of five-field cron, bounded second interval, or one-shot timestamp, always with
an IANA timezone.

Create and every mutation require a composed human confirmation, idempotency
key, and expected revision. The confirmed definition authorizes later fires
only within those exact fields. A worker receives neither the `schedule` nor
`agent_dispatch` tool.

## Fire lifecycle

At fire time the daemon:

1. claims the occurrence transactionally;
2. resolves and records the source ref's exact commit;
3. creates a fresh `out_<ULID>` agent and unique result branch;
4. submits it through ordinary FIFO admission; and
5. records settlement and notification metadata.

A scheduled agent begins unowned. A matching Kin workspace explicitly adopts
it before conversation continuation.

## Coalescing and overlap

Missed occurrences coalesce into at most one catch-up. If the schedule already
has active work, the due occurrence is skipped rather than queued behind it.
Once worker execution begins, that occurrence is durable and is never replayed,
including after a daemon restart.

The next-fire calculation and fire claim live in WAL transactions so several
scheduler ticks cannot admit the same occurrence. Manual Fire uses the same
single-flight and overlap rules.

## Failure streak

Agent success resets the schedule's consecutive-failure count. Failure
increments it. At three consecutive failures the store disables the definition
and emits one durable `auto_pause` attention item. A human inspects the failed
agents and confirms Resume after correcting the definition or repository.

## Concurrency

Schedules share the appliance's top-level FIFO worker queue with one-shot
dispatches. The default is two running roots. Paused and Needs You agents
release their slots. The limit is operator deployment state, not a schedule
field or model-writable setting.

## Notification behavior

Default notification is attention-only. Report-only success without returned
changes is silent. Returned Git changes, failure, Needs You, and auto-pause
create global attention. No email, push, webhook, dashboard, recipe, or inbound
trigger path exists.

## Protocol operations

Reads:

```text
GET /v1/outpost/schedules
GET /v1/outpost/schedules/<id>
```

Confirmed mutations:

```text
POST  /v1/outpost/schedules
PATCH /v1/outpost/schedules/<id>
POST  /v1/outpost/schedules/<id>/control
```

Control accepts `enable`, `pause`, `resume`, `fire`, or `archive`. Mutations
require `Idempotency-Key` and `If-Match`; stale revisions fail rather than
silently overwriting another Kin's edit.

## Recovery checks

For a missing or surprising occurrence, inspect in order:

1. schedule revision, enabled/archive state, timing, timezone, and next fire;
2. active occurrence and overlap skip record;
3. exact resolved commit and created agent ID;
4. worker attempt boundary and event acknowledgement;
5. failure streak and auto-pause attention; and
6. client event cursor versus transactional snapshot.

Do not replay an occurrence to repair a missing notification. Repair the client
projection with a fresh snapshot, or surface an ambiguous attempt as failed.

See [Outpost operations](/docs/kin/internals/outpost-operations/) for appliance and cutover
procedure and the [protocol index](/docs/kin/protocol/) for the wire contract.

_Source authority: Kinra Site (src/content/docs/kin/internals/automation-operations.md)._