Skip to main content

Diagnostics ladder

The CLI prints the run directory, state.jsonl and events.jsonl paths.

Follow the run, job and step​

  1. Run loom logs <run_id> --state to inspect lifecycle transitions.
  2. Find the failed workflow, job, step or command and its exit code.
  3. Run loom logs <run_id> --tail 30 to read recent messages.
  4. Use loom logs <run_id> --json for full job, step, command and stream context.

Both files live directly beneath .loom/.runtime/runs/<run_id>/. A message can contain several output lines, carriage returns or output without a terminating newline. Events retain their recorded order.

Execution outcome and evidence state​

An interrupted process may leave a running state as its last complete record. Readers ignore an incomplete final append and reject malformed complete records. If no run directory was allocated, inspect the terminal error. The two JSONL files are the recorded source; readers do not reconstruct other artifact formats.

Read through MCP​

loom_read_run returns ordered state records for a run ID. loom_read_events returns events and supports job_id, stream, max_lines and tail. For command failures, inspect output preceding the failed state with the same job, step or command ID. A stderr record is stream attribution; it does not automatically imply an error.

Keep investigation pointers portable​

Share the run ID and relevant job, step or command IDs with a reviewed excerpt from state.jsonl and events.jsonl. The records can be read without the original workflow workspace. Review messages for secrets before sharing.

Next steps​