Receipts

A receipt is Loom's smallest shareable run artifact. It tells you which run happened, where its runtime artifacts live, and now also where the phase report lives if you need to validate the runtime timeline itself.

If you remember one thing, remember this: share the receipt path first.

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 does not replace the logs tree. It gets you into the right run quickly.

What the current run receipt contains

For loom run --local, the receipt currently 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

What phase_report_path adds

The older receipt story was mostly "follow logs_dir into manifests and events."

The current runtime adds a second top-level pointer:

Pointer	Best use
logs_dir	Find the failing job, step, section, or artifact
phase_report_path	Check phase coverage, missing boundaries, or invalid ordering

In other words:

• Use logs_dir for failure evidence
• Use phase_report_path for runtime-contract evidence

How to use a receipt in practice

1. Open the receipt from the path Loom printed.
2. Check status and exit_code.
3. If the run failed, follow logs_dir into pipeline/summary.json and pipeline/manifest.json.
4. Open the failing job manifest and follow the exact events pointer from there.
5. Open phase_report_path only 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 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

Loom prints the receipt path at the end of the run:

receipt: /absolute/path/to/repo/.loom/.runtime/receipts/loom-run-local-1772865600000000000.json

The current implementation prints an absolute path, which makes it easy to paste into editors, issue reports, or automation.

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 can follow the exact same pointers you see
Reporting Loom behavior that feels wrong	The receipt anchors the report to one real run
Escalating a CI failure	It is a smaller, cleaner handoff than a large log dump
Comparing two runs	It gives you stable paths and status metadata for each run

Privacy notes

Receipts are small, but they still contain sensitive context.

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

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

What to read next

• Runtime logs
• Receipts contract
• Diagnostics ladder