Runs

A run is one execution of a pinned crew-member version. The run dispatcher invokes the compiled program as the member's identity and records every step.

Lifecycle#

scdoc

1
2
3

queued → running → ┬→ succeeded
                   ├→ waiting_approval → (decision) → running → …
                   └→ failed

Invoke — the dispatcher runs the program, persisting the step timeline to run_events.
Checkpoint — when the program reaches an approval @checkpoint, the run moves to waiting_approval, a local approval mirror is created, and a HITL item is raised in ScaiQueue.
Resume — an approve/reject decision resumes the run from the checkpoint (or fails it).
Succeed — on success, any declared handoff conditions are evaluated and the first match fires as a child run.

Dry run#

A dry run executes the draft with external effects stubbed — a safe preview that produces a full step timeline without touching the outside world. Ideal for validating a member before publishing.

Audit & history#

run_events, trigger_invocations, and the audit_log are append-only and never soft-deleted. Each run pins the exact version it executed, so a run is always reproducible against its definition.

Deferred: run retry is not yet implemented (returns 501).