@vellumai/assistant 0.10.12 → 0.11.0-staging.2

package/src/__tests__/host-shell-tool.test.ts

@@ -357,7 +357,7 @@ describe("host_bash — input validation", () => {
     );
 
     expect(result.isError).toBe(true);
-    expect(result.content).toContain("command is required");
+    expect(result.content).toContain('Invalid input for tool "host_bash"');
   });
 
   test("rejects non-string command", async () => {
@@ -369,9 +369,7 @@ describe("host_bash — input validation", () => {
     );
 
     expect(result.isError).toBe(true);
-    expect(result.content).toContain(
-      "command is required and must be a string",
-    );
+    expect(result.content).toContain('Invalid input for tool "host_bash"');
   });
 
   test("rejects non-string working_dir", async () => {
@@ -384,7 +382,7 @@ describe("host_bash — input validation", () => {
     );
 
     expect(result.isError).toBe(true);
-    expect(result.content).toContain("working_dir must be a string");
+    expect(result.content).toContain('Invalid input for tool "host_bash"');
   });
 });
 
@@ -406,6 +404,20 @@ describe("host_bash — environment setup", () => {
     expect(result.content.trim()).toBe(realpathSync(homedir()));
   });
 
+  test("treats an explicit null working_dir as omitted (runs from home)", async () => {
+    const { homedir } = await import("node:os");
+    const result = await hostShellTool.execute(
+      {
+        command: "pwd",
+        working_dir: null,
+      },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(false);
+    expect(result.content.trim()).toBe(realpathSync(homedir()));
+  });
+
   test("PATH includes ~/.local/bin and ~/.bun/bin", async () => {
     const { homedir } = await import("node:os");
     const home = homedir();

package/src/__tests__/host-transfer-pending-interactions.test.ts

@@ -3,7 +3,7 @@
  * registration.
  *
  * Verifies:
- * - HostTransferRequestEvent and HostTransferCancelEvent are part of ServerMessage
+ * - HostTransferRequestEvent and HostTransferCancelEvent are part of AssistantEvent
  * - "host_transfer" is a valid PendingInteraction kind
  * - host_transfer interactions survive removeByConversation (not auto-denied)
  */
@@ -13,7 +13,7 @@ import type {
   HostTransferCancelEvent,
   HostTransferRequestEvent,
 } from "../api/events/host-transfer.js";
-import type { ServerMessage } from "../daemon/message-protocol.js";
+import type { AssistantEvent } from "../api/index.js";
 import * as pendingInteractions from "../runtime/pending-interactions.js";
 
 // ---------------------------------------------------------------------------
@@ -21,7 +21,7 @@ import * as pendingInteractions from "../runtime/pending-interactions.js";
 // ---------------------------------------------------------------------------
 
 describe("HostTransfer message types", () => {
-  test("host_transfer to_host request is assignable to ServerMessage", () => {
+  test("host_transfer to_host request is assignable to AssistantEvent", () => {
     const msg: HostTransferRequestEvent = {
       type: "host_transfer_request",
       requestId: "req-1",
@@ -33,11 +33,11 @@ describe("HostTransfer message types", () => {
       sha256: "abc123",
       overwrite: false,
     };
-    const _sm: ServerMessage = msg;
+    const _sm: AssistantEvent = msg;
     expect(_sm.type).toBe("host_transfer_request");
   });
 
-  test("host_transfer to_sandbox request is assignable to ServerMessage", () => {
+  test("host_transfer to_sandbox request is assignable to AssistantEvent", () => {
     const msg: HostTransferRequestEvent = {
       type: "host_transfer_request",
       requestId: "req-2",
@@ -46,17 +46,17 @@ describe("HostTransfer message types", () => {
       transferId: "xfer-2",
       sourcePath: "/home/user/file.txt",
     };
-    const _sm: ServerMessage = msg;
+    const _sm: AssistantEvent = msg;
     expect(_sm.type).toBe("host_transfer_request");
   });
 
-  test("HostTransferCancelEvent is assignable to ServerMessage", () => {
+  test("HostTransferCancelEvent is assignable to AssistantEvent", () => {
     const msg: HostTransferCancelEvent = {
       type: "host_transfer_cancel",
       requestId: "req-3",
       conversationId: "conv-1",
     };
-    const _sm: ServerMessage = msg;
+    const _sm: AssistantEvent = msg;
     expect(_sm.type).toBe("host_transfer_cancel");
   });
 

package/src/__tests__/image-credentials.test.ts

@@ -21,7 +21,10 @@ mock.module("../providers/platform-proxy/context.js", () => ({
 }));
 
 // Import after mocks
-import { resolveImageGenCredentials } from "../media/image-credentials.js";
+import {
+  resolveImageGenCredentials,
+  resolveImageGenRouting,
+} from "../media/image-credentials.js";
 
 describe("resolveImageGenCredentials", () => {
   beforeEach(() => {
@@ -37,7 +40,7 @@ describe("resolveImageGenCredentials", () => {
 
       const result = await resolveImageGenCredentials({
         provider: "gemini",
-        mode: "managed",
+        managed: true,
       });
 
       expect(result.errorHint).toBeUndefined();
@@ -54,7 +57,7 @@ describe("resolveImageGenCredentials", () => {
 
       const result = await resolveImageGenCredentials({
         provider: "gemini",
-        mode: "managed",
+        managed: true,
       });
 
       expect(result.credentials).toBeUndefined();
@@ -68,7 +71,7 @@ describe("resolveImageGenCredentials", () => {
 
       const result = await resolveImageGenCredentials({
         provider: "gemini",
-        mode: "managed",
+        managed: true,
       });
 
       expect(result.credentials).toBeUndefined();
@@ -83,7 +86,7 @@ describe("resolveImageGenCredentials", () => {
 
       const result = await resolveImageGenCredentials({
         provider: "gemini",
-        mode: "your-own",
+        managed: false,
       });
 
       expect(result.errorHint).toBeUndefined();
@@ -98,7 +101,7 @@ describe("resolveImageGenCredentials", () => {
 
       const result = await resolveImageGenCredentials({
         provider: "gemini",
-        mode: "your-own",
+        managed: false,
       });
 
       expect(result.credentials).toBeUndefined();
@@ -111,7 +114,7 @@ describe("resolveImageGenCredentials", () => {
 
       const result = await resolveImageGenCredentials({
         provider: "openai",
-        mode: "your-own",
+        managed: false,
       });
 
       expect(result.errorHint).toBeUndefined();
@@ -126,7 +129,7 @@ describe("resolveImageGenCredentials", () => {
 
       const result = await resolveImageGenCredentials({
         provider: "openai",
-        mode: "your-own",
+        managed: false,
       });
 
       expect(result.credentials).toBeUndefined();
@@ -135,3 +138,57 @@ describe("resolveImageGenCredentials", () => {
     });
   });
 });
+
+describe("resolveImageGenRouting", () => {
+  test("provider vellum is managed with a gemini backend for gemini models", () => {
+    expect(
+      resolveImageGenRouting({
+        provider: "vellum",
+        model: "gemini-3.1-flash-image-preview",
+      }),
+    ).toEqual({ backendProvider: "gemini", managed: true });
+  });
+
+  test("provider vellum derives an openai backend from a gpt model", () => {
+    expect(
+      resolveImageGenRouting({ provider: "vellum", model: "gpt-image-2" }),
+    ).toEqual({ backendProvider: "openai", managed: true });
+  });
+
+  test("a model override wins over the stored model under vellum", () => {
+    expect(
+      resolveImageGenRouting(
+        { provider: "vellum", model: "gemini-3.1-flash-image-preview" },
+        "gpt-image-2",
+      ),
+    ).toEqual({ backendProvider: "openai", managed: true });
+  });
+
+  test("BYOK providers keep the override re-routing without managed", () => {
+    expect(
+      resolveImageGenRouting(
+        { provider: "gemini", model: "gemini-3.1-flash-image-preview" },
+        "gpt-image-2",
+      ),
+    ).toEqual({ backendProvider: "openai", managed: false });
+  });
+
+  test("vellum with an unavailable platform is a hard error, not a BYOK fallback", async () => {
+    // Billing rule: an explicit vellum choice never silently spends a stored
+    // provider key.
+    mockProviderKey = "gemini-key-should-not-be-used";
+    mockPlatformBaseUrl = "";
+
+    const routing = resolveImageGenRouting({
+      provider: "vellum",
+      model: "gemini-3.1-flash-image-preview",
+    });
+    const result = await resolveImageGenCredentials({
+      provider: routing.backendProvider,
+      managed: routing.managed,
+    });
+
+    expect(result.credentials).toBeUndefined();
+    expect(result.errorHint).toContain("Managed proxy is not available");
+  });
+});

package/src/__tests__/injection-block.test.ts

@@ -1,13 +1,13 @@
 import { describe, expect, test } from "bun:test";
 
-import {
-  assembleContextBlock,
-  assembleInjectionBlock,
-} from "../plugins/defaults/memory/graph/injection.js";
 import type {
   MemoryNode,
   ScoredNode,
 } from "../plugins/defaults/memory/graph/types.js";
+import {
+  assembleContextBlock,
+  assembleInjectionBlock,
+} from "../plugins/defaults/memory/v1/graph/injection.js";
 
 function makeScoredNode(
   overrides: Partial<MemoryNode> & { content: string },

package/src/__tests__/injector-chain.test.ts

@@ -79,7 +79,7 @@ import {
 import { getDb } from "../persistence/db-connection.js";
 import { initializeDb } from "../persistence/db-init.js";
 import { conversations, messages } from "../persistence/schema/index.js";
-import { getPkbRoot } from "../plugins/defaults/memory/pkb/types.js";
+import { getPkbRoot } from "../plugins/defaults/memory/v1/pkb/types.js";
 import { buildUnifiedTurnContextBlock } from "../plugins/defaults/turn-context/unified-turn-context.js";
 import type { TurnContext } from "../plugins/types.js";
 import type { Message } from "../providers/types.js";

package/src/__tests__/injector-pkb-v2-silenced.test.ts

@@ -48,7 +48,7 @@ mock.module("../plugins/defaults/memory/config.js", () => ({
   }),
 }));
 
-mock.module("../plugins/defaults/memory/pkb/pkb-search.js", () => ({
+mock.module("../plugins/defaults/memory/v1/pkb/pkb-search.js", () => ({
   searchPkbFiles: async () => [],
 }));
 
@@ -56,7 +56,7 @@ const { applyRuntimeInjections } =
   await import("../daemon/conversation-runtime-assembly.js");
 const { registerDefaultPluginInjectors } =
   await import("../plugins/defaults/index.js");
-import { getPkbRoot } from "../plugins/defaults/memory/pkb/types.js";
+import { getPkbRoot } from "../plugins/defaults/memory/v1/pkb/types.js";
 import type { TurnContext } from "../plugins/types.js";
 import type { Message } from "../providers/types.js";
 import { getWorkspacePromptPath } from "../util/platform.js";

package/src/__tests__/injector-registry-order-guard.test.ts

@@ -20,10 +20,6 @@ import { channelInjectors } from "../plugins/defaults/channel/injectors.js";
 import { documentsInjectors } from "../plugins/defaults/documents/injectors.js";
 import { registerDefaultPluginInjectors } from "../plugins/defaults/index.js";
 import { memoryInjectors } from "../plugins/defaults/memory/injectors.js";
-import {
-  memoryV3Injector,
-  memoryV3SpotlightInjector,
-} from "../plugins/defaults/memory/v3/injector.js";
 import { sessionInjectors } from "../plugins/defaults/session/injectors.js";
 import { turnContextInjectors } from "../plugins/defaults/turn-context/injectors.js";
 import { workspaceInjectors } from "../plugins/defaults/workspace/injectors.js";
@@ -35,9 +31,10 @@ import {
 import type { Injector } from "../plugins/types.js";
 
 // Every injector every default plugin contributes — the registry-independent
-// union, gathered straight from the plugins' exported arrays. Sorting this by
-// `order` must reproduce what `getRegisteredInjectors()` returns once the
-// defaults are registered.
+// union, gathered straight from the plugins' exported arrays (the memory
+// plugin's whole set, memory-v3 injectors included, comes through
+// `memory/injectors.ts`). Sorting this by `order` must reproduce what
+// `getRegisteredInjectors()` returns once the defaults are registered.
 const ALL_CONTRIBUTED = [
   ...turnContextInjectors,
   ...workspaceInjectors,
@@ -45,8 +42,6 @@ const ALL_CONTRIBUTED = [
   ...channelInjectors,
   ...sessionInjectors,
   ...memoryInjectors,
-  memoryV3Injector,
-  memoryV3SpotlightInjector,
 ];
 
 // The ordered id sequence the chain must produce, by ascending `order`. This

package/src/__tests__/injector-v3-suppression.test.ts

@@ -56,13 +56,15 @@ mock.module("../plugins/injector-registry.js", () => ({
 
 // `applyRuntimeInjections` reads the v3-live gate (`config.memory.v3.live`)
 // via `isMemoryV3Live`; drive it directly through this slot per-test. The
-// import graph also pulls `isProcToSkillsActive` (the permission policy-context
-// precomputes the proc-to-skills gate), so the wholesale mock must expose it —
-// keyed off the same v3-live slot.
+// import graph also pulls `isV3TierActive` (the permission policy-context
+// precomputes the proc-to-skills gate off it) and `isMemoryEnabled`, so the
+// wholesale mock must expose both.
 let memoryV3LiveSlot = false;
 mock.module("../config/memory-v3-gate.js", () => ({
   isMemoryV3Live: () => memoryV3LiveSlot,
-  isProcToSkillsActive: () => false,
+  isV3TierActive: () => false,
+  isMemoryEnabled: (config?: { memory?: { enabled?: boolean } }) =>
+    config?.memory?.enabled !== false,
   usesConceptPageMemory: (memory?: {
     enabled?: boolean;
     v2?: { enabled?: boolean };

package/src/__tests__/lifecycle-memory-v2-seed.test.ts

@@ -1,13 +1,13 @@
 /**
  * Tests for the memory-v2 skill seed gate and the v2 concept-page schema
  * rebuild gate, both invoked from the daemon startup path
- * (`assistant/src/plugins/defaults/memory/v2/memory-v2-startup.ts`).
+ * (`assistant/src/plugins/defaults/memory/substrate/boot-maintenance.ts`).
  *
  * The gates are exercised in isolation rather than mounting the full
  * lifecycle import graph. Coverage matrix:
- *   - Skill seed (`maybeSeedMemoryV2Skills`): config gating, rejection
+ *   - Skill seed (`maybeSeedCapabilitySkills`): config gating, rejection
  *     swallowing.
- *   - Schema rebuild (`maybeRebuildMemoryV2Concepts`): config gating,
+ *   - Schema rebuild (`maybeRebuildConceptCollection`): config gating,
  *     drift-triggered reembed enqueue, empty-after-create reembed enqueue,
  *     no enqueue when collection is healthy, error swallowing.
  *
@@ -27,7 +27,7 @@ interface TestState {
   seedShouldReject: Error | null;
   warnCalls: Array<{ obj: unknown; msg: unknown }>;
   infoCalls: Array<{ obj: unknown; msg: unknown }>;
-  // Rebuild-gate mocks (drive maybeRebuildMemoryV2Concepts).
+  // Rebuild-gate mocks (drive maybeRebuildConceptCollection).
   ensureCollectionCallCount: number;
   ensureCollectionResult: { migrated: boolean };
   ensureCollectionThrows: Error | null;
@@ -61,13 +61,13 @@ const state: TestState = {
 // Mocks — installed before the module under test is loaded.
 // ---------------------------------------------------------------------------
 
-mock.module("../plugins/defaults/memory/v3/substrate/skill-store.js", () => ({
+mock.module("../plugins/defaults/memory/substrate/skill-store.js", () => ({
   seedV2SkillEntries: async (opts?: {
     throwOnError?: boolean;
   }): Promise<void> => {
     state.seedCallCount += 1;
     state.seedCallOpts.push(opts);
-    if (state.seedShouldReject) throw state.seedShouldReject;
+    if (state.seedShouldReject) {throw state.seedShouldReject;}
   },
 }));
 
@@ -75,16 +75,16 @@ mock.module("../plugins/defaults/memory/v3/substrate/skill-store.js", () => ({
 // (which runs both reseeds in parallel) does not invoke the real Qdrant-backed
 // implementation and emit warnings that break the no-warnings assertions below.
 mock.module(
-  "../plugins/defaults/memory/v3/substrate/cli-command-store.js",
+  "../plugins/defaults/memory/substrate/cli-command-store.js",
   () => ({
     seedV2CliCommandEntries: async (): Promise<void> => {},
   }),
 );
 
-mock.module("../plugins/defaults/memory/v3/substrate/qdrant.js", () => ({
+mock.module("../plugins/defaults/memory/substrate/qdrant.js", () => ({
   ensureConceptPageCollection: async (): Promise<{ migrated: boolean }> => {
     state.ensureCollectionCallCount += 1;
-    if (state.ensureCollectionThrows) throw state.ensureCollectionThrows;
+    if (state.ensureCollectionThrows) {throw state.ensureCollectionThrows;}
     return state.ensureCollectionResult;
   },
   countConceptPagePoints: async (): Promise<number> => state.countResult,
@@ -96,15 +96,15 @@ mock.module("../plugins/defaults/memory/v3/substrate/qdrant.js", () => ({
   dropLegacySkillsCollection: async (): Promise<void> => {},
 }));
 
-mock.module("../plugins/defaults/memory/v3/substrate/page-store.js", () => ({
+mock.module("../plugins/defaults/memory/substrate/page-store.js", () => ({
   hasConceptPages: async (): Promise<boolean> =>
     state.listPagesResult.length > 0,
 }));
 
-mock.module("../plugins/defaults/memory/v3/substrate/sparse-bm25.js", () => ({
+mock.module("../plugins/defaults/memory/substrate/sparse-bm25.js", () => ({
   rebuildConceptPageCorpusStats: async (): Promise<void> => {
     state.corpusStatsBuildCount += 1;
-    if (state.corpusStatsThrows) throw state.corpusStatsThrows;
+    if (state.corpusStatsThrows) {throw state.corpusStatsThrows;}
   },
 }));
 
@@ -142,11 +142,10 @@ mock.module("../util/logger.js", () => ({
 }));
 
 const {
-  maybeSeedMemoryV2Skills,
-  maybeRebuildMemoryV2Concepts,
+  maybeSeedCapabilitySkills,
+  maybeRebuildConceptCollection,
   rebuildBm25CorpusStatsAndReseedSkills,
-} =
-  await import("../plugins/defaults/memory/v3/substrate/memory-v2-startup.js");
+} = await import("../plugins/defaults/memory/substrate/boot-maintenance.js");
 
 // ---------------------------------------------------------------------------
 // Test fixtures
@@ -163,7 +162,7 @@ function makeConfig(v2Enabled: boolean): AssistantConfig {
 
 /**
  * Drain all pending async work so any `void`-prefixed promise inside
- * `maybeSeedMemoryV2Skills` settles before the test asserts. The fire-and-
+ * `maybeSeedCapabilitySkills` settles before the test asserts. The fire-and-
  * forget chain involves: dynamic-import settle → `.then` callback →
  * inner `seedV2SkillEntries` resolution → `.catch` settle. Dynamic-import
  * settlement can take a macrotask (not just microtasks), so yield through
@@ -200,18 +199,18 @@ function resetState(): void {
   state.corpusStatsThrows = null;
 }
 
-describe("maybeSeedMemoryV2Skills (daemon startup gate)", () => {
+describe("maybeSeedCapabilitySkills (daemon startup gate)", () => {
   beforeEach(resetState);
 
   test("invokes seedV2SkillEntries when memory.v2.enabled is true", async () => {
-    maybeSeedMemoryV2Skills(makeConfig(true));
+    maybeSeedCapabilitySkills(makeConfig(true));
     await flushMicrotasks();
     expect(state.seedCallCount).toBe(1);
     expect(state.warnCalls).toHaveLength(0);
   });
 
   test("does not invoke seedV2SkillEntries when memory.v2.enabled is false", async () => {
-    maybeSeedMemoryV2Skills(makeConfig(false));
+    maybeSeedCapabilitySkills(makeConfig(false));
     await flushMicrotasks();
     expect(state.seedCallCount).toBe(0);
     expect(state.warnCalls).toHaveLength(0);
@@ -221,7 +220,7 @@ describe("maybeSeedMemoryV2Skills (daemon startup gate)", () => {
     state.seedShouldReject = new Error("seed failed");
 
     // The gate must not throw — startup must not block on this.
-    expect(() => maybeSeedMemoryV2Skills(makeConfig(true))).not.toThrow();
+    expect(() => maybeSeedCapabilitySkills(makeConfig(true))).not.toThrow();
 
     await flushMicrotasks();
 
@@ -233,11 +232,11 @@ describe("maybeSeedMemoryV2Skills (daemon startup gate)", () => {
   });
 });
 
-describe("maybeRebuildMemoryV2Concepts (daemon startup gate)", () => {
+describe("maybeRebuildConceptCollection (daemon startup gate)", () => {
   beforeEach(resetState);
 
   test("does nothing when memory.v2.enabled is false", async () => {
-    await maybeRebuildMemoryV2Concepts(makeConfig(false));
+    await maybeRebuildConceptCollection(makeConfig(false));
 
     expect(state.ensureCollectionCallCount).toBe(0);
     expect(state.enqueueCalls).toEqual([]);
@@ -246,7 +245,7 @@ describe("maybeRebuildMemoryV2Concepts (daemon startup gate)", () => {
   test("enqueues memory_v2_reembed when the collection was migrated", async () => {
     state.ensureCollectionResult = { migrated: true };
 
-    await maybeRebuildMemoryV2Concepts(makeConfig(true));
+    await maybeRebuildConceptCollection(makeConfig(true));
 
     expect(state.ensureCollectionCallCount).toBe(1);
     expect(state.enqueueCalls).toEqual([
@@ -266,7 +265,7 @@ describe("maybeRebuildMemoryV2Concepts (daemon startup gate)", () => {
     state.countResult = 0;
     state.listPagesResult = ["people/alice", "topics/zsh"];
 
-    await maybeRebuildMemoryV2Concepts(makeConfig(true));
+    await maybeRebuildConceptCollection(makeConfig(true));
 
     expect(state.enqueueCalls).toEqual([
       { type: "memory_v2_reembed", payload: {} },
@@ -278,7 +277,7 @@ describe("maybeRebuildMemoryV2Concepts (daemon startup gate)", () => {
     state.countResult = 1185;
     state.listPagesResult = ["people/alice"];
 
-    await maybeRebuildMemoryV2Concepts(makeConfig(true));
+    await maybeRebuildConceptCollection(makeConfig(true));
 
     expect(state.enqueueCalls).toEqual([]);
   });
@@ -288,7 +287,7 @@ describe("maybeRebuildMemoryV2Concepts (daemon startup gate)", () => {
     state.countResult = 0;
     state.listPagesResult = [];
 
-    await maybeRebuildMemoryV2Concepts(makeConfig(true));
+    await maybeRebuildConceptCollection(makeConfig(true));
 
     expect(state.enqueueCalls).toEqual([]);
   });
@@ -299,7 +298,7 @@ describe("maybeRebuildMemoryV2Concepts (daemon startup gate)", () => {
     // Must not throw — startup never blocks on this gate.
     let thrown: unknown = null;
     try {
-      await maybeRebuildMemoryV2Concepts(makeConfig(true));
+      await maybeRebuildConceptCollection(makeConfig(true));
     } catch (err) {
       thrown = err;
     }

package/src/__tests__/list-messages-page-latest.test.ts

@@ -21,6 +21,7 @@ mock.module("../daemon/identity-helpers.js", () => ({
   getAssistantName: () => mockAssistantName,
 }));
 
+import type { AssistantEventEnvelope } from "../api/index.js";
 import { writeSlackMetadata } from "../messaging/providers/slack/message-metadata.js";
 import {
   createConversation,
@@ -31,7 +32,6 @@ import {
 import { getDb } from "../persistence/db-connection.js";
 import { initializeDb } from "../persistence/db-init.js";
 import { messages } from "../persistence/schema/index.js";
-import type { AssistantEvent } from "../runtime/assistant-event.js";
 import {
   _resetStreamStateForTesting,
   getCurrentSeq,
@@ -130,7 +130,7 @@ function advanceGlobalSeq(count: number): void {
         conversationId: "seq-bump-conv",
         text: "x",
       },
-    } as AssistantEvent);
+    } as AssistantEventEnvelope);
   }
 }
 

package/src/__tests__/llm-usage-store.test.ts

@@ -1739,12 +1739,14 @@ describe("queryUnreportedUsageEvents", () => {
   });
 
   // -------------------------------------------------------------------------
-  // Conversation-level metadata (conversationType + turnIndex). These are
-  // JOIN-computed at telemetry-query time so the reporter can emit them on
-  // the wire without persisting extra columns on `llm_usage_events`.
+  // Conversation-level metadata (conversationType + turnIndex).
+  // `conversationType` is stamped on the row at record time (so it survives
+  // deletion of the parent conversation before flush) with a JOIN fallback
+  // for pre-migration rows; `turnIndex` is JOIN-computed at telemetry-query
+  // time.
   // -------------------------------------------------------------------------
 
-  test("conversationType is JOINed from the conversations table", () => {
+  test("conversationType resolves from the conversations table", () => {
     const db = getDb();
     const now = Date.now();
     db.run(
@@ -1766,6 +1768,67 @@ describe("queryUnreportedUsageEvents", () => {
     expect(events[2].conversationType).toBeNull();
   });
 
+  test("conversationType is stamped on the row at record time", () => {
+    const db = getDb();
+    const now = Date.now();
+    db.run(
+      `INSERT INTO conversations (id, conversation_type, created_at, updated_at) VALUES ('conv-stamp', 'background', ${now}, ${now})`,
+    );
+
+    const event = recordUsageEvent(
+      makeInput({ conversationId: "conv-stamp" }),
+      pricedResult,
+    );
+
+    const row = getSqlite()
+      .query("SELECT conversation_type FROM llm_usage_events WHERE id = ?")
+      .get(event.id) as { conversation_type: string | null } | null;
+    expect(row?.conversation_type).toBe("background");
+  });
+
+  test("conversationType survives deletion of the parent conversation before flush", () => {
+    // Reproduces the memory-retrospective NULL-label bug: the retrospective
+    // runs in a `background` fork conversation whose row is GC'd once a
+    // newer run supersedes it (or immediately on wake failure). Usage rows
+    // flushed after that deletion carried a conversation_id but a null
+    // conversation_type, because the type was derived only via a flush-time
+    // JOIN. Same mechanism covers users deleting a standard conversation
+    // within the flush window (the mainAgent NULL case).
+    const db = getDb();
+    const now = Date.now();
+    db.run(
+      `INSERT INTO conversations (id, conversation_type, created_at, updated_at) VALUES ('conv-gone', 'background', ${now}, ${now})`,
+    );
+    insertEventAt(1000, {
+      conversationId: "conv-gone",
+      callSite: "memoryRetrospective",
+    });
+
+    db.run(`DELETE FROM conversations WHERE id = 'conv-gone'`);
+
+    const events = queryUnreportedUsageEvents(0, undefined, 100);
+    expect(events).toHaveLength(1);
+    expect(events[0].conversationId).toBe("conv-gone");
+    expect(events[0].conversationType).toBe("background");
+  });
+
+  test("conversationType falls back to the JOIN for pre-migration rows", () => {
+    const db = getDb();
+    const now = Date.now();
+    db.run(
+      `INSERT INTO conversations (id, conversation_type, created_at, updated_at) VALUES ('conv-legacy', 'scheduled', ${now}, ${now})`,
+    );
+    insertEventAt(1000, { conversationId: "conv-legacy" });
+    // Simulate a row persisted before migration 353 stamped the column.
+    db.run(
+      `UPDATE llm_usage_events SET conversation_type = NULL WHERE conversation_id = 'conv-legacy'`,
+    );
+
+    const events = queryUnreportedUsageEvents(0, undefined, 100);
+    expect(events).toHaveLength(1);
+    expect(events[0].conversationType).toBe("scheduled");
+  });
+
   test("turnIndex counts real user turns up to the LLM call's createdAt", () => {
     const db = getDb();
     const now = Date.now();