@vellumai/assistant 0.8.3 → 0.8.5

package/src/home/suggested-prompts.ts

@@ -6,11 +6,22 @@
  *
  * Two sources of prompts:
  *   - **Deterministic** — derived from missing OAuth connections.
+ *     Computed inline (read-only, safe for GET).
  *   - **Assistant-generated** — contextual suggestions from the LLM
- *     (placeholder; not yet implemented).
+ *     based on what's relevant to the user. Read from an in-memory
+ *     cache in the GET path; generation runs in the background via
+ *     `refreshAssistantSuggestedPrompts`.
  */
 
-import { isProviderConnected, listProviders } from "../oauth/oauth-store.js";
+import { resolveCallSiteConfig } from "../config/llm-resolver.js";
+import { getConfig } from "../config/loader.js";
+import { listProviders } from "../oauth/oauth-store.js";
+import { buildSystemPrompt } from "../prompts/system-prompt.js";
+import { getConfiguredProvider } from "../providers/provider-send-message.js";
+import { buildAssistantEvent } from "../runtime/assistant-event.js";
+import { assistantEventHub } from "../runtime/assistant-event-hub.js";
+import { runBtwSidechain } from "../runtime/btw-sidechain.js";
+import { isOAuthProviderConnected } from "../schedule/integration-status.js";
 import { getLogger } from "../util/logger.js";
 import type { SuggestedPrompt } from "./feed-types.js";
 
@@ -72,27 +83,88 @@ const CONNECT_PROMPT_META: Record<
   },
 };
 
+const LLM_SUGGESTIONS_TIMEOUT_MS = 5_000;
+const LLM_CACHE_TTL_MS = 30 * 60 * 1000; // 30 minutes
+
+// ---------------------------------------------------------------------------
+// In-memory cache for LLM-generated suggestions
+// ---------------------------------------------------------------------------
+
+let cachedLLMPrompts: SuggestedPrompt[] = [];
+let cachedLLMPromptsAt = 0;
+
 /**
- * Produce deterministic suggested prompts based on missing OAuth
- * connections and (in the future) assistant-generated conversation
- * starters.
+ * Produce suggested prompts from both deterministic and cached LLM sources.
+ * Deterministic prompts always come first; cached LLM-generated prompts are
+ * appended when available. No LLM calls happen in this path — safe for GET.
  */
 export async function getSuggestedPrompts(): Promise<SuggestedPrompt[]> {
   const prompts: SuggestedPrompt[] = [];
 
+  let deterministicPrompts: SuggestedPrompt[] = [];
   try {
-    const deterministicPrompts = await getDeterministicPrompts();
+    deterministicPrompts = await getDeterministicPrompts();
     prompts.push(...deterministicPrompts);
   } catch (err) {
     log.warn({ err }, "Failed to compute deterministic suggested prompts");
   }
 
-  // Placeholder: assistant-generated prompts will be added here once
-  // the LLM producer is implemented.
+  if (Date.now() - cachedLLMPromptsAt < LLM_CACHE_TTL_MS) {
+    prompts.push(...cachedLLMPrompts);
+  }
 
   return prompts;
 }
 
+/**
+ * Drops the in-memory LLM suggestion cache so the next call to
+ * `getSuggestedPrompts()` returns only the fresh deterministic list (and
+ * a follow-up background refresh repopulates the LLM half).
+ *
+ * Called from OAuth connect/disconnect paths so a freshly-connected
+ * provider stops surfacing as a "Connect X" pill within one reload — the
+ * 30-minute TTL would otherwise pin a stale suggestion until the next
+ * periodic refresh.
+ */
+export function invalidateAssistantSuggestedPromptsCache(): void {
+  cachedLLMPrompts = [];
+  cachedLLMPromptsAt = 0;
+  assistantEventHub
+    .publish(
+      buildAssistantEvent({
+        type: "home_feed_updated",
+        updatedAt: new Date().toISOString(),
+        newItemCount: 0,
+      }),
+    )
+    .catch((err) => {
+      log.warn(
+        { err },
+        "Failed to publish home_feed_updated after prompt cache invalidation",
+      );
+    });
+}
+
+/**
+ * Generate LLM-based suggestion prompts and write them to the in-memory
+ * cache. No-ops when the cache is still fresh. Intended for background
+ * invocation (daemon startup / periodic refresh), not the GET path.
+ */
+export async function refreshAssistantSuggestedPrompts(): Promise<void> {
+  if (Date.now() - cachedLLMPromptsAt < LLM_CACHE_TTL_MS) {
+    return;
+  }
+
+  try {
+    const deterministicPrompts = await getDeterministicPrompts();
+    const llmPrompts = await generateAssistantPrompts(deterministicPrompts);
+    cachedLLMPrompts = llmPrompts;
+    cachedLLMPromptsAt = Date.now();
+  } catch (err) {
+    log.warn({ err }, "Failed to refresh assistant suggested prompts");
+  }
+}
+
 /**
  * Check which well-known OAuth providers are not connected and return
  * a "Connect X" prompt for each. For connected providers that have
@@ -107,7 +179,7 @@ async function getDeterministicPrompts(): Promise<SuggestedPrompt[]> {
     const meta = CONNECT_PROMPT_META[provider.provider];
     if (!meta) continue;
 
-    const connected = await isProviderConnected(provider.provider);
+    const connected = await isOAuthProviderConnected(provider.provider);
 
     if (!connected) {
       prompts.push({
@@ -135,3 +207,90 @@ async function getDeterministicPrompts(): Promise<SuggestedPrompt[]> {
 
   return prompts;
 }
+
+// ---------------------------------------------------------------------------
+// LLM-generated suggestions
+// ---------------------------------------------------------------------------
+
+interface LLMSuggestion {
+  label: string;
+  prompt: string;
+}
+
+/**
+ * Ask the LLM to generate contextual conversation-starter suggestions
+ * based on the assistant's persona and the user's connected services.
+ * Returns an empty array on failure so deterministic prompts still show.
+ */
+async function generateAssistantPrompts(
+  deterministicPrompts: SuggestedPrompt[],
+): Promise<SuggestedPrompt[]> {
+  const config = getConfig();
+  const resolved = resolveCallSiteConfig("homeSuggestedPrompts", config.llm);
+
+  const provider = await getConfiguredProvider("homeSuggestedPrompts");
+  if (!provider) {
+    return [];
+  }
+
+  const systemPrompt = buildSystemPrompt({
+    excludeBootstrap: true,
+    excludeCustomPrefix: true,
+  });
+
+  const existingLabels = deterministicPrompts.map((p) => p.label).join(", ");
+  const contextNote = existingLabels
+    ? `The user already has these suggestions: ${existingLabels}. Do NOT duplicate them.`
+    : "";
+
+  const result = await runBtwSidechain({
+    content:
+      "Suggest 2-3 short, actionable conversation starters for the home page. " +
+      "Each should be something specific and helpful you can do for the user right now. " +
+      `${contextNote} ` +
+      'Return ONLY a JSON array of objects with "label" (max 5 words) and "prompt" (the full message to send). ' +
+      "No markdown fences, no explanation.",
+    provider,
+    systemPrompt,
+    messages: [],
+    tools: [],
+    callSite: "homeSuggestedPrompts",
+    maxTokens: resolved.maxTokens,
+    timeoutMs: LLM_SUGGESTIONS_TIMEOUT_MS,
+  });
+
+  const text = result.text.trim();
+  if (!text) {
+    return [];
+  }
+
+  const parsed = parseLLMSuggestions(text);
+  return parsed.map((s, i) => ({
+    id: `assistant-${i}-${s.label.toLowerCase().replace(/\s+/g, "-")}`,
+    label: s.label,
+    prompt: s.prompt,
+    source: "assistant" as const,
+  }));
+}
+
+function parseLLMSuggestions(text: string): LLMSuggestion[] {
+  try {
+    const cleaned = text
+      .replace(/^```(?:json)?\n?/m, "")
+      .replace(/\n?```$/m, "");
+    const parsed = JSON.parse(cleaned);
+    if (!Array.isArray(parsed)) {
+      return [];
+    }
+    return parsed.filter(
+      (item): item is LLMSuggestion =>
+        typeof item === "object" &&
+        item !== null &&
+        typeof item.label === "string" &&
+        typeof item.prompt === "string",
+    );
+  } catch {
+    log.warn("Failed to parse LLM suggestions response");
+    return [];
+  }
+}

package/src/ipc/gateway-flag-listener.ts

@@ -0,0 +1,123 @@
+import { connect, type Socket } from "node:net";
+
+import { refreshOverridesFromGateway } from "../config/assistant-feature-flags.js";
+import { SYNC_TAGS } from "../daemon/message-types/sync.js";
+import { publishSyncInvalidation } from "../runtime/sync/sync-publisher.js";
+import { getLogger } from "../util/logger.js";
+import { resolveIpcSocketPath } from "./socket-path.js";
+
+const log = getLogger("gateway-flag-listener");
+
+const MAX_BACKOFF_MS = 30_000;
+const INITIAL_BACKOFF_MS = 1_000;
+
+let socket: Socket | null = null;
+let stopped = false;
+let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+let currentBackoffMs = INITIAL_BACKOFF_MS;
+
+function getSocketPath(): string {
+  return resolveIpcSocketPath("gateway").path;
+}
+
+function handleData(chunk: Buffer): void {
+  const lines = chunk.toString().split("\n");
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const msg = JSON.parse(trimmed) as { event?: string };
+      if (msg.event === "feature_flags_changed") {
+        log.info("Received feature_flags_changed event — refreshing overrides");
+        refreshOverridesFromGateway().catch((err) => {
+          log.warn({ err }, "Failed to refresh feature flag overrides");
+        });
+        // Fan out to every connected web client so React Query caches
+        // for `/v1/feature-flags/client-flag-values/` and
+        // `/v1/assistants/:id/feature-flags` invalidate immediately
+        // instead of waiting on a 5s polling tick.
+        publishSyncInvalidation([
+          SYNC_TAGS.featureFlagsClient,
+          SYNC_TAGS.featureFlagsAssistant,
+        ]).catch((err) => {
+          log.warn({ err }, "Failed to broadcast feature-flags sync_changed");
+        });
+      }
+    } catch {
+      // Ignore non-JSON lines (e.g. IPC responses on a shared socket)
+    }
+  }
+}
+
+function scheduleReconnect(): void {
+  if (stopped) return;
+  reconnectTimer = setTimeout(() => {
+    reconnectTimer = null;
+    connectToGateway();
+  }, currentBackoffMs);
+  currentBackoffMs = Math.min(currentBackoffMs * 2, MAX_BACKOFF_MS);
+}
+
+function connectToGateway(): void {
+  if (stopped) return;
+
+  const socketPath = getSocketPath();
+  const conn = connect(socketPath);
+
+  conn.on("connect", () => {
+    if (stopped) {
+      conn.destroy();
+      return;
+    }
+    log.info("Connected to gateway IPC for flag events");
+    currentBackoffMs = INITIAL_BACKOFF_MS;
+    socket = conn;
+    refreshOverridesFromGateway().catch((err) => {
+      log.warn({ err }, "Failed to refresh feature flag overrides on reconnect");
+    });
+  });
+
+  let buffer = "";
+  conn.on("data", (chunk) => {
+    buffer += chunk.toString();
+    let newlineIdx: number;
+    while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
+      const line = buffer.slice(0, newlineIdx);
+      buffer = buffer.slice(newlineIdx + 1);
+      if (line.trim()) {
+        handleData(Buffer.from(line));
+      }
+    }
+  });
+
+  conn.on("close", () => {
+    socket = null;
+    if (!stopped) {
+      log.debug("Gateway IPC connection closed — reconnecting");
+      scheduleReconnect();
+    }
+  });
+
+  conn.on("error", (err) => {
+    log.debug({ err }, "Gateway IPC connection error");
+    conn.destroy();
+  });
+}
+
+export function startGatewayFlagListener(): void {
+  stopped = false;
+  currentBackoffMs = INITIAL_BACKOFF_MS;
+  connectToGateway();
+}
+
+export function stopGatewayFlagListener(): void {
+  stopped = true;
+  if (reconnectTimer) {
+    clearTimeout(reconnectTimer);
+    reconnectTimer = null;
+  }
+  if (socket) {
+    socket.destroy();
+    socket = null;
+  }
+}

package/src/ipc/skill-routes/registries.ts

@@ -22,12 +22,9 @@ import { z } from "zod";
 import type { MeetHostSupervisor } from "../../daemon/meet-host-supervisor.js";
 import { registerShutdownHook } from "../../daemon/shutdown-registry.js";
 import { registerSkillRoute } from "../../runtime/skill-route-registry.js";
+import { resolveExecutionTarget } from "../../tools/execution-target.js";
 import { registerSkillTools } from "../../tools/registry.js";
-import type {
-  ExecutionTarget,
-  Tool,
-  ToolDefinition,
-} from "../../tools/types.js";
+import type { ExecutionTarget, Tool } from "../../tools/types.js";
 import { RiskLevel } from "../../tools/types.js";
 import { getLogger } from "../../util/logger.js";
 import type { SkillIpcRoute } from "../skill-ipc-types.js";
@@ -182,25 +179,24 @@ export function __getActiveSessionCountForTesting(): number {
  * exercised end-to-end.
  */
 function buildProxyTool(manifest: ToolManifest): Tool {
-  const definition: ToolDefinition = {
-    name: manifest.name,
-    description: manifest.description,
-    input_schema: manifest.input_schema as object,
-  };
   // RiskLevel is a string enum whose values are "low" | "medium" | "high",
   // matching the schema above exactly — the cast is a no-op at runtime.
   return {
     name: manifest.name,
     description: manifest.description,
+    input_schema: manifest.input_schema as object,
     category: manifest.category,
     defaultRiskLevel: manifest.defaultRiskLevel as RiskLevel,
     executionMode: manifest.executionMode ?? "proxy",
-    executionTarget: manifest.executionTarget as ExecutionTarget | undefined,
+    executionTarget: resolveExecutionTarget({
+      name: manifest.name,
+      executionTarget: manifest.executionTarget as ExecutionTarget | undefined,
+      executionMode: manifest.executionMode ?? "proxy",
+    }),
     origin: "skill",
     ownerSkillId: manifest.ownerSkillId,
     ownerSkillBundled: manifest.ownerSkillBundled,
     ownerSkillVersionHash: manifest.ownerSkillVersionHash,
-    getDefinition: () => definition,
     execute: async () => {
       // Only reached when no supervisor is attached (tests/boot race);
       // the supervisor short-circuit above replaces this with the

package/src/memory/__tests__/db-async-query.test.ts

@@ -0,0 +1,165 @@
+/**
+ * Tests for `db-async-query.ts` — the runAsyncSqlite abstraction.
+ *
+ * The contract this PR locks in:
+ *   1. **The main event loop keeps ticking while a long SQLite
+ *      statement is in flight via the sqlite3 CLI backend.** This is
+ *      the structural anti-block assertion — a recursive `setImmediate`
+ *      probe counts event-loop iterations during the operation; if
+ *      anyone moves the slow path back onto the main thread,
+ *      `bun:sqlite` is synchronous and tick counting collapses to ~0;
+ *      this test fails loudly.
+ *   2. The CLI backend reports `backend: "sqlite3-cli"` and `ok: true`
+ *      on success.
+ *   3. The in-process fallback backend executes the statement
+ *      synchronously and reports `backend: "in-process-blocking"`.
+ *   4. Errors from sqlite3 surface as `ok: false` with the stderr
+ *      preserved in `error`.
+ */
+import { beforeEach, describe, expect, test } from "bun:test";
+
+const { getSqlite } = await import("../db-connection.js");
+const { initializeDb } = await import("../db-init.js");
+const { runAsyncSqlite, _resetFallbackWarning } =
+  await import("../db-async-query.js");
+const { findSqlite3 } = await import("../../util/sqlite3-runtime.js");
+
+initializeDb();
+
+const sqlite3Available = findSqlite3() !== undefined;
+
+beforeEach(() => {
+  _resetFallbackWarning();
+});
+
+function inflateAndDelete(byteTarget: number): void {
+  const sqlite = getSqlite();
+  sqlite.exec(
+    "CREATE TABLE IF NOT EXISTS async_bloat (id INTEGER PRIMARY KEY, payload BLOB)",
+  );
+  const pageSize = (
+    sqlite.query("PRAGMA page_size").get() as { page_size: number }
+  ).page_size;
+  const rowsTarget = Math.max(1, Math.ceil(byteTarget / pageSize));
+  const payload = new Uint8Array(Math.max(1, pageSize - 64));
+  const insert = sqlite.prepare("INSERT INTO async_bloat (payload) VALUES (?)");
+  sqlite.exec("BEGIN");
+  for (let i = 0; i < rowsTarget; i++) {
+    insert.run(payload);
+  }
+  sqlite.exec("COMMIT");
+  sqlite.exec("DELETE FROM async_bloat");
+  sqlite.exec("DROP TABLE async_bloat");
+  sqlite.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+}
+
+describe("runAsyncSqlite", () => {
+  test("returns ok=true for a trivial statement", async () => {
+    const result = await runAsyncSqlite("SELECT 1");
+    expect(result.ok).toBe(true);
+    expect(result.error).toBeNull();
+  });
+
+  test("in-process fallback reports the right backend", async () => {
+    const result = await runAsyncSqlite("SELECT 1", {
+      forceBackend: "in-process-blocking",
+    });
+    expect(result.ok).toBe(true);
+    expect(result.backend).toBe("in-process-blocking");
+  });
+
+  test("in-process fallback emits changes() count on stdout after a DELETE", async () => {
+    // Regression for Codex P1 on #31894: callers (e.g. prune jobs) rely
+    // on reading the row count off `result.stdout`. The CLI backend
+    // populates this naturally when the SQL ends with `SELECT changes();`,
+    // but `bun:sqlite`'s `exec()` discards SELECT results — so the
+    // in-process backend has to synthesize the same line, or the
+    // re-enqueue gate in pruneOld*Job silently never fires on hosts
+    // without the sqlite3 CLI.
+    const sqlite = getSqlite();
+    sqlite.exec(
+      "CREATE TABLE IF NOT EXISTS async_changes_probe (id INTEGER PRIMARY KEY)",
+    );
+    sqlite.exec("DELETE FROM async_changes_probe");
+    sqlite.exec(
+      "INSERT INTO async_changes_probe (id) VALUES (1),(2),(3),(4),(5)",
+    );
+
+    const result = await runAsyncSqlite(
+      "DELETE FROM async_changes_probe WHERE id <= 3; SELECT changes();",
+      { forceBackend: "in-process-blocking" },
+    );
+
+    expect(result.ok).toBe(true);
+    expect(result.backend).toBe("in-process-blocking");
+    // The synthesized stdout matches what the CLI backend would emit:
+    // a bare integer on its own line. The exact format keeps the
+    // parser in cleanup.ts backend-agnostic.
+    expect(result.stdout).toBe("3\n");
+
+    sqlite.exec("DROP TABLE async_changes_probe");
+  });
+
+  test.if(sqlite3Available)(
+    "sqlite3 CLI backend reports the right backend on success",
+    async () => {
+      const result = await runAsyncSqlite("SELECT 1");
+      expect(result.ok).toBe(true);
+      expect(result.backend).toBe("sqlite3-cli");
+    },
+  );
+
+  test.if(sqlite3Available)(
+    "surfaces sqlite3 errors as ok=false with the message preserved",
+    async () => {
+      // Intentional SQL syntax error.
+      const result = await runAsyncSqlite("THIS IS NOT VALID SQL");
+      expect(result.ok).toBe(false);
+      expect(result.backend).toBe("sqlite3-cli");
+      expect(result.error).toBeTruthy();
+    },
+  );
+
+  test.if(sqlite3Available)(
+    "VACUUM via sqlite3 CLI keeps the event loop ticking (anti-block)",
+    async () => {
+      // Inflate the DB so VACUUM has measurable work to do. Without
+      // this the subprocess finishes in single-digit ms and the
+      // probe has no opportunity to record meaningful ticks.
+      inflateAndDelete(8 * 1024 * 1024);
+
+      // Probe the event loop with recursive setImmediate. This fires
+      // on every event-loop iteration with no minimum delay, so on a
+      // healthy unblocked loop it produces tens of thousands of ticks
+      // per second (vs. setInterval(1) which is capped by the host's
+      // timer resolution — observed at ~32 ms on GitHub Actions
+      // runners). If anyone moves VACUUM back onto the main thread,
+      // `bun:sqlite` is sync and tick count collapses to ~0; the
+      // assertion below fails loudly. The signal is intentionally
+      // binary: "many" vs "none".
+      let tickCount = 0;
+      let probing = true;
+      const tick = (): void => {
+        if (!probing) return;
+        tickCount += 1;
+        setImmediate(tick);
+      };
+      setImmediate(tick);
+
+      let result;
+      try {
+        result = await runAsyncSqlite("VACUUM");
+      } finally {
+        probing = false;
+      }
+
+      expect(result.ok).toBe(true);
+      expect(result.backend).toBe("sqlite3-cli");
+
+      // Any positive tick count proves the event loop wasn't blocked.
+      // A sync in-process VACUUM would collapse this to 0.
+      expect(tickCount).toBeGreaterThanOrEqual(1);
+    },
+    60_000,
+  );
+});

package/src/memory/__tests__/db-maintenance.test.ts

@@ -0,0 +1,115 @@
+/**
+ * Tests for `db-maintenance.ts` (orchestration) and the underlying
+ * `db-async-query.ts` abstraction.
+ *
+ * The contract this PR locks in:
+ *   1. `runDbMaintenance` runs `VACUUM` through the async abstraction
+ *      — when the `sqlite3` CLI is available, that means a subprocess
+ *      and the daemon's main event loop keeps ticking. (The structural
+ *      anti-block assertion lives in
+ *      `db-async-query.test.ts`; here we focus on orchestration.)
+ *   2. The subprocess actually shrinks the on-disk page count when
+ *      there's reclaimable space.
+ *   3. `maybeRunDbMaintenance` is genuinely async — callers can `await`
+ *      it and observe completion.
+ *   4. The 24 h interval guard short-circuits a recent re-run.
+ *
+ * The per-file temp workspace is set up by `test-preload.ts`; tests just
+ * dynamic-import the DB modules so they resolve paths under that temp dir.
+ */
+import { Database } from "bun:sqlite";
+import { beforeEach, describe, expect, test } from "bun:test";
+
+const { getSqlite } = await import("../db-connection.js");
+const { initializeDb } = await import("../db-init.js");
+const { deleteMemoryCheckpoint, getMemoryCheckpoint } =
+  await import("../checkpoints.js");
+const { maybeRunDbMaintenance } = await import("../db-maintenance.js");
+const { getDbPath } = await import("../../util/platform.js");
+
+initializeDb();
+
+const MAINTENANCE_CHECKPOINT_KEY = "db_maintenance:last_run";
+
+beforeEach(() => {
+  deleteMemoryCheckpoint(MAINTENANCE_CHECKPOINT_KEY);
+});
+
+/** Inflate the test DB with bloat that VACUUM can reclaim. */
+function inflateAndDelete(byteTarget: number): void {
+  const sqlite = getSqlite();
+  sqlite.exec(
+    "CREATE TABLE IF NOT EXISTS bloat (id INTEGER PRIMARY KEY, payload BLOB)",
+  );
+  const pageSize = (
+    sqlite.query("PRAGMA page_size").get() as { page_size: number }
+  ).page_size;
+  const rowsTarget = Math.max(1, Math.ceil(byteTarget / pageSize));
+  const payload = new Uint8Array(Math.max(1, pageSize - 64));
+  const insert = sqlite.prepare("INSERT INTO bloat (payload) VALUES (?)");
+  sqlite.exec("BEGIN");
+  for (let i = 0; i < rowsTarget; i++) {
+    insert.run(payload);
+  }
+  sqlite.exec("COMMIT");
+  sqlite.exec("DELETE FROM bloat");
+  sqlite.exec("DROP TABLE bloat");
+  // Force the WAL onto the main DB file so the bloat is visible on disk.
+  sqlite.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+}
+
+describe("maybeRunDbMaintenance", () => {
+  test("returns a Promise that resolves", async () => {
+    const result = maybeRunDbMaintenance();
+    expect(result).toBeInstanceOf(Promise);
+    await result;
+  });
+
+  test("respects the 24h interval and skips when last run was recent", async () => {
+    const now = Date.now();
+    const recent = now - 60_000;
+    const { setMemoryCheckpoint } = await import("../checkpoints.js");
+    setMemoryCheckpoint(MAINTENANCE_CHECKPOINT_KEY, String(recent));
+
+    await maybeRunDbMaintenance(now);
+
+    expect(getMemoryCheckpoint(MAINTENANCE_CHECKPOINT_KEY)).toBe(
+      String(recent),
+    );
+  });
+
+  test("stamps the checkpoint after a maintenance run", async () => {
+    const now = Date.now();
+    await maybeRunDbMaintenance(now);
+
+    expect(getMemoryCheckpoint(MAINTENANCE_CHECKPOINT_KEY)).toBe(String(now));
+  });
+
+  test("VACUUM reclaims pages on a bloated DB", async () => {
+    const sqlite = getSqlite();
+    sqlite.exec("DROP TABLE IF EXISTS bloat");
+    sqlite.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+
+    inflateAndDelete(8 * 1024 * 1024);
+
+    const dbPath = getDbPath();
+    // Read page_count from a fresh connection so we observe post-write
+    // ground truth without snapshot caching on the main test connection.
+    const readPageCount = (): number => {
+      const probe = new Database(dbPath, { readonly: true });
+      try {
+        return (
+          probe.query("PRAGMA page_count").get() as { page_count: number }
+        ).page_count;
+      } finally {
+        probe.close();
+      }
+    };
+    const pagesBefore = readPageCount();
+
+    await maybeRunDbMaintenance();
+
+    const pagesAfter = readPageCount();
+    expect(pagesAfter).toBeLessThan(pagesBefore);
+  }, 60_000);
+});