@vellumai/assistant 0.10.4 → 0.10.5-dev.202607022329.d89bf2f

package/src/__tests__/media-stream-server-integration.test.ts

@@ -12,10 +12,13 @@ import {
 // Module mocks — declared before imports of the module under test.
 // ---------------------------------------------------------------------------
 
-// Mock the STT resolve module (used by MediaStreamSttSession)
+// Mock the STT resolve module (used by MediaStreamSttSession).
+// resolveStreamingTranscriber yields no transcriber, so sessions settle on
+// the batch path regardless of the calls.voice.telephonyStreaming default.
 mock.module("../providers/speech-to-text/resolve.js", () => ({
   resolveTelephonySttCapability: jest.fn(),
   resolveBatchTranscriber: jest.fn(),
+  resolveStreamingTranscriber: jest.fn(async () => null),
 }));
 
 // Mock the logger to suppress output during tests
@@ -98,28 +101,33 @@ mock.module("../calls/finalize-call.js", () => ({
 
 // Mock the call pointer messages
 mock.module("../calls/call-pointer-messages.js", () => ({
-  addPointerMessage: jest.fn(async () => {}),
+  postPointerMessageSafe: jest.fn(),
   formatDuration: jest.fn((ms: number) => `${Math.round(ms / 1000)}s`),
 }));
 
 // Mock the CallController to avoid pulling in the full conversation pipeline
 const mockStartInitialGreeting = jest.fn(async () => {});
+const mockStartPostVerificationGreeting = jest.fn(async () => {});
+const mockMarkNextCallerTurnAsOpeningAck = jest.fn();
 const mockHandleCallerUtterance = jest.fn(async () => {});
 const mockHandleInterrupt = jest.fn();
 const mockDestroy = jest.fn();
 
-const mockHandleBargeIn = jest.fn(() => false);
+// Mirrors CallController.handleBargeIn: invokes onAccepted only when the
+// barge-in passes the speaking gate.
+const mockHandleBargeIn = jest.fn((_onAccepted?: () => void) => false);
 
 mock.module("../calls/call-controller.js", () => ({
   CallController: jest.fn().mockImplementation(() => ({
     startInitialGreeting: mockStartInitialGreeting,
+    startPostVerificationGreeting: mockStartPostVerificationGreeting,
+    markNextCallerTurnAsOpeningAck: mockMarkNextCallerTurnAsOpeningAck,
     handleCallerUtterance: mockHandleCallerUtterance,
     handleInterrupt: mockHandleInterrupt,
     handleBargeIn: mockHandleBargeIn,
     destroy: mockDestroy,
     getState: jest.fn(() => "idle"),
     setTrustContext: jest.fn(),
-    markNextCallerTurnAsOpeningAck: jest.fn(),
     getPendingConsultationQuestionId: jest.fn(),
     handleUserAnswer: jest.fn(),
     handleUserInstruction: jest.fn(),
@@ -177,11 +185,20 @@ mock.module("../calls/channel-admission-reader.js", () => ({
 }));
 
 // Mock the inbound trust reader. handleStart awaits this and threads the
-// verdict into routeSetup so the media-stream transport enforces the same
-// gateway ACL as ConversationRelay. Tests override mockInboundVerdict.
+// verdict into routeSetup so the media-stream transport enforces the
+// gateway ACL. Tests override mockInboundVerdict.
+// The optional gate lets a test hold mid-setup trust re-resolution open
+// (the setup flow's default resolver reads the verdict first) so it can
+// deliver transcripts during the deferral window.
 let mockInboundVerdict: unknown = null;
+let mockVerdictGate: Promise<void> | null = null;
 const mockGetInboundTrustVerdict = jest.fn(
-  async (_args?: Record<string, unknown>) => mockInboundVerdict,
+  async (_args?: Record<string, unknown>) => {
+    if (mockVerdictGate) {
+      await mockVerdictGate;
+    }
+    return mockInboundVerdict;
+  },
 );
 mock.module("../calls/inbound-trust-reader.js", () => ({
   getInboundTrustVerdict: mockGetInboundTrustVerdict,
@@ -225,12 +242,152 @@ mock.module("../calls/resolve-call-tts-provider.js", () => ({
   })),
 }));
 
+// ── Setup-flow dependency mocks ─────────────────────────────────────────
+// MediaStreamCallSession drives every routeSetup outcome through a real
+// CallSetupFlow (and, for name capture, a real GuardianWaitController).
+// Mock the side-effectful modules those pull in: config-backed timing
+// constants, guardian labels, verification/invite services, the guardian
+// notifier, canonical-request polling, and wait heartbeats.
+
+// Config-backed call constants — small real-timer-friendly values.
+let mockTtsPlaybackDelayMs = 5;
+let mockAccessRequestPollIntervalMs = 5;
+let mockUserConsultationTimeoutMs = 500;
+mock.module("../calls/call-constants.js", () => ({
+  isDeniedNumber: jest.fn(() => false),
+  getMaxCallDurationMs: jest.fn(() => 3_600_000),
+  getUserConsultationTimeoutMs: jest.fn(() => mockUserConsultationTimeoutMs),
+  getTtsPlaybackDelayMs: jest.fn(() => mockTtsPlaybackDelayMs),
+  getAccessRequestPollIntervalMs: jest.fn(
+    () => mockAccessRequestPollIntervalMs,
+  ),
+  getGuardianWaitUpdateInitialIntervalMs: jest.fn(() => 10_000),
+  getGuardianWaitUpdateInitialWindowMs: jest.fn(() => 60_000),
+  getGuardianWaitUpdateSteadyMinIntervalMs: jest.fn(() => 20_000),
+  getGuardianWaitUpdateSteadyMaxIntervalMs: jest.fn(() => 40_000),
+  getSilenceTimeoutMs: jest.fn(() => 30_000),
+  getEndCallListenWindowMs: jest.fn(() => 15_000),
+}));
+
+// Guardian delivery reader (IPC-backed): label priming + cache warming.
+mock.module("../contacts/guardian-delivery-reader.js", () => ({
+  getGuardianDelivery: jest.fn(async () => [
+    { channelType: "phone", status: "active", displayName: "Alex" },
+  ]),
+  getGuardianDeliveryFresh: jest.fn(async () => []),
+  peekCachedGuardianDelivery: jest.fn(() => null),
+  voiceGuardianDisplayName: jest.fn(() => "Alex"),
+  guardianForChannel: jest.fn(),
+  anyGuardian: jest.fn(),
+  invalidateGuardianDeliveryCache: jest.fn(),
+}));
+
+// Guardian/assistant display labels (filesystem-backed).
+mock.module("../prompts/user-reference.js", () => ({
+  DEFAULT_USER_REFERENCE: "my human",
+  resolveGuardianName: jest.fn(
+    (primed?: string | null) => primed ?? "my human",
+  ),
+}));
+mock.module("../daemon/identity-helpers.js", () => ({
+  getAssistantName: jest.fn(() => "Aria"),
+  resolveUserName: jest.fn(() => null),
+}));
+
+// Conversation persistence (used by callee verification code posting).
+const mockAddMessage = jest.fn(async () => ({}));
+mock.module("../persistence/conversation-crud.js", () => ({
+  addMessage: mockAddMessage,
+}));
+
+// Verification / invite services (gateway + verification-store backed).
+type MockVerificationResult =
+  | {
+      outcome: "success";
+      verificationType: "guardian" | "trusted_contact";
+      eventName: string;
+      ttsMessage?: string;
+    }
+  | {
+      outcome: "failure";
+      eventName: string;
+      ttsMessage: string;
+      attempts: number;
+    }
+  | {
+      outcome: "retry";
+      ttsMessage: string;
+      attempt: number;
+      maxAttempts: number;
+    };
+let mockVerificationResult: MockVerificationResult = {
+  outcome: "success",
+  verificationType: "guardian",
+  eventName: "voice_verification_succeeded",
+};
+const mockAttemptVerificationCode = jest.fn(async () => mockVerificationResult);
+type MockInviteResult =
+  | { outcome: "success"; memberId: string; inviteId: string; type: string }
+  | { outcome: "failure"; ttsMessage: string };
+let mockInviteResult: MockInviteResult = {
+  outcome: "success",
+  memberId: "member-1",
+  inviteId: "invite-1",
+  type: "trusted_contact",
+};
+const mockAttemptInviteCodeRedemption = jest.fn(async () => mockInviteResult);
+mock.module("../calls/relay-verification.js", () => ({
+  attemptVerificationCode: mockAttemptVerificationCode,
+  attemptInviteCodeRedemption: mockAttemptInviteCodeRedemption,
+  parseDigitsFromSpeech: jest.fn((text: string) => text.replace(/\D+/g, "")),
+}));
+
+// Guardian access-request notifier (name-capture sub-flow).
+type MockNotifyResult =
+  | { notified: true; created: boolean; requestId: string }
+  | { notified: false; reason: string };
+let mockNotifyResult: MockNotifyResult = {
+  notified: true,
+  created: true,
+  requestId: "req-1",
+};
+const mockNotifyGuardianOfAccessRequest = jest.fn(async () => mockNotifyResult);
+mock.module("../runtime/access-request-helper.js", () => ({
+  notifyGuardianOfAccessRequest: mockNotifyGuardianOfAccessRequest,
+}));
+
+// Canonical guardian-request store polled by the guardian wait controller.
+let mockCanonicalRequest: { status: string } | null = null;
+const mockGetCanonicalGuardianRequest = jest.fn(() => mockCanonicalRequest);
+mock.module("../contacts/canonical-guardian-store.js", () => ({
+  getCanonicalGuardianRequest: mockGetCanonicalGuardianRequest,
+}));
+
+// Wait-state helpers: no heartbeats in tests; capture callback handoffs.
+const mockEmitCallbackHandoff = jest.fn(
+  (args: { callbackHandoffNotified: boolean }) => ({
+    callbackHandoffNotified: args.callbackHandoffNotified,
+    notified: false,
+  }),
+);
+mock.module("../calls/relay-access-wait.js", () => ({
+  classifyWaitUtterance: jest.fn(() => "neutral"),
+  scheduleNextHeartbeat: jest.fn(() => null),
+  emitAccessRequestCallbackHandoff: mockEmitCallbackHandoff,
+}));
+
 // ---------------------------------------------------------------------------
 // Now import the module under test.
 // ---------------------------------------------------------------------------
 
+import { revokeScopedApprovalGrantsForContext } from "../approvals/scoped-approval-grants.js";
+import { CallController } from "../calls/call-controller.js";
+import { postPointerMessageSafe } from "../calls/call-pointer-messages.js";
 import { speakSystemPrompt } from "../calls/call-speech-output.js";
-import { registerCallController } from "../calls/call-state.js";
+import {
+  fireCallTranscriptNotifier,
+  registerCallController,
+} from "../calls/call-state.js";
 import { recordCallEvent, updateCallSession } from "../calls/call-store.js";
 import { finalizeCall } from "../calls/finalize-call.js";
 import {
@@ -358,22 +515,51 @@ beforeEach(() => {
   mockControllers.clear();
   activeMediaStreamSessions.clear();
   mockStartInitialGreeting.mockClear();
+  mockStartPostVerificationGreeting.mockClear();
+  mockMarkNextCallerTurnAsOpeningAck.mockClear();
   mockHandleCallerUtterance.mockClear();
   mockHandleInterrupt.mockClear();
   mockHandleBargeIn.mockClear();
   mockHandleBargeIn.mockReturnValue(false);
   mockDestroy.mockClear();
+  (CallController as unknown as jest.Mock).mockClear();
   (registerCallController as jest.Mock).mockClear();
+  (fireCallTranscriptNotifier as jest.Mock).mockClear();
   (recordCallEvent as jest.Mock).mockClear();
   (updateCallSession as jest.Mock).mockClear();
   (finalizeCall as jest.Mock).mockClear();
+  (revokeScopedApprovalGrantsForContext as jest.Mock).mockClear();
   (speakSystemPrompt as jest.Mock).mockClear();
+  (postPointerMessageSafe as jest.Mock).mockClear();
   (routeSetup as jest.Mock).mockClear();
   mockGetChannelAdmissionPolicy.mockClear();
   mockAdmissionPolicy = null;
   mockAdmissionGate = null;
   mockGetInboundTrustVerdict.mockClear();
   mockInboundVerdict = null;
+  mockVerdictGate = null;
+  mockAddMessage.mockClear();
+  mockAttemptVerificationCode.mockClear();
+  mockVerificationResult = {
+    outcome: "success",
+    verificationType: "guardian",
+    eventName: "voice_verification_succeeded",
+  };
+  mockAttemptInviteCodeRedemption.mockClear();
+  mockInviteResult = {
+    outcome: "success",
+    memberId: "member-1",
+    inviteId: "invite-1",
+    type: "trusted_contact",
+  };
+  mockNotifyGuardianOfAccessRequest.mockClear();
+  mockNotifyResult = { notified: true, created: true, requestId: "req-1" };
+  mockGetCanonicalGuardianRequest.mockClear();
+  mockCanonicalRequest = null;
+  mockEmitCallbackHandoff.mockClear();
+  mockTtsPlaybackDelayMs = 5;
+  mockAccessRequestPollIntervalMs = 5;
+  mockUserConsultationTimeoutMs = 500;
   // Reset routeSetup to default normal_call
   mockRouteSetupResult = {
     outcome: { action: "normal_call" as const, isInbound: true },
@@ -404,7 +590,6 @@ describe("MediaStreamCallSession", () => {
     const session = new MediaStreamCallSession(ws, "call-1");
     expect(session.callSessionId).toBe("call-1");
     expect(session.getOutput()).toBeDefined();
-    expect(session.getOutput().getConnectionState()).toBe("connected");
   });
 
   describe("start event handling", () => {
@@ -472,7 +657,7 @@ describe("MediaStreamCallSession", () => {
   });
 
   describe("transport close handling", () => {
-    test("normal close (1000) marks session as completed", () => {
+    test("normal close (1000) marks session as completed and writes the completed pointer", () => {
       const mock = createMockWs();
       mockSessions.set("call-1", {
         id: "call-1",
@@ -480,6 +665,7 @@ describe("MediaStreamCallSession", () => {
         status: "in_progress",
         startedAt: Date.now() - 60000,
         toNumber: "+15551234567",
+        initiatedFromConversationId: "conv-origin",
       });
 
       const session = new MediaStreamCallSession(mock.ws, "call-1");
@@ -490,9 +676,15 @@ describe("MediaStreamCallSession", () => {
         expect.objectContaining({ status: "completed" }),
       );
       expect(finalizeCall).toHaveBeenCalledWith("call-1", "conv-1");
+      expect(postPointerMessageSafe).toHaveBeenCalledWith(
+        "conv-origin",
+        "completed",
+        "+15551234567",
+        expect.objectContaining({ duration: expect.any(String) }),
+      );
     });
 
-    test("abnormal close marks session as failed", () => {
+    test("abnormal close marks session as failed and writes the failed pointer", () => {
       const mock = createMockWs();
       mockSessions.set("call-1", {
         id: "call-1",
@@ -500,6 +692,7 @@ describe("MediaStreamCallSession", () => {
         status: "in_progress",
         startedAt: Date.now() - 60000,
         toNumber: "+15551234567",
+        initiatedFromConversationId: "conv-origin",
       });
 
       const session = new MediaStreamCallSession(mock.ws, "call-1");
@@ -513,6 +706,12 @@ describe("MediaStreamCallSession", () => {
         }),
       );
       expect(finalizeCall).toHaveBeenCalledWith("call-1", "conv-1");
+      expect(postPointerMessageSafe).toHaveBeenCalledWith(
+        "conv-origin",
+        "failed",
+        "+15551234567",
+        expect.objectContaining({ reason: expect.any(String) }),
+      );
     });
 
     test("close on already-terminal session is a no-op", () => {
@@ -552,7 +751,6 @@ describe("MediaStreamCallSession", () => {
 
       session.destroy();
       expect(mockDestroy).toHaveBeenCalled();
-      expect(session.getOutput().getConnectionState()).toBe("closed");
     });
 
     test("destroy is idempotent", () => {
@@ -955,157 +1153,7 @@ describe("media-stream setup outcome scenarios", () => {
     });
   });
 
-  describe("unsupported interactive setup flow", () => {
-    test("verification outcome records call_failed with preflight-bypass reason", async () => {
-      mockRouteSetupResult = {
-        outcome: {
-          action: "verification",
-          assistantId: "self",
-          fromNumber: "+14155551234",
-        },
-        resolved: {
-          assistantId: "self",
-          isInbound: true,
-          otherPartyNumber: "+14155551234",
-          actorTrust: { trustClass: "unknown", memberRecord: null },
-        },
-      };
-
-      const mockWs = createMockWs();
-      mockSessions.set("call-unsup-verify-1", {
-        id: "call-unsup-verify-1",
-        conversationId: "conv-unsup-verify-1",
-        status: "initiated",
-        task: null,
-        startedAt: null,
-        fromNumber: "+14155551234",
-        toNumber: "+15550001111",
-      });
-
-      const session = new MediaStreamCallSession(
-        mockWs.ws,
-        "call-unsup-verify-1",
-      );
-      session.handleMessage(makeStartMessage());
-      await session.whenSetupSettled();
-
-      // Should record call_failed event with preflight-bypass note
-      expect(recordCallEvent).toHaveBeenCalledWith(
-        "call-unsup-verify-1",
-        "call_failed",
-        expect.objectContaining({
-          reason: expect.stringContaining("verification"),
-          transport: "media-stream",
-        }),
-      );
-
-      // Should set session status to failed
-      expect(updateCallSession).toHaveBeenCalledWith(
-        "call-unsup-verify-1",
-        expect.objectContaining({
-          status: "failed",
-          lastError: expect.stringContaining("preflight guard"),
-        }),
-      );
-
-      // Should NOT register a controller
-      expect(registerCallController).not.toHaveBeenCalled();
-    });
-
-    test("name_capture outcome speaks generic apology and tears down", async () => {
-      mockRouteSetupResult = {
-        outcome: {
-          action: "name_capture",
-          assistantId: "self",
-          fromNumber: "+14155551234",
-        },
-        resolved: {
-          assistantId: "self",
-          isInbound: true,
-          otherPartyNumber: "+14155551234",
-          actorTrust: { trustClass: "unknown", memberRecord: null },
-        },
-      };
-
-      const mockWs = createMockWs();
-      mockSessions.set("call-unsup-name-1", {
-        id: "call-unsup-name-1",
-        conversationId: "conv-unsup-name-1",
-        status: "initiated",
-        task: null,
-        startedAt: null,
-        fromNumber: "+14155551234",
-        toNumber: "+15550001111",
-      });
-
-      const session = new MediaStreamCallSession(
-        mockWs.ws,
-        "call-unsup-name-1",
-      );
-      session.handleMessage(makeStartMessage());
-      await session.whenSetupSettled();
-
-      // speakSystemPrompt should be called with the generic apology
-      expect(speakSystemPrompt).toHaveBeenCalledWith(
-        expect.anything(),
-        expect.stringContaining("additional verification"),
-      );
-
-      // Should run finalization inline
-      expect(finalizeCall).toHaveBeenCalledWith(
-        "call-unsup-name-1",
-        "conv-unsup-name-1",
-      );
-    });
-
-    test("callee_verification outcome fails with explicit reason", async () => {
-      mockRouteSetupResult = {
-        outcome: {
-          action: "callee_verification",
-          verificationConfig: { maxAttempts: 3, codeLength: 6 },
-        },
-        resolved: {
-          assistantId: "self",
-          isInbound: false,
-          otherPartyNumber: "+14155551234",
-          actorTrust: { trustClass: "guardian", memberRecord: null },
-        },
-      };
-
-      const mockWs = createMockWs();
-      mockSessions.set("call-unsup-callee-1", {
-        id: "call-unsup-callee-1",
-        conversationId: "conv-unsup-callee-1",
-        status: "initiated",
-        task: null,
-        startedAt: null,
-        fromNumber: "+15550001111",
-        toNumber: "+14155551234",
-      });
-
-      const session = new MediaStreamCallSession(
-        mockWs.ws,
-        "call-unsup-callee-1",
-      );
-      session.handleMessage(makeStartMessage());
-      await session.whenSetupSettled();
-
-      // Should record the failure with the specific action
-      expect(recordCallEvent).toHaveBeenCalledWith(
-        "call-unsup-callee-1",
-        "call_failed",
-        expect.objectContaining({
-          reason: expect.stringContaining("callee_verification"),
-        }),
-      );
-
-      // Session should be failed
-      expect(updateCallSession).toHaveBeenCalledWith(
-        "call-unsup-callee-1",
-        expect.objectContaining({ status: "failed" }),
-      );
-    });
-
+  describe("normal_call reset after deny", () => {
     test("normal_call after deny scenario still creates controller", async () => {
       // Verify that after a deny-scenario test, resetting to normal_call
       // properly creates a controller (no cross-test pollution).
@@ -1179,6 +1227,15 @@ describe("media-stream setup outcome scenarios", () => {
       expect(mockHandleBargeIn).toHaveBeenCalled();
       expect(mockHandleInterrupt).not.toHaveBeenCalled();
 
+      // An ignored barge-in flushes only Twilio's buffered audio (to
+      // stop a completed turn's tail talking over the caller). The
+      // internal playback queue is untouched, so the queued greeting
+      // still plays — handleInterrupt must not have run.
+      const clearCommands = mockWs.sent.filter(
+        (s) => JSON.parse(s).event === "clear",
+      );
+      expect(clearCommands.length).toBeGreaterThan(0);
+
       // voice_session_aborted should NOT appear in recorded events
       const abortEvents = mockEvents.filter(
         (e) =>
@@ -1191,8 +1248,12 @@ describe("media-stream setup outcome scenarios", () => {
     });
 
     test("barge-in is accepted when controller is speaking", async () => {
-      // Configure mock to indicate the controller is speaking
-      mockHandleBargeIn.mockReturnValue(true);
+      // Configure mock to indicate the controller is speaking; like the
+      // real controller, it fires onAccepted before interrupting.
+      mockHandleBargeIn.mockImplementation((onAccepted?: () => void) => {
+        onAccepted?.();
+        return true;
+      });
 
       const mockWs = createMockWs();
       mockSessions.set("call-bargein-2", {
@@ -1213,8 +1274,13 @@ describe("media-stream setup outcome scenarios", () => {
       const speechPayload = Buffer.alloc(160, 0x00).toString("base64");
       session.handleMessage(makeMediaMessage(speechPayload, "1"));
 
-      // handleBargeIn should have been called (returning true)
+      // handleBargeIn should have been called (returning true), and the
+      // accepted barge-in flushes outbound audio via the onAccepted hook.
       expect(mockHandleBargeIn).toHaveBeenCalled();
+      const clearCommands = mockWs.sent.filter(
+        (s) => JSON.parse(s).event === "clear",
+      );
+      expect(clearCommands.length).toBe(1);
 
       session.destroy();
     });
@@ -1556,9 +1622,9 @@ describe("media-stream setup outcome scenarios", () => {
 
   // ── Gateway trust verdict ──────────────────────────────────────────
   // handleStart fetches getInboundTrustVerdict for the inbound caller and
-  // threads it into routeSetup, so the media-stream transport enforces the
-  // same gateway ACL as ConversationRelay. routeSetup itself decides
-  // verdict-vs-local; these tests assert the verdict is fetched and passed.
+  // threads it into routeSetup, so the media-stream transport enforces
+  // the gateway ACL. routeSetup itself decides verdict-vs-local; these
+  // tests assert the verdict is fetched and passed.
 
   describe("gateway trust verdict", () => {
     test("fetches the inbound caller's verdict and threads it into routeSetup", async () => {
@@ -1663,3 +1729,711 @@ describe("media-stream setup outcome scenarios", () => {
     });
   });
 });
+
+// ---------------------------------------------------------------------------
+// Setup-flow integration scenarios
+// ---------------------------------------------------------------------------
+// Drive every interactive routeSetup outcome end to end through the real
+// CallSetupFlow (and, for name capture, the real GuardianWaitController)
+// over a fake WebSocket. These use real timers with small mocked timing
+// constants so terminal hangups and guardian-wait polling actually fire.
+
+describe("setup flows over the media-stream transport", () => {
+  beforeEach(() => {
+    jest.useRealTimers();
+  });
+
+  const FROM = "+14155550100";
+  const TO = "+15550001111";
+
+  const sleep = (ms = 15) => Bun.sleep(ms);
+
+  function setupCall(opts: {
+    callId: string;
+    outcome: { action: string; [key: string]: unknown };
+    resolved?: Partial<(typeof mockRouteSetupResult)["resolved"]>;
+    session?: Record<string, unknown>;
+  }) {
+    mockRouteSetupResult = {
+      outcome: opts.outcome,
+      resolved: {
+        assistantId: "self",
+        isInbound: true,
+        otherPartyNumber: FROM,
+        actorTrust: { trustClass: "unknown", memberRecord: null },
+        ...opts.resolved,
+      },
+    };
+    mockSessions.set(opts.callId, {
+      id: opts.callId,
+      conversationId: `conv-${opts.callId}`,
+      status: "initiated",
+      task: null,
+      startedAt: null,
+      fromNumber: FROM,
+      toNumber: TO,
+      ...opts.session,
+    });
+    const mockWs = createMockWs();
+    const session = new MediaStreamCallSession(mockWs.ws, opts.callId);
+    session.handleMessage(makeStartMessage());
+    return { session, mockWs };
+  }
+
+  /**
+   * Deliver a final caller transcript, mirroring the STT session's
+   * onTranscriptFinal callback wiring (driving real audio through the
+   * batch transcriber is out of scope for these tests).
+   */
+  function deliverTranscript(
+    session: MediaStreamCallSession,
+    text: string,
+  ): void {
+    (
+      session as unknown as {
+        handleTranscriptFinal(text: string, durationMs: number): void;
+      }
+    ).handleTranscriptFinal(text, 500);
+  }
+
+  function enterDigits(session: MediaStreamCallSession, digits: string): void {
+    for (const digit of digits) {
+      session.handleMessage(makeDtmfMessage(digit));
+    }
+  }
+
+  function callerSpokeEvents(callId: string) {
+    return mockEvents.filter(
+      (e) => e.callSessionId === callId && e.eventType === "caller_spoke",
+    );
+  }
+
+  describe("inbound verification", () => {
+    test("success routes DTMF to the flow, then proceeds to the initial greeting", async () => {
+      const { session } = setupCall({
+        callId: "call-verif-ok",
+        outcome: {
+          action: "verification",
+          assistantId: "self",
+          fromNumber: FROM,
+        },
+      });
+      await session.whenSetupSettled();
+
+      // The flow prompts for the code; no controller exists during setup.
+      expect(speakSystemPrompt).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.stringContaining("six-digit verification code"),
+      );
+      expect(session.getSetupFlow()?.getState()).toBe("collecting_code");
+      expect(session.getController()).toBeNull();
+      expect(registerCallController).not.toHaveBeenCalled();
+
+      enterDigits(session, "123456");
+      await sleep();
+
+      expect(mockAttemptVerificationCode).toHaveBeenCalledWith(
+        expect.objectContaining({ enteredCode: "123456", isOutbound: false }),
+      );
+      // The server records per-digit caller_spoke events for the flow.
+      expect(callerSpokeEvents("call-verif-ok")).toHaveLength(6);
+
+      // Flow completed: controller created + initial greeting fired.
+      expect(registerCallController).toHaveBeenCalledWith(
+        "call-verif-ok",
+        expect.anything(),
+      );
+      expect(
+        (CallController as unknown as jest.Mock).mock.calls[0]?.[3],
+      ).toMatchObject({ assistantId: "self" });
+      expect(mockStartInitialGreeting).toHaveBeenCalled();
+      expect(session.getSetupFlow()).toBeNull();
+      expect(session.getController()).not.toBeNull();
+      expect(finalizeCall).not.toHaveBeenCalled();
+
+      // Post-setup transcripts route to the controller.
+      deliverTranscript(session, "hello there");
+      await sleep(5);
+      expect(mockHandleCallerUtterance).toHaveBeenCalledWith("hello there");
+
+      session.destroy();
+    });
+
+    test("failure fails the session, finalizes exactly once, and hangs up", async () => {
+      mockVerificationResult = {
+        outcome: "failure",
+        eventName: "voice_verification_failed",
+        ttsMessage: "Verification failed. Goodbye.",
+        attempts: 3,
+      };
+      const { session, mockWs } = setupCall({
+        callId: "call-verif-fail",
+        outcome: {
+          action: "verification",
+          assistantId: "self",
+          fromNumber: FROM,
+        },
+      });
+      await session.whenSetupSettled();
+
+      enterDigits(session, "000000");
+      await sleep();
+
+      expect(speakSystemPrompt).toHaveBeenCalledWith(
+        expect.anything(),
+        "Verification failed. Goodbye.",
+      );
+      expect(updateCallSession).toHaveBeenCalledWith(
+        "call-verif-fail",
+        expect.objectContaining({ status: "failed" }),
+      );
+      expect(finalizeCall).toHaveBeenCalledTimes(1);
+      expect(finalizeCall).toHaveBeenCalledWith(
+        "call-verif-fail",
+        "conv-call-verif-fail",
+      );
+      expect(registerCallController).not.toHaveBeenCalled();
+
+      // The flow schedules its own delayed endSession.
+      await sleep(30);
+      expect(mockWs.closed).toBe(true);
+
+      // Transport close after flow-side finalization must not double-finalize.
+      session.handleTransportClosed(1000, "session-ended");
+      expect(finalizeCall).toHaveBeenCalledTimes(1);
+
+      session.destroy();
+    });
+  });
+
+  describe("outbound verification", () => {
+    test("success posts the pointer and fires the post-verification greeting", async () => {
+      const { session } = setupCall({
+        callId: "call-outverif",
+        outcome: {
+          action: "outbound_verification",
+          assistantId: "self",
+          sessionId: "verif-sess-1",
+          toNumber: TO,
+        },
+        resolved: {
+          isInbound: false,
+          otherPartyNumber: TO,
+          actorTrust: { trustClass: "guardian", memberRecord: null },
+        },
+        session: { initiatedFromConversationId: "conv-origin-1" },
+      });
+      await session.whenSetupSettled();
+      expect(registerCallController).not.toHaveBeenCalled();
+
+      enterDigits(session, "654321");
+      await sleep();
+
+      expect(mockAttemptVerificationCode).toHaveBeenCalledWith(
+        expect.objectContaining({ enteredCode: "654321", isOutbound: true }),
+      );
+      expect(postPointerMessageSafe).toHaveBeenCalledWith(
+        "conv-origin-1",
+        "verification_succeeded",
+        TO,
+        expect.objectContaining({ channel: "phone" }),
+      );
+      expect(mockStartPostVerificationGreeting).toHaveBeenCalled();
+      expect(mockStartInitialGreeting).not.toHaveBeenCalled();
+      expect(registerCallController).toHaveBeenCalledWith(
+        "call-outverif",
+        expect.anything(),
+      );
+
+      session.destroy();
+    });
+  });
+
+  describe("callee verification", () => {
+    test("posts the code to the origin conversation, retries a wrong code, greets on a match", async () => {
+      const { session } = setupCall({
+        callId: "call-callee",
+        outcome: {
+          action: "callee_verification",
+          verificationConfig: { maxAttempts: 3, codeLength: 4 },
+        },
+        resolved: {
+          isInbound: false,
+          otherPartyNumber: TO,
+          actorTrust: { trustClass: "guardian", memberRecord: null },
+        },
+        session: { initiatedFromConversationId: "conv-origin-2" },
+      });
+      await session.whenSetupSettled();
+
+      // The generated code is posted to the initiating conversation.
+      expect(mockAddMessage).toHaveBeenCalledTimes(1);
+      const [postedConvId, , postedContent] = mockAddMessage.mock
+        .calls[0] as unknown as [string, string, string];
+      expect(postedConvId).toBe("conv-origin-2");
+      const code = /: (\d{4})/.exec(postedContent)?.[1];
+      expect(code).toBeDefined();
+
+      // A wrong code re-prompts without ending the call.
+      const wrongCode = code === "0000" ? "1111" : "0000";
+      enterDigits(session, wrongCode);
+      await sleep();
+      expect(speakSystemPrompt).toHaveBeenCalledWith(
+        expect.anything(),
+        "That code was incorrect. Please try again.",
+      );
+      expect(registerCallController).not.toHaveBeenCalled();
+
+      // The right code proceeds to the initial greeting.
+      enterDigits(session, code!);
+      await sleep();
+      expect(registerCallController).toHaveBeenCalledWith(
+        "call-callee",
+        expect.anything(),
+      );
+      expect(mockStartInitialGreeting).toHaveBeenCalled();
+      expect(finalizeCall).not.toHaveBeenCalled();
+
+      session.destroy();
+    });
+  });
+
+  describe("invite redemption", () => {
+    test("success speaks the handoff, marks the opening ack, and replays deferred transcripts", async () => {
+      const { session } = setupCall({
+        callId: "call-invite",
+        outcome: {
+          action: "invite_redemption",
+          assistantId: "self",
+          fromNumber: FROM,
+          inviteeName: "Casey Example",
+        },
+      });
+      await session.whenSetupSettled();
+
+      expect(speakSystemPrompt).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.stringContaining("Welcome Casey."),
+      );
+
+      // Hold mid-setup trust re-resolution open so a transcript arrives
+      // during the deferral window.
+      let releaseVerdict!: () => void;
+      mockVerdictGate = new Promise<void>((resolve) => {
+        releaseVerdict = resolve;
+      });
+
+      enterDigits(session, "111222");
+      await sleep();
+      expect(mockAttemptInviteCodeRedemption).toHaveBeenCalledWith(
+        expect.objectContaining({ enteredCode: "111222" }),
+      );
+
+      // Caller speaks while the trust upgrade is in flight — deferred, but
+      // the transcript notifier still fires for UI subscribers.
+      deliverTranscript(session, "hi can you help me book a flight");
+      expect(fireCallTranscriptNotifier).toHaveBeenCalledWith(
+        "conv-call-invite",
+        "call-invite",
+        "caller",
+        "hi can you help me book a flight",
+      );
+      expect(mockHandleCallerUtterance).not.toHaveBeenCalled();
+
+      releaseVerdict();
+      await sleep();
+
+      expect(speakSystemPrompt).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.stringContaining("verified that you are Casey"),
+      );
+      expect(mockMarkNextCallerTurnAsOpeningAck).toHaveBeenCalled();
+      expect(mockStartInitialGreeting).not.toHaveBeenCalled();
+      expect(registerCallController).toHaveBeenCalledWith(
+        "call-invite",
+        expect.anything(),
+      );
+      // The deferred transcript replays into the controller after the opener.
+      expect(mockHandleCallerUtterance).toHaveBeenCalledWith(
+        "hi can you help me book a flight",
+      );
+
+      session.destroy();
+    });
+
+    test("failure speaks the failure copy and finalizes exactly once", async () => {
+      mockInviteResult = {
+        outcome: "failure",
+        ttsMessage: "That code is not valid. Goodbye.",
+      };
+      const { session, mockWs } = setupCall({
+        callId: "call-invite-fail",
+        outcome: {
+          action: "invite_redemption",
+          assistantId: "self",
+          fromNumber: FROM,
+          inviteeName: null,
+        },
+      });
+      await session.whenSetupSettled();
+
+      enterDigits(session, "999999");
+      await sleep();
+
+      expect(speakSystemPrompt).toHaveBeenCalledWith(
+        expect.anything(),
+        "That code is not valid. Goodbye.",
+      );
+      expect(updateCallSession).toHaveBeenCalledWith(
+        "call-invite-fail",
+        expect.objectContaining({ status: "failed" }),
+      );
+      expect(finalizeCall).toHaveBeenCalledTimes(1);
+      expect(registerCallController).not.toHaveBeenCalled();
+
+      await sleep(30);
+      expect(mockWs.closed).toBe(true);
+      session.handleTransportClosed(1000, "session-ended");
+      expect(finalizeCall).toHaveBeenCalledTimes(1);
+
+      session.destroy();
+    });
+  });
+
+  describe("name capture and guardian wait", () => {
+    function nameCaptureOutcome() {
+      return {
+        action: "name_capture",
+        assistantId: "self",
+        fromNumber: FROM,
+      };
+    }
+
+    test("waits for the guardian with NO controller, then approval hands off", async () => {
+      const { session } = setupCall({
+        callId: "call-name-ok",
+        outcome: nameCaptureOutcome(),
+      });
+      await session.whenSetupSettled();
+
+      expect(speakSystemPrompt).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.stringContaining("Can I get your name?"),
+      );
+      expect(session.getSetupFlow()?.getState()).toBe("capturing_name");
+
+      mockCanonicalRequest = { status: "pending" };
+      deliverTranscript(session, "Casey Example");
+      await sleep();
+
+      expect(mockNotifyGuardianOfAccessRequest).toHaveBeenCalledWith(
+        expect.objectContaining({ actorDisplayName: "Casey Example" }),
+      );
+      // The transcript notifier fires for caller turns during setup.
+      expect(fireCallTranscriptNotifier).toHaveBeenCalledWith(
+        "conv-call-name-ok",
+        "call-name-ok",
+        "caller",
+        "Casey Example",
+      );
+      expect(updateCallSession).toHaveBeenCalledWith("call-name-ok", {
+        status: "waiting_on_user",
+      });
+      // No controller exists during the wait — no silence nudges can fire.
+      expect(session.getSetupFlow()?.getState()).toBe(
+        "awaiting_guardian_decision",
+      );
+      expect(session.getController()).toBeNull();
+      expect(CallController as unknown as jest.Mock).not.toHaveBeenCalled();
+      expect(registerCallController).not.toHaveBeenCalled();
+
+      // The guardian approves; the wait poll picks it up.
+      mockCanonicalRequest = { status: "approved" };
+      await sleep(40);
+
+      expect(speakSystemPrompt).toHaveBeenCalledWith(
+        expect.anything(),
+        "Great! Alex said I can speak with you. How can I help?",
+      );
+      expect(mockMarkNextCallerTurnAsOpeningAck).toHaveBeenCalled();
+      expect(registerCallController).toHaveBeenCalledWith(
+        "call-name-ok",
+        expect.anything(),
+      );
+      expect(session.getSetupFlow()).toBeNull();
+      expect(finalizeCall).not.toHaveBeenCalled();
+
+      session.destroy();
+    });
+
+    test("guardian denial speaks the goodbye copy and finalizes exactly once", async () => {
+      const { session, mockWs } = setupCall({
+        callId: "call-name-deny",
+        outcome: nameCaptureOutcome(),
+      });
+      await session.whenSetupSettled();
+
+      mockCanonicalRequest = { status: "pending" };
+      deliverTranscript(session, "Casey Example");
+      await sleep();
+
+      mockCanonicalRequest = { status: "denied" };
+      await sleep(40);
+
+      expect(speakSystemPrompt).toHaveBeenCalledWith(
+        expect.anything(),
+        "Sorry, Alex says I'm not allowed to speak with you. Goodbye.",
+      );
+      expect(updateCallSession).toHaveBeenCalledWith(
+        "call-name-deny",
+        expect.objectContaining({ status: "failed" }),
+      );
+      expect(finalizeCall).toHaveBeenCalledTimes(1);
+      expect(registerCallController).not.toHaveBeenCalled();
+
+      await sleep(30);
+      expect(mockWs.closed).toBe(true);
+      session.handleTransportClosed(1000, "session-ended");
+      expect(finalizeCall).toHaveBeenCalledTimes(1);
+
+      session.destroy();
+    });
+
+    test("guardian-wait timeout speaks the timeout copy and finalizes exactly once", async () => {
+      mockUserConsultationTimeoutMs = 40;
+      const { session } = setupCall({
+        callId: "call-name-timeout",
+        outcome: nameCaptureOutcome(),
+      });
+      await session.whenSetupSettled();
+
+      mockCanonicalRequest = { status: "pending" };
+      deliverTranscript(session, "Casey Example");
+      await sleep();
+
+      await sleep(80);
+
+      expect(mockEmitCallbackHandoff).toHaveBeenCalledWith(
+        expect.objectContaining({ reason: "timeout" }),
+      );
+      expect(speakSystemPrompt).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.stringContaining("Sorry, I can't get ahold of Alex right now."),
+      );
+      expect(updateCallSession).toHaveBeenCalledWith(
+        "call-name-timeout",
+        expect.objectContaining({ status: "failed" }),
+      );
+      expect(finalizeCall).toHaveBeenCalledTimes(1);
+      expect(registerCallController).not.toHaveBeenCalled();
+
+      session.destroy();
+    });
+
+    test("disconnect mid-wait disposes the flow, emits the callback handoff, and finalizes once", async () => {
+      const { session } = setupCall({
+        callId: "call-name-drop",
+        outcome: nameCaptureOutcome(),
+      });
+      await session.whenSetupSettled();
+
+      mockCanonicalRequest = { status: "pending" };
+      deliverTranscript(session, "Casey Example");
+      await sleep();
+      expect(session.getSetupFlow()?.getState()).toBe(
+        "awaiting_guardian_decision",
+      );
+
+      session.handleTransportClosed(1006, "network dropped");
+
+      expect(mockEmitCallbackHandoff).toHaveBeenCalledWith(
+        expect.objectContaining({ reason: "transport_closed" }),
+      );
+      expect(updateCallSession).toHaveBeenCalledWith(
+        "call-name-drop",
+        expect.objectContaining({ status: "failed" }),
+      );
+      expect(finalizeCall).toHaveBeenCalledTimes(1);
+      expect(session.getSetupFlow()).toBeNull();
+
+      // A late approval must not resurrect the torn-down call.
+      mockCanonicalRequest = { status: "approved" };
+      await sleep(40);
+      expect(registerCallController).not.toHaveBeenCalled();
+      expect(finalizeCall).toHaveBeenCalledTimes(1);
+
+      session.destroy();
+    });
+  });
+
+  describe("unverified caller", () => {
+    test("hears the verification guidance and the call ends without a controller", async () => {
+      const { session, mockWs } = setupCall({
+        callId: "call-unverified",
+        outcome: {
+          action: "unverified_caller",
+          assistantId: "self",
+          fromNumber: FROM,
+          displayName: "Sam Example",
+          isGuardian: false,
+        },
+      });
+      await session.whenSetupSettled();
+
+      expect(speakSystemPrompt).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.stringContaining("registered as Sam Example's phone"),
+      );
+      expect(
+        mockEvents.some(
+          (e) =>
+            e.callSessionId === "call-unverified" &&
+            e.eventType === "inbound_acl_unverified_caller",
+        ),
+      ).toBe(true);
+      expect(updateCallSession).toHaveBeenCalledWith(
+        "call-unverified",
+        expect.objectContaining({ status: "failed" }),
+      );
+      expect(finalizeCall).toHaveBeenCalledTimes(1);
+      expect(registerCallController).not.toHaveBeenCalled();
+
+      await sleep(30);
+      expect(mockWs.closed).toBe(true);
+
+      session.destroy();
+    });
+  });
+
+  describe("hangup during terminal setup speech", () => {
+    /** Gate the next speakSystemPrompt call on a manually released promise. */
+    function gateNextSpeech(): () => void {
+      let release!: () => void;
+      (speakSystemPrompt as jest.Mock).mockImplementationOnce(
+        () =>
+          new Promise<void>((resolve) => {
+            release = resolve;
+          }),
+      );
+      return () => release();
+    }
+
+    test("hangup during the deny goodbye finalizes exactly once and revokes grants", async () => {
+      const releaseSpeech = gateNextSpeech();
+      const { session } = setupCall({
+        callId: "call-deny-hangup",
+        outcome: {
+          action: "deny",
+          message: "Not authorized.",
+          logReason: "ACL deny",
+        },
+      });
+      await sleep();
+
+      // The deny path sets terminal status before its goodbye finishes.
+      expect(updateCallSession).toHaveBeenCalledWith(
+        "call-deny-hangup",
+        expect.objectContaining({ status: "failed" }),
+      );
+      expect(finalizeCall).not.toHaveBeenCalled();
+
+      // Caller hangs up while the goodbye is still speaking.
+      session.handleTransportClosed(1006, "caller hung up");
+
+      expect(finalizeCall).toHaveBeenCalledTimes(1);
+      expect(finalizeCall).toHaveBeenCalledWith(
+        "call-deny-hangup",
+        "conv-call-deny-hangup",
+      );
+      expect(revokeScopedApprovalGrantsForContext).toHaveBeenCalledWith({
+        callSessionId: "call-deny-hangup",
+      });
+      expect(revokeScopedApprovalGrantsForContext).toHaveBeenCalledWith({
+        conversationId: "conv-call-deny-hangup",
+      });
+      expect(session.getSetupFlow()).toBeNull();
+
+      // The speech promise settling later must not double-finalize.
+      releaseSpeech();
+      await session.whenSetupSettled();
+      await sleep();
+      expect(finalizeCall).toHaveBeenCalledTimes(1);
+      expect(registerCallController).not.toHaveBeenCalled();
+
+      session.destroy();
+    });
+
+    test("hangup during the guardian-denial goodbye finalizes exactly once and revokes grants", async () => {
+      const { session } = setupCall({
+        callId: "call-guard-deny-hangup",
+        outcome: {
+          action: "name_capture",
+          assistantId: "self",
+          fromNumber: FROM,
+        },
+      });
+      await session.whenSetupSettled();
+
+      mockCanonicalRequest = { status: "pending" };
+      deliverTranscript(session, "Casey Example");
+      await sleep();
+
+      const releaseSpeech = gateNextSpeech();
+      mockCanonicalRequest = { status: "denied" };
+      await sleep(40);
+
+      expect(updateCallSession).toHaveBeenCalledWith(
+        "call-guard-deny-hangup",
+        expect.objectContaining({ status: "failed" }),
+      );
+      expect(finalizeCall).not.toHaveBeenCalled();
+
+      // Caller hangs up while the denial goodbye is still speaking.
+      session.handleTransportClosed(1006, "caller hung up");
+
+      expect(finalizeCall).toHaveBeenCalledTimes(1);
+      expect(finalizeCall).toHaveBeenCalledWith(
+        "call-guard-deny-hangup",
+        "conv-call-guard-deny-hangup",
+      );
+      expect(revokeScopedApprovalGrantsForContext).toHaveBeenCalledWith({
+        callSessionId: "call-guard-deny-hangup",
+      });
+      expect(session.getSetupFlow()).toBeNull();
+
+      releaseSpeech();
+      await sleep();
+      expect(finalizeCall).toHaveBeenCalledTimes(1);
+      expect(registerCallController).not.toHaveBeenCalled();
+
+      session.destroy();
+    });
+
+    test("deny completion without a hangup finalizes exactly once; a later close does not re-finalize", async () => {
+      const { session, mockWs } = setupCall({
+        callId: "call-deny-normal",
+        outcome: {
+          action: "deny",
+          message: "Not authorized.",
+          logReason: "ACL deny",
+        },
+      });
+      await session.whenSetupSettled();
+
+      expect(finalizeCall).toHaveBeenCalledTimes(1);
+      expect(finalizeCall).toHaveBeenCalledWith(
+        "call-deny-normal",
+        "conv-call-deny-normal",
+      );
+
+      // The flow schedules its own delayed endSession.
+      await sleep(30);
+      expect(mockWs.closed).toBe(true);
+
+      session.handleTransportClosed(1000, "session-ended");
+      expect(finalizeCall).toHaveBeenCalledTimes(1);
+
+      session.destroy();
+    });
+  });
+});