daemon: event.* fan-out (D5) + category.list/queue.list (D3) — GUI-ready

The two items aimed at pointing GUI at a real veloxd instead of mockd.

rpc/event_hub — per-subscription fan-out shared by both transports.
subscribe() registers a connection with no interest; set_filter()
(session.subscribe, replaces not adds) turns on event kinds and an
optional per-task id filter; publish() delivers a pre-built
notification to every matching subscriber. session.subscribe on both
UdsServer and WsServer now does the real thing — registers/updates a
subscription, tears it down in close_conn.

sched/scheduler — the on_engine_state hook now actually publishes:
- transition() is the one place a task's row changes state; it reads
  the store's own prior row for previousState (authoritative
  regardless of engine/scheduler timing), writes the error columns,
  and — when a hub is supplied — publishes event.task.state with
  {taskId, state, previousState, summary, error}. Wired into every
  transition: scheduler-driven (admission -> probing, resume ->
  connecting, pause) and engine-reported (on_engine_state).
- progress_snapshot(): one row per task the engine is tracking
  (EnginePort::progress(), a new interface method backed by
  DownloadHandle::progress()), plus a store side-effect
  (Tasks::update_progress) so download.list/get stay current between
  state transitions. Returns rows; does NOT publish itself — batching
  into one array message is the caller's job, per the schema's
  x-maxRateHz: 4 and AGENT-DAEMON.md item 5 ("one message per task per
  tick burns a core"). main.cpp's 250 ms timerfd is that caller: one
  event.task.progress per tick, only when there's something to say.

dispatcher::on_download_add now publishes event.task.added (schema:
"summary is always present so a client can insert the row without a
follow-up download.get").

store/categories, store/queues — the two D3 handlers GUI's panels
call. category.list projects the six seeded built-ins; queue.list
derives taskIds from tasks.queue_id/queue_position (Queue's own schema
note: a queue's stored row never carries membership, download.update
/ queue.reorder do).

Verified live end to end against tools/testserver: a subscribed client
sees event.task.added on add, then the full event.task.state sequence
(queued -> probing -> connecting -> downloading -> assembling ->
verifying -> complete) with correct previousState at every step, and
real category.list / queue.list results.

Tests: event_hub (filter-by-kind, filter-by-task-id, replace-not-add,
unsubscribe), store_categories_queues, plus new sched_scheduler cases
for event.task.state publishing and progress_snapshot's store
side-effect. 38 daemon/cli tests green; sched_scheduler / event_hub /
ws_server / uds_roundtrip TSan-clean.

deferrals.md: D5 mostly closed (event.task.removed and the
still-unpublished events wait on their owning D3 handlers); D3 down to
the remaining download.* verbs, rules/settings/limiter/schedule,
queue mutation, category mutation, grabber, media.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Upd9WhG9oppieig5nRDLig

daemon/tests/CMakeLists.txt

@@ -20,4 +20,6 @@ veloxd_test(sched_window     LIBS veloxd_sched)
 veloxd_test(sched_governor   LIBS veloxd_sched)
 veloxd_test(safepath         LIBS veloxd_fs)
 veloxd_test(store_tasks      LIBS veloxd_store)
-veloxd_test(sched_scheduler  LIBS veloxd_sched)
+veloxd_test(sched_scheduler  LIBS veloxd_sched veloxd_rpc)
+veloxd_test(event_hub               LIBS veloxd_rpc)
+veloxd_test(store_categories_queues LIBS veloxd_store)

daemon/tests/event_hub_test.cpp

@@ -0,0 +1,68 @@
+#include "rpc/event_hub.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include "check.hpp"
+
+using velox::daemon::rpc::EventHub;
+namespace proto = velox::proto;
+
+void run() {
+    EventHub hub;
+
+    // --- no subscribers: publish is a no-op, not an error --------------------------
+    hub.publish(proto::Event::TaskAdded, nlohmann::json{{"x", 1}});
+
+    // --- a subscription with no filter set receives nothing -------------------
+    std::vector<nlohmann::json> a;
+    const auto sub_a = hub.subscribe([&](const nlohmann::json& n) { a.push_back(n); });
+    hub.publish(proto::Event::TaskAdded, nlohmann::json{{"n", 1}});
+    CHECK_EQ(a.size(), 0u);
+
+    // --- filtering by event kind ------------------------------------------------
+    hub.set_filter(sub_a, {proto::Event::TaskAdded}, std::nullopt);
+    hub.publish(proto::Event::TaskAdded, nlohmann::json{{"n", 2}});
+    hub.publish(proto::Event::TaskRemoved, nlohmann::json{{"n", 3}});  // not subscribed
+    CHECK_EQ(a.size(), 1u);
+    CHECK_EQ(a[0]["n"].get<int>(), 2);
+
+    // --- two subscribers, independent filters -----------------------------------
+    std::vector<nlohmann::json> b;
+    const auto sub_b = hub.subscribe([&](const nlohmann::json& n) { b.push_back(n); });
+    hub.set_filter(sub_b, {proto::Event::TaskRemoved}, std::nullopt);
+    hub.publish(proto::Event::TaskAdded, nlohmann::json{{"n", 4}});
+    hub.publish(proto::Event::TaskRemoved, nlohmann::json{{"n", 5}});
+    CHECK_EQ(a.size(), 2u);   // got the TaskAdded
+    CHECK_EQ(b.size(), 1u);   // got the TaskRemoved
+    CHECK_EQ(b[0]["n"].get<int>(), 5);
+
+    // --- per-task filter: only the named ids reach the subscriber ---------------
+    std::vector<nlohmann::json> c;
+    const auto sub_c = hub.subscribe([&](const nlohmann::json& n) { c.push_back(n); });
+    hub.set_filter(sub_c, {proto::Event::TaskState},
+                   std::vector<std::string>{"t1", "t2"});
+    hub.publish(proto::Event::TaskState, nlohmann::json{{"n", 6}}, "t1");
+    hub.publish(proto::Event::TaskState, nlohmann::json{{"n", 7}}, "t9");  // filtered out
+    hub.publish(proto::Event::TaskState, nlohmann::json{{"n", 8}}, "t2");
+    CHECK_EQ(c.size(), 2u);
+    CHECK_EQ(c[0]["n"].get<int>(), 6);
+    CHECK_EQ(c[1]["n"].get<int>(), 8);
+
+    // --- a non-task-scoped publish (no task_id) reaches a task-filtered sub too --
+    // (matches "session.subscribe narrows task events" — a global event isn't one)
+    hub.publish(proto::Event::TaskState, nlohmann::json{{"n", 9}});
+    CHECK_EQ(c.size(), 3u);
+
+    // --- set_filter replaces, it does not add -----------------------------------
+    hub.set_filter(sub_a, {proto::Event::TaskRemoved}, std::nullopt);
+    hub.publish(proto::Event::TaskAdded, nlohmann::json{{"n", 10}});
+    CHECK_EQ(a.size(), 2u);  // still 2 -- TaskAdded no longer reaches sub_a
+
+    // --- unsubscribe stops delivery ------------------------------------------
+    hub.unsubscribe(sub_b);
+    hub.publish(proto::Event::TaskRemoved, nlohmann::json{{"n", 11}});
+    CHECK_EQ(b.size(), 1u);  // unchanged
+    CHECK_EQ(a.size(), 3u);  // sub_a still gets TaskRemoved
+}
+
+TEST_MAIN()

daemon/tests/sched_scheduler_test.cpp

@@ -3,7 +3,10 @@
 
 #include <string>
 
+#include <nlohmann/json.hpp>
+
 #include "check.hpp"
+#include "rpc/event_hub.hpp"
 #include "sched/fake_engine_port.hpp"
 #include "sched/governor.hpp"
 #include "sched/scheduler.hpp"
@@ -91,10 +94,10 @@ void run() {
         CHECK_EQ(engine.starts.size(), 1u);  // b0 only
         CHECK_EQ(task_state(*db, "b0"), std::string("probing"));
 
-        sched.on_engine_state("b0", "downloading", std::nullopt);
+        sched.on_engine_state("b0", "probing", "downloading", std::nullopt);
         CHECK_EQ(task_state(*db, "b0"), std::string("downloading"));
 
-        sched.on_engine_state("b0", "complete", std::nullopt);
+        sched.on_engine_state("b0", "downloading", "complete", std::nullopt);
         CHECK_EQ(task_state(*db, "b0"), std::string("complete"));
 
         CHECK(sched.tick().has_value());  // b0 terminal -> b1 admitted
@@ -113,7 +116,7 @@ void run() {
         CHECK(tasks.insert(task("q0", "queued", "2026-09-10T10:00:00Z", "main", 0)).has_value());
         CHECK(sched.tick().has_value());
         CHECK_EQ(engine.starts.size(), 1u);
-        sched.on_engine_state("q0", "downloading", std::nullopt);
+        sched.on_engine_state("q0", "connecting", "downloading", std::nullopt);
 
         CHECK(db->exec("UPDATE queues SET state='stopped' WHERE queue_id='main'").has_value());
         CHECK(sched.tick().has_value());
@@ -143,7 +146,7 @@ void run() {
         ef.code = "auth_required";
         ef.message = "401";
         ef.http_status = 401;
-        sched.on_engine_state("auth", "paused", ef);
+        sched.on_engine_state("auth", "connecting", "paused", ef);
 
         store::Tasks t(*db);
         auto row = t.get("auth").value().value();
@@ -186,6 +189,76 @@ void run() {
         CHECK_EQ(engine.max_active_segments.back(), 12u);
         CHECK_EQ(sched.reload_config().has_value() ? 0 : 1, 0);
     }
+
+    // --- event.task.state: published on admission, on a paused transition, and on an
+    // engine-reported transition; previousState reflects the store's prior row ----------
+    {
+        for (const char* id : {"r0", "r1", "r2"}) tasks.remove(id);  // leftover from above
+        FakeEnginePort engine;
+        rpc::EventHub hub;
+        Scheduler sched(*db, engine, Governor(GovernorConfig{.max_concurrent_downloads = 10,
+                                                              .max_active_segments = 32}),
+                        &hub);
+        std::vector<nlohmann::json> received;
+        const auto sub = hub.subscribe([&](const nlohmann::json& n) { received.push_back(n); });
+        hub.set_filter(sub, {velox::proto::Event::TaskState}, std::nullopt);
+
+        CHECK(tasks.insert(task("ev0", "queued", "2026-09-10T10:00:00Z")).has_value());
+        CHECK(sched.tick().has_value());  // admits ev0: queued -> probing
+        CHECK_EQ(received.size(), 1u);
+        CHECK_EQ(received[0]["params"]["taskId"].get<std::string>(), std::string("ev0"));
+        CHECK_EQ(received[0]["params"]["state"].get<std::string>(), std::string("probing"));
+        CHECK_EQ(received[0]["params"]["previousState"].get<std::string>(), std::string("queued"));
+        CHECK(received[0]["params"]["error"].is_null());
+        CHECK_EQ(received[0]["params"]["summary"]["taskId"].get<std::string>(), std::string("ev0"));
+
+        sched.on_engine_state("ev0", "probing", "downloading", std::nullopt);
+        CHECK_EQ(received.size(), 2u);
+        CHECK_EQ(received[1]["params"]["previousState"].get<std::string>(), std::string("probing"));
+        CHECK_EQ(received[1]["params"]["state"].get<std::string>(), std::string("downloading"));
+
+        sched::TaskErrorFields ef;
+        ef.code = "connection_reset";
+        ef.message = "reset";
+        sched.on_engine_state("ev0", "downloading", "paused", ef);
+        CHECK_EQ(received.size(), 3u);
+        CHECK(!received[2]["params"]["error"].is_null());
+        CHECK_EQ(received[2]["params"]["error"]["code"].get<std::string>(),
+                 std::string("connection_reset"));
+
+        tasks.remove("ev0");
+    }
+
+    // --- progress_snapshot: only started tasks, plus a store side-effect --------------
+    {
+        FakeEnginePort engine;
+        Scheduler sched(*db, engine,
+                        Governor(GovernorConfig{.max_concurrent_downloads = 10,
+                                                .max_active_segments = 32}));
+        CHECK(tasks.insert(task("pr0", "queued", "2026-09-10T10:00:00Z")).has_value());
+        CHECK(sched.tick().has_value());
+        CHECK_EQ(engine.starts.size(), 1u);
+
+        vdm::task::Progress p;
+        p.downloaded = 12345;
+        p.speed_bps = 999;
+        p.effective_segments = 4;
+        p.effective_buffer_bytes = 65536;
+        engine.fake_progress[engine.starts[0].id.value] = p;
+
+        const auto snap = sched.progress_snapshot();
+        CHECK_EQ(snap.size(), 1u);
+        CHECK_EQ(snap[0].task_id, std::string("pr0"));
+        CHECK_EQ(snap[0].downloaded_bytes, 12345u);
+        CHECK_EQ(snap[0].speed_bps, 999u);
+
+        auto row = tasks.get("pr0").value().value();
+        CHECK_EQ(row.downloaded_bytes, 12345);
+        CHECK_EQ(row.eff_segments, 4);
+        CHECK((row.eff_buffer_bytes.has_value() && *row.eff_buffer_bytes == 65536));
+
+        tasks.remove("pr0");
+    }
 }
 
 TEST_MAIN()

daemon/tests/store_categories_queues_test.cpp

@@ -0,0 +1,78 @@
+// store/categories + store/queues: the two D3 handlers GUI's category panel and queue
+// view need against a real daemon.
+
+#include <string>
+
+#include "check.hpp"
+#include "store/categories.hpp"
+#include "store/migrations.hpp"
+#include "store/queues.hpp"
+#include "store/sqlite.hpp"
+#include "store/tasks.hpp"
+
+using namespace velox::daemon::store;
+
+void run() {
+    auto db = Db::open(":memory:");
+    CHECK(db.has_value());
+    if (!db) return;
+    CHECK(migrate_to_head(*db).has_value());
+
+    // --- categories: the six seeded built-ins, builtin first --------------------
+    {
+        Categories categories(*db);
+        auto items = categories.list();
+        CHECK(items.has_value());
+        if (items) {
+            CHECK_EQ(items->size(), 6u);
+            for (const auto& c : *items) CHECK(c.builtin);
+            const auto& programs =
+                *std::find_if(items->begin(), items->end(),
+                              [](const auto& c) { return c.categoryId == "programs"; });
+            CHECK(!programs.extensions.empty());
+            CHECK(std::find(programs.extensions.begin(), programs.extensions.end(), "iso") !=
+                  programs.extensions.end());
+        }
+    }
+
+    // --- queues: the seeded "main" queue, empty task list ------------------------
+    {
+        Queues queues(*db);
+        auto items = queues.list();
+        CHECK(items.has_value());
+        if (items) {
+            CHECK_EQ(items->size(), 1u);
+            CHECK_EQ(items->front().queueId, std::string("main"));
+            CHECK(items->front().taskIds.has_value());
+            CHECK(items->front().taskIds->empty());
+        }
+    }
+
+    // --- queue.taskIds reflects membership, in queue_position order ------------
+    {
+        Tasks tasks(*db);
+        for (int i = 0; i < 3; ++i) {
+            TaskRow r;
+            r.task_id = "t" + std::to_string(i);
+            r.url = "https://example.com/" + r.task_id;
+            r.save_dir = "/tmp";
+            r.filename = r.task_id;
+            r.created_at = "2026-09-11T00:00:00Z";
+            r.queue_id = "main";
+            r.queue_position = 2 - i;  // reverse insertion order
+            CHECK(tasks.insert(r).has_value());
+        }
+        Queues queues(*db);
+        auto items = queues.list();
+        CHECK(items.has_value());
+        if (items && !items->empty()) {
+            const auto& ids = *items->front().taskIds;
+            CHECK_EQ(ids.size(), 3u);
+            CHECK_EQ(ids[0], std::string("t2"));  // queue_position 0
+            CHECK_EQ(ids[1], std::string("t1"));
+            CHECK_EQ(ids[2], std::string("t0"));
+        }
+    }
+}
+
+TEST_MAIN()

daemon/tests/uds_roundtrip_test.cpp

@@ -14,6 +14,7 @@
 
 #include "check.hpp"
 #include "rpc/dispatcher.hpp"
+#include "rpc/event_hub.hpp"
 #include "rpc/event_loop.hpp"
 #include "rpc/ndjson.hpp"
 #include "rpc/uds_server.hpp"
@@ -71,8 +72,9 @@ void run() {
     CHECK(velox::daemon::store::migrate_to_head(*db).has_value());
 
     rpc::EventLoop loop;
-    rpc::VeloxDispatcher dispatcher(*db);
-    rpc::UdsServer server(loop, dispatcher, sock);
+    rpc::EventHub hub;
+    rpc::VeloxDispatcher dispatcher(*db, hub);
+    rpc::UdsServer server(loop, dispatcher, hub, sock);
     const auto ec = server.start();
     CHECK(!ec);
     if (ec) return;

daemon/tests/ws_server_test.cpp

@@ -16,6 +16,7 @@
 
 #include "check.hpp"
 #include "rpc/dispatcher.hpp"
+#include "rpc/event_hub.hpp"
 #include "rpc/event_loop.hpp"
 #include "rpc/pairing.hpp"
 #include "rpc/runtime_dir.hpp"
@@ -123,9 +124,10 @@ void run() {
     rpc::RuntimeDir rt{dir ? dir : "/tmp"};
 
     rpc::EventLoop loop;
-    rpc::VeloxDispatcher dispatcher(*db);
+    rpc::EventHub hub;
+    rpc::VeloxDispatcher dispatcher(*db, hub);
     rpc::EnvAutoApprover approver;
-    rpc::WsServer server(loop, dispatcher, *db, approver, rt);
+    rpc::WsServer server(loop, dispatcher, *db, approver, hub, rt);
     const auto ec = server.start();
     CHECK(!ec);
     if (ec) return;