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 autonom replay --bundle <dir> --to-step 4

Needs a session on one target · a flow run

How it works

A replay starts from a recorded run. --bundle names a finalized report bundle, 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.

    autonom replay --bundle bundle --to-step 4

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

{ "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:

{ "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 shows where to read it.

    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.

{ "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. 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.autonom replay --bundle bundle

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

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

    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.

    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.

{ "ok": true, "status": "failed", "run_id": "fr_…", "parent_attempt_id": "attempt_…", "strategy": "baseline", "target": null, "events": "…/flows/fr_…/events.ndjson"}exit 1
{"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 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.

{"ok": false, "error_code": "flow_replay_step_not_reached", "error": "source attempt has no step or checkpoint 'pin-entered'"}
{"ok": false, "error_code": "flow_secret_undefined", "error": "replay requires secret environment variables that are not set", "secret_names": ["APP_PIN"]}
{"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"}
{"ok": false, "error_code": "report_integrity_failed", "error": "report bundle integrity verification failed", "failures": [{"path": "steps/src_4d88cd3b8ce7.1.json", "reason": "digest-mismatch"}]}
{"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 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 names the variables to export. replay_manifest_invalid means the flow file is gone; a bundle source avoids it, because the bundle keeps its own copy. report_integrity_failed lists each file whose digest no longer matches. 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.

# autonom below runs this checkout against Autonom's test emulator, showing a PIN screen the script writes.S=$PWD W=/tmp/autonom-replayrm -rf $W && mkdir -p $Wexport AUTONOM_HOME=$W/.autonom AUTONOM_FAKE_STATE=$W/device.jsonautonom() { 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>XMLecho "{\"ui_dump\": \"$W/pin.xml\"}" > $AUTONOM_FAKE_STATEcat > $W/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 > /dev/nullexport APP_PIN=271828# The source run fails at step 6; keep it as a report bundleautonom flow run $W/pin.yaml --secret APP_PIN > $W/run.jsonRUN=$(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 stepautonom replay --bundle $W/bundle --to-step 4 | tee $W/replay.jsonREPLAY=$(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/nullpython3 -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 idautonom replay --bundle $W/bundle --to-step src_4d88cd3b8ce7.1# Replay the whole runautonom replay --bundle $W/bundle; echo "exit $?"# When the replay does not reach its stepsed 's/content-desc="PIN"/content-desc="Code"/' $W/pin.xml > $W/code.xmlecho "{\"ui_dump\": \"$W/code.xml\"}" > $AUTONOM_FAKE_STATEautonom replay --bundle $W/bundle --to-step 4; echo "exit $?"sed 's/text="Enter your PIN"/text="Welcome"/' $W/pin.xml > $W/welcome.xmlecho "{\"ui_dump\": \"$W/welcome.xml\"}" > $AUTONOM_FAKE_STATEautonom replay --bundle $W/bundle --to-step src_4d88cd3b8ce7.1; echo "exit $?"echo "{\"ui_dump\": \"$W/pin.xml\"}" > $AUTONOM_FAKE_STATE# Read the refusalsautonom 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.yamlautonom replay --run $RUN --to-step 4mv $W/pin-moved.yaml $W/pin.yamlcp -R $W/bundle $W/edited && echo '{}' >> $W/edited/steps/src_4d88cd3b8ce7.1.jsonautonom replay --bundle $W/edited --to-step 4autonom session stop > /dev/nullautonom 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 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 shows where it ends up.

Reference

autonom replay takes one source and an optional stop.

CommandWhat it does
autonom replay --bundle DIRVerifies the report bundle, then replays the copy of the flow stored in it.
autonom replay --run IDReplays a run of the current session from its recorded flow file. Add --session ID to take the run from another session.
autonom replayReplays the current session's latest run.
--to-step STEPStops after the step with this runtime index or stable step id, once it ends as it did in the source run.
--session IDThe 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 codeWhen
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_invalidThe flow file a --run source points at is gone.
flow_secret_undefinedA secret the source run used is not set in your environment.
report_integrity_failedThe bundle has no manifest, or a file in it no longer matches its digest.
no_active_sessionNo session is running to replay on.

Next steps

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

Search documentation

Type to find a guide.

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