Skip to content

The run record

Every action on a run is an event: a start, a claim, a heartbeat, a report, a decision, a signal, a take-over, a timer firing. Events are appended, never edited, and each records who caused it: a person, an agent (with its sponsor, token or run, session and model), a service token, a schedule (schedule:<id>), a webhook trigger (webhook:<id>), or the engine. The run’s state is computed from its events, so the record and the run can’t disagree.

  1. EventsAppend-only, with who and when
  2. Run pageReads like a document
  3. ReportsMarkdown, JSON, JUnit, PDF
  4. ArchivesOne file per runbook per day

The web app shows a run as a document: the runbook’s steps in order, each with who did it, when, its status and verdict, its outputs, summary, logs, evidence and checklist, and every approval with who decided what and why. Runs that end have their spec.report summary at the top.

Terminal window
runbook run report "$EXE" --format md > run.md

For tickets, postmortems and chat.

Terminal window
runbook run watch "$EXE" # events as they happen
runbook run get "$EXE" --wait # block until the run ends; exit 3 if it failed

The web app’s run page updates live the same way, over a server-sent event stream.

The record is never rewritten, but it can be amended:

  • a person with executions:admin can override a step’s result, which is recorded as its own event next to the original;
  • a step whose result was changed afterwards is marked amended, and steps that had read its old outputs are marked stale, so nobody trusts a value that changed;
  • runbook run rerun starts a fresh run with the same inputs.

See Redaction and the audit trail for what’s redacted and where else actions are recorded.