@vellumai/assistant 0.3.18 → 0.3.20

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

@@ -1,9 +1,14 @@
 /**
  * Channel inbound message handler: validates, records, and routes inbound
  * messages from all channels. Handles ingress ACL, edits, guardian
- * verification, guardian action answers, and approval interception.
+ * verification, guardian action answers, approval interception, and
+ * invite token redemption.
  */
+// 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';
@@ -19,10 +24,12 @@ 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,
@@ -49,9 +56,11 @@ import {
   updateSessionStatus,
   validateAndConsumeChallenge,
 } 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 {
@@ -67,6 +76,8 @@ import type {
   GuardianFollowUpConversationGenerator,
   MessageProcessor,
 } from '../http-types.js';
+import { redeemInvite } from '../invite-redemption-service.js';
+import { getInviteRedemptionReply } from '../invite-redemption-templates.js';
 import { deliverReplyViaCallback } from './channel-delivery-routes.js';
 import {
   canonicalChannelAssistantId,
@@ -79,6 +90,8 @@ import {
 import { handleApprovalInterception } from './guardian-approval-interception.js';
 import { deliverGeneratedApprovalPrompt } from './guardian-approval-prompt.js';
 
+import '../channel-invite-transports/telegram.js';
+
 const log = getLogger('runtime-http');
 
 /**
@@ -209,6 +222,19 @@ 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
+  // 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)
+    ? rawCommandIntentForAcl as Record<string, unknown>
+    : undefined;
+  const inviteTransport = getTransport(sourceChannel);
+  const inviteToken = inviteTransport?.extractInboundToken({
+    commandIntent: commandIntentForAcl,
+    content: trimmedContent,
+    sourceMetadata: body.sourceMetadata,
+  });
+
   if (body.senderExternalUserId) {
     resolvedMember = findMember({
       assistantId: canonicalAssistantId,
@@ -252,25 +278,36 @@ export async function handleChannelInbound(
         }
       }
 
+      // ── Invite token intercept (non-member) ──
+      // /start iv_<token> 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) {
+        const inviteResult = await handleInviteTokenIntercept({
+          rawToken: inviteToken,
+          sourceChannel,
+          externalChatId,
+          externalMessageId,
+          senderExternalUserId: body.senderExternalUserId,
+          senderName: body.senderName,
+          senderUsername: body.senderUsername,
+          replyCallbackUrl: body.replyCallbackUrl,
+          bearerToken,
+          assistantId,
+          canonicalAssistantId,
+        });
+        if (inviteResult) return inviteResult;
+      }
+
       if (denyNonMember) {
         log.info({ sourceChannel, externalUserId: body.senderExternalUserId }, 'Ingress ACL: no member record, denying');
-        if (body.replyCallbackUrl) {
-          try {
-            await deliverChannelReply(body.replyCallbackUrl, {
-              chatId: externalChatId,
-              text: "Sorry, you haven't been approved to message this assistant. You can ask its Guardian for an invite.",
-              assistantId,
-            }, bearerToken);
-          } catch (err) {
-            log.error({ err, externalChatId }, 'Failed to deliver ACL rejection reply');
-          }
-        }
 
         // 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.
+        let guardianNotified = false;
         try {
-          notifyGuardianOfAccessRequest({
+          guardianNotified = notifyGuardianOfAccessRequest({
             canonicalAssistantId,
             sourceChannel,
             externalChatId,
@@ -282,25 +319,109 @@ export async function handleChannelInbound(
           log.error({ err, sourceChannel, externalChatId }, 'Failed to notify guardian of access request');
         }
 
-        return Response.json({ accepted: true, denied: true, reason: 'not_a_member' });
-      }
-    }
-
-    if (resolvedMember) {
-      if (resolvedMember.status !== 'active') {
-        log.info({ sourceChannel, memberId: resolvedMember.id, status: resolvedMember.status }, 'Ingress ACL: member not active, denying');
         if (body.replyCallbackUrl) {
+          const replyText = guardianNotified
+            ? "Hmm looks like you don't have access to talk to me. I'll let them know you tried talking to me and get back to you."
+            : "Sorry, you haven't been approved to message this assistant.";
           try {
             await deliverChannelReply(body.replyCallbackUrl, {
               chatId: externalChatId,
-              text: "Sorry, you haven't been approved to message this assistant. You can ask its Guardian for an invite.",
+              text: replyText,
               assistantId,
             }, bearerToken);
           } catch (err) {
             log.error({ err, externalChatId }, 'Failed to deliver ACL rejection reply');
           }
         }
-        return Response.json({ accepted: true, denied: true, reason: `member_${resolvedMember.status}` });
+
+        return Response.json({ accepted: true, denied: true, reason: 'not_a_member' });
+      }
+    }
+
+    if (resolvedMember) {
+      if (resolvedMember.status !== 'active') {
+        // Same bypass logic as the no-member branch: verification codes and
+        // bootstrap commands must pass through even when the member record is
+        // revoked/blocked — otherwise the user can never re-verify.
+        let denyInactiveMember = true;
+        if (isGuardianVerifyCode) {
+          const hasPendingChallenge = !!getPendingChallenge(canonicalAssistantId, sourceChannel);
+          const hasActiveOutboundSession = !!findActiveSession(canonicalAssistantId, sourceChannel);
+          if (hasPendingChallenge || hasActiveOutboundSession) {
+            denyInactiveMember = false;
+          } else {
+            log.info({ sourceChannel, memberId: resolvedMember.id, hasPendingChallenge, hasActiveOutboundSession }, 'Ingress ACL: inactive member verification bypass denied');
+          }
+        }
+        if (isBootstrapCommand) {
+          const bootstrapPayload = (rawCommandIntentForAcl as Record<string, unknown>).payload as string;
+          const bootstrapTokenForAcl = bootstrapPayload.slice(3);
+          const bootstrapSessionForAcl = resolveBootstrapToken(canonicalAssistantId, sourceChannel, bootstrapTokenForAcl);
+          if (bootstrapSessionForAcl && bootstrapSessionForAcl.status === 'pending_bootstrap') {
+            denyInactiveMember = false;
+          } else {
+            log.info({ sourceChannel, memberId: resolvedMember.id, hasValidBootstrapSession: false }, 'Ingress ACL: inactive member bootstrap bypass denied');
+          }
+        }
+
+        // ── Invite token intercept (inactive member) ──
+        // Same as the non-member branch: invite tokens can reactivate
+        // revoked/pending members without requiring guardian approval.
+        if (inviteToken && denyInactiveMember) {
+          const inviteResult = await handleInviteTokenIntercept({
+            rawToken: inviteToken,
+            sourceChannel,
+            externalChatId,
+            externalMessageId,
+            senderExternalUserId: body.senderExternalUserId,
+            senderName: body.senderName,
+            senderUsername: body.senderUsername,
+            replyCallbackUrl: body.replyCallbackUrl,
+            bearerToken,
+            assistantId,
+            canonicalAssistantId,
+          });
+          if (inviteResult) return inviteResult;
+        }
+
+        if (denyInactiveMember) {
+          log.info({ sourceChannel, memberId: resolvedMember.id, status: resolvedMember.status }, 'Ingress ACL: member not active, denying');
+
+          // 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 (resolvedMember.status !== 'blocked') {
+            try {
+              guardianNotified = notifyGuardianOfAccessRequest({
+                canonicalAssistantId,
+                sourceChannel,
+                externalChatId,
+                senderExternalUserId: body.senderExternalUserId,
+                senderName: body.senderName,
+                senderUsername: body.senderUsername,
+              });
+            } catch (err) {
+              log.error({ err, sourceChannel, externalChatId }, 'Failed to notify guardian of access request');
+            }
+          }
+
+          if (body.replyCallbackUrl) {
+            const replyText = guardianNotified
+              ? "Hmm looks like you don't have access to talk to me. I'll let them know you tried talking to me and get back to you."
+              : "Sorry, you haven't been approved to message this assistant.";
+            try {
+              await deliverChannelReply(body.replyCallbackUrl, {
+                chatId: externalChatId,
+                text: replyText,
+                assistantId,
+              }, bearerToken);
+            } catch (err) {
+              log.error({ err, externalChatId }, 'Failed to deliver ACL rejection reply');
+            }
+          }
+          return Response.json({ accepted: true, denied: true, reason: `member_${resolvedMember.status}` });
+        }
       }
 
       if (resolvedMember.policy === 'deny') {
@@ -309,7 +430,7 @@ export async function handleChannelInbound(
           try {
             await deliverChannelReply(body.replyCallbackUrl, {
               chatId: externalChatId,
-              text: "Sorry, you haven't been approved to message this assistant. You can ask its Guardian for an invite.",
+              text: "Sorry, you haven't been approved to message this assistant.",
               assistantId,
             }, bearerToken);
           } catch (err) {
@@ -752,12 +873,13 @@ export async function handleChannelInbound(
     });
   }
 
-  // ── Guardian action answer interception ──
-  // Check if this inbound message is a reply to a cross-channel guardian
-  // action request (from a voice call). Must run before approval interception
-  // so guardian answers are not mistakenly routed into the approval flow.
-  // Callback payloads (inline button presses) are excluded — they should
-  // not be misclassified as guardian answers.
+  // ── 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 &&
@@ -765,430 +887,346 @@ export async function handleChannelInbound(
     body.senderExternalUserId &&
     replyCallbackUrl
   ) {
-    const pendingDeliveries = getPendingDeliveriesByDestination(canonicalAssistantId, sourceChannel, externalChatId);
-    if (pendingDeliveries.length > 0) {
-      // Identity check: only the designated guardian can answer
-      const validDeliveries = pendingDeliveries.filter(
-        (d) => d.destinationExternalUserId === body.senderExternalUserId,
-      );
-
-      if (validDeliveries.length > 0) {
-        let matchedDelivery = validDeliveries.length === 1 ? validDeliveries[0] : null;
-        let answerText = trimmedContent;
-
-        // Multiple pending deliveries: require request code prefix for disambiguation
-        if (validDeliveries.length > 1) {
-          for (const d of validDeliveries) {
-            const req = getGuardianActionRequest(d.requestId);
-            if (req && trimmedContent.toUpperCase().startsWith(req.requestCode)) {
-              matchedDelivery = d;
-              answerText = trimmedContent.slice(req.requestCode.length).trim();
-              break;
-            }
+    // 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;
+      }
 
-          if (!matchedDelivery) {
-            // Send disambiguation message listing the request codes
-            const codes = validDeliveries
-              .map((d) => {
-                const req = getGuardianActionRequest(d.requestId);
-                return req ? req.requestCode : null;
-              })
-              .filter(Boolean);
+      // ── 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: `You have multiple pending guardian questions. Please prefix your reply with the reference code (${codes.join(', ')}) to indicate which question you are answering.`,
-                assistantId,
-              }, bearerToken);
+              await deliverChannelReply(replyCallbackUrl, { chatId: externalChatId, text: staleText, assistantId }, bearerToken);
             } catch (err) {
-              log.error({ err, externalChatId }, 'Failed to deliver guardian action disambiguation message');
+              log.error({ err, externalChatId }, 'Failed to deliver superseded terminal notice');
             }
-            return Response.json({
-              accepted: true,
-              duplicate: false,
-              eventId: result.eventId,
-              guardianAnswer: 'disambiguation_sent',
-            });
+            return Response.json({ accepted: true, duplicate: false, eventId: result.eventId, guardianAnswer: 'stale_superseded' });
           }
         }
 
-        if (matchedDelivery) {
-          const request = getGuardianActionRequest(matchedDelivery.requestId);
-          if (request) {
-            // Attempt to deliver the answer to the call first. Only resolve
-            // the guardian action request if answerCall succeeds, so that a
-            // failed delivery (e.g. pending question timed out) leaves the
-            // request pending for retry from another channel.
-            const answerResult = await answerCall({ callSessionId: request.callSessionId, answer: answerText });
-
-            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 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).
+      }
 
-            if (resolved) {
-              return Response.json({
-                accepted: true,
-                duplicate: false,
-                eventId: result.eventId,
-                guardianAnswer: 'resolved',
-              });
-            } else {
-              // resolveGuardianActionRequest returned null — request was no
-              // longer pending. answerCall already succeeded above, so the
-              // answer WAS delivered to the call. Don't initiate a follow-up
-              // negotiation; instead tell the guardian the answer was relayed.
-              const freshRequest = getGuardianActionRequest(request.id);
-
-              // answerCall succeeded, so the answer was delivered regardless
-              // of the resolve race. Inform the guardian accordingly.
-              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',
-              });
-            }
+      // ── 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 };
         }
       }
-    }
-  }
 
-  // ── Expired guardian action late answer interception ──
-  // When no pending delivery was found above, check for expired requests
-  // eligible for follow-up (status='expired', followup_state='none').
-  // Exclude callback payloads — inline button presses should not be
-  // misclassified as late guardian answers.
-  if (
-    !result.duplicate &&
-    !hasCallbackData &&
-    trimmedContent.length > 0 &&
-    body.senderExternalUserId &&
-    replyCallbackUrl
-  ) {
-    const expiredDeliveries = getExpiredDeliveriesByDestination(canonicalAssistantId, sourceChannel, externalChatId);
-    if (expiredDeliveries.length > 0) {
-      const validExpired = expiredDeliveries.filter(
-        (d) => d.destinationExternalUserId === body.senderExternalUserId,
-      );
-
-      if (validExpired.length > 0) {
-        let matchedExpired = validExpired.length === 1 ? validExpired[0] : null;
-        let expiredAnswerText = trimmedContent;
-
-        // Multiple expired deliveries: require request code prefix for disambiguation
-        if (validExpired.length > 1) {
-          for (const d of validExpired) {
-            const req = getGuardianActionRequest(d.requestId);
-            if (req && trimmedContent.toUpperCase().startsWith(req.requestCode)) {
-              matchedExpired = d;
-              expiredAnswerText = trimmedContent.slice(req.requestCode.length).trim();
-              break;
-            }
-          }
-
-          if (!matchedExpired) {
-            // Send disambiguation message listing the request codes
-            const codes = validExpired
-              .map((d) => {
-                const req = getGuardianActionRequest(d.requestId);
-                return req ? req.requestCode : null;
-              })
-              .filter((code): code is string => typeof code === 'string' && code.length > 0);
-            const disambiguationText = await composeGuardianActionMessageGenerative(
-              {
-                scenario: 'guardian_expired_disambiguation',
-                requestCodes: codes,
-                channel: sourceChannel,
-              },
-              { requiredKeywords: codes },
+      // ── 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: disambiguationText,
-                assistantId,
-              }, bearerToken);
+              await deliverChannelReply(replyCallbackUrl, { chatId: externalChatId, text: unknownText, assistantId }, bearerToken);
             } catch (err) {
-              log.error({ err, externalChatId }, 'Failed to deliver guardian action expired disambiguation message');
+              log.error({ err, externalChatId }, 'Failed to deliver unknown code notice');
             }
-            return Response.json({
-              accepted: true,
-              duplicate: false,
-              eventId: result.eventId,
-              guardianAnswer: 'disambiguation_sent',
-            });
+            return Response.json({ accepted: true, duplicate: false, eventId: result.eventId, guardianAnswer: 'unknown_code' });
           }
         }
+      }
 
-        if (matchedExpired) {
-          const expiredRequest = getGuardianActionRequest(matchedExpired.requestId);
-
-          if (expiredRequest && expiredRequest.status === 'expired' && expiredRequest.followupState === 'none') {
-            const followupResult = startFollowupFromExpiredRequest(expiredRequest.id, expiredAnswerText);
-            if (followupResult) {
-              const followupText = await composeGuardianActionMessageGenerative(
-                {
-                  scenario: 'guardian_late_answer_followup',
-                  questionText: expiredRequest.questionText,
-                  lateAnswerText: expiredAnswerText,
-                },
-                {},
-                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 {
-              // startFollowupFromExpiredRequest returned null (race condition:
-              // another reply already transitioned the request). Send a stale
-              // notice instead of falling through to the normal agent pipeline.
-              const staleText = await composeGuardianActionMessageGenerative(
-                { scenario: 'guardian_stale_expired' as const },
+      // ── 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,
+        );
+        try {
+          await deliverChannelReply(replyCallbackUrl, { chatId: externalChatId, text: disambiguationText, assistantId }, bearerToken);
+        } catch (err) {
+          log.error({ err, externalChatId }, 'Failed to deliver guardian action disambiguation message');
+        }
+        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,
               );
-              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',
-              });
+              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' });
           }
-        }
-      }
-    }
-  }
 
-  // ── Guardian follow-up conversation interception ──
-  // When a request is in `awaiting_guardian_choice` state, the guardian has
-  // already been asked "call back or send a message?". Their next message
-  // is the reply to that prompt — route it through the conversation engine
-  // to classify their intent.
-  if (
-    !result.duplicate &&
-    !hasCallbackData &&
-    trimmedContent.length > 0 &&
-    body.senderExternalUserId &&
-    replyCallbackUrl
-  ) {
-    const followupDeliveries = getFollowupDeliveriesByDestination(canonicalAssistantId, sourceChannel, externalChatId);
-    if (followupDeliveries.length > 0) {
-      const validFollowup = followupDeliveries.filter(
-        (d) => d.destinationExternalUserId === body.senderExternalUserId,
-      );
+          const resolved = resolveGuardianActionRequest(request.id, answerText, sourceChannel, body.senderExternalUserId);
 
-      if (validFollowup.length > 0) {
-        let matchedFollowup = validFollowup.length === 1 ? validFollowup[0] : null;
-        let followupReplyText = trimmedContent;
-
-        // Multiple follow-up deliveries: require request code prefix for disambiguation
-        if (validFollowup.length > 1) {
-          for (const d of validFollowup) {
-            const req = getGuardianActionRequest(d.requestId);
-            if (req && trimmedContent.toUpperCase().startsWith(req.requestCode)) {
-              matchedFollowup = d;
-              followupReplyText = trimmedContent.slice(req.requestCode.length).trim();
-              break;
-            }
-          }
+          if (resolved) {
+            await tryMintGuardianActionGrant({
+              request,
+              answerText,
+              decisionChannel: sourceChannel,
+              guardianExternalUserId: body.senderExternalUserId,
+              approvalConversationGenerator,
+            });
 
-          if (!matchedFollowup) {
-            // Send disambiguation message listing the request codes
-            const codes = validFollowup
-              .map((d) => {
-                const req = getGuardianActionRequest(d.requestId);
-                return req ? req.requestCode : null;
-              })
-              .filter((code): code is string => typeof code === 'string' && code.length > 0);
-            const disambiguationText = await composeGuardianActionMessageGenerative(
-              {
-                scenario: 'guardian_followup_disambiguation',
-                requestCodes: codes,
-                channel: sourceChannel,
-              },
-              { requiredKeywords: codes },
+            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: disambiguationText,
-                assistantId,
-              }, bearerToken);
+              await deliverChannelReply(replyCallbackUrl, { chatId: externalChatId, text: relayedText, assistantId }, bearerToken);
             } catch (err) {
-              log.error({ err, externalChatId }, 'Failed to deliver guardian follow-up disambiguation message');
+              log.error({ err, externalChatId }, 'Failed to deliver guardian action stale notice');
             }
-            return Response.json({
-              accepted: true,
-              duplicate: false,
-              eventId: result.eventId,
-              guardianFollowUp: 'disambiguation_sent',
-            });
+            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' });
           }
         }
 
-        if (matchedFollowup) {
-          const followupRequest = getGuardianActionRequest(matchedFollowup.requestId);
-
-          if (followupRequest && followupRequest.followupState === 'awaiting_guardian_choice') {
-            const turnResult = await processGuardianFollowUpTurn(
-              {
-                questionText: followupRequest.questionText,
-                lateAnswerText: followupRequest.lateAnswerText ?? '',
-                guardianReply: followupReplyText,
-              },
-              guardianFollowUpConversationGenerator,
-            );
+        // ── 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) !== undefined;
+          } else if (turnResult.disposition === 'decline') {
+            stateApplied = finalizeFollowup(request.id, 'declined') !== undefined;
+          }
 
-            // Apply the disposition to the follow-up state machine.
-            // Both progressFollowupState and finalizeFollowup are compare-and-set:
-            // they return null when the transition was not applied (e.g. a concurrent
-            // reply already advanced the state). In that case we notify the guardian
-            // that the request was already resolved and skip action execution.
-            let stateApplied = true;
-            if (turnResult.disposition === 'call_back' || turnResult.disposition === 'message_back') {
-              stateApplied = progressFollowupState(followupRequest.id, 'dispatching', turnResult.disposition) !== undefined;
-            } else if (turnResult.disposition === 'decline') {
-              stateApplied = finalizeFollowup(followupRequest.id, 'declined') !== undefined;
+          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');
             }
-            // keep_pending: no state change — guardian can reply again
+            return Response.json({ accepted: true, duplicate: false, eventId: result.eventId, guardianFollowUp: 'stale_ignored' });
+          }
 
-            if (!stateApplied) {
-              log.warn({ requestId: followupRequest.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: 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 {
-                await deliverChannelReply(replyCallbackUrl, {
-                  chatId: externalChatId,
-                  text: staleText,
-                  assistantId,
-                }, bearerToken);
-              } catch (err) {
-                log.error({ err, externalChatId }, 'Failed to deliver stale follow-up notice');
+                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: 'stale_ignored',
-              });
-            }
+            })();
+          }
 
-            // Deliver the generated reply to the guardian
-            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');
-            }
+          return Response.json({ accepted: true, duplicate: false, eventId: result.eventId, guardianFollowUp: turnResult.disposition });
+        }
 
-            // Execute the action and send a completion/failure reply (fire-and-forget).
-            // The initial reply above acknowledges the guardian's choice; the executor
-            // carries out the actual call_back or message_back and posts a second message.
-            if (turnResult.disposition === 'call_back' || turnResult.disposition === 'message_back') {
-              void (async () => {
-                try {
-                  const execResult = await executeFollowupAction(
-                    followupRequest.id,
-                    turnResult.disposition as 'call_back' | 'message_back',
+        // ── 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,
                   );
-                  await deliverChannelReply(replyCallbackUrl, {
-                    chatId: externalChatId,
-                    text: execResult.guardianReplyText,
-                    assistantId,
-                  }, bearerToken);
-                } catch (execErr) {
-                  log.error({ err: execErr, requestId: followupRequest.id }, 'Follow-up action execution or completion reply failed');
+                  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,
-              guardianFollowUp: turnResult.disposition,
-            });
+          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' });
           }
         }
       }
@@ -1391,6 +1429,124 @@ export async function handleChannelInbound(
   });
 }
 
+// ---------------------------------------------------------------------------
+// Invite token intercept
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle an inbound invite token for a non-member or inactive member.
+ *
+ * Redeems the invite, delivers a deterministic reply, and returns a Response
+ * to short-circuit the handler. Returns `null` when the intercept should not
+ * fire (e.g. already_member outcome — let normal flow handle it).
+ */
+async function handleInviteTokenIntercept(params: {
+  rawToken: string;
+  sourceChannel: ChannelId;
+  externalChatId: string;
+  externalMessageId: string;
+  senderExternalUserId?: string;
+  senderName?: string;
+  senderUsername?: string;
+  replyCallbackUrl?: string;
+  bearerToken?: string;
+  assistantId?: string;
+  canonicalAssistantId: string;
+}): Promise<Response | null> {
+  const {
+    rawToken,
+    sourceChannel,
+    externalChatId,
+    externalMessageId,
+    senderExternalUserId,
+    senderName,
+    senderUsername,
+    replyCallbackUrl,
+    bearerToken,
+    assistantId,
+    canonicalAssistantId,
+  } = params;
+
+  // Record the inbound event for dedup tracking BEFORE performing redemption.
+  // Without this, duplicate webhook deliveries (common with Telegram) would
+  // not be tracked: the first delivery redeems the invite and returns early,
+  // then the retry finds an active member, passes ACL, and the raw
+  // /start iv_<token> message leaks into the agent pipeline.
+  const dedupResult = channelDeliveryStore.recordInbound(
+    sourceChannel,
+    externalChatId,
+    externalMessageId,
+    { assistantId: canonicalAssistantId },
+  );
+
+  if (dedupResult.duplicate) {
+    return Response.json({
+      accepted: true,
+      duplicate: true,
+      eventId: dedupResult.eventId,
+    });
+  }
+
+  const outcome = redeemInvite({
+    rawToken,
+    sourceChannel,
+    externalUserId: senderExternalUserId,
+    externalChatId,
+    displayName: senderName,
+    username: senderUsername,
+    assistantId: canonicalAssistantId,
+  });
+
+  log.info(
+    { sourceChannel, externalChatId, ok: outcome.ok, type: outcome.ok ? outcome.type : undefined, reason: !outcome.ok ? outcome.reason : undefined },
+    'Invite token intercept: redemption result',
+  );
+
+  // already_member means the user has an active record — let the normal
+  // flow handle them (they passed ACL or the member is active).
+  if (outcome.ok && outcome.type === 'already_member') {
+    // Deliver a quick acknowledgement and short-circuit so the user
+    // does not trigger the deny gate or a duplicate agent loop.
+    const replyText = getInviteRedemptionReply(outcome);
+    if (replyCallbackUrl) {
+      try {
+        await deliverChannelReply(replyCallbackUrl, {
+          chatId: externalChatId,
+          text: replyText,
+          assistantId,
+        }, bearerToken);
+      } catch (err) {
+        log.error({ err, externalChatId }, 'Failed to deliver invite already-member reply');
+      }
+    }
+    channelDeliveryStore.markProcessed(dedupResult.eventId);
+    return Response.json({ accepted: true, eventId: dedupResult.eventId, inviteRedemption: 'already_member' });
+  }
+
+  const replyText = getInviteRedemptionReply(outcome);
+
+  if (replyCallbackUrl) {
+    try {
+      await deliverChannelReply(replyCallbackUrl, {
+        chatId: externalChatId,
+        text: replyText,
+        assistantId,
+      }, bearerToken);
+    } catch (err) {
+      log.error({ err, externalChatId }, 'Failed to deliver invite redemption reply');
+    }
+  }
+
+  if (outcome.ok && outcome.type === 'redeemed') {
+    channelDeliveryStore.markProcessed(dedupResult.eventId);
+    return Response.json({ accepted: true, eventId: dedupResult.eventId, inviteRedemption: 'redeemed', memberId: outcome.memberId });
+  }
+
+  // Failed redemption — inform the user and deny
+  channelDeliveryStore.markProcessed(dedupResult.eventId);
+  return Response.json({ accepted: true, eventId: dedupResult.eventId, denied: true, inviteRedemption: outcome.reason });
+}
+
 // ---------------------------------------------------------------------------
 // Non-member access request notification
 // ---------------------------------------------------------------------------
@@ -1408,7 +1564,7 @@ function notifyGuardianOfAccessRequest(params: {
   senderExternalUserId?: string;
   senderName?: string;
   senderUsername?: string;
-}): void {
+}): boolean {
   const {
     canonicalAssistantId,
     sourceChannel,
@@ -1418,16 +1574,17 @@ function notifyGuardianOfAccessRequest(params: {
     senderUsername,
   } = params;
 
-  if (!senderExternalUserId) return;
+  if (!senderExternalUserId) return false;
 
   const binding = getGuardianBinding(canonicalAssistantId, sourceChannel);
   if (!binding) {
     log.debug({ sourceChannel, canonicalAssistantId }, 'No guardian binding for access request notification');
-    return;
+    return false;
   }
 
   // Deduplicate: skip if there is already a pending approval request for
-  // the same requester on this channel.
+  // the same requester on this channel.  Still return true — the guardian
+  // was already notified for this request.
   const existing = findPendingAccessRequestForRequester(
     canonicalAssistantId,
     sourceChannel,
@@ -1439,7 +1596,7 @@ function notifyGuardianOfAccessRequest(params: {
       { sourceChannel, senderExternalUserId, existingId: existing.id },
       'Skipping duplicate access request notification',
     );
-    return;
+    return true;
   }
 
   const senderIdentifier = senderName || senderUsername || senderExternalUserId;
@@ -1491,6 +1648,8 @@ function notifyGuardianOfAccessRequest(params: {
     { sourceChannel, senderExternalUserId, senderIdentifier },
     'Guardian notified of non-member access request',
   );
+
+  return true;
 }
 
 // ---------------------------------------------------------------------------