Report bundle
Keep a run as one portable directory: its flow, its steps, its report and its evidence, each file recorded by its digest. Autonom never rewrites a finalized bundle, and replay, the agent report and ci pack verify it before they read it, which catches a damaged file or an edit that left the records alone. ci merge and ci finalize do not check the digests, so verify packs from other runners before you merge them. The digests are not a signature, so take bundles only from a source you trust.
Try it autonom report bundle --run <run-id> --out bundle
Needs a flow run
How it works
autonom report bundle finalizes one run of a session as a Report Bundle v2. It takes the current session's latest run, the run --run names, or a run of the session --session names, which can be stopped. Without --out, the bundle goes to bundle-v2 in the run's own directory.
The bundle is written into a staging directory beside --out, then moved into place in one step, so nobody reads half a bundle. Its manifest.json is the autonom.bundle/v2 descriptor: the run and attempt ids, and where the report, summary, catalog, replay manifest and integrity list are. Evidence files are stored once each under blobs/sha256/, named by their digest.
integrity.json lists every file of the bundle with its SHA-256 digest and size, except itself, manifest.json, finalized.json and annotations/. finalized.json records the digest of integrity.json and of the report. autonom report verify checks both records and every listed file, and says which file failed and why. The digests are plain SHA-256 values stored in the bundle itself, with no key and no signature: verification catches corruption and edits that did not also rewrite integrity.json and finalized.json, but someone who changes a file and recomputes both records gets a bundle that verifies. It shows that a bundle is whole, not who made it, so take bundles and CI shards only from runners and channels you trust. Replay, agent export and agent inspect and ci pack run the same check before they read anything, and refuse a bundle that fails it. ci merge and ci finalize do not: merge reads shard.json and bundle/model/report.json from each pack and checks only the report's schema, and finalize gates the reports merge copied. A pack whose report was changed after ci pack, for example a failed run flipped to passed, is merged and gated as it is. Before you merge a pack from a runner you do not control, unzip it and run autonom report verify on its bundle/ directory. Or, after the merge and before ci finalize, compare the pack's sha256 that ci pack printed on the runner with the sha256 that campaign.json records for that shard.
A finalized bundle is never rewritten. Finalizing the same run into the same directory again is a no-op that answers idempotent: true. A different run, or a directory that holds anything else, is refused with report_bundle_finalized.
Notes go beside the evidence, not into it. autonom report annotate writes one file under annotations/, which the digests do not cover, so a bundle still verifies after every note. Its --step takes the step's stable step id, such as src_4d88cd3b8ce7.1. In v0.36.1 it does not take a runtime index, although agent inspect and replay do.
Examples
Every output here comes from Autonom's test emulator showing a PIN screen, so you can rerun it without a device. The run types a PIN from the APP_PIN secret, taps Continue, then waits for a Welcome screen that never comes, so step 6 fails. On a real device the blobs hold real screenshots, so their number and sizes differ. Reproduce these outputs, at the end of this section, has the exact commands.
Finalize a run as a bundle
Goal: keep a failed run in a form that outlives the session.
- Finalize the run.
The run id comes from the answer of
flow run.autonom report bundle --run <run-id> --out bundle
You should see finalized: true and the number of attachments it kept.
What to look at. model_sha256 is the digest of the report inside the bundle. attachments counts the evidence of the run: here its event stream, and a screen tree and a screenshot after step 4 and at the failure.
Look inside
Goal: know where each part of the run is.
- List the files.
find bundle -type f | sort - Read the descriptor and the summary.
python3 -m json.tool bundle/manifest.json python3 -m json.tool bundle/summary.json
You should see the evidence under blobs/, one file per step, and a summary that names the first failure.
What to look at. The bundle carries its own copy of the flow under flow/, which is why a replay from a bundle still works after the checkout moves on. Each step file is named by its stable step id. first_causal_failure names the step to start from, src_4d88cd3b8ce7.1, the failing step 6. The reference below describes every path.
Verify it
Goal: check that no file changed after finalizing without its records being rewritten too.
- Check every digest.
autonom report verify bundle
You should see ok: true, the number of files checked and the run.
What to look at. files counts the files integrity.json lists: the 21 files above, less manifest.json, integrity.json and finalized.json, which report verify checks in their own ways: the descriptor's schema and paths, and the two digests finalized.json records.
Finalize again
Goal: retry a bundle step safely, and see what Autonom refuses to overwrite.
- Finalize the same run into the same directory.
autonom report bundle --run <run-id> --out bundle - Finalize a second run into it, then into a directory of notes.
autonom report bundle --run <second-run-id> --out bundle autonom report bundle --run <second-run-id> --out notes
You should see idempotent: true for the retry, then report_bundle_finalized twice, with exit code 2.
What to look at. The retry returns the same model_sha256 and rewrites nothing, so a CI step that finalizes twice is harmless. A bundle never takes another run's evidence, and a directory with other files in it is never used, so nothing is overwritten by mistake. Give every run its own --out.
Annotate a step
Goal: add a reviewer's note to the failing step without changing the evidence.
- Annotate by the step's stable id.
The id comes from
first_causal_failure, or fromagent inspect.autonom report annotate bundle "Welcome never appears after Continue" --author qa --step src_4d88cd3b8ce7.1 - Try the same with the step's index.
autonom report annotate bundle "Welcome never appears after Continue" --author qa --step 6 - Verify the bundle again.
autonom report verify bundle
You should see the note and where it was written, then a refusal for the index, then a bundle that still verifies.
What to look at. In v0.36.1 --step matches the stable step id only, so the index 6 is refused with flow_replay_step_not_reached even though step 6 exists. Without --step the note is about the whole run, and without --author its author is human. files is still 18: the note is not part of the evidence, so it is not covered by a digest either.
When verification fails
Goal: see what a changed, a missing and a foreign file look like.
- Verify a copy whose step file was edited, a copy that lost its event stream, and a directory that is not a bundle.
autonom report verify edited autonom report verify missing autonom report verify notes
You should see report_integrity_failed three times, with exit code 2.
What to look at. failures names each file and its reason: digest-mismatch for a file whose content changed, missing for a listed file that is gone. A directory without manifest.json is not read at all. Replay, the agent report and ci pack give the same answer for the same bundle, so a damaged bundle, or one edited without rewriting its records, cannot be replayed, reported on or packed. ci merge does not run this check, so a pack changed after ci pack is merged as it is. A deliberate edit that recomputes integrity.json and finalized.json passes, because the digests carry no key.
Bundle a run after the session stopped
Goal: keep a run you forgot to bundle before session stop.
- Finalize it without a session, then with the stopped session's id.
autonom report bundle --run <run-id> --out later autonom report bundle --session <session-id> --run <run-id> --out later
You should see no_active_session, then a finalized bundle.
What to look at. A stopped session keeps its runs, so --session reaches them. The new bundle's model_sha256 differs from the first bundle's, because the report records when it was compiled; the retry in Finalize again kept the first digest because it compiled nothing.
Reproduce these outputs
From the root of an Autonom checkout at tag v0.36.1 (commit ca2a280), in bash or zsh. The autonom function runs that checkout against its test emulator, and the script writes the PIN screen it shows. Run ids, attempt ids, annotation ids, session ids, digests and times differ on every run, and ids are shortened to … on the page; step, case and history ids stay the same, because the flow has an id.
Good to know
Bundle every run that matters later. A bundle outlives the session and the checkout: it keeps its own copy of the flow, and replay, the agent report and
ci packverify it first.One run, one directory. A finalized directory takes no other run and no other files. A retry of the same run is safe.
Annotate by step id. Read the id from
first_causal_failureinsummary.json, or fromagent inspect, which accepts either form.Notes are not evidence. Annotations sit outside the digests, so anyone who can write to the bundle can add or change one, and
report verifydoes not notice. Files thatintegrity.jsondoes not list are not checked either.Verified is not signed. The digests have no key, so anyone who can write to the bundle can change a file and recompute
integrity.jsonandfinalized.json, and the bundle still verifies. Move bundles and shards over channels you trust, and keep your own copy of a digest you need to rely on, such as the pack'ssha256fromci pack, and check packs beforeci merge, which does not verify them.Treat a bundle as sensitive when the screen can show a secret. The run records a secret's name, not its value, but screen trees and screenshots keep what the screen showed. Agent report shows where it ends up.
Send it whole.
ci packputs a verified bundle into one ZIP file for a CI campaign.
Reference
The commands.
| Command | What it does |
|---|---|
autonom report bundle --out DIR | Finalizes the current session's latest run into an empty or new directory. Without --out, into bundle-v2 in the run's directory. |
--run ID | Finalizes that run instead of the latest. |
--session ID | Takes the run from that session, running or stopped. |
autonom report verify DIR | Checks the descriptor, both finalization records and every listed file. |
autonom report annotate DIR TEXT | Writes a note under annotations/. Takes --step STEP_ID and --author NAME; the default author is human. |
The layout of a bundle.
| Path | What it holds |
|---|---|
manifest.json | The autonom.bundle/v2 descriptor: run_id, attempt_id, and the paths of the model, summary, catalog, replay manifest and integrity list. |
run.json | The run's record, with values under keys that look like credentials replaced by <redacted>. |
model/report.json | The report of the run, which the agent report and the gates read. |
summary.json | autonom.summary/v1: status, proof verdict, step counts, first_causal_failure, and the case_id and history_id of the flow. |
catalog.json | Every attachment, with the blob that holds it, its size and digest, or why it is unavailable. |
replay.json | autonom.replay/v1: what a replay needs, its checkpoints, and the status each step must end with. |
steps/<step-id>.json | One file per step. |
streams/events.ndjson | The run's event stream. |
flow/ | The copy of the flow, and flow/.autonom/. |
blobs/sha256/<prefix>/<digest> | The evidence files, each stored once under its digest. |
integrity.json | The digest and size of every file above except manifest.json. |
finalized.json | autonom.finalized/v1: the digests of integrity.json and of the report. |
annotations/ | The notes, one file each. Not covered by the digests. |
What report verify answers when a check fails, in v0.36.1. Each is report_integrity_failed.
error | What it means |
|---|---|
bundle has no manifest.json | The directory is not a bundle. |
unsupported bundle schema | manifest.json is not autonom.bundle/v2. |
bundle descriptor contains non-canonical core paths | manifest.json points the model, summary, catalog, replay manifest or integrity list somewhere else. |
bundle is missing its integrity or finalization record | integrity.json or finalized.json is gone. |
bundle integrity catalog digest does not match finalization record | integrity.json was changed. |
report model digest does not match finalization record | model/report.json was changed or removed. |
report bundle integrity verification failed | A listed file failed; failures names each path with reason digest-mismatch when its content changed, or missing when it is gone. |
The error codes, each with exit code 2.
| Error code | When |
|---|---|
report_bundle_finalized | --out holds a finalized bundle of another run, or other files. |
report_integrity_failed | The directory has no manifest.json, or a check failed. |
flow_replay_step_not_reached | report annotate --step names no step id of the run. |
no_active_session | There is no --session and no current session. |
Next steps
You can keep, check and annotate any run as a bundle.