From e0f0e7594c7da853a4751b6f27ad0c11ce0db065 Mon Sep 17 00:00:00 2001
From: dayfine <difancpa@gmail.com>
Date: Mon, 9 Nov 2026 10:58:42 -0800
Subject: [PATCH 1/5] AutoStory: save stream history, screenshot and JSON when
 an event fails

A story failure throws with NO_ERROR_REPORT, so no error report (and no
Video.mp4) was written for it, and a retry reloaded the game before anyone
saw the failure frame. SegmentHooks gets a `failed` hook, told of each failed
attempt and verify run before any reload. FailureCapture attaches to it and
saves USER_FILE_PATH()/<game>/AutoStoryFailures/<time>-<checkpoint>-<event>/
with Video.mp4 (stream history), Screenshot.png and Failure.json, whatever
the error-report send mode; save_thrown() covers exceptions out of the run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss
---
 .../ComputerPrograms_UnitTestRunner.cpp       |   1 +
 .../Pokemon_AutoStoryFailureCapture.cpp       | 149 ++++++++++++++++++
 .../Pokemon_AutoStoryFailureCapture.h         |  89 +++++++++++
 .../Pokemon_AutoStoryFailureCapture_Tests.cpp | 105 ++++++++++++
 .../AutoStory/Pokemon_AutoStory_Tests.h       |   2 +
 .../AutoStory/Pokemon_StorySegments.cpp       |   8 +
 .../Pokemon/AutoStory/Pokemon_StorySegments.h |   5 +
 .../AutoStory/Pokemon_StorySegments_Tests.cpp |  33 ++++
 SerialPrograms/cmake/SourceFiles.cmake        |   3 +
 9 files changed, 395 insertions(+)
 create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture.cpp
 create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture.h
 create mode 100644 SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture_Tests.cpp

diff --git a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
index 2f878a6551..e0f8e79b96 100644
--- a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
+++ b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
@@ -86,6 +86,7 @@ UnitTestDatabase make_UNIT_TESTS_ALL(){
     Pokemon::add_tests_StoryEvents(ret);
     Pokemon::add_tests_StorySegments(ret);
     Pokemon::add_tests_StorySteps(ret);
+    Pokemon::add_tests_AutoStoryFailureCapture(ret);
     Pokemon::add_tests_StoryStepJson(ret);
     Pokemon::add_tests_AuthoredCheckpointJson(ret);
     NintendoSwitch::add_tests_CheckOnlineDetector(ret);
diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture.cpp
new file mode 100644
index 0000000000..a52aa220c0
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture.cpp
@@ -0,0 +1,149 @@
+/*  AutoStory Failure Capture
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ */
+
+#include <utility>
+#include "Common/Cpp/Color.h"
+#include "Common/Cpp/Exceptions.h"
+#include "Common/Cpp/Filesystem/Filesystem.h"
+#include "Common/Cpp/Json/JsonArray.h"
+#include "Common/Cpp/Json/JsonValue.h"
+#include "Common/Cpp/Logging/GlobalLogger.h"
+#include "Common/Cpp/Logging/LastLogTracker.h"
+#include "Common/Cpp/PrettyPrint.h"
+#include "CommonFramework/GlobalAutoPaths.h"
+#include "CommonFramework/ImageTypes/ImageRGB32.h"
+#include "CommonFramework/Recording/StreamHistorySession.h"
+#include "CommonFramework/VideoPipeline/VideoFeed.h"
+#include "Pokemon_AutoStoryFailureCapture.h"
+
+namespace PokemonAutomation{
+namespace Pokemon{
+
+
+namespace{
+
+//  Log lines kept in Failure.json.
+constexpr size_t LOG_LINES = 30;
+
+bool folder_safe(char c){
+    return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9')
+        || c == '.' || c == '-' || c == '_';
+}
+
+std::string folder_safe(std::string_view text){
+    std::string safe(text);
+    for (char& c : safe){
+        if (!folder_safe(c)){
+            c = '_';
+        }
+    }
+    return safe;
+}
+
+std::vector<std::string> recent_log(){
+    std::vector<std::string> lines;
+    for (const LogLine& line : global_last_log_history().get_recent(LOG_LINES)){
+        lines.push_back(line.text);
+    }
+    return lines;
+}
+
+} // namespace
+
+
+std::string failure_folder_name(std::string_view time, const FailureRecord& record){
+    const std::string_view event = record.event.empty() ? std::string_view("checkpoint") : std::string_view(record.event);
+    return folder_safe(time) + "-" + folder_safe(record.checkpoint) + "-" + folder_safe(event);
+}
+
+JsonObject failure_json(const FailureRecord& record){
+    JsonObject json;
+    json["game"] = record.game;
+    json["checkpoint"] = record.checkpoint;
+    json["event"] = record.event;
+    json["error"] = record.error;
+    JsonArray log;
+    for (const std::string& line : record.log){
+        log.push_back(line);
+    }
+    json["log"] = std::move(log);
+    return json;
+}
+
+StatusStep step_of_status(std::string_view line){
+    const size_t space = line.find(' ');
+    const size_t slash = line.find('/');
+    if (space == std::string_view::npos || slash == std::string_view::npos || slash > space){
+        return {};
+    }
+    const size_t colon = line.find(':', space + 1);
+    if (colon == std::string_view::npos){
+        return {};
+    }
+    return StatusStep{
+        std::string(line.substr(0, slash)),
+        std::string(line.substr(space + 1, colon - space - 1)),
+    };
+}
+
+
+FailureCapture::FailureCapture(VideoStream& stream, std::string game)
+    : m_stream(stream)
+    , m_game(std::move(game))
+{}
+
+void FailureCapture::attach(SegmentHooks& hooks){
+    hooks.status = [this, status = std::move(hooks.status)](const std::string& line){
+        StatusStep step = step_of_status(line);
+        if (!step.checkpoint.empty()){
+            m_last_step = std::move(step);
+        }
+        if (status){
+            status(line);
+        }
+    };
+    hooks.failed = [this](const std::string& checkpoint, const std::string& event, const Outcome& failure){
+        save(checkpoint, event, to_string(failure));
+    };
+}
+
+void FailureCapture::save_thrown(const std::string& error){
+    const std::string checkpoint = m_last_step.checkpoint.empty() ? "unknown" : m_last_step.checkpoint;
+    save(checkpoint, m_last_step.event, error);
+}
+
+std::string FailureCapture::save(const std::string& checkpoint, const std::string& event, const std::string& error){
+    try{
+        const VideoSnapshot snapshot = m_stream.video().snapshot();
+        FailureRecord record{m_game, checkpoint, event, error, recent_log()};
+        const std::string folder = USER_FILE_PATH() + m_game + "/AutoStoryFailures/"
+            + failure_folder_name(now_to_filestring(), record) + "/";
+        Filesystem::create_directories(Filesystem::Path(folder));
+        if (!Filesystem::is_directory(Filesystem::Path(folder))){
+            m_stream.log("AutoStory failure capture: cannot make " + folder, COLOR_RED);
+            return "";
+        }
+        if (!snapshot || !snapshot->save(folder + "Screenshot.png")){
+            m_stream.log("AutoStory failure capture: no screenshot.", COLOR_ORANGE);
+        }
+        JsonValue(failure_json(record)).dump(folder + "Failure.json");
+        if (!m_stream.save_stream_history(folder + "Video.mp4")){
+            m_stream.log("AutoStory failure capture: no video (is Stream History on?).", COLOR_ORANGE);
+        }
+        m_stream.log("AutoStory failure capture: " + folder, COLOR_BLUE);
+        return folder;
+    }catch (Exception& e){
+        m_stream.log("AutoStory failure capture failed: " + e.message(), COLOR_RED);
+    }catch (std::exception& e){
+        m_stream.log(std::string("AutoStory failure capture failed: ") + e.what(), COLOR_RED);
+    }
+    return "";
+}
+
+
+
+} // namespace Pokemon
+} // namespace PokemonAutomation
diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture.h
new file mode 100644
index 0000000000..0e2d951f25
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture.h
@@ -0,0 +1,89 @@
+/*  AutoStory Failure Capture
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ *  What a failed AutoStory event leaves behind, whatever the error-report
+ *  settings say (a story failure throws with NO_ERROR_REPORT, so no error
+ *  report is written for it): the stream history as a video, the frame on
+ *  screen and a short JSON, in
+ *
+ *      USER_FILE_PATH()/<game>/AutoStoryFailures/<time>-<checkpoint>-<event>/
+ *          Video.mp4       the stream history, when its setting is on
+ *          Screenshot.png  the frame on screen when the event failed
+ *          Failure.json    game, checkpoint, event, error, the last log lines
+ *
+ *  The video holds the whole stream history (the "Stream History" setting's
+ *  seconds), saved before the reload. Pokemon_FrameReplay.h says how to cut
+ *  the seconds before the failure into a frame-replay fixture.
+ *
+ */
+
+#ifndef PokemonAutomation_Pokemon_AutoStoryFailureCapture_H
+#define PokemonAutomation_Pokemon_AutoStoryFailureCapture_H
+
+#include <string>
+#include <string_view>
+#include <vector>
+#include "Common/Cpp/Json/JsonObject.h"
+#include "CommonFramework/Tools/VideoStream.h"
+#include "Pokemon_StorySegments.h"
+
+namespace PokemonAutomation{
+namespace Pokemon{
+
+
+//  One failure, as Failure.json holds it.
+struct FailureRecord{
+    std::string game;
+    std::string checkpoint;
+    std::string event;
+    std::string error;
+    //  The last log lines before the failure, oldest first.
+    std::vector<std::string> log;
+};
+
+//  "<time>-<checkpoint>-<event>", each character a folder name can't hold
+//  made "_". An empty event (a start or end check failed) is "checkpoint".
+std::string failure_folder_name(std::string_view time, const FailureRecord& record);
+
+JsonObject failure_json(const FailureRecord& record);
+
+//  The checkpoint and event a status line names:
+//  "00.03/2 below_oaks_trigger: start" names 00.03 and below_oaks_trigger.
+//  Both empty for a line that names no event ("00: start, 3 checkpoints").
+struct StatusStep{
+    std::string checkpoint;
+    std::string event;
+};
+StatusStep step_of_status(std::string_view line);
+
+
+//  Saves a capture for each failed event of the run it is attached to.
+class FailureCapture{
+public:
+    //  `game` names the folder under USER_FILE_PATH(): "PokemonBDSP".
+    FailureCapture(VideoStream& stream, std::string game);
+
+    //  Sets `hooks.failed`, and wraps `hooks.status` to remember the step
+    //  under way for save_thrown(). Must outlive the hooks.
+    void attach(SegmentHooks& hooks);
+
+    //  For an exception out of the run, saved under the last step a status
+    //  line named.
+    void save_thrown(const std::string& error);
+
+    //  Writes the folder and returns its path, or "" if it couldn't be
+    //  made. Logs what it skipped; never throws.
+    std::string save(const std::string& checkpoint, const std::string& event, const std::string& error);
+
+private:
+    VideoStream& m_stream;
+    std::string m_game;
+    StatusStep m_last_step;
+};
+
+
+
+} // namespace Pokemon
+} // namespace PokemonAutomation
+#endif
diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture_Tests.cpp
new file mode 100644
index 0000000000..0574a9db5f
--- /dev/null
+++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture_Tests.cpp
@@ -0,0 +1,105 @@
+/*  AutoStory Failure Capture Tests
+ *
+ *  From: https://github.com/PokemonAutomation/
+ *
+ *  The pure parts of the failure capture: its folder names, its JSON and
+ *  the step a status line names. Saving needs a console's stream.
+ *
+ */
+
+#include <string>
+#include "Common/Cpp/Json/JsonArray.h"
+#include "Common/Cpp/Json/JsonValue.h"
+#include "Common/Cpp/TestRunners/UnitTest.h"
+#include "Pokemon_AutoStoryFailureCapture.h"
+#include "Pokemon_AutoStory_Tests.h"
+
+namespace PokemonAutomation{
+namespace Pokemon{
+
+
+namespace{
+
+FailureRecord oaks_lab_failure(){
+    return FailureRecord{
+        "PokemonFRLG", "00.27", "walk_to_oak", "expect_failed: dialogue opened",
+        {"[Event] 00.27/3 walk_to_oak: start", "[Event] 00.27/3 walk_to_oak: failed"},
+    };
+}
+
+UnitTestResult test_folder_name(){
+    FailureRecord record = oaks_lab_failure();
+    std::string name = failure_folder_name("20261109-110102123456", record);
+    if (name != "20261109-110102123456-00.27-walk_to_oak"){
+        return "Unexpected folder name: " + name;
+    }
+    record.event = "";
+    name = failure_folder_name("t", record);
+    if (name != "t-00.27-checkpoint"){
+        return "A failed check should be named \"checkpoint\": " + name;
+    }
+    record.checkpoint = "00/27";
+    record.event = "talk: Oak?";
+    name = failure_folder_name("t", record);
+    if (name != "t-00_27-talk__Oak_"){
+        return "Characters a folder can't hold should be \"_\": " + name;
+    }
+    return true;
+}
+
+UnitTestResult test_json(){
+    const JsonObject json = failure_json(oaks_lab_failure());
+    if (json.get_string_throw("game") != "PokemonFRLG"
+        || json.get_string_throw("checkpoint") != "00.27"
+        || json.get_string_throw("event") != "walk_to_oak"
+        || json.get_string_throw("error") != "expect_failed: dialogue opened"
+    ){
+        return "Unexpected fields: " + JsonValue(json.clone()).dump();
+    }
+    const JsonArray& log = json.get_array_throw("log");
+    if (log.size() != 2 || log[1].to_string_throw() != "[Event] 00.27/3 walk_to_oak: failed"){
+        return "Expected the log lines, oldest first: " + JsonValue(json.clone()).dump();
+    }
+    return true;
+}
+
+UnitTestResult test_step_of_status(){
+    StatusStep step = step_of_status("00.03/2 below_oaks_trigger: start");
+    if (step.checkpoint != "00.03" || step.event != "below_oaks_trigger"){
+        return "Expected 00.03 below_oaks_trigger, got \"" + step.checkpoint + "\" \"" + step.event + "\"";
+    }
+    for (const char* line : {"00: start, 3 checkpoints", "00.02: passed on attempt 1 (one-shot)", "", "a/b"}){
+        step = step_of_status(line);
+        if (!step.checkpoint.empty() || !step.event.empty()){
+            return std::string("Expected no step in \"") + line + "\"";
+        }
+    }
+    return true;
+}
+
+class Test_AutoStoryFailureCapture : public UnitTest{
+public:
+    Test_AutoStoryFailureCapture(const std::string& name, UnitTestResult (*test)())
+        : UnitTest("Pokemon::AutoStoryFailureCapture - " + name)
+        , m_test(test)
+    {}
+    virtual UnitTestResult run(Logger&, CancellableScope&) const override{
+        return m_test();
+    }
+
+private:
+    UnitTestResult (*m_test)();
+};
+
+} // namespace
+
+
+void add_tests_AutoStoryFailureCapture(UnitTestDatabase& database){
+    database.add<Test_AutoStoryFailureCapture>("folder name", test_folder_name);
+    database.add<Test_AutoStoryFailureCapture>("json", test_json);
+    database.add<Test_AutoStoryFailureCapture>("step of a status line", test_step_of_status);
+}
+
+
+} // namespace Pokemon
+} // namespace PokemonAutomation
diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h
index 10c5ab8848..81771a47d9 100644
--- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h
+++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h
@@ -31,6 +31,8 @@ void add_tests_StoryEvents(UnitTestDatabase& database);
 void add_tests_StorySegments(UnitTestDatabase& database);
 // Registers unit tests for high-level story step dispatching and table conversion.
 void add_tests_StorySteps(UnitTestDatabase& database);
+//  The failure capture's folder names, its JSON and the step a status line names.
+void add_tests_AutoStoryFailureCapture(UnitTestDatabase& database);
 
 
 
diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.cpp
index e217d6ce0b..ea28de777d 100644
--- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.cpp
+++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.cpp
@@ -102,6 +102,12 @@ Outcome reload(RunState& state, SegmentHooks& hooks){
     return outcome_ok();
 }
 
+void tell_failed(SegmentHooks& hooks, const std::string& checkpoint, const CheckpointReport& result){
+    if (hooks.failed){
+        hooks.failed(checkpoint, result.failed_name, result.failure);
+    }
+}
+
 //  The policy's in-place recovery, after each event's own: the game's
 //  recover hook, if any, then the event again. Counts into `used`.
 void add_policy_recoveries(Checkpoint& checkpoint, const SegmentPolicy& policy, SegmentHooks& hooks, size_t& used){
@@ -155,6 +161,7 @@ CheckpointReport run_row(
             ));
             return result;
         }
+        tell_failed(hooks, spec.id, result);
         if (policy.stop_at_first_failure){
             say(hooks, std::format(
                 "[Segment] {}: {} failed; stopping at the first failure, the game stays where it failed",
@@ -250,6 +257,7 @@ bool verify_run(
         say(hooks, std::format("[Verify] {}: run {}/{} passed", spec.id, run, policy.runs));
         return true;
     }
+    tell_failed(hooks, spec.id, result);
     say(hooks, std::format(
         "[Verify] {}: run {}/{} failed{}: {}",
         spec.id, run, policy.runs,
diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.h
index 8e2426aee8..95b14bb4a3 100644
--- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.h
+++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments.h
@@ -60,6 +60,11 @@ struct SegmentHooks{
     //  overlay, so whoever watches the stream sees the step under way; and,
     //  once run records land (#132), for the run's events.
     EventLogger status;
+    //  Optional: told of each failed checkpoint attempt and verify run, by
+    //  checkpoint, event (empty when no event failed) and failure, right
+    //  after it fails: before any reload, while the screen still shows it.
+    //  An exception out of an event goes on to the game instead.
+    MoveOnlyFunction<void(const std::string& checkpoint, const std::string& event, const Outcome& failure)> failed;
 };
 
 // Retry and timeout configuration for story segment execution.
diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments_Tests.cpp
index 4575d6d396..2d4e812b7b 100644
--- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments_Tests.cpp
+++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments_Tests.cpp
@@ -405,6 +405,35 @@ UnitTestResult test_describe(){
     return true;
 }
 
+//  The failed hook hears of each failed attempt and verify run, before the
+//  reload that would take the failure off the screen.
+UnitTestResult test_failed_hook_before_reload(){
+    Lab lab;
+    lab.world.walk_failures = 10;
+    Segment segment = twinleaf_to_sandgem(lab.world);
+    SegmentHooks hooks = lab.hooks();
+    hooks.failed = [&lab](const std::string& checkpoint, const std::string& event, const Outcome& failure){
+        lab.world.trace.push_back("failed " + checkpoint + " " + event + " " + to_string(failure));
+    };
+    RunState state;
+    run_segment(state, segment, SegmentRange{}, SegmentPolicy{.attempts_per_checkpoint = 2}, hooks);
+    const std::string failed = "failed 00.02 walk_south blocked: a wanderer on the path";
+    const std::vector<std::string> expected = {"walk_out", "save", "walk_south", failed, "reload", "walk_south", failed};
+    if (lab.world.trace != expected){
+        return "Expected each failed attempt told before its reload:" + lab.all();
+    }
+    lab.world.trace.clear();
+    lab.world.walk_failures = 1;
+    lab.saved = lab.world;
+    lab.saved.map = "Route 201";
+    lab.world.map = "Route 201";
+    verify_checkpoint(state, segment, "00.02", VerifyPolicy{}, hooks);
+    if (lab.world.trace.size() < 2 || lab.world.trace[1] != failed){
+        return "Expected the failed verify run told:" + lab.all();
+    }
+    return true;
+}
+
 
 struct StorySegmentInput{
     std::string name;
@@ -435,6 +464,10 @@ class Test_StorySegments : public UnitTest{
 };
 
 const StorySegmentTestCase STORY_SEGMENT_CASES[] = {
+    {
+        .input = {.name = "failed hook before reload", .test = test_failed_hook_before_reload},
+        .expectation = {.description = "tells the game of each failed attempt while the failure is on screen"},
+    },
     {
         .input = {.name = "checkpoints run in order", .test = test_runs_checkpoints_in_order},
         .expectation = {.description = "executes sequential checkpoints and saves state"},
diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake
index fc888392dc..46f0b4bc57 100644
--- a/SerialPrograms/cmake/SourceFiles.cmake
+++ b/SerialPrograms/cmake/SourceFiles.cmake
@@ -1493,6 +1493,9 @@ file(GLOB LIBRARY_SOURCES
     Source/Pokemon/Options/Pokemon_StatsHuntFilter.h
     Source/Pokemon/Options/Pokemon_StoryRunOptions.cpp
     Source/Pokemon/Options/Pokemon_StoryRunOptions.h
+    Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture.cpp
+    Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture.h
+    Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture_Tests.cpp
     Source/Pokemon/AutoStory/Pokemon_AutoStorySelect.h
     Source/Pokemon/AutoStory/Pokemon_AutoStorySelect_Tests.cpp
     Source/Pokemon/AutoStory/Pokemon_AutoStorySelect_Tests.h

From a4fba9355f1fdae27a50b7cf0e09607f3c8d5c98 Mon Sep 17 00:00:00 2001
From: dayfine <difancpa@gmail.com>
Date: Mon, 9 Nov 2026 10:59:10 -0800
Subject: [PATCH 2/5] AutoStory: failure capture's status wrapper calls the
 game's status sink

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss
---
 .../Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture.cpp       | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture.cpp
index a52aa220c0..02e5195c20 100644
--- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture.cpp
+++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture.cpp
@@ -96,7 +96,7 @@ FailureCapture::FailureCapture(VideoStream& stream, std::string game)
 {}
 
 void FailureCapture::attach(SegmentHooks& hooks){
-    hooks.status = [this, status = std::move(hooks.status)](const std::string& line){
+    hooks.status = [this, status = std::move(hooks.status)](const std::string& line) mutable{
         StatusStep step = step_of_status(line);
         if (!step.checkpoint.empty()){
             m_last_step = std::move(step);

From 841e0aee2cc4bd0c0f9d776e5a20ab1df446c228 Mon Sep 17 00:00:00 2001
From: dayfine <difancpa@gmail.com>
Date: Mon, 9 Nov 2026 11:00:08 -0800
Subject: [PATCH 3/5] AutoStory: failure capture tests as a case table;
 document each header symbol

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss
---
 .../Pokemon_AutoStoryFailureCapture.h         |  7 +--
 .../Pokemon_AutoStoryFailureCapture_Tests.cpp | 46 +++++++++++++++----
 2 files changed, 42 insertions(+), 11 deletions(-)

diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture.h
index 0e2d951f25..d4a7079fb8 100644
--- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture.h
+++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture.h
@@ -46,15 +46,16 @@ struct FailureRecord{
 //  made "_". An empty event (a start or end check failed) is "checkpoint".
 std::string failure_folder_name(std::string_view time, const FailureRecord& record);
 
+//  Failure.json: the record's fields, its log lines as an array.
 JsonObject failure_json(const FailureRecord& record);
 
-//  The checkpoint and event a status line names:
-//  "00.03/2 below_oaks_trigger: start" names 00.03 and below_oaks_trigger.
-//  Both empty for a line that names no event ("00: start, 3 checkpoints").
+//  The step a story status line names.
 struct StatusStep{
     std::string checkpoint;
     std::string event;
 };
+//  "00.03/2 below_oaks_trigger: start" names 00.03 and below_oaks_trigger.
+//  Both empty for a line that names no event ("00: start, 3 checkpoints").
 StatusStep step_of_status(std::string_view line);
 
 
diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture_Tests.cpp
index 0574a9db5f..5f11f3e523 100644
--- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture_Tests.cpp
+++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture_Tests.cpp
@@ -8,6 +8,7 @@
  */
 
 #include <string>
+#include <utility>
 #include "Common/Cpp/Json/JsonArray.h"
 #include "Common/Cpp/Json/JsonValue.h"
 #include "Common/Cpp/TestRunners/UnitTest.h"
@@ -77,27 +78,56 @@ UnitTestResult test_step_of_status(){
     return true;
 }
 
+struct FailureCaptureInput{
+    std::string name;
+    UnitTestResult (*test)();
+};
+
+struct FailureCaptureExpectation{
+    const char* description;
+};
+
+struct FailureCaptureTestCase{
+    FailureCaptureInput input;
+    FailureCaptureExpectation expectation;
+};
+
 class Test_AutoStoryFailureCapture : public UnitTest{
 public:
-    Test_AutoStoryFailureCapture(const std::string& name, UnitTestResult (*test)())
-        : UnitTest("Pokemon::AutoStoryFailureCapture - " + name)
-        , m_test(test)
+    explicit Test_AutoStoryFailureCapture(FailureCaptureTestCase scenario)
+        : UnitTest("Pokemon::AutoStoryFailureCapture - " + scenario.input.name)
+        , m_scenario(std::move(scenario))
     {}
     virtual UnitTestResult run(Logger&, CancellableScope&) const override{
-        return m_test();
+        return m_scenario.input.test();
     }
 
 private:
-    UnitTestResult (*m_test)();
+    FailureCaptureTestCase m_scenario;
+};
+
+const FailureCaptureTestCase FAILURE_CAPTURE_CASES[] = {
+    {
+        .input = {.name = "folder name", .test = test_folder_name},
+        .expectation = {.description = "names the folder by time, checkpoint and event, safe for a path"},
+    },
+    {
+        .input = {.name = "json", .test = test_json},
+        .expectation = {.description = "writes the record's fields and its log lines in order"},
+    },
+    {
+        .input = {.name = "step of a status line", .test = test_step_of_status},
+        .expectation = {.description = "reads checkpoint and event from event lines only"},
+    },
 };
 
 } // namespace
 
 
 void add_tests_AutoStoryFailureCapture(UnitTestDatabase& database){
-    database.add<Test_AutoStoryFailureCapture>("folder name", test_folder_name);
-    database.add<Test_AutoStoryFailureCapture>("json", test_json);
-    database.add<Test_AutoStoryFailureCapture>("step of a status line", test_step_of_status);
+    for (const auto& scenario : FAILURE_CAPTURE_CASES){
+        database.add<Test_AutoStoryFailureCapture>(scenario);
+    }
 }
 
 

From ce3299fc9c7a837b2100dee25b6721d4fe8c59a8 Mon Sep 17 00:00:00 2001
From: dayfine <difancpa@gmail.com>
Date: Mon, 9 Nov 2026 11:02:40 -0800
Subject: [PATCH 4/5] AutoStory: register the failure capture tests with the
 segment's

The unit-test runner's registration function is at its length limit on the
game stacks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss
---
 .../ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp       | 1 -
 .../Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h         | 3 ++-
 .../Source/Pokemon/AutoStory/Pokemon_StorySegments_Tests.cpp   | 3 +++
 3 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
index e0f8e79b96..2f878a6551 100644
--- a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
+++ b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp
@@ -86,7 +86,6 @@ UnitTestDatabase make_UNIT_TESTS_ALL(){
     Pokemon::add_tests_StoryEvents(ret);
     Pokemon::add_tests_StorySegments(ret);
     Pokemon::add_tests_StorySteps(ret);
-    Pokemon::add_tests_AutoStoryFailureCapture(ret);
     Pokemon::add_tests_StoryStepJson(ret);
     Pokemon::add_tests_AuthoredCheckpointJson(ret);
     NintendoSwitch::add_tests_CheckOnlineDetector(ret);
diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h
index 81771a47d9..41b82680c3 100644
--- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h
+++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h
@@ -31,7 +31,8 @@ void add_tests_StoryEvents(UnitTestDatabase& database);
 void add_tests_StorySegments(UnitTestDatabase& database);
 // Registers unit tests for high-level story step dispatching and table conversion.
 void add_tests_StorySteps(UnitTestDatabase& database);
-//  The failure capture's folder names, its JSON and the step a status line names.
+//  The failure capture's folder names, its JSON and the step a status line
+//  names. Registered by add_tests_StorySegments().
 void add_tests_AutoStoryFailureCapture(UnitTestDatabase& database);
 
 
diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments_Tests.cpp
index 2d4e812b7b..9520afb2d8 100644
--- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments_Tests.cpp
+++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StorySegments_Tests.cpp
@@ -517,6 +517,9 @@ void add_tests_StorySegments(UnitTestDatabase& database){
     for (const auto& scenario : STORY_SEGMENT_CASES){
         database.add<Test_StorySegments>(scenario);
     }
+    //  The failure capture is what the games attach to the segment's
+    //  failed hook; its tests run with the segment's.
+    add_tests_AutoStoryFailureCapture(database);
 }
 
 

From d4663f2535bb71728423c935c2f152a963127c69 Mon Sep 17 00:00:00 2001
From: dayfine <difancpa@gmail.com>
Date: Mon, 9 Nov 2026 11:04:21 -0800
Subject: [PATCH 5/5] FRLG AutoStory: save each failed event's stream history
 for replay

FailureCapture is attached to the story hooks of story rows and verify
mode, so each failed attempt saves its video, screenshot and JSON before
the soft reset, and a run that throws saves under the last step under way.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss
---
 .../AutoStory/PokemonFRLG_AutoStory.cpp       | 25 ++++++++++++++++---
 1 file changed, 21 insertions(+), 4 deletions(-)

diff --git a/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStory.cpp b/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStory.cpp
index 8f9fb0623a..a7fb3f3e2d 100644
--- a/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStory.cpp
+++ b/SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/AutoStory/PokemonFRLG_AutoStory.cpp
@@ -12,6 +12,7 @@
 #include "CommonFramework/Exceptions/OperationFailedExceptionWithScreenshot.h"
 #include "CommonFramework/Notifications/ProgramNotifications.h"
 #include "CommonFramework/VideoPipeline/VideoOverlay.h"
+#include "Pokemon/AutoStory/Pokemon_AutoStoryFailureCapture.h"
 #include "Pokemon/AutoStory/Pokemon_AutoStoryStats.h"
 #include "Pokemon/AutoStory/Pokemon_StorySegments.h"
 #include "Pokemon/Pokemon_Strings.h"
@@ -258,9 +259,18 @@ void verify_story_checkpoint(
     executor.set_language(run.language());
     Pokemon::Segment segment = make_story_segment(checkpoints, executor);
     Pokemon::SegmentHooks hooks = story_hooks(env, story);
+    //  Each failed run's stream history, screenshot and log, for a replay test.
+    Pokemon::FailureCapture capture(env.console, "PokemonFRLG");
+    capture.attach(hooks);
 
     Pokemon::RunState state;
-    const Pokemon::VerifyReport report = Pokemon::verify_checkpoint(state, segment, checkpoint.id, policy, hooks);
+    Pokemon::VerifyReport report;
+    try{
+        report = Pokemon::verify_checkpoint(state, segment, checkpoint.id, policy, hooks);
+    }catch (OperationFailedException& e){
+        capture.save_thrown(e.message());
+        throw;
+    }
     const std::string summary = std::format(
         "AutoStory verify: {} {}/{} passed, {} needed.", checkpoint.id, report.passes, policy.runs, policy.passes_needed
     );
@@ -451,11 +461,18 @@ static void run_story_rows(
         before_last_save(segment, std::move(before));
     }
     Pokemon::SegmentHooks hooks = story_hooks(env, story);
+    //  Each failed event's stream history, screenshot and log, for a replay test.
+    Pokemon::FailureCapture capture(env.console, "PokemonFRLG");
+    capture.attach(hooks);
 
     Pokemon::RunState state;
-    const Pokemon::SegmentReport report = run_segment(
-        state, segment, Pokemon::SegmentRange{rows.front().id, rows.back().id}, policy, hooks
-    );
+    Pokemon::SegmentReport report;
+    try{
+        report = run_segment(state, segment, Pokemon::SegmentRange{rows.front().id, rows.back().id}, policy, hooks);
+    }catch (OperationFailedException& e){
+        capture.save_thrown(e.message());
+        throw;
+    }
     Pokemon::record_story_stats(env.current_stats<Pokemon::AutoStoryStats>(), report);
     env.update_stats();
     throw_if_failed(report);