@vellumai/assistant 0.3.15 → 0.3.18

package/src/__tests__/ipc-snapshot.test.ts

@@ -727,6 +727,10 @@ const clientMessages: Record<ClientMessageType, ClientMessage> = {
     type: 'heartbeat_checklist_write',
     content: '- [ ] Check email\n- [ ] Review PRs',
   },
+  voice_config_update: {
+    type: 'voice_config_update',
+    activationKey: 'fn',
+  },
 };
 
 // ---------------------------------------------------------------------------
@@ -839,8 +843,8 @@ const serverMessages: Record<ServerMessageType, ServerMessage> = {
   session_list_response: {
     type: 'session_list_response',
     sessions: [
-      { id: 'sess-001', title: 'First session', updatedAt: 1700000000, threadType: 'standard' },
-      { id: 'sess-002', title: 'Second session', updatedAt: 1700001000, threadType: 'standard', assistantAttention: { hasUnseenLatestAssistantMessage: true, latestAssistantMessageAt: 1700001000, lastSeenConfidence: 'explicit', lastSeenSignalType: 'macos_notification_view' } },
+      { id: 'sess-001', title: 'First session', createdAt: 1699999000, updatedAt: 1700000000, threadType: 'standard' },
+      { id: 'sess-002', title: 'Second session', createdAt: 1700000000, updatedAt: 1700001000, threadType: 'standard', assistantAttention: { hasUnseenLatestAssistantMessage: true, latestAssistantMessageAt: 1700001000, lastSeenConfidence: 'explicit', lastSeenSignalType: 'macos_notification_view' } },
     ],
   },
   sessions_clear_response: {
@@ -1775,9 +1779,6 @@ const serverMessages: Record<ServerMessageType, ServerMessage> = {
   tasks_changed: {
     type: 'tasks_changed',
   },
-  open_tasks_window: {
-    type: 'open_tasks_window',
-  },
   task_run_thread_created: {
     type: 'task_run_thread_created',
     conversationId: 'conv-task-run-001',
@@ -2001,6 +2002,23 @@ const serverMessages: Record<ServerMessageType, ServerMessage> = {
     type: 'heartbeat_checklist_write_response',
     success: true,
   },
+  navigate_settings: {
+    type: 'navigate_settings',
+    tab: 'general',
+  },
+  client_settings_update: {
+    type: 'client_settings_update',
+    key: 'activationKey',
+    value: 'fn',
+  },
+  identity_changed: {
+    type: 'identity_changed',
+    name: 'Vellum',
+    role: 'assistant',
+    personality: 'friendly',
+    emoji: '',
+    home: '',
+  },
 };
 
 // ---------------------------------------------------------------------------

package/src/__tests__/media-reuse-story.e2e.test.ts

@@ -188,7 +188,7 @@ describe('Story E2E: selfie yesterday -> generated image today', () => {
   let selfieId: string;
   let selfieAttachment: ReturnType<typeof uploadAttachment>;
 
-  beforeEach(() => {
+  beforeEach(async () => {
     resetTables();
     // Clear sandbox so stale files from prior tests don't mask regressions
     rmSync(sandboxDir, { recursive: true, force: true });
@@ -216,7 +216,7 @@ describe('Story E2E: selfie yesterday -> generated image today', () => {
     selfieAttachment = uploadAttachment('selfie.png', 'image/png', TINY_PNG_BASE64);
     selfieId = selfieAttachment.id;
 
-    const msgA = addMessage(threadA.id, 'user', 'Here is my selfie from yesterday');
+    const msgA = await addMessage(threadA.id, 'user', 'Here is my selfie from yesterday');
     linkAttachmentToMessage(msgA.id, selfieId, 0);
 
     // Backdate the selfie to "yesterday" for realism
@@ -365,7 +365,7 @@ describe('Story E2E: selfie yesterday -> generated image today', () => {
       generatedImageBase64,
     );
 
-    const msgB = addMessage(threadB.id, 'assistant', 'Here is your generated portrait!');
+    const msgB = await addMessage(threadB.id, 'assistant', 'Here is your generated portrait!');
     linkAttachmentToMessage(msgB.id, outputAttachment.id, 0);
 
     // Verify the output attachment exists in the DB via raw search
@@ -475,7 +475,7 @@ describe('Private-thread variant: cross-thread media blocking', () => {
     // Upload selfie in a private thread
     const privateThread = createConversation({ title: 'Private selfie thread', threadType: 'private' });
     const selfie = uploadAttachment('private-selfie.png', 'image/png', TINY_PNG_BASE64);
-    const msg = addMessage(privateThread.id, 'user', 'My private selfie');
+    const msg = await addMessage(privateThread.id, 'user', 'My private selfie');
     linkAttachmentToMessage(msg.id, selfie.id, 0);
 
     // Search from a standard thread
@@ -499,7 +499,7 @@ describe('Private-thread variant: cross-thread media blocking', () => {
     const privateThread = createConversation({ title: 'Private selfie thread', threadType: 'private' });
     const base64 = Buffer.from('private image data').toString('base64');
     const selfie = uploadAttachment('private-selfie.png', 'image/png', base64);
-    const msg = addMessage(privateThread.id, 'user', 'My private selfie');
+    const msg = await addMessage(privateThread.id, 'user', 'My private selfie');
     linkAttachmentToMessage(msg.id, selfie.id, 0);
 
     // Try to materialize from a standard thread
@@ -523,7 +523,7 @@ describe('Private-thread variant: cross-thread media blocking', () => {
   test('selfie in private thread IS accessible from the same private thread', async () => {
     const privateThread = createConversation({ title: 'Private selfie thread', threadType: 'private' });
     const selfie = uploadAttachment('private-selfie.png', 'image/png', TINY_PNG_BASE64);
-    const msg = addMessage(privateThread.id, 'user', 'My private selfie');
+    const msg = await addMessage(privateThread.id, 'user', 'My private selfie');
     linkAttachmentToMessage(msg.id, selfie.id, 0);
 
     // Search from the same private thread
@@ -552,7 +552,7 @@ describe('Private-thread variant: cross-thread media blocking', () => {
   test('selfie in private thread A is NOT accessible from private thread B', async () => {
     const privateThreadA = createConversation({ title: 'Private thread A', threadType: 'private' });
     const selfie = uploadAttachment('thread-a-selfie.png', 'image/png', TINY_PNG_BASE64);
-    const msgA = addMessage(privateThreadA.id, 'user', 'Selfie in thread A');
+    const msgA = await addMessage(privateThreadA.id, 'user', 'Selfie in thread A');
     linkAttachmentToMessage(msgA.id, selfie.id, 0);
 
     // Search from a different private thread

package/src/__tests__/memory-regressions.test.ts

@@ -3577,11 +3577,11 @@ describe('Memory regressions', () => {
   });
 
   // PR-17: addMessage() passes conversation scope to the indexer
-  test('addMessage inherits private conversation scope on memory segments', () => {
+  test('addMessage inherits private conversation scope on memory segments', async () => {
     const conv = createConversation({ title: 'Private thread', threadType: 'private' });
     expect(conv.memoryScopeId).toMatch(/^private:/);
 
-    const msg = addMessage(conv.id, 'user', 'My secret project details for the private thread.');
+    const msg = await addMessage(conv.id, 'user', 'My secret project details for the private thread.');
 
     const db = getDb();
     const segments = db
@@ -3596,11 +3596,11 @@ describe('Memory regressions', () => {
     }
   });
 
-  test('addMessage uses default scope for standard conversations', () => {
+  test('addMessage uses default scope for standard conversations', async () => {
     const conv = createConversation({ title: 'Standard thread', threadType: 'standard' });
     expect(conv.memoryScopeId).toBe('default');
 
-    const msg = addMessage(conv.id, 'user', 'Normal conversation content for testing scope defaults.');
+    const msg = await addMessage(conv.id, 'user', 'Normal conversation content for testing scope defaults.');
 
     const db = getDb();
     const segments = db
@@ -3910,6 +3910,7 @@ describe('Memory regressions', () => {
       deferrals: 0,
       runAfter: 0,
       lastError: null,
+      startedAt: Date.now(),
       createdAt: Date.now(),
       updatedAt: Date.now(),
     };
@@ -3958,7 +3959,7 @@ describe('Memory regressions', () => {
       payload: { conversationId: privConv.id },
       status: 'running' as const,
       attempts: 0, deferrals: 0, runAfter: 0, lastError: null,
-      createdAt: now, updatedAt: now,
+      startedAt: now, createdAt: now, updatedAt: now,
     }, TEST_CONFIG);
 
     // Create a standard conversation and build its summary
@@ -3990,7 +3991,7 @@ describe('Memory regressions', () => {
       payload: { conversationId: stdConv.id },
       status: 'running' as const,
       attempts: 0, deferrals: 0, runAfter: 0, lastError: null,
-      createdAt: now, updatedAt: now,
+      startedAt: now, createdAt: now, updatedAt: now,
     }, TEST_CONFIG);
 
     // Query summaries scoped to 'default' — should only include the standard one
@@ -4018,7 +4019,7 @@ describe('Memory regressions', () => {
     const privScope = getConversationMemoryScopeId(privConv.id);
     expect(privScope).toMatch(/^private:/);
 
-    const privMsg = addMessage(
+    const privMsg = await addMessage(
       privConv.id,
       'user',
       'I prefer using the Zephyr framework for all backend microservices.',
@@ -4095,7 +4096,7 @@ describe('Memory regressions', () => {
     const stdScope = getConversationMemoryScopeId(stdConv.id);
     expect(stdScope).toBe('default');
 
-    const stdMsg = addMessage(
+    const stdMsg = await addMessage(
       stdConv.id,
       'user',
       'I prefer using the Obsidian editor for all my note-taking workflows.',
@@ -4417,6 +4418,7 @@ describe('Memory regressions', () => {
       deferrals: 0,
       runAfter: 0,
       lastError: null,
+      startedAt: Date.now(),
       createdAt: Date.now(),
       updatedAt: Date.now(),
     };
@@ -4461,6 +4463,7 @@ describe('Memory regressions', () => {
       deferrals: 0,
       runAfter: 0,
       lastError: null,
+      startedAt: Date.now(),
       createdAt: Date.now(),
       updatedAt: Date.now(),
     };
@@ -4535,6 +4538,7 @@ describe('Memory regressions', () => {
         deferrals: 0,
         runAfter: 0,
         lastError: null,
+        startedAt: Date.now(),
         createdAt: Date.now(),
         updatedAt: Date.now(),
       };
@@ -4558,7 +4562,7 @@ describe('Memory regressions', () => {
 
   // ── Provenance plumbing tests ────────────────────────────────────────
 
-  test('provenance fields are preserved in stored message metadata', () => {
+  test('provenance fields are preserved in stored message metadata', async () => {
     const conv = createConversation('provenance-preserve');
     const metadata = {
       userMessageChannel: 'telegram' as const,
@@ -4567,7 +4571,7 @@ describe('Memory regressions', () => {
       provenanceGuardianExternalUserId: 'guardian-123',
       provenanceRequesterIdentifier: 'Alice',
     };
-    const msg = addMessage(conv.id, 'user', 'Hello from telegram', metadata);
+    const msg = await addMessage(conv.id, 'user', 'Hello from telegram', metadata);
 
     const db = getDb();
     const stored = db
@@ -4628,7 +4632,7 @@ describe('Memory regressions', () => {
     expect(result.provenanceRequesterIdentifier).toBe('Charlie');
   });
 
-  test('indexMessageNow receives provenanceActorRole when metadata includes it', () => {
+  test('indexMessageNow receives provenanceActorRole when metadata includes it', async () => {
     const conv = createConversation('provenance-indexer');
     const metadata = {
       provenanceActorRole: 'non-guardian' as const,
@@ -4636,7 +4640,7 @@ describe('Memory regressions', () => {
     };
     // addMessage parses metadata and passes provenanceActorRole to indexMessageNow.
     // We verify indirectly: the message is persisted with metadata and segments are indexed.
-    const msg = addMessage(conv.id, 'user', 'Test provenance indexing message with enough content to segment', metadata);
+    const msg = await addMessage(conv.id, 'user', 'Test provenance indexing message with enough content to segment', metadata);
     expect(msg.id).toBeTruthy();
 
     // Verify segments were created (indexMessageNow was called successfully)

package/src/__tests__/non-member-access-request.test.ts

@@ -0,0 +1,281 @@
+/**
+ * Tests for the non-member access request notification flow.
+ *
+ * When a non-member messages the assistant on a channel, the system should:
+ * 1. Deny the message with the standard rejection reply
+ * 2. Notify the guardian (if a guardian binding exists)
+ * 3. Create a guardian approval request for the access request
+ * 4. Deduplicate: don't create duplicate requests for repeated messages
+ */
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterAll, beforeEach, describe, expect, mock, test } from 'bun:test';
+
+// ---------------------------------------------------------------------------
+// Test isolation: in-memory SQLite via temp directory
+// ---------------------------------------------------------------------------
+
+const testDir = mkdtempSync(join(tmpdir(), 'non-member-access-request-test-'));
+
+mock.module('../util/platform.js', () => ({
+  getRootDir: () => testDir,
+  getDataDir: () => testDir,
+  isMacOS: () => process.platform === 'darwin',
+  isLinux: () => process.platform === 'linux',
+  isWindows: () => process.platform === 'win32',
+  getSocketPath: () => join(testDir, 'test.sock'),
+  getPidPath: () => join(testDir, 'test.pid'),
+  getDbPath: () => join(testDir, 'test.db'),
+  getLogPath: () => join(testDir, 'test.log'),
+  ensureDataDir: () => {},
+  normalizeAssistantId: (id: string) => id === 'self' ? 'self' : id,
+  readHttpToken: () => 'test-bearer-token',
+}));
+
+mock.module('../util/logger.js', () => ({
+  getLogger: () => new Proxy({} as Record<string, unknown>, {
+    get: () => () => {},
+  }),
+}));
+
+// Mock security check to always pass
+mock.module('../security/secret-ingress.js', () => ({
+  checkIngressForSecrets: () => ({ blocked: false }),
+}));
+
+// Mock ingress member store: findMember always returns null (non-member),
+// updateLastSeen is a no-op.
+mock.module('../memory/ingress-member-store.js', () => ({
+  findMember: () => null,
+  updateLastSeen: () => {},
+  upsertMember: () => {},
+}));
+
+mock.module('../config/env.js', () => ({
+  getGatewayInternalBaseUrl: () => 'http://127.0.0.1:7830',
+}));
+
+// Track emitNotificationSignal calls
+const emitSignalCalls: Array<Record<string, unknown>> = [];
+mock.module('../notifications/emit-signal.js', () => ({
+  emitNotificationSignal: async (params: Record<string, unknown>) => {
+    emitSignalCalls.push(params);
+    return {
+      signalId: 'mock-signal-id',
+      deduplicated: false,
+      dispatched: true,
+      reason: 'mock',
+      deliveryResults: [],
+    };
+  },
+}));
+
+// Track deliverChannelReply calls
+const deliverReplyCalls: Array<{ url: string; payload: Record<string, unknown> }> = [];
+mock.module('../runtime/gateway-client.js', () => ({
+  deliverChannelReply: async (url: string, payload: Record<string, unknown>) => {
+    deliverReplyCalls.push({ url, payload });
+  },
+}));
+
+import {
+  createBinding,
+  findPendingAccessRequestForRequester,
+} from '../memory/channel-guardian-store.js';
+import { getDb, initializeDb, resetDb } from '../memory/db.js';
+import { handleChannelInbound } from '../runtime/routes/channel-routes.js';
+
+initializeDb();
+
+afterAll(() => {
+  resetDb();
+  try { rmSync(testDir, { recursive: true }); } catch { /* best effort */ }
+});
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const TEST_BEARER_TOKEN = 'test-token';
+
+function resetState(): void {
+  const db = getDb();
+  db.run('DELETE FROM channel_guardian_approval_requests');
+  db.run('DELETE FROM channel_guardian_bindings');
+  db.run('DELETE FROM channel_inbound_events');
+  db.run('DELETE FROM conversations');
+  db.run('DELETE FROM notification_events');
+  emitSignalCalls.length = 0;
+  deliverReplyCalls.length = 0;
+}
+
+function buildInboundRequest(overrides: Record<string, unknown> = {}): Request {
+  const body: Record<string, unknown> = {
+    sourceChannel: 'telegram',
+    interface: 'telegram',
+    externalChatId: 'chat-123',
+    externalMessageId: `msg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    content: 'Hello, can I use this assistant?',
+    senderExternalUserId: 'user-unknown-456',
+    senderName: 'Alice Unknown',
+    senderUsername: 'alice_unknown',
+    replyCallbackUrl: 'http://localhost:7830/deliver/telegram',
+    ...overrides,
+  };
+
+  return new Request('http://localhost:8080/channels/inbound', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-Gateway-Origin': TEST_BEARER_TOKEN,
+    },
+    body: JSON.stringify(body),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('non-member access request notification', () => {
+  beforeEach(() => {
+    resetState();
+  });
+
+  test('non-member message is denied with rejection reply', async () => {
+    const req = buildInboundRequest();
+    const resp = await handleChannelInbound(req, undefined, TEST_BEARER_TOKEN);
+    const json = await resp.json() as Record<string, unknown>;
+
+    expect(json.denied).toBe(true);
+    expect(json.reason).toBe('not_a_member');
+
+    // Rejection reply was delivered
+    expect(deliverReplyCalls.length).toBe(1);
+    expect((deliverReplyCalls[0].payload as Record<string, unknown>).text).toContain("you haven't been approved");
+  });
+
+  test('guardian is notified when a non-member messages and a guardian binding exists', async () => {
+    // Set up a guardian binding for this channel
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'guardian-user-789',
+      guardianDeliveryChatId: 'guardian-chat-789',
+    });
+
+    const req = buildInboundRequest();
+    const resp = await handleChannelInbound(req, undefined, TEST_BEARER_TOKEN);
+    const json = await resp.json() as Record<string, unknown>;
+
+    // Message is still denied
+    expect(json.denied).toBe(true);
+    expect(json.reason).toBe('not_a_member');
+
+    // Rejection reply was delivered
+    expect(deliverReplyCalls.length).toBe(1);
+
+    // A notification signal was emitted
+    expect(emitSignalCalls.length).toBe(1);
+    expect(emitSignalCalls[0].sourceEventName).toBe('ingress.access_request');
+    expect(emitSignalCalls[0].sourceChannel).toBe('telegram');
+    const payload = emitSignalCalls[0].contextPayload as Record<string, unknown>;
+    expect(payload.senderExternalUserId).toBe('user-unknown-456');
+    expect(payload.senderName).toBe('Alice Unknown');
+
+    // An approval request was created
+    const pending = findPendingAccessRequestForRequester(
+      'self',
+      'telegram',
+      'user-unknown-456',
+      'ingress_access_request',
+    );
+    expect(pending).not.toBeNull();
+    expect(pending!.status).toBe('pending');
+    expect(pending!.requesterExternalUserId).toBe('user-unknown-456');
+    expect(pending!.guardianExternalUserId).toBe('guardian-user-789');
+    expect(pending!.toolName).toBe('ingress_access_request');
+  });
+
+  test('no duplicate approval requests for repeated messages from same non-member', async () => {
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'guardian-user-789',
+      guardianDeliveryChatId: 'guardian-chat-789',
+    });
+
+    // First message
+    const req1 = buildInboundRequest();
+    await handleChannelInbound(req1, undefined, TEST_BEARER_TOKEN);
+
+    // Second message from the same user
+    const req2 = buildInboundRequest({
+      externalMessageId: `msg-second-${Date.now()}`,
+      content: 'Please let me in!',
+    });
+    await handleChannelInbound(req2, undefined, TEST_BEARER_TOKEN);
+
+    // Both messages should be denied with rejection replies
+    expect(deliverReplyCalls.length).toBe(2);
+
+    // Only one notification signal should be emitted (second is deduplicated)
+    expect(emitSignalCalls.length).toBe(1);
+
+    // Only one approval request should exist
+    const pending = findPendingAccessRequestForRequester(
+      'self',
+      'telegram',
+      'user-unknown-456',
+      'ingress_access_request',
+    );
+    expect(pending).not.toBeNull();
+  });
+
+  test('deny works without error when no guardian binding exists', async () => {
+    // No guardian binding — should deny without notification
+    const req = buildInboundRequest();
+    const resp = await handleChannelInbound(req, undefined, TEST_BEARER_TOKEN);
+    const json = await resp.json() as Record<string, unknown>;
+
+    expect(json.denied).toBe(true);
+    expect(json.reason).toBe('not_a_member');
+
+    // Rejection reply was still delivered
+    expect(deliverReplyCalls.length).toBe(1);
+
+    // No notification signal was emitted
+    expect(emitSignalCalls.length).toBe(0);
+
+    // No approval request was created
+    const pending = findPendingAccessRequestForRequester(
+      'self',
+      'telegram',
+      'user-unknown-456',
+      'ingress_access_request',
+    );
+    expect(pending).toBeNull();
+  });
+
+  test('no notification when senderExternalUserId is absent', async () => {
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'guardian-user-789',
+      guardianDeliveryChatId: 'guardian-chat-789',
+    });
+
+    // Message without senderExternalUserId — can't identify the requester.
+    // The ACL check requires senderExternalUserId to look up members,
+    // so without it the non-member gate is bypassed entirely.
+    const req = buildInboundRequest({
+      senderExternalUserId: undefined,
+    });
+    await handleChannelInbound(req, undefined, TEST_BEARER_TOKEN);
+
+    // No access request notification should fire (no identity to notify about)
+    expect(emitSignalCalls.length).toBe(0);
+  });
+});

package/src/__tests__/notification-broadcaster.test.ts

@@ -6,6 +6,8 @@
  * - Handles missing adapters gracefully
  * - Falls back to copy-composer when decision copy is missing
  * - Reports delivery results per channel
+ * - Emits notification_thread_created only when a new conversation is created
+ * - Does NOT emit notification_thread_created when reusing an existing thread
  */
 
 import { describe, expect, mock, test } from 'bun:test';
@@ -36,6 +38,32 @@ mock.module('../notifications/deliveries-store.js', () => ({
   updateDeliveryStatus: () => {},
 }));
 
+// Configurable mock for conversation-pairing.
+// By default returns a "new conversation" result with a stable UUID.
+// Set `nextPairingResult` to override the return value for a single call.
+let nextPairingResult: import('../notifications/conversation-pairing.js').PairingResult | null = null;
+let pairingCallCount = 0;
+
+mock.module('../notifications/conversation-pairing.js', () => ({
+  pairDeliveryWithConversation: async () => {
+    if (nextPairingResult) {
+      const result = nextPairingResult;
+      nextPairingResult = null;
+      return result;
+    }
+    // Default: simulate creating a new conversation with a unique ID
+    const id = `mock-conv-${++pairingCallCount}`;
+    return {
+      conversationId: id,
+      messageId: `mock-msg-${pairingCallCount}`,
+      strategy: 'start_new_conversation' as const,
+      createdNewConversation: true,
+      threadDecisionFallbackUsed: false,
+    };
+  },
+}));
+
+import type { ThreadCreatedInfo } from '../notifications/broadcaster.js';
 import { NotificationBroadcaster } from '../notifications/broadcaster.js';
 import type { NotificationSignal } from '../notifications/signal.js';
 import type {
@@ -167,10 +195,17 @@ describe('notification broadcaster', () => {
     await broadcaster.broadcastDecision(signal, decision);
 
     expect(vellumAdapter.sent).toHaveLength(1);
-    expect(vellumAdapter.sent[0].deepLinkTarget).toEqual({
-      conversationId: 'conv-123',
-      screen: 'thread',
-    });
+    // The broadcaster overwrites deepLinkTarget.conversationId with the
+    // paired conversation ID, so the original 'conv-123' is replaced.
+    // Verify the structure is correct and that conversationId comes from
+    // the pairing result, not the pre-pairing placeholder.
+    const deepLink = vellumAdapter.sent[0].deepLinkTarget;
+    expect(deepLink).toBeDefined();
+    expect(deepLink!.screen).toBe('thread');
+    expect(deepLink!.conversationId).toBeDefined();
+    expect(deepLink!.conversationId).not.toBe('conv-123');
+    // Should be the paired conversation ID from conversation-pairing
+    expect(deepLink!.conversationId).toMatch(/^mock-conv-\d+$/);
   });
 
   test('multiple channels receive independent copy from the decision', async () => {
@@ -253,4 +288,80 @@ describe('notification broadcaster', () => {
     expect(results).toHaveLength(0);
     expect(vellumAdapter.sent).toHaveLength(0);
   });
+
+  // ── Thread-created IPC emission ─────────────────────────────────────
+
+  test('fires onThreadCreated when a new vellum conversation is created (start_new)', async () => {
+    const vellumAdapter = new MockAdapter('vellum');
+    const broadcaster = new NotificationBroadcaster([vellumAdapter]);
+    const threadCreatedCalls: ThreadCreatedInfo[] = [];
+    broadcaster.setOnThreadCreated((info) => threadCreatedCalls.push(info));
+
+    const signal = makeSignal();
+    // No threadActions means default start_new behavior
+    const decision = makeDecision();
+
+    await broadcaster.broadcastDecision(signal, decision);
+
+    // Pairing creates a new conversation by default, so onThreadCreated should fire
+    expect(threadCreatedCalls).toHaveLength(1);
+    expect(threadCreatedCalls[0].sourceEventName).toBe('test.event');
+  });
+
+  test('fires per-dispatch onThreadCreated callback on new conversation', async () => {
+    const vellumAdapter = new MockAdapter('vellum');
+    const broadcaster = new NotificationBroadcaster([vellumAdapter]);
+    const dispatchCalls: ThreadCreatedInfo[] = [];
+
+    const signal = makeSignal();
+    const decision = makeDecision();
+
+    await broadcaster.broadcastDecision(signal, decision, {
+      onThreadCreated: (info) => dispatchCalls.push(info),
+    });
+
+    expect(dispatchCalls).toHaveLength(1);
+  });
+
+  test('does NOT fire class-level onThreadCreated when reusing an existing thread', async () => {
+    const vellumAdapter = new MockAdapter('vellum');
+    const broadcaster = new NotificationBroadcaster([vellumAdapter]);
+    const ipcCalls: ThreadCreatedInfo[] = [];
+    const dispatchCalls: ThreadCreatedInfo[] = [];
+    broadcaster.setOnThreadCreated((info) => ipcCalls.push(info));
+
+    // Simulate a successful reuse by injecting a pairing result with
+    // createdNewConversation=false. This bypasses the real conversation
+    // store (which would fall back to creating a new conversation since
+    // the target does not exist in the test DB).
+    nextPairingResult = {
+      conversationId: 'conv-reused-456',
+      messageId: 'msg-reused-789',
+      strategy: 'start_new_conversation',
+      createdNewConversation: false,
+      threadDecisionFallbackUsed: false,
+    };
+
+    const signal = makeSignal();
+    const decision = makeDecision({
+      threadActions: {
+        vellum: { action: 'reuse_existing', conversationId: 'conv-existing-123' },
+      },
+    });
+
+    await broadcaster.broadcastDecision(signal, decision, {
+      onThreadCreated: (info) => dispatchCalls.push(info),
+    });
+
+    // The class-level IPC callback should NOT fire because
+    // createdNewConversation is false — the client already knows about
+    // the reused conversation.
+    expect(ipcCalls).toHaveLength(0);
+
+    // The per-dispatch callback SHOULD fire for both new and reused
+    // pairings (used by callers like dispatchGuardianQuestion for
+    // delivery bookkeeping).
+    expect(dispatchCalls).toHaveLength(1);
+    expect(dispatchCalls[0].conversationId).toBe('conv-reused-456');
+  });
 });