@vellumai/assistant 0.3.27 → 0.4.0

package/src/runtime/routes/inbound-message-handler.ts

@@ -6,40 +6,28 @@
  */
 // Side-effect import: registers the Telegram invite transport adapter so
 // getTransport('telegram') resolves at runtime.
-import { answerCall } from '../../calls/call-domain.js';
-import { isTerminalState } from '../../calls/call-state-machine.js';
-import { getCallSession } from '../../calls/call-store.js';
 import type { ChannelId, InterfaceId } from '../../channels/types.js';
 import { CHANNEL_IDS, INTERFACE_IDS, isChannelId, parseInterfaceId } from '../../channels/types.js';
 import { getGatewayInternalBaseUrl } from '../../config/env.js';
 import { RESEND_COOLDOWN_MS } from '../../daemon/handlers/config-channels.js';
 import * as attachmentsStore from '../../memory/attachments-store.js';
-import * as channelDeliveryStore from '../../memory/channel-delivery-store.js';
 import {
-  createApprovalRequest,
-  findPendingAccessRequestForRequester,
-} from '../../memory/channel-guardian-store.js';
+  createCanonicalGuardianRequest,
+  listCanonicalGuardianRequests,
+  listPendingCanonicalGuardianRequestsByDestinationChat,
+} from '../../memory/canonical-guardian-store.js';
+import * as channelDeliveryStore from '../../memory/channel-delivery-store.js';
 import { recordConversationSeenSignal } from '../../memory/conversation-attention-store.js';
 import * as conversationStore from '../../memory/conversation-store.js';
 import * as externalConversationStore from '../../memory/external-conversation-store.js';
-import {
-  finalizeFollowup,
-  getDeliveriesByRequestId,
-  getExpiredDeliveriesByDestination,
-  getFollowupDeliveriesByDestination,
-  getGuardianActionRequest,
-  getPendingDeliveriesByDestination,
-  getPendingRequestByCallSessionId,
-  progressFollowupState,
-  resolveGuardianActionRequest,
-  startFollowupFromExpiredRequest,
-} from '../../memory/guardian-action-store.js';
 import { findMember, updateLastSeen, upsertMember } from '../../memory/ingress-member-store.js';
 import { emitNotificationSignal } from '../../notifications/emit-signal.js';
 import { checkIngressForSecrets } from '../../security/secret-ingress.js';
+import { canonicalizeInboundIdentity } from '../../util/canonicalize-identity.js';
 import { IngressBlockedError } from '../../util/errors.js';
 import { getLogger } from '../../util/logger.js';
 import { readHttpToken } from '../../util/platform.js';
+import { notifyGuardianOfAccessRequest } from '../access-request-helper.js';
 import {
   buildApprovalUIMetadata,
   getApprovalInfoByConversation,
@@ -58,11 +46,8 @@ import {
 } from '../channel-guardian-service.js';
 import { getTransport } from '../channel-invite-transport.js';
 import { deliverChannelReply } from '../gateway-client.js';
-import { processGuardianFollowUpTurn } from '../guardian-action-conversation-turn.js';
-import { executeFollowupAction } from '../guardian-action-followup-executor.js';
-import { tryMintGuardianActionGrant } from '../guardian-action-grant-minter.js';
-import { composeGuardianActionMessageGenerative } from '../guardian-action-message-composer.js';
 import { resolveGuardianContext } from '../guardian-context-resolver.js';
+import { routeGuardianReply } from '../guardian-reply-router.js';
 import {
   composeChannelVerifyReply,
   composeVerificationTelegram,
@@ -91,6 +76,7 @@ import { handleApprovalInterception } from './guardian-approval-interception.js'
 import { deliverGeneratedApprovalPrompt } from './guardian-approval-prompt.js';
 
 import '../channel-invite-transports/telegram.js';
+import '../channel-invite-transports/voice.js';
 
 const log = getLogger('runtime-http');
 
@@ -115,8 +101,8 @@ export async function handleChannelInbound(
   gatewayOriginSecret?: string,
   approvalCopyGenerator?: ApprovalCopyGenerator,
   approvalConversationGenerator?: ApprovalConversationGenerator,
-  guardianActionCopyGenerator?: GuardianActionCopyGenerator,
-  guardianFollowUpConversationGenerator?: GuardianFollowUpConversationGenerator,
+  _guardianActionCopyGenerator?: GuardianActionCopyGenerator,
+  _guardianFollowUpConversationGenerator?: GuardianFollowUpConversationGenerator,
 ): Promise<Response> {
   // Reject requests that lack valid gateway-origin proof. This ensures
   // channel inbound messages can only arrive via the gateway (which
@@ -202,6 +188,28 @@ export async function handleChannelInbound(
     log.debug({ raw: assistantId, canonical: canonicalAssistantId }, 'Canonicalized channel assistant ID');
   }
 
+  // Coerce senderExternalUserId to a string at the boundary — the field
+  // comes from unvalidated JSON and may be a number, object, or other
+  // non-string type. Non-string truthy values would throw inside
+  // canonicalizeInboundIdentity when it calls .trim().
+  const rawSenderId = body.senderExternalUserId != null
+    ? String(body.senderExternalUserId)
+    : undefined;
+
+  // Canonicalize the sender identity so all trust lookups, member matching,
+  // and guardian binding comparisons use a normalized form. Phone-like
+  // channels (sms, voice, whatsapp) are normalized to E.164; non-phone
+  // channels pass through the platform-stable ID unchanged.
+  const canonicalSenderId = rawSenderId
+    ? canonicalizeInboundIdentity(sourceChannel, rawSenderId)
+    : null;
+
+  // Track whether the original payload included a sender identity. A
+  // whitespace-only senderExternalUserId canonicalizes to null but still
+  // represents an explicit (malformed) identity claim that must enter the
+  // ACL deny path rather than bypassing it.
+  const hasSenderIdentityClaim = rawSenderId !== undefined;
+
   // ── Ingress ACL enforcement ──
   // Track the resolved member so the escalate branch can reference it after
   // recordInbound (where we have a conversationId).
@@ -222,7 +230,7 @@ export async function handleChannelInbound(
     typeof (rawCommandIntentForAcl as Record<string, unknown>).payload === 'string' &&
     ((rawCommandIntentForAcl as Record<string, unknown>).payload as string).startsWith('gv_');
 
-  // Parse invite token from /start iv_<token> commands using the transport
+  // Parse invite token from /start payloads using the channel transport
   // adapter. The token is extracted once here so both the ACL bypass and
   // the intercept handler can reference it without re-parsing.
   const commandIntentForAcl = rawCommandIntentForAcl && typeof rawCommandIntentForAcl === 'object' && !Array.isArray(rawCommandIntentForAcl)
@@ -235,13 +243,18 @@ export async function handleChannelInbound(
     sourceMetadata: body.sourceMetadata,
   });
 
-  if (body.senderExternalUserId) {
-    resolvedMember = findMember({
-      assistantId: canonicalAssistantId,
-      sourceChannel,
-      externalUserId: body.senderExternalUserId,
-      externalChatId,
-    });
+  if (canonicalSenderId || hasSenderIdentityClaim) {
+    // Only perform member lookup when we have a usable canonical ID.
+    // Whitespace-only senders (hasSenderIdentityClaim=true but
+    // canonicalSenderId=null) skip the lookup and fall into the deny path.
+    if (canonicalSenderId) {
+      resolvedMember = findMember({
+        assistantId: canonicalAssistantId,
+        sourceChannel,
+        externalUserId: canonicalSenderId,
+        externalChatId,
+      });
+    }
 
     if (!resolvedMember) {
       // Determine whether a verification-code bypass is warranted: only allow
@@ -279,7 +292,7 @@ export async function handleChannelInbound(
       }
 
       // ── Invite token intercept (non-member) ──
-      // /start iv_<token> deep links grant access without guardian approval.
+      // /start invite deep links grant access without guardian approval.
       // Intercept here — before the deny gate — so valid invites short-circuit
       // the ACL rejection and never reach the agent pipeline.
       if (inviteToken && denyNonMember) {
@@ -288,7 +301,7 @@ export async function handleChannelInbound(
           sourceChannel,
           externalChatId,
           externalMessageId,
-          senderExternalUserId: body.senderExternalUserId,
+          senderExternalUserId: canonicalSenderId ?? rawSenderId,
           senderName: body.senderName,
           senderUsername: body.senderUsername,
           replyCallbackUrl: body.replyCallbackUrl,
@@ -300,21 +313,22 @@ export async function handleChannelInbound(
       }
 
       if (denyNonMember) {
-        log.info({ sourceChannel, externalUserId: body.senderExternalUserId }, 'Ingress ACL: no member record, denying');
+        log.info({ sourceChannel, externalUserId: canonicalSenderId }, 'Ingress ACL: no member record, denying');
 
         // Notify the guardian about the access request so they can approve/deny.
-        // Only fires when a guardian binding exists and no duplicate pending
-        // request already exists for this requester.
+        // Uses the shared helper which handles guardian binding lookup,
+        // deduplication, canonical request creation, and notification emission.
         let guardianNotified = false;
         try {
-          guardianNotified = notifyGuardianOfAccessRequest({
+          const accessResult = notifyGuardianOfAccessRequest({
             canonicalAssistantId,
             sourceChannel,
             externalChatId,
-            senderExternalUserId: body.senderExternalUserId,
+            senderExternalUserId: canonicalSenderId ?? rawSenderId,
             senderName: body.senderName,
             senderUsername: body.senderUsername,
           });
+          guardianNotified = accessResult.notified;
         } catch (err) {
           log.error({ err, sourceChannel, externalChatId }, 'Failed to notify guardian of access request');
         }
@@ -373,7 +387,7 @@ export async function handleChannelInbound(
             sourceChannel,
             externalChatId,
             externalMessageId,
-            senderExternalUserId: body.senderExternalUserId,
+            senderExternalUserId: canonicalSenderId ?? rawSenderId,
             senderName: body.senderName,
             senderUsername: body.senderUsername,
             replyCallbackUrl: body.replyCallbackUrl,
@@ -393,14 +407,15 @@ export async function handleChannelInbound(
           let guardianNotified = false;
           if (resolvedMember.status !== 'blocked') {
             try {
-              guardianNotified = notifyGuardianOfAccessRequest({
+              const accessResult = notifyGuardianOfAccessRequest({
                 canonicalAssistantId,
                 sourceChannel,
                 externalChatId,
-                senderExternalUserId: body.senderExternalUserId,
+                senderExternalUserId: canonicalSenderId ?? rawSenderId,
                 senderName: body.senderName,
                 senderUsername: body.senderUsername,
               });
+              guardianNotified = accessResult.notified;
             } catch (err) {
               log.error({ err, sourceChannel, externalChatId }, 'Failed to notify guardian of access request');
             }
@@ -570,7 +585,7 @@ export async function handleChannelInbound(
       conversationId: result.conversationId,
       sourceChannel,
       externalChatId,
-      externalUserId: body.senderExternalUserId ?? null,
+      externalUserId: canonicalSenderId ?? rawSenderId ?? null,
       displayName: body.senderName ?? null,
       username: body.senderUsername ?? null,
     });
@@ -600,19 +615,16 @@ export async function handleChannelInbound(
       assistantId: canonicalAssistantId,
     });
 
-    createApprovalRequest({
-      runId: `ingress-escalation-${Date.now()}`,
+    createCanonicalGuardianRequest({
+      kind: 'tool_approval',
+      sourceType: 'channel',
+      sourceChannel,
       conversationId: result.conversationId,
-      assistantId: canonicalAssistantId,
-      channel: sourceChannel,
-      requesterExternalUserId: body.senderExternalUserId ?? '',
-      requesterChatId: externalChatId,
+      requesterExternalUserId: canonicalSenderId ?? rawSenderId ?? undefined,
       guardianExternalUserId: binding.guardianExternalUserId,
-      guardianChatId: binding.guardianDeliveryChatId,
       toolName: 'ingress_message',
-      riskLevel: 'escalated_ingress',
-      reason: 'Ingress policy requires guardian approval',
-      expiresAt: Date.now() + GUARDIAN_APPROVAL_TTL_MS,
+      questionText: 'Ingress policy requires guardian approval',
+      expiresAt: new Date(Date.now() + GUARDIAN_APPROVAL_TTL_MS).toISOString(),
     });
 
     // Emit notification signal through the unified pipeline (fire-and-forget).
@@ -633,7 +645,7 @@ export async function handleChannelInbound(
         conversationId: result.conversationId,
         sourceChannel,
         externalChatId,
-        senderIdentifier: body.senderName || body.senderUsername || body.senderExternalUserId || 'Unknown sender',
+        senderIdentifier: body.senderName || body.senderUsername || rawSenderId || 'Unknown sender',
         eventId: result.eventId,
       },
       dedupeKey: `escalation:${result.eventId}`,
@@ -679,14 +691,14 @@ export async function handleChannelInbound(
     commandIntent?.type === 'start' &&
     typeof commandIntent.payload === 'string' &&
     (commandIntent.payload as string).startsWith('gv_') &&
-    body.senderExternalUserId
+    rawSenderId
   ) {
     const bootstrapToken = (commandIntent.payload as string).slice(3);
     const bootstrapSession = resolveBootstrapToken(canonicalAssistantId, sourceChannel, bootstrapToken);
 
     if (bootstrapSession && bootstrapSession.status === 'pending_bootstrap') {
       // Bind the pending_bootstrap session to the sender's identity
-      bindSessionIdentity(bootstrapSession.id, body.senderExternalUserId, externalChatId);
+      bindSessionIdentity(bootstrapSession.id, rawSenderId!, externalChatId);
 
       // Transition bootstrap session to awaiting_response
       updateSessionStatus(bootstrapSession.id, 'awaiting_response');
@@ -696,7 +708,7 @@ export async function handleChannelInbound(
       const newSession = createOutboundSession({
         assistantId: canonicalAssistantId,
         channel: sourceChannel,
-        expectedExternalUserId: body.senderExternalUserId,
+        expectedExternalUserId: rawSenderId!,
         expectedChatId: externalChatId,
         identityBindingStatus: 'bound',
         destinationAddress: externalChatId,
@@ -748,13 +760,13 @@ export async function handleChannelInbound(
     !result.duplicate &&
     shouldInterceptVerification &&
     guardianVerifyCode !== undefined &&
-    body.senderExternalUserId
+    rawSenderId
   ) {
     const verifyResult = validateAndConsumeChallenge(
       canonicalAssistantId,
       sourceChannel,
       guardianVerifyCode,
-      body.senderExternalUserId,
+      canonicalSenderId ?? rawSenderId!,
       externalChatId,
       body.senderUsername,
       body.senderName,
@@ -763,21 +775,37 @@ export async function handleChannelInbound(
     const guardianVerifyOutcome: 'verified' | 'failed' = verifyResult.success ? 'verified' : 'failed';
 
     if (verifyResult.success) {
+      const existingMember = (canonicalSenderId ?? rawSenderId)
+        ? findMember({
+          assistantId: canonicalAssistantId,
+          sourceChannel,
+          externalUserId: canonicalSenderId ?? rawSenderId!,
+          externalChatId,
+        })
+        : null;
+      const memberMatchesSender = existingMember?.externalUserId
+        ? canonicalizeInboundIdentity(sourceChannel, existingMember.externalUserId) === (canonicalSenderId ?? rawSenderId)
+        : false;
+      const preservedDisplayName = memberMatchesSender && existingMember?.displayName?.trim().length
+        ? existingMember.displayName
+        : body.senderName;
+
       upsertMember({
         assistantId: canonicalAssistantId,
         sourceChannel,
-        externalUserId: body.senderExternalUserId,
+        externalUserId: canonicalSenderId ?? rawSenderId!,
         externalChatId,
         status: 'active',
         policy: 'allow',
-        displayName: body.senderName,
+        // Keep guardian-curated member name stable across re-verification.
+        displayName: preservedDisplayName,
         username: body.senderUsername,
       });
 
       const verifyLogLabel = verifyResult.verificationType === 'trusted_contact'
         ? 'Trusted contact verified'
         : 'Guardian verified';
-      log.info({ sourceChannel, externalUserId: body.senderExternalUserId, verificationType: verifyResult.verificationType }, `${verifyLogLabel}: auto-upserted ingress member`);
+      log.info({ sourceChannel, externalUserId: canonicalSenderId, verificationType: verifyResult.verificationType }, `${verifyLogLabel}: auto-upserted ingress member`);
 
       // Emit activated signal when a trusted contact completes verification.
       // Member record is persisted above before this event fires, satisfying
@@ -796,12 +824,12 @@ export async function handleChannelInbound(
           },
           contextPayload: {
             sourceChannel,
-            externalUserId: body.senderExternalUserId,
+            externalUserId: canonicalSenderId ?? rawSenderId!,
             externalChatId,
             senderName: body.senderName ?? null,
             senderUsername: body.senderUsername ?? null,
           },
-          dedupeKey: `trusted-contact:activated:${canonicalAssistantId}:${sourceChannel}:${body.senderExternalUserId}`,
+          dedupeKey: `trusted-contact:activated:${canonicalAssistantId}:${sourceChannel}:${canonicalSenderId ?? rawSenderId!}`,
         });
       }
     }
@@ -873,382 +901,126 @@ export async function handleChannelInbound(
     });
   }
 
-  // ── Unified guardian action answer interception ──
-  // Deterministic priority matching: pending → follow-up → expired.
-  // When the guardian includes an explicit request code, match it across all
-  // states in priority order. When only one actionable request exists,
-  // auto-match without requiring a code prefix. Callback payloads (inline
-  // button presses) are excluded — they should not be misclassified as
-  // guardian answers.
-  if (
-    !result.duplicate &&
-    !hasCallbackData &&
-    trimmedContent.length > 0 &&
-    body.senderExternalUserId &&
-    replyCallbackUrl
-  ) {
-    // Gather deliveries across all states for this destination, filtered by sender identity
-    const allPending = getPendingDeliveriesByDestination(canonicalAssistantId, sourceChannel, externalChatId)
-      .filter((d) => d.destinationExternalUserId === body.senderExternalUserId);
-    const allFollowup = getFollowupDeliveriesByDestination(canonicalAssistantId, sourceChannel, externalChatId)
-      .filter((d) => d.destinationExternalUserId === body.senderExternalUserId);
-    const allExpired = getExpiredDeliveriesByDestination(canonicalAssistantId, sourceChannel, externalChatId)
-      .filter((d) => d.destinationExternalUserId === body.senderExternalUserId);
-    const totalActionable = allPending.length + allFollowup.length + allExpired.length;
-
-    if (totalActionable > 0) {
-      // ── Try to parse an explicit request code from the message ──
-      // Check all deliveries across states for a code prefix match, in priority order
-      type CodeMatch = { delivery: typeof allPending[0]; request: NonNullable<ReturnType<typeof getGuardianActionRequest>>; state: 'pending' | 'followup' | 'expired'; answerText: string };
-      let codeMatch: CodeMatch | null = null;
-      const upperContent = trimmedContent.toUpperCase();
-      const orderedSets: Array<{ deliveries: typeof allPending; state: 'pending' | 'followup' | 'expired' }> = [
-        { deliveries: allPending, state: 'pending' },
-        { deliveries: allFollowup, state: 'followup' },
-        { deliveries: allExpired, state: 'expired' },
-      ];
-      for (const { deliveries, state } of orderedSets) {
-        for (const d of deliveries) {
-          const req = getGuardianActionRequest(d.requestId);
-          if (req && upperContent.startsWith(req.requestCode)) {
-            codeMatch = { delivery: d, request: req, state, answerText: trimmedContent.slice(req.requestCode.length).trim() };
-            break;
-          }
-        }
-        if (codeMatch) break;
-      }
+  // Legacy voice guardian action interception removed — all guardian reply
+  // routing now flows through the canonical router below (routeGuardianReply),
+  // which handles request code matching, callback parsing, and NL classification
+  // against canonical_guardian_requests.
 
-      // ── Explicit code targets a non-pending state: handle terminal/remap ──
-      if (codeMatch && codeMatch.state !== 'pending') {
-        const targetReq = codeMatch.request;
-
-        // Superseded request with no active call → terminal notice
-        if (targetReq.status === 'expired' && targetReq.expiredReason === 'superseded') {
-          const callSession = getCallSession(targetReq.callSessionId);
-          const callStillActive = callSession && !isTerminalState(callSession.status);
-          if (!callStillActive) {
-            const staleText = await composeGuardianActionMessageGenerative(
-              { scenario: 'guardian_stale_superseded' },
-              {},
-              guardianActionCopyGenerator,
-            );
-            try {
-              await deliverChannelReply(replyCallbackUrl, { chatId: externalChatId, text: staleText, assistantId }, bearerToken);
-            } catch (err) {
-              log.error({ err, externalChatId }, 'Failed to deliver superseded terminal notice');
-            }
-            return Response.json({ accepted: true, duplicate: false, eventId: result.eventId, guardianAnswer: 'stale_superseded' });
-          }
-        }
+  // ── Actor role resolution ──
+  // Uses shared channel-agnostic resolution so all ingress paths classify
+  // guardian vs non-guardian actors the same way.
+  const guardianCtx: GuardianContext = resolveGuardianContext({
+    assistantId: canonicalAssistantId,
+    sourceChannel,
+    externalChatId,
+    senderExternalUserId: rawSenderId,
+    senderUsername: body.senderUsername,
+    senderDisplayName: body.senderName,
+  });
 
-        // If the code pointed to expired/follow-up but there's a pending request,
-        // route intentionally to the expired/follow-up handler with explanation
-        // (the per-state blocks below will pick it up via codeMatch).
-      }
+  // Hoisted flag: set by the canonical guardian reply router when the invite
+  // handoff bypass fires. Prevents legacy approval interception from swallowing
+  // the message when other approvals are pending in the same chat.
+  let skipApprovalInterception = false;
 
-      // ── Auto-match: single actionable request across all states ──
-      // When there's only one request and no explicit code, auto-match directly
-      if (!codeMatch && totalActionable === 1) {
-        const singleDelivery = allPending[0] ?? allFollowup[0] ?? allExpired[0];
-        const singleReq = getGuardianActionRequest(singleDelivery.requestId);
-        if (singleReq) {
-          const state: 'pending' | 'followup' | 'expired' = allPending.length === 1 ? 'pending' : allFollowup.length === 1 ? 'followup' : 'expired';
-          // Strip the code prefix if the guardian uses it out of habit
-          let text = trimmedContent;
-          if (upperContent.startsWith(singleReq.requestCode)) {
-            text = trimmedContent.slice(singleReq.requestCode.length).trim();
-          }
-          codeMatch = { delivery: singleDelivery, request: singleReq, state, answerText: text };
-        }
+  // ── Canonical guardian reply router ──
+  // Attempts to route inbound messages through the canonical decision pipeline
+  // before falling through to the legacy approval interception. Handles
+  // deterministic callbacks (button presses), request code prefixes, and
+  // NL classification via the conversational approval engine.
+  if (
+    !result.duplicate &&
+    replyCallbackUrl &&
+    (trimmedContent.length > 0 || hasCallbackData) &&
+    rawSenderId &&
+    guardianCtx.trustClass === 'guardian'
+  ) {
+    // Compute destination-scoped pending request hints so the router can
+    // discover canonical requests delivered to this chat even when the
+    // request lacks a guardianExternalUserId (e.g. voice-originated
+    // pending_question requests).
+    //
+    // When delivery-scoped matches exist, union them with any identity-
+    // based pending requests so that requests without delivery rows (e.g.
+    // tool_approval requests created inline) are not silently excluded.
+    // Pass undefined (not []) when there are zero combined results so the
+    // router's own identity-based fallback stays active.
+    const deliveryScopedPendingRequests = listPendingCanonicalGuardianRequestsByDestinationChat(
+      sourceChannel,
+      externalChatId,
+    );
+    let pendingRequestIds: string[] | undefined;
+    if (deliveryScopedPendingRequests.length > 0) {
+      const deliveryIds = new Set(deliveryScopedPendingRequests.map(r => r.id));
+      // Also include identity-based pending requests so we don't hide them
+      const identityId = canonicalSenderId ?? rawSenderId!;
+      const identityPending = listCanonicalGuardianRequests({
+        status: 'pending',
+        guardianExternalUserId: identityId,
+      });
+      for (const r of identityPending) {
+        deliveryIds.add(r.id);
       }
+      pendingRequestIds = [...deliveryIds];
+    }
 
-      // ── Unknown code: message looks like a code prefix but doesn't match anything ──
-      // Detect when the message starts with a 6-char alphanumeric token that
-      // resembles a request code but doesn't match any known delivery.
-      if (!codeMatch && totalActionable > 0) {
-        const possibleCodeMatch = trimmedContent.match(/^([A-F0-9]{6})\s/i);
-        if (possibleCodeMatch) {
-          const candidateCode = possibleCodeMatch[1].toUpperCase();
-          // Check if this code exists in ANY delivery across states
-          const allDeliveries = [...allPending, ...allFollowup, ...allExpired];
-          const knownCodes = allDeliveries
-            .map((d) => { const req = getGuardianActionRequest(d.requestId); return req?.requestCode; })
-            .filter((code): code is string => typeof code === 'string');
-          const isKnown = knownCodes.includes(candidateCode);
-          if (!isKnown) {
-            const unknownText = await composeGuardianActionMessageGenerative(
-              { scenario: 'guardian_unknown_code', unknownCode: candidateCode },
-              {},
-              guardianActionCopyGenerator,
-            );
-            try {
-              await deliverChannelReply(replyCallbackUrl, { chatId: externalChatId, text: unknownText, assistantId }, bearerToken);
-            } catch (err) {
-              log.error({ err, externalChatId }, 'Failed to deliver unknown code notice');
-            }
-            return Response.json({ accepted: true, duplicate: false, eventId: result.eventId, guardianAnswer: 'unknown_code' });
-          }
-        }
-      }
+    const routerResult = await routeGuardianReply({
+      messageText: trimmedContent,
+      channel: sourceChannel,
+      actor: {
+        externalUserId: canonicalSenderId ?? rawSenderId!,
+        channel: sourceChannel,
+        isTrusted: false,
+      },
+      conversationId: result.conversationId,
+      callbackData: body.callbackData,
+      pendingRequestIds,
+      approvalConversationGenerator,
+      channelDeliveryContext: {
+        replyCallbackUrl,
+        guardianChatId: externalChatId,
+        assistantId: canonicalAssistantId,
+        bearerToken,
+      },
+    });
 
-      // ── No match and multiple actionable requests → disambiguation ──
-      if (!codeMatch && totalActionable > 1) {
-        const allDeliveries = [...allPending, ...allFollowup, ...allExpired];
-        const codes = allDeliveries
-          .map((d) => { const req = getGuardianActionRequest(d.requestId); return req ? req.requestCode : null; })
-          .filter((code): code is string => typeof code === 'string' && code.length > 0);
-
-        // Choose the appropriate disambiguation scenario based on which states are present
-        const disambiguationScenario = allPending.length > 0
-          ? 'guardian_pending_disambiguation' as const
-          : allFollowup.length > 0
-            ? 'guardian_followup_disambiguation' as const
-            : 'guardian_expired_disambiguation' as const;
-
-        const disambiguationText = await composeGuardianActionMessageGenerative(
-          { scenario: disambiguationScenario, requestCodes: codes, channel: sourceChannel },
-          { requiredKeywords: codes },
-          guardianActionCopyGenerator,
-        );
+    if (routerResult.consumed) {
+      // Deliver reply text if the router produced one
+      if (routerResult.replyText) {
         try {
-          await deliverChannelReply(replyCallbackUrl, { chatId: externalChatId, text: disambiguationText, assistantId }, bearerToken);
+          await deliverChannelReply(replyCallbackUrl, {
+            chatId: externalChatId,
+            text: routerResult.replyText,
+            assistantId: canonicalAssistantId,
+          }, bearerToken);
         } catch (err) {
-          log.error({ err, externalChatId }, 'Failed to deliver guardian action disambiguation message');
+          log.error({ err, externalChatId }, 'Failed to deliver canonical router reply');
         }
-        return Response.json({ accepted: true, duplicate: false, eventId: result.eventId, guardianAnswer: 'disambiguation_sent' });
       }
 
-      // ── Dispatch matched delivery by state ──
-      if (codeMatch) {
-        const { request, state, answerText } = codeMatch;
-
-        // ── PENDING state handler ──
-        if (state === 'pending' && request.status === 'pending') {
-          const answerResult = await answerCall({ callSessionId: request.callSessionId, answer: answerText, pendingQuestionId: request.pendingQuestionId });
-
-          if (!('ok' in answerResult) || !answerResult.ok) {
-            const errorMsg = 'error' in answerResult ? answerResult.error : 'Unknown error';
-            log.warn({ callSessionId: request.callSessionId, error: errorMsg }, 'answerCall failed for guardian answer');
-            try {
-              const failureText = await composeGuardianActionMessageGenerative(
-                { scenario: 'guardian_answer_delivery_failed' },
-                {},
-                guardianActionCopyGenerator,
-              );
-              await deliverChannelReply(replyCallbackUrl, { chatId: externalChatId, text: failureText, assistantId }, bearerToken);
-            } catch (deliverErr) {
-              log.error({ err: deliverErr, externalChatId }, 'Failed to deliver guardian answer failure notice');
-            }
-            return Response.json({ accepted: true, duplicate: false, eventId: result.eventId, guardianAnswer: 'answer_failed' });
-          }
-
-          const resolved = resolveGuardianActionRequest(request.id, answerText, sourceChannel, body.senderExternalUserId);
-
-          if (resolved) {
-            await tryMintGuardianActionGrant({
-              request,
-              answerText,
-              decisionChannel: sourceChannel,
-              guardianExternalUserId: body.senderExternalUserId,
-              approvalConversationGenerator,
-            });
-
-            return Response.json({ accepted: true, duplicate: false, eventId: result.eventId, guardianAnswer: 'resolved' });
-          } else {
-            const freshRequest = getGuardianActionRequest(request.id);
-            const relayedText = await composeGuardianActionMessageGenerative(
-              { scenario: 'guardian_stale_answered' as const },
-              {},
-              guardianActionCopyGenerator,
-            );
-            try {
-              await deliverChannelReply(replyCallbackUrl, { chatId: externalChatId, text: relayedText, assistantId }, bearerToken);
-            } catch (err) {
-              log.error({ err, externalChatId }, 'Failed to deliver guardian action stale notice');
-            }
-            log.info(
-              { requestId: request.id, freshStatus: freshRequest?.status },
-              'answerCall succeeded but resolveGuardianActionRequest returned null — informed guardian answer was relayed',
-            );
-            return Response.json({ accepted: true, duplicate: false, eventId: result.eventId, guardianAnswer: 'stale' });
-          }
-        }
-
-        // ── FOLLOW-UP state handler ──
-        if (state === 'followup' && request.followupState === 'awaiting_guardian_choice') {
-          const turnResult = await processGuardianFollowUpTurn(
-            {
-              questionText: request.questionText,
-              lateAnswerText: request.lateAnswerText ?? '',
-              guardianReply: answerText,
-            },
-            guardianFollowUpConversationGenerator,
-          );
-
-          let stateApplied = true;
-          if (turnResult.disposition === 'call_back' || turnResult.disposition === 'message_back') {
-            stateApplied = progressFollowupState(request.id, 'dispatching', turnResult.disposition) !== null;
-          } else if (turnResult.disposition === 'decline') {
-            stateApplied = finalizeFollowup(request.id, 'declined') !== null;
-          }
-
-          if (!stateApplied) {
-            log.warn({ requestId: request.id, disposition: turnResult.disposition }, 'Follow-up state transition failed (already resolved)');
-            const staleText = await composeGuardianActionMessageGenerative(
-              { scenario: 'guardian_stale_followup' as const },
-              {},
-              guardianActionCopyGenerator,
-            );
-            try {
-              await deliverChannelReply(replyCallbackUrl, { chatId: externalChatId, text: staleText, assistantId }, bearerToken);
-            } catch (err) {
-              log.error({ err, externalChatId }, 'Failed to deliver stale follow-up notice');
-            }
-            return Response.json({ accepted: true, duplicate: false, eventId: result.eventId, guardianFollowUp: 'stale_ignored' });
-          }
-
-          try {
-            await deliverChannelReply(replyCallbackUrl, { chatId: externalChatId, text: turnResult.replyText, assistantId }, bearerToken);
-          } catch (err) {
-            log.error({ err, externalChatId }, 'Failed to deliver guardian follow-up conversation reply');
-          }
-
-          if (turnResult.disposition === 'call_back' || turnResult.disposition === 'message_back') {
-            void (async () => {
-              try {
-                const execResult = await executeFollowupAction(
-                  request.id,
-                  turnResult.disposition as 'call_back' | 'message_back',
-                  guardianActionCopyGenerator,
-                );
-                await deliverChannelReply(replyCallbackUrl, { chatId: externalChatId, text: execResult.guardianReplyText, assistantId }, bearerToken);
-              } catch (execErr) {
-                log.error({ err: execErr, requestId: request.id }, 'Follow-up action execution or completion reply failed');
-              }
-            })();
-          }
-
-          return Response.json({ accepted: true, duplicate: false, eventId: result.eventId, guardianFollowUp: turnResult.disposition });
-        }
-
-        // ── EXPIRED state handler ──
-        if (state === 'expired' && request.status === 'expired' && request.followupState === 'none') {
-          // Superseded remap: if the request was superseded (not timed out
-          // or disconnected), check whether the call is still active with a
-          // current pending request. If so, remap the late approval to the
-          // current request instead of entering the callback/message follow-up.
-          if (request.expiredReason === 'superseded') {
-            const callSession = getCallSession(request.callSessionId);
-            const callStillActive = callSession && !isTerminalState(callSession.status);
-            const currentPending = callStillActive
-              ? getPendingRequestByCallSessionId(request.callSessionId)
-              : null;
-
-            if (callStillActive && currentPending) {
-              const currentDeliveries = getDeliveriesByRequestId(currentPending.id);
-              // When senderExternalUserId is present, verify the sender has a
-              // matching delivery on the current pending request. When it's absent
-              // (trusted session), allow the remap without delivery check.
-              const senderHasDelivery = body.senderExternalUserId
-                ? currentDeliveries.some((d) => d.destinationExternalUserId === body.senderExternalUserId)
-                : true;
-              if (!senderHasDelivery) {
-                log.info(
-                  { supersededRequestId: request.id, currentRequestId: currentPending.id, senderExternalUserId: body.senderExternalUserId },
-                  'Superseded remap skipped: sender has no delivery on current pending request',
-                );
-              } else {
-                const remapResult = await answerCall({
-                  callSessionId: currentPending.callSessionId,
-                  answer: answerText,
-                  pendingQuestionId: currentPending.pendingQuestionId,
-                });
-
-                if ('ok' in remapResult && remapResult.ok) {
-                  const resolved = resolveGuardianActionRequest(currentPending.id, answerText, sourceChannel, body.senderExternalUserId);
-
-                  if (resolved) {
-                    await tryMintGuardianActionGrant({
-                      request: currentPending,
-                      answerText,
-                      decisionChannel: sourceChannel,
-                      guardianExternalUserId: body.senderExternalUserId,
-                      approvalConversationGenerator,
-                    });
-                  }
-
-                  const remapText = await composeGuardianActionMessageGenerative(
-                    { scenario: 'guardian_superseded_remap', questionText: currentPending.questionText },
-                    {},
-                    guardianActionCopyGenerator,
-                  );
-                  try {
-                    await deliverChannelReply(replyCallbackUrl, { chatId: externalChatId, text: remapText, assistantId }, bearerToken);
-                  } catch (err) {
-                    log.error({ err, externalChatId }, 'Failed to deliver superseded remap confirmation');
-                  }
-                  log.info(
-                    { supersededRequestId: request.id, remappedToRequestId: currentPending.id },
-                    'Late approval for superseded request remapped to current pending request',
-                  );
-                  return Response.json({ accepted: true, duplicate: false, eventId: result.eventId, guardianAnswer: 'superseded_remapped' });
-                }
-                log.warn(
-                  { callSessionId: currentPending.callSessionId, error: 'error' in remapResult ? remapResult.error : 'unknown' },
-                  'Superseded remap answerCall failed, falling through to follow-up',
-                );
-              }
-            }
-            // Call not active or no pending request — fall through to follow-up
-          }
+      return Response.json({
+        accepted: true,
+        duplicate: false,
+        eventId: result.eventId,
+        canonicalRouter: routerResult.type,
+        requestId: routerResult.requestId,
+      });
+    }
 
-          const followupResult = startFollowupFromExpiredRequest(request.id, answerText);
-          if (followupResult) {
-            const followupText = await composeGuardianActionMessageGenerative(
-              { scenario: 'guardian_late_answer_followup', questionText: request.questionText, lateAnswerText: answerText },
-              {},
-              guardianActionCopyGenerator,
-            );
-            try {
-              await deliverChannelReply(replyCallbackUrl, { chatId: externalChatId, text: followupText, assistantId }, bearerToken);
-            } catch (err) {
-              log.error({ err, externalChatId }, 'Failed to deliver guardian action late answer follow-up');
-            }
-            return Response.json({ accepted: true, duplicate: false, eventId: result.eventId, guardianAnswer: 'followup_initiated' });
-          } else {
-            const staleText = await composeGuardianActionMessageGenerative(
-              { scenario: 'guardian_stale_expired' as const },
-              {},
-              guardianActionCopyGenerator,
-            );
-            try {
-              await deliverChannelReply(replyCallbackUrl, { chatId: externalChatId, text: staleText, assistantId }, bearerToken);
-            } catch (err) {
-              log.error({ err, externalChatId }, 'Failed to deliver guardian action stale notice for expired follow-up race');
-            }
-            return Response.json({ accepted: true, duplicate: false, eventId: result.eventId, guardianAnswer: 'stale' });
-          }
-        }
-      }
+    if (routerResult.skipApprovalInterception) {
+      skipApprovalInterception = true;
     }
   }
 
-  // ── Actor role resolution ──
-  // Uses shared channel-agnostic resolution so all ingress paths classify
-  // guardian vs non-guardian actors the same way.
-  const guardianCtx: GuardianContext = resolveGuardianContext({
-    assistantId: canonicalAssistantId,
-    sourceChannel,
-    externalChatId,
-    senderExternalUserId: body.senderExternalUserId,
-    senderUsername: body.senderUsername,
-  });
-
   // ── Approval interception ──
   // Keep this active whenever callback context is available.
+  // Skipped when the canonical router flagged skipApprovalInterception (e.g.
+  // invite handoff bypass) to prevent the legacy interceptor from swallowing
+  // messages that should reach the assistant.
   if (
     replyCallbackUrl &&
-    !result.duplicate
+    !result.duplicate &&
+    !skipApprovalInterception
   ) {
     const approvalResult = await handleApprovalInterception({
       conversationId: result.conversationId,
@@ -1256,7 +1028,7 @@ export async function handleChannelInbound(
       content: trimmedContent,
       externalChatId,
       sourceChannel,
-      senderExternalUserId: body.senderExternalUserId,
+      senderExternalUserId: canonicalSenderId ?? rawSenderId,
       replyCallbackUrl,
       bearerToken,
       guardianCtx,
@@ -1547,111 +1319,6 @@ async function handleInviteTokenIntercept(params: {
   return Response.json({ accepted: true, eventId: dedupResult.eventId, denied: true, inviteRedemption: outcome.reason });
 }
 
-// ---------------------------------------------------------------------------
-// Non-member access request notification
-// ---------------------------------------------------------------------------
-
-/**
- * Fire-and-forget: look up the guardian binding and, if present, create an
- * approval request + emit a notification signal so the guardian can
- * approve/deny the unknown user. Deduplicates by checking for an existing
- * pending approval for the same (requester, assistant, channel).
- */
-function notifyGuardianOfAccessRequest(params: {
-  canonicalAssistantId: string;
-  sourceChannel: ChannelId;
-  externalChatId: string;
-  senderExternalUserId?: string;
-  senderName?: string;
-  senderUsername?: string;
-}): boolean {
-  const {
-    canonicalAssistantId,
-    sourceChannel,
-    externalChatId,
-    senderExternalUserId,
-    senderName,
-    senderUsername,
-  } = params;
-
-  if (!senderExternalUserId) return false;
-
-  const binding = getGuardianBinding(canonicalAssistantId, sourceChannel);
-  if (!binding) {
-    log.debug({ sourceChannel, canonicalAssistantId }, 'No guardian binding for access request notification');
-    return false;
-  }
-
-  // Deduplicate: skip if there is already a pending approval request for
-  // the same requester on this channel.  Still return true — the guardian
-  // was already notified for this request.
-  const existing = findPendingAccessRequestForRequester(
-    canonicalAssistantId,
-    sourceChannel,
-    senderExternalUserId,
-    'ingress_access_request',
-  );
-  if (existing) {
-    log.debug(
-      { sourceChannel, senderExternalUserId, existingId: existing.id },
-      'Skipping duplicate access request notification',
-    );
-    return true;
-  }
-
-  const senderIdentifier = senderName || senderUsername || senderExternalUserId;
-  const requestId = `access-req-${canonicalAssistantId}-${sourceChannel}-${senderExternalUserId}-${Date.now()}`;
-
-  const approvalRequest = createApprovalRequest({
-    runId: `ingress-access-request-${Date.now()}`,
-    requestId,
-    conversationId: `access-req-${sourceChannel}-${senderExternalUserId}`,
-    assistantId: canonicalAssistantId,
-    channel: sourceChannel,
-    requesterExternalUserId: senderExternalUserId,
-    requesterChatId: externalChatId,
-    guardianExternalUserId: binding.guardianExternalUserId,
-    guardianChatId: binding.guardianDeliveryChatId,
-    toolName: 'ingress_access_request',
-    riskLevel: 'access_request',
-    reason: `${senderIdentifier} is requesting access to the assistant`,
-    expiresAt: Date.now() + GUARDIAN_APPROVAL_TTL_MS,
-  });
-
-  void emitNotificationSignal({
-    sourceEventName: 'ingress.access_request',
-    sourceChannel,
-    sourceSessionId: `access-req-${sourceChannel}-${senderExternalUserId}`,
-    assistantId: canonicalAssistantId,
-    attentionHints: {
-      requiresAction: true,
-      urgency: 'high',
-      isAsyncBackground: false,
-      visibleInSourceNow: false,
-    },
-    contextPayload: {
-      requestId,
-      sourceChannel,
-      externalChatId,
-      senderExternalUserId,
-      senderName: senderName ?? null,
-      senderUsername: senderUsername ?? null,
-      senderIdentifier,
-    },
-    // Scoped to the approval request ID so duplicate notifications for the
-    // same request are suppressed, but a new request (after deny/expire)
-    // gets its own dedupe key and the guardian is notified again.
-    dedupeKey: `access-request:${approvalRequest.id}`,
-  });
-
-  log.info(
-    { sourceChannel, senderExternalUserId, senderIdentifier },
-    'Guardian notified of non-member access request',
-  );
-
-  return true;
-}
-
 // ---------------------------------------------------------------------------
 // Background message processing
 // ---------------------------------------------------------------------------
@@ -1733,6 +1400,7 @@ function startPendingApprovalPromptWatcher(params: {
   conversationId: string;
   sourceChannel: ChannelId;
   externalChatId: string;
+  guardianTrustClass: GuardianContext['trustClass'];
   replyCallbackUrl: string;
   bearerToken?: string;
   assistantId?: string;
@@ -1742,12 +1410,19 @@ function startPendingApprovalPromptWatcher(params: {
     conversationId,
     sourceChannel,
     externalChatId,
+    guardianTrustClass,
     replyCallbackUrl,
     bearerToken,
     assistantId,
     approvalCopyGenerator,
   } = params;
 
+  // Approval prompt delivery is guardian-only. Non-guardian and unverified
+  // actors must never receive approval prompt broadcasts for the conversation.
+  if (guardianTrustClass !== 'guardian') {
+    return () => {};
+  }
+
   let active = true;
   const deliveredRequestIds = new Set<string>();
 
@@ -1826,6 +1501,7 @@ function processChannelMessageInBackground(params: BackgroundProcessingParams):
         conversationId,
         sourceChannel,
         externalChatId,
+        guardianTrustClass: guardianCtx.trustClass,
         replyCallbackUrl,
         bearerToken,
         assistantId,
@@ -1849,7 +1525,7 @@ function processChannelMessageInBackground(params: BackgroundProcessingParams):
           },
           assistantId,
           guardianContext: toGuardianRuntimeContext(sourceChannel, guardianCtx),
-          isInteractive: guardianCtx.actorRole === 'guardian',
+          isInteractive: guardianCtx.trustClass === 'guardian',
           ...(cmdIntent ? { commandIntent: cmdIntent } : {}),
         },
         sourceChannel,