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.
- EventsAppend-only, with who and when
- Run pageReads like a document
- ReportsMarkdown, JSON, JUnit, PDF
- ArchivesOne file per runbook per day
The run page
Section titled “The run page”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.
Reports
Section titled “Reports”runbook run report "$EXE" --format md > run.mdFor tickets, postmortems and chat.
runbook run report "$EXE" --format pdf --out run.pdfFor audits and sign-off records.
runbook run report "$EXE" --format junit > run.xmlChecks become test cases, so CI systems show a run’s verdicts like a test suite.
runbook run report "$EXE" --format jsonEvery section with its step run IDs, for your own tools.
Watching live
Section titled “Watching live”runbook run watch "$EXE" # events as they happenrunbook run get "$EXE" --wait # block until the run ends; exit 3 if it failedThe web app’s run page updates live the same way, over a server-sent event stream.
Correcting the record
Section titled “Correcting the record”The record is never rewritten, but it can be amended:
- a person with
executions:admincan 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 rerunstarts a fresh run with the same inputs.
See Redaction and the audit trail for what’s redacted and where else actions are recorded.