@vellumai/assistant 0.4.5 → 0.4.7

package/src/__tests__/channel-delivery-store.test.ts

@@ -508,7 +508,7 @@ describe('channel-delivery-store', () => {
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({
         sourceChannel: 'telegram',
-        externalChatId: 'chat-del',
+        conversationExternalId: 'chat-del',
         // Note: no assistantId in the body — it comes from the route param
       }),
     });
@@ -558,7 +558,7 @@ describe('channel-delivery-store', () => {
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({
         sourceChannel: 'telegram',
-        externalChatId: 'chat-def',
+        conversationExternalId: 'chat-def',
       }),
     });
 

package/src/__tests__/confirmation-request-guardian-bridge.test.ts

@@ -118,6 +118,7 @@ function makeCanonicalRequest(overrides: Record<string, unknown> = {}) {
     conversationId: 'conv-1',
     requesterExternalUserId: 'requester-1',
     guardianExternalUserId: 'guardian-1',
+    guardianPrincipalId: 'test-principal-id',
     toolName: 'bash',
     status: 'pending',
     requestCode: generateCanonicalRequestCode(),

package/src/__tests__/conversation-attention-telegram.test.ts

@@ -119,8 +119,8 @@ function makeInboundRequest(overrides: Record<string, unknown> = {}): Request {
   const body = {
     sourceChannel: 'telegram',
     interface: 'telegram',
-    externalChatId: 'chat-123',
-    senderExternalUserId: 'telegram-user-default',
+    conversationExternalId: 'chat-123',
+    actorExternalId: 'telegram-user-default',
     externalMessageId: `msg-${Date.now()}-${Math.random()}`,
     content: 'hello',
     replyCallbackUrl: 'https://gateway.test/deliver',

package/src/__tests__/deterministic-verification-control-plane.test.ts

@@ -257,11 +257,11 @@ describe('Verification control messages are deterministic (guard)', () => {
         body: JSON.stringify({
           sourceChannel: 'telegram',
           interface: 'telegram',
-          externalChatId: 'chat-123',
+          conversationExternalId: 'chat-123',
           externalMessageId: `msg-guard-${Date.now()}`,
           content: secret,
-          senderExternalUserId: 'user-123',
-          senderName: 'Test User',
+          actorExternalId: 'user-123',
+          actorDisplayName: 'Test User',
           replyCallbackUrl: 'http://localhost/callback',
         }),
       });
@@ -330,11 +330,11 @@ describe('Verification control messages are deterministic (guard)', () => {
         body: JSON.stringify({
           sourceChannel: 'telegram',
           interface: 'telegram',
-          externalChatId: 'chat-bootstrap-123',
+          conversationExternalId: 'chat-bootstrap-123',
           externalMessageId: `msg-bootstrap-${Date.now()}`,
           content: `/start gv_${bootstrapToken}`,
-          senderExternalUserId: 'user-bootstrap-123',
-          senderName: 'Bootstrap User',
+          actorExternalId: 'user-bootstrap-123',
+          actorDisplayName: 'Bootstrap User',
           replyCallbackUrl: 'http://localhost/callback',
           sourceMetadata: {
             commandIntent: { type: 'start', payload: `gv_${bootstrapToken}` },

package/src/__tests__/gateway-client-managed-outbound.test.ts

@@ -0,0 +1,147 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';
+
+import { deliverChannelReply } from '../runtime/gateway-client.js';
+
+type FetchCall = {
+  url: string;
+  init: RequestInit;
+};
+
+describe('gateway-client managed outbound lane', () => {
+  const originalFetch = globalThis.fetch;
+  const calls: FetchCall[] = [];
+
+  beforeEach(() => {
+    calls.length = 0;
+    globalThis.fetch = mock(async (input: string | URL | Request, init?: RequestInit) => {
+      const url = typeof input === 'string'
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : input.url;
+      calls.push({ url, init: init ?? {} });
+      return new Response(JSON.stringify({ status: 'accepted' }), { status: 202 });
+    }) as unknown as typeof globalThis.fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  test('translates managed callback URL into managed outbound-send request', async () => {
+    await deliverChannelReply(
+      'https://platform.test/v1/internal/managed-gateway/outbound-send/?route_id=route-123&assistant_id=assistant-123&source_channel=sms&source_update_id=SM-inbound-123&callback_token=runtime-token',
+      {
+        chatId: '+15550001111',
+        text: 'hello from runtime',
+      },
+    );
+
+    expect(calls).toHaveLength(1);
+    const call = calls[0];
+    expect(call.url).toBe('https://platform.test/v1/internal/managed-gateway/outbound-send/');
+
+    const headers = call.init.headers as Record<string, string>;
+    expect(headers['Content-Type']).toBe('application/json');
+    expect(headers['X-Managed-Gateway-Callback-Token']).toBe('runtime-token');
+    expect(headers['X-Idempotency-Key']).toStartWith('mgw-send-');
+    expect(headers.Authorization).toBeUndefined();
+
+    const body = JSON.parse(String(call.init.body)) as {
+      route_id: string;
+      assistant_id: string;
+      normalized_send: {
+        sourceChannel: string;
+        message: {
+          to: string;
+          content: string;
+          externalMessageId: string;
+        };
+        source: {
+          requestId: string;
+        };
+        raw: {
+          sourceUpdateId: string;
+        };
+      };
+    };
+    expect(body.route_id).toBe('route-123');
+    expect(body.assistant_id).toBe('assistant-123');
+    expect(body.normalized_send.sourceChannel).toBe('sms');
+    expect(body.normalized_send.message.to).toBe('+15550001111');
+    expect(body.normalized_send.message.content).toBe('hello from runtime');
+    expect(body.normalized_send.message.externalMessageId).toStartWith('mgw-send-');
+    expect(body.normalized_send.source.requestId).toBe(
+      body.normalized_send.message.externalMessageId,
+    );
+    expect(body.normalized_send.raw.sourceUpdateId).toBe('SM-inbound-123');
+  });
+
+  test('retries managed outbound send on retriable upstream responses with stable idempotency key', async () => {
+    calls.length = 0;
+    let attempt = 0;
+    globalThis.fetch = mock(async (input: string | URL | Request, init?: RequestInit) => {
+      const url = typeof input === 'string'
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : input.url;
+      calls.push({ url, init: init ?? {} });
+      attempt += 1;
+      if (attempt === 1) {
+        return new Response('temporary upstream error', { status: 502 });
+      }
+      return new Response(JSON.stringify({ status: 'accepted' }), { status: 202 });
+    }) as unknown as typeof globalThis.fetch;
+
+    await deliverChannelReply(
+      'https://platform.test/v1/internal/managed-gateway/outbound-send/?route_id=route-retry&assistant_id=assistant-retry&source_channel=sms&source_update_id=SM-retry',
+      {
+        chatId: '+15550002222',
+        text: 'retry this outbound send',
+      },
+    );
+
+    expect(calls).toHaveLength(2);
+
+    const firstHeaders = calls[0].init.headers as Record<string, string>;
+    const secondHeaders = calls[1].init.headers as Record<string, string>;
+    expect(firstHeaders['X-Idempotency-Key']).toBeDefined();
+    expect(secondHeaders['X-Idempotency-Key']).toBe(firstHeaders['X-Idempotency-Key']);
+
+    const firstBody = JSON.parse(String(calls[0].init.body)) as {
+      normalized_send: { source: { requestId: string } };
+    };
+    const secondBody = JSON.parse(String(calls[1].init.body)) as {
+      normalized_send: { source: { requestId: string } };
+    };
+    expect(secondBody.normalized_send.source.requestId).toBe(
+      firstBody.normalized_send.source.requestId,
+    );
+  });
+
+  test('falls back to standard callback delivery for non-managed callback URL', async () => {
+    await deliverChannelReply(
+      'https://gateway.test/deliver/sms',
+      {
+        chatId: '+15550001111',
+        text: 'standard gateway callback',
+      },
+      'runtime-bearer',
+    );
+
+    expect(calls).toHaveLength(1);
+    const call = calls[0];
+    expect(call.url).toBe('https://gateway.test/deliver/sms');
+
+    const headers = call.init.headers as Record<string, string>;
+    expect(headers['Content-Type']).toBe('application/json');
+    expect(headers.Authorization).toBe('Bearer runtime-bearer');
+
+    const body = JSON.parse(String(call.init.body)) as { chatId: string; text: string };
+    expect(body).toEqual({
+      chatId: '+15550001111',
+      text: 'standard gateway callback',
+    });
+  });
+});

package/src/__tests__/guardian-actions-endpoint.test.ts

@@ -94,6 +94,7 @@ function createTestCanonicalRequest(overrides: {
   kind?: string;
   toolName?: string;
   guardianExternalUserId?: string;
+  guardianPrincipalId?: string;
   questionText?: string;
   expiresAt?: string;
 }) {
@@ -105,6 +106,7 @@ function createTestCanonicalRequest(overrides: {
     sourceChannel: 'vellum',
     conversationId: overrides.conversationId,
     guardianExternalUserId: overrides.guardianExternalUserId,
+    guardianPrincipalId: overrides.guardianPrincipalId ?? 'test-principal',
     toolName: overrides.toolName ?? 'bash',
     questionText: overrides.questionText,
     requestCode: generateCanonicalRequestCode(),
@@ -304,7 +306,7 @@ describe('HTTP handleGuardianActionDecision', () => {
     expect(body.requestId).toBe('req-stale-1');
   });
 
-  test('passes actorContext with undefined externalUserId (unauthenticated endpoint)', async () => {
+  test('passes actorContext with vellum channel and guardianPrincipalId', async () => {
     createTestCanonicalRequest({ conversationId: 'conv-actor', requestId: 'req-actor-1' });
     mockApplyCanonicalGuardianDecision.mockResolvedValueOnce({ applied: true, requestId: 'req-actor-1', grantMinted: false });
 
@@ -315,9 +317,8 @@ describe('HTTP handleGuardianActionDecision', () => {
     await handleGuardianActionDecision(req, mockLoopbackServer);
     const call = mockApplyCanonicalGuardianDecision.mock.calls[0]![0] as Record<string, unknown>;
     const actorContext = call.actorContext as Record<string, unknown>;
-    expect(actorContext.externalUserId).toBeUndefined();
     expect(actorContext.channel).toBe('vellum');
-    expect(actorContext.isTrusted).toBe(true);
+    expect(actorContext.guardianPrincipalId).toBeDefined();
   });
 });
 
@@ -373,6 +374,7 @@ describe('listGuardianDecisionPrompts', () => {
       sourceType: 'desktop',
       sourceChannel: 'vellum',
       conversationId: 'conv-expired',
+      guardianPrincipalId: 'test-principal',
       toolName: 'bash',
       requestCode: generateCanonicalRequestCode(),
       status: 'pending',
@@ -597,7 +599,7 @@ describe('IPC guardian_action_decision', () => {
     expect(sent[0].reason).toBe('already_resolved');
   });
 
-  test('passes actorContext with undefined externalUserId (unauthenticated endpoint)', async () => {
+  test('passes actorContext with vellum channel and guardianPrincipalId', async () => {
     createTestCanonicalRequest({ conversationId: 'conv-ipc-actor', requestId: 'req-ipc-actor' });
     mockApplyCanonicalGuardianDecision.mockResolvedValueOnce({ applied: true, requestId: 'req-ipc-actor', grantMinted: false });
 
@@ -609,9 +611,8 @@ describe('IPC guardian_action_decision', () => {
     );
     const call = mockApplyCanonicalGuardianDecision.mock.calls[0]![0] as Record<string, unknown>;
     const actorContext = call.actorContext as Record<string, unknown>;
-    expect(actorContext.externalUserId).toBeUndefined();
     expect(actorContext.channel).toBe('vellum');
-    expect(actorContext.isTrusted).toBe(true);
+    expect(actorContext.guardianPrincipalId).toBeDefined();
   });
 });
 

package/src/__tests__/guardian-decision-primitive-canonical.test.ts

@@ -64,11 +64,14 @@ afterAll(() => {
 // Helpers
 // ---------------------------------------------------------------------------
 
+/** Consistent test principal used across all test actors and requests. */
+const TEST_PRINCIPAL_ID = 'test-principal-id';
+
 function guardianActor(overrides: Partial<ActorContext> = {}): ActorContext {
   return {
     externalUserId: 'guardian-1',
     channel: 'telegram',
-    isTrusted: false,
+    guardianPrincipalId: TEST_PRINCIPAL_ID,
     ...overrides,
   };
 }
@@ -77,7 +80,7 @@ function trustedActor(overrides: Partial<ActorContext> = {}): ActorContext {
   return {
     externalUserId: undefined,
     channel: 'desktop',
-    isTrusted: true,
+    guardianPrincipalId: TEST_PRINCIPAL_ID,
     ...overrides,
   };
 }
@@ -120,6 +123,7 @@ describe('applyCanonicalGuardianDecision', () => {
       sourceChannel: 'telegram',
       conversationId: 'conv-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       toolName: 'shell',
       inputDigest: 'sha256:abc',
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
@@ -153,6 +157,7 @@ describe('applyCanonicalGuardianDecision', () => {
       sourceChannel: 'telegram',
       conversationId: 'conv-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       toolName: 'shell',
       inputDigest: 'sha256:abc',
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
@@ -178,6 +183,7 @@ describe('applyCanonicalGuardianDecision', () => {
       sourceType: 'voice',
       sourceChannel: 'twilio',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       callSessionId: 'call-1',
       pendingQuestionId: 'pq-1',
       questionText: 'What is the gate code?',
@@ -199,21 +205,22 @@ describe('applyCanonicalGuardianDecision', () => {
     expect(resolved!.answerText).toBe('1234');
   });
 
-  // ── Identity mismatch ──────────────────────────────────────────────
+  // ── Principal mismatch ──────────────────────────────────────────────
 
-  test('rejects decision when actor does not match guardian', async () => {
+  test('rejects decision when actor principal does not match request principal', async () => {
     const req = createCanonicalGuardianRequest({
       kind: 'tool_approval',
       sourceType: 'channel',
       conversationId: 'conv-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
     });
 
     const result = await applyCanonicalGuardianDecision({
       requestId: req.id,
       action: 'approve_once',
-      actorContext: guardianActor({ externalUserId: 'imposter-99' }),
+      actorContext: guardianActor({ guardianPrincipalId: 'wrong-principal' }),
     });
 
     expect(result.applied).toBe(false);
@@ -225,12 +232,13 @@ describe('applyCanonicalGuardianDecision', () => {
     expect(unchanged!.status).toBe('pending');
   });
 
-  test('trusted actor bypasses identity check', async () => {
+  test('matching principal authorizes decision (cross-channel same principal)', async () => {
     const req = createCanonicalGuardianRequest({
       kind: 'tool_approval',
       sourceType: 'desktop',
       conversationId: 'conv-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       toolName: 'shell',
       inputDigest: 'sha256:abc',
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
@@ -243,24 +251,48 @@ describe('applyCanonicalGuardianDecision', () => {
     });
 
     expect(result.applied).toBe(true);
-    // No grant minted because trusted actor has no externalUserId
     if (!result.applied) return;
+    // No grant minted because trusted actor has no externalUserId
     expect(result.grantMinted).toBe(false);
   });
 
-  test('rejects non-trusted decision when tool approval has no guardian binding', async () => {
+  test('rejects decision when request has no guardianPrincipalId', async () => {
+    // unknown_kind is not in DECISIONABLE_KINDS so it can be created without
+    // guardianPrincipalId, but the decision primitive still rejects because
+    // the request is missing its principal binding.
+    const req = createCanonicalGuardianRequest({
+      kind: 'unknown_kind',
+      sourceType: 'channel',
+      conversationId: 'conv-1',
+      guardianExternalUserId: 'guardian-1',
+      expiresAt: new Date(Date.now() + 60_000).toISOString(),
+    });
+
+    const result = await applyCanonicalGuardianDecision({
+      requestId: req.id,
+      action: 'approve_once',
+      actorContext: guardianActor({ guardianPrincipalId: 'some-principal' }),
+    });
+
+    expect(result.applied).toBe(false);
+    if (result.applied) return;
+    expect(result.reason).toBe('identity_mismatch');
+  });
+
+  test('rejects decision when actor has no guardianPrincipalId', async () => {
     const req = createCanonicalGuardianRequest({
       kind: 'tool_approval',
       sourceType: 'channel',
       conversationId: 'conv-1',
-      // No guardianExternalUserId — open request
+      guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
     });
 
     const result = await applyCanonicalGuardianDecision({
       requestId: req.id,
       action: 'approve_once',
-      actorContext: guardianActor({ externalUserId: 'anyone' }),
+      actorContext: guardianActor({ guardianPrincipalId: undefined }),
     });
 
     expect(result.applied).toBe(false);
@@ -276,6 +308,7 @@ describe('applyCanonicalGuardianDecision', () => {
       sourceType: 'channel',
       conversationId: 'conv-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
     });
 
@@ -324,6 +357,7 @@ describe('applyCanonicalGuardianDecision', () => {
       sourceType: 'channel',
       conversationId: 'conv-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
     });
 
@@ -351,6 +385,7 @@ describe('applyCanonicalGuardianDecision', () => {
       sourceChannel: 'telegram',
       conversationId: 'conv-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       toolName: 'shell',
       inputDigest: 'sha256:abc',
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
@@ -385,6 +420,7 @@ describe('applyCanonicalGuardianDecision', () => {
       sourceType: 'channel',
       conversationId: 'conv-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       expiresAt: new Date(Date.now() - 10_000).toISOString(), // already expired
     });
 
@@ -405,6 +441,7 @@ describe('applyCanonicalGuardianDecision', () => {
       sourceType: 'channel',
       conversationId: 'conv-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       // No expiresAt
     });
 
@@ -426,6 +463,7 @@ describe('applyCanonicalGuardianDecision', () => {
       sourceChannel: 'telegram',
       conversationId: 'conv-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       toolName: 'file_read',
       inputDigest: 'sha256:def',
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
@@ -446,6 +484,7 @@ describe('applyCanonicalGuardianDecision', () => {
       sourceType: 'voice',
       sourceChannel: 'twilio',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       callSessionId: 'call-99',
       pendingQuestionId: 'pq-99',
       questionText: 'What is the password?',
@@ -464,12 +503,13 @@ describe('applyCanonicalGuardianDecision', () => {
     expect(resolved!.answerText).toBe('secret123');
   });
 
-  test('succeeds even with no resolver for unknown kind', async () => {
+  test('succeeds for non-decisionable kind with matching principal', async () => {
     const req = createCanonicalGuardianRequest({
       kind: 'unknown_kind',
       sourceType: 'channel',
       conversationId: 'conv-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
     });
 
@@ -485,7 +525,7 @@ describe('applyCanonicalGuardianDecision', () => {
     expect(resolved!.status).toBe('approved');
   });
 
-  test('trusted desktop actor still mints scoped grant for approved canonical request', async () => {
+  test('desktop actor with matching principal mints scoped grant for approved canonical request', async () => {
     const req = createCanonicalGuardianRequest({
       kind: 'unknown_kind',
       sourceType: 'voice',
@@ -494,6 +534,7 @@ describe('applyCanonicalGuardianDecision', () => {
       callSessionId: 'call-voice-1',
       toolName: 'host_bash',
       inputDigest: 'sha256:voice-digest-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
     });
 
@@ -530,6 +571,7 @@ describe('mintCanonicalRequestGrant', () => {
       sourceType: 'channel',
       sourceChannel: 'telegram',
       conversationId: 'conv-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       toolName: 'shell',
       inputDigest: 'sha256:abc',
     });
@@ -549,6 +591,7 @@ describe('mintCanonicalRequestGrant', () => {
       sourceType: 'channel',
       sourceChannel: 'telegram',
       conversationId: 'conv-2',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       toolName: 'shell',
       inputDigest: 'sha256:xyz',
     });
@@ -570,6 +613,7 @@ describe('mintCanonicalRequestGrant', () => {
     const req = createCanonicalGuardianRequest({
       kind: 'pending_question',
       sourceType: 'voice',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       // No toolName or inputDigest
     });
 
@@ -586,6 +630,7 @@ describe('mintCanonicalRequestGrant', () => {
     const req = createCanonicalGuardianRequest({
       kind: 'tool_approval',
       sourceType: 'channel',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       toolName: 'shell',
       // No inputDigest
     });

package/src/__tests__/guardian-dispatch.test.ts

@@ -31,25 +31,45 @@ mock.module('../util/logger.js', () => ({
 
 let mockTelegramBinding: unknown = null;
 let mockSmsBinding: unknown = null;
+let mockVellumBinding: unknown = null;
 
 mock.module('../memory/channel-guardian-store.js', () => ({
   getActiveBinding: (_assistantId: string, channel: string) => {
     if (channel === 'telegram') return mockTelegramBinding;
     if (channel === 'sms') return mockSmsBinding;
+    if (channel === 'vellum') return mockVellumBinding;
     return null;
   },
+  createBinding: (params: Record<string, unknown>) => ({
+    id: `binding-${Date.now()}`,
+    ...params,
+    status: 'active',
+    verifiedAt: Date.now(),
+    verifiedVia: 'test',
+    metadataJson: null,
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+  }),
+  listActiveBindingsByAssistant: () => mockVellumBinding ? [mockVellumBinding] : [],
 }));
 
 mock.module('../config/loader.js', () => ({
   getConfig: () => ({
     ui: {},
-    
+
     calls: {
       userConsultTimeoutSeconds: 120,
     },
   }),
 }));
 
+// Mock guardian-vellum-migration to use a stable principal, avoiding UNIQUE
+// constraint errors when ensureVellumGuardianBinding is called across tests.
+// Returns a known principal so guardian-dispatch can attribute requests.
+mock.module('../runtime/guardian-vellum-migration.js', () => ({
+  ensureVellumGuardianBinding: () => 'test-principal-id',
+}));
+
 const emitCalls: unknown[] = [];
 let threadCreatedFromMock: ThreadCreatedInfo | null = null;
 let mockEmitResult: {
@@ -109,12 +129,30 @@ function resetTables(): void {
   db.run('DELETE FROM canonical_guardian_requests');
   db.run('DELETE FROM guardian_action_deliveries');
   db.run('DELETE FROM guardian_action_requests');
+  db.run('DELETE FROM channel_guardian_bindings');
   db.run('DELETE FROM call_pending_questions');
   db.run('DELETE FROM call_events');
   db.run('DELETE FROM call_sessions');
   db.run('DELETE FROM conversations');
+
   mockTelegramBinding = null;
   mockSmsBinding = null;
+  // Pre-seed vellum binding so the self-healing path in dispatchGuardianQuestion
+  // never triggers (avoids UNIQUE constraint violations on repeated dispatches).
+  mockVellumBinding = {
+    id: 'binding-vellum-test',
+    assistantId: 'self',
+    channel: 'vellum',
+    guardianExternalUserId: 'vellum-guardian',
+    guardianDeliveryChatId: 'local',
+    guardianPrincipalId: 'test-principal-id',
+    status: 'active',
+    verifiedAt: Date.now(),
+    verifiedVia: 'test',
+    metadataJson: null,
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+  };
   emitCalls.length = 0;
   threadCreatedFromMock = null;
   mockEmitResult = {