@vellumai/assistant 0.4.2 → 0.4.4

package/src/calls/relay-server.ts

@@ -10,17 +10,22 @@ import { randomInt } from 'node:crypto';
 
 import type { ServerWebSocket } from 'bun';
 
-import { isAssistantFeatureFlagEnabled } from '../config/assistant-feature-flags.js';
 import { getConfig } from '../config/loader.js';
+import { getCanonicalGuardianRequest } from '../memory/canonical-guardian-store.js';
+import { listActiveBindingsByAssistant } from '../memory/channel-guardian-store.js';
 import * as conversationStore from '../memory/conversation-store.js';
 import { findActiveVoiceInvites } from '../memory/ingress-invite-store.js';
+import { findMember, upsertMember } from '../memory/ingress-member-store.js';
 import { revokeScopedApprovalGrantsForContext } from '../memory/scoped-approval-grants.js';
+import { emitNotificationSignal } from '../notifications/emit-signal.js';
 import { notifyGuardianOfAccessRequest } from '../runtime/access-request-helper.js';
 import {
   resolveActorTrust,
   toGuardianRuntimeContextFromTrust,
 } from '../runtime/actor-trust-resolver.js';
+import { DAEMON_INTERNAL_ASSISTANT_ID } from '../runtime/assistant-scope.js';
 import {
+  getGuardianBinding,
   getPendingChallenge,
   validateAndConsumeChallenge,
 } from '../runtime/channel-guardian-service.js';
@@ -31,7 +36,15 @@ import {
 import { redeemVoiceInviteCode } from '../runtime/ingress-service.js';
 import { parseJsonSafe } from '../util/json.js';
 import { getLogger } from '../util/logger.js';
-import { normalizeAssistantId } from '../util/platform.js';
+import {
+  getAccessRequestPollIntervalMs,
+  getGuardianWaitUpdateInitialIntervalMs,
+  getGuardianWaitUpdateInitialWindowMs,
+  getGuardianWaitUpdateSteadyMaxIntervalMs,
+  getGuardianWaitUpdateSteadyMinIntervalMs,
+  getTtsPlaybackDelayMs,
+  getUserConsultationTimeoutMs,
+} from './call-constants.js';
 import { CallController } from './call-controller.js';
 import { persistCallCompletionMessage } from './call-conversation-messages.js';
 import { addPointerMessage, formatDuration } from './call-pointer-messages.js';
@@ -144,7 +157,7 @@ export function setRelayBroadcast(fn: (msg: import('../daemon/ipc-contract.js').
 /**
  * Manages a single WebSocket connection for one call.
  */
-export type RelayConnectionState = 'connected' | 'verification_pending' | 'disconnecting';
+export type RelayConnectionState = 'connected' | 'verification_pending' | 'awaiting_name' | 'awaiting_guardian_decision' | 'disconnecting';
 
 export class RelayConnection {
   private ws: ServerWebSocket<RelayWebSocketData>;
@@ -180,6 +193,34 @@ export class RelayConnection {
   private inviteRedemptionAssistantId: string | null = null;
   private inviteRedemptionFromNumber: string | null = null;
   private inviteRedemptionCodeLength = 6;
+  private inviteRedemptionFriendName: string | null = null;
+  private inviteRedemptionGuardianName: string | null = null;
+
+  // In-call guardian approval wait state (friend-initiated)
+  private accessRequestWaitActive = false;
+  private accessRequestId: string | null = null;
+  private accessRequestAssistantId: string | null = null;
+  private accessRequestFromNumber: string | null = null;
+  private accessRequestPollTimer: ReturnType<typeof setInterval> | null = null;
+  private accessRequestTimeoutTimer: ReturnType<typeof setTimeout> | null = null;
+  private accessRequestCallerName: string | null = null;
+
+  // Name capture timeout (unknown inbound callers)
+  private nameCaptureTimeoutTimer: ReturnType<typeof setTimeout> | null = null;
+
+  // Guardian wait heartbeat state
+  private accessRequestHeartbeatTimer: ReturnType<typeof setTimeout> | null = null;
+  private accessRequestWaitStartedAt: number = 0;
+  private heartbeatSequence = 0;
+
+  // In-wait prompt handling state
+  private lastInWaitReplyAt = 0;
+  private static readonly IN_WAIT_REPLY_COOLDOWN_MS = 3000;
+
+  // Callback offer state (in-memory per-call)
+  private callbackOfferMade = false;
+  private callbackOptIn = false;
+  private callbackHandoffNotified = false;
 
   constructor(ws: ServerWebSocket<RelayWebSocketData>, callSessionId: string) {
     this.ws = ws;
@@ -304,6 +345,23 @@ export class RelayConnection {
       this.controller.destroy();
       this.controller = null;
     }
+    if (this.accessRequestPollTimer) {
+      clearInterval(this.accessRequestPollTimer);
+      this.accessRequestPollTimer = null;
+    }
+    if (this.accessRequestTimeoutTimer) {
+      clearTimeout(this.accessRequestTimeoutTimer);
+      this.accessRequestTimeoutTimer = null;
+    }
+    if (this.accessRequestHeartbeatTimer) {
+      clearTimeout(this.accessRequestHeartbeatTimer);
+      this.accessRequestHeartbeatTimer = null;
+    }
+    if (this.nameCaptureTimeoutTimer) {
+      clearTimeout(this.nameCaptureTimeoutTimer);
+      this.nameCaptureTimeoutTimer = null;
+    }
+    this.accessRequestWaitActive = false;
     this.abortController.abort();
     log.info({ callSessionId: this.callSessionId }, 'RelayConnection destroyed');
   }
@@ -315,6 +373,19 @@ export class RelayConnection {
    * we still finalize the call lifecycle from the relay close signal.
    */
   handleTransportClosed(code?: number, reason?: string): void {
+    // If the call was still in guardian-wait with callback opt-in, emit the
+    // handoff notification before cleaning up wait state.
+    if (this.accessRequestWaitActive && this.callbackOptIn) {
+      this.emitAccessRequestCallbackHandoff('transport_closed');
+    }
+
+    // Clean up access request wait state on disconnect to stop polling
+    this.clearAccessRequestWait();
+    if (this.nameCaptureTimeoutTimer) {
+      clearTimeout(this.nameCaptureTimeoutTimer);
+      this.nameCaptureTimeoutTimer = null;
+    }
+
     const session = getCallSession(this.callSessionId);
     if (!session) return;
     if (isTerminalState(session.status)) return;
@@ -427,7 +498,7 @@ export class RelayConnection {
     // calls (created via createInboundVoiceSession) never do. Relying on
     // task == null is unreliable: task-less outbound sessions would
     // incorrectly bypass outbound verification.
-    const assistantId = normalizeAssistantId(session?.assistantId ?? 'self');
+    const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
     const isInbound = session?.initiatedFromConversationId == null;
 
     // Create and attach the session-backed voice controller. Seed guardian
@@ -500,89 +571,80 @@ export class RelayConnection {
       const pendingChallenge = getPendingChallenge(assistantId, 'voice');
 
       if (actorTrust.trustClass === 'unknown' && !pendingChallenge) {
-        // Before denying, check if there is an active voice invite bound
-        // to the caller's phone number. If so, enter the invite redemption
-        // subflow instead of denying the call outright.
-        // Gated behind the voice-invite-redemption feature flag (defaults OFF).
-        const voiceInviteEnabled = isAssistantFeatureFlagEnabled(
-          'feature_flags.voice-invite-redemption.enabled',
-          config,
-        );
+        // Before entering the name capture flow, check if there is an
+        // active voice invite bound to the caller's phone number. If so,
+        // enter the invite redemption subflow instead.
+        let voiceInvites: ReturnType<typeof findActiveVoiceInvites> = [];
+        try {
+          voiceInvites = findActiveVoiceInvites({
+            assistantId,
+            expectedExternalUserId: msg.from,
+          });
+        } catch (err) {
+          log.warn({ err, callSessionId: this.callSessionId }, 'Failed to check voice invites for unknown caller');
+        }
 
-        if (voiceInviteEnabled) {
-          let voiceInvites: ReturnType<typeof findActiveVoiceInvites> = [];
-          try {
-            voiceInvites = findActiveVoiceInvites({
-              assistantId,
-              expectedExternalUserId: msg.from,
-            });
-          } catch (err) {
-            log.warn({ err, callSessionId: this.callSessionId }, 'Failed to check voice invites for unknown caller');
-          }
+        // Exclude invites that are past their expiresAt even if the DB
+        // status hasn't been lazily flipped to 'expired' yet.
+        const now = Date.now();
+        const nonExpiredInvites = voiceInvites.filter(i => !i.expiresAt || i.expiresAt > now);
+
+        // Blocked members get immediate denial — the guardian already made
+        // an explicit decision to block them. This must be checked before
+        // invite redemption so a blocked caller cannot bypass the block by
+        // redeeming an active invite.
+        if (actorTrust.memberRecord?.status === 'blocked') {
+          log.info(
+            { callSessionId: this.callSessionId, from: msg.from, trustClass: actorTrust.trustClass },
+            'Inbound voice ACL: blocked caller denied',
+          );
 
-          // Exclude invites that are past their expiresAt even if the DB
-          // status hasn't been lazily flipped to 'expired' yet.
-          const now = Date.now();
-          const nonExpiredInvites = voiceInvites.filter(i => !i.expiresAt || i.expiresAt > now);
+          recordCallEvent(this.callSessionId, 'inbound_acl_denied', {
+            from: msg.from,
+            trustClass: actorTrust.trustClass,
+            denialReason: actorTrust.denialReason,
+          });
 
-          if (nonExpiredInvites.length > 0) {
-            log.info(
-              { callSessionId: this.callSessionId, from: msg.from },
-              'Inbound voice ACL: unknown caller has active voice invite — entering redemption flow',
-            );
-            this.startInviteRedemption(assistantId, msg.from);
-            return;
-          }
+          this.sendTextToken('This number is not authorized to use this assistant.', true);
+
+          this.connectionState = 'disconnecting';
+
+          updateCallSession(this.callSessionId, {
+            status: 'failed',
+            endedAt: Date.now(),
+            lastError: 'Inbound voice ACL: caller blocked',
+          });
+
+          setTimeout(() => {
+            this.endSession('Inbound voice ACL denied — blocked');
+          }, getTtsPlaybackDelayMs());
+          return;
+        }
+
+        if (nonExpiredInvites.length > 0) {
+          // Use the first matching invite's metadata for personalized prompts
+          const matchedInvite = nonExpiredInvites[0];
+          log.info(
+            { callSessionId: this.callSessionId, from: msg.from },
+            'Inbound voice ACL: unknown caller has active voice invite — entering redemption flow',
+          );
+          this.startInviteRedemption(assistantId, msg.from, matchedInvite.friendName, matchedInvite.guardianName);
+          return;
         }
 
+        // Unknown/revoked/pending callers enter the name capture + guardian
+        // approval wait flow instead of being hard-rejected.
         log.info(
           { callSessionId: this.callSessionId, from: msg.from, trustClass: actorTrust.trustClass },
-          'Inbound voice ACL: unknown caller denied',
+          'Inbound voice ACL: unknown caller — entering name capture flow',
         );
 
-        recordCallEvent(this.callSessionId, 'inbound_acl_denied', {
+        recordCallEvent(this.callSessionId, 'inbound_acl_name_capture_started', {
           from: msg.from,
           trustClass: actorTrust.trustClass,
-          denialReason: actorTrust.denialReason,
-        });
-
-        // For revoked/pending members, notify the guardian so they can
-        // re-approve. Blocked members are intentionally excluded — the
-        // guardian already made an explicit decision to block them.
-        let guardianNotified = false;
-        if (actorTrust.memberRecord?.status !== 'blocked') {
-          try {
-            const accessResult = notifyGuardianOfAccessRequest({
-              canonicalAssistantId: assistantId,
-              sourceChannel: 'voice',
-              externalChatId: msg.from,
-              senderExternalUserId: actorTrust.canonicalSenderId ?? msg.from,
-            });
-            guardianNotified = accessResult.notified;
-          } catch (err) {
-            log.error({ err, callSessionId: this.callSessionId }, 'Failed to create access request for denied voice caller');
-          }
-        }
-
-        // Deny with deterministic voice copy and end the call.
-        // Mark as disconnecting so handlePrompt ignores caller input
-        // during the delay before the session ends.
-        const denialMessage = guardianNotified
-          ? 'This number is not authorized. Your request has been forwarded to the account guardian.'
-          : 'This number is not authorized to use this assistant.';
-        this.sendTextToken(denialMessage, true);
-
-        this.connectionState = 'disconnecting';
-
-        updateCallSession(this.callSessionId, {
-          status: 'failed',
-          endedAt: Date.now(),
-          lastError: 'Inbound voice ACL: caller not authorized',
         });
 
-        setTimeout(() => {
-          this.endSession('Inbound voice ACL denied');
-        }, 3000);
+        this.startNameCapture(assistantId, msg.from);
         return;
       }
 
@@ -614,7 +676,7 @@ export class RelayConnection {
 
         setTimeout(() => {
           this.endSession('Inbound voice ACL: member policy deny');
-        }, 3000);
+        }, getTtsPlaybackDelayMs());
         return;
       }
 
@@ -646,7 +708,7 @@ export class RelayConnection {
 
         setTimeout(() => {
           this.endSession('Inbound voice ACL: member policy escalate');
-        }, 3000);
+        }, getTtsPlaybackDelayMs());
         return;
       }
 
@@ -910,7 +972,7 @@ export class RelayConnection {
 
         setTimeout(() => {
           this.endSession('Guardian verification succeeded');
-        }, 3000);
+        }, getTtsPlaybackDelayMs());
       } else {
         // Inbound: proceed to normal call flow
         if (this.controller) {
@@ -981,7 +1043,7 @@ export class RelayConnection {
 
         setTimeout(() => {
           this.endSession('Guardian verification failed');
-        }, 2000);
+        }, getTtsPlaybackDelayMs());
       } else {
         const retryText = isOutbound
           ? composeVerificationVoice(GUARDIAN_VERIFY_TEMPLATE_KEYS.VOICE_RETRY, { codeDigits })
@@ -1001,13 +1063,15 @@ export class RelayConnection {
    * who has an active voice invite. Prompts the caller to enter their
    * invite code via DTMF or speech.
    */
-  private startInviteRedemption(assistantId: string, fromNumber: string): void {
+  private startInviteRedemption(assistantId: string, fromNumber: string, friendName: string | null, guardianName: string | null): void {
     this.inviteRedemptionActive = true;
     this.inviteRedemptionAssistantId = assistantId;
     this.inviteRedemptionFromNumber = fromNumber;
+    this.inviteRedemptionFriendName = friendName;
+    this.inviteRedemptionGuardianName = guardianName;
     this.connectionState = 'verification_pending';
     this.verificationAttempts = 0;
-    this.verificationMaxAttempts = 3;
+    this.verificationMaxAttempts = 1;
     this.inviteRedemptionCodeLength = 6;
     this.dtmfBuffer = '';
 
@@ -1017,8 +1081,10 @@ export class RelayConnection {
       maxAttempts: this.verificationMaxAttempts,
     });
 
+    const displayFriend = friendName ?? 'there';
+    const displayGuardian = guardianName ?? 'your contact';
     this.sendTextToken(
-      'Please enter your 6-digit invite code using your keypad, or speak the digits now.',
+      `Welcome ${displayFriend}. Please enter the 6-digit code that ${displayGuardian} provided you to verify your identity.`,
       true,
     );
 
@@ -1028,6 +1094,459 @@ export class RelayConnection {
     );
   }
 
+  /**
+   * Enter the name capture subflow for unknown inbound callers.
+   * Prompts the caller to provide their name so we can include it
+   * in the guardian notification.
+   */
+  private startNameCapture(assistantId: string, fromNumber: string): void {
+    this.accessRequestAssistantId = assistantId;
+    this.accessRequestFromNumber = fromNumber;
+    this.connectionState = 'awaiting_name';
+
+    this.sendTextToken(
+      "Sorry, I don't recognize this number. I'll let my guardian know you called and see if I have permission to speak with you. Can I get your name?",
+      true,
+    );
+
+    // Start a timeout so silent callers don't keep the call open indefinitely.
+    // Uses a 30-second window — enough time to speak a name but short enough
+    // to avoid wasting resources on callers who never respond.
+    const NAME_CAPTURE_TIMEOUT_MS = 30_000;
+    this.nameCaptureTimeoutTimer = setTimeout(() => {
+      if (this.connectionState !== 'awaiting_name') return;
+      this.handleNameCaptureTimeout();
+    }, NAME_CAPTURE_TIMEOUT_MS);
+
+    log.info(
+      { callSessionId: this.callSessionId, assistantId, timeoutMs: NAME_CAPTURE_TIMEOUT_MS },
+      'Name capture started for unknown inbound caller',
+    );
+  }
+
+  /**
+   * Handle the caller's name response during the name capture subflow.
+   * Creates a canonical access request, notifies the guardian, and
+   * enters the bounded wait loop for the guardian decision.
+   */
+  private handleNameCaptureResponse(callerName: string): void {
+    if (!this.accessRequestAssistantId || !this.accessRequestFromNumber) {
+      return;
+    }
+
+    // Clear the name capture timeout since the caller responded.
+    if (this.nameCaptureTimeoutTimer) {
+      clearTimeout(this.nameCaptureTimeoutTimer);
+      this.nameCaptureTimeoutTimer = null;
+    }
+
+    this.accessRequestCallerName = callerName;
+
+    recordCallEvent(this.callSessionId, 'inbound_acl_name_captured', {
+      from: this.accessRequestFromNumber,
+      callerName,
+    });
+
+    // Create canonical access request and notify the guardian, including
+    // the caller's spoken name and voice channel metadata.
+    try {
+      const accessResult = notifyGuardianOfAccessRequest({
+        canonicalAssistantId: this.accessRequestAssistantId,
+        sourceChannel: 'voice',
+        externalChatId: this.accessRequestFromNumber,
+        senderExternalUserId: this.accessRequestFromNumber,
+        senderName: callerName,
+      });
+
+      if (accessResult.notified) {
+        this.accessRequestId = accessResult.requestId;
+        log.info(
+          { callSessionId: this.callSessionId, requestId: accessResult.requestId, callerName },
+          'Guardian notified of voice access request with caller name',
+        );
+      } else {
+        log.warn(
+          { callSessionId: this.callSessionId },
+          'Failed to notify guardian of voice access request — no sender ID',
+        );
+      }
+    } catch (err) {
+      log.error({ err, callSessionId: this.callSessionId }, 'Failed to create access request for voice caller');
+    }
+
+    // If the access request was not successfully created (notifyGuardianOfAccessRequest
+    // threw or returned notified: false), fail closed rather than leaving the caller
+    // stuck on hold with no guardian poll target.
+    if (!this.accessRequestId) {
+      log.warn(
+        { callSessionId: this.callSessionId },
+        'Access request ID is null after notification attempt — failing closed',
+      );
+      this.handleAccessRequestTimeout();
+      return;
+    }
+
+    // Enter the bounded wait loop for the guardian decision
+    this.startAccessRequestWait();
+  }
+
+  /**
+   * Start a bounded in-call wait loop polling the canonical request
+   * status until approved, denied, or timeout.
+   */
+  private startAccessRequestWait(): void {
+    this.accessRequestWaitActive = true;
+    this.connectionState = 'awaiting_guardian_decision';
+
+    const timeoutMs = getUserConsultationTimeoutMs();
+    const pollIntervalMs = getAccessRequestPollIntervalMs();
+
+    const guardianLabel = this.resolveGuardianLabel();
+    this.sendTextToken(
+      `Thank you. I've let ${guardianLabel} know. Please hold while I check if I have permission to speak with you.`,
+      true,
+    );
+
+    updateCallSession(this.callSessionId, { status: 'waiting_on_user' });
+
+    // Start the heartbeat timer for periodic progress updates
+    this.accessRequestWaitStartedAt = Date.now();
+    this.heartbeatSequence = 0;
+    this.scheduleNextHeartbeat();
+
+    // Poll the canonical request status
+    this.accessRequestPollTimer = setInterval(() => {
+      if (!this.accessRequestWaitActive || !this.accessRequestId) {
+        this.clearAccessRequestWait();
+        return;
+      }
+
+      const request = getCanonicalGuardianRequest(this.accessRequestId);
+      if (!request) {
+        return;
+      }
+
+      if (request.status === 'approved') {
+        this.handleAccessRequestApproved();
+      } else if (request.status === 'denied') {
+        this.handleAccessRequestDenied();
+      }
+      // 'pending' continues polling; 'expired'/'cancelled' handled by timeout
+    }, pollIntervalMs);
+
+    // Timeout: give up waiting for the guardian
+    this.accessRequestTimeoutTimer = setTimeout(() => {
+      if (!this.accessRequestWaitActive) return;
+
+      log.info(
+        { callSessionId: this.callSessionId, requestId: this.accessRequestId },
+        'Access request in-call wait timed out',
+      );
+
+      this.handleAccessRequestTimeout();
+    }, timeoutMs);
+
+    log.info(
+      { callSessionId: this.callSessionId, requestId: this.accessRequestId, timeoutMs },
+      'Access request in-call wait started',
+    );
+  }
+
+  /**
+   * Clean up access request wait state (timers, flags).
+   */
+  private clearAccessRequestWait(): void {
+    this.accessRequestWaitActive = false;
+    if (this.accessRequestPollTimer) {
+      clearInterval(this.accessRequestPollTimer);
+      this.accessRequestPollTimer = null;
+    }
+    if (this.accessRequestTimeoutTimer) {
+      clearTimeout(this.accessRequestTimeoutTimer);
+      this.accessRequestTimeoutTimer = null;
+    }
+    if (this.accessRequestHeartbeatTimer) {
+      clearTimeout(this.accessRequestHeartbeatTimer);
+      this.accessRequestHeartbeatTimer = null;
+    }
+  }
+
+  /**
+   * Handle an approved access request: activate the caller as a trusted
+   * contact, update runtime context, and continue with normal call flow.
+   */
+  private handleAccessRequestApproved(): void {
+    this.clearAccessRequestWait();
+    this.connectionState = 'connected';
+
+    const assistantId = this.accessRequestAssistantId!;
+    const fromNumber = this.accessRequestFromNumber!;
+    const callerName = this.accessRequestCallerName;
+
+    recordCallEvent(this.callSessionId, 'inbound_acl_access_approved', {
+      from: fromNumber,
+      callerName,
+      requestId: this.accessRequestId,
+    });
+
+    // Activate the caller as a trusted contact via the existing upsert path
+    try {
+      upsertMember({
+        assistantId,
+        sourceChannel: 'voice',
+        externalUserId: fromNumber,
+        externalChatId: fromNumber,
+        displayName: callerName ?? undefined,
+        status: 'active',
+        policy: 'allow',
+      });
+    } catch (err) {
+      log.error({ err, callSessionId: this.callSessionId }, 'Failed to activate voice caller as trusted contact');
+    }
+
+    // Re-resolve actor trust now that the member is active
+    const updatedTrust = resolveActorTrust({
+      assistantId,
+      sourceChannel: 'voice',
+      externalChatId: fromNumber,
+      senderExternalUserId: fromNumber,
+    });
+
+    if (this.controller) {
+      this.controller.setGuardianContext(
+        toGuardianRuntimeContextFromTrust(updatedTrust, fromNumber),
+      );
+    }
+
+    updateCallSession(this.callSessionId, { status: 'in_progress' });
+
+    log.info(
+      { callSessionId: this.callSessionId, from: fromNumber },
+      'Access request approved — caller activated and continuing call',
+    );
+
+    // Use handleUserInstruction to deliver the approval-aware greeting
+    // through the normal session pipeline.
+    const guardianLabel = this.resolveGuardianLabel();
+    if (this.controller) {
+      this.controller.handleUserInstruction(
+        `Great, ${guardianLabel} approved! Now how can I help you?`,
+      ).catch((err) => {
+        log.error({ err, callSessionId: this.callSessionId }, 'Failed to deliver approval greeting');
+      });
+    }
+  }
+
+  /**
+   * Handle a denied access request: deliver deterministic copy and hang up.
+   */
+  private handleAccessRequestDenied(): void {
+    this.clearAccessRequestWait();
+
+    const guardianLabel = this.resolveGuardianLabel();
+
+    recordCallEvent(this.callSessionId, 'inbound_acl_access_denied', {
+      from: this.accessRequestFromNumber,
+      requestId: this.accessRequestId,
+    });
+
+    this.sendTextToken(
+      `Sorry, ${guardianLabel} says I'm not allowed to speak with you. Goodbye.`,
+      true,
+    );
+
+    this.connectionState = 'disconnecting';
+
+    updateCallSession(this.callSessionId, {
+      status: 'failed',
+      endedAt: Date.now(),
+      lastError: 'Inbound voice ACL: guardian denied access request',
+    });
+
+    log.info(
+      { callSessionId: this.callSessionId },
+      'Access request denied — ending call',
+    );
+
+    setTimeout(() => {
+      this.endSession('Access request denied');
+    }, getTtsPlaybackDelayMs());
+  }
+
+  /**
+   * Handle an access request timeout: deliver deterministic copy and hang up.
+   */
+  private handleAccessRequestTimeout(): void {
+    // Emit callback handoff notification before clearing wait state
+    this.emitAccessRequestCallbackHandoff('timeout');
+
+    this.clearAccessRequestWait();
+
+    const guardianLabel = this.resolveGuardianLabel();
+
+    recordCallEvent(this.callSessionId, 'inbound_acl_access_timeout', {
+      from: this.accessRequestFromNumber,
+      requestId: this.accessRequestId,
+      callbackOptIn: this.callbackOptIn,
+    });
+
+    const callbackNote = this.callbackOptIn
+      ? ` I've noted that you'd like a callback — I'll pass that along to ${guardianLabel}.`
+      : '';
+    this.sendTextToken(
+      `Sorry, I can't get ahold of ${guardianLabel} right now. I'll let them know you called.${callbackNote}`,
+      true,
+    );
+
+    this.connectionState = 'disconnecting';
+
+    updateCallSession(this.callSessionId, {
+      status: 'failed',
+      endedAt: Date.now(),
+      lastError: 'Inbound voice ACL: guardian approval wait timed out',
+    });
+
+    log.info(
+      { callSessionId: this.callSessionId },
+      'Access request timed out — ending call',
+    );
+
+    setTimeout(() => {
+      this.endSession('Access request timed out');
+    }, getTtsPlaybackDelayMs());
+  }
+
+  /**
+   * Emit a callback handoff notification to the guardian when the caller
+   * opted into a callback during guardian wait but the wait ended without
+   * resolution (timeout or transport close).
+   *
+   * Idempotent: uses callbackHandoffNotified guard + deterministic dedupeKey
+   * to ensure at most one notification per call/request.
+   */
+  private emitAccessRequestCallbackHandoff(reason: 'timeout' | 'transport_closed'): void {
+    if (!this.callbackOptIn) return;
+    if (!this.accessRequestId) return;
+    if (this.callbackHandoffNotified) return;
+
+    this.callbackHandoffNotified = true;
+
+    const assistantId = this.accessRequestAssistantId ?? DAEMON_INTERNAL_ASSISTANT_ID;
+    const fromNumber = this.accessRequestFromNumber ?? null;
+
+    // Resolve canonical request for requestCode and conversationId
+    const canonicalRequest = this.accessRequestId
+      ? getCanonicalGuardianRequest(this.accessRequestId)
+      : null;
+
+    // Resolve trusted-contact member reference when possible
+    let requesterMemberId: string | null = null;
+    if (fromNumber) {
+      try {
+        const member = findMember({
+          assistantId,
+          sourceChannel: 'voice',
+          externalUserId: fromNumber,
+          externalChatId: fromNumber,
+        });
+        if (member && member.status === 'active' && member.policy === 'allow') {
+          requesterMemberId = member.id;
+        }
+      } catch (err) {
+        log.warn({ err, callSessionId: this.callSessionId }, 'Failed to resolve member for callback handoff');
+      }
+    }
+
+    const dedupeKey = `access-request-callback-handoff:${this.accessRequestId}`;
+    const sourceSessionId = canonicalRequest?.conversationId
+      ?? `access-req-callback-${this.accessRequestId}`;
+
+    void emitNotificationSignal({
+      sourceEventName: 'ingress.access_request.callback_handoff',
+      sourceChannel: 'voice',
+      sourceSessionId,
+      assistantId,
+      attentionHints: {
+        requiresAction: false,
+        urgency: 'medium',
+        isAsyncBackground: true,
+        visibleInSourceNow: false,
+      },
+      contextPayload: {
+        requestId: this.accessRequestId,
+        requestCode: canonicalRequest?.requestCode ?? null,
+        callSessionId: this.callSessionId,
+        sourceChannel: 'voice',
+        reason,
+        callbackOptIn: true,
+        callerPhoneNumber: fromNumber,
+        callerName: this.accessRequestCallerName ?? null,
+        requesterExternalUserId: fromNumber,
+        requesterChatId: fromNumber,
+        requesterMemberId,
+        requesterMemberSourceChannel: requesterMemberId ? 'voice' : null,
+      },
+      dedupeKey,
+    }).then(() => {
+      recordCallEvent(this.callSessionId, 'callback_handoff_notified', {
+        requestId: this.accessRequestId,
+        reason,
+        requesterMemberId,
+      });
+      log.info(
+        { callSessionId: this.callSessionId, requestId: this.accessRequestId, reason },
+        'Callback handoff notification emitted',
+      );
+    }).catch((err) => {
+      recordCallEvent(this.callSessionId, 'callback_handoff_failed', {
+        requestId: this.accessRequestId,
+        reason,
+        error: err instanceof Error ? err.message : String(err),
+      });
+      log.error(
+        { err, callSessionId: this.callSessionId, requestId: this.accessRequestId },
+        'Failed to emit callback handoff notification',
+      );
+    });
+  }
+
+  /**
+   * Handle a name capture timeout: the caller never provided their name
+   * within the allotted window. Deliver deterministic copy and hang up.
+   */
+  private handleNameCaptureTimeout(): void {
+    if (this.nameCaptureTimeoutTimer) {
+      clearTimeout(this.nameCaptureTimeoutTimer);
+      this.nameCaptureTimeoutTimer = null;
+    }
+
+    recordCallEvent(this.callSessionId, 'inbound_acl_name_capture_timeout', {
+      from: this.accessRequestFromNumber,
+    });
+
+    this.sendTextToken(
+      "Sorry, I didn't catch your name. Please try calling back. Goodbye.",
+      true,
+    );
+
+    this.connectionState = 'disconnecting';
+
+    updateCallSession(this.callSessionId, {
+      status: 'failed',
+      endedAt: Date.now(),
+      lastError: 'Inbound voice ACL: name capture timed out',
+    });
+
+    log.info(
+      { callSessionId: this.callSessionId },
+      'Name capture timed out — ending call',
+    );
+
+    setTimeout(() => {
+      this.endSession('Name capture timed out');
+    }, getTtsPlaybackDelayMs());
+  }
+
   /**
    * Validate an entered invite code against active voice invites for the
    * caller. On success, create/activate the ingress member and transition
@@ -1073,45 +1592,306 @@ export class RelayConnection {
         this.startNormalCallFlow(this.controller, true);
       }
     } else {
-      this.verificationAttempts++;
+      // On any invalid/expired code, emit exact deterministic failure copy and end call immediately.
+      this.inviteRedemptionActive = false;
 
-      if (this.verificationAttempts >= this.verificationMaxAttempts) {
-        this.inviteRedemptionActive = false;
+      recordCallEvent(this.callSessionId, 'invite_redemption_failed', {
+        attempts: 1,
+      });
+      log.warn(
+        { callSessionId: this.callSessionId },
+        'Voice invite redemption failed — invalid or expired code',
+      );
 
-        recordCallEvent(this.callSessionId, 'invite_redemption_failed', {
-          attempts: this.verificationAttempts,
-        });
-        log.warn(
-          { callSessionId: this.callSessionId, attempts: this.verificationAttempts },
-          'Voice invite redemption failed — max attempts reached',
-        );
+      const displayGuardian = this.inviteRedemptionGuardianName ?? 'your contact';
+      this.sendTextToken(
+        `Sorry, the code you provided is incorrect or has since expired. Please ask ${displayGuardian} for a new code. Goodbye.`,
+        true,
+      );
 
-        this.sendTextToken('Too many invalid attempts. Goodbye.', true);
+      this.connectionState = 'disconnecting';
 
-        updateCallSession(this.callSessionId, {
-          status: 'failed',
-          endedAt: Date.now(),
-          lastError: 'Voice invite redemption failed — max attempts exceeded',
+      updateCallSession(this.callSessionId, {
+        status: 'failed',
+        endedAt: Date.now(),
+        lastError: 'Voice invite redemption failed — invalid or expired code',
+      });
+
+      const failSession = getCallSession(this.callSessionId);
+      if (failSession) {
+        expirePendingQuestions(this.callSessionId);
+        persistCallCompletionMessage(failSession.conversationId, this.callSessionId).catch((err) => {
+          log.error({ err, conversationId: failSession.conversationId, callSessionId: this.callSessionId }, 'Failed to persist call completion message');
         });
+        fireCallCompletionNotifier(failSession.conversationId, this.callSessionId);
+      }
 
-        const failSession = getCallSession(this.callSessionId);
-        if (failSession) {
-          expirePendingQuestions(this.callSessionId);
-          persistCallCompletionMessage(failSession.conversationId, this.callSessionId).catch((err) => {
-            log.error({ err, conversationId: failSession.conversationId, callSessionId: this.callSessionId }, 'Failed to persist call completion message');
-          });
-          fireCallCompletionNotifier(failSession.conversationId, this.callSessionId);
+      setTimeout(() => {
+        this.endSession('Invite redemption failed');
+      }, getTtsPlaybackDelayMs());
+    }
+  }
+
+  // ── Guardian wait UX layer ─────────────────────────────────────
+
+  /**
+   * Resolve a human-readable guardian label for voice wait copy.
+   * Prefers displayName from the guardian binding metadata, falls back
+   * to @username, then "my guardian".
+   */
+  private resolveGuardianLabel(): string {
+    const assistantId = this.accessRequestAssistantId ?? DAEMON_INTERNAL_ASSISTANT_ID;
+
+    // Try the voice-channel binding first, then fall back to any active
+    // binding for the assistant (mirrors the cross-channel fallback pattern
+    // in access-request-helper.ts).
+    let metadataJson: string | null = null;
+    const voiceBinding = getGuardianBinding(assistantId, 'voice');
+    if (voiceBinding?.metadataJson) {
+      metadataJson = voiceBinding.metadataJson;
+    } else {
+      const allBindings = listActiveBindingsByAssistant(assistantId);
+      if (allBindings.length > 0 && allBindings[0].metadataJson) {
+        metadataJson = allBindings[0].metadataJson;
+      }
+    }
+
+    if (metadataJson) {
+      try {
+        const parsed = JSON.parse(metadataJson) as Record<string, unknown>;
+        if (typeof parsed.displayName === 'string' && parsed.displayName.trim().length > 0) {
+          return parsed.displayName.trim();
+        }
+        if (typeof parsed.username === 'string' && parsed.username.trim().length > 0) {
+          return `@${parsed.username.trim()}`;
+        }
+      } catch {
+        // ignore malformed metadata
+      }
+    }
+    return 'my guardian';
+  }
+
+  /**
+   * Generate a non-repetitive heartbeat message for the caller based
+   * on the current sequence counter and guardian label.
+   */
+  private getHeartbeatMessage(): string {
+    const guardianLabel = this.resolveGuardianLabel();
+    const seq = this.heartbeatSequence++;
+    const messages = [
+      `Still waiting to hear back from ${guardianLabel}. Thank you for your patience.`,
+      `I'm still trying to reach ${guardianLabel}. One moment please.`,
+      `Hang tight, still waiting on ${guardianLabel}.`,
+      `Still checking with ${guardianLabel}. I appreciate you waiting.`,
+      `I haven't heard back from ${guardianLabel} yet. Thanks for holding.`,
+    ];
+    return messages[seq % messages.length];
+  }
+
+  /**
+   * Schedule the next heartbeat update. Uses the initial fixed interval
+   * during the initial window, then jitters between steady min/max.
+   */
+  private scheduleNextHeartbeat(): void {
+    if (!this.accessRequestWaitActive) return;
+
+    const elapsed = Date.now() - this.accessRequestWaitStartedAt;
+    const initialWindow = getGuardianWaitUpdateInitialWindowMs();
+    const intervalMs = elapsed < initialWindow
+      ? getGuardianWaitUpdateInitialIntervalMs()
+      : getGuardianWaitUpdateSteadyMinIntervalMs() +
+        Math.floor(Math.random() * Math.max(0, getGuardianWaitUpdateSteadyMaxIntervalMs() - getGuardianWaitUpdateSteadyMinIntervalMs()));
+
+    this.accessRequestHeartbeatTimer = setTimeout(() => {
+      if (!this.accessRequestWaitActive) return;
+
+      const message = this.getHeartbeatMessage();
+      this.sendTextToken(message, true);
+
+      recordCallEvent(this.callSessionId, 'voice_guardian_wait_heartbeat_sent', {
+        sequence: this.heartbeatSequence - 1,
+        message,
+      });
+
+      log.debug(
+        { callSessionId: this.callSessionId, sequence: this.heartbeatSequence - 1 },
+        'Guardian wait heartbeat sent',
+      );
+
+      // Schedule the next heartbeat
+      this.scheduleNextHeartbeat();
+    }, intervalMs);
+  }
+
+  /**
+   * Classify a caller utterance during guardian wait into one of:
+   * - 'empty': whitespace or noise
+   * - 'patience_check': asking for status or checking in
+   * - 'impatient': expressing frustration or wanting to end
+   * - 'callback_opt_in': explicitly agreeing to a callback
+   * - 'callback_decline': explicitly declining a callback
+   * - 'neutral': anything else
+   */
+  private classifyWaitUtterance(text: string): 'empty' | 'patience_check' | 'impatient' | 'callback_opt_in' | 'callback_decline' | 'neutral' {
+    const lower = text.toLowerCase().trim();
+    if (lower.length === 0) return 'empty';
+
+    // Callback opt-in patterns (check before impatience to catch "yes call me back")
+    if (this.callbackOfferMade) {
+      if (/\b(yes|yeah|yep|sure|okay|ok|please)\b.*\b(call\s*(me\s*)?back|callback)\b/.test(lower)
+        || /\b(call\s*(me\s*)?back|callback)\b.*\b(yes|yeah|please|sure)\b/.test(lower)
+        || /^(yes|yeah|yep|sure|okay|ok|please)\s*[.,!]?\s*$/.test(lower)
+        || /\bcall\s*(me\s*)?back\b/.test(lower)
+        || /\bplease\s+do\b/.test(lower)) {
+        return 'callback_opt_in';
+      }
+      if (/\b(no|nah|nope)\b/.test(lower)
+        || /\bi('?ll| will)\s+hold\b/.test(lower)
+        || /\bi('?ll| will)\s+wait\b/.test(lower)) {
+        return 'callback_decline';
+      }
+    }
+
+    // Impatience patterns
+    if (/\bhurry\s*(up)?\b/.test(lower)
+      || /\btaking\s+(too\s+|so\s+)?long\b/.test(lower)
+      || /\bforget\s+it\b/.test(lower)
+      || /\bnever\s*mind\b/.test(lower)
+      || /\bdon'?t\s+have\s+time\b/.test(lower)
+      || /\bhow\s+much\s+longer\b/.test(lower)
+      || /\bi('?m| am)\s+(getting\s+)?impatient\b/.test(lower)
+      || /\bthis\s+is\s+(ridiculous|absurd|crazy)\b/.test(lower)
+      || /\bcome\s+on\b/.test(lower)
+      || /\bi\s+(gotta|have\s+to|need\s+to)\s+go\b/.test(lower)) {
+      return 'impatient';
+    }
+
+    // Patience check / status inquiry patterns
+    if (/\bhello\??\s*$/.test(lower)
+      || /\bstill\s+there\b/.test(lower)
+      || /\bany\s+(update|news)\b/.test(lower)
+      || /\bwhat('?s| is)\s+(happening|going\s+on)\b/.test(lower)
+      || /\bare\s+you\s+still\b/.test(lower)
+      || /\bhow\s+(long|much\s+longer)\b/.test(lower)
+      || /\banyone\s+there\b/.test(lower)) {
+      return 'patience_check';
+    }
+
+    return 'neutral';
+  }
+
+  /**
+   * Handle a caller utterance during the guardian decision wait state.
+   * Provides reassurance, impatience detection, and callback offer.
+   */
+  private handleWaitStatePrompt(text: string): void {
+    const now = Date.now();
+    const classification = this.classifyWaitUtterance(text);
+
+    recordCallEvent(this.callSessionId, 'voice_guardian_wait_prompt_classified', {
+      classification,
+      transcript: text,
+    });
+
+    if (classification === 'empty') return;
+
+    const guardianLabel = this.resolveGuardianLabel();
+
+    // Callback decisions must always be processed regardless of cooldown —
+    // the caller is answering a direct question and dropping their response
+    // would silently discard their decision.
+    switch (classification) {
+      case 'callback_opt_in': {
+        this.callbackOptIn = true;
+        this.lastInWaitReplyAt = now;
+        recordCallEvent(this.callSessionId, 'voice_guardian_wait_callback_opt_in_set', {});
+        if (this.accessRequestHeartbeatTimer) {
+          clearTimeout(this.accessRequestHeartbeatTimer);
+          this.accessRequestHeartbeatTimer = null;
         }
+        this.sendTextToken(
+          `Noted, I'll make sure ${guardianLabel} knows you'd like a callback. For now, I'll keep trying to reach them.`,
+          true,
+        );
+        this.scheduleNextHeartbeat();
+        return;
+      }
+      case 'callback_decline': {
+        this.callbackOptIn = false;
+        this.lastInWaitReplyAt = now;
+        recordCallEvent(this.callSessionId, 'voice_guardian_wait_callback_opt_in_declined', {});
+        if (this.accessRequestHeartbeatTimer) {
+          clearTimeout(this.accessRequestHeartbeatTimer);
+          this.accessRequestHeartbeatTimer = null;
+        }
+        this.sendTextToken(
+          `No problem, I'll keep holding. Still waiting on ${guardianLabel}.`,
+          true,
+        );
+        this.scheduleNextHeartbeat();
+        return;
+      }
+      default:
+        break;
+    }
 
-        setTimeout(() => {
-          this.endSession('Invite redemption failed');
-        }, 2000);
-      } else {
-        log.info(
-          { callSessionId: this.callSessionId, attempt: this.verificationAttempts, maxAttempts: this.verificationMaxAttempts },
-          'Voice invite redemption attempt failed — retrying',
+    // Enforce cooldown on non-callback utterances to prevent spam
+    if (now - this.lastInWaitReplyAt < RelayConnection.IN_WAIT_REPLY_COOLDOWN_MS) {
+      log.debug({ callSessionId: this.callSessionId }, 'In-wait reply suppressed by cooldown');
+      return;
+    }
+    this.lastInWaitReplyAt = now;
+
+    switch (classification) {
+      case 'impatient': {
+        if (this.accessRequestHeartbeatTimer) {
+          clearTimeout(this.accessRequestHeartbeatTimer);
+          this.accessRequestHeartbeatTimer = null;
+        }
+        if (!this.callbackOfferMade) {
+          this.callbackOfferMade = true;
+          recordCallEvent(this.callSessionId, 'voice_guardian_wait_callback_offer_sent', {});
+          this.sendTextToken(
+            `I understand this is taking a while. I can have ${guardianLabel} call you back once I hear from them. Would you like that, or would you prefer to keep holding?`,
+            true,
+          );
+        } else {
+          // Already offered callback — just reassure
+          this.sendTextToken(
+            `I hear you, I'm sorry for the wait. Still trying to reach ${guardianLabel}.`,
+            true,
+          );
+        }
+        this.scheduleNextHeartbeat();
+        break;
+      }
+      case 'patience_check': {
+        // Immediate reassurance — reset the heartbeat timer so we
+        // don't double up with a scheduled heartbeat
+        if (this.accessRequestHeartbeatTimer) {
+          clearTimeout(this.accessRequestHeartbeatTimer);
+          this.accessRequestHeartbeatTimer = null;
+        }
+        this.sendTextToken(
+          `Yes, I'm still here. Still waiting to hear back from ${guardianLabel}.`,
+          true,
         );
-        this.sendTextToken('Invalid code. Please try again.', true);
+        this.scheduleNextHeartbeat();
+        break;
+      }
+      case 'neutral':
+      default: {
+        if (this.accessRequestHeartbeatTimer) {
+          clearTimeout(this.accessRequestHeartbeatTimer);
+          this.accessRequestHeartbeatTimer = null;
+        }
+        this.sendTextToken(
+          `Thanks for that. I'm still waiting on ${guardianLabel}. I'll let you know as soon as I hear back.`,
+          true,
+        );
+        this.scheduleNextHeartbeat();
+        break;
       }
     }
   }
@@ -1126,6 +1906,30 @@ export class RelayConnection {
       return;
     }
 
+    // During name capture, the caller's response is their name.
+    if (this.connectionState === 'awaiting_name') {
+      const callerName = msg.voicePrompt.trim();
+      if (!callerName) {
+        // Whitespace-only or empty transcript (e.g. silence/noise) —
+        // keep waiting for a real name. The name-capture timeout will
+        // still fire if the caller never provides one.
+        return;
+      }
+      log.info(
+        { callSessionId: this.callSessionId, callerName },
+        'Name captured from unknown inbound caller',
+      );
+      this.handleNameCaptureResponse(callerName);
+      return;
+    }
+
+    // During guardian decision wait, classify caller speech for
+    // reassurance, impatience detection, and callback offer.
+    if (this.connectionState === 'awaiting_guardian_decision') {
+      this.handleWaitStatePrompt(msg.voicePrompt);
+      return;
+    }
+
     // During guardian verification (inbound or outbound), attempt to parse
     // spoken digits from the transcript and validate them.
     if (this.connectionState === 'verification_pending' && this.guardianVerificationActive) {
@@ -1256,6 +2060,11 @@ export class RelayConnection {
       return;
     }
 
+    // Ignore DTMF during name capture and guardian decision wait
+    if (this.connectionState === 'awaiting_name' || this.connectionState === 'awaiting_guardian_decision') {
+      return;
+    }
+
     log.info(
       { callSessionId: this.callSessionId, digit: msg.digit },
       'DTMF digit received',
@@ -1354,7 +2163,7 @@ export class RelayConnection {
             // End the call with failed status after TTS plays
             setTimeout(() => {
               this.endSession('Verification failed');
-            }, 2000);
+            }, getTtsPlaybackDelayMs());
           } else {
             // Allow another attempt
             log.info(