@vellumai/assistant 0.3.14 → 0.3.16

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

@@ -12,14 +12,20 @@ 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';
 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,
+  getExpiredDeliveriesByDestination,
+  getFollowupDeliveriesByDestination,
   getGuardianActionRequest,
   getPendingDeliveriesByDestination,
+  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';
@@ -53,8 +59,14 @@ import {
 import type {
   ApprovalConversationGenerator,
   ApprovalCopyGenerator,
+  GuardianActionCopyGenerator,
+  GuardianFollowUpConversationGenerator,
   MessageProcessor,
 } from '../http-types.js';
+import { processGuardianFollowUpTurn } from '../guardian-action-conversation-turn.js';
+import { composeGuardianActionMessageGenerative } from '../guardian-action-message-composer.js';
+import { executeFollowupAction } from '../guardian-action-followup-executor.js';
+import { httpError } from '../http-errors.js';
 import { deliverReplyViaCallback } from './channel-delivery-routes.js';
 import {
   canonicalChannelAssistantId,
@@ -71,26 +83,13 @@ const log = getLogger('runtime-http');
 
 /**
  * Parse a guardian verification code from message content.
- * Accepts three formats:
- *   1. `/guardian_verify <code>` (legacy command format)
- *   2. `/guardian_verify@BotName <code>` (Telegram group format)
- *   3. A bare code as the entire message: 6-digit numeric OR 64-char hex
- *      (hex is retained for backward compatibility with in-flight inbound
- *      challenges that still use high-entropy secrets)
- * Returns `{ code, isExplicitCommand }` if recognized, or undefined otherwise.
- * `isExplicitCommand` is true for legacy /guardian_verify commands (explicit
- * intent) and false for bare codes (which need additional gating to avoid
- * intercepting normal 6-digit messages like zip codes or PINs).
+ * Accepts a bare code as the entire message: 6-digit numeric OR 64-char hex
+ * (hex is retained for compatibility with unbound inbound/bootstrap sessions
+ * that intentionally use high-entropy secrets).
  */
-function parseGuardianVerifyCommand(content: string): { code: string; isExplicitCommand: boolean } | undefined {
-  // Legacy /guardian_verify command format
-  const commandMatch = content.match(/^\/guardian_verify(?:@\S+)?\s+(\S+)/);
-  if (commandMatch) return { code: commandMatch[1], isExplicitCommand: true };
-
-  // Bare code: 6-digit numeric (identity-bound outbound sessions) or
-  // 64-char hex (unbound inbound challenges)
+function parseGuardianVerifyCode(content: string): string | undefined {
   const bareMatch = content.match(/^([0-9a-fA-F]{64}|\d{6})$/);
-  if (bareMatch) return { code: bareMatch[1], isExplicitCommand: false };
+  if (bareMatch) return bareMatch[1];
 
   return undefined;
 }
@@ -103,6 +102,8 @@ export async function handleChannelInbound(
   gatewayOriginSecret?: string,
   approvalCopyGenerator?: ApprovalCopyGenerator,
   approvalConversationGenerator?: ApprovalConversationGenerator,
+  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
@@ -142,40 +143,34 @@ export async function handleChannelInbound(
   } = body;
 
   if (!body.sourceChannel || typeof body.sourceChannel !== 'string') {
-    return Response.json({ error: 'sourceChannel is required' }, { status: 400 });
+    return httpError('BAD_REQUEST', 'sourceChannel is required', 400);
   }
   // Validate and narrow to canonical ChannelId at the boundary — the gateway
   // only sends well-known channel strings, so an unknown value is rejected.
   if (!isChannelId(body.sourceChannel)) {
-    return Response.json(
-      { error: `Invalid sourceChannel: ${body.sourceChannel}. Valid values: ${CHANNEL_IDS.join(', ')}` },
-      { status: 400 },
-    );
+    return httpError('BAD_REQUEST', `Invalid sourceChannel: ${body.sourceChannel}. Valid values: ${CHANNEL_IDS.join(', ')}`, 400);
   }
 
   const sourceChannel = body.sourceChannel;
 
   if (!body.interface || typeof body.interface !== 'string') {
-    return Response.json({ error: 'interface is required' }, { status: 400 });
+    return httpError('BAD_REQUEST', 'interface is required', 400);
   }
   const sourceInterface = parseInterfaceId(body.interface);
   if (!sourceInterface) {
-    return Response.json(
-      { error: `Invalid interface: ${body.interface}. Valid values: ${INTERFACE_IDS.join(', ')}` },
-      { status: 400 },
-    );
+    return httpError('BAD_REQUEST', `Invalid interface: ${body.interface}. Valid values: ${INTERFACE_IDS.join(', ')}`, 400);
   }
 
   if (!externalChatId || typeof externalChatId !== 'string') {
-    return Response.json({ error: 'externalChatId is required' }, { status: 400 });
+    return httpError('BAD_REQUEST', 'externalChatId is required', 400);
   }
   if (!externalMessageId || typeof externalMessageId !== 'string') {
-    return Response.json({ error: 'externalMessageId is required' }, { status: 400 });
+    return httpError('BAD_REQUEST', 'externalMessageId is required', 400);
   }
 
   // Reject non-string content regardless of whether attachments are present.
   if (content != null && typeof content !== 'string') {
-    return Response.json({ error: 'content must be a string' }, { status: 400 });
+    return httpError('BAD_REQUEST', 'content must be a string', 400);
   }
 
   const trimmedContent = typeof content === 'string' ? content.trim() : '';
@@ -184,7 +179,7 @@ export async function handleChannelInbound(
   const hasCallbackData = typeof body.callbackData === 'string' && body.callbackData.length > 0;
 
   if (trimmedContent.length === 0 && !hasAttachments && !isEdit && !hasCallbackData) {
-    return Response.json({ error: 'content or attachmentIds is required' }, { status: 400 });
+    return httpError('BAD_REQUEST', 'content or attachmentIds is required', 400);
   }
 
   // Canonicalize the assistant ID so all DB-facing operations use the
@@ -199,10 +194,10 @@ export async function handleChannelInbound(
   // recordInbound (where we have a conversationId).
   let resolvedMember: ReturnType<typeof findMember> = null;
 
-  // /guardian_verify must bypass the ACL membership check — users without a
+  // Verification codes must bypass the ACL membership check — users without a
   // member record need to verify before they can be recognized as members.
-  const guardianVerifyParsed = parseGuardianVerifyCommand(trimmedContent);
-  const isGuardianVerifyCommand = guardianVerifyParsed !== undefined;
+  const guardianVerifyCode = parseGuardianVerifyCode(trimmedContent);
+  const isGuardianVerifyCode = guardianVerifyCode !== undefined;
 
   // /start gv_<token> bootstrap commands must also bypass ACL — the user
   // hasn't been verified yet and needs to complete the bootstrap handshake.
@@ -223,11 +218,11 @@ export async function handleChannelInbound(
     });
 
     if (!resolvedMember) {
-      // Determine whether a /guardian_verify bypass is warranted: only allow
+      // Determine whether a verification-code bypass is warranted: only allow
       // when there is a pending (unconsumed, unexpired) challenge AND no
       // active guardian binding for this (assistantId, channel).
       let denyNonMember = true;
-      if (isGuardianVerifyCommand) {
+      if (isGuardianVerifyCode) {
         // Allow bypass when there is any consumable challenge or active
         // outbound session.  The !hasActiveBinding guard is intentionally
         // omitted: rebind sessions create a consumable challenge while a
@@ -238,7 +233,7 @@ export async function handleChannelInbound(
         if (hasPendingChallenge || hasActiveOutboundSession) {
           denyNonMember = false;
         } else {
-          log.info({ sourceChannel, hasPendingChallenge, hasActiveOutboundSession }, 'Ingress ACL: guardian_verify bypass denied');
+          log.info({ sourceChannel, hasPendingChallenge, hasActiveOutboundSession }, 'Ingress ACL: guardian verification bypass denied');
         }
       }
 
@@ -270,6 +265,23 @@ export async function handleChannelInbound(
             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.
+        try {
+          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');
+        }
+
         return Response.json({ accepted: true, denied: true, reason: 'not_a_member' });
       }
     }
@@ -329,7 +341,7 @@ export async function handleChannelInbound(
     : undefined;
 
   if (isEdit && !sourceMessageId) {
-    return Response.json({ error: 'sourceMetadata.messageId is required for edits' }, { status: 400 });
+    return httpError('BAD_REQUEST', 'sourceMetadata.messageId is required for edits', 400);
   }
 
   // ── Edit path: update existing message content, no new agent loop ──
@@ -536,7 +548,7 @@ export async function handleChannelInbound(
     : undefined;
 
   // ── Telegram bootstrap deep-link handling ──
-  // Intercept /start gv_<token> commands BEFORE the guardian_verify intercept.
+  // Intercept /start gv_<token> commands BEFORE the verification-code intercept.
   // When a user clicks the deep link, Telegram sends /start gv_<token> which
   // the gateway forwards with commandIntent: { type: 'start', payload: 'gv_<token>' }.
   // We resolve the bootstrap token, bind the session identity, create a new
@@ -569,7 +581,7 @@ export async function handleChannelInbound(
         destinationAddress: externalChatId,
       });
 
-      // Compose and send the verification code via Telegram
+      // Compose and send the verification prompt via Telegram
       const telegramBody = composeVerificationTelegram(
         GUARDIAN_VERIFY_TEMPLATE_KEYS.TELEGRAM_CHALLENGE_REQUEST,
         {
@@ -595,34 +607,32 @@ export async function handleChannelInbound(
     // If not found or expired, fall through to normal /start handling
   }
 
-  // ── Guardian verification command intercept (deterministic) ──
+  // ── Guardian verification code intercept (deterministic) ──
   // Validate/consume the challenge synchronously so side effects (member
   // upsert, binding creation) complete before any reply. The reply is
-  // delivered via template-driven deterministic messages and the command
+  // delivered via template-driven deterministic messages and the code
   // is short-circuited — it NEVER enters the agent pipeline. This
-  // prevents verification commands from producing agent-generated copy.
+  // prevents verification code messages from producing agent-generated copy.
   //
   // Bare 6-digit codes are only intercepted when there is actually a
   // pending challenge or active outbound session for this channel.
   // Without this guard, normal 6-digit messages (zip codes, PINs, etc.)
   // would be swallowed by the verification handler and never reach the
-  // agent pipeline.  Legacy /guardian_verify commands are always
-  // intercepted because the explicit command prefix signals clear intent.
-  const shouldInterceptVerification = guardianVerifyParsed !== undefined &&
-    (guardianVerifyParsed.isExplicitCommand ||
-     !!getPendingChallenge(canonicalAssistantId, sourceChannel) ||
+  // agent pipeline.
+  const shouldInterceptVerification = guardianVerifyCode !== undefined &&
+    (!!getPendingChallenge(canonicalAssistantId, sourceChannel) ||
      !!findActiveSession(canonicalAssistantId, sourceChannel));
 
   if (
     !result.duplicate &&
     shouldInterceptVerification &&
-    guardianVerifyParsed !== undefined &&
+    guardianVerifyCode !== undefined &&
     body.senderExternalUserId
   ) {
     const verifyResult = validateAndConsumeChallenge(
       canonicalAssistantId,
       sourceChannel,
-      guardianVerifyParsed.code,
+      guardianVerifyCode,
       body.senderExternalUserId,
       externalChatId,
       body.senderUsername,
@@ -642,17 +652,52 @@ export async function handleChannelInbound(
         displayName: body.senderName,
         username: body.senderUsername,
       });
-      log.info({ sourceChannel, externalUserId: body.senderExternalUserId }, 'Guardian verified: auto-upserted ingress member');
+
+      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`);
+
+      // Emit activated signal when a trusted contact completes verification.
+      // Member record is persisted above before this event fires, satisfying
+      // the persistence-before-event ordering invariant.
+      if (verifyResult.verificationType === 'trusted_contact') {
+        void emitNotificationSignal({
+          sourceEventName: 'ingress.trusted_contact.activated',
+          sourceChannel,
+          sourceSessionId: result.conversationId,
+          assistantId: canonicalAssistantId,
+          attentionHints: {
+            requiresAction: false,
+            urgency: 'low',
+            isAsyncBackground: false,
+            visibleInSourceNow: false,
+          },
+          contextPayload: {
+            sourceChannel,
+            externalUserId: body.senderExternalUserId,
+            externalChatId,
+            senderName: body.senderName ?? null,
+            senderUsername: body.senderUsername ?? null,
+          },
+          dedupeKey: `trusted-contact:activated:${canonicalAssistantId}:${sourceChannel}:${body.senderExternalUserId}`,
+        });
+      }
     }
 
     // Deliver a deterministic template-driven reply and short-circuit.
-    // Verification commands must never produce agent-generated copy.
+    // Verification code messages must never produce agent-generated copy.
     if (replyCallbackUrl) {
-      const replyText = verifyResult.success
-        ? composeChannelVerifyReply(GUARDIAN_VERIFY_TEMPLATE_KEYS.CHANNEL_VERIFY_SUCCESS)
-        : composeChannelVerifyReply(GUARDIAN_VERIFY_TEMPLATE_KEYS.CHANNEL_VERIFY_FAILED, {
-            failureReason: stripVerificationFailurePrefix(verifyResult.reason),
-          });
+      let replyText: string;
+      if (!verifyResult.success) {
+        replyText = composeChannelVerifyReply(GUARDIAN_VERIFY_TEMPLATE_KEYS.CHANNEL_VERIFY_FAILED, {
+          failureReason: stripVerificationFailurePrefix(verifyResult.reason),
+        });
+      } else if (verifyResult.verificationType === 'trusted_contact') {
+        replyText = composeChannelVerifyReply(GUARDIAN_VERIFY_TEMPLATE_KEYS.CHANNEL_TRUSTED_CONTACT_VERIFY_SUCCESS);
+      } else {
+        replyText = composeChannelVerifyReply(GUARDIAN_VERIFY_TEMPLATE_KEYS.CHANNEL_VERIFY_SUCCESS);
+      }
       try {
         await deliverChannelReply(replyCallbackUrl, {
           chatId: externalChatId,
@@ -711,8 +756,11 @@ export async function handleChannelInbound(
   // 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.
   if (
     !result.duplicate &&
+    !hasCallbackData &&
     trimmedContent.length > 0 &&
     body.senderExternalUserId &&
     replyCallbackUrl
@@ -778,9 +826,14 @@ export async function handleChannelInbound(
               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: 'Failed to deliver your answer to the call. Please try again.',
+                  text: failureText,
                   assistantId,
                 }, bearerToken);
               } catch (deliverErr) {
@@ -809,16 +862,34 @@ export async function handleChannelInbound(
                 guardianAnswer: 'resolved',
               });
             } else {
-              // Already answered from another channel
+              // 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: 'This question has already been answered from another channel.',
+                  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,
@@ -832,6 +903,298 @@ export async function handleChannelInbound(
     }
   }
 
+  // ── 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 },
+              guardianActionCopyGenerator,
+            );
+            try {
+              await deliverChannelReply(replyCallbackUrl, {
+                chatId: externalChatId,
+                text: disambiguationText,
+                assistantId,
+              }, bearerToken);
+            } catch (err) {
+              log.error({ err, externalChatId }, 'Failed to deliver guardian action expired disambiguation message');
+            }
+            return Response.json({
+              accepted: true,
+              duplicate: false,
+              eventId: result.eventId,
+              guardianAnswer: 'disambiguation_sent',
+            });
+          }
+        }
+
+        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 },
+                {},
+                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',
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // ── 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,
+      );
+
+      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 (!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 },
+              guardianActionCopyGenerator,
+            );
+            try {
+              await deliverChannelReply(replyCallbackUrl, {
+                chatId: externalChatId,
+                text: disambiguationText,
+                assistantId,
+              }, bearerToken);
+            } catch (err) {
+              log.error({ err, externalChatId }, 'Failed to deliver guardian follow-up disambiguation message');
+            }
+            return Response.json({
+              accepted: true,
+              duplicate: false,
+              eventId: result.eventId,
+              guardianFollowUp: 'disambiguation_sent',
+            });
+          }
+        }
+
+        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,
+            );
+
+            // 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) !== null;
+            } else if (turnResult.disposition === 'decline') {
+              stateApplied = finalizeFollowup(followupRequest.id, 'declined') !== null;
+            }
+            // keep_pending: no state change — guardian can reply again
+
+            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: 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',
+              });
+            }
+
+            // 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');
+            }
+
+            // 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',
+                    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');
+                }
+              })();
+            }
+
+            return Response.json({
+              accepted: true,
+              duplicate: false,
+              eventId: result.eventId,
+              guardianFollowUp: turnResult.disposition,
+            });
+          }
+        }
+      }
+    }
+  }
+
   // ── Actor role resolution ──
   // Uses shared channel-agnostic resolution so all ingress paths classify
   // guardian vs non-guardian actors the same way.
@@ -1028,6 +1391,108 @@ export async function handleChannelInbound(
   });
 }
 
+// ---------------------------------------------------------------------------
+// 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;
+}): void {
+  const {
+    canonicalAssistantId,
+    sourceChannel,
+    externalChatId,
+    senderExternalUserId,
+    senderName,
+    senderUsername,
+  } = params;
+
+  if (!senderExternalUserId) return;
+
+  const binding = getGuardianBinding(canonicalAssistantId, sourceChannel);
+  if (!binding) {
+    log.debug({ sourceChannel, canonicalAssistantId }, 'No guardian binding for access request notification');
+    return;
+  }
+
+  // Deduplicate: skip if there is already a pending approval request for
+  // the same requester on this channel.
+  const existing = findPendingAccessRequestForRequester(
+    canonicalAssistantId,
+    sourceChannel,
+    senderExternalUserId,
+    'ingress_access_request',
+  );
+  if (existing) {
+    log.debug(
+      { sourceChannel, senderExternalUserId, existingId: existing.id },
+      'Skipping duplicate access request notification',
+    );
+    return;
+  }
+
+  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',
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Background message processing
 // ---------------------------------------------------------------------------
@@ -1225,7 +1690,7 @@ function processChannelMessageInBackground(params: BackgroundProcessingParams):
           },
           assistantId,
           guardianContext: toGuardianRuntimeContext(sourceChannel, guardianCtx),
-          isInteractive: true,
+          isInteractive: guardianCtx.actorRole === 'guardian',
           ...(cmdIntent ? { commandIntent: cmdIntent } : {}),
         },
         sourceChannel,