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.

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:

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

Confirmed mutations:

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 for appliance and cutover procedure and the protocol index for the wire contract.