Playbook: diagnose a failing run

Keep the run ID printed by loom run. Inspect the state transitions, then the recent event messages:

loom logs <run_id> --state
loom logs <run_id> --tail 30

State records identify the failed job, step or command and its exit code. Event records include the same IDs, stream and protected message. For structured filtering, use loom logs <run_id> --json, or MCP:

{ "tool": "loom_read_run", "run_id": "<run_id>" }

{
  "tool": "loom_read_events",
  "run_id": "<run_id>",
  "job_id": "<failed-job-id>",
  "tail": true,
  "max_lines": 30
}

If recent messages do not explain the failure, inspect more records from the same events.jsonl and compare their job and step IDs. An interrupted run may have no final state. If the run directory could not be created, use the terminal error.

Share the command, relevant state records and a short event excerpt. Review for credentials, secret values and sensitive paths first. See What to share, Diagnostics ladder, and Runtime logs.