From 7ab299f0367c43eb5ab72975ea359a857385bdc4 Mon Sep 17 00:00:00 2001
From: Alexbeav <7005125+Alexbeav@users.noreply.github.com>
Date: Wed, 4 Nov 2026 11:18:57 +0200
Subject: [PATCH] feat: add deterministic input replays

---
 CMakeLists.txt                |  33 ++-
 README.md                     |   3 +
 corelink/core_link.cpp        |  33 +++
 corelink/core_link.hpp        |   9 +-
 corelink/link_protocol.hpp    |  20 +-
 corelink/link_test_main.cpp   |  51 ++++-
 docs/BOOT_ROUTES.md           | 128 +++++++++++
 docs/CORE_LINK.md             |  11 +-
 docs/CORE_RUNNER.md           |   4 +
 docs/OVERLAY.md               |   7 +-
 runner/host_session.cpp       |   9 +-
 runner/host_session.hpp       |   4 +
 runner/route.cpp              | 419 ++++++++++++++++++++++++++++++++++
 runner/route.hpp              |  89 ++++++++
 runner/runner_link.cpp        | 110 ++++++++-
 runner/runner_link.hpp        |   2 +
 runner/runner_main.cpp        |  55 ++++-
 scripts/route_recover.py      |  72 ++++++
 tests/route_anchor_test.cmake |  35 +++
 tests/route_contract_test.cpp |  99 ++++++++
 tests/route_recover_test.py   |  49 ++++
 tests/route_test.cmake        |  66 ++++++
 tests/route_watch_test.cmake  |  56 +++++
 23 files changed, 1347 insertions(+), 17 deletions(-)
 create mode 100644 docs/BOOT_ROUTES.md
 create mode 100644 runner/route.cpp
 create mode 100644 runner/route.hpp
 create mode 100644 scripts/route_recover.py
 create mode 100644 tests/route_anchor_test.cmake
 create mode 100644 tests/route_contract_test.cpp
 create mode 100644 tests/route_recover_test.py
 create mode 100644 tests/route_test.cmake
 create mode 100644 tests/route_watch_test.cmake

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 0e0fa19..c257b09 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -81,6 +81,8 @@ if(WIN32)
 endif()
 
 add_library(retro_state STATIC state/state_envelope.cpp)
+add_library(retro_route STATIC runner/route.cpp)
+target_link_libraries(retro_route PUBLIC retro_core_support retro_corelink)
 target_include_directories(retro_state PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/state)
 target_link_libraries(retro_state PUBLIC retro_core_support)
 
@@ -119,8 +121,35 @@ if(RETRO_RUNTIME_TOOLS)
     )
     add_executable(retro-gpu-host-test tests/gpu_host_test.cpp runner/host_session.cpp)
     target_include_directories(retro-gpu-host-test PRIVATE runner)
-    target_link_libraries(retro-gpu-host-test PRIVATE retro_core_support)
+    target_link_libraries(retro-gpu-host-test PRIVATE retro_core_support retro_route)
     add_test(NAME gpu_host_contract COMMAND retro-gpu-host-test)
+    add_executable(retro-route-test tests/route_contract_test.cpp runner/host_session.cpp)
+    target_include_directories(retro-route-test PRIVATE runner)
+    target_link_libraries(retro-route-test PRIVATE retro_route)
+    add_test(NAME route_input_roundtrip COMMAND retro-route-test ${CMAKE_CURRENT_BINARY_DIR}/route-contract)
+    add_test(NAME runner_routes COMMAND ${CMAKE_COMMAND}
+        -DRUNNER=$<TARGET_FILE:retro-core-runner> -DCORE=$<TARGET_FILE:rcore_fake_core>
+        -DLINK=$<TARGET_FILE:retro-core-link-test> -DOUT=${CMAKE_CURRENT_BINARY_DIR}/route-integration
+        -P ${CMAKE_CURRENT_SOURCE_DIR}/tests/route_test.cmake)
+    add_test(NAME route_watch COMMAND ${CMAKE_COMMAND}
+        -DRUNNER=$<TARGET_FILE:retro-core-runner> -DCORE=$<TARGET_FILE:rcore_fake_core>
+        -DLINK=$<TARGET_FILE:retro-core-link-test> -DOUT=${CMAKE_CURRENT_BINARY_DIR}/route-watch
+        -P ${CMAKE_CURRENT_SOURCE_DIR}/tests/route_watch_test.cmake)
+    add_test(NAME route_anchor COMMAND ${CMAKE_COMMAND}
+        -DRUNNER=$<TARGET_FILE:retro-core-runner> -DCORE=$<TARGET_FILE:rcore_fake_core>
+        -DLINK=$<TARGET_FILE:retro-core-link-test> -DOUT=${CMAKE_CURRENT_BINARY_DIR}/route-anchor
+        -P ${CMAKE_CURRENT_SOURCE_DIR}/tests/route_anchor_test.cmake)
+    find_package(Python3 COMPONENTS Interpreter QUIET)
+    if(Python3_Interpreter_FOUND)
+        file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/route-tmp)
+        add_test(NAME route_recovery COMMAND ${Python3_EXECUTABLE} -I -B
+            ${CMAKE_CURRENT_SOURCE_DIR}/tests/route_recover_test.py)
+        set_tests_properties(route_recovery PROPERTIES ENVIRONMENT
+            "TEMP=${CMAKE_CURRENT_BINARY_DIR}/route-tmp;TMP=${CMAKE_CURRENT_BINARY_DIR}/route-tmp;PYTHONDONTWRITEBYTECODE=1")
+    else()
+        add_test(NAME route_recovery COMMAND ${CMAKE_COMMAND} -E echo "SKIP: Python3 is unavailable")
+        set_tests_properties(route_recovery PROPERTIES SKIP_REGULAR_EXPRESSION "SKIP:")
+    endif()
     # Netplay (runner/net_session.hpp): recomp-net's episode driver and UDP
     # transport, compiled in from a checkout when one is named. Without it the
     # runner answers `netplay 0` and refuses --net-*.
@@ -172,7 +201,7 @@ if(RETRO_RUNTIME_TOOLS)
     endif()
     # Threads: the savestate keeper hashes content off the core thread.
     find_package(Threads REQUIRED)
-    target_link_libraries(retro-core-runner PRIVATE retro_core_support retro_corelink retro_state
+    target_link_libraries(retro-core-runner PRIVATE retro_core_support retro_corelink retro_state retro_route
                           Threads::Threads)
     target_include_directories(retro-core-runner PRIVATE ${CMAKE_CURRENT_BINARY_DIR}/generated)
     if(_sdl)
diff --git a/README.md b/README.md
index 9af78e3..22580ab 100644
--- a/README.md
+++ b/README.md
@@ -90,3 +90,6 @@ The runner can therefore update separately from hosts and cores:
 
 This repository was split out of Retro Launcher on 2026-09-25, with its
 history.
+
+See [Input replays](docs/BOOT_ROUTES.md) for recording, anchored playback,
+headless verification and link recording controls.
diff --git a/corelink/core_link.cpp b/corelink/core_link.cpp
index 3366be3..47163a9 100644
--- a/corelink/core_link.cpp
+++ b/corelink/core_link.cpp
@@ -16,6 +16,13 @@ CoreLink::~CoreLink() {
     channel_.close();
 }
 
+bool CoreLink::restart(const LaunchSpec& spec, std::string* error) {
+    stop();
+    this->~CoreLink();
+    new (this) CoreLink();
+    return start(spec,error);
+}
+
 bool CoreLink::start(const LaunchSpec& spec, std::string* error) {
     auto fail = [&](const std::string& m) {
         if (error) *error = m;
@@ -256,6 +263,13 @@ void CoreLink::handle_packet(const std::vector<unsigned char>& buf,
             if (as_msg(buf, m)) exit_reason_ = m.reason;
             break;
         }
+        case Msg::ReplayStatus: {
+            ReplayStatusMsg m{};
+            if (!as_msg(buf,m)) break;
+            m.path[sizeof m.path-1]=0; m.detail[sizeof m.detail-1]=0;
+            replay_status_=m; replay_pending_=false;
+            break;
+        }
         case Msg::StateDone: {
             StateDoneMsg m{};
             if (!as_msg(buf, m) || !state_pending_) break;
@@ -300,6 +314,20 @@ bool CoreLink::states_supported() const {
            (identity_.capabilities & RCORE_CAP_SAVESTATE);
 }
 
+bool CoreLink::replays_supported() const {
+    return states_supported() && link_has_replays(identity_.protocol_minor);
+}
+bool CoreLink::request_recording(bool record, const fs::path& path) {
+    if (!replays_supported() || !can_grant()) return false;
+    ReplayControlMsg m{}; m.h.type=Msg::ReplayControl; m.record=record ? 1 : 0;
+    const auto p=path_utf8(path);
+    if (p.size()>=sizeof m.path) return false;
+    std::memcpy(m.path,p.c_str(),p.size()+1);
+    if (!send_msg(channel_,m)) return false;
+    replay_pending_=true;
+    return true;
+}
+
 bool CoreLink::request_state(Msg type, const fs::path& path) {
     if (!can_request_state()) return false;
     StateRequestMsg m{};
@@ -425,6 +453,11 @@ void CoreLink::on_ended(int code) {
     exit_code_ = code;
     state_ = LinkState::Ended;
     outstanding_ = 0;
+    if (replay_pending_) {
+        replay_pending_=false;
+        replay_status_.state=ReplayState::Failed;
+        std::strcpy(replay_status_.detail,"the runner ended before it answered");
+    }
     if (state_pending_) {
         StateResult r = state_request_;
         r.ok = false;
diff --git a/corelink/core_link.hpp b/corelink/core_link.hpp
index cebebea..74121dd 100644
--- a/corelink/core_link.hpp
+++ b/corelink/core_link.hpp
@@ -143,6 +143,7 @@ class CoreLink {
     ~CoreLink();
 
     bool start(const LaunchSpec& spec, std::string* error);
+    bool restart(const LaunchSpec& spec, std::string* error);
 
     // Handles every message waiting (up to timeout_ms for the first).
     void pump(int timeout_ms = 0);
@@ -154,7 +155,7 @@ class CoreLink {
     // time; can_grant() says whether the previous one has finished. Nothing is
     // granted while a savestate request is outstanding.
     bool can_grant() const {
-        return state_ == LinkState::Ready && outstanding_ == 0 && !state_pending_;
+        return state_ == LinkState::Ready && outstanding_ == 0 && !state_pending_ && !replay_pending_;
     }
     // Available physical pixels before letterboxing; zeros when unknown.
     bool grant(const rcore_pad pads[RCORE_MAX_SEATS], std::uint32_t width = 0,
@@ -175,6 +176,10 @@ class CoreLink {
     // The answer, once, when it has arrived. A runner that ends first
     // answers with a failure naming that.
     std::optional<StateResult> take_state_result();
+    bool replays_supported() const;
+    bool request_recording(bool record, const fs::path& path = {});
+    bool replay_pending() const { return replay_pending_; }
+    const ReplayStatusMsg& replay_status() const { return replay_status_; }
 
     // Accessory data (link 2.1, rcore rev 7; docs/CORE_ABI.md "Accessory
     // data"). send_accessory() queues one whole message for the accessory at
@@ -249,6 +254,8 @@ class CoreLink {
     std::uint32_t front_ = 0; // the triple buffer's initial front slot
     bool have_frame_ = false;
     bool state_pending_ = false;
+    bool replay_pending_ = false;
+    ReplayStatusMsg replay_status_{};
     StateResult state_request_;
     std::optional<StateResult> state_result_;
     std::deque<AccessoryNotify> notifies_;
diff --git a/corelink/link_protocol.hpp b/corelink/link_protocol.hpp
index eaba1aa..01c9b86 100644
--- a/corelink/link_protocol.hpp
+++ b/corelink/link_protocol.hpp
@@ -45,7 +45,9 @@ constexpr std::uint32_t kProtocolMajor = 2;
 // reads a 2.1 runner's with both fields zero.
 // 2.3: Grant appends the available drawable pixel area (rcore rev 9).
 // 2.4: optional core-owned GPU rings, native handle transfer and release events.
-constexpr std::uint32_t kProtocolMinor = 4;
+// 2.5: between-frame replay recording controls and authoritative status.
+constexpr std::uint32_t kProtocolMinor = 5;
+constexpr bool link_has_replays(std::uint32_t peer_minor) { return peer_minor >= 5; }
 constexpr bool link_has_gpu_frames(std::uint32_t peer_minor) {
     return kProtocolMajor > 2 || peer_minor >= 4;
 }
@@ -154,6 +156,7 @@ enum class Msg : std::uint32_t {
     GpuRing = 10,        // 2.4: metadata plus 3 native handles per image
     GpuFrame = 11,       // accepted GPU picture, before its FrameDone
     GpuUnregister = 12,  // retire a generation after all GPU users finish
+    ReplayStatus = 13,
     // hub -> runner
     SavesFilled = 64, // every region filled from its file; the seats at power-on
     Grant = 65,       // run exactly one frame, with these pads
@@ -164,6 +167,7 @@ enum class Msg : std::uint32_t {
     GpuCapabilities = 70, // 2.4: once after Hello, before core init
     GpuStatus = 71,       // resource ownership events, not capabilities
     StateThumbnail = 72, // 2.4: displayed image observer for the next save
+    ReplayControl = 73,
 };
 
 struct MsgHeader {
@@ -171,6 +175,20 @@ struct MsgHeader {
     std::uint32_t size; // whole packet, header included
 };
 
+enum class ReplayState : std::uint32_t { Idle, Recording, Saved, Playing, TakenOver, Failed, Complete, Stopped };
+struct ReplayControlMsg {
+    MsgHeader h;
+    std::uint32_t record; // 1: start at a restored anchor, 0: stop recording
+    char path[4096]; // exclusive destination, never overwrite
+};
+struct ReplayStatusMsg {
+    MsgHeader h;
+    ReplayState state;
+    std::uint64_t fields;
+    char path[4096];
+    char detail[512];
+};
+
 struct GpuCapabilitiesMsg {
     MsgHeader h;
     rcore_gpu_capabilities caps;
diff --git a/corelink/link_test_main.cpp b/corelink/link_test_main.cpp
index 646f5b5..091fc75 100644
--- a/corelink/link_test_main.cpp
+++ b/corelink/link_test_main.cpp
@@ -39,6 +39,9 @@
 using namespace retro::corelink;
 
 namespace {
+constexpr std::uint32_t kLeft = 1u << 20, kRight = 1u << 21,
+                        kUp = 1u << 22, kDown = 1u << 23;
+constexpr std::uint32_t kStick = kLeft | kRight | kUp | kDown;
 
 [[noreturn]] void die(const std::string& m) {
     std::fprintf(stderr, "retro-core-link-test: %s\n", m.c_str());
@@ -63,6 +66,10 @@ std::uint32_t script_buttons(const std::string& s) {
         else if (t == "ddown") b |= RCORE_PAD_DPAD_DOWN;
         else if (t == "dleft") b |= RCORE_PAD_DPAD_LEFT;
         else if (t == "dright") b |= RCORE_PAD_DPAD_RIGHT;
+        else if (t == "left") b |= kLeft;
+        else if (t == "right") b |= kRight;
+        else if (t == "up") b |= kUp;
+        else if (t == "down") b |= kDown;
         else die("--input-script: unknown button '" + t + "'");
         if (plus == std::string::npos) break;
         start = plus + 1;
@@ -81,6 +88,8 @@ int main(int argc, char** argv) {
     std::uint64_t frames = 60;
     bool seat0 = true;
     bool presentation_test = false;
+    bool expect_route_end = false;
+    std::string restart_route;
     std::vector<std::pair<std::uint64_t, std::uint32_t>> script;
     struct StateOp {
         std::uint64_t at;
@@ -88,6 +97,7 @@ int main(int argc, char** argv) {
         std::string path;
     };
     std::vector<StateOp> state_ops;
+    std::vector<StateOp> record_ops;
     struct AccessorySend {
         std::uint64_t before_frame;
         std::uint32_t seat, slot;
@@ -117,6 +127,7 @@ int main(int argc, char** argv) {
                         v.game_package, v.describe, v.accessory_data);
             return 0;
         } else if (a == "--runner") spec.runner = utf8_path(val());
+        else if (a == "--restart-route") restart_route=val();
         else if (a == "--core") spec.core = utf8_path(val());
         else if (a == "--rom") spec.rom = val();
         else if (a == "--package") spec.package = val();
@@ -156,6 +167,7 @@ int main(int argc, char** argv) {
         else if (a == "--strict") spec.strict = true;
         else if (a == "--no-seats") seat0 = false;
         else if (a == "--presentation-test") presentation_test = true;
+        else if (a == "--expect-route-end") expect_route_end = true;
         else if (a == "--opt") {
             const std::string kv = val();
             const auto eq = kv.find('=');
@@ -175,6 +187,12 @@ int main(int argc, char** argv) {
                 if (comma == std::string::npos) break;
                 start = comma + 1;
             }
+        } else if (a == "--record-start-at") {
+            const auto v=val(); const auto colon=v.find(':');
+            if (colon==std::string::npos) die("--record-start-at K:PATH");
+            record_ops.push_back({std::strtoull(v.substr(0,colon).c_str(),nullptr,10),true,v.substr(colon+1)});
+        } else if (a == "--record-stop-at") {
+            record_ops.push_back({std::strtoull(val().c_str(),nullptr,10),false,{}});
         } else if (a == "--state-save-at") {
             state_op(val(), true);
         } else if (a == "--state-load-at") {
@@ -208,6 +226,14 @@ int main(int argc, char** argv) {
             (link.exit_reason().empty() ? "" : ": " + link.exit_reason()) + "); see " +
             link.runner_log().string());
     }
+    if (!restart_route.empty()) {
+        auto replay=spec;
+        replay.env.push_back("RETRO_PLAY_ROUTE="+restart_route);
+        replay.env.push_back("RETRO_ROUTE_TAKEOVER=1");
+        if (!link.restart(replay,&err)) die(err);
+        while (link.state()==LinkState::Starting) link.pump(100);
+        if (link.state()!=LinkState::Ready) die("selected replay refused: "+link.exit_reason());
+    }
     const CoreIdentity& id = link.identity();
     std::printf("link: %s %s sha256 %s draft %u%s\n", id.core_id.c_str(), id.core_version.c_str(),
                 id.sha256.c_str(), id.draft_revision, id.engine_dirty ? " (engine dirty)" : "");
@@ -243,18 +269,39 @@ int main(int argc, char** argv) {
             for (const auto& [at, buttons] : script) {
                 if (at <= k) pads[0].buttons = buttons;
             }
+            const auto held = pads[0].buttons;
+            pads[0].buttons &= ~kStick;
+            pads[0].axes[RCORE_AXIS_LX] = held & kLeft ? -32767 : held & kRight ? 32767 : 0;
+            pads[0].axes[RCORE_AXIS_LY] = held & kUp ? 32767 : held & kDown ? -32767 : 0;
         }
         // Fixture exercises resize, unavailable/minimized, then recovery.
         const std::uint32_t pw = presentation_test && k != 3 ? (k == 1 ? 1280 : 2560) : 0;
         const std::uint32_t ph = presentation_test && k != 3 ? (k == 1 ? 720 : 1080) : 0;
-        if (!link.grant(pads, pw, ph)) die("grant " + std::to_string(k) + " refused");
+        if (!link.grant(pads, pw, ph)) {
+            if (expect_route_end) {
+                link.pump(100);
+                if (link.state()==LinkState::Ended && !link.exit_code()) break;
+            }
+            die("grant " + std::to_string(k) + " refused");
+        }
         while (link.state() == LinkState::Ready && link.frames_done() < k) link.pump(100);
         print_notifies();
-        if (link.state() != LinkState::Ready) ok = false;
+        const bool clean_route_end = expect_route_end && link.state()==LinkState::Ended && !link.exit_code();
+        if (link.state() != LinkState::Ready && !clean_route_end) ok = false;
         link.take_frame();
         std::int16_t sink[4096];
         while (link.drain_audio(sink, 2048)) {
         }
+        if (clean_route_end) break;
+        for (const StateOp& op : record_ops) {
+            if (op.at!=k || !ok) continue;
+            if (!link.request_recording(op.save,utf8_path(op.path))) die("replay request refused");
+            while (link.replay_pending() && link.state()==LinkState::Ready) link.pump(100);
+            const auto& status=link.replay_status();
+            std::printf("replay: %s at %llu state %u fields %llu %s\n",op.save ? "start" : "stop",
+                static_cast<unsigned long long>(k),unsigned(status.state),
+                static_cast<unsigned long long>(status.fields),status.detail);
+        }
         for (const StateOp& op : state_ops) {
             if (op.at != k || !ok) continue;
             const bool sent = op.save ? link.request_save_state(utf8_path(op.path))
diff --git a/docs/BOOT_ROUTES.md b/docs/BOOT_ROUTES.md
new file mode 100644
index 0000000..4c861eb
--- /dev/null
+++ b/docs/BOOT_ROUTES.md
@@ -0,0 +1,128 @@
+# Input replays
+
+Input replays record a play session from a cold boot or a restored mid-game
+anchor and replay it in a fresh runner process. `--version` reports `boot_routes 1` in a runner with this feature.
+No core ABI change is required.
+
+The recorder runs in `HostSession`, on the same input callbacks that headless
+and link sessions use. It records the order of actual `input_get` calls, all
+eight seats, connection flags, buttons and six signed axes. It also records
+host clock calls. Playback supplies those values and refuses a changed
+callback sequence. It does not sample desktop input on a timer.
+
+Each completed field has a state checkpoint, the last CPU picture hash and a
+hash of the delivered PCM samples. Cores without public state hashes have
+picture/audio checks only. A mark also writes a PPM picture. GPU-only
+presentation has no CPU picture to hash. Use software rendering for a route
+that requires exact pictures across these two runner modes.
+
+The file contains the initial save regions and these identities:
+
+- The ROM, core, runner, game package and title `game.toml`.
+- The core id and version, strict mode and every resolved option.
+- The process's `N64LLE_` environment variables.
+
+The initial saves are restored after load and before the first field.
+Playback does not persist them to the recording's original save files.
+Routes contain private player data. Keep them with private game inputs.
+
+## Record and replay
+
+`--record-route <new-file>` records headless input. `--route-mark FIELD:NAME`
+adds a named checkpoint picture. The existing `--input-script` can supply
+buttons and stick directions for scripted recording. A route file is never
+overwritten.
+
+For ordinary play through a hub, set `RETRO_RECORD_ROUTE` to a new absolute
+route path and select this runner through the hub's `--runner` option. The
+runner records the pads that the hub grants. Quit the game normally to seal
+the movie. No launcher change is required. The headless link test exercises
+the same path without a window.
+
+`--play-route <file>` runs the movie headlessly or over the hub link. Supply the same ROM,
+package, title directory and resolved configuration. Playback ignores
+`--frames` and runs the movie's field count. It refuses simultaneous input
+scripts, netplay, loaded states and accessories. Accessories need
+their own input/state contract before they can join this format.
+
+A compatible frontend uses link 2.5 `ReplayControl` to start or stop recording
+between frames. Start captures and restores a core snapshot before recording
+inputs. The optional `A` record stores that anchor and its public digest;
+boot movies remain readable. Fresh playback restores initial saves and the
+anchor before the first field, and checks its digest immediately. A core must
+serialize all replay-relevant state for anchored playback to work. A core that
+only supports same-process restores is insufficient; playback refuses or
+reports divergence instead of weakening checkpoints. Anchors are limited to
+64 MiB and the entire movie to 256 MiB.
+
+`ReplayStatus` confirms Recording, Saved, Playing, TakenOver or Failed. Hosts
+must wait for the response before granting another frame and display recording
+status only after confirmation. Controls are unavailable with older peers,
+netplay, accessories, or an active playback. Existing-file destinations refuse.
+The frontend can list sealed `.route` files and start playback in a fresh runner
+using `RETRO_PLAY_ROUTE`. `RETRO_ROUTE_VERDICT` selects the result path.
+The hub supplies presentation and pacing. Normal completion ends the runner;
+Quit writes `stopped`. Playback uses private save memory, leaving the frontend's
+persistent save mappings alone, including after takeover.
+
+Watch enables `--route-takeover` through `RETRO_ROUTE_TAKEOVER=1`. First neutral
+live pads arm takeover. A later button or stick movement ends replay input
+authority at the next field, without a core reset. The verdict is `taken_over`
+and records that field. Checks stop there. The live grants then drive the game
+normally. The frontend's mapped input/deadzone is retained, with its raw-axis
+fallback of 8000 as a residual-noise guard for takeover detection only.
+Headless replay has no takeover path.
+
+## Results and core updates
+
+`<out>/route-verdict.json` records `recorded`, `in_sync`, `diverged`, `failed`,
+`stopped` or `taken_over`.
+`--route-verdict <path>` selects another result file. Exit 5 means that a
+checkpoint or callback sequence diverged. Exit 2 means that admission failed.
+The first differing field is recorded. A picture mismatch also writes the
+actual CPU picture. An identical final picture alone is not a passing replay.
+
+Default playback requires the exact recorded core and runner binaries.
+The Watch extension can use `--route-runner-reference` (or
+`RETRO_ROUTE_RUNNER_REFERENCE`) to name the preserved recording runner. Its
+hash must match the movie, and the verdict names both recorded and current
+runner hashes. Other identities and all checked checkpoints remain exact.
+`--route-allow-core-change` explicitly compares another core. The ROM, package,
+runner, existing options and expected checkpoints remain unchanged. A new
+option is accepted only at the new core's declared default, and the verdict
+lists it under `added_default_options`. A removed option or a changed
+recorded option still refuses. A passing comparison describes that route and
+configuration, not every game or future core version.
+
+## Interrupted recording
+
+The active file is `<route>.partial`. The writer flushes each complete field.
+A normal link Quit or headless Ctrl+C seals completed fields in the requested
+route file. A fault leaves the partial file. An unsealed partial file refuses
+normal playback.
+
+`scripts/route_recover.py` copies the complete field prefix into a new sealed
+file. It does not overwrite the source or an existing output. The normal
+runner still validates the recovered file before execution. For example:
+
+```powershell
+& python .\scripts\route_recover.py 'C:\private\route.partial' 'C:\private\recovered.route'
+```
+
+The format limit is 256 MiB. Recording and parsing have bounded callback,
+image and audio sizes. The checksum detects accidental file damage. It is
+not a signature that authenticates another person's route.
+
+## Validation
+
+`route_input_roundtrip` checks all seats and axes, clocks, initial-save
+restoration, state/picture/audio replay and explicit new-default handling.
+`runner_routes` checks new-process playback, link-to-headless playback,
+identity refusal, truncation, malformed field order and first divergence.
+`tests/route_recover_test.py` checks complete-prefix recovery and refusals
+without game data. The existing Runtime suite remains applicable.
+
+`route_anchor` checks recording controls, a restored mid-game anchor,
+fresh-process playback and protection of an existing movie. Runtime tests use
+synthetic cores; title/core-specific file-state replay must be qualified
+separately. They do not establish visual UI or physical-controller acceptance.
diff --git a/docs/CORE_LINK.md b/docs/CORE_LINK.md
index c91a395..e1cd1f7 100644
--- a/docs/CORE_LINK.md
+++ b/docs/CORE_LINK.md
@@ -209,9 +209,9 @@ package; `--title-dir` then defaults to the shim's directory.
   `game_package 1`, the window shows the error and the hub exits 1. A background
   runtime update applies from the next launch, never mid-session.
 - **Menu:** Esc or F1, or L3 + R3 on a pad, open the paused quick menu (Resume,
-  Save states, Show FPS, Volume, Close game). F11 toggles fullscreen.
+  Save states, Replays, Show FPS, Volume, Close game). Alt+Enter toggles fullscreen.
 - **Overlay** (`OVERLAY.md`): F3 FPS, Tab (held) turbo, +/- volume, F7 save
-  states by default. Since 2026-09-27 the hub's hotkeys are the player's to
+  states/replays and F11 recording by default (see `BOOT_ROUTES.md`). Since 2026-09-27 the hub's hotkeys are the player's to
   bind (Retro-Launcher's settings page, `play.ini` `[keys]` / `[combos]`), and
   its pad shortcuts are `Function + <button>`, Function being an input the
   player assigns per controller (Back by default: some USB pads report Select
@@ -264,3 +264,10 @@ All on `pokemonstadium_core.so` built clean from n64lle `ffa84cfc`.
   path exists (2.1); the hub's recognizer and its pak dropdown do not yet.
 - **The hub on macOS and Windows.** Retro Launcher builds `hub_play.cpp` only on
   Linux.
+
+## Replay controls (2.5)
+
+`ReplayControl` starts/stops anchored recording between grants. `ReplayStatus`
+confirms the actual state and destination; a host waits for its answer before
+granting another field. See [Input replays](BOOT_ROUTES.md) for the format,
+identity checks, private saves and fresh-process playback contract.
diff --git a/docs/CORE_RUNNER.md b/docs/CORE_RUNNER.md
index 66af6da..f8b3588 100644
--- a/docs/CORE_RUNNER.md
+++ b/docs/CORE_RUNNER.md
@@ -4,6 +4,10 @@ The child process that runs an rcore core for the Retro frontend. Design:
 `HOST_LIFECYCLE.md` (process model, states) and `CORE_ABI.md` (the contract).
 This page covers what exists and how it is checked.
 
+[Boot routes](BOOT_ROUTES.md) cover player input recording, fresh-process
+playback, private initial saves and checkpoint verdicts. This is separate
+from the same-process `--replay-at` save/restore probe below.
+
 **Status, 2026-09-25:** two modes. **Headless** is described here. **Link**
 (`--link`) is how the hub runs a core in its own window; see `CORE_LINK.md`.
 
diff --git a/docs/OVERLAY.md b/docs/OVERLAY.md
index d358521..d7982e5 100644
--- a/docs/OVERLAY.md
+++ b/docs/OVERLAY.md
@@ -175,7 +175,7 @@ These are the hub's choices, listed here because every core gets them:
 | F3 | show / hide FPS (also a setting: "Show FPS", saved in `<data_dir>/play.ini`) |
 | Tab (held) | turbo; sound is dropped while it runs |
 | + / - (`=` `-` or keypad) | volume, 10% steps, meter on the right (saved in `play.ini`) |
-| F7, or SELECT + R1 (Retro-Launcher's hub: Function + R1, rebindable) | save states |
+| F7, or SELECT + R1 (Retro-Launcher's hub: Function + R1, rebindable) | save states / replays |
 | Esc, F1 (Retro-Launcher's hub: also L3 + R3 or Function + Start; never Guide, which Steam keeps) | the pause menu, which also has Save states, Show FPS and Volume |
 
 - The recomp-ui family binds FPS to F. In the hub F drives C-Left (the TFGH
@@ -216,3 +216,8 @@ These are the hub's choices, listed here because every core gets them:
 - **Not checked:** a real screen, a real controller (the SELECT + R1 chord,
   stick repeat), sound and volume by ear, and the settings page's new section
   as drawn. Those are Alex's to judge.
+
+The hub adds a Replays page to the F7 save menu. F11 starts/stops anchored
+recording; a red REC indicator appears only after runner confirmation. Fullscreen
+is Alt+Enter. Playback, export copies and confirmed deletion are available on
+the Replays page. See [Input replays](BOOT_ROUTES.md).
diff --git a/runner/host_session.cpp b/runner/host_session.cpp
index 9731d67..fb26407 100644
--- a/runner/host_session.cpp
+++ b/runner/host_session.cpp
@@ -1,4 +1,5 @@
 #include "host_session.hpp"
+#include "route.hpp"
 
 #include <chrono>
 #include <cstdio>
@@ -101,6 +102,7 @@ std::uint32_t HostSession::h_gpu_released(void* ctx, std::uint64_t generation,
 std::uint32_t HostSession::h_gpu_frame(void* ctx, const rcore_gpu_frame* frame) {
     if (!frame || frame->struct_size < sizeof *frame || !frame->generation ||
         frame->image_index >= RCORE_GPU_MAX_IMAGES) return 0;
+    if (self(ctx)->route_) self(ctx)->route_->gpu_video();
     return self(ctx)->sink_.gpu_frame(*frame) ? 1u : 0u;
 }
 
@@ -240,10 +242,12 @@ void HostSession::h_report(void* ctx, const rcore_event* e) {
 }
 
 void HostSession::h_video(void* ctx, const rcore_frame* f) {
+    if (f && self(ctx)->route_) self(ctx)->route_->video(*f);
     if (f) self(ctx)->sink_.frame(*f);
 }
 
 void HostSession::h_audio(void* ctx, const std::int16_t* s, std::uint32_t n) {
+    if (self(ctx)->route_) self(ctx)->route_->audio(s, n);
     self(ctx)->sink_.audio(s, n);
 }
 
@@ -254,6 +258,7 @@ void HostSession::h_input(void* ctx, std::uint32_t seat, rcore_pad* out) {
     rcore_pad pad{};
     pad.struct_size = sizeof(rcore_pad);
     HostSession* s = self(ctx);
+    if (s->route_ && s->route_->input(seat, pad)) { *out = pad; return; }
     // A seat bound to a data accessory reads no pad (rev 7): the console sees
     // the accessory alone on that port. Decided here, on the one path every
     // mode shares, so neither a Sink nor a hub can leak a pad into it.
@@ -263,6 +268,7 @@ void HostSession::h_input(void* ctx, std::uint32_t seat, rcore_pad* out) {
         if (s->input_source_) s->input_source_(seat, pad);
         else s->sink_.input(seat, pad);
     }
+    if (s->route_) s->route_->delivered(seat,pad);
     *out = pad;
 }
 
@@ -339,8 +345,9 @@ std::uint64_t HostSession::h_wall_clock(void* ctx) {
     if (s->clock_tick_) return s->clock_epoch_us_ + s->clock_tick_() * 1000000ull / 60ull;
     // Offline: real time.
     using namespace std::chrono;
-    return static_cast<std::uint64_t>(
+    const auto live = static_cast<std::uint64_t>(
         duration_cast<microseconds>(system_clock::now().time_since_epoch()).count());
+    return s->route_ ? s->route_->clock(live) : live;
 }
 
 } // namespace retro::runner
diff --git a/runner/host_session.hpp b/runner/host_session.hpp
index bcf3d65..09760bd 100644
--- a/runner/host_session.hpp
+++ b/runner/host_session.hpp
@@ -18,6 +18,8 @@
 
 namespace retro::runner {
 
+class Route;
+
 class Sink {
 public:
     virtual ~Sink() = default;
@@ -67,6 +69,7 @@ class HostSession {
     bool set_options(const std::map<std::string, std::string>& overrides, std::string* error);
     // Declared keys and their resolved values; nullopt = unset.
     const std::map<std::string, std::optional<std::string>>& options() const { return options_; }
+    void set_route(Route* route) { route_ = route; }
 
     // Lend a GL context: `proc` resolves names against a context the caller
     // keeps current on the core thread for every core call. Before init():
@@ -167,6 +170,7 @@ class HostSession {
     AccessoryQueue* accessory_queue(std::uint32_t seat, std::uint32_t slot);
 
     const LoadedCore& core_;
+    Route* route_ = nullptr;
     Sink& sink_;
     rcore_host_api host_{};
     std::uint32_t presentation_width_ = 0, presentation_height_ = 0;
diff --git a/runner/route.cpp b/runner/route.cpp
new file mode 100644
index 0000000..aff6c05
--- /dev/null
+++ b/runner/route.cpp
@@ -0,0 +1,419 @@
+#include "route.hpp"
+#include "sha256.hpp"
+#include "transport.hpp"
+
+#include <charconv>
+#include <cstring>
+#include <iomanip>
+#include <sstream>
+#if defined(_WIN32)
+#include <windows.h>
+#else
+extern char** environ;
+#endif
+
+namespace retro::runner {
+namespace {
+constexpr std::size_t limit = 256 * 1024 * 1024;
+std::string hex(const void* data, std::size_t n) {
+    if (!n) return "-";
+    static const char digits[] = "0123456789abcdef";
+    const auto* p = static_cast<const unsigned char*>(data);
+    std::string s(n * 2, '0');
+    for (std::size_t i = 0; i < n; ++i) { s[2*i] = digits[p[i] >> 4]; s[2*i+1] = digits[p[i] & 15]; }
+    return s;
+}
+std::string hex(const std::string& s) { return hex(s.data(), s.size()); }
+std::string unhex(const std::string& s) {
+    if (s == "-") return {};
+    if (s.size() % 2 || s.size() > limit) throw std::runtime_error("invalid hex length");
+    std::string out(s.size() / 2, '\0');
+    auto nibble = [](char c) -> unsigned { if (c >= '0' && c <= '9') return c-'0'; if (c >= 'a' && c <= 'f') return c-'a'+10; throw std::runtime_error("invalid hex digit"); };
+    for (std::size_t i = 0; i < out.size(); ++i) out[i] = char((nibble(s[2*i]) << 4) | nibble(s[2*i+1]));
+    return out;
+}
+std::string word(std::istringstream& s) { std::string v; if (!(s >> v)) throw std::runtime_error("missing field"); return v; }
+template<class T> T number(std::istringstream& s) {
+    const std::string v = word(s); T n{};
+    const auto r = std::from_chars(v.data(), v.data()+v.size(), n);
+    if (r.ec != std::errc() || r.ptr != v.data()+v.size()) throw std::runtime_error("invalid number");
+    return n;
+}
+void end_line(std::istringstream& s) { std::string v; if (s >> v) throw std::runtime_error("extra field"); }
+std::string json(const std::string& s) {
+    std::ostringstream o; o << '"';
+    for (unsigned char c : s) {
+        if (c == '"' || c == '\\') o << '\\' << char(c);
+        else if (c < 32) o << "\\u00" << std::hex << std::setw(2) << std::setfill('0') << unsigned(c);
+        else o << char(c);
+    }
+    return o.str() + '"';
+}
+std::map<std::string,std::string> engine_environment() {
+    std::map<std::string,std::string> result;
+    auto take=[&](const std::string& entry) {
+        if(entry.rfind("N64LLE_",0)!=0)return;
+        const auto eq=entry.find('=');
+        if(eq!=std::string::npos)result["env:"+entry.substr(0,eq)]=entry.substr(eq+1);
+    };
+#if defined(_WIN32)
+    wchar_t* block=GetEnvironmentStringsW();
+    if(!block)throw std::runtime_error("cannot read engine environment");
+    for(const wchar_t* p=block;*p;p+=wcslen(p)+1) {
+        const int size=WideCharToMultiByte(CP_UTF8,0,p,-1,nullptr,0,nullptr,nullptr);
+        std::string value(size,'\0');
+        WideCharToMultiByte(CP_UTF8,0,p,-1,value.data(),size,nullptr,nullptr);
+        value.pop_back();take(value);
+    }
+    FreeEnvironmentStringsW(block);
+#else
+    for(char** p=environ;p && *p;++p)take(*p);
+#endif
+    return result;
+}
+}
+
+Route::Route(const LoadedCore& c, HostSession& s, const RouteArgs& a, const fs::path& out)
+    : core_(c), session_(s), args_(a), out_(out) {}
+
+bool Route::fail(const std::string& s, bool divergence) {
+    if (error_.empty()) { error_ = s; diverged_ = divergence; }
+    return false;
+}
+
+bool Route::open(const std::string& rom, const std::string& package_sha,
+                 const std::string& title_dir, bool strict) {
+    if (args_.record.empty() == args_.play.empty()) return fail("select exactly one route record/play mode");
+    identity_["rom"] = file_sha256_hex(retro::corelink::utf8_path(rom));
+    identity_["package"] = package_sha;
+    identity_["core"] = core_.sha256;
+    identity_["core_id"] = core_.info->core_id;
+    identity_["core_version"] = core_.info->core_version;
+    identity_["runner"] = file_sha256_hex(args_.runner);
+    const fs::path game = retro::corelink::utf8_path(title_dir) / "game.toml";
+    identity_["game.toml"] = fs::exists(game) ? file_sha256_hex(game) : "absent";
+    identity_["strict"] = strict ? "1" : "0";
+    for (const auto& [k,v] : session_.options()) identity_["option:" + k] = v ? "set:" + *v : "unset";
+    const auto environment=engine_environment();
+    identity_.insert(environment.begin(),environment.end());
+    if (identity_["rom"].empty() || identity_["runner"].empty()) return fail("unreadable ROM or runner identity");
+    if (playback()) {
+        if (!read()) return false;
+        auto recorded = recorded_identity_, actual = identity_;
+        if (!args_.runner_reference.empty()) {
+            const auto reference = file_sha256_hex(args_.runner_reference);
+            if (reference.empty() || reference != recorded_identity_["runner"])
+                return fail("runner reference does not match the recorded runner");
+            recorded.erase("runner"); actual.erase("runner");
+        }
+        if (args_.allow_core_change) {
+            for (const char* key : {"core", "core_version"}) { recorded.erase(key); actual.erase(key); }
+            // Compare an upgrade with an expanded option surface. Existing
+            // recorded options remain exact; only NEW declared defaults are
+            // admitted, and the verdict names them. Removed options refuse.
+            if(recorded_identity_["core"] != identity_["core"]) {
+                std::uint32_t n=0;
+                const auto* options=core_.api->options ? core_.api->options(&n) : nullptr;
+                for(std::uint32_t i=0;options && i<n;++i) {
+                    const auto& option=options[i]; const std::string key="option:"+std::string(option.key);
+                    const std::string value=option.default_value ? "set:"+std::string(option.default_value) : "unset";
+                    if(!recorded.count(key) && actual[key]==value) {
+                        added_defaults_.push_back(key+"="+value); actual.erase(key);
+                    }
+                }
+            }
+        }
+        if (recorded != actual) {
+            for (const auto& [k,v] : actual) if (!recorded.count(k) || recorded[k] != v) return fail("route identity mismatch: " + k);
+            return fail("route identity contains an unsupported key");
+        }
+    } else {
+        partial_ = args_.record; partial_ += ".partial";
+        if (fs::exists(args_.record) || fs::exists(partial_)) return fail("route or partial file already exists");
+        if (!args_.record.parent_path().empty()) fs::create_directories(args_.record.parent_path());
+        file_.open(partial_, std::ios::binary | std::ios::out);
+        if (!file_) return fail("cannot create route partial file");
+        file_ << "RCORE_ROUTE 1\n";
+        for (const auto& [k,v] : identity_) file_ << "I " << hex(k) << ' ' << hex(v) << '\n';
+    }
+    return true;
+}
+
+bool Route::capture_anchor() {
+    const auto& api = *core_.api;
+    if (playback() || !(core_.info->capabilities & RCORE_CAP_SAVESTATE) ||
+        !api.serialize_size || !api.serialize || !api.unserialize)
+        return fail("this core cannot anchor a replay");
+    const auto size = api.serialize_size();
+    if (!size || size > limit/4) return fail("replay anchor is empty or too large");
+    anchor_.resize(static_cast<std::size_t>(size));
+    if (api.serialize(anchor_.data(),size) != RCORE_OK)
+        return fail("the core refused to save the replay anchor");
+    const auto before=state_digest();
+    // Record and playback both follow the core's restore path.
+    if (api.unserialize(anchor_.data(),size) != RCORE_OK)
+        return fail("the core refused to restore the replay anchor");
+    anchor_state_=state_digest();
+    if (before!=anchor_state_) {
+        expected_state_=before; actual_state_=anchor_state_;
+        return fail("the core changed state while restoring the replay anchor",true);
+    }
+    file_ << "A " << hex(anchor_state_) << ' ' << hex(anchor_.data(),anchor_.size()) << '\n';
+    return bool(file_);
+}
+
+bool Route::initial_saves() {
+    const auto& regions = session_.save_regions();
+    if (playback()) {
+        if (regions.size() != saves_.size()) return fail("initial save region count mismatch");
+        for (std::size_t i = 0; i < regions.size(); ++i) {
+            const auto& r = regions[i]; const auto& s = saves_[i];
+            if (r.id != s.id || r.kind != s.kind || r.seat != s.seat || r.slot != s.slot || r.erase_value != s.erase || r.size != s.bytes.size()) return fail("initial save region mismatch");
+            if(r.size)std::memcpy(r.data, s.bytes.data(), r.size);
+        }
+        if (!calls_complete()) return false;
+        if (anchored() && (!core_.api->unserialize ||
+            core_.api->unserialize(anchor_.data(),anchor_.size()) != RCORE_OK))
+            return fail("the core refused the replay anchor");
+        if (anchored() && state_digest()!=anchor_state_) {
+            expected_state_=anchor_state_; actual_state_=state_digest();
+            return fail("replay anchor state differs before the first field",true);
+        }
+    } else {
+        for (const auto& r : regions) {
+            if (r.size > limit/2) return fail("initial save region too large");
+            file_ << "S " << hex(r.id) << ' ' << r.kind << ' ' << r.seat << ' ' << r.slot << ' ' << r.erase_value << ' ' << hex(r.data,r.size) << '\n';
+        }
+        if (!write_field(boot_, true)) return false;
+    }
+    started_ = true;
+    return true;
+}
+
+bool Route::begin(std::uint32_t w, std::uint32_t h) {
+    if (!started_ || done() || !error_.empty()) return fail("route frame is not available");
+    current_ = {}; current_.width = w; current_.height = h;
+    if (playback()) {
+        current_.width = frames_[next_].width; current_.height = frames_[next_].height;
+    }
+    input_cursor_ = clock_cursor_ = 0;
+    pcm_.clear();
+    session_.set_presentation_size(current_.width, current_.height);
+    return true;
+}
+
+bool Route::input(std::uint32_t seat, rcore_pad& pad) {
+    if (!playback()) return false;
+    const Field& f = started_ && next_ < frames_.size() ? frames_[next_] : boot_;
+    if (input_cursor_ >= f.inputs.size() || f.inputs[input_cursor_].seat != seat) {
+        fail("input call order differs at field " + std::to_string(next_ + (started_ ? 1 : 0)), true);
+        pad = {}; pad.struct_size = sizeof pad;
+    } else pad = f.inputs[input_cursor_++].pad;
+    return true;
+}
+void Route::delivered(std::uint32_t seat, const rcore_pad& pad) {
+    if (!playback()) {
+        auto& f = started_ ? current_ : boot_;
+        if (f.inputs.size() >= 4096) { fail("too many input calls in one field"); return; }
+        f.inputs.push_back({seat,pad});
+    }
+}
+std::uint64_t Route::clock(std::uint64_t live) {
+    if (!playback()) {
+        auto& f = started_ ? current_ : boot_;
+        if (f.clocks.size() >= 4096) { fail("too many clock calls in one field"); return 0; }
+        f.clocks.push_back(live); return live;
+    }
+    const auto& f = started_ && next_ < frames_.size() ? frames_[next_] : boot_;
+    if (clock_cursor_ >= f.clocks.size()) { fail("clock call count differs", true); return 0; }
+    return f.clocks[clock_cursor_++];
+}
+void Route::video(const rcore_frame& f) {
+    if (!f.pixels || f.pixel_format != RCORE_PIXEL_RGBA8 || !f.width || !f.height || std::uint64_t(f.width)*f.height > 16*1024*1024 || f.stride < std::uint64_t(f.width)*4) { fail("unsupported route picture"); return; }
+    picture_width_ = f.width; picture_height_ = f.height;
+    picture_.resize(std::size_t(f.width)*f.height*4);
+    for (std::uint32_t y=0;y<f.height;++y) std::memcpy(picture_.data()+std::size_t(y)*f.width*4, static_cast<const std::uint8_t*>(f.pixels)+std::size_t(y)*f.stride, std::size_t(f.width)*4);
+}
+void Route::audio(const std::int16_t* s, std::uint32_t n) {
+    if (std::uint64_t(n)*4 + pcm_.size() > 16*1024*1024) { fail("too much audio in one field"); return; }
+    // Explicit little endian, independent of the host's byte order.
+    for (std::uint64_t i=0;i<std::uint64_t(n)*2;++i) { pcm_.push_back(std::uint8_t(s[i])); pcm_.push_back(std::uint16_t(s[i]) >> 8); }
+}
+void Route::gpu_video() { gpu_ = true; picture_.clear(); }
+
+bool Route::calls_complete() {
+    if (!playback()) return true;
+    const auto& f = started_ ? frames_[next_] : boot_;
+    if (input_cursor_ != f.inputs.size() || clock_cursor_ != f.clocks.size()) return fail("input/clock call count differs at field " + std::to_string(next_ + (started_ ? 1 : 0)), true);
+    return error_.empty();
+}
+
+std::string Route::state_digest() const {
+    std::string digest="-";
+    if (RCORE_HAS(core_.api,rcore_core_api,state_hash) && core_.api->state_hash) {
+        digest = std::to_string(core_.api->state_hash());
+        if (RCORE_HAS(core_.api,rcore_core_api,state_hash_parts) && core_.api->state_hash_parts) {
+            std::uint64_t parts[3]{}; const char* names[3]{};
+            core_.api->state_hash_parts(parts,names);
+            for (unsigned i=0;i<3;++i) digest += ":" + std::to_string(parts[i]);
+        }
+    }
+    return digest;
+}
+bool Route::end() {
+    if (!calls_complete()) return false;
+    current_.state=state_digest();
+    current_.image = picture_.empty() ? "-" : std::to_string(picture_width_) + ":" + std::to_string(picture_height_) + ":" + sha256_hex(picture_.data(),picture_.size());
+    current_.audio = sha256_hex(pcm_.data(),pcm_.size());
+    const auto mark = args_.marks.find(next_+1);
+    current_.mark = playback() ? frames_[next_].mark : mark == args_.marks.end() ? "" : mark->second;
+    if (playback()) {
+        const auto& f = frames_[next_];
+        if (f.state != current_.state) {
+            expected_state_=f.state; actual_state_=current_.state;
+            fail("state checkpoint differs at field " + std::to_string(next_+1),true);
+        }
+        else if (f.image != current_.image) fail("picture checkpoint differs at field " + std::to_string(next_+1),true);
+        else if (f.audio != current_.audio) fail("audio checkpoint differs at field " + std::to_string(next_+1),true);
+    }
+    if ((!current_.mark.empty() || !error_.empty()) && !picture_.empty()) {
+        std::ofstream shot(out_ / ("route-"+std::to_string(next_+1)+".ppm"),std::ios::binary);
+        shot << "P6\n" << picture_width_ << ' ' << picture_height_ << "\n255\n";
+        for (std::size_t i=0;i<picture_.size();i+=4) shot.write(reinterpret_cast<const char*>(picture_.data()+i),3);
+        if (!shot) fail("cannot write checkpoint picture");
+    }
+    if (!playback() && error_.empty() && !write_field(current_,false)) return false;
+    if (error_.empty()) ++next_;
+    return error_.empty();
+}
+
+bool Route::write_field(const Field& f, bool boot) {
+    file_ << (boot ? "B 0" : "F " + std::to_string(next_+1)) << ' ' << f.width << ' ' << f.height << ' ' << f.inputs.size() << ' ' << f.clocks.size() << ' ' << hex(f.state) << ' ' << hex(f.image) << ' ' << hex(f.audio) << ' ' << hex(f.mark) << '\n';
+    for (const auto& i : f.inputs) {
+        file_ << "P " << i.seat << ' ' << i.pad.connected << ' ' << i.pad.buttons;
+        for (auto a : i.pad.axes) file_ << ' ' << a;
+        file_ << '\n';
+    }
+    for (auto t : f.clocks) file_ << "T " << t << '\n';
+    file_.flush();
+    if(file_.tellp()>std::streamoff(limit-1024))return fail("route exceeds 256 MiB limit");
+    return file_ ? true : fail("cannot write route");
+}
+
+bool Route::read() {
+    try {
+        std::error_code ec; const auto size = fs::file_size(args_.play,ec);
+        if (ec || size > limit || size < 16) throw std::runtime_error("missing or oversized route");
+        std::ifstream in(args_.play,std::ios::binary);
+        std::string text(std::istreambuf_iterator<char>(in),{});
+        const auto footer = text.rfind("\nEND ");
+        if (footer == std::string::npos || text.back() != '\n') throw std::runtime_error("incomplete route (missing END)");
+        const std::string prefix = text.substr(0,footer+1);
+        std::istringstream tail(text.substr(footer+1));
+        if (word(tail) != "END") throw std::runtime_error("missing END");
+        const auto count = number<std::uint64_t>(tail);
+        if (word(tail) != sha256_hex(prefix.data(),prefix.size())) throw std::runtime_error("route checksum mismatch");
+        end_line(tail);
+        std::istringstream lines(prefix); std::string line;
+        if (!std::getline(lines,line) || line != "RCORE_ROUTE 1") throw std::runtime_error("unsupported route format");
+        bool boot_seen = false;
+        while (std::getline(lines,line)) {
+            std::istringstream row(line); const auto type = word(row);
+            if (type == "I" && !boot_seen && saves_.empty()) {
+                const auto key=unhex(word(row)), value=unhex(word(row));
+                if (!recorded_identity_.emplace(key,value).second) throw std::runtime_error("duplicate identity");
+            } else if (type == "A" && !boot_seen && saves_.empty() && anchor_.empty()) {
+                anchor_state_=unhex(word(row));
+                const auto bytes=unhex(word(row));
+                if (bytes.empty() || bytes.size()>limit/4) throw std::runtime_error("invalid anchor size");
+                anchor_.assign(bytes.begin(),bytes.end());
+            } else if (type == "S" && !boot_seen) {
+                InitialSave s; s.id=unhex(word(row)); s.kind=number<std::uint32_t>(row); s.seat=number<std::uint32_t>(row); s.slot=number<std::uint32_t>(row); s.erase=number<std::uint32_t>(row);
+                const auto bytes=unhex(word(row)); s.bytes.assign(bytes.begin(),bytes.end()); saves_.push_back(std::move(s));
+                if (saves_.size()>64) throw std::runtime_error("too many save regions");
+            } else if (type == "B" || type == "F") {
+                const auto n=number<std::uint64_t>(row);
+                if ((type == "B" && (boot_seen || n)) || (type == "F" && (!boot_seen || n != frames_.size()+1))) throw std::runtime_error("field order mismatch");
+                Field f; f.width=number<std::uint32_t>(row); f.height=number<std::uint32_t>(row);
+                const auto pads=number<unsigned>(row), clocks=number<unsigned>(row);
+                if (pads>4096 || clocks>4096) throw std::runtime_error("too many callbacks");
+                f.state=unhex(word(row)); f.image=unhex(word(row)); f.audio=unhex(word(row)); f.mark=unhex(word(row)); end_line(row);
+                for(unsigned i=0;i<pads;++i) {
+                    if (!std::getline(lines,line)) throw std::runtime_error("missing pad");
+                    std::istringstream p(line); if(word(p)!="P") throw std::runtime_error("missing pad");
+                    Input v{}; v.seat=number<std::uint32_t>(p); v.pad.struct_size=sizeof v.pad; v.pad.connected=number<std::uint32_t>(p); v.pad.buttons=number<std::uint32_t>(p);
+                    if(v.seat>=RCORE_MAX_SEATS || v.pad.connected>1) throw std::runtime_error("invalid seat/connection");
+                    for(auto& a:v.pad.axes) a=number<std::int16_t>(p); end_line(p); f.inputs.push_back(v);
+                }
+                for(unsigned i=0;i<clocks;++i) {
+                    if(!std::getline(lines,line)) throw std::runtime_error("missing clock");
+                    std::istringstream t(line); if(word(t)!="T") throw std::runtime_error("missing clock"); f.clocks.push_back(number<std::uint64_t>(t)); end_line(t);
+                }
+                if(type=="B") { boot_=std::move(f); boot_seen=true; } else frames_.push_back(std::move(f));
+                continue;
+            } else throw std::runtime_error("unknown or misplaced record");
+            end_line(row);
+        }
+        if(!boot_seen || frames_.empty() || count!=frames_.size()) throw std::runtime_error("field count mismatch");
+        return true;
+    } catch(const std::exception& e) { return fail(std::string("route refused: ")+e.what()); }
+}
+
+void Route::write_verdict(const char* result) {
+    const fs::path path=args_.verdict.empty() ? out_/"route-verdict.json" : args_.verdict;
+    const auto target=fs::absolute(path).lexically_normal();
+    for(const auto& source:{args_.record,args_.play,partial_})
+        if(!source.empty() && target==fs::absolute(source).lexically_normal()) { fail("verdict path would overwrite a route"); return; }
+    std::ofstream v(path,std::ios::binary);
+    v << "{\n  \"schema\": 1,\n  \"result\": " << json(result) << ",\n  \"frames\": " << next_
+      << ",\n  \"first_divergence\": " << (diverged_ ? std::to_string(next_+1) : "null")
+      << ",\n  \"takeover_frame\": " << (taken_over_ ? std::to_string(next_+1) : "null")
+      << ",\n  \"detail\": " << json(error_) << ",\n  \"recorded_core\": " << json(playback() ? recorded_identity_["core"] : identity_["core"])
+      << ",\n  \"expected_state\": " << json(expected_state_)
+      << ",\n  \"actual_state\": " << json(actual_state_)
+      << ",\n  \"player_core\": " << json(identity_["core"])
+      << ",\n  \"recorded_runner\": " << json(playback() ? recorded_identity_["runner"] : identity_["runner"])
+      << ",\n  \"player_runner\": " << json(identity_["runner"])
+      << ",\n  \"runner_reference_supplied\": " << (!args_.runner_reference.empty() ? "true" : "false")
+      << ",\n  \"core_change_allowed\": " << (args_.allow_core_change ? "true" : "false")
+      << ",\n  \"added_default_options\": [";
+    for(std::size_t i=0;i<added_defaults_.size();++i) { if(i)v << ',';v << json(added_defaults_[i]); }
+    v << "]\n}\n";
+    if(!v) fail("cannot write route verdict");
+}
+
+bool Route::live_input(const rcore_pad pads[RCORE_MAX_SEATS]) {
+    // The frontend already maps controls and applies its configured deadzone.
+    // Its raw-axis fallback of 8000 also rejects residual noise here; this
+    // affects takeover detection only, never the input delivered after it.
+    for (unsigned seat=0;seat<RCORE_MAX_SEATS;++seat) {
+        if (!pads[seat].connected) continue;
+        if (pads[seat].buttons) return true;
+        for (auto axis:pads[seat].axes) if (axis>8000 || axis<-8000) return true;
+    }
+    return false;
+}
+
+bool Route::finish(bool success, bool stopped, bool taken_over) {
+    if(finished_) return error_.empty(); finished_=true;
+    taken_over_ = taken_over;
+    const bool user_stop = (stopped || taken_over) && playback() && !done();
+    if(!success && error_.empty()) fail("core or session failed");
+    if(!next_ && !user_stop && error_.empty()) fail("no complete field was recorded or played");
+    if(playback() && !done() && !user_stop && error_.empty()) fail("playback stopped before the route ended");
+    if(!playback() && error_.empty()) {
+        file_.close();
+        const auto digest=file_sha256_hex(partial_);
+        std::ofstream tail(partial_,std::ios::binary|std::ios::app);
+        tail << "END " << next_ << ' ' << digest << '\n'; tail.close();
+        std::error_code ec;
+        if(digest.empty() || !tail) fail("cannot seal route");
+        else { fs::rename(partial_,args_.record,ec); if(ec) fail("cannot publish completed route: "+ec.message()); }
+    }
+    write_verdict(error_.empty() ? (taken_over ? "taken_over" : user_stop ? "stopped" : playback() ? "in_sync" : "recorded") : diverged_ ? "diverged" : "failed");
+    return error_.empty();
+}
+
+std::uint32_t Route::width() const { return playback() && next_<frames_.size() ? frames_[next_].width : 0; }
+std::uint32_t Route::height() const { return playback() && next_<frames_.size() ? frames_[next_].height : 0; }
+} // namespace retro::runner
diff --git a/runner/route.hpp b/runner/route.hpp
new file mode 100644
index 0000000..8123717
--- /dev/null
+++ b/runner/route.hpp
@@ -0,0 +1,89 @@
+#pragma once
+
+#include "host_session.hpp"
+#include <array>
+#include <fstream>
+
+namespace retro::runner {
+
+// An input movie from boot or a restored anchor. Input is captured at the core callback, not at a
+// desktop timer. The route is private: its initial save regions can contain
+// player data. The .partial file is flushed after each complete field.
+struct RouteArgs {
+    fs::path record, play, verdict, runner, runner_reference;
+    bool allow_core_change = false;
+    bool takeover = false;
+    std::map<std::uint64_t, std::string> marks;
+    bool active() const { return !record.empty() || !play.empty(); }
+};
+
+class Route {
+public:
+    Route(const LoadedCore&, HostSession&, const RouteArgs&, const fs::path& out);
+    bool open(const std::string& rom, const std::string& package_sha,
+              const std::string& title_dir, bool strict);
+    bool initial_saves();
+    bool capture_anchor();
+    bool anchored() const { return !anchor_.empty(); }
+    bool begin(std::uint32_t width = 0, std::uint32_t height = 0);
+    bool end();
+    bool finish(bool success, bool stopped = false, bool taken_over = false);
+    static bool live_input(const rcore_pad pads[RCORE_MAX_SEATS]);
+    bool playback() const { return !args_.play.empty(); }
+    bool done() const { return playback() && next_ >= frames_.size(); }
+    std::uint64_t length() const { return frames_.size(); }
+    std::uint64_t field() const { return next_; }
+    std::uint32_t width() const;
+    std::uint32_t height() const;
+    const std::string& error() const { return error_; }
+    int exit_code() const { return diverged_ ? 5 : 2; }
+
+    // Called only by HostSession's shared core callbacks.
+    bool input(std::uint32_t, rcore_pad&); // true when playback supplies it
+    void delivered(std::uint32_t, const rcore_pad&);
+    std::uint64_t clock(std::uint64_t live);
+    void video(const rcore_frame&);
+    void audio(const std::int16_t*, std::uint32_t);
+    void gpu_video();
+
+private:
+    struct Input { std::uint32_t seat; rcore_pad pad; };
+    struct Field {
+        std::vector<Input> inputs;
+        std::vector<std::uint64_t> clocks;
+        std::uint32_t width = 0, height = 0;
+        std::string state, image, audio, mark;
+    };
+    struct InitialSave {
+        std::string id;
+        std::uint32_t kind, seat, slot, erase;
+        std::vector<std::uint8_t> bytes;
+    };
+    bool fail(const std::string&, bool divergence = false);
+    bool read();
+    bool write_field(const Field&, bool boot);
+    bool calls_complete();
+    std::string state_digest() const;
+    void write_verdict(const char* result);
+    const LoadedCore& core_;
+    HostSession& session_;
+    RouteArgs args_;
+    fs::path out_, partial_;
+    std::map<std::string, std::string> identity_, recorded_identity_;
+    std::vector<InitialSave> saves_;
+    Field boot_, current_;
+    std::vector<Field> frames_;
+    std::vector<std::uint8_t> picture_, pcm_;
+    std::vector<std::uint8_t> anchor_;
+    std::string anchor_state_;
+    std::string expected_state_, actual_state_;
+    std::uint32_t picture_width_ = 0, picture_height_ = 0;
+    std::ofstream file_;
+    std::uint64_t next_ = 0, input_cursor_ = 0, clock_cursor_ = 0;
+    bool started_ = false, finished_ = false, diverged_ = false, gpu_ = false;
+    std::string error_;
+    std::vector<std::string> added_defaults_;
+    bool taken_over_ = false;
+};
+
+} // namespace retro::runner
diff --git a/runner/runner_link.cpp b/runner/runner_link.cpp
index d9179e3..efda31d 100644
--- a/runner/runner_link.cpp
+++ b/runner/runner_link.cpp
@@ -460,6 +460,14 @@ int run_link_mode(const LoadedCore& core, const CoreManifest& manifest, const Li
     };
     std::string err;
     if (!session.set_options(a.overrides, &err)) return exiting(sock, 2, err);
+    std::optional<Route> route;
+    if (a.route.active()) {
+        route.emplace(core,session,a.route,a.out);
+        if (!route->open(a.rom,a.package_sha256,a.title_dir,a.strict)) {
+            route->finish(false); return exiting(sock,2,route->error());
+        }
+        if (!route->anchored()) session.set_route(&*route);
+    }
     if (a.gl) lend_gl(session);
 
     const std::string cache = a.out.string();
@@ -546,8 +554,24 @@ int run_link_mode(const LoadedCore& core, const CoreManifest& manifest, const Li
             return 0;
         }
     }
-    session.adopt_external_save_regions(regs, nregs, memory);
-
+    const bool private_saves = route && route->playback();
+    if (private_saves || link_has_replays(session_minor)) {
+        // Playback uses private save memory. The hub's mappings remain
+        // untouched, even if the runner crashes and the hub persists them.
+        session.adopt_save_regions(regs,nregs,{});
+        if (!private_saves) for (std::size_t i=0;i<memory.size();++i)
+            if (regs[i].size) std::memcpy(session.save_regions()[i].data,memory[i],regs[i].size);
+    } else session.adopt_external_save_regions(regs, nregs, memory);
+    if (route && !route->initial_saves()) {
+        session.set_route(nullptr); route->finish(false); return exiting(sock,2,route->error());
+    }
+
+    if (route) session.set_route(&*route);
+    auto mirror_saves = [&] {
+        if (private_saves || !link_has_replays(session_minor)) return;
+        for (std::size_t i=0;i<memory.size();++i)
+            if (regs[i].size) std::memcpy(memory[i],session.save_regions()[i].data,regs[i].size);
+    };
     StateKeeper keeper(core, session, a.rom, a.package_sha256, bindings);
     // A core that can save gets its content hashed now, off the core thread,
     // so the player's first save does not wait on it.
@@ -604,13 +628,25 @@ int run_link_mode(const LoadedCore& core, const CoreManifest& manifest, const Li
     PerfHint hint;
     bool hint_said = false;
     int code = 0;
+    bool user_quit = false;
+    bool taken_over = false, takeover_armed = false;
+    std::string recording_path = a.route.record.string();
+    auto replay_status = [&](ReplayState state, const std::string& detail = {}) {
+        if (!link_has_replays(session_minor)) return;
+        ReplayStatusMsg msg{}; msg.h.type=Msg::ReplayStatus; msg.state=state;
+        msg.fields=route ? route->field() : 0;
+        copy_str(msg.path,sizeof msg.path,recording_path.c_str());
+        copy_str(msg.detail,sizeof msg.detail,detail.c_str());
+        send_msg(sock,msg);
+    };
+    if (route) replay_status(route->playback() ? ReplayState::Playing : ReplayState::Recording);
     for (;;) {
         const RecvResult rr = recv_packet(sock, buf, nullptr, -1);
-        if (rr != RecvResult::Packet) break; // hub gone: stop quietly
+        if (rr != RecvResult::Packet) { user_quit = true; break; }
         Msg t{};
         packet_type(buf, t);
         if (sink.take_gpu_status(buf)) continue;
-        if (t == Msg::Quit) break;
+        if (t == Msg::Quit) { user_quit = true; break; }
         if (t == Msg::StateThumbnail && link_has_gpu_frames(session_minor)) {
             sink.take_thumbnail(buf);
             continue;
@@ -619,13 +655,46 @@ int run_link_mode(const LoadedCore& core, const CoreManifest& manifest, const Li
             take_accessory_data(buf);
             continue;
         }
-        if ((t == Msg::SaveState || t == Msg::LoadState) && a.netplay) {
+        if (t == Msg::ReplayControl && link_has_replays(session_minor)) {
+            ReplayControlMsg request{};
+            if (!as_msg(buf,request) || request.record>1) {
+                replay_status(ReplayState::Failed,"malformed replay request"); continue;
+            }
+            request.path[sizeof request.path-1]=0;
+            if (a.netplay || !bindings.empty() || !a.data_accessories.empty() || private_saves) {
+                replay_status(ReplayState::Failed,"recording is off during playback, netplay or accessory sessions"); continue;
+            }
+            if (request.record) {
+                if (route && !taken_over) {
+                    replay_status(route->playback() ? ReplayState::Playing : ReplayState::Recording,"a replay is already active"); continue;
+                }
+                route.reset();
+                RouteArgs args=a.route; args.play.clear(); args.record=utf8_path(request.path);
+                args.verdict=args.record; args.verdict += ".verdict.json";
+                if (args.record.empty()) { replay_status(ReplayState::Failed,"a replay destination is required"); continue; }
+                route.emplace(core,session,args,a.out); recording_path=request.path;
+                if (!route->open(a.rom,a.package_sha256,a.title_dir,a.strict) ||
+                    !route->capture_anchor() || !route->initial_saves()) {
+                    const auto why=route->error(); route->finish(false);
+                    replay_status(ReplayState::Failed,why); route.reset(); continue;
+                }
+                taken_over=false; takeover_armed=false; session.set_route(&*route);
+                replay_status(ReplayState::Recording);
+            } else if (route && !route->playback()) {
+                session.set_route(nullptr);
+                const bool ok=route->finish(true);
+                replay_status(ok ? ReplayState::Saved : ReplayState::Failed,route->error());
+                route.reset();
+            } else replay_status(ReplayState::Failed,"no recording is active");
+            continue;
+        }
+        if ((t == Msg::SaveState || t == Msg::LoadState) && (a.netplay || (route && !taken_over))) {
             // A match starts from a cold boot and is never rewound by a player.
             StateDoneMsg d{};
             d.h.type = Msg::StateDone;
             d.request = t;
             d.ok = 0;
-            copy_str(d.detail, sizeof d.detail, "savestates are off during a netplay match");
+            copy_str(d.detail, sizeof d.detail, route ? "savestates are off during a boot route" : "savestates are off during a netplay match");
             send_msg(sock, d);
             continue;
         }
@@ -664,12 +733,26 @@ int run_link_mode(const LoadedCore& core, const CoreManifest& manifest, const Li
             break;
         }
         std::copy(std::begin(g.pads), std::end(g.pads), std::begin(sink.pads));
+        if (route && route->playback() && a.route.takeover && !taken_over) {
+            const bool active = Route::live_input(g.pads);
+            if (!active) takeover_armed = true;
+            else if (takeover_armed) {
+                if (!route->finish(true,false,true)) { code=exiting(sock,route->exit_code(),route->error());break; }
+                session.set_route(nullptr);
+                taken_over=true;
+                replay_status(ReplayState::TakenOver);
+                std::fprintf(stderr,"route: live input took over at field %llu\n",static_cast<unsigned long long>(g.frame_number));
+            }
+        }
         sink.frame_number = g.frame_number;
         session.set_presentation_size(g.presentation_width, g.presentation_height);
         // Everything that arrived before this grant is the frame's accessory
         // sequence; a message that arrives while the frame runs waits for the
         // next (the runner reads nothing from the hub mid-frame).
         session.begin_frame_accessories();
+        if (route && !taken_over && !route->begin(g.presentation_width,g.presentation_height)) {
+            code = exiting(sock,route->exit_code(),route->error()); break;
+        }
         FrameDoneMsg done{};
         done.h.type = Msg::FrameDone;
         done.frame_number = g.frame_number;
@@ -724,6 +807,10 @@ int run_link_mode(const LoadedCore& core, const CoreManifest& manifest, const Li
             if (quit) break;
         }
         done.game_frame = sink.last_game_frame;
+        if (route && !taken_over && done.result == RCORE_OK && !route->end()) {
+            code = exiting(sock,route->exit_code(),route->error()); break;
+        }
+        mirror_saves();
         send_msg_sized(sock, done, frame_done_size);
         const std::uint64_t period_ns =
             sink.rate_num && sink.rate_den
@@ -744,9 +831,20 @@ int run_link_mode(const LoadedCore& core, const CoreManifest& manifest, const Li
                                         std::to_string(done.result));
             break;
         }
+        if (route && !taken_over && route->done()) break;
+    }
+    session.set_route(nullptr);
+    if (route && !route->finish(!code && !sink.faults,user_quit)) {
+        if (!code) code = exiting(sock,route->exit_code(),route->error());
     }
+    if (route && !taken_over) replay_status(code || sink.faults ? ReplayState::Failed :
+        route->playback() ? (user_quit ? ReplayState::Stopped : ReplayState::Complete) : ReplayState::Saved,
+        route->error());
+    mirror_saves();
     core.api->unload();
     core.api->deinit();
+    if (route && route->playback() && !code && !sink.faults)
+        exiting(sock,0,taken_over ? "live session complete after replay takeover" : user_quit ? "replay stopped" : "replay complete");
     return code ? code : (sink.faults ? 1 : 0);
 }
 
diff --git a/runner/runner_link.hpp b/runner/runner_link.hpp
index bf28ee8..bde67d2 100644
--- a/runner/runner_link.hpp
+++ b/runner/runner_link.hpp
@@ -7,6 +7,7 @@
 #include "core_manifest.hpp"
 #include "host_session.hpp"
 #include "net_session.hpp"
+#include "route.hpp"
 
 #include <map>
 #include <optional>
@@ -53,6 +54,7 @@ std::string check_data_accessories(const LoadedCore& core, const std::vector<Dat
                                    bool netplay);
 
 struct LinkArgs {
+    RouteArgs route;
     std::string rom;
     std::string package;     // --package; empty for a core without game_package
     std::string package_sha256; // the runner's hash of it, for savestate envelopes
diff --git a/runner/runner_main.cpp b/runner/runner_main.cpp
index 408ad25..b82b24d 100644
--- a/runner/runner_main.cpp
+++ b/runner/runner_main.cpp
@@ -65,8 +65,10 @@
 #include "sha256.hpp"
 #include "state_keeper.hpp"
 #include "transport.hpp"
+#include "route.hpp"
 
 #include <array>
+#include <algorithm>
 #include <chrono>
 #include <cinttypes>
 #include <cstdio>
@@ -80,6 +82,7 @@
 #include <string>
 #include <utility>
 #include <vector>
+#include <csignal>
 
 #if defined(RETRO_RUNNER_HAVE_SDL3)
 #  include <SDL3/SDL.h>
@@ -92,6 +95,8 @@
 using namespace retro::runner;
 
 namespace {
+volatile std::sig_atomic_t route_stop = 0;
+void request_route_stop(int) { route_stop = 1; }
 
 [[noreturn]] void die(const std::string& msg) {
     std::fprintf(stderr, "retro-core-runner: %s\n", msg.c_str());
@@ -311,7 +316,8 @@ void print_version() {
                 "transfer_pak_seats %zu\n"
                 "netplay %d\n"
                 "netplay_module_abi %u\n"
-                "accessory_data 1\n",
+                "accessory_data 1\n"
+                "boot_routes 1\n",
                 RETRO_RUNTIME_VERSION, RETRO_RUNTIME_VERSION, RETRO_RUNTIME_COMMIT,
                 retro::corelink::kProtocolMajor, retro::corelink::kProtocolMinor,
                 RCORE_ABI_MAJOR, RCORE_DRAFT_REVISION, gl, retro::runner::kTransferPakSeats,
@@ -421,6 +427,13 @@ int main(int argc, char** argv) {
     bool gl = false, strict = false, seat0 = true, list_options = false, link = false;
     bool describe = false;
     std::optional<std::uint64_t> replay_at;
+    RouteArgs route_args;
+    route_args.runner = retro::corelink::utf8_path(args[0]);
+    if (const char* p = std::getenv("RETRO_RECORD_ROUTE")) route_args.record = retro::corelink::utf8_path(p);
+    if (const char* p = std::getenv("RETRO_PLAY_ROUTE")) route_args.play = retro::corelink::utf8_path(p);
+    if (const char* p = std::getenv("RETRO_ROUTE_VERDICT")) route_args.verdict = retro::corelink::utf8_path(p);
+    if (const char* p = std::getenv("RETRO_ROUTE_RUNNER_REFERENCE")) route_args.runner_reference = retro::corelink::utf8_path(p);
+    if (const char* p = std::getenv("RETRO_ROUTE_TAKEOVER")) route_args.takeover = std::strcmp(p,"1")==0;
     std::map<std::string, std::string> overrides;
     std::vector<std::pair<std::uint64_t, std::uint32_t>> script;
     // Netplay (net_session.hpp): any --net-* flag makes this a netplay run.
@@ -473,6 +486,18 @@ int main(int argc, char** argv) {
         else if (a == "--list-options") list_options = true;
         else if (a == "--describe") describe = true;
         else if (a == "--replay-at") replay_at = num(val());
+        else if (a == "--record-route") route_args.record = retro::corelink::utf8_path(val());
+        else if (a == "--play-route") route_args.play = retro::corelink::utf8_path(val());
+        else if (a == "--route-verdict") route_args.verdict = retro::corelink::utf8_path(val());
+        else if (a == "--route-runner-reference") route_args.runner_reference = retro::corelink::utf8_path(val());
+        else if (a == "--route-takeover") route_args.takeover = true;
+        else if (a == "--route-allow-core-change") route_args.allow_core_change = true;
+        else if (a == "--route-mark") {
+            const auto mark = val(); const auto sep = mark.find(':');
+            if (sep == std::string::npos || sep == mark.size()-1) die("--route-mark FIELD:NAME");
+            const auto at = num(mark.substr(0,sep));
+            if (!at || !route_args.marks.emplace(at,mark.substr(sep+1)).second) die("duplicate or zero route mark");
+        }
         else if (a == "--net-module") { netplay = true; net.module_path = val(); }
         else if (a == "--net-slot") { netplay = true; net.slot = static_cast<int>(num(val())); }
         else if (a == "--net-slots") { netplay = true; net.slots = static_cast<int>(num(val())); }
@@ -509,6 +534,13 @@ int main(int argc, char** argv) {
         }
     }
     if (core_path.empty()) die("--core <library> is required");
+    if (route_args.active() && (netplay || load_state || replay_at || accessory_script ||
+        std::any_of(vru_seats.begin(),vru_seats.end(),[](bool v){return v;}) ||
+        std::any_of(tpak_roms.begin(),tpak_roms.end(),[](const auto& v){return !v.empty();})))
+        die("boot routes refuse netplay, loaded states and accessories");
+    if (!route_args.play.empty() && (!script.empty() || !route_args.record.empty()))
+        die("--play-route refuses an input script or recorder");
+    if (route_args.takeover && (!link || route_args.play.empty())) die("--route-takeover requires link playback");
     if (net.module_path.empty())
         if (const char* e = std::getenv("RETRO_NETPLAY_MODULE")) net.module_path = e;
     if (netplay && (replay_at || load_state))
@@ -639,6 +671,7 @@ int main(int argc, char** argv) {
         void (*lend)(HostSession&) = lend_gl_context;
 #endif
         LinkArgs la;
+        la.route = route_args;
         la.rom = rom;
         la.package = package;
         la.package_sha256 = pkg_sha;
@@ -704,6 +737,15 @@ int main(int argc, char** argv) {
         }
     }
     if (!session.set_options(overrides, &err)) die(err);
+    std::optional<Route> route;
+    if (route_args.active()) {
+        route.emplace(core,session,route_args,out);
+        if (!route->open(rom,pkg_sha,title_dir,strict)) { route->finish(false); die(route->error()); }
+        if (!route->anchored()) session.set_route(&*route);
+        if (route->playback()) frames = route->length();
+        std::signal(SIGINT,request_route_stop);
+        std::signal(SIGTERM,request_route_stop);
+    }
     for (const auto& [k, v] : session.options()) {
         if (v) std::printf("option %s = %s\n", k.c_str(), v->c_str());
         else if (list_options) std::printf("option %s unset\n", k.c_str());
@@ -759,6 +801,8 @@ int main(int argc, char** argv) {
         if (tpak_rtcs[seat]) save_files[id + ".rtc"] = *tpak_rtcs[seat];
     }
     session.adopt_save_regions(regs, nregs, save_files);
+    if (route && !route->initial_saves()) { session.set_route(nullptr); route->finish(false); die(route->error()); }
+    if (route) session.set_route(&*route);
     for (const SaveRegion& r : session.save_regions()) {
         std::printf("save region %s: kind=%u seat=%u size=%zu from %s\n", r.id.c_str(), r.kind,
                     r.seat, r.size, r.file ? r.file->string().c_str() : "(none)");
@@ -894,11 +938,14 @@ int main(int argc, char** argv) {
                 if (l.frame == k) session.queue_accessory_data(l.seat, l.slot, l.bytes.data(), l.bytes.size());
             }
             session.begin_frame_accessories();
+            if (route && !route->begin()) return false;
             if (const rcore_result rc = core.api->run_frame(); rc != RCORE_OK) {
                 std::fprintf(stderr, "retro-core-runner: run_frame %llu -> %d\n",
                              static_cast<unsigned long long>(k), rc);
                 return false;
             }
+            if (route && !route->end()) return false;
+            if (route && route_stop) break;
         }
         return true;
     };
@@ -924,6 +971,12 @@ int main(int argc, char** argv) {
         std::printf("%s\n", replay_verdict.c_str());
     }
 
+    session.set_route(nullptr);
+    if (route && !route->finish(ok && !sink.faults)) {
+        std::fprintf(stderr,"route: %s\n",route->error().c_str());
+        core.api->unload(); core.api->deinit();
+        return route->exit_code();
+    }
     core.api->unload();
     write_ppm(out / "shot.ppm", sink.last, sink.last_w, sink.last_h);
     session.persist_save_regions();
diff --git a/scripts/route_recover.py b/scripts/route_recover.py
new file mode 100644
index 0000000..96b6f9d
--- /dev/null
+++ b/scripts/route_recover.py
@@ -0,0 +1,72 @@
+"""Copy the complete field prefix of a crashed private route into a sealed file."""
+from __future__ import annotations
+
+import argparse
+import hashlib
+from pathlib import Path
+
+
+def recover(source: Path, destination: Path) -> int:
+    if source.stat().st_size > 256 * 1024 * 1024:
+        raise ValueError('route exceeds 256 MiB')
+    data = source.read_bytes()
+    if b'\nEND ' in data:
+        raise ValueError('route is already sealed')
+    lines = data.splitlines(keepends=True)
+    if not lines or lines[0] != b'RCORE_ROUTE 1\n':
+        raise ValueError('unsupported route header')
+    index, end, count, boot = 1, 0, 0, False
+    while index < len(lines):
+        row = lines[index].split()
+        if not row or not lines[index].endswith(b'\n'):
+            break
+        if row[0] in (b'I', b'A', b'S') and not boot:
+            index += 1
+            continue
+        if row[0] not in (b'B', b'F') or len(row) != 10:
+            raise ValueError(f'invalid field header at line {index + 1}')
+        field, pads, clocks = int(row[1]), int(row[4]), int(row[5])
+        if not 0 <= pads <= 4096 or not 0 <= clocks <= 4096:
+            raise ValueError('invalid callback count')
+        if row[0] == b'B':
+            if boot or field:
+                raise ValueError('invalid boot field')
+        elif not boot or field != count + 1:
+            raise ValueError('field order mismatch')
+        boundary = index + 1 + pads + clocks
+        if boundary > len(lines) or not all(line.endswith(b'\n') for line in lines[index:boundary]):
+            break
+        if any(not line.startswith(b'P ') for line in lines[index + 1:index + 1 + pads]):
+            raise ValueError('invalid pad record')
+        if any(not line.startswith(b'T ') for line in lines[index + 1 + pads:boundary]):
+            raise ValueError('invalid clock record')
+        boot = True
+        if row[0] == b'F':
+            count += 1
+            end = boundary
+        index = boundary
+    if not count:
+        raise ValueError('no complete field to recover')
+    prefix = b''.join(lines[:end])
+    footer = f'END {count} {hashlib.sha256(prefix).hexdigest()}\n'.encode('ascii')
+    # Exclusive creation preserves both the original and any existing output.
+    with destination.open('xb') as output:
+        output.write(prefix)
+        output.write(footer)
+    return count
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('partial', type=Path)
+    parser.add_argument('output', type=Path)
+    args = parser.parse_args()
+    try:
+        frames = recover(args.partial, args.output)
+    except (OSError, ValueError) as error:
+        parser.exit(2, f'recovery refused: {error}\n')
+    print(f'recovered {frames} complete fields; the original is unchanged')
+
+
+if __name__ == '__main__':
+    main()
diff --git a/tests/route_anchor_test.cmake b/tests/route_anchor_test.cmake
new file mode 100644
index 0000000..349b86d
--- /dev/null
+++ b/tests/route_anchor_test.cmake
@@ -0,0 +1,35 @@
+file(MAKE_DIRECTORY "${OUT}")
+file(REMOVE "${OUT}/anchor.route" "${OUT}/anchor.route.partial")
+set(base --core "${CORE}" --rom "${CMAKE_CURRENT_LIST_DIR}/fake_package.txt")
+execute_process(COMMAND "${LINK}" --runner "${RUNNER}" ${base} --frames 12
+    --record-start-at "3:${OUT}/anchor.route" --record-stop-at 10 --out "${OUT}/record"
+    RESULT_VARIABLE rc OUTPUT_VARIABLE output ERROR_VARIABLE err)
+if(NOT rc EQUAL 0 OR NOT output MATCHES "start at 3 state 1" OR NOT output MATCHES "stop at 10 state 2 fields 7")
+    message(FATAL_ERROR "anchor controls: ${rc} ${output} ${err}")
+endif()
+file(READ "${OUT}/anchor.route" movie)
+if(NOT movie MATCHES "\nA [0-9a-f]+ [0-9a-f]+\n")
+    message(FATAL_ERROR "anchor is missing")
+endif()
+execute_process(COMMAND "${RUNNER}" ${base} --frames 20 --play-route "${OUT}/anchor.route"
+    --out "${OUT}/play" RESULT_VARIABLE rc OUTPUT_VARIABLE output ERROR_VARIABLE err)
+file(READ "${OUT}/play/route-verdict.json" verdict)
+if(NOT rc EQUAL 0 OR NOT verdict MATCHES "in_sync" OR NOT verdict MATCHES "\"frames\": 7")
+    message(FATAL_ERROR "anchor replay: ${rc} ${verdict} ${output} ${err}")
+endif()
+# Starting on an existing destination must refuse and leave it unchanged.
+file(SHA256 "${OUT}/anchor.route" original)
+execute_process(COMMAND "${LINK}" --runner "${RUNNER}" ${base} --frames 5
+    --record-start-at "2:${OUT}/anchor.route" --out "${OUT}/existing"
+    RESULT_VARIABLE rc OUTPUT_VARIABLE output ERROR_VARIABLE err)
+file(SHA256 "${OUT}/anchor.route" after)
+if(NOT rc EQUAL 0 OR NOT output MATCHES "state 5.*already exists" OR NOT original STREQUAL after)
+    message(FATAL_ERROR "existing replay protection: ${rc} ${output} ${err}")
+endif()
+execute_process(COMMAND "${LINK}" --runner "${RUNNER}" ${base} --restart-route "${OUT}/anchor.route"
+    --frames 20 --expect-route-end --out "${OUT}/selected"
+    RESULT_VARIABLE rc OUTPUT_VARIABLE output ERROR_VARIABLE err)
+file(READ "${OUT}/selected/route-verdict.json" verdict)
+if(NOT rc EQUAL 0 OR NOT verdict MATCHES "in_sync" OR NOT output MATCHES "7 frame.s. granted and done")
+    message(FATAL_ERROR "selected replay restart: ${rc} ${verdict} ${output} ${err}")
+endif()
diff --git a/tests/route_contract_test.cpp b/tests/route_contract_test.cpp
new file mode 100644
index 0000000..b8af801
--- /dev/null
+++ b/tests/route_contract_test.cpp
@@ -0,0 +1,99 @@
+#include "route.hpp"
+#include <cstdlib>
+#include <cstring>
+#include <iostream>
+
+using namespace retro::runner;
+namespace {
+void check(bool yes) { if (!yes) { std::cerr << "route contract check failed\n"; std::exit(1); } }
+std::uint64_t digest = 0;
+std::uint64_t state_hash() { return digest; }
+const rcore_option* new_options(std::uint32_t* count) {
+    static rcore_option option{};
+    option.struct_size=sizeof option;option.key="new_default";option.default_value="off";
+    *count=1;return &option;
+}
+class TestSink : public Sink {
+public:
+    bool noisy = false;
+    void log(std::uint32_t,const char*) override {}
+    void event(const rcore_event&) override {}
+    void frame(const rcore_frame&) override {}
+    void audio(const std::int16_t*,std::uint32_t) override {}
+    void audio_rate(std::uint32_t) override {}
+    void input(std::uint32_t seat,rcore_pad& pad) override {
+        if(noisy) { pad.connected=1;pad.buttons=0xffffffff;return; }
+        pad.connected = seat % 2;
+        pad.buttons = 1u << seat;
+        for (unsigned i=0;i<RCORE_AXIS_COUNT;++i) pad.axes[i]=std::int16_t(-32768+int(seat*100+i));
+    }
+};
+void drive(Route& route,HostSession& session) {
+    const auto* host=session.host_api();
+    check(host->wall_clock_us(host->host_ctx)>0);
+    check(route.initial_saves());
+    for(unsigned field=1;field<=4;++field) {
+        check(route.begin(640,480));
+        for(unsigned seat=0;seat<RCORE_MAX_SEATS;++seat) {
+            rcore_pad p{}; host->input_get(host->host_ctx,seat,&p);
+            check(p.connected==seat%2 && p.buttons==(1u<<seat));
+            for(unsigned axis=0;axis<RCORE_AXIS_COUNT;++axis) check(p.axes[axis]==-32768+int(seat*100+axis));
+        }
+        check(host->wall_clock_us(host->host_ctx)>0);
+        std::uint32_t pixel=0xff112233+field;
+        rcore_frame frame{};frame.struct_size=sizeof frame;frame.width=frame.height=1;
+        frame.stride=4;frame.pixel_format=RCORE_PIXEL_RGBA8;frame.pixels=&pixel;
+        host->video_submit(host->host_ctx,&frame);
+        std::int16_t samples[]={-32768,32767,-111,123};
+        host->audio_push(host->host_ctx,samples,2);
+        digest=field*7;
+        check(route.end());
+    }
+    session.set_route(nullptr);
+    check(route.finish(true));
+}
+}
+int main(int argc,char** argv) {
+    if(argc!=2)return 2;
+    rcore_pad live[RCORE_MAX_SEATS]{};live[0].connected=1;
+    live[0].axes[0]=8000;check(!Route::live_input(live));
+    live[0].axes[0]=8001;check(Route::live_input(live));
+    live[0].axes[0]=-8001;check(Route::live_input(live));
+    live[0].axes[0]=0;live[0].buttons=1;check(Route::live_input(live));
+    live[0].connected=0;check(!Route::live_input(live));
+    fs::path out=argv[1];fs::create_directories(out);
+    fs::remove(out/"input.route");fs::remove(out/"input.route.partial");
+    rcore_core_info info{};info.struct_size=sizeof info;info.core_id="route_fixture";info.core_version="1";
+    rcore_core_api api{};api.struct_size=sizeof api;api.state_hash=state_hash;
+    LoadedCore core;core.api=&api;core.info=&info;core.sha256="fixture";
+    TestSink sink;
+    rcore_save_region region{};region.struct_size=sizeof region;region.id="battery";region.size=16;region.erase_value=0x7a;
+    RouteArgs args;args.record=out/"input.route";args.runner=fs::absolute(argv[0]);args.marks[2]="gameplay";
+    HostSession recording(core,sink);std::string error;check(recording.set_options({},&error));
+    recording.adopt_save_regions(&region,1,{});
+    Route recorder(core,recording,args,out);check(recorder.open(argv[0],"",".",false));recording.set_route(&recorder);
+    drive(recorder,recording);
+    HostSession playing(core,sink);check(playing.set_options({},&error));playing.adopt_save_regions(&region,1,{});
+    sink.noisy=true;
+    std::memset(playing.save_regions()[0].data,0,16);
+    args.play=args.record;args.record.clear();
+    Route player(core,playing,args,out);check(player.open(argv[0],"",".",false));playing.set_route(&player);
+    drive(player,playing);
+    for(unsigned i=0;i<16;++i)check(playing.save_regions()[0].data[i]==0x7a);
+    auto newer_api=api;newer_api.options=new_options;
+    auto newer=core;newer.api=&newer_api;newer.sha256="newer_fixture";
+    HostSession upgraded(newer,sink);check(upgraded.set_options({},&error));upgraded.adopt_save_regions(&region,1,{});
+    args.allow_core_change=true;
+    Route upgrade(newer,upgraded,args,out);check(upgrade.open(argv[0],"",".",false));upgraded.set_route(&upgrade);
+    drive(upgrade,upgraded);
+    HostSession changed(newer,sink);check(changed.set_options({{"new_default","on"}},&error));
+    Route invalid(newer,changed,args,out);check(!invalid.open(argv[0],"",".",false));
+    const auto reference=args.runner;
+    args.runner=out/"alternate-runner";std::ofstream(args.runner) << "alternate host fixture";
+    args.runner_reference=reference;
+    HostSession reference_session(core,sink);check(reference_session.set_options({},&error));
+    Route compatible(core,reference_session,args,out);check(compatible.open(argv[0],"",".",false));
+    args.runner_reference=args.runner;
+    Route wrong_reference(core,reference_session,args,out);check(!wrong_reference.open(argv[0],"",".",false));
+    std::cout << "8 seats, 6 axes, clocks, save restoration, state, audio and picture replay pass\n";
+}
diff --git a/tests/route_recover_test.py b/tests/route_recover_test.py
new file mode 100644
index 0000000..5b3f5f9
--- /dev/null
+++ b/tests/route_recover_test.py
@@ -0,0 +1,49 @@
+"""Check crash-prefix recovery without retail data or external packages."""
+import importlib.util
+import tempfile
+import unittest
+from pathlib import Path
+
+spec = importlib.util.spec_from_file_location('route_recover', Path(__file__).resolve().parents[1] / 'scripts' / 'route_recover.py')
+module = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(module)
+
+
+class RecoveryTest(unittest.TestCase):
+    def test_complete_prefix_and_preserved_source(self):
+        import hashlib
+        with tempfile.TemporaryDirectory() as folder:
+            source, output = Path(folder) / 'movie.partial', Path(folder) / 'recovered.route'
+            prefix = (b'RCORE_ROUTE 1\nI 726f6d 74657374\nB 0 0 0 0 0 - - - -\n'
+                      b'F 1 0 0 1 1 2d 2d 2d -\nP 0 1 0 0 0 0 0 0 0\nT 7\n')
+            data = prefix + b'F 2 0 0 1 1 2d 2d 2d -\nP 0 1 0 0 0'
+            source.write_bytes(data)
+            self.assertEqual(module.recover(source, output), 1)
+            self.assertEqual(output.read_bytes(), prefix + f'END 1 {hashlib.sha256(prefix).hexdigest()}\n'.encode())
+            self.assertEqual(source.read_bytes(), data)
+            with self.assertRaises(FileExistsError):
+                module.recover(source, output)
+
+    def test_anchor_prefix_is_preserved(self):
+        with tempfile.TemporaryDirectory() as folder:
+            source, output = Path(folder) / 'movie.partial', Path(folder) / 'recovered.route'
+            prefix = (b'RCORE_ROUTE 1\nA 2d 46414b45\nB 0 0 0 0 0 - - - -\n'
+                      b'F 1 0 0 0 0 2d 2d 2d -\n')
+            source.write_bytes(prefix)
+            self.assertEqual(module.recover(source, output), 1)
+            self.assertTrue(output.read_bytes().startswith(prefix))
+            self.assertEqual(source.read_bytes(), prefix)
+
+    def test_invalid_and_empty_prefixes_refuse(self):
+        with tempfile.TemporaryDirectory() as folder:
+            source, output = Path(folder) / 'movie.partial', Path(folder) / 'recovered.route'
+            for data in (b'bad\n', b'RCORE_ROUTE 1\n', b'RCORE_ROUTE 1\nEND 0 bad\n',
+                         b'RCORE_ROUTE 1\nB 0 0 0 0 0 - - - -\nF 3 0 0 0 0 - - - -\n'):
+                source.write_bytes(data)
+                with self.assertRaises(ValueError):
+                    module.recover(source, output)
+                self.assertFalse(output.exists())
+
+
+if __name__ == '__main__':
+    unittest.main()
diff --git a/tests/route_test.cmake b/tests/route_test.cmake
new file mode 100644
index 0000000..77ab31d
--- /dev/null
+++ b/tests/route_test.cmake
@@ -0,0 +1,66 @@
+file(MAKE_DIRECTORY "${OUT}")
+file(REMOVE "${OUT}/test.route" "${OUT}/test.route.partial" "${OUT}/link.route" "${OUT}/link.route.partial")
+set(base --core "${CORE}" --rom "${CMAKE_CURRENT_LIST_DIR}/fake_package.txt")
+execute_process(COMMAND "${RUNNER}" ${base} --frames 8 --record-route "${OUT}/test.route"
+    --route-mark 4:menu --out "${OUT}/record" RESULT_VARIABLE rc OUTPUT_QUIET ERROR_VARIABLE err)
+if(NOT rc EQUAL 0)
+    message(FATAL_ERROR "record: ${rc} ${err}")
+endif()
+execute_process(COMMAND "${RUNNER}" ${base} --play-route "${OUT}/test.route"
+    --out "${OUT}/play" RESULT_VARIABLE rc OUTPUT_QUIET ERROR_VARIABLE err)
+if(NOT rc EQUAL 0)
+    message(FATAL_ERROR "play: ${rc} ${err}")
+endif()
+file(READ "${OUT}/play/route-verdict.json" verdict)
+if(NOT verdict MATCHES "in_sync" OR NOT EXISTS "${OUT}/play/route-4.ppm")
+    message(FATAL_ERROR "missing successful verdict or marker picture")
+endif()
+execute_process(COMMAND "${RUNNER}" ${base} --play-route "${OUT}/test.route"
+    --opt audio.mute=1 --out "${OUT}/identity" RESULT_VARIABLE rc OUTPUT_QUIET ERROR_VARIABLE err)
+if(NOT rc EQUAL 2 OR NOT err MATCHES "identity mismatch")
+    message(FATAL_ERROR "changed identity did not refuse: ${rc} ${err}")
+endif()
+file(READ "${OUT}/test.route" movie)
+string(FIND "${movie}" "\nEND " end)
+math(EXPR end "${end}+1")
+string(SUBSTRING "${movie}" 0 ${end} prefix)
+file(WRITE "${OUT}/truncated.route" "${prefix}")
+execute_process(COMMAND "${RUNNER}" ${base} --play-route "${OUT}/truncated.route"
+    --out "${OUT}/truncated" RESULT_VARIABLE rc OUTPUT_QUIET ERROR_VARIABLE err)
+if(NOT rc EQUAL 2 OR NOT err MATCHES "incomplete")
+    message(FATAL_ERROR "truncated route did not refuse: ${rc} ${err}")
+endif()
+# Reseal an intentionally wrong first checkpoint to exercise the actual
+# runtime divergence verdict, rather than only the file checksum check.
+string(REPLACE "F 1 0 0 0 0 2d " "F 1 0 0 0 0 626164 " changed "${prefix}")
+string(SHA256 digest "${changed}")
+file(WRITE "${OUT}/rewrite.tmp" "${changed}END 8 ${digest}\n")
+configure_file("${OUT}/rewrite.tmp" "${OUT}/divergence.route" @ONLY NEWLINE_STYLE UNIX)
+execute_process(COMMAND "${RUNNER}" ${base} --play-route "${OUT}/divergence.route"
+    --out "${OUT}/divergence" RESULT_VARIABLE rc OUTPUT_QUIET ERROR_VARIABLE err)
+if(NOT rc EQUAL 5 OR NOT err MATCHES "field 1")
+    message(FATAL_ERROR "changed checkpoint did not diverge: ${rc} ${err}")
+endif()
+# A semantically invalid field with a valid checksum must not reach the core.
+string(REPLACE "F 1 " "F 9 " changed "${prefix}")
+string(SHA256 digest "${changed}")
+file(WRITE "${OUT}/rewrite.tmp" "${changed}END 8 ${digest}\n")
+configure_file("${OUT}/rewrite.tmp" "${OUT}/malformed.route" @ONLY NEWLINE_STYLE UNIX)
+execute_process(COMMAND "${RUNNER}" ${base} --play-route "${OUT}/malformed.route"
+    --out "${OUT}/malformed" RESULT_VARIABLE rc OUTPUT_QUIET ERROR_VARIABLE err)
+if(NOT rc EQUAL 2 OR NOT err MATCHES "field order mismatch")
+    message(FATAL_ERROR "malformed route did not refuse: ${rc} ${err}")
+endif()
+# A real link session uses precisely the same recorder as headless playback.
+execute_process(COMMAND "${CMAKE_COMMAND}" -E env "RETRO_RECORD_ROUTE=${OUT}/link.route"
+    "${LINK}" --runner "${RUNNER}" ${base} --frames 8 --out "${OUT}/link-record"
+    RESULT_VARIABLE rc OUTPUT_QUIET ERROR_VARIABLE err)
+if(NOT rc EQUAL 0)
+    message(FATAL_ERROR "link recording: ${rc} ${err}")
+endif()
+execute_process(COMMAND "${RUNNER}" ${base} --play-route "${OUT}/link.route"
+    --out "${OUT}/link-play" RESULT_VARIABLE rc OUTPUT_QUIET ERROR_VARIABLE err)
+if(NOT rc EQUAL 0)
+    message(FATAL_ERROR "link to headless replay: ${rc} ${err}")
+endif()
+message(STATUS "routes: fresh process, link recording, identity/truncation/grammar refusals and first divergence pass")
diff --git a/tests/route_watch_test.cmake b/tests/route_watch_test.cmake
new file mode 100644
index 0000000..0b555e0
--- /dev/null
+++ b/tests/route_watch_test.cmake
@@ -0,0 +1,56 @@
+file(MAKE_DIRECTORY "${OUT}")
+file(REMOVE "${OUT}/watch.route" "${OUT}/watch.route.partial")
+set(base --core "${CORE}" --rom "${CMAKE_CURRENT_LIST_DIR}/fake_package.txt")
+execute_process(COMMAND "${RUNNER}" ${base} --frames 8 --record-route "${OUT}/watch.route"
+    --out "${OUT}/record" RESULT_VARIABLE rc OUTPUT_QUIET ERROR_VARIABLE err)
+if(NOT rc EQUAL 0)
+    message(FATAL_ERROR "watch fixture record: ${rc} ${err}")
+endif()
+string(REPEAT "u" 64 original_save)
+file(WRITE "${OUT}/battery" "${original_save}")
+execute_process(COMMAND "${CMAKE_COMMAND}" -E env "RETRO_PLAY_ROUTE=${OUT}/watch.route"
+    "${LINK}" --runner "${RUNNER}" ${base} --frames 20 --expect-route-end
+    --save "battery=${OUT}/battery" --input-script 1:a+left --out "${OUT}/complete"
+    RESULT_VARIABLE rc OUTPUT_VARIABLE stdout ERROR_VARIABLE err)
+if(NOT rc EQUAL 0 OR NOT stdout MATCHES "8 frame.s. granted and done")
+    message(FATAL_ERROR "watch completion: ${rc} ${stdout} ${err}")
+endif()
+file(READ "${OUT}/complete/route-verdict.json" verdict)
+file(READ "${OUT}/battery" saved)
+if(NOT verdict MATCHES "in_sync" OR NOT saved STREQUAL original_save)
+    message(FATAL_ERROR "watch changed save or failed: ${verdict}")
+endif()
+execute_process(COMMAND "${CMAKE_COMMAND}" -E env "RETRO_PLAY_ROUTE=${OUT}/watch.route"
+    "${LINK}" --runner "${RUNNER}" ${base} --frames 3 --out "${OUT}/stop"
+    RESULT_VARIABLE rc OUTPUT_QUIET ERROR_VARIABLE err)
+file(READ "${OUT}/stop/route-verdict.json" verdict)
+if(NOT rc EQUAL 0 OR NOT verdict MATCHES "stopped")
+    message(FATAL_ERROR "watch Quit: ${rc} ${verdict} ${err}")
+endif()
+foreach(input IN ITEMS a left)
+    execute_process(COMMAND "${CMAKE_COMMAND}" -E env "RETRO_PLAY_ROUTE=${OUT}/watch.route" RETRO_ROUTE_TAKEOVER=1
+        "${LINK}" --runner "${RUNNER}" ${base} --frames 12
+        --input-script "1:a,3:none,5:${input}" --out "${OUT}/takeover-${input}"
+        RESULT_VARIABLE rc OUTPUT_VARIABLE stdout ERROR_VARIABLE err)
+    file(READ "${OUT}/takeover-${input}/route-verdict.json" verdict)
+    if(NOT rc EQUAL 0 OR NOT verdict MATCHES "taken_over" OR NOT verdict MATCHES "\"takeover_frame\": 5"
+       OR NOT stdout MATCHES "12 frame.s. granted and done" OR NOT stdout MATCHES "picture: first byte 12")
+        message(FATAL_ERROR "watch takeover ${input}: ${rc} ${verdict} ${stdout} ${err}")
+    endif()
+endforeach()
+file(READ "${OUT}/watch.route" movie)
+string(FIND "${movie}" "\nEND " boundary)
+math(EXPR boundary "${boundary}+1")
+string(SUBSTRING "${movie}" 0 ${boundary} prefix)
+string(REPLACE "F 1 0 0 0 0 2d " "F 1 0 0 0 0 626164 " changed "${prefix}")
+string(SHA256 digest "${changed}")
+file(WRITE "${OUT}/rewrite.tmp" "${changed}END 8 ${digest}\n")
+configure_file("${OUT}/rewrite.tmp" "${OUT}/wrong.route" @ONLY NEWLINE_STYLE UNIX)
+execute_process(COMMAND "${CMAKE_COMMAND}" -E env "RETRO_PLAY_ROUTE=${OUT}/wrong.route"
+    "${LINK}" --runner "${RUNNER}" ${base} --frames 20 --expect-route-end --out "${OUT}/mismatch"
+    RESULT_VARIABLE rc OUTPUT_QUIET ERROR_VARIABLE err)
+file(READ "${OUT}/mismatch/route-verdict.json" verdict)
+if(rc EQUAL 0 OR NOT verdict MATCHES "diverged" OR NOT verdict MATCHES "\"first_divergence\": 1")
+    message(FATAL_ERROR "watch mismatch: ${rc} ${verdict} ${err}")
+endif()
+message(STATUS "watch: end, Quit, input authority, private saves, neutral arming and button/analog takeover pass")