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

package/src/__tests__/credential-vault-unit.test.ts

@@ -27,8 +27,8 @@ mock.module("../util/logger.js", () => ({
 // Use encrypted backend with a temp store path
 // ---------------------------------------------------------------------------
 
-import { _setStorePath } from "../security/encrypted-store.js";
 import { _resetBackend } from "../security/secure-keys.js";
+import { setStorePathForTesting } from "./encrypted-store-test-helpers.js";
 
 const TEST_DIR = join(
   tmpdir(),
@@ -280,7 +280,7 @@ describe("CredentialBroker transient credentials", () => {
   beforeEach(() => {
     if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true });
     mkdirSync(TEST_DIR, { recursive: true });
-    _setStorePath(STORE_PATH);
+    setStorePathForTesting(STORE_PATH);
     _resetBackend();
     _setMetadataPath(join(TEST_DIR, "metadata.json"));
     broker = new CredentialBroker();
@@ -288,7 +288,7 @@ describe("CredentialBroker transient credentials", () => {
 
   afterEach(() => {
     _setMetadataPath(null);
-    _setStorePath(null);
+    setStorePathForTesting(null);
     _resetBackend();
   });
 
@@ -504,14 +504,14 @@ describe("credential_store tool — unknown action", () => {
   beforeEach(() => {
     if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true });
     mkdirSync(TEST_DIR, { recursive: true });
-    _setStorePath(STORE_PATH);
+    setStorePathForTesting(STORE_PATH);
     _resetBackend();
     _setMetadataPath(join(TEST_DIR, "metadata.json"));
   });
 
   afterEach(() => {
     _setMetadataPath(null);
-    _setStorePath(null);
+    setStorePathForTesting(null);
     _resetBackend();
   });
 
@@ -534,14 +534,14 @@ describe("credential_store tool — prompt action", () => {
   beforeEach(() => {
     if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true });
     mkdirSync(TEST_DIR, { recursive: true });
-    _setStorePath(STORE_PATH);
+    setStorePathForTesting(STORE_PATH);
     _resetBackend();
     _setMetadataPath(join(TEST_DIR, "metadata.json"));
   });
 
   afterEach(() => {
     _setMetadataPath(null);
-    _setStorePath(null);
+    setStorePathForTesting(null);
     _resetBackend();
   });
 
@@ -845,14 +845,14 @@ describe("credential_store tool — slack_channel store routing", () => {
   beforeEach(() => {
     if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true });
     mkdirSync(TEST_DIR, { recursive: true });
-    _setStorePath(STORE_PATH);
+    setStorePathForTesting(STORE_PATH);
     _resetBackend();
     _setMetadataPath(join(TEST_DIR, "metadata.json"));
   });
 
   afterEach(() => {
     _setMetadataPath(null);
-    _setStorePath(null);
+    setStorePathForTesting(null);
     _resetBackend();
   });
 
@@ -956,14 +956,14 @@ describe("credential_store tool — store validation edge cases", () => {
   beforeEach(() => {
     if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true });
     mkdirSync(TEST_DIR, { recursive: true });
-    _setStorePath(STORE_PATH);
+    setStorePathForTesting(STORE_PATH);
     _resetBackend();
     _setMetadataPath(join(TEST_DIR, "metadata.json"));
   });
 
   afterEach(() => {
     _setMetadataPath(null);
-    _setStorePath(null);
+    setStorePathForTesting(null);
     _resetBackend();
   });
 
@@ -1124,14 +1124,14 @@ describe("credential_store tool — slack_channel delete routing", () => {
   beforeEach(() => {
     if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true });
     mkdirSync(TEST_DIR, { recursive: true });
-    _setStorePath(STORE_PATH);
+    setStorePathForTesting(STORE_PATH);
     _resetBackend();
     _setMetadataPath(join(TEST_DIR, "metadata.json"));
   });
 
   afterEach(() => {
     _setMetadataPath(null);
-    _setStorePath(null);
+    setStorePathForTesting(null);
     _resetBackend();
   });
 
@@ -1304,7 +1304,7 @@ describe("CredentialBroker — serverUseById edge cases", () => {
   beforeEach(() => {
     if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true });
     mkdirSync(TEST_DIR, { recursive: true });
-    _setStorePath(STORE_PATH);
+    setStorePathForTesting(STORE_PATH);
     _resetBackend();
     _setMetadataPath(join(TEST_DIR, "metadata.json"));
     broker = new CredentialBroker();
@@ -1312,7 +1312,7 @@ describe("CredentialBroker — serverUseById edge cases", () => {
 
   afterEach(() => {
     _setMetadataPath(null);
-    _setStorePath(null);
+    setStorePathForTesting(null);
     _resetBackend();
   });
 
@@ -1376,7 +1376,7 @@ describe("CredentialBroker — revokeAll", () => {
   beforeEach(() => {
     if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true });
     mkdirSync(TEST_DIR, { recursive: true });
-    _setStorePath(STORE_PATH);
+    setStorePathForTesting(STORE_PATH);
     _resetBackend();
     _setMetadataPath(join(TEST_DIR, "metadata.json"));
     broker = new CredentialBroker();
@@ -1384,7 +1384,7 @@ describe("CredentialBroker — revokeAll", () => {
 
   afterEach(() => {
     _setMetadataPath(null);
-    _setStorePath(null);
+    setStorePathForTesting(null);
     _resetBackend();
   });
 
@@ -1432,7 +1432,7 @@ describe("CredentialBroker — canonical capability key", () => {
   beforeEach(() => {
     if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true });
     mkdirSync(TEST_DIR, { recursive: true });
-    _setStorePath(STORE_PATH);
+    setStorePathForTesting(STORE_PATH);
     _resetBackend();
     _setMetadataPath(join(TEST_DIR, "metadata.json"));
     broker = new CredentialBroker();
@@ -1440,7 +1440,7 @@ describe("CredentialBroker — canonical capability key", () => {
 
   afterEach(() => {
     _setMetadataPath(null);
-    _setStorePath(null);
+    setStorePathForTesting(null);
     _resetBackend();
   });
 

package/src/__tests__/credential-vault.test.ts

@@ -28,8 +28,8 @@ mock.module("../util/logger.js", () => ({
 // Use encrypted backend with a temp store path
 // ---------------------------------------------------------------------------
 
-import { _setStorePath } from "../security/encrypted-store.js";
 import { _resetBackend } from "../security/secure-keys.js";
+import { setStorePathForTesting } from "./encrypted-store-test-helpers.js";
 
 const TEST_DIR = join(
   tmpdir(),
@@ -282,7 +282,7 @@ describe("credential_store tool", () => {
     for (const entry of readdirSync(TEST_DIR)) {
       rmSync(join(TEST_DIR, entry), { recursive: true, force: true });
     }
-    _setStorePath(STORE_PATH);
+    setStorePathForTesting(STORE_PATH);
     _setMetadataPath(join(TEST_DIR, "metadata.json"));
     mockDisconnectOAuthProvider.mockClear();
     mockConnections.clear();
@@ -290,7 +290,7 @@ describe("credential_store tool", () => {
 
   afterEach(() => {
     _setMetadataPath(null);
-    _setStorePath(null);
+    setStorePathForTesting(null);
     _resetBackend();
     mockConnections.clear();
   });
@@ -1282,7 +1282,7 @@ describe("withValidToken refresh deduplication", () => {
     for (const entry of readdirSync(TEST_DIR)) {
       rmSync(join(TEST_DIR, entry), { recursive: true, force: true });
     }
-    _setStorePath(STORE_PATH);
+    setStorePathForTesting(STORE_PATH);
     _setMetadataPath(join(TEST_DIR, "metadata.json"));
     _resetRefreshBreakers();
     _resetInflightRefreshes();
@@ -1295,7 +1295,7 @@ describe("withValidToken refresh deduplication", () => {
 
   afterEach(() => {
     _setMetadataPath(null);
-    _setStorePath(null);
+    setStorePathForTesting(null);
     _resetBackend();
     _resetRefreshBreakers();
     _resetInflightRefreshes();

package/src/__tests__/cross-provider-web-search.test.ts

@@ -1,6 +1,10 @@
-import { beforeEach, describe, expect, mock, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 
-import type { ContentBlock, Message } from "../providers/types.js";
+import type {
+  ContentBlock,
+  Message,
+  ToolDefinition,
+} from "../providers/types.js";
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -85,6 +89,22 @@ function webSearchResultOnlyMessage(): Message[] {
   ];
 }
 
+const sampleTools: ToolDefinition[] = [
+  {
+    name: "file_read",
+    description: "Read a file",
+    input_schema: { type: "object", properties: { path: { type: "string" } } },
+  },
+  {
+    name: "web_search",
+    description: "Search the web",
+    input_schema: {
+      type: "object",
+      properties: { query: { type: "string" } },
+    },
+  },
+];
+
 // ---------------------------------------------------------------------------
 // Mock OpenAI SDK
 // ---------------------------------------------------------------------------
@@ -128,7 +148,7 @@ mock.module("openai", () => {
         },
       };
       responses = {
-        stream: (params: Record<string, unknown>) => {
+        create: async (params: Record<string, unknown>) => {
           lastOpenAIResponsesParams = JSON.parse(JSON.stringify(params));
           return (async function* () {
             yield {
@@ -194,12 +214,71 @@ mock.module("@google/genai", () => {
 });
 
 // Import providers after mocking
+import { FireworksProvider } from "../providers/fireworks/client.js";
 import { GeminiProvider } from "../providers/gemini/client.js";
 import {
   OpenAIChatCompletionsProvider,
   OpenAIResponsesProvider,
 } from "../providers/openai/client.js";
 
+// ---------------------------------------------------------------------------
+// App-side web_search provider adapters (Brave/Perplexity/Tavily)
+//
+// Exercise the real `web-search.ts` execute path with a mocked config, provider
+// key, and global fetch. The logger is mocked to capture structured warnings so
+// we can assert the `web_search_backend_failure` telemetry (ATL-727).
+// ---------------------------------------------------------------------------
+
+let mockWebSearchProvider: string = "brave";
+let mockProviderKey: string | undefined = "test-key";
+const capturedWarnLogs: Record<string, unknown>[] = [];
+
+const realConfigLoader = await import("../config/loader.js");
+mock.module("../config/loader.js", () => ({
+  ...realConfigLoader,
+  getConfig: () => ({
+    services: { "web-search": { provider: mockWebSearchProvider } },
+  }),
+}));
+
+const realSecureKeys = await import("../security/secure-keys.js");
+mock.module("../security/secure-keys.js", () => ({
+  ...realSecureKeys,
+  getProviderKeyAsync: async () => mockProviderKey,
+}));
+
+const realLogger = await import("../util/logger.js");
+mock.module("../util/logger.js", () => ({
+  ...realLogger,
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: (_target, prop) => {
+        if (prop === "warn") {
+          return (obj: Record<string, unknown>) => {
+            capturedWarnLogs.push(obj);
+          };
+        }
+        return () => {};
+      },
+    }),
+}));
+
+const { webSearchTool } = await import("../tools/network/web-search.js");
+const { WEB_SEARCH_BACKEND_FAILURE_MESSAGE } = await import(
+  "../tools/network/web-search-error.js"
+);
+
+function executeWebSearch(input: Record<string, unknown>) {
+  return webSearchTool.execute(input, {} as never);
+}
+
+function executeWebSearchWithSignal(
+  input: Record<string, unknown>,
+  signal: AbortSignal,
+) {
+  return webSearchTool.execute(input, { signal } as never);
+}
+
 // ---------------------------------------------------------------------------
 // OpenAI Responses API provider tests
 // ---------------------------------------------------------------------------
@@ -345,7 +424,9 @@ describe("Cross-Provider Web Search — OpenAI (Responses API, native mode)", ()
       },
     ];
 
-    await provider.sendMessage([userMsg("Search for something")], tools);
+    await provider.sendMessage([userMsg("Search for something")], {
+      tools,
+    });
 
     const sentTools = lastOpenAIResponsesParams!.tools as Array<
       Record<string, unknown>
@@ -458,6 +539,41 @@ describe("Cross-Provider Web Search — OpenAI Chat Completions (compatibility)"
   });
 });
 
+// ---------------------------------------------------------------------------
+// Fireworks provider tests
+// ---------------------------------------------------------------------------
+
+describe("Cross-Provider Web Search — Fireworks", () => {
+  beforeEach(() => {
+    lastOpenAIChatParams = null;
+  });
+
+  test("keeps web_search as an app-executed function tool for managed Brave fallback", async () => {
+    const provider = new FireworksProvider(
+      "fw-test",
+      "accounts/fireworks/models/kimi-k2p6",
+    );
+
+    await provider.sendMessage([userMsg("Search for something")], {
+      tools: sampleTools,
+    });
+
+    const tools = lastOpenAIChatParams!.tools as Array<{
+      type: string;
+      function: { name: string; description?: string };
+    }>;
+
+    expect(tools).toHaveLength(2);
+    expect(tools[1]).toMatchObject({
+      type: "function",
+      function: {
+        name: "web_search",
+        description: "Search the web",
+      },
+    });
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Gemini provider tests
 // ---------------------------------------------------------------------------
@@ -546,3 +662,158 @@ describe("Cross-Provider Web Search — Gemini", () => {
     expect(functionCallParts).toHaveLength(0);
   });
 });
+
+// ---------------------------------------------------------------------------
+// App-side provider backend-failure normalization (ATL-727)
+// ---------------------------------------------------------------------------
+
+describe("Cross-Provider Web Search — app-side backend failure normalization", () => {
+  let originalFetch: typeof globalThis.fetch;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    mockWebSearchProvider = "brave";
+    mockProviderKey = "test-key";
+    capturedWarnLogs.length = 0;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  function backendFailureLog() {
+    return capturedWarnLogs.find(
+      (entry) => entry.event === "web_search_backend_failure",
+    );
+  }
+
+  test("503 from provider yields friendly recoverable copy in content + errorMessage, logs raw 503, no body leak", async () => {
+    const rawBody = '{"error":"upstream exploded","trace":"do-not-leak"}';
+    globalThis.fetch = (async () =>
+      new Response(rawBody, { status: 503 })) as unknown as typeof fetch;
+
+    const result = await executeWebSearch({ query: "needle in a haystack" });
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toBe(WEB_SEARCH_BACKEND_FAILURE_MESSAGE);
+    const meta = result.activityMetadata?.webSearch;
+    expect(meta?.errorMessage).toBe(WEB_SEARCH_BACKEND_FAILURE_MESSAGE);
+    expect(meta?.results).toEqual([]);
+    expect(meta?.resultCount).toBe(0);
+
+    const logEntry = backendFailureLog();
+    expect(logEntry).toBeDefined();
+    expect(logEntry!.provider).toBe("brave");
+    expect(logEntry!.errorCategory).toBe("backend_unavailable");
+    expect(logEntry!.fallbackShown).toBe(true);
+    expect(logEntry!.queryLength).toBe("needle in a haystack".length);
+    expect(String(logEntry!.rawDetail)).toContain("503");
+    // Provider diagnostic body is preserved in internal telemetry rawDetail.
+    expect(String(logEntry!.rawDetail)).toContain("upstream exploded");
+    expect(String(logEntry!.rawDetail)).toContain("do-not-leak");
+
+    // Raw provider body must never reach user-facing fields.
+    expect(result.content).not.toContain("upstream exploded");
+    expect(result.content).not.toContain("do-not-leak");
+    expect(meta?.errorMessage).not.toContain("upstream exploded");
+    expect(meta?.errorMessage).not.toContain("do-not-leak");
+  });
+
+  test("thrown network error yields the same friendly backend result", async () => {
+    globalThis.fetch = (async () => {
+      throw new TypeError("fetch failed");
+    }) as unknown as typeof fetch;
+
+    const result = await executeWebSearch({ query: "offline" });
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toBe(WEB_SEARCH_BACKEND_FAILURE_MESSAGE);
+    expect(result.activityMetadata?.webSearch?.errorMessage).toBe(
+      WEB_SEARCH_BACKEND_FAILURE_MESSAGE,
+    );
+    const logEntry = backendFailureLog();
+    expect(logEntry).toBeDefined();
+    expect(logEntry!.errorCategory).toBe("backend_unavailable");
+    expect(result.content).not.toContain("fetch failed");
+  });
+
+  test("401 invalid-key preserves the specific message, not the backend copy", async () => {
+    globalThis.fetch = (async () =>
+      new Response("Unauthorized", { status: 401 })) as unknown as typeof fetch;
+
+    const result = await executeWebSearch({ query: "bad key" });
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("Invalid or expired Brave Search API key");
+    expect(result.content).not.toBe(WEB_SEARCH_BACKEND_FAILURE_MESSAGE);
+    expect(result.activityMetadata?.webSearch?.errorMessage).not.toBe(
+      WEB_SEARCH_BACKEND_FAILURE_MESSAGE,
+    );
+    expect(backendFailureLog()).toBeUndefined();
+  });
+
+  test("HTTP 200 with zero results stays a success (unchanged)", async () => {
+    globalThis.fetch = (async () =>
+      new Response(JSON.stringify({ web: { results: [] } }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      })) as unknown as typeof fetch;
+
+    const result = await executeWebSearch({ query: "no hits" });
+
+    expect(result.isError).toBe(false);
+    expect(result.activityMetadata?.webSearch?.errorMessage).toBeUndefined();
+    expect(result.content).toContain("No results found");
+    expect(backendFailureLog()).toBeUndefined();
+  });
+
+  test("post-retry 429 yields the friendly recoverable copy and preserves body in rawDetail", async () => {
+    const rawBody = '{"error":"quota burned","retryHint":"do-not-leak-429"}';
+    globalThis.fetch = (async () =>
+      new Response(rawBody, {
+        status: 429,
+        headers: { "retry-after": "0" },
+      })) as unknown as typeof fetch;
+
+    const result = await executeWebSearch({ query: "rate limited" });
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toBe(WEB_SEARCH_BACKEND_FAILURE_MESSAGE);
+    const meta = result.activityMetadata?.webSearch;
+    expect(meta?.errorMessage).toBe(WEB_SEARCH_BACKEND_FAILURE_MESSAGE);
+    const logEntry = backendFailureLog();
+    expect(logEntry).toBeDefined();
+    expect(logEntry!.errorCategory).toBe("rate_limited");
+    expect(String(logEntry!.rawDetail)).toContain("429");
+    // Provider diagnostic body is preserved in internal telemetry rawDetail.
+    expect(String(logEntry!.rawDetail)).toContain("quota burned");
+    expect(String(logEntry!.rawDetail)).toContain("do-not-leak-429");
+
+    // Raw provider body must never reach user-facing fields.
+    expect(result.content).not.toContain("quota burned");
+    expect(result.content).not.toContain("do-not-leak-429");
+    expect(meta?.errorMessage).not.toContain("quota burned");
+    expect(meta?.errorMessage).not.toContain("do-not-leak-429");
+  });
+
+  test("caller abort re-throws instead of producing a backend failure (no telemetry)", async () => {
+    const controller = new AbortController();
+    controller.abort();
+
+    // A caller-aborted request surfaces an AbortError from fetch.
+    globalThis.fetch = (async () => {
+      const abortError = new Error("The operation was aborted");
+      abortError.name = "AbortError";
+      throw abortError;
+    }) as unknown as typeof fetch;
+
+    // The cancellation must re-throw so the executor's abort handling takes
+    // over — NOT resolve to the friendly backend-failure result.
+    await expect(
+      executeWebSearchWithSignal({ query: "cancel me" }, controller.signal),
+    ).rejects.toThrow();
+
+    // No spurious backend-failure telemetry for a user/external cancellation.
+    expect(backendFailureLog()).toBeUndefined();
+  });
+});

package/src/__tests__/cu-unified-flow.test.ts

@@ -438,7 +438,7 @@ describe("surfaceProxyResolver — CU tool routing", () => {
       });
 
       expect(result.isError).toBe(true);
-      expect(result.content).toContain("multiple clients support host_cu");
+      expect(result.content).toContain("Multiple host_cu clients");
       expect(result.content).toContain("target_client_id");
       // No message should have been dispatched
       expect(sentMessages).toHaveLength(0);
@@ -705,6 +705,31 @@ describe("surfaceProxyResolver — CU tool routing", () => {
       });
       await resultPromise;
     });
+
+    test("rejects untargeted CU dispatch when only another actor has a capable client", async () => {
+      sentMessages.length = 0;
+      mockHasClient = true;
+      mockCuClients = [
+        {
+          clientId: "cu-other",
+          capabilities: ["host_cu"],
+          actorPrincipalId: "user-other",
+        },
+      ];
+      proxy = new HostCuProxy();
+      const ctx = buildMockContext(proxy, DEFAULT_PRINCIPAL);
+
+      const result = await surfaceProxyResolver(ctx, "computer_use_click", {
+        element_id: 1,
+        reasoning: "click",
+      });
+
+      expect(result.isError).toBe(true);
+      expect(result.content).toContain("current actor");
+      // No step burned, no dispatch.
+      expect(proxy.stepCount).toBe(0);
+      expect(sentMessages).toHaveLength(0);
+    });
   });
 
   describe("step limit enforcement through resolver", () => {

package/src/__tests__/db-acp-history.test.ts

@@ -5,6 +5,7 @@ import { drizzle } from "drizzle-orm/bun-sqlite";
 
 import { getSqliteFrom } from "../memory/db-connection.js";
 import { migrate230AcpSessionHistory } from "../memory/migrations/230-acp-session-history.js";
+import { migrateAcpSessionHistoryCwd } from "../memory/migrations/272-acp-session-history-cwd.js";
 import * as schema from "../memory/schema.js";
 
 function createTestDb() {
@@ -282,3 +283,103 @@ describe("acp_session_history migration", () => {
     expect(row?.id).toBe("history-rerun");
   });
 });
+
+describe("acp_session_history cwd migration (272)", () => {
+  function readColumns(raw: Database): Map<string, ColumnRow> {
+    const columns = raw
+      .query(`PRAGMA table_info(acp_session_history)`)
+      .all() as ColumnRow[];
+    return new Map(columns.map((c) => [c.name, c]));
+  }
+
+  test("adds a nullable cwd TEXT column to an upgraded table", () => {
+    const db = createTestDb();
+    const raw = getSqliteFrom(db);
+    bootstrapCheckpointsTable(raw);
+
+    migrate230AcpSessionHistory(db);
+    expect(readColumns(raw).has("cwd")).toBe(false);
+
+    migrateAcpSessionHistoryCwd(db);
+
+    const cwd = readColumns(raw).get("cwd");
+    expect(cwd).toBeDefined();
+    expect(cwd?.type).toBe("TEXT");
+    expect(cwd?.notnull).toBe(0);
+  });
+
+  test("re-running is a no-op, including with a cleared checkpoint", () => {
+    const db = createTestDb();
+    const raw = getSqliteFrom(db);
+    bootstrapCheckpointsTable(raw);
+
+    migrate230AcpSessionHistory(db);
+    migrateAcpSessionHistoryCwd(db);
+
+    // Second run short-circuits on the completed checkpoint.
+    expect(() => migrateAcpSessionHistoryCwd(db)).not.toThrow();
+
+    // Even with the checkpoint cleared (simulating crash recovery), the
+    // column-existence guard makes the ALTER a no-op.
+    raw
+      .query(`DELETE FROM memory_checkpoints WHERE key = ?`)
+      .run("migration_acp_session_history_cwd_v1");
+    expect(() => migrateAcpSessionHistoryCwd(db)).not.toThrow();
+
+    const columns = raw
+      .query(`PRAGMA table_info(acp_session_history)`)
+      .all() as ColumnRow[];
+    expect(columns.filter((c) => c.name === "cwd")).toHaveLength(1);
+  });
+
+  test("legacy rows read back with cwd null; new rows round-trip cwd", () => {
+    const db = createTestDb();
+    const raw = getSqliteFrom(db);
+    bootstrapCheckpointsTable(raw);
+
+    migrate230AcpSessionHistory(db);
+
+    // Legacy row inserted before the cwd column existed.
+    raw
+      .query(
+        /*sql*/ `
+        INSERT INTO acp_session_history (
+          id, agent_id, acp_session_id, parent_conversation_id,
+          started_at, status
+        ) VALUES (?, ?, ?, ?, ?, ?)
+      `,
+      )
+      .run("legacy-1", "agent-old", "acp-old", "conv-old", 100, "completed");
+
+    migrateAcpSessionHistoryCwd(db);
+
+    const legacy = raw
+      .query(`SELECT cwd FROM acp_session_history WHERE id = 'legacy-1'`)
+      .get() as { cwd: string | null } | null;
+    expect(legacy?.cwd).toBeNull();
+
+    raw
+      .query(
+        /*sql*/ `
+        INSERT INTO acp_session_history (
+          id, agent_id, acp_session_id, parent_conversation_id,
+          started_at, status, cwd
+        ) VALUES (?, ?, ?, ?, ?, ?, ?)
+      `,
+      )
+      .run(
+        "new-1",
+        "agent-new",
+        "acp-new",
+        "conv-new",
+        200,
+        "completed",
+        "/Users/me/project",
+      );
+
+    const fresh = raw
+      .query(`SELECT cwd FROM acp_session_history WHERE id = 'new-1'`)
+      .get() as { cwd: string | null } | null;
+    expect(fresh?.cwd).toBe("/Users/me/project");
+  });
+});