Skip to main content

Job execution flow

A Loom job becomes eligible when its scheduling prerequisites are satisfied. Loom prepares its workspace and provider, resolves variables and secrets, runs its commands, and completes cleanup and any configured artifact publication.

Execution order​

Optional cache, services and image-build work depend on the job definition. Provider or preparation failures can prevent command execution.

Recorded steps and commands​

The run's state.jsonl records jobs and their declared setup, script and finalization steps. Each command has a phase-local ID such as setup-01, script-01 or finalization-01. The step ID includes the job and phase, for example build:script. A configured image build has a separate image_build step. All records also identify the run and workflow.

Commands in a phase run sequentially. Setup and script share a shell; finalization uses a fresh shell after the primary command, including when setup or script fails. The first failing command stops its phase. Commands never entered are recorded as not_run without a fabricated exit code.

Step and command transitions record their completion when it is observed. Later artifact or cleanup failure can fail the job without changing an already completed command's result. Job state is final only after that follow-up work.

Cleanup and artifact publication​

Secret cleanup finishes before declared artifact publication. Artifact matching uses the workspace that executed the job or its provider export. Published files are retained beneath .loom/.runtime/artifacts/<run_id>/jobs/<job-id>/, with artifacts.tar.gz in that directory when files are published.

Publication diagnostics and failures appear in the run's events.jsonl with job_id. A required publication or cleanup failure contributes to job failure. See Workflow artifacts for when, required, includes and exclusions.

Inspect a job​

loom logs <run_id> --state
loom logs <run_id> --json

Find the job's state records, then match its job_id, step_id and command_id in the event records. Events contain contextual messages and stdout/stderr with timestamp, level, stream and optional exit_code. Provider, cache, services and artifact diagnostics share this event file.

For a smaller structured excerpt, MCP supports an exact job filter:

{
  "tool": "loom_read_events",
  "run_id": "<run_id>",
  "job_id": "build",
  "tail": true,
  "max_lines": 30
}

loom_read_run returns all state transitions. See MCP tools, Runtime logs and Pipeline execution flow.