Pipeline execution flow
A Loom workflow schedules eligible jobs inside a local run. Job results determine
whether dependent work can proceed. The run records lifecycle transitions in
state.jsonl and execution output and diagnostics in events.jsonl.
Execution sequence
A recorded run starts with a pending workflow state. Preparation or compilation failure records a failed workflow state and a diagnostic when recording is available. A workflow that proceeds to execution records running, then its final outcome. See Job execution flow for work inside a job.
What controls whether work can start
| Control | What to rely on |
|---|---|
| Stage barriers | Omitted needs waits for executable jobs in earlier declared stages. |
| Explicit dependencies | An explicit needs list replaces stage barriers; needs: [] adds no stage dependency. |
| Artifact inputs | Artifact producers remain prerequisites independently of needs. |
| Upstream result | A failed prerequisite blocks its dependents; independent ready jobs continue. |
When a job fails, finished jobs keep their results, its dependents become blocked, and independent ready jobs can continue. State records retain the job outcomes and the final workflow result. A workflow-rule denial records a skipped workflow; see Rules.
Inspect the recorded result
loom logs <run_id> --state
loom logs <run_id> --tail 30
loom logs <run_id> --json
The run ID and both file paths are printed by loom run. Records in
.loom/.runtime/runs/<run_id>/state.jsonl identify workflow, job, step and command
transitions by kind, IDs, timestamp and status. Recorded results may include
exit_code and error. The adjacent events.jsonl contains messages with the
same context, plus level, stream and optional exit_code.
MCP clients use loom_read_run to read states and loom_read_events to read
messages, optionally filtering by exact job_id or stream. See
MCP tools and the
Runtime logs contract.
An interrupted run may have no final state. If recording could not start, use
the terminal error. Declared artifact files are stored separately beneath
.loom/.runtime/artifacts/<run_id>/jobs/<job-id>/.