@vellumai/assistant 0.8.4 → 0.8.6

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/__tests__/memory.test.ts

@@ -24,6 +24,7 @@ const addMessageSpy = mock(
 );
 mock.module("../../../memory/conversation-crud.js", () => ({
   addMessage: addMessageSpy,
+  reserveMessage: mock(async () => ({ id: "msg-reserve" })),
 }));
 
 const wakeAgentSpy = mock(

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

@@ -19,6 +19,7 @@ import {
   __clearExternalToolProvidersForTesting,
   __clearRegistryForTesting,
   getTool,
+  getToolOwner,
 } from "../../../tools/registry.js";
 import {
   __getActiveSessionCountForTesting,
@@ -55,7 +56,12 @@ afterEach(() => {
 
 describe("host.registries.register_tools", () => {
   test("installs proxy tools into the daemon's external tool registry", async () => {
+    // `skillId` lives at the top of the params object (one frame = one
+    // skill's batch). The per-tool manifest schema no longer carries an
+    // `owner` field — ownership flows in through this top-level key and
+    // is recorded in the registry's `ownersByName` map.
     const result = (await registerToolsRoute.handler({
+      skillId: "demo-skill",
       tools: [
         {
           name: "skill_demo_tool",
@@ -64,7 +70,6 @@ describe("host.registries.register_tools", () => {
           defaultRiskLevel: "low",
           category: "skill",
           executionTarget: "sandbox",
-          ownerSkillId: "demo-skill",
         },
       ],
     })) as { registered: string[] };
@@ -72,13 +77,17 @@ describe("host.registries.register_tools", () => {
     expect(result.registered).toEqual(["skill_demo_tool"]);
     const installed = getTool("skill_demo_tool");
     expect(installed).toBeDefined();
-    expect(installed!.origin).toBe("skill");
-    expect(installed!.ownerSkillId).toBe("demo-skill");
-    expect(installed!.executionMode).toBe("proxy");
+    // Ownership lives on the registry — getToolOwner is the single source of
+    // truth. The Tool object itself no longer carries the kind.
+    expect(getToolOwner("skill_demo_tool")).toEqual({
+      kind: "skill",
+      id: "demo-skill",
+    });
   });
 
   test("proxy execute throws when no supervisor is attached", async () => {
     await registerToolsRoute.handler({
+      skillId: "stub-skill",
       tools: [
         {
           name: "skill_stub_tool",
@@ -86,7 +95,6 @@ describe("host.registries.register_tools", () => {
           input_schema: { type: "object" },
           defaultRiskLevel: "medium",
           category: "skill",
-          ownerSkillId: "stub-skill",
         },
       ],
     });
@@ -106,16 +114,37 @@ describe("host.registries.register_tools", () => {
   });
 
   test("rejects empty tool list", async () => {
-    await expect(registerToolsRoute.handler({ tools: [] })).rejects.toThrow();
+    await expect(
+      registerToolsRoute.handler({ skillId: "any-skill", tools: [] }),
+    ).rejects.toThrow();
   });
 
   test("rejects missing required fields", async () => {
     await expect(
       registerToolsRoute.handler({
+        skillId: "any-skill",
         tools: [{ name: "missing_rest" }],
       }),
     ).rejects.toThrow();
   });
+
+  test("rejects missing skillId", async () => {
+    // skillId is the only place ownership flows in over IPC — without it
+    // the registry can't claim the tools, so the handler must reject.
+    await expect(
+      registerToolsRoute.handler({
+        tools: [
+          {
+            name: "skill_orphan_tool",
+            description: "no owner",
+            input_schema: { type: "object" },
+            defaultRiskLevel: "low",
+            category: "skill",
+          },
+        ],
+      }),
+    ).rejects.toThrow();
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -302,6 +331,7 @@ describe("lazy-external short-circuit", () => {
 
     const result = (await registerToolsRoute.handler(
       {
+        skillId: "demo-skill",
         tools: [
           {
             name: "skill_demo_tool",
@@ -309,7 +339,6 @@ describe("lazy-external short-circuit", () => {
             input_schema: {},
             defaultRiskLevel: "low",
             category: "skill",
-            ownerSkillId: "demo-skill",
           },
         ],
       },

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

@@ -17,13 +17,14 @@ import type { SkillIpcRoute } from "../skill-ipc-types.js";
 
 /**
  * Shape mirrors the daemon's `addMessage()` positional signature:
- * `(conversationId, role, content, metadata?, opts?)`. Metadata is a
- * free-form record (validated downstream by `messageMetadataSchema` with a
+ * `(conversationId, role, content, metadata?, opts?)`. `role` is
+ * constrained to the `MessageRole` union. Metadata is a free-form
+ * record (validated downstream by `messageMetadataSchema` with a
  * warn-and-store fallback). Only `skipIndexing` is recognised in `opts`.
  */
 const MemoryAddMessageParams = z.object({
   conversationId: z.string().min(1),
-  role: z.string().min(1),
+  role: z.enum(["user", "assistant", "system"]),
   content: z.string(),
   metadata: z.record(z.string(), z.unknown()).optional(),
   opts: z

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";
@@ -51,18 +48,19 @@ const ToolManifestSchema = z.object({
   defaultRiskLevel: z.enum(["low", "medium", "high"]),
   category: z.string().min(1),
   executionTarget: z.enum(["sandbox", "host"]).optional(),
-  executionMode: z.enum(["local", "proxy"]).optional(),
-  // Required so disconnect can decrement the tool-registry refcount: a
-  // tool registered without an owner has no ref-counted entry to drop and
-  // would leak into the global registry on socket close.
-  ownerSkillId: z.string().min(1),
-  ownerSkillBundled: z.boolean().optional(),
-  ownerSkillVersionHash: z.string().optional(),
 });
 
 export type ToolManifest = z.infer<typeof ToolManifestSchema>;
 
+// `skillId` lives at the params level rather than per-tool: a single
+// `register_tools` IPC frame is always one skill's batch, ownership flows
+// through `registerSkillTools(skillId, tools)` into the registry's
+// `ownersByName` map, and the tools themselves stay free of owner
+// metadata so callers cannot spoof ownership by forging a field on the
+// manifest. Only skill-owned tools cross IPC — plugin and MCP tools live
+// in-process on the assistant side.
 const RegisterToolsParams = z.object({
+  skillId: z.string().min(1),
   tools: z.array(ToolManifestSchema).min(1),
 });
 
@@ -182,25 +180,18 @@ 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,
-    origin: "skill",
-    ownerSkillId: manifest.ownerSkillId,
-    ownerSkillBundled: manifest.ownerSkillBundled,
-    ownerSkillVersionHash: manifest.ownerSkillVersionHash,
-    getDefinition: () => definition,
+    executionTarget: resolveExecutionTarget({
+      name: manifest.name,
+      executionTarget: manifest.executionTarget as ExecutionTarget | undefined,
+    }),
     execute: async () => {
       // Only reached when no supervisor is attached (tests/boot race);
       // the supervisor short-circuit above replaces this with the
@@ -218,7 +209,7 @@ async function handleRegisterTools(
   params: Record<string, unknown> | undefined,
   connection?: unknown,
 ): Promise<{ registered: string[] }> {
-  const { tools } = RegisterToolsParams.parse(params);
+  const { skillId, tools } = RegisterToolsParams.parse(params);
   const conn = connection as SkillIpcConnection | undefined;
 
   // Supervisor short-circuit: when a supervisor is registered, the
@@ -230,7 +221,11 @@ async function handleRegisterTools(
   if (sessionSupervisor) {
     if (conn) sessionSupervisor.setActiveConnection(conn);
     log.info(
-      { count: tools.length, names: tools.map((t) => t.name) },
+      {
+        count: tools.length,
+        names: tools.map((t) => t.name),
+        ownerSkillId: skillId,
+      },
       "Supervisor active: skipping in-memory tool re-registration; manifest proxies serve dispatches",
     );
     return { registered: tools.map((t) => t.name) };
@@ -240,23 +235,23 @@ async function handleRegisterTools(
   // `registerExternalTools` is only consumed inside `initializeTools()` at
   // daemon boot; IPC children connect after boot, so route through
   // `registerSkillTools` into the live registry the agent-loop reads from.
-  const accepted = registerSkillTools(proxies);
-
-  // `registerSkillTools` increments the registry refcount once per unique
-  // ownerSkillId in the batch; mirror that on the connection so disconnect
-  // issues exactly the matching number of decrements.
-  if (conn) {
-    const ownerIds = new Set<string>();
-    for (const tool of accepted) {
-      if (tool.ownerSkillId) ownerIds.add(tool.ownerSkillId);
-    }
-    for (const skillId of ownerIds) {
-      conn.addSkillToolsOwner(skillId);
-    }
+  // Owner is stamped registry-side from `skillId`; the proxy `Tool` objects
+  // carry no owner field.
+  const accepted = registerSkillTools(skillId, proxies);
+
+  // `registerSkillTools` increments the registry refcount once per call;
+  // mirror that on the connection so disconnect issues exactly one matching
+  // decrement.
+  if (conn && accepted.length > 0) {
+    conn.addSkillToolsOwner(skillId);
   }
 
   log.info(
-    { count: accepted.length, names: accepted.map((t) => t.name) },
+    {
+      count: accepted.length,
+      names: accepted.map((t) => t.name),
+      ownerSkillId: skillId,
+    },
     "Registered skill proxy tools via IPC",
   );
   return { registered: accepted.map((t) => t.name) };

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);
+});