Receipts
A receipt records the run's status, source context, and paths to its runtime logs and phase report. It also contains the compiled graph and executor output, so its size grows with the workflow and output volume.
Start with the receipt path when asking for help. The recipient needs access to the referenced files; for remote help, attach reviewed evidence or provide an excerpt as described in What to share.
Why receipts matter
Receipts give you a stable starting point for three common tasks:
- Diagnose a failing run without guessing at paths
- Hand the same run context to a teammate or agent
- Confirm which exact repository state and runtime artifacts were used
What a receipt points to
The receipt identifies the logs tree for the recorded run.
What a run receipt contains
For loom run --local, the receipt includes:
| Field | Why it matters |
|---|---|
status, exit_code | Fast pass or fail check |
logs_dir | Pointer to the full runtime logs tree |
events_jsonl_path | Pointer to the run-scoped event stream |
phase_report_path | Pointer to the phase validation and coverage report |
repo_root, workflow_path | Identify the workspace and workflow that ran |
snapshot_path, snapshot_head_sha | Identify the snapshot context when present |
graph_ir, executor_receipt | Explain what Loom planned and what the executor did |
For jobs with artifacts:, the executor receipt separates Command from ArtifactPublication. This is the quickest way to distinguish a script failure from a file-secret cleanup, copy, provider export, required-match, or archive failure. The aggregate node and run still fail if either required phase fails.
What phase_report_path adds
Choose a pointer based on what you need to inspect:
| Pointer | Best use |
|---|---|
logs_dir | Find the failing job, step, section, or artifact |
phase_report_path | Check phase coverage, missing boundaries, or invalid ordering |
How to use a receipt in practice
- Open the receipt from the path Loom printed.
- Check
statusandexit_code. - If the run failed, follow
logs_dirintopipeline/summary.jsonandpipeline/manifest.json. - Open the failing job manifest and follow the exact events pointer from there.
- Open
phase_report_pathonly when you need phase validation or coverage detail.
When to reach for the phase report
Open phase-report.json when the usual failure ladder does not answer the right question.
| Question | Better pointer |
|---|---|
| "Which job or step failed?" | logs_dir |
| "Did the command or artifact publication fail?" | executor_receipt.Nodes[] |
| "Did cache save run at all?" | phase_report_path |
| "Was cleanup emitted?" | phase_report_path |
| "Why is this skipped rather than failed?" | Job manifest first, then phase_report_path if needed |
| "Did Loom emit phases out of order?" | phase_report_path |
What Loom prints
When Loom writes a run receipt, it prints the path:
receipt: /absolute/path/to/repo/.loom/.runtime/receipts/loom-run-local-1772865600000000000.json
Loom prints an absolute path. Configuration, workspace, or observer setup can fail before a receipt is written; use the CLI error if no path was printed.
When to share the receipt
Share the receipt path before sharing broad logs when:
| Situation | Why it helps |
|---|---|
| Asking for help with a failing run | Others with access to the evidence can follow the same pointers |
| Reporting Loom behavior that feels wrong | The receipt anchors the report to one real run |
| Escalating a CI failure | It identifies the run and the evidence to inspect |
| Comparing two runs | It identifies each run's paths and status |
Privacy notes
Review receipts before sharing. They contain source and environment context as well as recorded executor output.
| Field family | Why to review it |
|---|---|
Path fields such as repo_root, workflow_path, logs_dir, phase_report_path | Reveal usernames and filesystem layout |
snapshot_head_sha | Reveals commit identity |
command | Reveals exact CLI flags and arguments |
graph_ir, executor_receipt | Can contain declared variable values and command output |
If you need to share externally, redact paths first and then expand only to the specific event stream someone actually needs.
Common mistakes
| Mistake | Better move |
|---|---|
| Guessing the receipt filename | Copy the path Loom printed |
Jumping straight to events.jsonl | Follow the receipt into the manifests first |
Treating phase_report_path as the main failure ladder | Use it as a complement, not a replacement |
| Sharing an entire runtime directory | Share the receipt path and one pointed artifact |