@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/server/lib/realtime/topics/workspace.server.ts

@@ -0,0 +1,106 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The WORKSPACE-scoped topics: `git:<root>\0<repo>`, `fs:<scope>`,
+ * `repos:<root>` and `wiki:<scope>`.
+ *
+ * All four describe one working tree and take the panel's own scope string
+ * (`root\0repo`, or a bare root for repo discovery) — the same key
+ * `workspace.activeRepo` stores, so a scope that names no resolvable root is
+ * refused rather than answered for the wrong tree.
+ *
+ * Each resolver calls the SAME lib function its HTTP route does, so a panel
+ * renders one answer whichever path delivered it.
+ */
+
+import { type TopicDescriptor } from '@/server/lib/realtime/hub.server';
+import { getDefaultFsRoot, resolveRoot, resolveWithinRoot } from '@/server/lib/fs/root';
+import { readGitStatus } from '@/server/lib/fs/git-status-read';
+import { listDirectoryEntries } from '@/server/lib/fs/listing';
+import { discoveredRepos, startRepoScan } from '@/server/lib/fs/git-repos';
+import { buildWikiRepoPayload } from '@/server/lib/wiki/payload.server';
+
+/**
+ * Split a workspace topic's scope into its root and repo parts.
+ *
+ * The root is resolved through `resolveRoot`, which is the security boundary: a
+ * topic may only name a tree the caller could have asked for over HTTP, and an
+ * unresolvable root answers null rather than a default nobody asked for.
+ */
+async function resolveScope(scope: string): Promise<{ root: string; repo: string } | null> {
+  const separator = scope.indexOf('\u0000');
+  const rootPart = separator === -1 ? scope : scope.slice(0, separator);
+  const repo = (separator === -1 ? '.' : scope.slice(separator + 1)) || '.';
+  const root = await resolveRoot(rootPart || null, await getDefaultFsRoot(false));
+  if (!root) return null;
+  return { root, repo };
+}
+
+/**
+ * One working tree's git status, as the panel renders its change list.
+ *
+ * The count is `local`, never `fetch`: the panel renders this topic's payload
+ * as its change list, and the ahead/behind it carries must therefore follow
+ * every push a tool call makes. A fetch here would be a network round trip per
+ * publish, so the badge would still read the pre-push numbers — the bug this
+ * replaces. The panel's own read (`?sync=1`) is what refreshes the tracking ref
+ * before counting, which is why `behind` becomes honest on mount and Refresh.
+ */
+async function gitResolve(scope: string): Promise<unknown> {
+  const parsed = await resolveScope(scope);
+  if (!parsed) return null;
+  const targetDir = parsed.repo === '.' ? parsed.root : resolveWithinRoot(parsed.root, parsed.repo);
+  if (!targetDir) return null;
+  return readGitStatus(targetDir, { count: 'local' });
+}
+
+/** One working tree's root listing, as the file explorer renders it. */
+async function fsResolve(scope: string): Promise<unknown> {
+  const parsed = await resolveScope(scope);
+  if (!parsed) return null;
+  const baseDir = parsed.repo === '.' ? parsed.root : resolveWithinRoot(parsed.root, parsed.repo);
+  if (!baseDir) return null;
+  try {
+    return { files: await listDirectoryEntries(baseDir, baseDir), root: baseDir, path: '.' };
+  } catch {
+    return null;
+  }
+}
+
+/** One workspace root's nested repositories, and whether discovery is running. */
+async function reposResolve(scope: string): Promise<unknown> {
+  const root = await resolveRoot(scope || null, await getDefaultFsRoot(false));
+  if (!root) return null;
+  startRepoScan(root);
+  const { repos, pending } = discoveredRepos(root);
+  return { repos, reposPending: pending };
+}
+
+/** One wiki's tree, scoped by `root\0repo`. */
+async function wikiResolve(scope: string): Promise<unknown> {
+  const parsed = await resolveScope(scope);
+  if (!parsed) return null;
+  return buildWikiRepoPayload(parsed.root, parsed.repo);
+}
+
+const RESOLVERS: Record<string, (scope: string) => Promise<unknown>> = {
+  git: gitResolve,
+  fs: fsResolve,
+  repos: reposResolve,
+  wiki: wikiResolve,
+};
+
+/**
+ * A descriptor for one workspace family. The resolver is picked by family name,
+ * so a prefix with no resolver is a topic the hub does not serve.
+ */
+export function workspaceDescriptor(family: string): (scope: string) => TopicDescriptor {
+  return (scope) => {
+    const resolve = RESOLVERS[family];
+    if (!resolve) throw new Error(`No workspace resolver for ${family}`);
+    return { resolve: () => resolve(scope) };
+  };
+}

package/src/server/lib/realtime/topics.server.test.ts

@@ -0,0 +1,255 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `publishTopic` must re-resolve through the descriptor the HUB was registered
+ * with.
+ *
+ * The failure this pins is silent in production and total: the publisher used
+ * its own module-level descriptor table, which holds only the exact-name
+ * topics. A scoped name (`git:<root>\0<repo>`, `fs:`, `repos:`, `wiki:`) is not
+ * in that table, so the lookup returned `null` and every subscriber's panel was
+ * BLANKED by a `delta null` instead of re-read — while the resolver that should
+ * have run never did. The same lookup also bypassed the registered table
+ * entirely, which is why a test with its own topic set saw the production
+ * resolver run.
+ */
+
+import { afterEach, describe, expect, test, vi } from 'bun:test';
+
+import { getRealtimeHub, registerTopics, resetRealtimeHub, type RealtimeConnection } from '@/server/lib/realtime/hub.server';
+import { initRealtimeTopics, publishTopic, republishSessionDataTopics } from '@/server/lib/realtime/topics.server';
+import { emitRealtimeSignal, clearRealtimeSignalListeners } from '@/server/lib/realtime/signals.server';
+import { TOPIC_MODELS, TOPIC_USAGE, gitTopic, sessionQueueTopic, sessionTodosTopic, sessionTopic, type RealtimeServerFrame } from '@/shared/lib/realtime/protocol';
+
+interface FakeConnection extends RealtimeConnection {
+  frames: RealtimeServerFrame[];
+}
+
+function connect(): FakeConnection {
+  const connection: FakeConnection = {
+    topics: new Set<string>(),
+    snapshotted: new Set<string>(),
+    closed: false,
+    frames: [],
+    send: (frame) => {
+      connection.frames.push(frame);
+    },
+  };
+  return connection;
+}
+
+/**
+ * Run the publisher's coalescing window and then drain the resolve's microtask
+ * chain. Deterministic: the clock is advanced, not waited on.
+ */
+async function flushPublish(): Promise<void> {
+  vi.advanceTimersByTime(200);
+  for (let tick = 0; tick < 32; tick += 1) await Promise.resolve();
+}
+
+afterEach(() => {
+  vi.useRealTimers();
+  resetRealtimeHub();
+  // The wiring test installs the real listener; leaving it in place would let a
+  // later suite's signal reach this hub.
+  clearRealtimeSignalListeners();
+  globalThis.__kabmoRealtimeTopicsReady = undefined;
+  // The dedupe/coalesce state is process state too; a payload identical to the
+  // previous test's would otherwise be skipped as a no-op publish.
+  globalThis.__kabmoRealtimePublish = undefined;
+});
+
+describe('publishTopic', () => {
+  test('a scoped topic is re-resolved and its subscribers get the new value', async () => {
+    vi.useFakeTimers();
+    const topic = gitTopic('/ws\u0000.');
+    let changes = 1;
+    registerTopics(new Map([[topic, { resolve: async () => ({ changes }) }]]));
+
+    const hub = getRealtimeHub();
+    const connection = connect();
+    hub.subscribe(connection, topic);
+    for (let tick = 0; tick < 32; tick += 1) await Promise.resolve();
+    expect(connection.frames).toHaveLength(1);
+
+    changes = 3;
+    connection.frames.length = 0;
+    publishTopic(topic);
+    await flushPublish();
+
+    // A DELTA carrying the fresh payload — not `null`, which is what the
+    // module-local lookup produced for a name it did not hold.
+    expect(connection.frames).toEqual([
+      { t: 'delta', topic, seq: 1, payload: { changes: 3 } },
+    ]);
+  });
+
+  test('the registered resolver is the one called, not a module-local copy', async () => {
+    vi.useFakeTimers();
+    const topic = gitTopic('/ws\u0000.');
+    let calls = 0;
+    registerTopics(new Map([[topic, { resolve: async () => { calls += 1; return { marker: 'registered' }; } }]]));
+
+    const hub = getRealtimeHub();
+    const connection = connect();
+    hub.subscribe(connection, topic);
+    for (let tick = 0; tick < 32; tick += 1) await Promise.resolve();
+
+    connection.frames.length = 0;
+    publishTopic(topic);
+    await flushPublish();
+
+    expect(calls).toBe(2);
+    expect(connection.frames[0]).toMatchObject({ t: 'delta', payload: { marker: 'registered' } });
+  });
+});
+
+describe('initRealtimeTopics signal wiring', () => {
+  /**
+   * `models-changed` fires on every provider write — connect/disconnect, a new
+   * models.yml entry, a key edit — and the Usage surfaces list exactly the
+   * credentialed providers. The `usage` topic had NO producer at all: it
+   * answered its snapshot on subscribe and then never moved, so a key added in
+   * another tab (or by a settings write here) never reached an open panel.
+   *
+   * Both topics are watched here because the signal must republish both: the
+   * model catalog and the credential list move together.
+   */
+  test('a models-changed signal republishes both models and usage', async () => {
+    vi.useFakeTimers();
+    // The real registration first (that is what installs the signal listener),
+    // then the stubs override its descriptors — the hub reads whatever map was
+    // registered last.
+    globalThis.__kabmoRealtimeTopicsReady = undefined;
+    initRealtimeTopics();
+    let modelsCalls = 0;
+    let usageCalls = 0;
+    registerTopics(new Map([
+      [TOPIC_MODELS, { resolve: async () => ({ models: ++modelsCalls }) }],
+      [TOPIC_USAGE, { resolve: async () => ({ providers: ++usageCalls }) }],
+    ]));
+
+    const hub = getRealtimeHub();
+    const connection = connect();
+    hub.subscribe(connection, TOPIC_MODELS);
+    hub.subscribe(connection, TOPIC_USAGE);
+    for (let tick = 0; tick < 32; tick += 1) await Promise.resolve();
+    connection.frames.length = 0;
+
+    emitRealtimeSignal('models-changed');
+    await flushPublish();
+
+    expect(connection.frames).toEqual([
+      { t: 'delta', topic: TOPIC_MODELS, seq: 1, payload: { models: 2 } },
+      { t: 'delta', topic: TOPIC_USAGE, seq: 1, payload: { providers: 2 } },
+    ]);
+  });
+
+  /**
+   * The reported failure: "sometimes the second prompt's answer does not
+   * stream until I reload". A session's omp child is routinely REPLACED under a
+   * live subscriber — idle-reaped, respawned for an approval-mode change, or
+   * restarted after a crash — and `attach` binds a topic to its source once per
+   * subscription. Without a rebind the topic stays wired to the dead child, so
+   * the client keeps its subscription and gets a snapshot (`running:true`, the
+   * indicator resumes) and then NO frames, until a reload re-subscribes.
+   * `session-attached` is raised by the spawn path exactly when the new child
+   * is reachable, so it must both rebind and re-snapshot.
+   */
+  test('session-attached rebinds the topic and re-snapshots it', async () => {
+    vi.useFakeTimers();
+    globalThis.__kabmoRealtimeTopicsReady = undefined;
+    initRealtimeTopics();
+    const topic = sessionTopic('sess-1');
+    let attaches = 0;
+    let detaches = 0;
+    let resolves = 0;
+    // A fresh descriptor stands in for the session topic: the point is the
+    // wiring, not the resolver's payload.
+    registerTopics(new Map([[topic, {
+      resolve: async () => ({ resolves: ++resolves }),
+      attach: () => {
+        attaches += 1;
+        return () => {
+          detaches += 1;
+        };
+      },
+    }]]));
+
+    const hub = getRealtimeHub();
+    const connection = connect();
+    hub.subscribe(connection, topic);
+    await flushPublish();
+    expect(attaches).toBe(1);
+
+    connection.frames.length = 0;
+    emitRealtimeSignal('session-attached', 'sess-1');
+    await flushPublish();
+
+    // Rebound to the replacement child AND re-snapshotted for the subscriber.
+    expect(detaches).toBe(1);
+    expect(attaches).toBe(2);
+    expect(connection.frames).toEqual([{ t: 'snapshot', topic, seq: 0, payload: { resolves: 2 } }]);
+  });
+});
+
+describe('republishSessionDataTopics', () => {
+  /**
+   * The four `session:<id>:<suffix>` topics are served by a resolver and nothing
+   * else — no writer calls them. Without a republish they answered their
+   * snapshot and then never moved, so the todo/plan/telemetry/queue panels
+   * showed whatever existed when they subscribed and only a reload showed the
+   * new state. This is that gap.
+   */
+  test('every WATCHED data topic of one session is re-resolved', async () => {
+    vi.useFakeTimers();
+    const sessionId = 'sess-1';
+    const todos = sessionTodosTopic(sessionId);
+    const queue = sessionQueueTopic(sessionId);
+    const other = sessionTodosTopic('sess-2');
+    let todosCalls = 0;
+    let queueCalls = 0;
+    registerTopics(new Map([
+      [todos, { resolve: async () => { todosCalls += 1; return { todos: todosCalls }; } }],
+      [queue, { resolve: async () => { queueCalls += 1; return { queue: queueCalls }; } }],
+      [other, { resolve: async () => ({ todos: 'other' }) }],
+    ]));
+
+    const hub = getRealtimeHub();
+    const connection = connect();
+    hub.subscribe(connection, todos);
+    hub.subscribe(connection, queue);
+    for (let tick = 0; tick < 32; tick += 1) await Promise.resolve();
+    expect(connection.frames).toHaveLength(2);
+
+    connection.frames.length = 0;
+    republishSessionDataTopics(sessionId);
+    await flushPublish();
+
+    expect(connection.frames).toEqual([
+      { t: 'delta', topic: todos, seq: 1, payload: { todos: 2 } },
+      { t: 'delta', topic: queue, seq: 1, payload: { queue: 2 } },
+    ]);
+    // Another session's topic is untouched, and an UNWATCHED topic of this one
+    // is never resolved — the whole point of reading the subscribed set.
+    expect(todosCalls).toBe(2);
+    expect(queueCalls).toBe(2);
+  });
+
+  test('a session with nothing watched resolves nothing', async () => {
+    vi.useFakeTimers();
+    const sessionId = 'sess-1';
+    let calls = 0;
+    registerTopics(new Map([
+      [sessionTodosTopic(sessionId), { resolve: async () => { calls += 1; return null; } }],
+    ]));
+
+    republishSessionDataTopics(sessionId);
+    await flushPublish();
+
+    expect(calls).toBe(0);
+  });
+});

package/src/server/lib/realtime/topics.server.ts

@@ -0,0 +1,261 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The topic registry: which topics exist, how each produces its snapshot, and
+ * the named publishers a producer calls instead of knowing about the hub.
+ *
+ * Split from `hub.server.ts` (which owns the delivery mechanics) so this file
+ * stays about WHAT is served and that one stays about HOW. Every resolver is
+ * read-only by contract — subscribing must never spawn an omp child for a
+ * session nobody is driving (see the plan's server-side invariants).
+ */
+
+import {
+  TOPIC_MODELS,
+  TOPIC_PANELS,
+  TOPIC_SCHEDULE,
+  TOPIC_SIDEBAR,
+  TOPIC_SIDEBAR_STATUS,
+  TOPIC_USAGE,
+  isValidTopic,
+  reposTopic,
+  sessionTopic,
+} from '@/shared/lib/realtime/protocol';
+import { getRealtimeHub, registerTopics, type TopicDescriptor } from '@/server/lib/realtime/hub.server';
+import { onRealtimeSignal } from '@/server/lib/realtime/signals.server';
+import { invalidateOmpSidebarData } from '@/server/lib/omp/session/reader';
+import { loadSidebarStatus, loadSidebarStructure } from '@/server/lib/omp/session/sidebar-data.server';
+import { EXACT_TOPICS, descriptorFor, isKnownTopicName } from '@/server/lib/realtime/topics/catalog.server';
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __kabmoRealtimeTopicsReady: boolean | undefined;
+}
+
+/**
+ * Window a burst of change signals collapses into one publish. A single run
+ * writes the stream status several times within milliseconds, and each write
+ * would otherwise cost a status read plus a fan-out to every tab.
+ */
+const PUBLISH_COALESCE_MS = 120;
+
+/**
+ * Build the descriptor map the hub serves.
+ *
+ * Scoped topics are resolved LAZILY through a proxy map: the hub asks for a
+ * topic's descriptor by name at subscribe time, and building every possible
+ * `session:<uuid>` up front is impossible. The proxy answers `get`/`has` for any
+ * known-prefix name, which are the only operations the hub performs.
+ */
+function buildDescriptors(): Map<string, TopicDescriptor> {
+  const map = new Map(EXACT_TOPICS);
+  return new Proxy(map, {
+    get(target, property, receiver) {
+      if (property === 'get') {
+        return (topic: string) => target.get(topic) ?? (isKnownTopicName(topic) ? descriptorFor(topic) : undefined);
+      }
+      if (property === 'has') {
+        return (topic: string) => target.has(topic) || isKnownTopicName(topic);
+      }
+      return Reflect.get(target, property, receiver);
+    },
+  });
+}
+
+/**
+ * Register the topic set with the hub. Idempotent: a `bun --hot` reload
+ * re-registers the same map rather than accumulating descriptors, and a second
+ * call from the route's boot path is a no-op.
+ */
+export function initRealtimeTopics(): void {
+  if (globalThis.__kabmoRealtimeTopicsReady) return;
+  globalThis.__kabmoRealtimeTopicsReady = true;
+  registerTopics(buildDescriptors());
+  onRealtimeSignal(({ signal, sessionId, root }) => {
+    if (signal === 'stream-status') publishSidebarStatus();
+    else if (signal === 'sidebar-structure') publishSidebarStructure();
+    else if (signal === 'session-attached' && sessionId) publishSessionState(sessionId);
+    else if (signal === 'schedule-changed') publishTopic(TOPIC_SCHEDULE);
+    else if (signal === 'panels-changed') publishTopic(TOPIC_PANELS);
+    else if (signal === 'models-changed') {
+      publishTopic(TOPIC_MODELS);
+      // A provider write is also a CREDENTIAL write (connect/disconnect, a new
+      // models.yml entry, a key edit), and the Usage surfaces list exactly the
+      // credentialed providers. Without this the `usage` topic had no producer
+      // at all, so a key added in another tab never reached an open panel. The
+      // probe it re-runs is cached for a minute, so a burst of writes costs one
+      // resolve.
+      publishTopic(TOPIC_USAGE);
+    }
+    else if (signal === 'workspace-dirty') republishWatchedWorkspaceTopics();
+    else if (signal === 'session-data-dirty' && sessionId) republishSessionDataTopics(sessionId);
+    else if (signal === 'repos-scanned' && root) publishTopic(reposTopic(root));
+  });
+}
+
+/** Whether this hub serves `topic`. Consulted before a subscribe is accepted. */
+export function isKnownTopic(topic: string): boolean {
+  return isValidTopic(topic) && getRealtimeHub().knows(topic);
+}
+
+/**
+ * Re-resolve a topic whose producer just changed it, coalescing a burst.
+ *
+ * Used by the GLOBAL topics and by the workspace families: their payloads are
+ * produced on demand, so a write is reported by re-resolving rather than by
+ * streaming the change.
+ *
+ * The resolve goes through the HUB's own descriptor table, never this module's
+ * `EXACT_TOPICS`/`descriptorFor`: the registry is what the hub was actually
+ * given, and re-resolving from a private copy answered from a different map —
+ * a `git:`/`fs:`/`repos:`/`wiki:` name is absent from `EXACT_TOPICS`, so the
+ * lookup returned `null` and every subscriber's panel was BLANKED instead of
+ * re-read. (In a test with its own topic set it also ran the production
+ * resolver, which is how that surfaced.)
+ */
+export function publishTopic(topic: string): void {
+  schedulePublish(topic, () => getRealtimeHub().resolve(topic));
+}
+
+/**
+ * Republish every workspace topic that someone is watching.
+ *
+ * A turn boundary means the working tree and the session's usage may both have
+ * moved, but the topics are scoped to trees this process does not know about
+ * until it is asked — so the SUBSCRIBED set is the list, not a guess. Only
+ * watched topics are re-read, so a tab with no git panel pays nothing.
+ */
+export function republishWatchedWorkspaceTopics(): void {
+  for (const topic of getRealtimeHub().activeTopics()) {
+    if (topic.startsWith('git:') || topic.startsWith('fs:')) publishTopic(topic);
+  }
+}
+
+/**
+ * Republish every watched DATA topic of one session (`todos`, `plan`,
+ * `telemetry`, `queue`).
+ *
+ * The list is the SUBSCRIBED set, not all four: a tab that never opened the
+ * todo panel pays nothing, and the topic's own resolver is the only reader that
+ * knows how expensive it is (`todos` parses a whole transcript, `telemetry`
+ * scans it). Publishing unconditionally would run both for every turn of every
+ * session, which is the polling this channel replaced.
+ */
+export function republishSessionDataTopics(sessionId: string): void {
+  const prefix = `session:${sessionId}:`;
+  for (const topic of getRealtimeHub().activeTopics()) {
+    if (topic.startsWith(prefix)) publishTopic(topic);
+  }
+}
+
+/**
+ * A session's live state changed outside its own frame stream — it was just
+ * spawned, adopted, or its run settled.
+ *
+ * REBINDS the topic as well as re-snapshotting it. `attach` binds a topic to
+ * its source once per subscription, and this is where that source is replaced:
+ * a subscriber watching when the child was idle-reaped, respawned for a mode
+ * change, or restarted after a crash still holds its subscription and would
+ * otherwise get snapshots and then silence — a live-looking run with no frames
+ * until the page reloads and re-subscribes. Also covers the reverse order: a
+ * topic subscribed before any child existed bound the peer-relay probe, which
+ * finds no owner for a session this process is about to own.
+ */
+export function publishSessionState(sessionId: string): void {
+  const topic = sessionTopic(sessionId);
+  getRealtimeHub().rebind(topic);
+  getRealtimeHub().republishSnapshot(topic);
+}
+
+// ---------------------------------------------------------------------------
+// Publishers — the names a producer calls
+// ---------------------------------------------------------------------------
+
+/**
+ * Coalescing and dedupe state, on `globalThis` for the reason the hub is: a
+ * hot reload must not leave a pending timer writing into a discarded map.
+ */
+interface PublishState {
+  timers: Map<string, number | NodeJS.Timeout>;
+  /** JSON of the last payload published per topic, to skip no-op republishes. */
+  last: Map<string, string>;
+}
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __kabmoRealtimePublish: PublishState | undefined;
+}
+
+function publishState(): PublishState {
+  return (globalThis.__kabmoRealtimePublish ??= { timers: new Map(), last: new Map() });
+}
+
+/**
+ * Publish a topic's freshly produced payload, coalescing a burst into one send
+ * and skipping a payload identical to the last one.
+ *
+ * Both halves are load-bearing. A single run writes the stream status several
+ * times (`turn_start`, `agent_start`, `message_start`, `message_end`), and each
+ * write would otherwise cost a full status read plus a fan-out to every tab —
+ * more work than the 8s poll this replaces. Dedupe catches the common case
+ * where the row did not actually move (the status was already `stream`).
+ */
+export function schedulePublish(topic: string, produce: () => Promise<unknown>): void {
+  const state = publishState();
+  if (state.timers.has(topic)) return;
+  state.timers.set(
+    topic,
+    setTimeout(() => {
+      state.timers.delete(topic);
+      const hub = getRealtimeHub();
+      if (!hub.knows(topic)) return;
+      void produce().then(
+        (payload) => {
+          const encoded = JSON.stringify(payload);
+          if (state.last.get(topic) === encoded) return;
+          state.last.set(topic, encoded);
+          hub.publish(topic, payload);
+        },
+        () => {
+          // A failed read leaves subscribers on their last good value; the next
+          // signal republishes. Publishing an empty payload would blank every
+          // spinner in every tab over a transient database hiccup.
+        },
+      );
+    }, PUBLISH_COALESCE_MS),
+  );
+}
+
+/**
+ * A sidebar session's volatile fields changed (a run started, ended, aborted,
+ * or the session became blocked on a dialog).
+ *
+ * Publishes the whole status map rather than one entry: it is one SQLite read
+ * and a small object, and a per-entry delta would need the client to merge
+ * removals — a session that finished has its badge CLEARED when opened, which
+ * is a deletion, not a value.
+ */
+export function publishSidebarStatus(): void {
+  schedulePublish(TOPIC_SIDEBAR_STATUS, loadSidebarStatus);
+}
+
+/**
+ * The sidebar's STRUCTURE changed: a session was created, deleted, renamed, a
+ * folder was added or removed, or a JSONL grew a new session.
+ *
+ * Separate from `publishSidebarStatus` because producing it runs a full omp
+ * discovery scan — so it is published on structure events only, never on a
+ * status flip.
+ *
+ * The scan cache is dropped FIRST, and that is not an optimisation: the signal
+ * says something structural moved, while the discovery scan is TTL'd (4s) and
+ * would otherwise answer with the snapshot taken before the change — a new
+ * session would not appear in the very publish that announced it.
+ */
+export function publishSidebarStructure(): void {
+  invalidateOmpSidebarData();
+  schedulePublish(TOPIC_SIDEBAR, loadSidebarStructure);
+}

package/src/server/lib/remix-compat.ts

@@ -0,0 +1,29 @@
+/**
+ * The `@remix-run/node` surface the API route modules actually used: the
+ * `json()` response helper and the two context argument types. Elysia serves
+ * these modules now (see `@/server/lib/route-adapter`), so the shim keeps the
+ * loader/action bodies — and therefore every status code and payload — intact.
+ */
+export interface LoaderFunctionArgs {
+  request: Request;
+  params: Record<string, string>;
+}
+
+export interface ActionFunctionArgs {
+  request: Request;
+  params: Record<string, string>;
+}
+
+export interface JsonInit {
+  status?: number;
+  headers?: Record<string, string>;
+}
+
+export function json(data: unknown, init: JsonInit = {}): Response {
+  const headers = new Headers(init.headers);
+  if (!headers.has('content-type')) headers.set('content-type', 'application/json; charset=utf-8');
+  return new Response(JSON.stringify(data), { status: init.status ?? 200, headers });
+}
+
+/** Shared no-store response headers for endpoints that must never be cached. */
+export const NO_STORE_HEADERS: Record<string, string> = { 'cache-control': 'no-store' };