ompchamber 1.1.0 → 1.2.0

package/src/server/db.server.ts

@@ -1,27 +1,31 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Database lifecycle for OMPChamber: resolve the SQLite path, open the
+ * `bun:sqlite` client once, bootstrap the schema, and seed demo data in mock
+ * mode. The DDL lives in `./db/schema`, the mock presets in `./db/seed` and
+ * the workspace discovery sync in `./db/workspace-sync`.
+ */
+
 import path from 'path';
 import os from 'os';
 import fs from 'fs';
 import { createDb, type DbClient } from '@/server/lib/db/client';
+import { initSchema } from '@/server/lib/db/schema';
+import { seedMockData } from '@/server/lib/db/seed';
+import { syncWorkspaceFoldersFromDiscovery } from '@/server/lib/db/workspace-sync';
 import { isMockMode } from '@/server/mock.server';
-import { SAMPLE_TOOLS_SESSION_ID, getSampleToolsSession } from '@/client/data/samples/tools-session';
-import { SAMPLE_DIALOGUE_SESSION_ID, getSampleDialogueSession } from '@/client/data/samples/dialogue-session';
-import { SAMPLE_DEVICES_SESSION_ID, getSampleDevicesSession } from '@/client/data/samples/virtual-devices-session';
-import { loadOmpSidebarData } from '@/server/lib/omp/session/reader';
-import { pathExists, projectPathKey } from '@/server/lib/omp/core/paths';
+import { pathExists } from '@/server/lib/omp/core/paths';
+import { migrateLegacyProjectSettings } from '@/shared/lib/workspace/project-settings-migration';
 
 let dbPromise: Promise<DbClient> | null = null;
 /** Resolved handle cached by getDb(); promise callbacks never run sync, so
  *  hot paths unwrap through `getDbSync` instead of awaiting. */
 let dbResolved: DbClient | null = null;
 
-/** SYNC_WORKSPACE env flag (default true when unset). When enabled in real
- *  mode, workspace folders are auto-created from discovered omp projects. */
-export function isWorkspaceSyncEnabled(): boolean {
-  const raw = (Bun.env.SYNC_WORKSPACE || '').trim().toLowerCase();
-  if (raw === '') return true;
-  return raw !== 'false' && raw !== '0' && raw !== 'off' && raw !== 'no';
-}
-
 export async function getDatabasePath(): Promise<string> {
   if (isMockMode()) {
     return path.join(process.cwd(), 'workspace.db');
@@ -53,250 +57,19 @@ export async function getDb(): Promise<DbClient> {
     const dbPath = await getDatabasePath();
     const db = createDb(dbPath);
 
-    await db.exec(`
-      CREATE TABLE IF NOT EXISTS workspace_folders (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        name TEXT NOT NULL,
-        is_expanded BOOLEAN DEFAULT 0,
-        project_path TEXT,
-        model TEXT DEFAULT 'Not selected',
-        accent_color TEXT DEFAULT '',
-        icon TEXT DEFAULT 'default',
-        custom_icon_url TEXT,
-        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-      );
-      
-      CREATE TABLE IF NOT EXISTS sessions (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        folder_id INTEGER NOT NULL,
-        title TEXT NOT NULL,
-        is_active BOOLEAN DEFAULT 0,
-        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-        FOREIGN KEY (folder_id) REFERENCES workspace_folders (id)
-      );
-
-      CREATE TABLE IF NOT EXISTS app_settings (
-        key TEXT PRIMARY KEY,
-        value TEXT NOT NULL
-      );
-
-      CREATE TABLE IF NOT EXISTS chat_sessions (
-        session_id TEXT PRIMARY KEY,
-        title TEXT,
-        messages TEXT NOT NULL,
-        updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
-      );
-
-      CREATE TABLE IF NOT EXISTS deleted_workspaces (
-        project_path TEXT PRIMARY KEY,
-        deleted_at DATETIME DEFAULT CURRENT_TIMESTAMP
-      );
-
-      CREATE TABLE IF NOT EXISTS archived_sessions (
-        session_id TEXT PRIMARY KEY,
-        archived_at DATETIME DEFAULT CURRENT_TIMESTAMP
-      );
-
-      CREATE TABLE IF NOT EXISTS session_ui_state (
-        session_id TEXT PRIMARY KEY,
-        state TEXT NOT NULL DEFAULT '{}',
-        updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
-      );
-
-      CREATE TABLE IF NOT EXISTS queued_messages (
-        id TEXT PRIMARY KEY,
-        session_id TEXT NOT NULL,
-        position INTEGER NOT NULL,
-        message TEXT NOT NULL DEFAULT '',
-        attachments TEXT NOT NULL DEFAULT '[]',
-        provider TEXT,
-        model_id TEXT,
-        thinking_level TEXT,
-        access_mode TEXT,
-        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-      );
-      CREATE INDEX IF NOT EXISTS idx_queued_messages_session ON queued_messages (session_id, position);
-
-      CREATE TABLE IF NOT EXISTS session_stream_state (
-        session_id TEXT PRIMARY KEY,
-        status TEXT NOT NULL,
-        updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
-      );
-    `);
-
-    const { migrateWorkspaceFolderColumns } = await import('@/shared/lib/workspace/schema-migrations');
-    await migrateWorkspaceFolderColumns(db);
-    // Installs older `queued_messages` schemas carry an invalid FK (see the
-    // migration module); rebuild once so real-session queue inserts work.
-    const { migrateQueueTableFk } = await import('@/server/lib/queue/schema-migration.server');
-    await migrateQueueTableFk(db);
-
-    await db.exec(`
-      CREATE TABLE IF NOT EXISTS files (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        session_id INTEGER NOT NULL,
-        parent_id INTEGER,
-        name TEXT NOT NULL,
-        type TEXT NOT NULL,
-        is_expanded BOOLEAN DEFAULT 0,
-        FOREIGN KEY (session_id) REFERENCES sessions (id),
-        FOREIGN KEY (parent_id) REFERENCES files (id)
-      );
-    `);
+    await initSchema(db);
 
     // Seed data based on MOCK mode
-    const folderCount = await db.get('SELECT COUNT(*) as count FROM workspace_folders');
-
     if (isMockMode()) {
-      // MOCK=true: Seed demo workspace folders, sample chats, and session files
-      if (folderCount.count === 0) {
-        await db.exec(`
-          INSERT OR IGNORE INTO workspace_folders (id, name, is_expanded) VALUES 
-            (1, 'Chats', 1), 
-            (2, 'Workspace', 1), 
-            (3, 'drrealhandler', 1);
-        `);
-      }
-
-      // Ensure ompchamber, Workspace, drrealhandler folders exist
-      await db.run("INSERT OR IGNORE INTO workspace_folders (id, name, is_expanded) VALUES (1, 'ompchamber', 1)");
-      await db.run("INSERT OR IGNORE INTO workspace_folders (id, name, is_expanded) VALUES (2, 'Workspace', 1)");
-      await db.run("INSERT OR IGNORE INTO workspace_folders (id, name, is_expanded) VALUES (3, 'drrealhandler', 1)");
-      await db.run("UPDATE workspace_folders SET name = 'ompchamber' WHERE id = 1");
-
-      // Seed specific sessions matching screenshot
-      const existingChats = await db.all("SELECT * FROM sessions WHERE folder_id = 1");
-      const title1 = 'Cek stream subagent di ompweb';
-      const title2 = 'Fitur Diff Panel dan Git Status Files';
-      const title3 = 'Implementasi Saved State UI per Session ID';
-      const title4 = 'Review loading indicator, model & intent title';
-      const title5 = 'Status fitur streer dan queue';
-
-      if (existingChats.length === 0) {
-        await db.run("INSERT INTO sessions (folder_id, title, is_active) VALUES (1, ?, 0)", [title1]);
-        await db.run("INSERT INTO sessions (folder_id, title, is_active) VALUES (1, ?, 0)", [title2]);
-        await db.run("INSERT INTO sessions (folder_id, title, is_active) VALUES (1, ?, 1)", [title3]);
-        await db.run("INSERT INTO sessions (folder_id, title, is_active) VALUES (1, ?, 0)", [title4]);
-        await db.run("INSERT INTO sessions (folder_id, title, is_active) VALUES (1, ?, 0)", [title5]);
-      } else {
-        await db.run("UPDATE sessions SET title = ? WHERE id = 1", [title1]);
-        await db.run("UPDATE sessions SET title = ? WHERE id = 2", [title2]);
-        await db.run("UPDATE sessions SET title = ? WHERE id = 3", [title3]);
-        await db.run("UPDATE sessions SET title = ? WHERE id = 4", [title4]);
-        await db.run("UPDATE sessions SET title = ? WHERE id = 5", [title5]);
-        await db.run("UPDATE sessions SET is_active = 0 WHERE folder_id = 1");
-        await db.run("UPDATE sessions SET is_active = 1 WHERE id = 3");
-      }
-
-      // Pre-seed sample sessions data
-      try {
-        const s1 = getSampleToolsSession();
-        await db.run('INSERT OR REPLACE INTO chat_sessions (session_id, title, messages, updated_at) VALUES (?, ?, ?, CURRENT_TIMESTAMP)', ['1', s1.title, JSON.stringify(s1.messages)]);
-        await db.run('INSERT OR REPLACE INTO chat_sessions (session_id, title, messages, updated_at) VALUES (?, ?, ?, CURRENT_TIMESTAMP)', [SAMPLE_TOOLS_SESSION_ID, s1.title, JSON.stringify(s1.messages)]);
-
-        const s2 = getSampleDialogueSession();
-        await db.run('INSERT OR REPLACE INTO chat_sessions (session_id, title, messages, updated_at) VALUES (?, ?, ?, CURRENT_TIMESTAMP)', ['2', s2.title, JSON.stringify(s2.messages)]);
-        await db.run('INSERT OR REPLACE INTO chat_sessions (session_id, title, messages, updated_at) VALUES (?, ?, ?, CURRENT_TIMESTAMP)', [SAMPLE_DIALOGUE_SESSION_ID, s2.title, JSON.stringify(s2.messages)]);
-
-        const s3 = getSampleDevicesSession();
-        await db.run('INSERT OR REPLACE INTO chat_sessions (session_id, title, messages, updated_at) VALUES (?, ?, ?, CURRENT_TIMESTAMP)', ['3', s3.title, JSON.stringify(s3.messages)]);
-        await db.run('INSERT OR REPLACE INTO chat_sessions (session_id, title, messages, updated_at) VALUES (?, ?, ?, CURRENT_TIMESTAMP)', [SAMPLE_DEVICES_SESSION_ID, s3.title, JSON.stringify(s3.messages)]);
-        const s3Row = await db.get("SELECT id FROM sessions WHERE folder_id = 1 AND title = ?", [title3]);
-        if (s3Row) {
-          await db.run('INSERT OR REPLACE INTO chat_sessions (session_id, title, messages, updated_at) VALUES (?, ?, ?, CURRENT_TIMESTAMP)', [String(s3Row.id), s3.title, JSON.stringify(s3.messages)]);
-        }
-      } catch (e) {
-        console.error('Failed to pre-seed sample sessions:', e);
-      }
-
-      const existingWorkspace = await db.all("SELECT * FROM sessions WHERE folder_id = 2");
-      if (existingWorkspace.length === 0) {
-        const workspaceTitles = [
-          'History Commit 2026-09-05 23:00',
-          'History Commit 2026-09-04 23:00',
-          'History Commit 2026-09-03 23:00',
-          'Error SMSC latency pada jns6.5 smppv2',
-          'Penyebab provider_submit_status=-1 di jns6.5 Smartfren SMPP',
-          'jns6.5 filevalidator error Mask Code di Release',
-          'Union query transaksi 202607 dan 202606'
-        ];
-        for (const t of workspaceTitles) {
-          await db.run("INSERT INTO sessions (folder_id, title, is_active) VALUES (2, ?, 0)", [t]);
-        }
-      }
-
-      const existingDrreal = await db.all("SELECT * FROM sessions WHERE folder_id = 3");
-      if (existingDrreal.length === 0) {
-        const drrealTitles = [
-          'Buat branch feat/add-provider-err-telco-to-dr-smpp',
-          'Update wiki v1.5.0 & testing dari add-configurabel',
-          'Konfigurasi rute DR SMPP via config lookup',
-          'drrealhandler update v1.5.0',
-          'Gitlab wiki clone isi kosong'
-        ];
-        for (const t of drrealTitles) {
-          await db.run("INSERT INTO sessions (folder_id, title, is_active) VALUES (3, ?, 0)", [t]);
-        }
-      }
-
-      // Add random sessions if we don't have enough to demonstrate the UI
-      const sessionCount = await db.get('SELECT COUNT(*) as count FROM sessions');
-      if (sessionCount.count < 15) {
-        const titles = [
-          'Fix header styling issue', 'Implement authentication flow', 'Setup CI/CD pipeline',
-          'Debug database connection', 'Update README.md docs', 'Refactor UI components'
-        ];
-        
-        for (let i = 1; i <= 3; i++) {
-          const numSessions = 3;
-          for (let j = 0; j < numSessions; j++) {
-            const title = titles[Math.floor(Math.random() * titles.length)] + ' #' + Math.floor(Math.random() * 1000);
-            await db.run('INSERT INTO sessions (folder_id, title, is_active) VALUES (?, ?, 0)', [i, title]);
-          }
-        }
-      }
-
-      // Seed random files for all sessions if files table is empty
-      const fileCount = await db.get('SELECT COUNT(*) as count FROM files');
-      if (fileCount.count === 0) {
-        const allSessions = await db.all('SELECT id FROM sessions');
-        for (const session of allSessions) {
-          // Create root folders
-          const res = await db.run('INSERT INTO files (session_id, parent_id, name, type, is_expanded) VALUES (?, NULL, ?, ?, ?)', [session.id, 'src', 'folder', 1]);
-          const srcId = res.lastID;
-          
-          const res2 = await db.run('INSERT INTO files (session_id, parent_id, name, type, is_expanded) VALUES (?, NULL, ?, ?, ?)', [session.id, 'components', 'folder', 0]);
-          const componentsId = res2.lastID;
-
-          // Create files in src
-          await db.run('INSERT INTO files (session_id, parent_id, name, type, is_expanded) VALUES (?, ?, ?, ?, ?)', [session.id, srcId, 'index.tsx', 'file', 0]);
-          await db.run('INSERT INTO files (session_id, parent_id, name, type, is_expanded) VALUES (?, ?, ?, ?, ?)', [session.id, srcId, 'App.tsx', 'file', 0]);
-          await db.run('INSERT INTO files (session_id, parent_id, name, type, is_expanded) VALUES (?, ?, ?, ?, ?)', [session.id, srcId, 'styles.css', 'file', 0]);
-
-          // Create files in components
-          await db.run('INSERT INTO files (session_id, parent_id, name, type, is_expanded) VALUES (?, ?, ?, ?, ?)', [session.id, componentsId, 'Button.tsx', 'file', 0]);
-          await db.run('INSERT INTO files (session_id, parent_id, name, type, is_expanded) VALUES (?, ?, ?, ?, ?)', [session.id, componentsId, 'Header.tsx', 'file', 0]);
-          
-          // Some root files
-          await db.run('INSERT INTO files (session_id, parent_id, name, type, is_expanded) VALUES (?, NULL, ?, ?, ?)', [session.id, 'package.json', 'file', 0]);
-          await db.run('INSERT INTO files (session_id, parent_id, name, type, is_expanded) VALUES (?, NULL, ?, ?, ?)', [session.id, 'README.md', 'file', 0]);
-        }
-      }
+      // MOCK=true: demo workspace folders, sample chats, and session files
+      await seedMockData(db);
     } else {
       // MOCK=false (Real Data Mode): when SYNC_WORKSPACE is enabled (default),
       // auto-create workspace folders from discovered omp projects. User-made
       // folders are never deleted; only additive sync.
-      if (isWorkspaceSyncEnabled()) {
-        try {
-          await syncWorkspaceFoldersWithOmp(db);
-        } catch (err) {
-          // Discovery must never block app startup.
-          console.error('OMP workspace sync failed:', err);
-        }
-      }
+      await syncWorkspaceFoldersFromDiscovery(db);
     }
 
-    const { migrateLegacyProjectSettings } = await import('@/shared/lib/workspace/project-settings-migration');
     await migrateLegacyProjectSettings(db);
 
     dbResolved = db;
@@ -316,42 +89,3 @@ export function getDbSync(): DbClient {
   if (!dbResolved) throw new Error('Database not initialized — call getDb() first');
   return dbResolved;
 }
-
-/**
- * Additive-only folder ↔ omp project sync: creates a workspace folder for
- * every project discovered from ~/.omp/agent (folder name = lowercase
- * basename, bound via project_path). It never modifies or deletes existing
- * user data — no renames, no re-binding of unbound folders — and it skips
- * projects the user has explicitly deleted (tombstoned in
- * `deleted_workspaces`), so a deleted workspace stays deleted.
- */
-async function syncWorkspaceFoldersWithOmp(db: DbClient): Promise<void> {
-  const { orderedOmpProjects, projectDisplayName } = await import('@/shared/lib/omp/session/sidebar');
-
-  const data = await loadOmpSidebarData();
-  const existing = await db.all('SELECT id, name, project_path FROM workspace_folders');
-  const tombstoned = await db.all('SELECT project_path FROM deleted_workspaces');
-
-  // Compare by canonical key, not raw string: tombstones may predate the
-  // directory (unresolved symlink spelling) while project.path is realpath'd.
-  const byPath = new Set(existing.map((r) => r.project_path).filter(Boolean).map(projectPathKey));
-  const usedNames = new Set(existing.map((r) => (r.name as string).toLowerCase()));
-  const deletedPaths = new Set(tombstoned.map((r) => projectPathKey(r.project_path as string)));
-
-  for (const project of orderedOmpProjects(data)) {
-    if (deletedPaths.has(projectPathKey(project.path))) continue;
-    if (byPath.has(projectPathKey(project.path))) continue;
-
-    const name = projectDisplayName(project);
-    let candidate = name;
-    let suffix = 2;
-    while (usedNames.has(candidate)) {
-      candidate = `${name}-${suffix++}`;
-    }
-    usedNames.add(candidate);
-    await db.run(
-      'INSERT INTO workspace_folders (name, is_expanded, project_path) VALUES (?, 1, ?)',
-      [candidate, project.path],
-    );
-  }
-}

package/src/server/lib/btw/frames.test.ts

@@ -0,0 +1,68 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * `finalStatus` decides what the panel shows under an answer and whether the
+ * promote button is offered, so an abnormal stop read as `complete` would both
+ * mislabel a failed turn and offer to branch a conversation from it. The
+ * stop-reason vocabulary belongs to omp (and to `turnStoppedAbnormally`), so
+ * these cases pin the mapping rather than the wire shape.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { finalAnswer, finalStatus, isAnswerableUiMethod } from '@/server/lib/btw/frames';
+
+function assistant(over: Record<string, unknown> = {}): Record<string, unknown> {
+  return { role: 'assistant', content: [{ type: 'text', text: 'answer' }], ...over };
+}
+
+describe('finalStatus', () => {
+  test('a clean turn completes', () => {
+    expect(finalStatus([assistant()])).toBe('complete');
+  });
+
+  test('a user abort is cancelled, not failed', () => {
+    expect(finalStatus([assistant({ stopReason: 'aborted' })])).toBe('cancelled');
+  });
+
+  test('a provider error is a failure, not a completed answer', () => {
+    expect(finalStatus([assistant({ stopReason: 'error' })])).toBe('failed');
+  });
+
+  test('an error carried as flat fields is still a failure', () => {
+    // omp writes abnormal stops as flat `errorStatus`/`errorMessage` on the
+    // message; a bare `stopReason` check would call this one complete.
+    expect(finalStatus([assistant({ errorMessage: 'upstream 500', errorStatus: 500 })])).toBe('failed');
+  });
+
+  test('the newest assistant turn decides', () => {
+    expect(finalStatus([assistant({ stopReason: 'aborted' }), assistant()])).toBe('complete');
+  });
+
+  test('a frame with no assistant message completes', () => {
+    expect(finalStatus([])).toBe('complete');
+    expect(finalStatus(undefined)).toBe('complete');
+  });
+});
+
+describe('finalAnswer', () => {
+  test('joins the assistant text parts of the newest turn', () => {
+    const messages = [assistant({ content: [{ type: 'text', text: 'one ' }, { type: 'text', text: 'two' }] })];
+    expect(finalAnswer(messages, 'streamed')).toBe('one two');
+  });
+
+  test('falls back to the streamed text when the frame carries no answer', () => {
+    expect(finalAnswer([], 'streamed')).toBe('streamed');
+    expect(finalAnswer(undefined, 'streamed')).toBe('streamed');
+  });
+});
+
+describe('isAnswerableUiMethod', () => {
+  test('recognizes the dialogs that park a child, and nothing else', () => {
+    expect(isAnswerableUiMethod('select')).toBe(true);
+    expect(isAnswerableUiMethod('confirm')).toBe(true);
+    expect(isAnswerableUiMethod('notify')).toBe(false);
+    expect(isAnswerableUiMethod(undefined)).toBe(false);
+  });
+});

package/src/server/lib/btw/frames.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Pure readers for the frames a side session emits — kept apart from the
+ * runtime so its lifecycle code stays readable, and so these small pieces of
+ * omp wire knowledge are testable on their own.
+ */
+
+import { isRecord } from '@/shared/lib/util/guards';
+import { turnStoppedAbnormally } from '@/shared/lib/omp/session/turn-error';
+import { ANSWERABLE_UI_METHODS } from '@/server/lib/omp/rpc/constants';
+import type { BtwTurnStatus } from '@/shared/types';
+
+/** A side session has no UI, so it must release every dialog omp parks on. */
+export function isAnswerableUiMethod(method: unknown): boolean {
+  return typeof method === 'string' && ANSWERABLE_UI_METHODS.has(method);
+}
+
+/** A turn stopped by the user is 'cancelled'; a provider error is a failure —
+ *  both are abnormal stops, so the shared predicate decides (it also reads the
+ *  flat `errorStatus`/`errorMessage` fields, which a bare `stopReason` check
+ *  would miss). Anything else that produced a terminal `agent_end` completed. */
+export function finalStatus(messages: unknown): BtwTurnStatus {
+  if (Array.isArray(messages)) {
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+      const message = messages[index];
+      if (isRecord(message) && message.role === 'assistant') {
+        if (!turnStoppedAbnormally(message)) return 'complete';
+        return message.stopReason === 'aborted' ? 'cancelled' : 'failed';
+      }
+    }
+  }
+  return 'complete';
+}
+
+/** The answer as the provider finally reported it; the streamed text is only a
+ *  fallback for a frame that carried no messages. */
+export function finalAnswer(messages: unknown, streamed: string): string {
+  if (!Array.isArray(messages)) return streamed;
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index];
+    if (!isRecord(message) || message.role !== 'assistant') continue;
+    const content = message.content;
+    if (typeof content === 'string') return content;
+    if (!Array.isArray(content)) continue;
+    let text = '';
+    for (const part of content) {
+      if (isRecord(part) && part.type === 'text' && typeof part.text === 'string') text += part.text;
+    }
+    if (text) return text;
+  }
+  return streamed;
+}

package/src/server/lib/btw/prompt.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The side-question prompt. Byte-for-byte the template omp's own `/btw`
+ * sends (`packages/coding-agent/src/prompts/system/btw-user.md`): the side
+ * answer must stay short, must not reach for tools, and must not open a
+ * follow-up dialogue of its own — follow-ups are explicit user turns.
+ *
+ * The parent session's history is NOT part of this text: the side session
+ * resumes the parent's transcript, so the context arrives as real provider
+ * messages and keeps the parent's prompt-cache prefix.
+ */
+
+export function buildBtwPrompt(question: string): string {
+  return [
+    '<btw>',
+    'Ephemeral side question for current interactive session.',
+    'Answer briefly, directly; use conversation context already provided.',
+    'NEVER use tools.',
+    'NEVER ask follow-up questions.',
+    'Question:',
+    question,
+    '</btw>',
+  ].join('\n');
+}

package/src/server/lib/btw/registry.server.ts

@@ -0,0 +1,141 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Process-wide BTW registry: the live topic runtimes, the per-session
+ * subscriber fan-out, and the single place that assembles a session's BTW
+ * state.
+ *
+ * It hangs off `globalThis` for the same reason the omp session registry does:
+ * a `bun --hot` reload re-evaluates modules but keeps `globalThis`, so a
+ * surviving side child stays reachable instead of being orphaned.
+ *
+ * Reading the state is also the repair point: a turn row still marked
+ * `running` whose runtime is gone (the server restarted, or the child was
+ * killed) is settled as `interrupted` instead of blocking every later
+ * question behind a turn that can never finish.
+ */
+
+import { listBtwTopics, settleRunningBtwTurns } from '@/server/lib/btw/store.server';
+import { BtwRuntime, type BtwRuntimeContext } from '@/server/lib/btw/runtime.server';
+import type { BtwFrame, BtwState, BtwTopic } from '@/shared/types';
+
+interface BtwRegistryHost {
+  runtimes: Map<string, BtwRuntime>;
+  listeners: Map<string, Set<(frame: BtwFrame) => void>>;
+}
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __ompBtwRegistry: BtwRegistryHost | undefined;
+}
+
+function registry(): BtwRegistryHost {
+  globalThis.__ompBtwRegistry ??= { runtimes: new Map(), listeners: new Map() };
+  return globalThis.__ompBtwRegistry;
+}
+
+export function getBtwRuntime(topicId: string): BtwRuntime | undefined {
+  return registry().runtimes.get(topicId);
+}
+
+/** Every runtime belonging to a session (at most a handful of topics). */
+function sessionBtwRuntimes(sessionId: string): BtwRuntime[] {
+  const found: BtwRuntime[] = [];
+  for (const runtime of registry().runtimes.values()) {
+    if (runtime.sessionId === sessionId) found.push(runtime);
+  }
+  return found;
+}
+
+/** The runtime currently carrying a turn for this session, if any. */
+export function findRunningBtwRuntime(sessionId: string): BtwRuntime | undefined {
+  return sessionBtwRuntimes(sessionId).find((runtime) => runtime.running);
+}
+
+/** Get (or create) the runtime for a topic, wiring its output to the session's
+ *  subscribers. */
+export function ensureBtwRuntime(context: BtwRuntimeContext): BtwRuntime {
+  const host = registry();
+  const existing = host.runtimes.get(context.topicId);
+  if (existing) return existing;
+  const runtime = new BtwRuntime(context, {
+    publish: (frame) => publishBtw(context.sessionId, frame),
+    stateChanged: () => {
+      void publishBtwState(context.sessionId);
+    },
+  });
+  host.runtimes.set(context.topicId, runtime);
+  return runtime;
+}
+
+export function forgetBtwRuntime(topicId: string): void {
+  registry().runtimes.delete(topicId);
+}
+
+/** Fan out one frame to everyone watching this session's btw stream. */
+export function publishBtw(sessionId: string, frame: BtwFrame): void {
+  const listeners = registry().listeners.get(sessionId);
+  if (!listeners) return;
+  for (const listener of listeners) {
+    try {
+      listener(frame);
+    } catch {
+      // A throwing subscriber (closed socket, encode failure) must not starve
+      // the remaining ones.
+    }
+  }
+}
+
+export function subscribeBtw(sessionId: string, listener: (frame: BtwFrame) => void): () => void {
+  const host = registry();
+  let listeners = host.listeners.get(sessionId);
+  if (!listeners) {
+    listeners = new Set();
+    host.listeners.set(sessionId, listeners);
+  }
+  listeners.add(listener);
+  return () => {
+    const current = host.listeners.get(sessionId);
+    if (!current) return;
+    current.delete(listener);
+    if (current.size === 0) host.listeners.delete(sessionId);
+  };
+}
+
+/** The session's BTW state, with stale `running` rows repaired. */
+export async function btwStateFor(sessionId: string): Promise<BtwState> {
+  const topics = await listBtwTopics(sessionId);
+  // A runtime that is mid-`settle()` has already cleared its turn index but has
+  // not written the row yet; counting it as gone would race its own UPDATE and
+  // rewrite a completed turn as `interrupted`. `busy` covers that window.
+  const liveTopicIds = new Set(
+    sessionBtwRuntimes(sessionId)
+      .filter((runtime) => runtime.running || runtime.busy)
+      .map((runtime) => runtime.topicId),
+  );
+
+  const stale = topics.filter((topic) => topic.turns.some((turn) => turn.status === 'running') && !liveTopicIds.has(topic.id));
+  if (stale.length > 0) {
+    await Promise.all(stale.map((topic) => settleRunningBtwTurns(topic.id, 'interrupted')));
+  }
+
+  const repaired: BtwTopic[] = topics.map((topic) =>
+    liveTopicIds.has(topic.id)
+      ? topic
+      : { ...topic, turns: topic.turns.map((turn) => (turn.status === 'running' ? { ...turn, status: 'interrupted' as const } : turn)) },
+  );
+
+  return {
+    topics: repaired,
+    runningTopicId: repaired.find((topic) => topic.turns.some((turn) => turn.status === 'running'))?.id ?? null,
+  };
+}
+
+/** Republish the whole state to the session's subscribers. */
+export async function publishBtwState(sessionId: string): Promise<void> {
+  const state = await btwStateFor(sessionId);
+  publishBtw(sessionId, { type: 'btw_state', state });
+}