@vellumai/assistant 0.4.2 → 0.4.4

package/src/__tests__/relay-server.test.ts

@@ -56,6 +56,12 @@ const mockConfig = {
     provider: 'twilio',
     maxDurationSeconds: 3600,
     userConsultTimeoutSeconds: 120,
+    ttsPlaybackDelayMs: 0,
+    accessRequestPollIntervalMs: 50,
+    guardianWaitUpdateInitialIntervalMs: 100,
+    guardianWaitUpdateInitialWindowMs: 300,
+    guardianWaitUpdateSteadyMinIntervalMs: 150,
+    guardianWaitUpdateSteadyMaxIntervalMs: 200,
     disclosure: { enabled: false, text: '' },
     safety: { denyCategories: [] },
     callerIdentity: {
@@ -135,15 +141,18 @@ import {
 import type { RelayWebSocketData } from '../calls/relay-server.js';
 import { activeRelayConnections,RelayConnection } from '../calls/relay-server.js';
 import { setVoiceBridgeDeps } from '../calls/voice-session-bridge.js';
+import { listCanonicalGuardianRequests, resolveCanonicalGuardianRequest } from '../memory/canonical-guardian-store.js';
 import { createBinding, createChallenge } from '../memory/channel-guardian-store.js';
 import { addMessage, getMessages } from '../memory/conversation-store.js';
 import { getDb, initializeDb, resetDb } from '../memory/db.js';
+import { createInvite } from '../memory/ingress-invite-store.js';
 import { upsertMember } from '../memory/ingress-member-store.js';
 import { conversations } from '../memory/schema.js';
 import {
   createOutboundSession,
   getGuardianBinding,
 } from '../runtime/channel-guardian-service.js';
+import { generateVoiceCode, hashVoiceCode } from '../util/voice-code.js';
 
 initializeDb();
 
@@ -205,9 +214,12 @@ function resetTables() {
   db.run('DELETE FROM messages');
   db.run('DELETE FROM conversations');
   db.run('DELETE FROM assistant_ingress_members');
+  db.run('DELETE FROM assistant_ingress_invites');
   db.run('DELETE FROM channel_guardian_verification_challenges');
   db.run('DELETE FROM channel_guardian_bindings');
   db.run('DELETE FROM channel_guardian_rate_limits');
+  db.run('DELETE FROM canonical_guardian_requests');
+  db.run('DELETE FROM canonical_guardian_deliveries');
   ensuredConvIds = new Set();
 }
 
@@ -733,7 +745,7 @@ describe('relay-server', () => {
     expect(getLatestAssistantText('conv-relay-verify-race')).toContain('**Call failed**');
 
     // Let the delayed endSession callback flush to avoid timer bleed across tests.
-    await new Promise((resolve) => setTimeout(resolve, 2100));
+    await new Promise((resolve) => setTimeout(resolve, 100));
 
     const finalState = getCallSession(session.id);
     expect(finalState).not.toBeNull();
@@ -1132,12 +1144,12 @@ describe('relay-server', () => {
       provider: 'twilio',
       fromNumber: '+15559999999',
       toNumber: '+15551111111',
-      assistantId: 'test-assistant',
+      assistantId: 'self',
       // no task — inbound call
     });
 
     // Create a pending voice guardian challenge
-    const secret = createPendingVoiceGuardianChallenge('test-assistant');
+    const secret = createPendingVoiceGuardianChallenge('self');
 
     mockSendMessage.mockImplementation(createMockProviderResponse(['Hello, how can I help you?']));
 
@@ -1172,7 +1184,7 @@ describe('relay-server', () => {
     expect(relay.getConnectionState()).toBe('connected');
 
     // Guardian binding should have been created
-    const binding = getGuardianBinding('test-assistant', 'voice');
+    const binding = getGuardianBinding('self', 'voice');
     expect(binding).not.toBeNull();
 
     // Orchestrator greeting should have fired
@@ -1196,10 +1208,10 @@ describe('relay-server', () => {
       provider: 'twilio',
       fromNumber: '+15559999999',
       toNumber: '+15551111111',
-      assistantId: 'test-assistant',
+      assistantId: 'self',
     });
 
-    const secret = createPendingVoiceGuardianChallenge('test-assistant');
+    const secret = createPendingVoiceGuardianChallenge('self');
 
     mockSendMessage.mockImplementation(createMockProviderResponse(['Hello, verified caller!']));
 
@@ -1230,7 +1242,7 @@ describe('relay-server', () => {
     expect(relay.getConnectionState()).toBe('connected');
 
     // Binding created
-    const binding = getGuardianBinding('test-assistant', 'voice');
+    const binding = getGuardianBinding('self', 'voice');
     expect(binding).not.toBeNull();
 
     // Greeting should have started
@@ -1249,11 +1261,11 @@ describe('relay-server', () => {
       provider: 'twilio',
       fromNumber: '+15550001111',
       toNumber: '+15551111111',
-      assistantId: 'test-assistant',
+      assistantId: 'self',
     });
 
     createBinding({
-      assistantId: 'test-assistant',
+      assistantId: 'self',
       channel: 'voice',
       guardianExternalUserId: '+15550001111',
       guardianDeliveryChatId: '+15550001111',
@@ -1285,16 +1297,16 @@ describe('relay-server', () => {
       provider: 'twilio',
       fromNumber: '+15550002222',
       toNumber: '+15551111111',
-      assistantId: 'test-assistant',
+      assistantId: 'self',
     });
 
     createBinding({
-      assistantId: 'test-assistant',
+      assistantId: 'self',
       channel: 'voice',
       guardianExternalUserId: '+15550009999',
       guardianDeliveryChatId: '+15550009999',
     });
-    addTrustedVoiceContact('+15550002222', 'test-assistant');
+    addTrustedVoiceContact('+15550002222', 'self');
 
     mockSendMessage.mockImplementation(createMockProviderResponse(['Hello there.']));
 
@@ -1331,12 +1343,12 @@ describe('relay-server', () => {
       provider: 'twilio',
       fromNumber: '+15551111111',
       toNumber: '+15550001111',
-      assistantId: 'test-assistant',
+      assistantId: 'self',
       initiatedFromConversationId: 'conv-guardian-outbound-voice-origin',
     });
 
     createBinding({
-      assistantId: 'test-assistant',
+      assistantId: 'self',
       channel: 'voice',
       guardianExternalUserId: '+15550001111',
       guardianDeliveryChatId: '+15550001111',
@@ -1375,12 +1387,12 @@ describe('relay-server', () => {
       provider: 'twilio',
       fromNumber: '+15551111111',
       toNumber: '+15550001111',
-      assistantId: 'test-assistant',
+      assistantId: 'self',
       initiatedFromConversationId: 'conv-guardian-outbound-strict-origin',
     });
 
     createBinding({
-      assistantId: 'test-assistant',
+      assistantId: 'self',
       channel: 'telegram',
       guardianExternalUserId: 'tg-guardian-user',
       guardianDeliveryChatId: 'tg-guardian-chat',
@@ -1419,10 +1431,10 @@ describe('relay-server', () => {
       provider: 'twilio',
       fromNumber: '+15550003333',
       toNumber: '+15551111111',
-      assistantId: 'test-assistant',
+      assistantId: 'self',
     });
 
-    const secret = createPendingVoiceGuardianChallenge('test-assistant');
+    const secret = createPendingVoiceGuardianChallenge('self');
     const spokenCode = secret.split('').join(' ');
 
     const { relay } = createMockWs(session.id);
@@ -1465,10 +1477,10 @@ describe('relay-server', () => {
       provider: 'twilio',
       fromNumber: '+15559999999',
       toNumber: '+15551111111',
-      assistantId: 'test-assistant',
+      assistantId: 'self',
     });
 
-    createPendingVoiceGuardianChallenge('test-assistant');
+    createPendingVoiceGuardianChallenge('self');
 
     const { ws, relay } = createMockWs(session.id);
 
@@ -1506,10 +1518,10 @@ describe('relay-server', () => {
       provider: 'twilio',
       fromNumber: '+15559999999',
       toNumber: '+15551111111',
-      assistantId: 'test-assistant',
+      assistantId: 'self',
     });
 
-    createPendingVoiceGuardianChallenge('test-assistant');
+    createPendingVoiceGuardianChallenge('self');
 
     const { ws, relay } = createMockWs(session.id);
 
@@ -1546,7 +1558,7 @@ describe('relay-server', () => {
     expect(events.some((e) => e.eventType === 'guardian_voice_verification_failed')).toBe(true);
 
     // Let the delayed endSession callback flush
-    await new Promise((resolve) => setTimeout(resolve, 2100));
+    await new Promise((resolve) => setTimeout(resolve, 100));
 
     // Verify end message was sent
     const endMessages = ws.sentMessages
@@ -1564,14 +1576,14 @@ describe('relay-server', () => {
       provider: 'twilio',
       fromNumber: '+15559999999',
       toNumber: '+15551111111',
-      assistantId: 'test-assistant',
+      assistantId: 'self',
       // no task — inbound call
     });
 
     // Do NOT create any pending challenge
 
     mockSendMessage.mockImplementation(createMockProviderResponse(['Welcome to the line.']));
-    addTrustedVoiceContact('+15559999999', 'test-assistant');
+    addTrustedVoiceContact('+15559999999', 'self');
 
     const { ws, relay } = createMockWs(session.id);
 
@@ -1604,10 +1616,10 @@ describe('relay-server', () => {
       provider: 'twilio',
       fromNumber: '+15559999999',
       toNumber: '+15551111111',
-      assistantId: 'test-assistant',
+      assistantId: 'self',
     });
 
-    createPendingVoiceGuardianChallenge('test-assistant');
+    createPendingVoiceGuardianChallenge('self');
 
     const { ws, relay } = createMockWs(session.id);
 
@@ -1651,13 +1663,13 @@ describe('relay-server', () => {
       provider: 'twilio',
       fromNumber: '+15551111111',
       toNumber: '+15559999999',
-      assistantId: 'test-assistant',
+      assistantId: 'self',
       callMode: 'guardian_verification',
       guardianVerificationSessionId: 'gv-session-ptr-success',
       initiatedFromConversationId: 'conv-gv-pointer-success-origin',
     });
 
-    const secret = createVoiceVerificationSession('test-assistant', '+15559999999', 'gv-session-ptr-success');
+    const secret = createVoiceVerificationSession('self', '+15559999999', 'gv-session-ptr-success');
 
     const { relay } = createMockWs(session.id);
 
@@ -1687,7 +1699,7 @@ describe('relay-server', () => {
     expect(originText).toContain('succeeded');
 
     // Let the delayed endSession callback flush
-    await new Promise((resolve) => setTimeout(resolve, 3100));
+    await new Promise((resolve) => setTimeout(resolve, 100));
 
     relay.destroy();
   });
@@ -1700,13 +1712,13 @@ describe('relay-server', () => {
       provider: 'twilio',
       fromNumber: '+15551111111',
       toNumber: '+15559999999',
-      assistantId: 'test-assistant',
+      assistantId: 'self',
       callMode: 'guardian_verification',
       guardianVerificationSessionId: 'gv-session-ptr-fail',
       initiatedFromConversationId: 'conv-gv-pointer-fail-origin',
     });
 
-    createVoiceVerificationSession('test-assistant', '+15559999999', 'gv-session-ptr-fail');
+    createVoiceVerificationSession('self', '+15559999999', 'gv-session-ptr-fail');
 
     const { relay } = createMockWs(session.id);
 
@@ -1740,8 +1752,1438 @@ describe('relay-server', () => {
     expect(originText).toContain('failed');
 
     // Let the delayed endSession callback flush
-    await new Promise((resolve) => setTimeout(resolve, 2100));
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    relay.destroy();
+  });
+
+  // ── Inbound voice invite redemption ──────────────────────────────────
+
+  test('inbound voice invite redemption: personalized welcome prompt with friend/guardian names', async () => {
+    ensureConversation('conv-invite-welcome');
+    const session = createCallSession({
+      conversationId: 'conv-invite-welcome',
+      provider: 'twilio',
+      fromNumber: '+15558887777',
+      toNumber: '+15551111111',
+      assistantId: 'self',
+    });
+
+    // Create a voice invite with friend/guardian names
+    const code = generateVoiceCode(6);
+    const codeHash = hashVoiceCode(code);
+    createInvite({
+      assistantId: 'self',
+      sourceChannel: 'voice',
+      maxUses: 1,
+      expectedExternalUserId: '+15558887777',
+      voiceCodeHash: codeHash,
+      voiceCodeDigits: 6,
+      friendName: 'Alice',
+      guardianName: 'Bob',
+    });
+
+    mockSendMessage.mockImplementation(createMockProviderResponse(['Hello, how can I help?']));
+
+    const { ws, relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_invite_welcome',
+      from: '+15558887777',
+      to: '+15551111111',
+    }));
+
+    // Should be in verification-pending state for invite redemption
+    expect(relay.getConnectionState()).toBe('verification_pending');
+
+    // Check that the welcome prompt includes friend/guardian names
+    const textMessages = ws.sentMessages
+      .map((raw) => JSON.parse(raw) as { type: string; token?: string })
+      .filter((m) => m.type === 'text');
+    expect(textMessages.some((m) => (m.token ?? '').includes('Welcome Alice'))).toBe(true);
+    expect(textMessages.some((m) => (m.token ?? '').includes('Bob provided you'))).toBe(true);
+
+    // Enter the correct code via DTMF
+    for (const digit of code) {
+      await relay.handleMessage(JSON.stringify({ type: 'dtmf', digit }));
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    // Should have transitioned to connected
+    expect(relay.getConnectionState()).toBe('connected');
+
+    // Verify events
+    const events = getCallEvents(session.id);
+    expect(events.some((e) => e.eventType === 'invite_redemption_started')).toBe(true);
+    expect(events.some((e) => e.eventType === 'invite_redemption_succeeded')).toBe(true);
+
+    relay.destroy();
+  });
+
+  test('inbound voice invite redemption: invalid code gets exact failure copy with guardian name and call ends', async () => {
+    ensureConversation('conv-invite-fail');
+    const session = createCallSession({
+      conversationId: 'conv-invite-fail',
+      provider: 'twilio',
+      fromNumber: '+15558886666',
+      toNumber: '+15551111111',
+      assistantId: 'self',
+    });
+
+    // Create a voice invite with friend/guardian names
+    const code = generateVoiceCode(6);
+    const codeHash = hashVoiceCode(code);
+    createInvite({
+      assistantId: 'self',
+      sourceChannel: 'voice',
+      maxUses: 1,
+      expectedExternalUserId: '+15558886666',
+      voiceCodeHash: codeHash,
+      voiceCodeDigits: 6,
+      friendName: 'Carol',
+      guardianName: 'Dave',
+    });
+
+    const { ws, relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_invite_fail',
+      from: '+15558886666',
+      to: '+15551111111',
+    }));
+
+    expect(relay.getConnectionState()).toBe('verification_pending');
+
+    // Enter a wrong code
+    for (const digit of '000000') {
+      await relay.handleMessage(JSON.stringify({ type: 'dtmf', digit }));
+    }
+
+    // Call should be marked as failed immediately
+    const updated = getCallSession(session.id);
+    expect(updated).not.toBeNull();
+    expect(updated!.status).toBe('failed');
+
+    // Should have sent the exact deterministic failure copy with guardian name
+    const textMessages = ws.sentMessages
+      .map((raw) => JSON.parse(raw) as { type: string; token?: string })
+      .filter((m) => m.type === 'text');
+    expect(textMessages.some((m) => (m.token ?? '').includes('Sorry, the code you provided is incorrect or has since expired'))).toBe(true);
+    expect(textMessages.some((m) => (m.token ?? '').includes('Please ask Dave for a new code'))).toBe(true);
+
+    // Verify events
+    const events = getCallEvents(session.id);
+    expect(events.some((e) => e.eventType === 'invite_redemption_failed')).toBe(true);
+
+    // Let the delayed endSession callback flush
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    // Verify end message was sent
+    const endMessages = ws.sentMessages
+      .map((raw) => JSON.parse(raw) as { type: string })
+      .filter((m) => m.type === 'end');
+    expect(endMessages.length).toBe(1);
+
+    relay.destroy();
+  });
+
+  test('inbound voice: unknown caller with no active invite enters name capture flow', async () => {
+    ensureConversation('conv-invite-no-invite');
+    const session = createCallSession({
+      conversationId: 'conv-invite-no-invite',
+      provider: 'twilio',
+      fromNumber: '+15558885555',
+      toNumber: '+15551111111',
+      assistantId: 'self',
+    });
+
+    // No voice invite created for this caller
+
+    const { ws, relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_invite_no_invite',
+      from: '+15558885555',
+      to: '+15551111111',
+    }));
+
+    // Should be in the name capture state (not denied)
+    expect(relay.getConnectionState()).toBe('awaiting_name');
+
+    // Should have sent the name capture prompt
+    const textMessages = ws.sentMessages
+      .map((raw) => JSON.parse(raw) as { type: string; token?: string })
+      .filter((m) => m.type === 'text');
+    expect(textMessages.some((m) => (m.token ?? '').includes("don't recognize this number"))).toBe(true);
+    expect(textMessages.some((m) => (m.token ?? '').includes('Can I get your name'))).toBe(true);
+
+    // Verify event was recorded
+    const events = getCallEvents(session.id);
+    expect(events.some((e) => e.eventType === 'inbound_acl_name_capture_started')).toBe(true);
+
+    relay.destroy();
+  });
+
+  // ── Friend-initiated in-call guardian approval flow ────────────────────
+
+  test('name capture flow: caller provides name and enters guardian decision wait', async () => {
+    ensureConversation('conv-name-capture');
+    const session = createCallSession({
+      conversationId: 'conv-name-capture',
+      provider: 'twilio',
+      fromNumber: '+15558884444',
+      toNumber: '+15551111111',
+      assistantId: 'self',
+    });
+
+    const { ws, relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_name_capture',
+      from: '+15558884444',
+      to: '+15551111111',
+    }));
+
+    // Should be in name capture state
+    expect(relay.getConnectionState()).toBe('awaiting_name');
+
+    // Caller speaks their name
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'My name is John',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    // Should have transitioned to awaiting guardian decision
+    expect(relay.getConnectionState()).toBe('awaiting_guardian_decision');
+
+    // Should have sent the hold message (guardian label defaults to "my guardian")
+    const textMessages = ws.sentMessages
+      .map((raw) => JSON.parse(raw) as { type: string; token?: string })
+      .filter((m) => m.type === 'text');
+    expect(textMessages.some((m) => (m.token ?? '').includes("I've let my guardian know"))).toBe(true);
+    expect(textMessages.some((m) => (m.token ?? '').includes('Please hold'))).toBe(true);
+
+    // Verify events were recorded
+    const events = getCallEvents(session.id);
+    expect(events.some((e) => e.eventType === 'inbound_acl_name_captured')).toBe(true);
+
+    // Session should be in waiting_on_user status
+    const updated = getCallSession(session.id);
+    expect(updated).not.toBeNull();
+    expect(updated!.status).toBe('waiting_on_user');
+
+    relay.destroy();
+  });
+
+  test('name capture flow: DTMF input is ignored during awaiting_name state', async () => {
+    ensureConversation('conv-name-dtmf-ignore');
+    const session = createCallSession({
+      conversationId: 'conv-name-dtmf-ignore',
+      provider: 'twilio',
+      fromNumber: '+15558883333',
+      toNumber: '+15551111111',
+      assistantId: 'self',
+    });
+
+    const { ws, relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_name_dtmf_ignore',
+      from: '+15558883333',
+      to: '+15551111111',
+    }));
+
+    expect(relay.getConnectionState()).toBe('awaiting_name');
+    const msgCountBefore = ws.sentMessages.length;
+
+    // DTMF should be ignored during name capture
+    await relay.handleMessage(JSON.stringify({ type: 'dtmf', digit: '5' }));
+
+    // No new messages should be sent (DTMF is ignored)
+    expect(ws.sentMessages.length).toBe(msgCountBefore);
+    expect(relay.getConnectionState()).toBe('awaiting_name');
+
+    relay.destroy();
+  });
+
+  test('name capture flow: voice prompts during guardian wait get reassurance response', async () => {
+    ensureConversation('conv-wait-prompt-reassure');
+    const session = createCallSession({
+      conversationId: 'conv-wait-prompt-reassure',
+      provider: 'twilio',
+      fromNumber: '+15558882222',
+      toNumber: '+15551111111',
+      assistantId: 'self',
+    });
+
+    const { ws, relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_wait_prompt_reassure',
+      from: '+15558882222',
+      to: '+15551111111',
+    }));
+
+    // Provide name to enter guardian decision wait
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Jane Doe',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    expect(relay.getConnectionState()).toBe('awaiting_guardian_decision');
+    const msgCountBefore = ws.sentMessages.length;
+
+    // Voice prompts during guardian wait should get a reassurance reply
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Are you still there?',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    // A reassurance message should have been sent
+    const newMessages = ws.sentMessages.slice(msgCountBefore);
+    const textMessages = newMessages
+      .map((raw) => JSON.parse(raw) as { type: string; token?: string })
+      .filter((m) => m.type === 'text');
+    expect(textMessages.length).toBeGreaterThan(0);
+    expect(textMessages.some((m) => (m.token ?? '').includes('still here'))).toBe(true);
+    expect(relay.getConnectionState()).toBe('awaiting_guardian_decision');
+
+    relay.destroy();
+  });
+
+  test('blocked caller gets immediate denial even with name capture flow', async () => {
+    ensureConversation('conv-blocked-deny');
+    const session = createCallSession({
+      conversationId: 'conv-blocked-deny',
+      provider: 'twilio',
+      fromNumber: '+15558881111',
+      toNumber: '+15551111111',
+      assistantId: 'self',
+    });
+
+    // Create a blocked member
+    upsertMember({
+      assistantId: 'self',
+      sourceChannel: 'voice',
+      externalUserId: '+15558881111',
+      externalChatId: '+15558881111',
+      status: 'blocked',
+      policy: 'allow',
+    });
+
+    const { ws, relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_blocked_deny',
+      from: '+15558881111',
+      to: '+15551111111',
+    }));
+
+    // Blocked callers should NOT enter name capture — they get immediate denial
+    expect(relay.getConnectionState()).toBe('disconnecting');
+
+    const updated = getCallSession(session.id);
+    expect(updated).not.toBeNull();
+    expect(updated!.status).toBe('failed');
+
+    const textMessages = ws.sentMessages
+      .map((raw) => JSON.parse(raw) as { type: string; token?: string })
+      .filter((m) => m.type === 'text');
+    expect(textMessages.some((m) => (m.token ?? '').includes('not authorized'))).toBe(true);
+
+    // Let delayed endSession callback flush
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    relay.destroy();
+  });
+
+  test('name capture flow: access request creates canonical request for guardian', async () => {
+    ensureConversation('conv-access-req-canonical');
+    const session = createCallSession({
+      conversationId: 'conv-access-req-canonical',
+      provider: 'twilio',
+      fromNumber: '+15557770001',
+      toNumber: '+15551111111',
+      assistantId: 'self',
+    });
+
+    const { relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_access_req_canonical',
+      from: '+15557770001',
+      to: '+15551111111',
+    }));
+
+    expect(relay.getConnectionState()).toBe('awaiting_name');
+
+    // Provide name
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Sarah Connor',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    expect(relay.getConnectionState()).toBe('awaiting_guardian_decision');
+
+    // A canonical access request should have been created
+    const pending = listCanonicalGuardianRequests({
+      status: 'pending',
+      requesterExternalUserId: '+15557770001',
+      sourceChannel: 'voice',
+      kind: 'access_request',
+    });
+    expect(pending.length).toBe(1);
+    expect(pending[0].requesterExternalUserId).toBe('+15557770001');
+
+    relay.destroy();
+  });
+
+  test('name capture flow: approved access request activates caller and continues call', async () => {
+    ensureConversation('conv-access-approved');
+    const session = createCallSession({
+      conversationId: 'conv-access-approved',
+      provider: 'twilio',
+      fromNumber: '+15557770002',
+      toNumber: '+15551111111',
+      assistantId: 'self',
+    });
+
+    mockSendMessage.mockImplementation(createMockProviderResponse(['I can help you with that.']));
+
+    const { relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_access_approved',
+      from: '+15557770002',
+      to: '+15551111111',
+    }));
+
+    // Provide name to enter wait state
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Bob Smith',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    expect(relay.getConnectionState()).toBe('awaiting_guardian_decision');
+
+    // Find the canonical request and simulate guardian approval
+    const pending = listCanonicalGuardianRequests({
+      status: 'pending',
+      requesterExternalUserId: '+15557770002',
+      sourceChannel: 'voice',
+      kind: 'access_request',
+    });
+    expect(pending.length).toBe(1);
+
+    // Resolve the request to approved status
+    resolveCanonicalGuardianRequest(pending[0].id, 'pending', {
+      status: 'approved',
+      answerText: undefined,
+      decidedByExternalUserId: undefined,
+    });
+
+    // Wait for the poll interval to detect the approval
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    // Should have transitioned to connected state
+    expect(relay.getConnectionState()).toBe('connected');
+
+    // Verify events
+    const events = getCallEvents(session.id);
+    expect(events.some((e) => e.eventType === 'inbound_acl_access_approved')).toBe(true);
+
+    // Session should be in_progress
+    const updated = getCallSession(session.id);
+    expect(updated).not.toBeNull();
+    expect(updated!.status).toBe('in_progress');
+
+    relay.destroy();
+  });
+
+  test('name capture flow: denied access request ends call with deterministic copy', async () => {
+    ensureConversation('conv-access-denied');
+    const session = createCallSession({
+      conversationId: 'conv-access-denied',
+      provider: 'twilio',
+      fromNumber: '+15557770003',
+      toNumber: '+15551111111',
+      assistantId: 'self',
+    });
+
+    const { ws, relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_access_denied',
+      from: '+15557770003',
+      to: '+15551111111',
+    }));
+
+    // Provide name
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Eve',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    expect(relay.getConnectionState()).toBe('awaiting_guardian_decision');
+
+    // Simulate guardian denial
+    const pending = listCanonicalGuardianRequests({
+      status: 'pending',
+      requesterExternalUserId: '+15557770003',
+      sourceChannel: 'voice',
+      kind: 'access_request',
+    });
+    expect(pending.length).toBe(1);
+
+    resolveCanonicalGuardianRequest(pending[0].id, 'pending', {
+      status: 'denied',
+      answerText: undefined,
+      decidedByExternalUserId: undefined,
+    });
+
+    // Wait for poll to detect the denial
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    // Should be disconnecting
+    expect(relay.getConnectionState()).toBe('disconnecting');
+
+    // Should have sent the denial message
+    const textMessages = ws.sentMessages
+      .map((raw) => JSON.parse(raw) as { type: string; token?: string })
+      .filter((m) => m.type === 'text');
+    expect(textMessages.some((m) => (m.token ?? '').includes("says I'm not allowed"))).toBe(true);
+
+    // Session should be failed
+    const updated = getCallSession(session.id);
+    expect(updated).not.toBeNull();
+    expect(updated!.status).toBe('failed');
+
+    // Verify event
+    const events = getCallEvents(session.id);
+    expect(events.some((e) => e.eventType === 'inbound_acl_access_denied')).toBe(true);
+
+    // Let the delayed endSession callback flush
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    relay.destroy();
+  });
+
+  test('name capture flow: timeout ends call with deterministic copy', async () => {
+    // Override the consultation timeout to a very short value for testing
+    mockConfig.calls.userConsultTimeoutSeconds = 2; // 2 seconds
+
+    ensureConversation('conv-access-timeout');
+    const session = createCallSession({
+      conversationId: 'conv-access-timeout',
+      provider: 'twilio',
+      fromNumber: '+15557770004',
+      toNumber: '+15551111111',
+      assistantId: 'self',
+    });
+
+    const { ws, relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_access_timeout',
+      from: '+15557770004',
+      to: '+15551111111',
+    }));
+
+    // Provide name
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Timeout Tester',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    expect(relay.getConnectionState()).toBe('awaiting_guardian_decision');
+
+    // Wait for timeout (2 seconds + buffer)
+    await new Promise((resolve) => setTimeout(resolve, 2500));
+
+    // Should be disconnecting after timeout
+    expect(relay.getConnectionState()).toBe('disconnecting');
+
+    // Should have sent the timeout message
+    const textMessages = ws.sentMessages
+      .map((raw) => JSON.parse(raw) as { type: string; token?: string })
+      .filter((m) => m.type === 'text');
+    expect(textMessages.some((m) => (m.token ?? '').includes("can't get ahold of"))).toBe(true);
+    expect(textMessages.some((m) => (m.token ?? '').includes("let them know you called"))).toBe(true);
+
+    // Session should be failed
+    const updated = getCallSession(session.id);
+    expect(updated).not.toBeNull();
+    expect(updated!.status).toBe('failed');
+
+    // Verify event
+    const events = getCallEvents(session.id);
+    expect(events.some((e) => e.eventType === 'inbound_acl_access_timeout')).toBe(true);
+
+    // Let the delayed endSession callback flush
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    // Restore default timeout
+    mockConfig.calls.userConsultTimeoutSeconds = 120;
+
+    relay.destroy();
+  });
+
+  test('name capture flow: transport close during guardian wait cleans up timers', async () => {
+    ensureConversation('conv-access-transport-close');
+    const session = createCallSession({
+      conversationId: 'conv-access-transport-close',
+      provider: 'twilio',
+      fromNumber: '+15557770005',
+      toNumber: '+15551111111',
+      assistantId: 'self',
+    });
+
+    const { relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_access_transport_close',
+      from: '+15557770005',
+      to: '+15551111111',
+    }));
+
+    // Provide name
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Disconnector',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    expect(relay.getConnectionState()).toBe('awaiting_guardian_decision');
+
+    // Simulate transport close while waiting for guardian
+    relay.handleTransportClosed(1000, 'caller hung up');
+
+    // Session should be completed (normal close)
+    const updated = getCallSession(session.id);
+    expect(updated).not.toBeNull();
+    expect(updated!.status).toBe('completed');
+
+    relay.destroy();
+  });
+
+  // ── Guardian wait heartbeat and impatience handling ──────────────────
+
+  test('guardian wait: heartbeat timer emits periodic updates', async () => {
+    ensureConversation('conv-heartbeat-basic');
+    const session = createCallSession({
+      conversationId: 'conv-heartbeat-basic',
+      provider: 'twilio',
+      fromNumber: '+15557770010',
+      toNumber: '+15551111111',
+      assistantId: 'self',
+    });
+
+    const { ws, relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_heartbeat_basic',
+      from: '+15557770010',
+      to: '+15551111111',
+    }));
+
+    // Provide name to enter guardian wait
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Heartbeat Tester',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    expect(relay.getConnectionState()).toBe('awaiting_guardian_decision');
+    const msgCountAfterHold = ws.sentMessages.length;
+
+    // Wait for at least one heartbeat (initial interval is 100ms in test config)
+    await new Promise((resolve) => setTimeout(resolve, 250));
+
+    const newMessages = ws.sentMessages.slice(msgCountAfterHold);
+    const textMessages = newMessages
+      .map((raw) => JSON.parse(raw) as { type: string; token?: string })
+      .filter((m) => m.type === 'text');
+    expect(textMessages.length).toBeGreaterThan(0);
+    // Heartbeat messages mention "waiting" or "guardian"
+    expect(textMessages.some((m) => (m.token ?? '').toLowerCase().includes('waiting'))).toBe(true);
+
+    // Verify heartbeat event was recorded
+    const events = getCallEvents(session.id);
+    expect(events.some((e) => e.eventType === 'voice_guardian_wait_heartbeat_sent')).toBe(true);
+
+    relay.destroy();
+  });
+
+  test('guardian wait: heartbeat stops on approval', async () => {
+    ensureConversation('conv-heartbeat-stop-approve');
+    const session = createCallSession({
+      conversationId: 'conv-heartbeat-stop-approve',
+      provider: 'twilio',
+      fromNumber: '+15557770011',
+      toNumber: '+15551111111',
+      assistantId: 'self',
+    });
+
+    mockSendMessage.mockImplementation(createMockProviderResponse(['Welcome!']));
+
+    const { ws, relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_heartbeat_stop_approve',
+      from: '+15557770011',
+      to: '+15551111111',
+    }));
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Approve Tester',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    expect(relay.getConnectionState()).toBe('awaiting_guardian_decision');
+
+    // Approve the request
+    const pending = listCanonicalGuardianRequests({
+      status: 'pending',
+      requesterExternalUserId: '+15557770011',
+      sourceChannel: 'voice',
+      kind: 'access_request',
+    });
+    expect(pending.length).toBe(1);
+
+    resolveCanonicalGuardianRequest(pending[0].id, 'pending', {
+      status: 'approved',
+      answerText: undefined,
+      decidedByExternalUserId: undefined,
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    // Connection should have transitioned
+    expect(relay.getConnectionState()).toBe('connected');
+
+    // Record message count after approval
+    const msgCountAfterApproval = ws.sentMessages.length;
+
+    // Wait and verify no more heartbeats
+    await new Promise((resolve) => setTimeout(resolve, 300));
+    expect(ws.sentMessages.length).toBe(msgCountAfterApproval);
+
+    relay.destroy();
+  });
+
+  test('guardian wait: heartbeat stops on destroy', async () => {
+    ensureConversation('conv-heartbeat-stop-destroy');
+    const session = createCallSession({
+      conversationId: 'conv-heartbeat-stop-destroy',
+      provider: 'twilio',
+      fromNumber: '+15557770012',
+      toNumber: '+15551111111',
+      assistantId: 'self',
+    });
+
+    const { relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_heartbeat_stop_destroy',
+      from: '+15557770012',
+      to: '+15551111111',
+    }));
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Destroy Tester',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    expect(relay.getConnectionState()).toBe('awaiting_guardian_decision');
+
+    // Destroy should not throw and should clean up timers
+    expect(() => relay.destroy()).not.toThrow();
+  });
+
+  test('guardian wait: impatience utterance triggers callback offer', async () => {
+    ensureConversation('conv-impatience-offer');
+    const session = createCallSession({
+      conversationId: 'conv-impatience-offer',
+      provider: 'twilio',
+      fromNumber: '+15557770013',
+      toNumber: '+15551111111',
+      assistantId: 'self',
+    });
+
+    const { ws, relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_impatience_offer',
+      from: '+15557770013',
+      to: '+15551111111',
+    }));
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Impatient Tester',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    expect(relay.getConnectionState()).toBe('awaiting_guardian_decision');
+    const msgCountBefore = ws.sentMessages.length;
+
+    // Send an impatient utterance
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'This is taking too long!',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    const newMessages = ws.sentMessages.slice(msgCountBefore);
+    const textMessages = newMessages
+      .map((raw) => JSON.parse(raw) as { type: string; token?: string })
+      .filter((m) => m.type === 'text');
+    expect(textMessages.length).toBeGreaterThan(0);
+    // Should offer callback
+    expect(textMessages.some((m) => (m.token ?? '').toLowerCase().includes('call you back'))).toBe(true);
+
+    // Verify event
+    const events = getCallEvents(session.id);
+    expect(events.some((e) => e.eventType === 'voice_guardian_wait_callback_offer_sent')).toBe(true);
+    expect(events.some((e) => e.eventType === 'voice_guardian_wait_prompt_classified')).toBe(true);
+
+    relay.destroy();
+  });
+
+  test('guardian wait: explicit callback opt-in after offer is acknowledged', async () => {
+    ensureConversation('conv-callback-optin');
+    const session = createCallSession({
+      conversationId: 'conv-callback-optin',
+      provider: 'twilio',
+      fromNumber: '+15557770014',
+      toNumber: '+15551111111',
+      assistantId: 'self',
+    });
+
+    const { ws, relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_callback_optin',
+      from: '+15557770014',
+      to: '+15551111111',
+    }));
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'OptIn Tester',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    expect(relay.getConnectionState()).toBe('awaiting_guardian_decision');
+
+    // Trigger impatience to get callback offer
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Hurry up please',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    // Wait for cooldown
+    await new Promise((resolve) => setTimeout(resolve, 3100));
+
+    const msgCountBeforeOptIn = ws.sentMessages.length;
+
+    // Accept the callback offer
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Yes, please call me back',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    const newMessages = ws.sentMessages.slice(msgCountBeforeOptIn);
+    const textMessages = newMessages
+      .map((raw) => JSON.parse(raw) as { type: string; token?: string })
+      .filter((m) => m.type === 'text');
+    expect(textMessages.length).toBeGreaterThan(0);
+    // Should acknowledge the callback opt-in
+    expect(textMessages.some((m) => (m.token ?? '').toLowerCase().includes('noted'))).toBe(true);
+
+    // Verify events
+    const events = getCallEvents(session.id);
+    expect(events.some((e) => e.eventType === 'voice_guardian_wait_callback_opt_in_set')).toBe(true);
+
+    // Connection should still be in guardian wait (callback not auto-dispatched)
+    expect(relay.getConnectionState()).toBe('awaiting_guardian_decision');
+
+    relay.destroy();
+  });
+
+  test('guardian wait: neutral utterance gets acknowledgment', async () => {
+    ensureConversation('conv-wait-neutral');
+    const session = createCallSession({
+      conversationId: 'conv-wait-neutral',
+      provider: 'twilio',
+      fromNumber: '+15557770015',
+      toNumber: '+15551111111',
+      assistantId: 'self',
+    });
+
+    const { ws, relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_wait_neutral',
+      from: '+15557770015',
+      to: '+15551111111',
+    }));
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Neutral Tester',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    expect(relay.getConnectionState()).toBe('awaiting_guardian_decision');
+    const msgCountBefore = ws.sentMessages.length;
+
+    // Send a neutral utterance
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'I just wanted to say thanks',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    const newMessages = ws.sentMessages.slice(msgCountBefore);
+    const textMessages = newMessages
+      .map((raw) => JSON.parse(raw) as { type: string; token?: string })
+      .filter((m) => m.type === 'text');
+    expect(textMessages.length).toBeGreaterThan(0);
+    // Should get an acknowledgment
+    expect(textMessages.some((m) => (m.token ?? '').toLowerCase().includes('waiting'))).toBe(true);
+
+    relay.destroy();
+  });
+
+  test('guardian wait: empty utterance is ignored without response', async () => {
+    ensureConversation('conv-wait-empty');
+    const session = createCallSession({
+      conversationId: 'conv-wait-empty',
+      provider: 'twilio',
+      fromNumber: '+15557770016',
+      toNumber: '+15551111111',
+      assistantId: 'self',
+    });
+
+    const { ws, relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_wait_empty',
+      from: '+15557770016',
+      to: '+15551111111',
+    }));
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Empty Tester',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    expect(relay.getConnectionState()).toBe('awaiting_guardian_decision');
+    const msgCountBefore = ws.sentMessages.length;
+
+    // Send an empty utterance
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: '   ',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    // No new messages should be sent
+    expect(ws.sentMessages.length).toBe(msgCountBefore);
+
+    relay.destroy();
+  });
+
+  test('guardian wait: cooldown prevents rapid-fire responses', async () => {
+    ensureConversation('conv-wait-cooldown');
+    const session = createCallSession({
+      conversationId: 'conv-wait-cooldown',
+      provider: 'twilio',
+      fromNumber: '+15557770017',
+      toNumber: '+15551111111',
+      assistantId: 'self',
+    });
+
+    const { ws, relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_wait_cooldown',
+      from: '+15557770017',
+      to: '+15551111111',
+    }));
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Cooldown Tester',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    expect(relay.getConnectionState()).toBe('awaiting_guardian_decision');
+
+    // First utterance should get a response
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Hello?',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    const msgCountAfterFirst = ws.sentMessages.length;
+
+    // Immediate second utterance should be suppressed by cooldown
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Hello again?',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    // No new messages due to cooldown
+    expect(ws.sentMessages.length).toBe(msgCountAfterFirst);
+
+    relay.destroy();
+  });
+
+  // ── Callback handoff notification tests ────────────────────────────
+
+  test('callback opt-in + access timeout -> emits callback handoff notification exactly once', async () => {
+    mockConfig.calls.userConsultTimeoutSeconds = 2;
+
+    ensureConversation('conv-cb-handoff-timeout');
+    const session = createCallSession({
+      conversationId: 'conv-cb-handoff-timeout',
+      provider: 'twilio',
+      fromNumber: '+15557770020',
+      toNumber: '+15551111111',
+      assistantId: 'self',
+    });
+
+    const { ws, relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_cb_handoff_timeout',
+      from: '+15557770020',
+      to: '+15551111111',
+    }));
+
+    // Provide name to enter guardian wait
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Callback Tester',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    expect(relay.getConnectionState()).toBe('awaiting_guardian_decision');
+
+    // Trigger impatience to get callback offer
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Hurry up please',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    // Accept callback offer (callback decisions bypass cooldown)
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Yes, please call me back',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    // Verify callback opt-in was set
+    const eventsBeforeTimeout = getCallEvents(session.id);
+    expect(eventsBeforeTimeout.some((e) => e.eventType === 'voice_guardian_wait_callback_opt_in_set')).toBe(true);
+
+    // Wait for timeout (2s) plus settling time
+    await new Promise((resolve) => setTimeout(resolve, 2500));
+
+    expect(relay.getConnectionState()).toBe('disconnecting');
+
+    // Allow async notification emission to complete
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    const events = getCallEvents(session.id);
+    // Should have exactly one callback_handoff_notified event (or callback_handoff_failed
+    // if the notification pipeline isn't fully wired in tests — either proves emission)
+    const handoffEvents = events.filter(
+      (e) => e.eventType === 'callback_handoff_notified' || e.eventType === 'callback_handoff_failed',
+    );
+    expect(handoffEvents.length).toBe(1);
+
+    // Verify the timeout event was also recorded
+    expect(events.some((e) => e.eventType === 'inbound_acl_access_timeout')).toBe(true);
+
+    // Timeout copy should include callback note
+    const textMessages = ws.sentMessages
+      .map((raw) => JSON.parse(raw) as { type: string; token?: string })
+      .filter((m) => m.type === 'text');
+    expect(textMessages.some((m) => (m.token ?? '').includes('callback'))).toBe(true);
+
+    mockConfig.calls.userConsultTimeoutSeconds = 120;
+    relay.destroy();
+  });
+
+  test('no callback opt-in + access timeout -> no callback handoff notification', async () => {
+    mockConfig.calls.userConsultTimeoutSeconds = 2;
+
+    ensureConversation('conv-no-cb-handoff');
+    const session = createCallSession({
+      conversationId: 'conv-no-cb-handoff',
+      provider: 'twilio',
+      fromNumber: '+15557770021',
+      toNumber: '+15551111111',
+      assistantId: 'self',
+    });
+
+    const { relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_no_cb_handoff',
+      from: '+15557770021',
+      to: '+15551111111',
+    }));
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'No Callback Tester',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    expect(relay.getConnectionState()).toBe('awaiting_guardian_decision');
+
+    // Wait for timeout without opting into callback
+    await new Promise((resolve) => setTimeout(resolve, 2500));
+
+    expect(relay.getConnectionState()).toBe('disconnecting');
+
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    const events = getCallEvents(session.id);
+    // Should NOT have callback handoff events
+    const handoffEvents = events.filter(
+      (e) => e.eventType === 'callback_handoff_notified' || e.eventType === 'callback_handoff_failed',
+    );
+    expect(handoffEvents.length).toBe(0);
+
+    mockConfig.calls.userConsultTimeoutSeconds = 120;
+    relay.destroy();
+  });
+
+  test('callback opt-in + transport close during guardian wait -> emits callback handoff notification', async () => {
+    ensureConversation('conv-cb-handoff-transport');
+    const session = createCallSession({
+      conversationId: 'conv-cb-handoff-transport',
+      provider: 'twilio',
+      fromNumber: '+15557770022',
+      toNumber: '+15551111111',
+      assistantId: 'self',
+    });
+
+    const { relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_cb_handoff_transport',
+      from: '+15557770022',
+      to: '+15551111111',
+    }));
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Transport Close Tester',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    expect(relay.getConnectionState()).toBe('awaiting_guardian_decision');
+
+    // Trigger callback offer and opt-in (callback decisions bypass cooldown)
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Hurry up please',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Yes, call me back please',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    // Simulate transport close while still in guardian wait
+    relay.handleTransportClosed(1001, 'Going away');
+
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    const events = getCallEvents(session.id);
+    const handoffEvents = events.filter(
+      (e) => e.eventType === 'callback_handoff_notified' || e.eventType === 'callback_handoff_failed',
+    );
+    expect(handoffEvents.length).toBe(1);
+
+    relay.destroy();
+  });
+
+  test('timeout then transport-close race -> still emits only one handoff notification', async () => {
+    mockConfig.calls.userConsultTimeoutSeconds = 2;
+
+    ensureConversation('conv-cb-handoff-race');
+    const session = createCallSession({
+      conversationId: 'conv-cb-handoff-race',
+      provider: 'twilio',
+      fromNumber: '+15557770023',
+      toNumber: '+15551111111',
+      assistantId: 'self',
+    });
+
+    const { relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_cb_handoff_race',
+      from: '+15557770023',
+      to: '+15551111111',
+    }));
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Race Tester',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    // Opt into callback (callback decisions bypass cooldown)
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Hurry up please',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Yes call me back',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    // Wait for timeout to fire (2s) plus settling time
+    await new Promise((resolve) => setTimeout(resolve, 2500));
+
+    // Now transport close too (simulating race)
+    relay.handleTransportClosed(1000, 'Normal closure');
+
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    const events = getCallEvents(session.id);
+    // Guard should ensure only ONE handoff event
+    const handoffEvents = events.filter(
+      (e) => e.eventType === 'callback_handoff_notified' || e.eventType === 'callback_handoff_failed',
+    );
+    expect(handoffEvents.length).toBe(1);
+
+    mockConfig.calls.userConsultTimeoutSeconds = 120;
+    relay.destroy();
+  });
+
+  test('callback handoff payload includes requesterMemberId when voice caller maps to existing member', async () => {
+    mockConfig.calls.userConsultTimeoutSeconds = 2;
+
+    ensureConversation('conv-cb-handoff-member');
+    const session = createCallSession({
+      conversationId: 'conv-cb-handoff-member',
+      provider: 'twilio',
+      fromNumber: '+15557770024',
+      toNumber: '+15551111111',
+      assistantId: 'self',
+    });
+
+    const { relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_cb_handoff_member',
+      from: '+15557770024',
+      to: '+15551111111',
+    }));
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Member Tester',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    expect(relay.getConnectionState()).toBe('awaiting_guardian_decision');
+
+    // Add the caller as a trusted contact AFTER the access request flow
+    // is entered so resolveActorTrust doesn't skip the flow. The handoff
+    // code uses findMember to resolve requesterMemberId at handoff time.
+    addTrustedVoiceContact('+15557770024');
+
+    // Opt into callback (callback decisions bypass cooldown)
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Hurry up',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Yes please call me back',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    // Wait for timeout (2s) plus settling time
+    await new Promise((resolve) => setTimeout(resolve, 2500));
+
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    const events = getCallEvents(session.id);
+    const handoffEvents = events.filter(
+      (e) => e.eventType === 'callback_handoff_notified' || e.eventType === 'callback_handoff_failed',
+    );
+    expect(handoffEvents.length).toBe(1);
+
+    // Parse the payload to verify requesterMemberId is present
+    const handoffEvent = handoffEvents[0];
+    const payload = JSON.parse(handoffEvent.payloadJson) as Record<string, unknown>;
+    // The member was added, so requesterMemberId should be populated
+    expect(payload.requesterMemberId).toBeDefined();
+    expect(typeof payload.requesterMemberId).toBe('string');
+
+    mockConfig.calls.userConsultTimeoutSeconds = 120;
+    relay.destroy();
+  });
+
+  test('callback handoff payload omits member reference when no member record exists', async () => {
+    mockConfig.calls.userConsultTimeoutSeconds = 2;
+
+    ensureConversation('conv-cb-handoff-no-member');
+    const session = createCallSession({
+      conversationId: 'conv-cb-handoff-no-member',
+      provider: 'twilio',
+      fromNumber: '+15557770025',
+      toNumber: '+15551111111',
+      assistantId: 'self',
+    });
+
+    // Do NOT add caller as trusted contact
+
+    const { relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_cb_handoff_no_member',
+      from: '+15557770025',
+      to: '+15551111111',
+    }));
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'No Member Tester',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    expect(relay.getConnectionState()).toBe('awaiting_guardian_decision');
+
+    // Opt into callback (callback decisions bypass cooldown)
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Come on hurry up',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'Yes callback please',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    // Wait for timeout (2s) plus settling time
+    await new Promise((resolve) => setTimeout(resolve, 2500));
+
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    const events = getCallEvents(session.id);
+    const handoffEvents = events.filter(
+      (e) => e.eventType === 'callback_handoff_notified' || e.eventType === 'callback_handoff_failed',
+    );
+    expect(handoffEvents.length).toBe(1);
+
+    // Parse the payload to verify requesterMemberId is null
+    const handoffEvent = handoffEvents[0];
+    const payload = JSON.parse(handoffEvent.payloadJson) as Record<string, unknown>;
+    expect(payload.requesterMemberId).toBeNull();
 
+    mockConfig.calls.userConsultTimeoutSeconds = 120;
     relay.destroy();
   });
 });