@vellumai/assistant 0.8.5 → 0.8.7-dev.202606052118.34cd356

package/src/memory/conversation-queries.ts

@@ -11,6 +11,7 @@ import type { ConversationRow } from "./conversation-crud.js";
 import { parseConversation } from "./conversation-crud.js";
 import { ensureDisplayOrderMigration } from "./conversation-display-order-migration.js";
 import { ensureGroupMigration } from "./conversation-group-migration.js";
+import type { ConversationType } from "./conversation-types.js";
 import { getDb } from "./db-connection.js";
 import { rawAll } from "./raw-query.js";
 import { conversations, messages } from "./schema.js";
@@ -48,30 +49,78 @@ export function buildFtsMatchQuery(
   return unique.map((token) => `"${token.replace(/"/g, '""')}"`).join(" ");
 }
 
+/**
+ * How {@link listConversations} (and friends) treats archived rows.
+ *
+ * - `"active"` — exclude rows with a non-null `archivedAt`. The default
+ *   for sidebar lists, restore, CLI pickers, and anything user-facing.
+ * - `"archived"` — return ONLY archived rows. Powers the Archive page
+ *   so it does not have to pull the entire conversation history and
+ *   filter client-side.
+ * - `"all"` — include both. Reserved for migrations and back-compat
+ *   call sites that genuinely want everything in one query.
+ */
+export type ArchiveStatusFilter = "active" | "archived" | "all";
+
+function archiveStatusClause(status: ArchiveStatusFilter) {
+  switch (status) {
+    case "active":
+      return sql`${conversations.archivedAt} IS NULL`;
+    case "archived":
+      return sql`${conversations.archivedAt} IS NOT NULL`;
+    case "all":
+      return null;
+  }
+}
+
+/**
+ * SQL predicate selecting which bucket {@link listConversations} and
+ * {@link countConversations} return, keyed by the canonical
+ * {@link ConversationType}:
+ *
+ * - `"standard"` — the primary sidebar list: standard conversations only,
+ *   excluding background, scheduled, and private rows. `"private"` is excluded
+ *   defensively because in-place snapshot restore swaps the SQLite file without
+ *   running migrations in-process, so legacy private rows can briefly exist
+ *   before migration cleanup deletes them.
+ * - `"background"` — the background **umbrella**: background *and* scheduled
+ *   rows together. The back-compat bucket for the single
+ *   `conversationType=background` fetch that older clients (e.g. the macOS app,
+ *   which ships out of lockstep with the daemon) rely on to populate both the
+ *   Background and Scheduled sidebar sections from one request.
+ * - `"scheduled"` — scheduled rows only, so the Scheduled section can load
+ *   independently of the broader background backlog without over-fetching it.
+ *
+ * `group_id` is matched alongside `conversationType` so conversations routed to
+ * `system:background` / `system:scheduled` (heartbeat, reminders, schedule-job
+ * runs) but created with conversationType `"standard"` still land in the
+ * correct bucket. Subagent runs are excluded from the background/scheduled
+ * buckets so the sidebar never surfaces them.
+ */
+function conversationTypeClause(type: ConversationType) {
+  const notSubagent = sql`(${conversations.source} IS NULL OR ${conversations.source} != 'subagent')`;
+  switch (type) {
+    case "standard":
+      return sql`${conversations.conversationType} NOT IN ('background', 'scheduled', 'private') AND COALESCE(group_id, 'system:all') NOT IN ('system:background', 'system:scheduled')`;
+    case "background":
+      return sql`(${conversations.conversationType} IN ('background', 'scheduled') OR group_id IN ('system:background', 'system:scheduled')) AND ${notSubagent}`;
+    case "scheduled":
+      return sql`(${conversations.conversationType} = 'scheduled' OR group_id = 'system:scheduled') AND ${notSubagent}`;
+  }
+}
+
 export function listConversations(
   limit?: number,
-  backgroundOnly = false,
+  conversationType: ConversationType = "standard",
   offset = 0,
-  includeArchived = true,
+  archiveStatus: ArchiveStatusFilter = "active",
 ): ConversationRow[] {
   ensureDisplayOrderMigration();
   ensureGroupMigration();
   const db = getDb();
-  // 'private' is excluded defensively: in-place snapshot restore swaps the
-  // SQLite file without running migrations in-process, so legacy private rows
-  // can briefly exist before migration cleanup. Hide them from foreground
-  // lists until the next migration pass deletes them.
-  //
-  // group_id is checked alongside conversationType so that conversations
-  // routed to system:background (e.g. heartbeat) via conversationMetadata
-  // but created with conversationType "standard" (vellum channel strategy)
-  // appear in the correct bucket.
-  const typeCond = backgroundOnly
-    ? sql`(${conversations.conversationType} IN ('background', 'scheduled') OR group_id IN ('system:background', 'system:scheduled')) AND (${conversations.source} IS NULL OR ${conversations.source} != 'subagent')`
-    : sql`${conversations.conversationType} NOT IN ('background', 'scheduled', 'private') AND COALESCE(group_id, 'system:all') NOT IN ('system:background', 'system:scheduled')`;
-  const where = includeArchived
-    ? typeCond
-    : sql`${typeCond} AND ${conversations.archivedAt} IS NULL`;
+  const typeCond = conversationTypeClause(conversationType);
+  const archiveCond = archiveStatusClause(archiveStatus);
+  const where = archiveCond ? sql`${typeCond} AND ${archiveCond}` : typeCond;
   const query = db
     .select()
     .from(conversations)
@@ -172,10 +221,13 @@ export function getMessageRoleStatsByConversation(
   );
 }
 
-export function listPinnedConversations(): ConversationRow[] {
+export function listPinnedConversations(
+  archiveStatus: ArchiveStatusFilter = "active",
+): ConversationRow[] {
   ensureDisplayOrderMigration();
   ensureGroupMigration();
   const db = getDb();
+  const archiveCond = archiveStatusClause(archiveStatus);
   const query = db
     .select()
     .from(conversations)
@@ -183,6 +235,7 @@ export function listPinnedConversations(): ConversationRow[] {
       and(
         sql`${conversations.conversationType} NOT IN ('background', 'scheduled', 'private')`,
         sql`is_pinned = 1`,
+        ...(archiveCond ? [archiveCond] : []),
       ),
     )
     .orderBy(
@@ -247,12 +300,15 @@ export function listConversationsByTitlePrefix(
   }));
 }
 
-export function countConversations(backgroundOnly = false): number {
+export function countConversations(
+  conversationType: ConversationType = "standard",
+  archiveStatus: ArchiveStatusFilter = "active",
+): number {
   ensureGroupMigration();
   const db = getDb();
-  const where = backgroundOnly
-    ? sql`(${conversations.conversationType} IN ('background', 'scheduled') OR group_id IN ('system:background', 'system:scheduled')) AND (${conversations.source} IS NULL OR ${conversations.source} != 'subagent')`
-    : sql`${conversations.conversationType} NOT IN ('background', 'scheduled', 'private') AND COALESCE(group_id, 'system:all') NOT IN ('system:background', 'system:scheduled')`;
+  const typeCond = conversationTypeClause(conversationType);
+  const archiveCond = archiveStatusClause(archiveStatus);
+  const where = archiveCond ? sql`${typeCond} AND ${archiveCond}` : typeCond;
   const [{ total }] = db
     .select({ total: count() })
     .from(conversations)

package/src/memory/conversation-starter-checkpoints.ts

@@ -15,6 +15,7 @@ import { memoryCheckpoints } from "./schema.js";
 export const CK_ITEM_COUNT = "conversation_starters:item_count_at_last_gen";
 export const CK_BATCH = "conversation_starters:generation_batch";
 export const CK_LAST_GEN_AT = "conversation_starters:last_gen_at";
+export const CK_LAST_ATTEMPT_AT = "conversation_starters:last_attempt_at";
 
 export function checkpointKey(base: string, scopeId: string): string {
   return `${base}:${scopeId}`;

package/src/memory/conversation-title-service.ts

@@ -10,7 +10,9 @@
 import { getConfiguredProvider } from "../providers/provider-send-message.js";
 import type { Provider } from "../providers/types.js";
 import { runBtwSidechain } from "../runtime/btw-sidechain.js";
+import { publishConversationTitleChanged } from "../runtime/sync/resource-sync-events.js";
 import { getLogger } from "../util/logger.js";
+import { Mutex } from "../util/mutex.js";
 import {
   getConversation,
   getMessages,
@@ -93,8 +95,6 @@ export interface GenerateTitleParams {
   userMessage?: string;
   /** Assistant response text (first turn). */
   assistantResponse?: string;
-  /** Callback to emit title update events. */
-  onTitleUpdated?: (title: string) => void;
   /** Abort signal. */
   signal?: AbortSignal;
 }
@@ -106,14 +106,8 @@ export interface GenerateTitleParams {
 export async function generateAndPersistConversationTitle(
   params: GenerateTitleParams,
 ): Promise<{ title: string; updated: boolean }> {
-  const {
-    conversationId,
-    context,
-    userMessage,
-    assistantResponse,
-    onTitleUpdated,
-    signal,
-  } = params;
+  const { conversationId, context, userMessage, assistantResponse, signal } =
+    params;
 
   // Check current title is replaceable
   const conversation = getConversation(conversationId);
@@ -127,7 +121,7 @@ export async function generateAndPersistConversationTitle(
     // No provider available — fall back to context-derived title or untitled
     const fallback = deriveFallbackTitle(context) ?? UNTITLED_FALLBACK;
     updateConversationTitle(conversationId, fallback, 1);
-    onTitleUpdated?.(fallback);
+    publishConversationTitleChanged(conversationId, fallback);
     return { title: fallback, updated: true };
   }
 
@@ -139,7 +133,7 @@ export async function generateAndPersistConversationTitle(
     tools: [],
     callSite: "conversationTitle",
     signal,
-    timeoutMs: 10_000,
+    timeoutMs: 15_000,
   });
   const title = normalizeTitle(result.text);
   if (title) {
@@ -150,7 +144,7 @@ export async function generateAndPersistConversationTitle(
     }
 
     updateConversationTitle(conversationId, title, 1);
-    onTitleUpdated?.(title);
+    publishConversationTitleChanged(conversationId, title);
     log.info({ conversationId, title }, "Auto-generated conversation title");
     return { title, updated: true };
   }
@@ -167,36 +161,61 @@ export async function generateAndPersistConversationTitle(
 
   const fallback = deriveFallbackTitle(context) ?? UNTITLED_FALLBACK;
   updateConversationTitle(conversationId, fallback, 1);
-  onTitleUpdated?.(fallback);
+  publishConversationTitleChanged(conversationId, fallback);
   return { title: fallback, updated: true };
 }
 
+// ── Serial title-generation queue ────────────────────────────────────
+
+/**
+ * Each title generation makes an LLM call. Without serialization, burst
+ * conversation creation (e.g. 5 new chats in quick succession) fires N
+ * concurrent requests that can hit provider rate limits or contend for
+ * API capacity, causing later calls to time out and fall back to
+ * "Untitled Conversation".
+ *
+ * A serial queue ensures at most one title-generation LLM call is
+ * in-flight at a time. Each call is lightweight (~1–3 s for a ≤5-word
+ * title), so the added serial latency is modest and invisible to the
+ * user (the UI shows "Generating title…" as a placeholder during the
+ * wait). Both initial generation and second-pass regeneration share
+ * this queue since they hit the same provider.
+ */
+export const titleMutex = new Mutex();
+
 /**
  * Fire-and-forget wrapper for title generation. Failures are logged
  * but do not propagate. On failure, replaces loading placeholder with
  * a stable fallback title so loading state is never permanent.
+ *
+ * Calls are serialized via {@link titleMutex} so burst conversation
+ * creation does not overwhelm the LLM provider.
  */
 export function queueGenerateConversationTitle(
   params: GenerateTitleParams,
 ): void {
-  generateAndPersistConversationTitle(params).catch((err) => {
-    log.warn(
-      { err, conversationId: params.conversationId },
-      "Failed to generate conversation title (non-fatal)",
-    );
-    // Replace loading placeholder with stable fallback
-    try {
-      const conversation = getConversation(params.conversationId);
-      if (conversation && conversation.title === GENERATING_TITLE) {
-        const fallback =
-          deriveFallbackTitle(params.context) ?? UNTITLED_FALLBACK;
-        updateConversationTitle(params.conversationId, fallback);
-        params.onTitleUpdated?.(fallback);
+  void titleMutex
+    .withLock(async () => {
+      await generateAndPersistConversationTitle(params);
+    })
+    .catch((err) => {
+      log.warn(
+        { err, conversationId: params.conversationId },
+        "Failed to generate conversation title (non-fatal)",
+      );
+      // Replace loading placeholder with stable fallback
+      try {
+        const conversation = getConversation(params.conversationId);
+        if (conversation && conversation.title === GENERATING_TITLE) {
+          const fallback =
+            deriveFallbackTitle(params.context) ?? UNTITLED_FALLBACK;
+          updateConversationTitle(params.conversationId, fallback);
+          publishConversationTitleChanged(params.conversationId, fallback);
+        }
+      } catch {
+        // Best-effort
       }
-    } catch {
-      // Best-effort
-    }
-  });
+    });
 }
 
 // ── Title regeneration (second pass) ─────────────────────────────────
@@ -204,7 +223,6 @@ export function queueGenerateConversationTitle(
 export interface RegenerateTitleParams {
   conversationId: string;
   provider?: Provider;
-  onTitleUpdated?: (title: string) => void;
   signal?: AbortSignal;
 }
 
@@ -216,7 +234,7 @@ export interface RegenerateTitleParams {
 export async function regenerateConversationTitle(
   params: RegenerateTitleParams,
 ): Promise<{ title: string; updated: boolean }> {
-  const { conversationId, onTitleUpdated, signal } = params;
+  const { conversationId, signal } = params;
 
   const conversation = getConversation(conversationId);
   if (!conversation || !conversation.isAutoTitle) {
@@ -249,7 +267,7 @@ export async function regenerateConversationTitle(
     tools: [],
     callSite: "conversationTitle",
     signal,
-    timeoutMs: 10_000,
+    timeoutMs: 15_000,
   });
   const title = normalizeTitle(result.text);
   if (title) {
@@ -260,7 +278,7 @@ export async function regenerateConversationTitle(
     }
 
     updateConversationTitle(conversationId, title, 1);
-    onTitleUpdated?.(title);
+    publishConversationTitleChanged(conversationId, title);
     log.info(
       { conversationId, title },
       "Re-generated conversation title (second pass)",
@@ -273,16 +291,22 @@ export async function regenerateConversationTitle(
 
 /**
  * Fire-and-forget wrapper for title regeneration.
+ *
+ * Serialized via the same {@link titleMutex} as initial generation.
  */
 export function queueRegenerateConversationTitle(
   params: RegenerateTitleParams,
 ): void {
-  regenerateConversationTitle(params).catch((err) => {
-    log.warn(
-      { err, conversationId: params.conversationId },
-      "Failed to regenerate conversation title (non-fatal)",
-    );
-  });
+  void titleMutex
+    .withLock(async () => {
+      await regenerateConversationTitle(params);
+    })
+    .catch((err) => {
+      log.warn(
+        { err, conversationId: params.conversationId },
+        "Failed to regenerate conversation title (non-fatal)",
+      );
+    });
 }
 
 // ── Internal helpers ─────────────────────────────────────────────────

package/src/memory/db-connection.ts

@@ -6,12 +6,15 @@ import { Database } from "bun:sqlite";
 import { drizzle } from "drizzle-orm/bun-sqlite";
 
 import { ensureDataDir, getDbPath } from "../util/platform.js";
+import {
+  clearStoredDb,
+  getStoredDb,
+  setStoredDb,
+} from "./db-singleton.js";
 import * as schema from "./schema.js";
 
 export type DrizzleDb = ReturnType<typeof drizzle<typeof schema>>;
 
-let db: DrizzleDb | null = null;
-
 function canonicalizePathThroughExistingParent(path: string): string {
   const resolvedPath = resolve(path);
   const pendingSegments: string[] = [];
@@ -71,18 +74,20 @@ function assertTestDbIsIsolated(): void {
 }
 
 export function getDb(): DrizzleDb {
-  if (!db) {
-    assertTestDbIsIsolated();
-    ensureDataDir();
-    const sqlite = new Database(getDbPath());
-    sqlite.exec("PRAGMA journal_mode=WAL");
-    sqlite.exec("PRAGMA synchronous=FULL");
-    sqlite.exec("PRAGMA busy_timeout=5000");
-    sqlite.exec("PRAGMA foreign_keys = ON");
-    sqlite.exec("PRAGMA cache_size=-256000");
-    sqlite.exec("PRAGMA temp_store=MEMORY");
-    db = drizzle(sqlite, { schema });
-  }
+  const existing = getStoredDb<DrizzleDb>();
+  if (existing) return existing;
+
+  assertTestDbIsIsolated();
+  ensureDataDir();
+  const sqlite = new Database(getDbPath());
+  sqlite.exec("PRAGMA journal_mode=WAL");
+  sqlite.exec("PRAGMA synchronous=FULL");
+  sqlite.exec("PRAGMA busy_timeout=5000");
+  sqlite.exec("PRAGMA foreign_keys = ON");
+  sqlite.exec("PRAGMA cache_size=-256000");
+  sqlite.exec("PRAGMA temp_store=MEMORY");
+  const db = drizzle(sqlite, { schema });
+  setStoredDb(db, () => sqlite.close());
   return db;
 }
 
@@ -107,10 +112,15 @@ export function getSqliteFrom(drizzleDb: DrizzleDb): Database {
   return (drizzleDb as unknown as { $client: Database }).$client;
 }
 
-/** Reset the db singleton. Used by tests to ensure isolation between test files. */
+/**
+ * Reset the db singleton. Used by production callers that need to close
+ * the live connection so the file can be replaced (post-migration,
+ * post-restore, post-vbundle-import) and on graceful shutdown.
+ *
+ * Tests should use `resetDbForTesting()` from
+ * `__tests__/db-test-helpers.ts` instead so they don't depend on this
+ * module's heavy import chain (`drizzle-orm/bun-sqlite`).
+ */
 export function resetDb(): void {
-  if (db) {
-    getSqliteFrom(db).close();
-    db = null;
-  }
+  clearStoredDb();
 }

package/src/memory/db-init.ts

@@ -18,6 +18,7 @@ import {
   addCoreColumns,
   createApprovalPromptTsTrackerTable,
   createAssistantInboxTables,
+  createAuthFallbackEventsTable,
   createCallSessionsTables,
   createCanonicalGuardianTables,
   createChannelGuardianTables,
@@ -40,9 +41,11 @@ import {
   migrate230AcpSessionHistory,
   migrate231RepairMemoryGraphEventDates,
   migrateA2ATasks,
+  migrateAcpSessionHistoryCwd,
   migrateActivationState,
   migrateActivationStateFkCascade,
   migrateAddConversationInferenceProfile,
+  migrateAddMemoryV3Selections,
   migrateAddSourceTypeColumns,
   migrateAssistantContactMetadata,
   migrateBackfillAudioAttachmentMimeTypes,
@@ -96,6 +99,7 @@ import {
   migrateDropMemoryItemsTables,
   migrateDropMemorySegmentFts,
   migrateDropOrphanedMediaTables,
+  migrateDropProviderConnectionStatus,
   migrateDropRemindersTable,
   migrateDropSetupSkillIdColumn,
   migrateDropSimplifiedMemory,
@@ -124,6 +128,7 @@ import {
   migrateLlmRequestLogsCreatedAtIndex,
   migrateLlmUsageAddRawUsage,
   migrateLlmUsageAttribution,
+  migrateLlmUsageEventsAddAssistantVersion,
   migrateMemoryGraphImageRefs,
   migrateMemoryItemSupersession,
   migrateMemoryRecallLogsQueryContext,
@@ -133,8 +138,10 @@ import {
   migrateMemoryV3AutoEdges,
   migrateMemoryV3Coactivation,
   migrateMessageBookmarks,
+  migrateMessagesClientMessageId,
   migrateMessagesConversationCreatedAtIndex,
   migrateMessagesFtsBackfill,
+  migrateMessagesRoleCreatedAtIndex,
   migrateNormalizePhoneIdentities,
   migrateNormalizeSlackExternalContent,
   migrateNormalizeUserFileByPrincipal,
@@ -182,6 +189,8 @@ import {
   migrateScheduleRetryPolicy,
   migrateScheduleReuseConversation,
   migrateScheduleScriptColumn,
+  migrateScheduleScriptTimeout,
+  migrateScheduleSourceConversation,
   migrateScheduleWakeConversationId,
   migrateSchemaIndexesAndColumns,
   migrateScrubCorruptedImageAttachments,
@@ -462,6 +471,15 @@ export function initializeDb(): void {
     migrateMemoryV3Coactivation,
     migrateMemoryV3AutoEdges,
     migrateLlmRequestLogCallSite,
+    migrateDropProviderConnectionStatus,
+    migrateMessagesClientMessageId,
+    migrateLlmUsageEventsAddAssistantVersion,
+    migrateAddMemoryV3Selections,
+    migrateScheduleScriptTimeout,
+    migrateScheduleSourceConversation,
+    migrateMessagesRoleCreatedAtIndex,
+    createAuthFallbackEventsTable,
+    migrateAcpSessionHistoryCwd,
   ];
 
   // Run each migration step, catching and logging individual failures so one

package/src/memory/db-maintenance.ts

@@ -1,15 +1,16 @@
 import { statSync } from "node:fs";
 
+import { getConfig } from "../config/loader.js";
 import { getLogger } from "../util/logger.js";
 import { getDbPath } from "../util/platform.js";
 import { getMemoryCheckpoint, setMemoryCheckpoint } from "./checkpoints.js";
+import { getLastUserMessageTimestamp } from "./conversation-crud.js";
 import { runAsyncSqlite } from "./db-async-query.js";
 import { getSqlite } from "./db-connection.js";
 
 const log = getLogger("db-maintenance");
 
 const DB_MAINTENANCE_CHECKPOINT_KEY = "db_maintenance:last_run";
-const DB_MAINTENANCE_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
 
 interface DbStats {
   pageSize: number;
@@ -101,11 +102,26 @@ async function runDbMaintenance(): Promise<void> {
 }
 
 export async function maybeRunDbMaintenance(nowMs = Date.now()): Promise<void> {
+  const { intervalMs, quietPeriodMs } = getConfig().memory.maintenance;
+
   const lastRun = parseInt(
     getMemoryCheckpoint(DB_MAINTENANCE_CHECKPOINT_KEY) ?? "0",
     10,
   );
-  if (nowMs - lastRun < DB_MAINTENANCE_INTERVAL_MS) return;
+  if (nowMs - lastRun < intervalMs) return;
+
+  // VACUUM holds an exclusive lock on the database for its full duration —
+  // minutes on a multi-GB DB — during which every other write fails with
+  // SQLITE_BUSY ("database is locked"). Defer maintenance until the user has
+  // been quiet for `quietPeriodMs` so that lock never lands mid-conversation.
+  // The checkpoint below is only written once maintenance actually runs, so a
+  // deferred run is simply retried on a later (still-idle) worker tick.
+  if (quietPeriodMs > 0) {
+    const lastUserMessageAt = getLastUserMessageTimestamp();
+    if (lastUserMessageAt > 0 && nowMs - lastUserMessageAt < quietPeriodMs) {
+      return;
+    }
+  }
 
   try {
     await runDbMaintenance();

package/src/memory/db-singleton.ts

@@ -0,0 +1,77 @@
+/**
+ * Holds the assistant DB connection singleton and its close callback.
+ *
+ * Lives in its own module (rather than alongside the resolver in
+ * `db-connection.ts`) so test code can reset the singleton without
+ * importing `db-connection.ts` — which transitively pulls
+ * `drizzle-orm/bun-sqlite`. Stdlib-only by design: this file must remain
+ * safe to import from the test preload's load-time chain, where a broken
+ * `node_modules` symlink has historically tripped the env override
+ * (see DB ghost #3, /workspace/journal/2026-05-25-db-ghost-3-recovery.md).
+ *
+ * State is held on `globalThis.vellumAssistant.dbSingleton` so test
+ * helpers in `__tests__/` can read/write it WITHOUT importing this
+ * module — they declare the same slot shape locally and access the
+ * globalThis namespace directly. See
+ * `__tests__/db-test-helpers.ts` for the test-side mirror; the slot
+ * shape MUST stay in sync between the two.
+ *
+ * The stored value is typed as `unknown` so this file never has to import
+ * Drizzle types. Callers in `db-connection.ts` narrow via the type
+ * parameter on `getStoredDb<DrizzleDb>()`.
+ *
+ * Consumers:
+ *   - `db-connection.ts` (opens/owns the connection)
+ *   - production callers that need to close the active connection
+ *     (migration routes, vbundle import, backup/restore, daemon shutdown)
+ *   - `__tests__/db-test-helpers.ts` (per-test reset, via globalThis)
+ */
+
+type DbSlot = {
+  db: unknown;
+  closer: (() => void) | null;
+};
+
+type VellumAssistantNamespace = {
+  dbSingleton?: DbSlot;
+};
+
+function slot(): DbSlot {
+  const g = globalThis as { vellumAssistant?: VellumAssistantNamespace };
+  const ns = (g.vellumAssistant ??= {});
+  return (ns.dbSingleton ??= { db: null, closer: null });
+}
+
+/** Read the current singleton, narrowed to `T`. `null` means not yet opened. */
+export function getStoredDb<T>(): T | null {
+  return slot().db as T | null;
+}
+
+/**
+ * Store a freshly-opened connection and the closer to run on
+ * `clearStoredDb()`. The closer must be self-contained — it is invoked
+ * inside a try/catch, so partial failures are swallowed (best-effort
+ * close on shutdown / restore paths).
+ */
+export function setStoredDb<T>(newDb: T, close: () => void): void {
+  const s = slot();
+  s.db = newDb;
+  s.closer = close;
+}
+
+/**
+ * Close the active connection (if any) via the stored closer, then drop
+ * both. Idempotent: safe to call when no connection is stored.
+ */
+export function clearStoredDb(): void {
+  const s = slot();
+  if (s.closer) {
+    try {
+      s.closer();
+    } catch {
+      /* best-effort close */
+    }
+  }
+  s.db = null;
+  s.closer = null;
+}