ompchamber 1.0.0 → 1.2.0

package/src/server/lib/btw/session-copy.server.ts

@@ -0,0 +1,213 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Per-topic session workspaces, and promotion of a topic into the chat.
+ *
+ * A topic's side conversation runs in an omp child that resumes a *copy* of
+ * the parent session file. That copy is what makes the side question cheap and
+ * honest: the parent's transcript arrives as real provider messages (no
+ * re-prompting it as text), the parent file is never written by the side
+ * child, and the copy itself becomes the topic's durable history — a follow-up
+ * after the child was reclaimed resumes it and still sees every earlier turn.
+ *
+ * Promotion turns the copy into a session of the chamber's own: the file is
+ * rewritten with a fresh session id and a title taken from the question, then
+ * placed beside the parent session — the same end state omp's `/btw` reaches
+ * with its branch action, where the side answer becomes the tip of a new
+ * conversation that carries the parent's history.
+ *
+ * Session-file layout details that matter here (all verified against omp
+ * 18.2.6 files):
+ *  - Line 1 is the title slot: `{"type":"title","v":1,"title":…,"source":…,
+ *    "updatedAt":…,"pad":"…"}` padded so the serialized line is exactly
+ *    `SESSION_TITLE_SLOT_BYTES` bytes — omp rewrites it in place, and the
+ *    serializer in `omp/session/title-slot.ts` owns both the truncation and the
+ *    padding arithmetic.
+ *  - Line 2 is the session header (`type:"session"`), carrying `id`, `cwd`,
+ *    and for a branch `parentSession` — the file it branched from.
+ *  - File names are `<ISO with [:. ] → ->_<session id>.jsonl`.
+ */
+
+import fs from 'fs';
+import * as path from 'path';
+import { getDatabasePath } from '@/server/db.server';
+import { clearSessionFileCaches } from '@/server/lib/omp/session/files';
+import { serializeTitleSlot } from '@/server/lib/omp/session/title-slot';
+import { isRecord } from '@/shared/lib/util/guards';
+
+/** Root holding every topic workspace, beside the chamber database. */
+export async function getBtwRoot(): Promise<string> {
+  const root = path.join(path.dirname(await getDatabasePath()), 'btw');
+  await fs.promises.mkdir(root, { recursive: true });
+  return root;
+}
+
+function parseJsonObject(line: string): Record<string, unknown> | null {
+  try {
+    const value: unknown = JSON.parse(line);
+    return value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The file's lines, minus a torn tail. A snapshot taken while the parent is
+ * mid-append can end in a partial line; keeping it would make the side child
+ * fail to load the transcript.
+ */
+function completeLines(text: string): string[] {
+  const lines = text.split('\n');
+  if (lines[lines.length - 1] === '') lines.pop();
+  const last = lines[lines.length - 1];
+  if (last !== undefined && parseJsonObject(last) === null) lines.pop();
+  return lines;
+}
+
+/** The transcript's leaf: the id of its last entry. */
+export function lastEntryId(lines: string[]): string | null {
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const record = parseJsonObject(lines[index]);
+    if (record && typeof record.id === 'string') return record.id;
+  }
+  return null;
+}
+
+/** Read a transcript's leaf id straight from disk. */
+export async function readTranscriptLeaf(sessionFile: string): Promise<string | null> {
+  try {
+    return lastEntryId(completeLines(await Bun.file(sessionFile).text()));
+  } catch {
+    return null;
+  }
+}
+
+/** The title slot line, padded to the fixed slot omp rewrites in place, with
+ *  the trailing newline removed (the writer here joins lines itself).
+ *
+ *  Delegates to the repo's slot serializer rather than re-deriving the width:
+ *  that one truncates the title by code point, so a question written in CJK
+ *  (up to 3 UTF-8 bytes each) still fits — clipping by character count alone
+ *  would overflow the slot and fail promotion outright. */
+export function buildTitleLine(title: string, source: string, updatedAt: string): string {
+  const line = serializeTitleSlot({ title, source: source === 'auto' ? 'auto' : 'user', updatedAt });
+  return line.endsWith('\n') ? line.slice(0, -1) : line;
+}
+
+export interface BtwWorkspace {
+  dir: string;
+  sessionFile: string;
+  /** Parent transcript leaf at snapshot time — the promotion guard's baseline. */
+  leafId: string | null;
+}
+
+/** Where a topic's transcript lives. Derived, never stored: a topic that lost
+ *  its runtime still finds the same file, which is what makes a follow-up
+ *  continue the side conversation instead of starting it over. */
+export async function resolveBtwWorkspacePaths(sessionId: string, topicId: string): Promise<Omit<BtwWorkspace, 'leafId'>> {
+  const dir = path.join(await getBtwRoot(), sessionId, topicId);
+  return { dir, sessionFile: path.join(dir, 'session.jsonl') };
+}
+
+/** Snapshot the parent transcript into a topic's private session file. */
+export async function createBtwWorkspace(input: {
+  parentSessionId: string;
+  topicId: string;
+  parentSessionFile: string;
+}): Promise<BtwWorkspace> {
+  const dir = path.join(await getBtwRoot(), input.parentSessionId, input.topicId);
+  await fs.promises.mkdir(dir, { recursive: true });
+  const lines = completeLines(await Bun.file(input.parentSessionFile).text());
+  const sessionFile = path.join(dir, 'session.jsonl');
+  await Bun.write(sessionFile, lines.length > 0 ? `${lines.join('\n')}\n` : '');
+  return { dir, sessionFile, leafId: lastEntryId(lines) };
+}
+
+/**
+ * The visible question behind a side-question prompt.
+ *
+ * The side session's own transcript keeps the full `<btw>` template (that is
+ * its record, and the shape the side child was resumed with). Promoting lifts
+ * the pair into a chat, where the boilerplate would be noise the user never
+ * typed — omp's own branch action appends the plain question, and so does this.
+ */
+function unwrapBtwQuestion(text: string): string {
+  if (!text.startsWith('<btw>')) return text;
+  const marker = '\nQuestion:\n';
+  const start = text.indexOf(marker);
+  if (start < 0) return text;
+  const end = text.lastIndexOf('</btw>');
+  const question = text.slice(start + marker.length, end > start ? end : undefined).trim();
+  return question || text;
+}
+
+function unwrapBtwPrompts(record: Record<string, unknown>): Record<string, unknown> {
+  const message = record.message;
+  if (!isRecord(message) || message.role !== 'user' || !Array.isArray(message.content)) return record;
+  const content = message.content.map((part) =>
+    isRecord(part) && part.type === 'text' && typeof part.text === 'string'
+      ? { ...part, text: unwrapBtwQuestion(part.text) }
+      : part,
+  );
+  return { ...record, message: { ...message, content } };
+}
+
+/**
+ * Promote a topic: write its transcript next to the parent session under a
+ * fresh session id, so the chamber (and omp) treat it as a branch of the
+ * parent conversation whose tip is the side answer. Returns the new id.
+ */
+export async function promoteBtwTopic(input: {
+  parentSessionFile: string;
+  topicSessionFile: string;
+  title: string;
+}): Promise<string> {
+  const lines = completeLines(await Bun.file(input.topicSessionFile).text());
+  const newId = crypto.randomUUID();
+  const timestamp = new Date().toISOString();
+
+  let titleDropped = false;
+  let headerWritten = false;
+  const body: string[] = [];
+  for (const line of lines) {
+    const record = parseJsonObject(line);
+    if (record?.type === 'title' && !titleDropped) {
+      // The slot moves to line 1 below; a later title record is left alone.
+      titleDropped = true;
+      continue;
+    }
+    if (record?.type === 'session' && !headerWritten) {
+      headerWritten = true;
+      body.push(
+        JSON.stringify({
+          ...record,
+          id: newId,
+          timestamp,
+          title: input.title,
+          titleSource: 'user',
+          parentSession: input.parentSessionFile,
+        }),
+      );
+      continue;
+    }
+    body.push(record?.type === 'message' ? JSON.stringify(unwrapBtwPrompts(record)) : line);
+  }
+  if (!headerWritten) throw new Error('BTW topic transcript has no session header');
+
+  const fileName = `${timestamp.replace(/[:.]/g, '-')}_${newId}.jsonl`;
+  const target = path.join(path.dirname(input.parentSessionFile), fileName);
+  // An existing file at this name would mean the id collided; never truncate.
+  if (await Bun.file(target).exists()) throw new Error(`Promoted session file already exists: ${fileName}`);
+  await Bun.write(target, `${[buildTitleLine(input.title, 'user', timestamp), ...body].join('\n')}\n`);
+  // The sidebar list and the id→path scan are mtime-keyed caches.
+  clearSessionFileCaches();
+  return newId;
+}
+
+/** Drop a topic's workspace (its transcript lives in the database after this). */
+export async function removeBtwWorkspace(dir: string): Promise<void> {
+  await fs.promises.rm(dir, { recursive: true, force: true });
+}

package/src/server/lib/btw/session-copy.test.ts

@@ -0,0 +1,166 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The topic transcript and its promotion are file surgery on a format omp
+ * owns, and every failure mode here is silent: a title slot that is not the
+ * fixed width stops omp rewriting it in place, a stale session id makes two
+ * sessions claim one identity, and a torn tail line makes the side child fail
+ * to load the transcript at all. These cases pin those invariants.
+ */
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { buildTitleLine, createBtwWorkspace, getBtwRoot, promoteBtwTopic, readTranscriptLeaf } from '@/server/lib/btw/session-copy.server';
+
+const timestamp = '2026-09-23T08:41:10.683Z';
+const createdDirs: string[] = [];
+const createdSessions: string[] = [];
+
+function tempDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'btw-test-'));
+  createdDirs.push(dir);
+  return dir;
+}
+
+function sessionLine(id: string, cwd = '/tmp'): string {
+  return JSON.stringify({ type: 'session', version: 3, id, timestamp, cwd });
+}
+
+function userLine(id: string, parentId: string | null, text: string): string {
+  return JSON.stringify({ type: 'message', id, parentId, timestamp, message: { role: 'user', content: [{ type: 'text', text }] } });
+}
+
+function assistantLine(id: string, parentId: string | null, text: string): string {
+  return JSON.stringify({ type: 'message', id, parentId, timestamp, message: { role: 'assistant', content: [{ type: 'text', text }] } });
+}
+
+afterEach(() => {
+  for (const dir of createdDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+  for (const dir of createdSessions.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+describe('buildTitleLine', () => {
+  test('pads the title record to the fixed slot omp rewrites in place', () => {
+    const line = buildTitleLine('Which codeword did we agree on?', 'user', timestamp);
+    expect(Buffer.byteLength(line, 'utf8')).toBe(255);
+    const record = JSON.parse(line);
+    expect(record.type).toBe('title');
+    expect(record.title).toBe('Which codeword did we agree on?');
+    expect(record.source).toBe('user');
+  });
+
+  test('fits a title the model wrote in multi-byte characters', () => {
+    // A 60-character topic label is 180 UTF-8 bytes in CJK: the slot holds
+    // ~158, so the title is truncated rather than thrown — otherwise promoting
+    // a perfectly ordinary question fails the whole request.
+    const title = 'この質問は日本語で書かれています。プロモートできるか確認します。ここから先は切り詰められます';
+    const line = buildTitleLine(title, 'user', timestamp);
+    expect(Buffer.byteLength(line, 'utf8')).toBe(255);
+    const record = JSON.parse(line);
+    expect(record.title.length).toBeGreaterThan(0);
+    expect(title.startsWith(record.title)).toBe(true);
+  });
+});
+
+describe('createBtwWorkspace', () => {
+  test('snapshots the parent transcript and reports its leaf', async () => {
+    const sessionId = crypto.randomUUID();
+    const parentDir = tempDir();
+    const parentFile = join(parentDir, 'parent.jsonl');
+    createdSessions.push(join(await getBtwRoot(), sessionId));
+    writeFileSync(
+      parentFile,
+      [buildTitleLine('parent', 'auto', timestamp), sessionLine(sessionId), userLine('a1', null, 'hello'), assistantLine('a2', 'a1', 'hi')].join('\n') + '\n',
+    );
+
+    const workspace = await createBtwWorkspace({ parentSessionId: sessionId, topicId: 'topic-1', parentSessionFile: parentFile });
+
+    expect(workspace.leafId).toBe('a2');
+    expect(existsSync(workspace.sessionFile)).toBe(true);
+    const copied = readFileSync(workspace.sessionFile, 'utf8');
+    expect(copied).toBe(readFileSync(parentFile, 'utf8'));
+  });
+
+  test('drops a torn tail line from a parent caught mid-append', async () => {
+    const sessionId = crypto.randomUUID();
+    const parentDir = tempDir();
+    const parentFile = join(parentDir, 'parent.jsonl');
+    createdSessions.push(join(await getBtwRoot(), sessionId));
+    const torn = '{"type":"message","id":"torn';
+    writeFileSync(
+      parentFile,
+      [buildTitleLine('parent', 'auto', timestamp), sessionLine(sessionId), userLine('a1', null, 'hello')].join('\n') + '\n' + torn,
+    );
+
+    const workspace = await createBtwWorkspace({ parentSessionId: sessionId, topicId: 'topic-2', parentSessionFile: parentFile });
+
+    const copied = readFileSync(workspace.sessionFile, 'utf8');
+    expect(copied.endsWith('\n')).toBe(true);
+    expect(copied).not.toContain('torn');
+    expect(workspace.leafId).toBe('a1');
+  });
+});
+
+describe('promoteBtwTopic', () => {
+  function topicFile(dir: string): { path: string; parentFile: string } {
+    const parentFile = join(dir, 'parent.jsonl');
+    const path = join(dir, 'topic.jsonl');
+    writeFileSync(parentFile, [buildTitleLine('parent', 'auto', timestamp), sessionLine('parent-session').replace('parent-session', 'aaaa1111')].join('\n') + '\n');
+    writeFileSync(
+      path,
+      [
+        buildTitleLine('side question', 'user', timestamp),
+        sessionLine('parent-id'),
+        userLine('u1', null, 'remember ORANGE-TAPIR'),
+        assistantLine('a1', 'u1', 'ok'),
+        userLine('u2', 'a1', '<btw>\nEphemeral side question for current interactive session.\nAnswer briefly, directly; use conversation context already provided.\nNEVER use tools.\nNEVER ask follow-up questions.\nQuestion:\nWhat is the codeword?\n</btw>'),
+        assistantLine('a2', 'u2', 'ORANGE-TAPIR'),
+      ].join('\n') + '\n',
+    );
+    return { path, parentFile };
+  }
+
+  test('writes a branch session beside the parent under a fresh identity', async () => {
+    const dir = tempDir();
+    const { path, parentFile } = topicFile(dir);
+
+    const created = await promoteBtwTopic({ parentSessionFile: parentFile, topicSessionFile: path, title: 'What is the codeword?' });
+
+    const promotedFiles = readdirSync(dir).filter((name) => name.endsWith(`_${created}.jsonl`));
+    expect(promotedFiles.length).toBe(1);
+    // omp names session files `<ISO with [:. ] → ->_<id>.jsonl`.
+    expect(promotedFiles[0]).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z_[0-9a-f-]{36}\.jsonl$/);
+    const promoted = join(dir, promotedFiles[0]);
+    const lines = readFileSync(promoted, 'utf8').trimEnd().split('\n');
+
+    expect(Buffer.byteLength(lines[0], 'utf8')).toBe(255);
+    expect(JSON.parse(lines[0]).title).toBe('What is the codeword?');
+
+    const header = JSON.parse(lines[1]);
+    expect(header.id).toBe(created);
+    expect(header.id).not.toBe('parent-id');
+    expect(header.parentSession).toBe(parentFile);
+    expect(header.title).toBe('What is the codeword?');
+    expect(header.cwd).toBe('/tmp');
+
+    // Exactly one title record, at the top: a second one would confuse the slot.
+    expect(lines.filter((line) => line.includes('"type":"title"')).length).toBe(1);
+    // The promoted chat shows the question the user asked, not the template.
+    expect(readFileSync(promoted, 'utf8')).toContain('"text":"What is the codeword?"');
+    expect(readFileSync(promoted, 'utf8')).not.toContain('NEVER use tools');
+    expect(await readTranscriptLeaf(promoted)).toBe('a2');
+  });
+
+  test('refuses a transcript with no session header instead of guessing one', async () => {
+    const dir = tempDir();
+    const topicPath = join(dir, 'headerless.jsonl');
+    writeFileSync(topicPath, userLine('u1', null, 'no header here') + '\n');
+
+    expect(
+      promoteBtwTopic({ parentSessionFile: join(dir, 'parent.jsonl'), topicSessionFile: topicPath, title: 'x' }),
+    ).rejects.toThrow('no session header');
+  });
+});

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

@@ -0,0 +1,240 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * SQLite-backed BTW store (`btw_topics` / `btw_turns`).
+ *
+ * A side question is a topic: an independent first question plus explicit
+ * follow-ups, scoped to the parent session. Rows mirror what the panel shows,
+ * so history survives a reload, a server restart, and the death of the side
+ * session's omp child — a follow-up resumes the topic's own session file,
+ * which already carries the parent's context and every turn before it.
+ *
+ * `leaf_id` is the parent session's transcript leaf when the topic started.
+ * Promotion refuses when the parent has moved on, exactly like omp's own
+ * `/btw` branch guard ("session changed since /btw started").
+ */
+
+import { getDb } from '@/server/db.server';
+import type { BtwModel, BtwTopic, BtwTurn, BtwTurnStatus } from '@/shared/types';
+
+interface TopicRow {
+  id: string;
+  session_id: string;
+  title: string;
+  provider: string | null;
+  model_id: string | null;
+  model_name: string | null;
+  leaf_id: string | null;
+  promoted_session_id: string | null;
+  created_at: number;
+  updated_at: number;
+}
+
+interface TurnRow {
+  topic_id: string;
+  turn_index: number;
+  question: string;
+  answer: string;
+  status: string;
+  created_at: number;
+  updated_at: number;
+}
+
+const TURN_STATUSES: Record<string, true> = {
+  running: true,
+  complete: true,
+  cancelled: true,
+  failed: true,
+  interrupted: true,
+};
+
+export function isBtwTurnStatus(value: unknown): value is BtwTurnStatus {
+  return typeof value === 'string' && value in TURN_STATUSES;
+}
+
+function rowToTopic(row: TopicRow): BtwTopic {
+  const model: BtwModel | undefined =
+    row.provider && row.model_id
+      ? { provider: row.provider, id: row.model_id, ...(row.model_name ? { name: row.model_name } : {}) }
+      : undefined;
+  return {
+    id: row.id,
+    sessionId: row.session_id,
+    title: row.title,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    ...(model ? { model } : {}),
+    ...(row.promoted_session_id ? { promotedSessionId: row.promoted_session_id } : {}),
+    turns: [],
+  };
+}
+
+function rowToTurn(row: TurnRow): BtwTurn {
+  return {
+    index: row.turn_index,
+    question: row.question,
+    answer: row.answer,
+    status: isBtwTurnStatus(row.status) ? row.status : 'interrupted',
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+/** Every topic of a session, oldest first, each with its turns in order. */
+export async function listBtwTopics(sessionId: string): Promise<BtwTopic[]> {
+  const db = await getDb();
+  const topics = ((await db.all(
+    'SELECT * FROM btw_topics WHERE session_id = ? ORDER BY created_at ASC, id ASC',
+    [sessionId],
+  )) as TopicRow[]).map(rowToTopic);
+  if (topics.length === 0) return topics;
+
+  const placeholders = topics.map(() => '?').join(', ');
+  const turns = (await db.all(
+    `SELECT * FROM btw_turns WHERE topic_id IN (${placeholders}) ORDER BY topic_id ASC, turn_index ASC`,
+    topics.map((topic) => topic.id),
+  )) as TurnRow[];
+
+  const byTopic = new Map<string, BtwTurn[]>(topics.map((topic) => [topic.id, []]));
+  for (const row of turns) byTopic.get(row.topic_id)?.push(rowToTurn(row));
+  return topics.map((topic) => ({ ...topic, turns: byTopic.get(topic.id) ?? [] }));
+}
+
+/** One topic with its turns, or undefined when the id is unknown. */
+export async function getBtwTopic(topicId: string): Promise<BtwTopic | undefined> {
+  const db = await getDb();
+  const row = (await db.get('SELECT * FROM btw_topics WHERE id = ?', [topicId])) as TopicRow | undefined;
+  if (!row) return undefined;
+  const turns = (await db.all(
+    'SELECT * FROM btw_turns WHERE topic_id = ? ORDER BY turn_index ASC',
+    [topicId],
+  )) as TurnRow[];
+  return { ...rowToTopic(row), turns: turns.map(rowToTurn) };
+}
+
+export interface NewBtwTopicInput {
+  sessionId: string;
+  title: string;
+  model?: BtwModel;
+  /** Parent transcript leaf when the topic was created (promotion guard). */
+  leafId?: string | null;
+}
+
+export async function createBtwTopic(input: NewBtwTopicInput): Promise<BtwTopic> {
+  const db = await getDb();
+  const now = Date.now();
+  const row: TopicRow = {
+    id: crypto.randomUUID(),
+    session_id: input.sessionId,
+    title: input.title,
+    provider: input.model?.provider ?? null,
+    model_id: input.model?.id ?? null,
+    model_name: input.model?.name ?? null,
+    leaf_id: input.leafId ?? null,
+    promoted_session_id: null,
+    created_at: now,
+    updated_at: now,
+  };
+  await db.run(
+    `INSERT INTO btw_topics
+       (id, session_id, title, provider, model_id, model_name, leaf_id, promoted_session_id, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, NULL, ?, ?)`,
+    [row.id, row.session_id, row.title, row.provider, row.model_id, row.model_name, row.leaf_id, now, now],
+  );
+  return rowToTopic(row);
+}
+
+/** Append a question to a topic; returns the new turn's index. */
+export async function appendBtwTurn(topicId: string, question: string): Promise<number> {
+  const db = await getDb();
+  const now = Date.now();
+  const next = (await db.get(
+    'SELECT COALESCE(MAX(turn_index), -1) + 1 AS next FROM btw_turns WHERE topic_id = ?',
+    [topicId],
+  )) as { next: number } | undefined;
+  const turnIndex = next?.next ?? 0;
+  await db.run(
+    `INSERT INTO btw_turns (topic_id, turn_index, question, answer, status, created_at, updated_at)
+     VALUES (?, ?, ?, '', 'running', ?, ?)`,
+    [topicId, turnIndex, question, now, now],
+  );
+  await db.run('UPDATE btw_topics SET updated_at = ? WHERE id = ?', [now, topicId]);
+  return turnIndex;
+}
+
+/** Patch one turn's answer and/or status. */
+export async function updateBtwTurn(
+  topicId: string,
+  turnIndex: number,
+  patch: { answer?: string; status?: BtwTurnStatus },
+): Promise<void> {
+  const db = await getDb();
+  const sets: string[] = ['updated_at = ?'];
+  const values: (string | number)[] = [Date.now()];
+  if (typeof patch.answer === 'string') {
+    sets.push('answer = ?');
+    values.push(patch.answer);
+  }
+  if (patch.status !== undefined) {
+    sets.push('status = ?');
+    values.push(patch.status);
+  }
+  await db.run(`UPDATE btw_turns SET ${sets.join(', ')} WHERE topic_id = ? AND turn_index = ?`, [
+    ...values,
+    topicId,
+    turnIndex,
+  ]);
+}
+
+/** Settle every still-running turn of a topic — the side session died or was
+ *  cancelled, so nothing will ever complete them. */
+export async function settleRunningBtwTurns(topicId: string, status: BtwTurnStatus): Promise<void> {
+  const db = await getDb();
+  await db.run(
+    "UPDATE btw_turns SET status = ?, updated_at = ? WHERE topic_id = ? AND status = 'running'",
+    [status, Date.now(), topicId],
+  );
+}
+
+/** Record the parent-transcript leaf a topic was snapshotted at. */
+export async function setBtwTopicLeaf(topicId: string, leafId: string): Promise<void> {
+  const db = await getDb();
+  await db.run('UPDATE btw_topics SET leaf_id = ? WHERE id = ?', [leafId, topicId]);
+}
+
+/** The parent-transcript leaf this topic was snapshotted at, when known. */
+export async function readBtwTopicLeaf(topicId: string): Promise<string | null> {
+  const db = await getDb();
+  const row = (await db.get('SELECT leaf_id FROM btw_topics WHERE id = ?', [topicId])) as { leaf_id: string | null } | undefined;
+  return row?.leaf_id ?? null;
+}
+
+export async function setBtwTopicModel(topicId: string, model: BtwModel): Promise<void> {
+  const db = await getDb();
+  await db.run('UPDATE btw_topics SET provider = ?, model_id = ?, model_name = ?, updated_at = ? WHERE id = ?', [
+    model.provider,
+    model.id,
+    model.name ?? null,
+    Date.now(),
+    topicId,
+  ]);
+}
+
+export async function setBtwTopicPromoted(topicId: string, promotedSessionId: string): Promise<void> {
+  const db = await getDb();
+  await db.run('UPDATE btw_topics SET promoted_session_id = ?, updated_at = ? WHERE id = ?', [
+    promotedSessionId,
+    Date.now(),
+    topicId,
+  ]);
+}
+
+export async function deleteBtwTopic(topicId: string): Promise<boolean> {
+  const db = await getDb();
+  const result = await db.run('DELETE FROM btw_topics WHERE id = ?', [topicId]);
+  await db.run('DELETE FROM btw_turns WHERE topic_id = ?', [topicId]);
+  return result.changes > 0;
+}