# Replay

Canonical URL: https://autonom.yatsuk.me/docs/replay/

Rebuild the state of a recorded run and stop at the step you want to look at. Replay runs the run's own flow again on your current target, from the start, so your agent can inspect the screen just before or at a failure.

**Try it**

```sh
autonom replay --bundle <dir> --to-step 4
```

**Needs** [a session on one target](https://autonom.yatsuk.me/docs/sessions/index.md) · [a flow run](https://autonom.yatsuk.me/docs/flows/index.md)

## How it works

A replay starts from a recorded run. `--bundle` names a finalized [report bundle](https://autonom.yatsuk.me/docs/report-bundle/index.md), which `autonom report bundle --run ID --out DIR` writes; Autonom verifies the bundle first and replays the copy of the flow stored inside it. `--run` names a run of the current session, or of the session `--session` names, and replays the flow file from the path the run recorded. With neither, the session's latest run is the source.

The replay itself always runs on the current session's target, so a current session is required even when the source is a bundle. It runs the flow from its first step, with the source run's `--env` values. Secrets are read again from your environment by name, because the run recorded only their names. Evidence is kept for every step: screenshots, screen trees, logs and requests.

`--to-step` chooses where to stop. It takes a runtime index such as `4`, or a stable step id such as `src_4d88cd3b8ce7.1`. The replay stops right after that step, with status `replayed`, once the step ends the way it ended in the source run. A step that failed there must fail again, so you can stop exactly on a failure.

Replay does no cleanup. It does not reset the app or the device before it starts, beyond what the flow's own steps do. When it stops at `--to-step`, the flow's `onFlowComplete` steps do not run, so the device stays in that state for your agent to inspect. Each replay is a new run in the session, linked to the source by `parent_attempt_id`.

The exit code says how the replay ended:

- **`0`,** status `replayed`: the replay stopped at the `--to-step` step, which ended as it did in the source run. Without `--to-step`, status `passed`: the whole flow passed.
- **`1`,** status `failed` and `target` `null`: a step failed before the replay reached its stop, or the `--to-step` step failed where it had passed in the source run. Without `--to-step`, the flow failed. Inspect the new run to see which step failed.
- **`2`,** an error object on stderr: the replay was refused before anything ran, or, with `flow_replay_step_not_reached` after the flow ran, the flow finished every step without the `--to-step` step ending as it did in the source run. A failure that no longer happens gives this.

## Examples

Every output here comes from Autonom's test emulator showing a PIN screen, so you can rerun it without a device. The source run types a PIN from the `APP_PIN` secret, taps Continue, then waits for a Welcome screen that never comes, so step 6 fails. Reproduce these outputs, at the end of this section, has the exact commands.

### Rebuild the state at a step

**Goal:** put the device back where step 4 left it, and keep it there.

1. **Replay the bundle up to step 4.** Step 4 is the checkpoint after the PIN was typed.

   ```sh
   autonom replay --bundle bundle --to-step 4
   ```

You should see status `replayed`, and the step it stopped at.

*Output of autonom replay*

```
{
  "ok": true,
  "status": "replayed",
  "run_id": "fr_…",
  "parent_attempt_id": "attempt_…",
  "strategy": "baseline",
  "target": {
    "step_index": 4,
    "step_id": "src_439e2527ecb3.1",
    "source_id": "src_439e2527ecb3",
    "command": "checkpoint",
    "line": 11,
    "status": "passed",
    "error_code": null,
    "error": null
  },
  "events": "…/flows/fr_…/events.ndjson"
}
```

**What to look at.** `strategy: baseline` says the state was rebuilt by running the flow from its start. The replay's own report records that it stopped early and skipped cleanup:

*The replay field of the replay's agent report*

```
{
  "cleanup_hooks_skipped": true,
  "mode": "prefix",
  "portable_restore": "replay-from-flow-start",
  "target": {
    "command": "checkpoint",
    "error": null,
    "error_code": null,
    "line": 11,
    "source_id": "src_439e2527ecb3",
    "status": "passed",
    "step_id": "src_439e2527ecb3.1",
    "step_index": 4
  }
}
```

### Stop on the failing step, by its id

**Goal:** reproduce a failure and leave the device on it.

1. **Replay up to the failing step.** The stable id comes from the run's report; [Agent report](https://autonom.yatsuk.me/docs/agent-report/index.md) shows where to read it.

   ```sh
   autonom replay --bundle bundle --to-step src_4d88cd3b8ce7.1
   ```

You should see status `replayed`, with the step failing the same way it failed in the source run.

*Output of autonom replay to a failing step*

```
{
  "ok": true,
  "status": "replayed",
  "run_id": "fr_…",
  "parent_attempt_id": "attempt_…",
  "strategy": "baseline",
  "target": {
    "step_index": 6,
    "step_id": "src_4d88cd3b8ce7.1",
    "source_id": "src_4d88cd3b8ce7",
    "command": "assertVisible",
    "line": 15,
    "status": "failed",
    "error_code": "flow_assertion_timeout",
    "error": "{'text': 'Welcome', 'match': 'exact'} was not visible within 1000 ms"
  },
  "events": "…/flows/fr_…/events.ndjson"
}
```

**What to look at.** The exit code is 0: the replay did what you asked, which was to reach the failure. The failure is reproducible on this target, and the device now shows the screen where Welcome never appeared, ready for [a UI tree](https://autonom.yatsuk.me/docs/screen/index.md). A step id names the same step even if the flow gains a conditional branch, where an index could point somewhere else.

### Replay the whole run

**Goal:** check whether a failure still happens, from start to end.

1. **Replay without `--to-step`.**

   ```sh
   autonom replay --bundle bundle
   ```

You should see status `failed` and exit code 1, as for a failed `flow run`.

*Output of autonom replay and its exit code*

```
{
  "ok": true,
  "status": "failed",
  "run_id": "fr_…",
  "parent_attempt_id": "attempt_…",
  "strategy": "baseline",
  "target": null,
  "events": "…/flows/fr_…/events.ndjson"
}
exit 1
```

**What to look at.** `target` is `null` because no stop was requested. After a fix, the same command passing with exit code 0 shows that the failure is gone on this target.

### When the replay does not reach its step

**Goal:** tell a replay that went another way from a failure that no longer happens.

1. **Replay up to step 4 after the PIN field was renamed.** The script now shows the PIN field with the label `Code`, so step 2, which taps `PIN`, finds nothing.

   ```sh
   autonom replay --bundle bundle --to-step 4
   ```

2. **Replay up to the failing step after Welcome appears.** The script now shows Welcome, so step 6 passes where it failed in the source run.

   ```sh
   autonom replay --bundle bundle --to-step src_4d88cd3b8ce7.1
   ```

You should see status `failed` with exit code 1 for the first, and `flow_replay_step_not_reached` with exit code 2 for the second.

*Output of autonom replay when an earlier step fails*

```
{
  "ok": true,
  "status": "failed",
  "run_id": "fr_…",
  "parent_attempt_id": "attempt_…",
  "strategy": "baseline",
  "target": null,
  "events": "…/flows/fr_…/events.ndjson"
}
exit 1
```

*Output of autonom replay when the step now passes*

```
{"ok": false, "error_code": "flow_replay_step_not_reached", "error": "flow finished before runtime step 6 was reached", "hint": "Choose a step from the source run. Conditional or retry control flow may have diverged during replay.", "requested_step": 6, "requested_step_id": "src_4d88cd3b8ce7.1", "last_step": 6}
exit 2
```

**What to look at.** Both replays ran on the device. Exit code 1 with `--to-step` means the replay never got to its stop: the state differs from the source run before that step, so read the new run with [`agent inspect`](https://autonom.yatsuk.me/docs/agent-report/index.md) to find the step that failed. Exit code 2 with `last_step` means the flow ran to its end, and the step you asked for did not fail this time: on this target the failure no longer reproduces.

### Read the refusals

**Goal:** tell why a replay did not start, from the error code alone.

Each refusal below is one error object on stderr, with exit code 2, and nothing runs on the device.

*A checkpoint name in v0.36.1*

```
{"ok": false, "error_code": "flow_replay_step_not_reached", "error": "source attempt has no step or checkpoint 'pin-entered'"}
```

*The APP_PIN secret is not set*

```
{"ok": false, "error_code": "flow_secret_undefined", "error": "replay requires secret environment variables that are not set", "secret_names": ["APP_PIN"]}
```

*The flow file of a --run source has moved*

```
{"ok": false, "error_code": "replay_manifest_invalid", "error": "the pinned replay flow is unavailable", "hint": "Restore the source checkout or keep the flow beside the bundle.", "flow": "/tmp/autonom-replay/pin.yaml"}
```

*A file in the bundle was edited*

```
{"ok": false, "error_code": "report_integrity_failed", "error": "report bundle integrity verification failed", "failures": [{"path": "steps/src_4d88cd3b8ce7.1.json", "reason": "digest-mismatch"}]}
```

*No session is running*

```
{"ok": false, "error_code": "no_active_session", "error": "no active session", "hint": "Start one with 'autonom session start'."}
```

**What to look at.** [`flow_replay_step_not_reached`](https://autonom.yatsuk.me/docs/safety/index.md#flow_replay_step_not_reached) before anything ran means the source run has no such step. The help of v0.36.1 also accepts a checkpoint name, but its report records each checkpoint step under the name `checkpoint`, so `pin-entered` is not found; pass the checkpoint's index or step id instead. [`flow_secret_undefined`](https://autonom.yatsuk.me/docs/safety/index.md#flow_secret_undefined) names the variables to export. [`replay_manifest_invalid`](https://autonom.yatsuk.me/docs/safety/index.md#replay_manifest_invalid) means the flow file is gone; a bundle source avoids it, because the bundle keeps its own copy. [`report_integrity_failed`](https://autonom.yatsuk.me/docs/safety/index.md#report_integrity_failed) lists each file whose digest no longer matches. [`no_active_session`](https://autonom.yatsuk.me/docs/safety/index.md#no_active_session) asks for a session to replay on.

### 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, then two changed copies of it. Run ids, attempt ids, session ids and times differ on every run, and are shortened to … on the page; step ids stay the same, because the flow has an `id`. On macOS the moved flow's path starts with `/private/tmp`.

*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-replay
rm -rf $W && mkdir -p $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 > $W/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 > $W/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 > /dev/null
export APP_PIN=271828
# The source run fails at step 6; keep it as a report bundle
autonom flow run $W/pin.yaml --secret APP_PIN > $W/run.json
RUN=$(python3 -c 'import json, sys; print(json.load(open(sys.argv[1]))["run_id"])' $W/run.json)
autonom report bundle --run $RUN --out $W/bundle > /dev/null
# Rebuild the state at a step
autonom replay --bundle $W/bundle --to-step 4 | tee $W/replay.json
REPLAY=$(python3 -c 'import json, sys; print(json.load(open(sys.argv[1]))["run_id"])' $W/replay.json)
autonom agent export --run $REPLAY --out $W/replay-agent.json > /dev/null
python3 -c 'import json, sys; print(json.dumps(json.load(open(sys.argv[1]))["replay"], indent=2))' $W/replay-agent.json
# Stop on the failing step, by its id
autonom replay --bundle $W/bundle --to-step src_4d88cd3b8ce7.1
# Replay the whole run
autonom replay --bundle $W/bundle; echo "exit $?"
# When the replay does not reach its step
sed 's/content-desc="PIN"/content-desc="Code"/' $W/pin.xml > $W/code.xml
echo "{\"ui_dump\": \"$W/code.xml\"}" > $AUTONOM_FAKE_STATE
autonom replay --bundle $W/bundle --to-step 4; echo "exit $?"
sed 's/text="Enter your PIN"/text="Welcome"/' $W/pin.xml > $W/welcome.xml
echo "{\"ui_dump\": \"$W/welcome.xml\"}" > $AUTONOM_FAKE_STATE
autonom replay --bundle $W/bundle --to-step src_4d88cd3b8ce7.1; echo "exit $?"
echo "{\"ui_dump\": \"$W/pin.xml\"}" > $AUTONOM_FAKE_STATE
# Read the refusals
autonom replay --bundle $W/bundle --to-step pin-entered
(unset APP_PIN; autonom replay --bundle $W/bundle --to-step 4)
mv $W/pin.yaml $W/pin-moved.yaml
autonom replay --run $RUN --to-step 4
mv $W/pin-moved.yaml $W/pin.yaml
cp -R $W/bundle $W/edited && echo '{}' >> $W/edited/steps/src_4d88cd3b8ce7.1.json
autonom replay --bundle $W/edited --to-step 4
autonom session stop > /dev/null
autonom replay --bundle $W/bundle --to-step 4
```

## Good to know

- **Prefer a bundle as the source.** It is verified before anything runs and carries its own copy of the flow, so it still replays after the checkout moves on. A `--run` source needs the flow file at the path the run recorded.
- **Prefer step ids to indexes.** An index counts runtime steps, so a conditional or a retry can shift it. A step id is derived from the flow's `id`, or its path, and the step's line, column and command.
- **The replay checks the outcome, not only the position.** A step that passed in the source run must pass again before the replay stops there; if it fails, the replay exits 1. A step that failed must fail again; if it passes and the flow finishes, the replay exits 2 with `flow_replay_step_not_reached`.
- **Nothing is cleaned up for you.** The app keeps its data from earlier runs unless the flow's own steps reset it, and `onFlowComplete` does not run after an early stop. Stop the app or the session yourself when you are done looking.
- **Every replay starts from the first step.** Autonom v0.36.1 takes no device snapshots: on an emulator or Simulator a checkpoint is restored by replaying the flow up to it, and an Android phone cannot be snapshotted at all. [Capabilities](https://autonom.yatsuk.me/docs/capabilities/index.md) shows this as `checkpoint.restore`.
- **Secret values are not recorded, but the screen is.** The run records only the secret's name, so a replay needs the same variable exported, and the value is not written into the flow, the recorded command line or the steps' arguments. Screenshots, screen trees and logs keep whatever the screen showed: a field that displays the typed value puts it into the run, its bundle and its report. [Agent report](https://autonom.yatsuk.me/docs/agent-report/index.md#screen-evidence) shows where it ends up.

## Reference

`autonom replay` takes one source and an optional stop.

| Command | What it does |
| --- | --- |
| `autonom replay --bundle DIR` | Verifies the report bundle, then replays the copy of the flow stored in it. |
| `autonom replay --run ID` | Replays a run of the current session from its recorded flow file. Add `--session ID` to take the run from another session. |
| `autonom replay` | Replays the current session's latest run. |
| `--to-step STEP` | Stops after the step with this runtime index or stable step id, once it ends as it did in the source run. |
| `--session ID` | The session that holds the `--run` source. The replay still runs in the current session. |

The error codes, each with exit code 2. A replay that runs and fails before its stop is not one of them: it exits 1 with status `failed`.

| Error code | When |
| --- | --- |
| `flow_replay_step_not_reached` | `--to-step` names no step of the source run, so nothing ran. Or the flow ran every step without that step ending as it did in the source run, for example because a failure no longer happens. |
| `replay_manifest_invalid` | The flow file a `--run` source points at is gone. |
| `flow_secret_undefined` | A secret the source run used is not set in your environment. |
| `report_integrity_failed` | The bundle has no manifest, or a file in it no longer matches its digest. |
| `no_active_session` | No session is running to replay on. |

## Next steps

You can rebuild the state of any recorded run and stop where you need to look.

- [Agent report](https://autonom.yatsuk.me/docs/agent-report/index.md): Read a run's steps, failure and evidence as compact JSON.
- [Flows](https://autonom.yatsuk.me/docs/flows/index.md): Write the flow a replay runs again.
- [Read and drive the screen](https://autonom.yatsuk.me/docs/screen/index.md): Look at the screen the replay left behind.
- [Capabilities](https://autonom.yatsuk.me/docs/capabilities/index.md): Check what a target can restore before you rely on it.