# Report bundle

Canonical URL: https://autonom.yatsuk.me/docs/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**

```sh
autonom report bundle --run <run-id> --out bundle
```

**Needs** [a flow run](https://autonom.yatsuk.me/docs/flows/index.md)

## 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](https://autonom.yatsuk.me/docs/replay/index.md), [`agent export` and `agent inspect`](https://autonom.yatsuk.me/docs/agent-report/index.md) and [`ci pack`](https://autonom.yatsuk.me/docs/ci/index.md) 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`](https://autonom.yatsuk.me/docs/safety/index.md#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`.

   ```sh
   autonom report bundle --run <run-id> --out bundle
   ```

You should see `finalized: true` and the number of attachments it kept.

*Output of autonom report bundle*

```
{
  "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.**

   ```sh
   find bundle -type f | sort
   ```

2. **Read the descriptor and the summary.**

   ```sh
   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.

*Output of find*

```
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.json
bundle/finalized.json
bundle/flow/pin.yaml
bundle/integrity.json
bundle/manifest.json
bundle/model/report.json
bundle/replay.json
bundle/run.json
bundle/steps/src_439e2527ecb3.1.json
bundle/steps/src_4d88cd3b8ce7.1.json
bundle/steps/src_6e8f4cb97336.1.json
bundle/steps/src_99a4836d6852.1.json
bundle/steps/src_e6b3bbcac7e1.1.json
bundle/steps/src_f8b360411243.1.json
bundle/streams/events.ndjson
bundle/summary.json
```

*manifest.json and summary.json, indented*

```
{
    "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.**

   ```sh
   autonom report verify bundle
   ```

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

*Output of autonom report verify and its exit code*

```
{
  "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.**

   ```sh
   autonom report bundle --run <run-id> --out bundle
   ```

2. **Finalize a second run into it, then into a directory of notes.**

   ```sh
   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`](https://autonom.yatsuk.me/docs/safety/index.md#report_bundle_finalized) twice, with exit code 2.

*Output of autonom report bundle, three times*

```
{
  "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`](https://autonom.yatsuk.me/docs/agent-report/index.md).

   ```sh
   autonom report annotate bundle "Welcome never appears after Continue" --author qa --step src_4d88cd3b8ce7.1
   ```

2. **Try the same with the step's index.**

   ```sh
   autonom report annotate bundle "Welcome never appears after Continue" --author qa --step 6
   ```

3. **Verify the bundle again.**

   ```sh
   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.

*Output of autonom report annotate, twice, and of autonom report verify*

```
{
  "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`](https://autonom.yatsuk.me/docs/safety/index.md#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.**

   ```sh
   autonom report verify edited autonom report verify missing autonom report verify notes
   ```

You should see [`report_integrity_failed`](https://autonom.yatsuk.me/docs/safety/index.md#report_integrity_failed) three times, with exit code 2.

*Output of autonom report verify, three times*

```
{"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.**

   ```sh
   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`](https://autonom.yatsuk.me/docs/safety/index.md#no_active_session), then a finalized bundle.

*Output of autonom report bundle, twice*

```
{"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`.

*Script that reproduces the outputs*

```sh
# autonom below runs this checkout against Autonom's test emulator, showing a PIN screen the script writes.
S=$PWD W=/tmp/autonom-bundle
rm -rf $W && mkdir -p $W && cd $W
export AUTONOM_HOME=$W/.autonom AUTONOM_FAKE_STATE=$W/device.json
autonom() { 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>
XML
echo "{\"ui_dump\": \"$W/pin.xml\"}" > $AUTONOM_FAKE_STATE
cat > pin.yaml <<'YAML'
schema: autonom.dev/flow/v1
appId: com.example.app
name: PIN sign-in
id: pin-sign-in
---
- launchApp
- tapOn:
    selector:
      description: PIN
- inputText: ${APP_PIN}
- checkpoint: pin-entered
- tapOn:
    selector:
      text: Continue
- assertVisible:
    selector:
      text: Welcome
    timeoutMs: 1000
YAML
autonom session start --serial emulator-5554 --app-id com.example.app > session.json
SESSION=$(python3 -c 'import json, sys; print(json.load(open(sys.argv[1]))["session"]["session_id"])' session.json)
export APP_PIN=271828
autonom flow run pin.yaml --secret APP_PIN > run.json
RUN=$(python3 -c 'import json, sys; print(json.load(open(sys.argv[1]))["run_id"])' run.json)
# Finalize a bundle
autonom report bundle --run $RUN --out bundle
# Look inside
find bundle -type f | sort
python3 -m json.tool bundle/manifest.json
python3 -m json.tool bundle/summary.json
# Verify it
autonom report verify bundle; echo "exit $?"
# Finalize again
autonom report bundle --run $RUN --out bundle; echo "exit $?"
autonom flow run pin.yaml --secret APP_PIN > run-2.json
RUN2=$(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.txt
autonom report bundle --run $RUN2 --out notes; echo "exit $?"
# Annotate a step
autonom report annotate bundle "Welcome never appears after Continue" --author qa --step src_4d88cd3b8ce7.1
autonom report annotate bundle "Welcome never appears after Continue" --author qa --step 6; echo "exit $?"
autonom report verify bundle
# When verification fails
cp -R bundle edited && echo '{}' >> edited/steps/src_4d88cd3b8ce7.1.json
autonom report verify edited; echo "exit $?"
cp -R bundle missing && rm missing/streams/events.ndjson
autonom report verify missing; echo "exit $?"
autonom report verify notes; echo "exit $?"
autonom session stop > /dev/null
autonom 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](https://autonom.yatsuk.me/docs/agent-report/index.md#screen-evidence) shows where it ends up.
- **Send it whole.** [`ci pack`](https://autonom.yatsuk.me/docs/ci/index.md) puts 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.

- [Agent report](https://autonom.yatsuk.me/docs/agent-report/index.md): Read the bundle as compact JSON your agent can act on.
- [Replay](https://autonom.yatsuk.me/docs/replay/index.md): Rebuild the state of the bundled run, up to the failing step.
- [CI campaigns](https://autonom.yatsuk.me/docs/ci/index.md): Pack bundles as shards and gate them as one campaign.
- [Evidence](https://autonom.yatsuk.me/docs/evidence/index.md): Open the same run as an HTML report.