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.

  1. 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.

{ "ok": true, "bundle": "bundle", "finalized": true, "idempotent": false, "model_sha256": "59397a4431d93c7281101e9ecc0a03a56460efe7c01151a6be2435b7549d09f4", "attachments": 5}

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.

  1. List the files.find bundle -type f | sort
  2. 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.

bundle/blobs/sha256/25/254ac303…bundle/blobs/sha256/5e/5e566dcf…bundle/blobs/sha256/bb/bbc9717a…bundle/blobs/sha256/da/da416f89…bundle/blobs/sha256/e8/e8fc40f1…bundle/catalog.jsonbundle/finalized.jsonbundle/flow/pin.yamlbundle/integrity.jsonbundle/manifest.jsonbundle/model/report.jsonbundle/replay.jsonbundle/run.jsonbundle/steps/src_439e2527ecb3.1.jsonbundle/steps/src_4d88cd3b8ce7.1.jsonbundle/steps/src_6e8f4cb97336.1.jsonbundle/steps/src_99a4836d6852.1.jsonbundle/steps/src_e6b3bbcac7e1.1.jsonbundle/steps/src_f8b360411243.1.jsonbundle/streams/events.ndjsonbundle/summary.json
{ "attempt_id": "attempt_…", "catalog": "catalog.json", "finalized": true, "integrity": "integrity.json", "model": "model/report.json", "replay": "replay.json", "run_id": "fr_…", "schema": "autonom.bundle/v2", "summary": "summary.json"}{ "attachments": 5, "attempt_id": "attempt_…", "case_id": "case_daaab23de6ec5430", "first_causal_failure": "src_4d88cd3b8ce7.1", "history_id": "hist_9d9270ba34dd43aa", "proof_verdict": "fail", "run_id": "fr_…", "schema": "autonom.summary/v1", "status": "failed", "step_status": { "broken": 0, "failed": 1, "passed": 5, "skipped": 0, "unknown": 0 }, "steps": 6}

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.

  1. Check every digest.autonom report verify bundle

You should see ok: true, the number of files checked and the run.

{ "ok": true, "bundle": "bundle", "files": 18, "run_id": "fr_…"}exit 0

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.

  1. Finalize the same run into the same directory.autonom report bundle --run <run-id> --out bundle
  2. 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.

{ "ok": true, "bundle": "bundle", "finalized": true, "idempotent": true, "model_sha256": "59397a4431d93c7281101e9ecc0a03a56460efe7c01151a6be2435b7549d09f4"}exit 0{"ok": false, "error_code": "report_bundle_finalized", "error": "report bundle is finalized and differs from this run", "hint": "Choose a new output directory; finalized raw evidence is immutable.", "bundle": "bundle"}exit 2{"ok": false, "error_code": "report_bundle_finalized", "error": "output directory is non-empty and not an Autonom finalized bundle", "hint": "Choose an empty output directory.", "bundle": "notes"}exit 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.

  1. Annotate by the step's stable id.

    The id comes from first_causal_failure, or from agent inspect.

    autonom report annotate bundle "Welcome never appears after Continue" --author qa --step src_4d88cd3b8ce7.1
  2. Try the same with the step's index.autonom report annotate bundle "Welcome never appears after Continue" --author qa --step 6
  3. 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.

{ "ok": true, "schema": "autonom.annotation/v1", "annotation_id": "annotation_…", "created_at": "2026-10-19T08:07:00.188Z", "author": "qa", "text": "Welcome never appears after Continue", "attempt_id": "attempt_…", "step_id": "src_4d88cd3b8ce7.1", "path": "bundle/annotations/annotation_….json"}{"ok": false, "error_code": "flow_replay_step_not_reached", "error": "bundle has no step '6'"}exit 2{ "ok": true, "bundle": "bundle", "files": 18, "run_id": "fr_…"}

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.

  1. 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.

{"ok": false, "error_code": "report_integrity_failed", "error": "report bundle integrity verification failed", "failures": [{"path": "steps/src_4d88cd3b8ce7.1.json", "reason": "digest-mismatch"}]}exit 2{"ok": false, "error_code": "report_integrity_failed", "error": "report bundle integrity verification failed", "failures": [{"path": "streams/events.ndjson", "reason": "missing"}]}exit 2{"ok": false, "error_code": "report_integrity_failed", "error": "bundle has no manifest.json"}exit 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.

  1. 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.

{"ok": false, "error_code": "no_active_session", "error": "no active session", "hint": "Start one with 'autonom session start', or pass a session id."}exit 2{ "ok": true, "bundle": "later", "finalized": true, "idempotent": false, "model_sha256": "60f7ad7012b7cbbe4891f108c16eb97b6d7d45b505da61d83c88390037d21c98", "attachments": 5}exit 0

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.

# autonom below runs this checkout against Autonom's test emulator, showing a PIN screen the script writes.S=$PWD W=/tmp/autonom-bundlerm -rf $W && mkdir -p $W && cd $Wexport AUTONOM_HOME=$W/.autonom AUTONOM_FAKE_STATE=$W/device.jsonautonom() { python3 $S/scripts/autonom.py --adb $S/tests/fakes/fake_adb.py "$@"; }cat > pin.xml <<'XML'<?xml version="1.0" encoding="UTF-8" standalone="yes" ?><hierarchy rotation="0"> <node index="0" text="" resource-id="" class="android.widget.FrameLayout" package="com.example.app" content-desc="" clickable="false" enabled="true" focusable="false" focused="false" scrollable="false" bounds="[0,0][1080,2400]"> <node index="0" text="Enter your PIN" resource-id="com.example.app:id/title" class="android.widget.TextView" package="com.example.app" content-desc="" clickable="false" enabled="true" focusable="false" focused="false" scrollable="false" bounds="[80,200][1000,300]" /> <node index="1" text="" resource-id="com.example.app:id/pin" class="android.widget.EditText" package="com.example.app" content-desc="PIN" clickable="true" enabled="true" focusable="true" focused="true" scrollable="false" bounds="[80,400][1000,520]" /> <node index="2" text="Continue" resource-id="com.example.app:id/continue" class="android.widget.Button" package="com.example.app" content-desc="" clickable="true" enabled="true" focusable="true" focused="false" scrollable="false" bounds="[80,600][1000,720]" /> </node></hierarchy>XMLecho "{\"ui_dump\": \"$W/pin.xml\"}" > $AUTONOM_FAKE_STATEcat > pin.yaml <<'YAML'schema: autonom.dev/flow/v1appId: com.example.appname: PIN sign-inid: pin-sign-in---- launchApp- tapOn: selector: description: PIN- inputText: ${APP_PIN}- checkpoint: pin-entered- tapOn: selector: text: Continue- assertVisible: selector: text: Welcome timeoutMs: 1000YAMLautonom session start --serial emulator-5554 --app-id com.example.app > session.jsonSESSION=$(python3 -c 'import json, sys; print(json.load(open(sys.argv[1]))["session"]["session_id"])' session.json)export APP_PIN=271828autonom flow run pin.yaml --secret APP_PIN > run.jsonRUN=$(python3 -c 'import json, sys; print(json.load(open(sys.argv[1]))["run_id"])' run.json)# Finalize a bundleautonom report bundle --run $RUN --out bundle# Look insidefind bundle -type f | sortpython3 -m json.tool bundle/manifest.jsonpython3 -m json.tool bundle/summary.json# Verify itautonom report verify bundle; echo "exit $?"# Finalize againautonom report bundle --run $RUN --out bundle; echo "exit $?"autonom flow run pin.yaml --secret APP_PIN > run-2.jsonRUN2=$(python3 -c 'import json, sys; print(json.load(open(sys.argv[1]))["run_id"])' run-2.json)autonom report bundle --run $RUN2 --out bundle; echo "exit $?"mkdir notes && echo "draft" > notes/todo.txtautonom report bundle --run $RUN2 --out notes; echo "exit $?"# Annotate a stepautonom report annotate bundle "Welcome never appears after Continue" --author qa --step src_4d88cd3b8ce7.1autonom report annotate bundle "Welcome never appears after Continue" --author qa --step 6; echo "exit $?"autonom report verify bundle# When verification failscp -R bundle edited && echo '{}' >> edited/steps/src_4d88cd3b8ce7.1.jsonautonom report verify edited; echo "exit $?"cp -R bundle missing && rm missing/streams/events.ndjsonautonom report verify missing; echo "exit $?"autonom report verify notes; echo "exit $?"autonom session stop > /dev/nullautonom report bundle --run $RUN --out later; echo "exit $?"autonom report bundle --session $SESSION --run $RUN --out later; echo "exit $?"

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 pack verify 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_failure in summary.json, or from agent 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 verify does not notice. Files that integrity.json does 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.json and finalized.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's sha256 from ci pack, and check packs before ci 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 pack puts a verified bundle into one ZIP file for a CI campaign.

Reference

The commands.

CommandWhat it does
autonom report bundle --out DIRFinalizes the current session's latest run into an empty or new directory. Without --out, into bundle-v2 in the run's directory.
--run IDFinalizes that run instead of the latest.
--session IDTakes the run from that session, running or stopped.
autonom report verify DIRChecks the descriptor, both finalization records and every listed file.
autonom report annotate DIR TEXTWrites a note under annotations/. Takes --step STEP_ID and --author NAME; the default author is human.

The layout of a bundle.

PathWhat it holds
manifest.jsonThe autonom.bundle/v2 descriptor: run_id, attempt_id, and the paths of the model, summary, catalog, replay manifest and integrity list.
run.jsonThe run's record, with values under keys that look like credentials replaced by <redacted>.
model/report.jsonThe report of the run, which the agent report and the gates read.
summary.jsonautonom.summary/v1: status, proof verdict, step counts, first_causal_failure, and the case_id and history_id of the flow.
catalog.jsonEvery attachment, with the blob that holds it, its size and digest, or why it is unavailable.
replay.jsonautonom.replay/v1: what a replay needs, its checkpoints, and the status each step must end with.
steps/<step-id>.jsonOne file per step.
streams/events.ndjsonThe 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.jsonThe digest and size of every file above except manifest.json.
finalized.jsonautonom.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.

errorWhat it means
bundle has no manifest.jsonThe directory is not a bundle.
unsupported bundle schemamanifest.json is not autonom.bundle/v2.
bundle descriptor contains non-canonical core pathsmanifest.json points the model, summary, catalog, replay manifest or integrity list somewhere else.
bundle is missing its integrity or finalization recordintegrity.json or finalized.json is gone.
bundle integrity catalog digest does not match finalization recordintegrity.json was changed.
report model digest does not match finalization recordmodel/report.json was changed or removed.
report bundle integrity verification failedA 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 codeWhen
report_bundle_finalized--out holds a finalized bundle of another run, or other files.
report_integrity_failedThe directory has no manifest.json, or a check failed.
flow_replay_step_not_reachedreport annotate --step names no step id of the run.
no_active_sessionThere is no --session and no current session.

Next steps

You can keep, check and annotate any run as a bundle.

Search documentation

Type to find a guide.

↑ ↓ to move · Enter to open · Esc to close