feat(session): serve requests without blocking a thread, pause and step

The app's end of the connection, independent of the transport, which
reaches it through Detail::Exchange: one request's way back, safe from
any thread and never blocking.

- What needs only the session's own state (hello, status, list, log,
  pause, resume) is answered on the transport thread. What touches the
  app (calls, get, set, trace, screenshot) queues for the next Pump and
  runs on the app's thread between frames. Waits and steps reply from
  the Pump that sees them satisfied, events from the thread that emits
  them. No request ever holds a thread while it waits.
- A request whose timeout passes before Pump is answered Timeout and
  is guaranteed not to have run, so an agent never wonders whether a
  command went through; an Async result arrives on the Pump it is
  ready; requests left when the Session ends are answered ShuttingDown.
- Advance() for frame loops and Paused()/TakeSteps() for fixed-step
  loops hold what the app gates on them; pausing an app that gates
  nothing is refused instead of silently doing nothing. pause --when
  stops the frame its condition holds; pause --on-check stops before
  the next Advance in the frame a check fails, optionally raising
  SIGTRAP for an attached debugger.
- A wait that times out says what its condition's paths were; a log
  follower gets matching entries in order, from the backlog on, and is
  dropped when it cannot keep up.
- Request parameters go through Codec, so a mistyped request gets the
  same did-you-mean replies a mistyped command does. The session sets
  PR_SET_PTRACER_ANY so a debugger the agent starts can attach.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

implementations/Crafter.Debug-Registry.cpp

@@ -156,6 +156,7 @@ std::uint64_t Registry::NewOwner() {
 
 void Registry::AddCommand(CommandEntry entry) {
     if (!ValidName(entry.name)) throw std::invalid_argument(std::format("Crafter.Debug: '{}' is not a command name: it must be non-empty, without whitespace", entry.name));
+    if (entry.name.starts_with("debug.")) throw std::invalid_argument(std::format("Crafter.Debug: '{}' is not a command name: debug.* belongs to the session", entry.name));
     std::string name = entry.name;
     std::lock_guard lock(mutex);
     commands.insert_or_assign(std::move(name), std::make_shared<const CommandEntry>(std::move(entry)));
@@ -255,7 +256,7 @@ Resolved Registry::Resolve(std::string_view path) const {
     return { *reached, {} };
 }
 
-std::optional<std::string> Registry::Set(std::string_view path, const Value& value) const {
+std::optional<Error> Registry::Set(std::string_view path, const Value& value) const {
     std::shared_ptr<const WatchEntry> watch;
     {
         std::lock_guard lock(mutex);
@@ -264,17 +265,23 @@ std::optional<std::string> Registry::Set(std::string_view path, const Value& val
     }
     if (!watch) {
         const auto suggestion = SuggestPath(path);
-        return suggestion ? std::format("no watch '{}'; did you mean '{}'?", path, *suggestion) : std::format("no watch '{}'", path);
+        return Error{ "UnknownPath", suggestion ? std::format("no watch '{}'; did you mean '{}'?", path, *suggestion) : std::format("no watch '{}'", path) };
     }
-    if (!watch->set) return std::format("'{}' is read-only", watch->path);
+    if (!watch->set) return Error{ "ReadOnly", std::format("'{}' is read-only", watch->path) };
     const std::string_view rest = path.substr(watch->path.size());
-    if (rest.empty()) return watch->set(value);
+    std::optional<std::string> refused;
+    if (rest.empty()) {
+        refused = watch->set(value);
+    } else {
         Value whole = watch->get();
         std::string error;
         Value* part = Walk(whole, rest, watch->path, error);
-    if (part == nullptr) return error;
+        if (part == nullptr) return Error{ "UnknownPath", error };
         *part = value;
-    return watch->set(whole);
+        refused = watch->set(whole);
+    }
+    if (refused) return Error{ "InvalidParams", *refused };
+    return std::nullopt;
 }
 
 std::optional<std::string> Registry::SuggestCommand(std::string_view name) const {

implementations/Crafter.Debug-Timeline.cpp

@@ -88,17 +88,21 @@ void Timeline::RecordCheck(std::string_view category, std::string message, const
     Notify(entry);
 }
 
+bool Crafter::Debug::Detail::Matches(const TimelineQuery& query, const TimelineEntry& entry) {
+    if (entry.sequence <= query.afterSequence) return false;
+    if (query.sinceFrame && entry.frame < *query.sinceFrame) return false;
+    if (Level(entry.kind) < query.minLevel) return false;
+    if (!query.kinds.empty() && std::ranges::find(query.kinds, entry.kind) == query.kinds.end()) return false;
+    if (!query.category.empty() && !GlobMatch(query.category, entry.category)) return false;
+    if (!query.grep.empty() && entry.message.find(query.grep) == std::string::npos && entry.category.find(query.grep) == std::string::npos) return false;
+    return true;
+}
+
 std::vector<TimelineEntry> Timeline::Query(const TimelineQuery& query) const {
     std::vector<TimelineEntry> matched;
     std::lock_guard lock(mutex);
     for (const TimelineEntry& entry : entries) {
-        if (entry.sequence <= query.afterSequence) continue;
-        if (query.sinceFrame && entry.frame < *query.sinceFrame) continue;
-        if (Level(entry.kind) < query.minLevel) continue;
-        if (!query.kinds.empty() && std::ranges::find(query.kinds, entry.kind) == query.kinds.end()) continue;
-        if (!query.category.empty() && !GlobMatch(query.category, entry.category)) continue;
-        if (!query.grep.empty() && entry.message.find(query.grep) == std::string::npos && entry.category.find(query.grep) == std::string::npos) continue;
-        matched.push_back(entry);
+        if (Matches(query, entry)) matched.push_back(entry);
     }
     if (query.last != 0 && matched.size() > query.last) matched.erase(matched.begin(), matched.end() - static_cast<std::ptrdiff_t>(query.last));
     return matched;

implementations/Crafter.Debug.Core-Protocol.cpp

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+// SPDX-FileCopyrightText: Copyright (C) 2026 Catcrafts®
+
+module Crafter.Debug.Core:Protocol_impl;
+import std;
+import :Value;
+import :Protocol;
+
+using namespace Crafter::Debug;
+
+namespace {
+    constexpr std::string_view alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+    std::int32_t Sextet(char c) {
+        if (c >= 'A' && c <= 'Z') return c - 'A';
+        if (c >= 'a' && c <= 'z') return c - 'a' + 26;
+        if (c >= '0' && c <= '9') return c - '0' + 52;
+        if (c == '+') return 62;
+        if (c == '/') return 63;
+        return -1;
+    }
+}
+
+Value Crafter::Debug::MakeReply(Value result) {
+    Value reply = Value::MakeObject();
+    reply.Set("result", std::move(result));
+    return reply;
+}
+
+Value Crafter::Debug::MakeErrorReply(std::string_view code, std::string_view message) {
+    Value error = Value::MakeObject();
+    error.Set("code", Value(code));
+    error.Set("message", Value(message));
+    Value reply = Value::MakeObject();
+    reply.Set("error", std::move(error));
+    return reply;
+}
+
+std::string Crafter::Debug::Base64Encode(std::span<const std::byte> bytes) {
+    std::string out;
+    out.reserve((bytes.size() + 2) / 3 * 4);
+    std::size_t i = 0;
+    for (; i + 3 <= bytes.size(); i += 3) {
+        const std::uint32_t chunk = (std::to_integer<std::uint32_t>(bytes[i]) << 16) | (std::to_integer<std::uint32_t>(bytes[i + 1]) << 8) | std::to_integer<std::uint32_t>(bytes[i + 2]);
+        out += alphabet[(chunk >> 18) & 63];
+        out += alphabet[(chunk >> 12) & 63];
+        out += alphabet[(chunk >> 6) & 63];
+        out += alphabet[chunk & 63];
+    }
+    const std::size_t rest = bytes.size() - i;
+    if (rest == 1) {
+        const std::uint32_t chunk = std::to_integer<std::uint32_t>(bytes[i]) << 16;
+        out += alphabet[(chunk >> 18) & 63];
+        out += alphabet[(chunk >> 12) & 63];
+        out += "==";
+    } else if (rest == 2) {
+        const std::uint32_t chunk = (std::to_integer<std::uint32_t>(bytes[i]) << 16) | (std::to_integer<std::uint32_t>(bytes[i + 1]) << 8);
+        out += alphabet[(chunk >> 18) & 63];
+        out += alphabet[(chunk >> 12) & 63];
+        out += alphabet[(chunk >> 6) & 63];
+        out += '=';
+    }
+    return out;
+}
+
+std::optional<std::vector<std::byte>> Crafter::Debug::Base64Decode(std::string_view text) {
+    if (text.size() % 4 != 0) return std::nullopt;
+    std::vector<std::byte> out;
+    out.reserve(text.size() / 4 * 3);
+    for (std::size_t i = 0; i < text.size(); i += 4) {
+        const bool last = i + 4 == text.size();
+        const std::int32_t a = Sextet(text[i]);
+        const std::int32_t b = Sextet(text[i + 1]);
+        const bool pad2 = last && text[i + 2] == '=';
+        const bool pad3 = last && text[i + 3] == '=';
+        const std::int32_t c = pad2 ? 0 : Sextet(text[i + 2]);
+        const std::int32_t d = pad3 ? 0 : Sextet(text[i + 3]);
+        if (a < 0 || b < 0 || c < 0 || d < 0 || (pad2 && !pad3)) return std::nullopt;
+        const std::uint32_t chunk = (static_cast<std::uint32_t>(a) << 18) | (static_cast<std::uint32_t>(b) << 12) | (static_cast<std::uint32_t>(c) << 6) | static_cast<std::uint32_t>(d);
+        out.push_back(static_cast<std::byte>((chunk >> 16) & 0xFF));
+        if (!pad2) out.push_back(static_cast<std::byte>((chunk >> 8) & 0xFF));
+        if (!pad3) out.push_back(static_cast<std::byte>(chunk & 0xFF));
+    }
+    return out;
+}

interfaces/Crafter.Debug-Registry.cppm

@@ -103,8 +103,9 @@ export namespace Crafter::Debug::Detail {
         Resolved Resolve(std::string_view path) const;
         // Sets the watch the path names, or a part of its value: "fort1.core.pos.x"
         // reads the watch "fort1.core.pos", replaces x and writes it back.
-        // Returns an error message, or nothing. Call on the Pump thread.
-        std::optional<std::string> Set(std::string_view path, const Value& value) const;
+        // Returns why not (UnknownPath, ReadOnly or InvalidParams), or
+        // nothing. Call on the Pump thread.
+        std::optional<Error> Set(std::string_view path, const Value& value) const;
 
         // The closest known command, watch or sample name to `name`, for
         // "did you mean" in errors.

interfaces/Crafter.Debug-Session.cppm

@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+// SPDX-FileCopyrightText: Copyright (C) 2026 Catcrafts®
+
+// The session: the app's end of the debug connection.
+//
+//     ThreadPool::Start();
+//     Debug::Session debug({ .name = "MyApp" });
+//     EventListener<void> pump(&window.onBeforeUpdate, [] { Debug::Pump(); });
+//
+// Requests arrive on transport threads and are never answered by blocking
+// one: what needs only the session's own state (status, the command list,
+// the log, pause, resume) is answered there and then; what touches the app
+// (calls, watches, traces, screenshots) waits in a queue for the next Pump,
+// which runs it on the app's own thread between frames; waits and steps are
+// answered by the Pump that sees them satisfied. A request that cannot run
+// before its timeout is answered Timeout and is guaranteed not to have run.
+//
+// Pause and step only stop what the app gates on them:
+//
+//     while (acc >= dt && Debug::Advance()) { sim.Tick(); acc -= dt; }  // frame loops
+//     if (Debug::Paused()) { for (auto n = Debug::TakeSteps(); n > 0; --n) sim.Tick(); acc = 0; }
+//                                                                       // fixed-step loops
+//
+// Rendering and Pump keep running while paused, so the agent can still read
+// watches, take screenshots and step.
+export module Crafter.Debug:Session;
+import std;
+import Crafter.Debug.Core;
+
+export namespace Crafter::Debug::Detail {
+    // One request's way back to its client. A transport implements it; the
+    // session calls it from transport threads, the Pump thread and whatever
+    // thread logs, so it must be safe from any thread and must not block.
+    class Exchange {
+    public:
+        virtual ~Exchange() = default;
+        // The final reply, ending the exchange.
+        virtual void Reply(const Value& reply) = 0;
+        // One more object on a streaming exchange (`log --follow`). False
+        // when the client is gone or too far behind; the session then drops it.
+        virtual bool Stream(const Value& line) = 0;
+        // Reply, then call `afterSent` once the reply has left: what
+        // `quit --force` exits from.
+        virtual void ReplyThen(const Value& reply, std::function<void()> afterSent) {
+            Reply(reply);
+            afterSent();
+        }
+    };
+}
+
+export namespace Crafter::Debug {
+    struct SessionOptions {
+        // What `crafter-debug ls` calls this instance; the executable's
+        // file name when empty.
+        std::string name;
+        // 0 for any free port; the discovery file says which.
+        std::uint16_t port = 0;
+        // Also record what the app writes to stdout and stderr on the timeline.
+        bool captureStdio = false;
+        // Called on the Pump thread when an agent asks the app to quit,
+        // after QuitRequested() turned true. Don't call std::exit from it:
+        // close the window or end the loop, so the Session is destroyed
+        // before main returns.
+        std::function<void()> onQuit;
+        // False: no transport and no discovery file; requests come only
+        // through Handle. For tests.
+        bool listen = true;
+    };
+
+    // One per process; a second throws. Destroy it before
+    // ThreadPool::Stop() and before main returns: it closes its connections,
+    // and msquic waits for open ones at exit.
+    class Session {
+    public:
+        explicit Session(SessionOptions options = {});
+        ~Session();
+        Session(const Session&) = delete;
+        Session& operator=(const Session&) = delete;
+
+        // One request, from a transport or a test. Never blocks; the reply
+        // goes through `exchange`.
+        void Handle(const Value& request, std::shared_ptr<Detail::Exchange> exchange);
+        // What every request must carry.
+        const std::string& Token() const;
+
+        struct State;
+
+    private:
+        std::shared_ptr<State> state;
+    };
+
+    // Once per frame, on the thread that owns the app's state: runs queued
+    // requests, polls Async results, evaluates waits and conditions, records
+    // traces, and counts the frame. Does nothing without a Session.
+    void Pump();
+    // For frame loops: false while paused, true once per step granted.
+    bool Advance();
+    // For fixed-step loops: whether the session is paused; see TakeSteps.
+    bool Paused();
+    // The steps granted since the last call, all at once.
+    std::uint32_t TakeSteps();
+    // Whether an agent asked the app to quit.
+    bool QuitRequested();
+    // Where `crafter-debug screenshot` gets a PNG: called on the Pump
+    // thread, returning the bytes when they are ready (a frame or two later
+    // for a GPU readback). See the README for the Crafter.Graphics version.
+    void SetCapture(std::function<Async<std::vector<std::byte>>()> capture);
+}

interfaces/Crafter.Debug-Timeline.cppm

@@ -87,6 +87,10 @@ export namespace Crafter::Debug::Detail {
         std::vector<EntryKind> kinds;
     };
 
+    // Whether one entry passes a query's filters (all but `last`), for a
+    // follower that sees entries one at a time.
+    bool Matches(const TimelineQuery& query, const TimelineEntry& entry);
+
     struct CheckSite {
         std::string file;
         std::uint32_t line = 0;

interfaces/Crafter.Debug.Core-Protocol.cppm

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+// SPDX-FileCopyrightText: Copyright (C) 2026 Catcrafts®
+
+// The wire contract between an app and crafter-debug. A request is one JSON
+// object,
+//
+//     {"token": "...", "method": "debug.get", "params": {...}, "timeoutMs": 30000}
+//
+// and its reply one JSON object, either {"result": ...} or
+// {"error": {"code": "...", "message": "..."}}, the envelope 3DForts' debug
+// API used. A streaming request (`debug.log` with follow) is answered by one
+// object per line instead. Methods named debug.* are the session's own; any
+// other method is a command the app registered.
+//
+// `debug.hello` is frozen: every version answers it the same way, so a
+// client can always learn the protocol and source of the app it reached
+// before relying on anything else.
+export module Crafter.Debug.Core:Protocol;
+import std;
+import :Value;
+
+export namespace Crafter::Debug {
+    // Bumped on any change to a request or reply a client relies on.
+    inline constexpr std::uint32_t protocolVersion = 1;
+    // The library's own version, which debug.hello reports.
+    inline constexpr std::string_view libraryVersion = "0.1.0-dev";
+    // The QUIC ALPN: frozen with debug.hello, so a mismatch is reported by
+    // hello instead of failing the handshake.
+    inline constexpr std::string_view alpn = "crafter-debug/1";
+
+    // The error codes the session itself answers with; app commands add
+    // their own.
+    namespace Codes {
+        inline constexpr std::string_view unauthorized = "Unauthorized";
+        inline constexpr std::string_view unknownMethod = "UnknownMethod";
+        inline constexpr std::string_view invalidRequest = "InvalidRequest";
+        inline constexpr std::string_view invalidParams = "InvalidParams";
+        inline constexpr std::string_view timeout = "Timeout";
+        inline constexpr std::string_view notPaused = "NotPaused";
+        inline constexpr std::string_view pauseUnsupported = "PauseUnsupported";
+        inline constexpr std::string_view noCapture = "NoCapture";
+        inline constexpr std::string_view shuttingDown = "ShuttingDown";
+        inline constexpr std::string_view exception = "Exception";
+        inline constexpr std::string_view readOnly = "ReadOnly";
+        inline constexpr std::string_view unknownPath = "UnknownPath";
+        inline constexpr std::string_view conditionError = "ConditionError";
+    }
+
+    Value MakeReply(Value result);
+    Value MakeErrorReply(std::string_view code, std::string_view message);
+
+    // Standard base64 with padding, for screenshots in a JSON reply.
+    std::string Base64Encode(std::span<const std::byte> bytes);
+    std::optional<std::vector<std::byte>> Base64Decode(std::string_view text);
+}

interfaces/Crafter.Debug.Core.cppm

@@ -9,3 +9,4 @@ export import :Value;
 export import :Reflect;
 export import :Codec;
 export import :Result;
+export import :Protocol;

interfaces/Crafter.Debug.cppm

@@ -3,17 +3,19 @@
 
 // Runtime debugging for AI agents: what an app imports. Commands, watches
 // and samples (:Registry), the timeline with Log, Check and Emit
-// (:Timeline), and the conditions waits and pauses use (:Condition), over
-// the core shared with the client. The session follows in a later phase.
+// (:Timeline), the conditions waits and pauses use (:Condition), and the
+// session that serves them with Pump, Advance and pause control (:Session),
+// over the core shared with the client.
 export module Crafter.Debug;
 export import Crafter.Debug.Core;
 export import :Registry;
 export import :Timeline;
 export import :Condition;
+export import :Session;
 import std;
 
 export namespace Crafter::Debug {
-    std::string_view Version() {
-        return "0.0.0-dev";
+    constexpr std::string_view Version() {
+        return libraryVersion;
     }
 }

project.cpp

@@ -36,11 +36,14 @@ namespace {
     };
 
     // Tests of the app library.
-    constexpr std::array<std::string_view, 4> libraryTests = {
+    constexpr std::array<std::string_view, 7> libraryTests = {
         "ShouldInvokeCommands",
         "ShouldResolveWatchPaths",
         "ShouldRecordTimeline",
         "ShouldEvaluateConditions",
+        "ShouldAnswerRequests",
+        "ShouldPauseAndStep",
+        "ShouldWaitTraceAndFollow",
     };
 }
 
@@ -59,16 +62,18 @@ extern "C" Configuration CrafterBuildProject(std::span<const std::string_view> a
     core.type = ConfigurationType::LibraryStatic;
     ApplyStandardArgs(core, args);
     {
-        std::array<fs::path, 5> interfaces = {
+        std::array<fs::path, 6> interfaces = {
             "interfaces/Crafter.Debug.Core-Value",
             "interfaces/Crafter.Debug.Core-Reflect",
             "interfaces/Crafter.Debug.Core-Codec",
             "interfaces/Crafter.Debug.Core-Result",
+            "interfaces/Crafter.Debug.Core-Protocol",
             "interfaces/Crafter.Debug.Core",
         };
-        std::array<fs::path, 2> implementations = {
+        std::array<fs::path, 3> implementations = {
             "implementations/Crafter.Debug.Core-Value",
             "implementations/Crafter.Debug.Core-Codec",
+            "implementations/Crafter.Debug.Core-Protocol",
         };
         core.GetInterfacesAndImplementations(interfaces, implementations);
     }
@@ -94,16 +99,18 @@ extern "C" Configuration CrafterBuildProject(std::span<const std::string_view> a
 
     cfg.dependencies = { &core, &client };
     {
-        std::array<fs::path, 4> interfaces = {
+        std::array<fs::path, 5> interfaces = {
             "interfaces/Crafter.Debug-Registry",
             "interfaces/Crafter.Debug-Timeline",
             "interfaces/Crafter.Debug-Condition",
+            "interfaces/Crafter.Debug-Session",
             "interfaces/Crafter.Debug",
         };
-        std::array<fs::path, 3> implementations = {
+        std::array<fs::path, 4> implementations = {
             "implementations/Crafter.Debug-Registry",
             "implementations/Crafter.Debug-Timeline",
             "implementations/Crafter.Debug-Condition",
+            "implementations/Crafter.Debug-Session",
         };
         cfg.GetInterfacesAndImplementations(interfaces, implementations);
     }

tests/ShouldAnswerRequests/main.cpp

@@ -0,0 +1,183 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+// SPDX-FileCopyrightText: Copyright (C) 2026 Catcrafts®
+
+// The session answers requests the way a client relies on: a wrong token is
+// Unauthorized, a mistyped method gets a suggestion, hello and status are
+// answered at once, while calls, gets, sets and screenshots wait for the
+// app's Pump and run there. A request whose timeout passes before that Pump
+// is answered Timeout and is never run; a throwing handler is an Exception
+// reply; an Async result arrives on the Pump it is ready; the agent's
+// actions appear on the timeline; there is one Session per process; and
+// requests still queued when it ends are answered ShuttingDown.
+import std;
+import Crafter.Debug;
+using namespace Crafter::Debug;
+
+namespace {
+    std::int32_t failures = 0;
+
+    void Check(bool ok, std::string_view what) {
+        std::println("{} {}", ok ? "PASS" : "FAIL", what);
+        if (!ok) ++failures;
+    }
+
+    class FakeExchange : public Detail::Exchange {
+    public:
+        void Reply(const Value& reply) override {
+            std::lock_guard lock(mutex);
+            if (!final) final = reply;
+        }
+        bool Stream(const Value& line) override {
+            std::lock_guard lock(mutex);
+            lines.push_back(line);
+            return true;
+        }
+        std::optional<Value> Final() {
+            std::lock_guard lock(mutex);
+            return final;
+        }
+
+    private:
+        std::mutex mutex;
+        std::optional<Value> final;
+        std::vector<Value> lines;
+    };
+
+    Session* session = nullptr;
+
+    std::shared_ptr<FakeExchange> Send(std::string_view method, Value params = {}, std::int64_t timeoutMs = 30'000) {
+        Value request = Value::MakeObject();
+        request.Set("token", Value(session->Token()));
+        request.Set("method", Value(method));
+        request.Set("params", std::move(params));
+        request.Set("timeoutMs", Value(timeoutMs));
+        auto exchange = std::make_shared<FakeExchange>();
+        session->Handle(request, exchange);
+        return exchange;
+    }
+
+    Value ResultOf(FakeExchange& exchange) {
+        const auto reply = exchange.Final();
+        return reply && reply->Find("result") ? *reply->Find("result") : Value();
+    }
+
+    std::string CodeOf(FakeExchange& exchange) {
+        const auto reply = exchange.Final();
+        return reply && reply->Find("error") ? reply->Find("error")->Find("code")->AsString() : std::string();
+    }
+
+    std::string MessageOf(FakeExchange& exchange) {
+        const auto reply = exchange.Final();
+        return reply && reply->Find("error") ? reply->Find("error")->Find("message")->AsString() : std::string();
+    }
+}
+
+int main() {
+    Command("Player_Fire", "Fire.", [] { return std::string("bang"); });
+    Command("Game_Crash", "Throws.", []() -> std::int32_t { throw std::runtime_error("boom"); });
+    std::int32_t polls = 0;
+    Command("Sim_Hash", "Ready on the second poll.", [&]() -> Async<std::int32_t> {
+        return Async<std::int32_t>([&]() -> std::optional<std::int32_t> {
+            if (++polls < 2) return std::nullopt;
+            return 7;
+        });
+    });
+    std::int32_t hp = 100;
+    Watch("fort.hp", hp);
+    const std::int32_t level = 3;
+    Watch("level", level);
+
+    std::shared_ptr<FakeExchange> leftOver;
+    {
+        Session owned({ .name = "test", .listen = false });
+        session = &owned;
+
+        auto wrongToken = std::make_shared<FakeExchange>();
+        owned.Handle(Value::Parse(R"({"token": "nope", "method": "debug.status"})"), wrongToken);
+        Check(CodeOf(*wrongToken) == "Unauthorized", "a wrong token is refused");
+        auto notObject = std::make_shared<FakeExchange>();
+        owned.Handle(Value(3), notObject);
+        Check(CodeOf(*notObject) == "InvalidRequest", "a request that is not an object is refused");
+
+        const Value hello = ResultOf(*Send("debug.hello"));
+        Check(hello.Find("protocol")->AsInteger() == 1 && hello.Find("name")->AsString() == "test", "hello names the protocol and the instance");
+        const Value status = ResultOf(*Send("debug.status"));
+        Check(status.Find("frame")->AsInteger() == 0 && !status.Find("paused")->AsBool() && !status.Find("pauseSupported")->AsBool(), "status is answered at once");
+        const Value list = ResultOf(*Send("debug.list"));
+        Check(list.Find("commands")->Size() == 3 && list.Find("watches")->Size() == 5, "list has the commands and watches, the session's own included");
+
+        auto typo = Send("debug.stauts");
+        Check(CodeOf(*typo) == "UnknownMethod" && MessageOf(*typo).find("did you mean 'debug.status'") != std::string::npos, "a mistyped method gets a suggestion");
+        auto commandTypo = Send("Player_Fier");
+        Check(CodeOf(*commandTypo) == "UnknownMethod" && MessageOf(*commandTypo).find("did you mean 'Player_Fire'") != std::string::npos, "a mistyped command gets a suggestion");
+
+        auto fire = Send("Player_Fire");
+        Check(!fire->Final(), "a call waits for Pump");
+        Pump();
+        Check(ResultOf(*fire).AsString() == "bang", "Pump runs the call and replies");
+
+        auto get = Send("debug.get", Value::Parse(R"({"paths": ["fort.hp", "lev*", "nope"]})"));
+        Pump();
+        const Value got = ResultOf(*get);
+        Check(got.Find("values")->Find("fort.hp")->AsInteger() == 100 && got.Find("values")->Find("level")->AsInteger() == 3 && got.Find("errors")->Find("nope") != nullptr,
+              "get reads paths and globs, and reports the ones it cannot");
+        auto badGet = Send("debug.get", Value::Parse(R"({"pathz": []})"));
+        Pump();
+        Check(CodeOf(*badGet) == "InvalidParams" && MessageOf(*badGet).find("did you mean 'paths'") != std::string::npos, "a mistyped parameter gets a suggestion");
+
+        auto set = Send("debug.set", Value::Parse(R"({"path": "fort.hp", "value": 5})"));
+        Pump();
+        Check(hp == 5 && ResultOf(*set).Find("value")->AsInteger() == 5, "set writes on the Pump thread and replies with the new value");
+        auto readOnly = Send("debug.set", Value::Parse(R"({"path": "level", "value": 5})"));
+        Pump();
+        Check(CodeOf(*readOnly) == "ReadOnly", "setting a read-only watch is refused");
+
+        auto crash = Send("Game_Crash");
+        Pump();
+        Check(CodeOf(*crash) == "Exception" && MessageOf(*crash).find("boom") != std::string::npos, "a throwing handler is an Exception reply");
+
+        std::int32_t fired = 0;
+        Command("Count", "Counts.", [&] { ++fired; });
+        auto late = Send("Count", {}, 1);
+        std::this_thread::sleep_for(std::chrono::milliseconds(20));
+        Pump();
+        Check(CodeOf(*late) == "Timeout" && MessageOf(*late).find("not run") != std::string::npos && fired == 0, "a request past its timeout before Pump is never run");
+
+        auto hash = Send("Sim_Hash");
+        Pump();
+        Check(!hash->Final(), "an Async result is not ready on its first poll");
+        Pump();
+        Check(ResultOf(*hash).AsInteger() == 7, "an Async result is replied on the Pump it is ready");
+
+        auto noShot = Send("debug.screenshot");
+        Pump();
+        Check(CodeOf(*noShot) == "NoCapture", "a screenshot without a capture source says so");
+        SetCapture([] {
+            return Async<std::vector<std::byte>>([]() -> std::optional<std::vector<std::byte>> {
+                return std::vector<std::byte>{ std::byte{ 0x89 }, std::byte{ 'P' }, std::byte{ 'N' }, std::byte{ 'G' } };
+            });
+        });
+        auto shot = Send("debug.screenshot");
+        Pump();
+        const auto png = Base64Decode(ResultOf(*shot).Find("png")->AsString());
+        Check(png && png->size() == 4 && (*png)[1] == std::byte{ 'P' }, "a screenshot's PNG comes back as base64");
+
+        auto agent = Send("debug.log", Value::Parse(R"({"kinds": ["agent"], "last": 100})"));
+        const Value entries = *ResultOf(*agent).Find("entries");
+        Check(std::ranges::any_of(entries.Items(), [](const Value& entry) { return entry.Find("message")->AsString().starts_with("Player_Fire"); }),
+              "the agent's calls are on the timeline");
+
+        bool threw = false;
+        try {
+            Session second({ .listen = false });
+        } catch (const std::logic_error&) {
+            threw = true;
+        }
+        Check(threw, "a second Session is refused");
+
+        leftOver = Send("Player_Fire");
+    }
+    Check(CodeOf(*leftOver) == "ShuttingDown", "a request still queued when the Session ends is answered ShuttingDown");
+
+    return failures == 0 ? 0 : 1;
+}

tests/ShouldPauseAndStep/main.cpp

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+// SPDX-FileCopyrightText: Copyright (C) 2026 Catcrafts®
+
+// Pause and step hold exactly what the app gates on them. Pausing an app
+// that never calls Advance is refused rather than silently doing nothing;
+// while paused Advance is false and a step lets it through that many times,
+// replying once they are taken; `pause --when` stops the app the frame its
+// condition holds; `pause --on-check` stops it within the frame a check
+// fails, before the next Advance; TakeSteps hands a fixed-step loop every
+// granted step at once; and quit calls onQuit once, on the Pump thread.
+import std;
+import Crafter.Debug;
+using namespace Crafter::Debug;
+
+namespace {
+    std::int32_t failures = 0;
+
+    void Check(bool ok, std::string_view what) {
+        std::println("{} {}", ok ? "PASS" : "FAIL", what);
+        if (!ok) ++failures;
+    }
+
+    class FakeExchange : public Detail::Exchange {
+    public:
+        void Reply(const Value& reply) override {
+            std::lock_guard lock(mutex);
+            if (!final) final = reply;
+        }
+        bool Stream(const Value&) override { return true; }
+        std::optional<Value> Final() {
+            std::lock_guard lock(mutex);
+            return final;
+        }
+
+    private:
+        std::mutex mutex;
+        std::optional<Value> final;
+    };
+
+    Session* session = nullptr;
+
+    std::shared_ptr<FakeExchange> Send(std::string_view method, std::string_view params = "{}") {
+        Value request = Value::MakeObject();
+        request.Set("token", Value(session->Token()));
+        request.Set("method", Value(method));
+        request.Set("params", Value::Parse(params));
+        auto exchange = std::make_shared<FakeExchange>();
+        session->Handle(request, exchange);
+        return exchange;
+    }
+
+    Value ResultOf(FakeExchange& exchange) {
+        const auto reply = exchange.Final();
+        return reply && reply->Find("result") ? *reply->Find("result") : Value();
+    }
+
+    std::string CodeOf(FakeExchange& exchange) {
+        const auto reply = exchange.Final();
+        return reply && reply->Find("error") ? reply->Find("error")->Find("code")->AsString() : std::string();
+    }
+}
+
+int main() {
+    std::int32_t counter = 0;
+    Watch("counter", counter);
+    std::int32_t quits = 0;
+    Session owned({ .name = "pause", .onQuit = [&] { ++quits; }, .listen = false });
+    session = &owned;
+
+    Check(CodeOf(*Send("debug.pause")) == "PauseUnsupported", "pausing an app that never calls Advance is refused");
+    Check(Advance(), "Advance is true while running");
+
+    Check(ResultOf(*Send("debug.pause")).Find("paused")->AsBool(), "pause replies at once");
+    Check(!Advance() && Paused(), "Advance is false while paused");
+    auto step = Send("debug.step", R"({"count": 2})");
+    Check(!step->Final(), "a step replies once its steps are taken, not before");
+    Check(Advance() && Advance() && !Advance(), "a step of two lets Advance through twice");
+    Pump();
+    Check(ResultOf(*step).Find("paused")->AsBool(), "the step replies on the next Pump");
+    Send("debug.resume");
+    Check(Advance() && !Paused(), "resume lets the app run");
+    Check(CodeOf(*Send("debug.step")) == "NotPaused", "a step while running is refused");
+
+    Check(ResultOf(*Send("debug.pause", R"({"when": "counter >= 3"})")).Find("armed")->AsString() == "when", "pause --when arms");
+    auto waitPaused = Send("debug.wait", R"({"paused": true})");
+    for (std::int32_t frame = 0; frame < 10 && Advance(); ++frame) {
+        ++counter;
+        Pump();
+    }
+    Check(counter == 3 && Paused(), "pause --when stops the app the frame its condition holds");
+    Pump();
+    const Value pausedReply = ResultOf(*waitPaused);
+    const Value* reason = pausedReply.Find("reason");
+    Check(reason != nullptr && reason->AsString().find("counter >= 3") != std::string::npos, "wait --paused replies with the reason");
+    Send("debug.resume");
+
+    Check(ResultOf(*Send("debug.pause", R"({"onCheck": true})")).Find("armed")->AsString() == "onCheck", "pause --on-check arms");
+    Check(Advance(), "running before the check fails");
+    Crafter::Debug::Check(false, "physics", "body {} has mass {}", 9, -1);
+    Check(!Advance(), "a failed check pauses before the next Advance in the same frame");
+    const Value status = ResultOf(*Send("debug.status"));
+    Check(status.Find("pauseReason")->AsString().find("check failed at main.cpp:") != std::string::npos, "the reason names the check's site");
+    Send("debug.resume");
+
+    Send("debug.pause");
+    auto steps = Send("debug.step", R"({"count": 3})");
+    Check(Paused() && TakeSteps() == 3 && TakeSteps() == 0, "TakeSteps hands out every granted step at once");
+    Pump();
+    Check(steps->Final().has_value() && CodeOf(*steps).empty(), "a fixed-step loop's steps reply too");
+    Send("debug.resume");
+
+    Check(CodeOf(*Send("debug.pause", R"({"trap": true})")) == "InvalidParams", "trap without when or onCheck is refused");
+    Check(CodeOf(*Send("debug.pause", R"({"when": "counter = 3"})")) == "ConditionError", "a malformed condition is refused when armed");
+
+    auto quit = Send("debug.quit");
+    Check(QuitRequested() && ResultOf(*quit).Find("quitting")->AsBool(), "quit replies and sets QuitRequested");
+    Check(quits == 0, "onQuit waits for the Pump thread");
+    Pump();
+    Pump();
+    Check(quits == 1, "onQuit runs once, on Pump");
+
+    return failures == 0 ? 0 : 1;
+}

tests/ShouldResolveWatchPaths/main.cpp

@@ -57,16 +57,16 @@ int main() {
 
     Check(!registry().Set("physics.gravity", Value(-3.5)) && gravity == -3.5F, "a set writes the variable");
     const auto bounded = registry().Set("physics.gravity", Value(10));
-    Check(bounded && bounded->find("outside") != std::string::npos && gravity == -3.5F, "a set outside the bounds is refused");
-    Check(registry().Set("build", Value(8)) == std::optional<std::string>("'build' is read-only") && build == 7, "a const variable's watch is read-only");
+    Check(bounded && bounded->code == "InvalidParams" && bounded->message.find("outside") != std::string::npos && gravity == -3.5F, "a set outside the bounds is refused");
+    Check(registry().Set("build", Value(8))->code == "ReadOnly" && build == 7, "a const variable's watch is read-only");
     Check(!registry().Set("bodies[0].pos.x", Value(9)) && bodies[0].pos.x == 9 && bodies[0].pos.y == 1, "a set into a member writes back the whole value");
     const auto wrongType = registry().Set("physics.gravity", Value("down"));
-    Check(wrongType && wrongType->find("expected a number") != std::string::npos, "a set of the wrong type is refused");
+    Check(wrongType && wrongType->message.find("expected a number") != std::string::npos, "a set of the wrong type is refused");
 
     Check(!registry().Set("lives", Value(5)) && lives == 5, "a computed watch sets through its setter");
     const auto negative = registry().Set("lives", Value(-1));
-    Check(negative && negative->find("lives cannot be negative") != std::string::npos && lives == 5, "a setter can refuse");
-    Check(registry().Set("score", Value(1)) == std::optional<std::string>("'score' is read-only"), "a getter-only watch is read-only");
+    Check(negative && negative->message.find("lives cannot be negative") != std::string::npos && lives == 5, "a setter can refuse");
+    Check(registry().Set("score", Value(1))->code == "ReadOnly", "a getter-only watch is read-only");
 
     const auto missing = registry().Resolve("physics.gravty");
     Check(!missing.Ok() && missing.error.find("did you mean 'physics.gravity'") != std::string::npos, "an unknown path gets a suggestion");

tests/ShouldWaitTraceAndFollow/main.cpp

@@ -0,0 +1,157 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+// SPDX-FileCopyrightText: Copyright (C) 2026 Catcrafts®
+
+// Waits, traces and log follows: `wait --frames` and a condition reply on the
+// Pump that satisfies them, a condition that cannot be decided replies with
+// why, an event wakes its waiter from the emitting thread without waiting
+// for Pump, and a timeout says what the condition's paths were. A trace
+// collects a value over frames with its stats, or a sample's history. The
+// log filters by level, and a follower receives new matching entries in
+// order, is dropped when it cannot keep up, and ends when its time is up.
+import std;
+import Crafter.Debug;
+using namespace Crafter::Debug;
+
+namespace {
+    std::int32_t failures = 0;
+
+    void Check(bool ok, std::string_view what) {
+        std::println("{} {}", ok ? "PASS" : "FAIL", what);
+        if (!ok) ++failures;
+    }
+
+    class FakeExchange : public Detail::Exchange {
+    public:
+        std::atomic<bool> refuse = false;
+
+        void Reply(const Value& reply) override {
+            std::lock_guard lock(mutex);
+            if (!final) final = reply;
+        }
+        bool Stream(const Value& line) override {
+            if (refuse) return false;
+            std::lock_guard lock(mutex);
+            lines.push_back(line);
+            return true;
+        }
+        std::optional<Value> Final() {
+            std::lock_guard lock(mutex);
+            return final;
+        }
+        std::vector<Value> Lines() {
+            std::lock_guard lock(mutex);
+            return lines;
+        }
+
+    private:
+        std::mutex mutex;
+        std::optional<Value> final;
+        std::vector<Value> lines;
+    };
+
+    Session* session = nullptr;
+
+    std::shared_ptr<FakeExchange> Send(std::string_view method, std::string_view params = "{}", std::int64_t timeoutMs = 30'000) {
+        Value request = Value::MakeObject();
+        request.Set("token", Value(session->Token()));
+        request.Set("method", Value(method));
+        request.Set("params", Value::Parse(params));
+        request.Set("timeoutMs", Value(timeoutMs));
+        auto exchange = std::make_shared<FakeExchange>();
+        session->Handle(request, exchange);
+        return exchange;
+    }
+
+    Value ResultOf(FakeExchange& exchange) {
+        const auto reply = exchange.Final();
+        return reply && reply->Find("result") ? *reply->Find("result") : Value();
+    }
+
+    std::string CodeOf(FakeExchange& exchange) {
+        const auto reply = exchange.Final();
+        return reply && reply->Find("error") ? reply->Find("error")->Find("code")->AsString() : std::string();
+    }
+
+    std::string MessageOf(FakeExchange& exchange) {
+        const auto reply = exchange.Final();
+        return reply && reply->Find("error") ? reply->Find("error")->Find("message")->AsString() : std::string();
+    }
+}
+
+int main() {
+    std::int32_t score = 0;
+    Watch("score", score);
+    Session owned({ .name = "wait", .listen = false });
+    session = &owned;
+
+    auto frames = Send("debug.wait", R"({"frames": 3})");
+    Pump();
+    Pump();
+    Check(!frames->Final(), "wait --frames 3 has not replied after two frames");
+    Pump();
+    Check(ResultOf(*frames).Find("frame")->AsInteger() == 3, "wait --frames 3 replies on the third");
+
+    auto condition = Send("debug.wait", R"({"condition": "score >= 2"})");
+    for (std::int32_t i = 0; i < 5 && !condition->Final(); ++i) {
+        ++score;
+        Pump();
+    }
+    Check(score == 2 && CodeOf(*condition).empty(), "a condition replies on the Pump it holds");
+    auto broken = Send("debug.wait", R"({"condition": "missing > 1"})");
+    Pump();
+    Check(CodeOf(*broken) == "ConditionError" && MessageOf(*broken).find("no watch or sample 'missing'") != std::string::npos, "an undecidable condition says why");
+
+    auto event = Send("debug.wait", R"({"event": "Boom"})");
+    std::thread([] { Emit("Boom", Value::Parse(R"({"power": 9})")); }).join();
+    Check(event->Final().has_value() && ResultOf(*event).Find("payload")->Find("power")->AsInteger() == 9, "an event wakes its waiter without waiting for Pump");
+
+    auto slow = Send("debug.wait", R"({"condition": "score > 100"})", 1);
+    std::this_thread::sleep_for(std::chrono::milliseconds(10));
+    Pump();
+    Check(CodeOf(*slow) == "Timeout" && MessageOf(*slow).find("score is 2") != std::string::npos, "a timeout reports the condition's paths");
+    Check(CodeOf(*Send("debug.wait", R"({"frames": 1, "paused": true})")) == "InvalidParams", "waiting for two things at once is refused");
+
+    auto trace = Send("debug.trace", R"({"paths": ["score"], "frames": 4})");
+    for (std::int32_t i = 0; i < 4; ++i) {
+        score += 10;
+        Pump();
+    }
+    const Value traced = ResultOf(*trace);
+    const Value* series = traced.Find("series") ? traced.Find("series")->Find("score") : nullptr;
+    Check(series != nullptr && series->Find("values")->Size() == 4 && series->Find("stats")->Find("min")->AsNumber() == 12
+              && series->Find("stats")->Find("max")->AsNumber() == 42 && series->Find("stats")->Find("changes")->AsInteger() == 3,
+          "a trace collects a value per frame with its stats");
+
+    for (std::int32_t i = 1; i <= 3; ++i) {
+        Sample("residual", 0.5 * i);
+        Pump();
+    }
+    auto history = Send("debug.trace", R"({"paths": ["residual"], "history": true})");
+    Pump();
+    const Value historyReply = ResultOf(*history);
+    const Value* samples = historyReply.Find("series") ? historyReply.Find("series")->Find("residual") : nullptr;
+    Check(samples != nullptr && samples->Find("values")->Size() == 3 && samples->Find("stats")->Find("last")->AsNumber() == 1.5, "a trace can read a sample's history");
+
+    Log("net", "hello {}", 1);
+    LogWarn("net", "careful");
+    const Value warnings = ResultOf(*Send("debug.log", R"({"level": "warn"})"));
+    Check(warnings.Find("entries")->Size() == 1 && warnings.Find("entries")->Items()[0].Find("message")->AsString() == "careful", "the log filters by level");
+    Check(CodeOf(*Send("debug.log", R"({"level": "loud"})")) == "InvalidParams", "an unknown level is refused");
+
+    auto follow = Send("debug.log", R"({"follow": true, "category": "game"})");
+    Log("game", "one");
+    Log("other", "skip");
+    Log("game", "two");
+    const std::vector<Value> lines = follow->Lines();
+    Check(lines.size() == 2 && lines[1].Find("entry")->Find("message")->AsString() == "two", "a follower receives new matching entries, in order");
+    follow->refuse = true;
+    Log("game", "three");
+    Check(ResultOf(*Send("debug.status")).Find("following")->AsInteger() == 0, "a follower that cannot keep up is dropped");
+
+    auto brief = Send("debug.log", R"({"follow": true, "forMs": 1})");
+    std::this_thread::sleep_for(std::chrono::milliseconds(10));
+    Pump();
+    Check(brief->Final().has_value() && ResultOf(*brief).Find("ended") != nullptr, "a follow ends when its time is up");
+
+    return failures == 0 ? 0 : 1;
+}