@vellumai/assistant 0.4.26 → 0.4.29

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

@@ -4,94 +4,46 @@
  * 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 type { ChannelId, InterfaceId } from '../../channels/types.js';
-import { CHANNEL_IDS, INTERFACE_IDS, isChannelId, parseInterfaceId } from '../../channels/types.js';
-import { getGatewayInternalBaseUrl } from '../../config/env.js';
-import { resolveUserReference } from '../../config/user-reference.js';
-import { RESEND_COOLDOWN_MS } from '../../daemon/handlers/config-channels.js';
-import * as attachmentsStore from '../../memory/attachments-store.js';
 import {
-  createCanonicalGuardianRequest,
-  listCanonicalGuardianRequests,
-  listPendingCanonicalGuardianRequestsByDestinationChat,
-} from '../../memory/canonical-guardian-store.js';
-import * as channelDeliveryStore from '../../memory/channel-delivery-store.js';
-import { recordConversationSeenSignal } from '../../memory/conversation-attention-store.js';
-import * as conversationStore from '../../memory/conversation-store.js';
-import * as externalConversationStore from '../../memory/external-conversation-store.js';
-import { findMember, updateLastSeen, upsertMember } from '../../memory/ingress-member-store.js';
-import { emitNotificationSignal } from '../../notifications/emit-signal.js';
-import { checkIngressForSecrets } from '../../security/secret-ingress.js';
-import { canonicalizeInboundIdentity } from '../../util/canonicalize-identity.js';
-import { IngressBlockedError } from '../../util/errors.js';
-import { getLogger } from '../../util/logger.js';
-import { notifyGuardianOfAccessRequest } from '../access-request-helper.js';
-import { DAEMON_INTERNAL_ASSISTANT_ID } from '../assistant-scope.js';
-import { mintDaemonDeliveryToken } from '../auth/token-service.js';
-import {
-  buildApprovalUIMetadata,
-  getApprovalInfoByConversation,
-  getChannelApprovalPrompt,
-} from '../channel-approvals.js';
-import {
-  bindSessionIdentity,
-  createOutboundSession,
-  findActiveSession,
-  getGuardianBinding,
-  getPendingChallenge,
-  resolveBootstrapToken,
-  updateSessionDelivery,
-  updateSessionStatus,
-  validateAndConsumeChallenge,
-} from '../channel-guardian-service.js';
-import { getTransport } from '../channel-invite-transport.js';
-import { deliverChannelReply } from '../gateway-client.js';
-import { resolveGuardianContext, resolveRoutingState } from '../guardian-context-resolver.js';
-import { routeGuardianReply } from '../guardian-reply-router.js';
-import {
-  composeChannelVerifyReply,
-  composeVerificationTelegram,
-  GUARDIAN_VERIFY_TEMPLATE_KEYS,
-} from '../guardian-verification-templates.js';
-import { httpError } from '../http-errors.js';
+  CHANNEL_IDS,
+  INTERFACE_IDS,
+  isChannelId,
+  parseInterfaceId,
+} from "../../channels/types.js";
+import type { TrustContext } from "../../daemon/session-runtime-assembly.js";
+import * as attachmentsStore from "../../memory/attachments-store.js";
+import * as channelDeliveryStore from "../../memory/channel-delivery-store.js";
+import { recordConversationSeenSignal } from "../../memory/conversation-attention-store.js";
+import * as externalConversationStore from "../../memory/external-conversation-store.js";
+import { canonicalizeInboundIdentity } from "../../util/canonicalize-identity.js";
+import { getLogger } from "../../util/logger.js";
+import { DAEMON_INTERNAL_ASSISTANT_ID } from "../assistant-scope.js";
+import { mintDaemonDeliveryToken } from "../auth/token-service.js";
+import { deliverChannelReply } from "../gateway-client.js";
+import { httpError } from "../http-errors.js";
 import type {
   ApprovalConversationGenerator,
   ApprovalCopyGenerator,
   GuardianActionCopyGenerator,
   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,
-  GUARDIAN_APPROVAL_TTL_MS,
-  type GuardianContext,
-  stripVerificationFailurePrefix,
-} from './channel-route-shared.js';
-import { handleApprovalInterception } from './guardian-approval-interception.js';
-import { deliverGeneratedApprovalPrompt } from './guardian-approval-prompt.js';
-
-import '../channel-invite-transports/telegram.js';
-import '../channel-invite-transports/voice.js';
-
-const log = getLogger('runtime-http');
-
-/**
- * Parse a guardian verification code from message content.
- * 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 parseGuardianVerifyCode(content: string): string | undefined {
-  const bareMatch = content.match(/^([0-9a-fA-F]{64}|\d{6})$/);
-  if (bareMatch) return bareMatch[1];
-
-  return undefined;
-}
+} from "../http-types.js";
+import { resolveTrustContext } from "../trust-context-resolver.js";
+import { canonicalChannelAssistantId } from "./channel-route-shared.js";
+import { handleApprovalInterception } from "./guardian-approval-interception.js";
+import { enforceIngressAcl } from "./inbound-stages/acl-enforcement.js";
+import { processChannelMessageInBackground } from "./inbound-stages/background-dispatch.js";
+import { handleBootstrapIntercept } from "./inbound-stages/bootstrap-intercept.js";
+import { handleEditIntercept } from "./inbound-stages/edit-intercept.js";
+import { handleEscalationIntercept } from "./inbound-stages/escalation-intercept.js";
+import { handleGuardianReplyIntercept } from "./inbound-stages/guardian-reply-intercept.js";
+import { runSecretIngressCheck } from "./inbound-stages/secret-ingress-check.js";
+import { handleVerificationIntercept } from "./inbound-stages/verification-intercept.js";
+
+import "../channel-invite-transports/telegram.js";
+import "../channel-invite-transports/voice.js";
+
+const log = getLogger("runtime-http");
 
 export async function handleChannelInbound(
   req: Request,
@@ -113,7 +65,7 @@ export async function handleChannelInbound(
   // a single token from request start.
   const mintBearerToken = (): string => mintDaemonDeliveryToken();
 
-  const body = await req.json() as {
+  const body = (await req.json()) as {
     sourceChannel?: string;
     interface?: string;
     conversationExternalId?: string;
@@ -139,63 +91,92 @@ export async function handleChannelInbound(
     sourceMetadata,
   } = body;
 
-  if (!body.sourceChannel || typeof body.sourceChannel !== 'string') {
-    return httpError('BAD_REQUEST', 'sourceChannel is required', 400);
+  if (!body.sourceChannel || typeof body.sourceChannel !== "string") {
+    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 httpError('BAD_REQUEST', `Invalid sourceChannel: ${body.sourceChannel}. Valid values: ${CHANNEL_IDS.join(', ')}`, 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 httpError('BAD_REQUEST', 'interface is required', 400);
+  if (!body.interface || typeof body.interface !== "string") {
+    return httpError("BAD_REQUEST", "interface is required", 400);
   }
   const sourceInterface = parseInterfaceId(body.interface);
   if (!sourceInterface) {
-    return httpError('BAD_REQUEST', `Invalid interface: ${body.interface}. Valid values: ${INTERFACE_IDS.join(', ')}`, 400);
+    return httpError(
+      "BAD_REQUEST",
+      `Invalid interface: ${body.interface}. Valid values: ${INTERFACE_IDS.join(
+        ", ",
+      )}`,
+      400,
+    );
   }
 
-  if (!conversationExternalId || typeof conversationExternalId !== 'string') {
-    return httpError('BAD_REQUEST', 'conversationExternalId is required', 400);
+  if (!conversationExternalId || typeof conversationExternalId !== "string") {
+    return httpError("BAD_REQUEST", "conversationExternalId is required", 400);
   }
-  if (!body.actorExternalId || typeof body.actorExternalId !== 'string' || !body.actorExternalId.trim()) {
-    return httpError('BAD_REQUEST', 'actorExternalId is required', 400);
+  if (
+    !body.actorExternalId ||
+    typeof body.actorExternalId !== "string" ||
+    !body.actorExternalId.trim()
+  ) {
+    return httpError("BAD_REQUEST", "actorExternalId is required", 400);
   }
-  if (!externalMessageId || typeof externalMessageId !== 'string') {
-    return httpError('BAD_REQUEST', 'externalMessageId is required', 400);
+  if (!externalMessageId || typeof externalMessageId !== "string") {
+    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 httpError('BAD_REQUEST', 'content must be a string', 400);
+  if (content != null && typeof content !== "string") {
+    return httpError("BAD_REQUEST", "content must be a string", 400);
   }
 
-  const trimmedContent = typeof content === 'string' ? content.trim() : '';
-  const hasAttachments = Array.isArray(attachmentIds) && attachmentIds.length > 0;
+  const trimmedContent = typeof content === "string" ? content.trim() : "";
+  const hasAttachments =
+    Array.isArray(attachmentIds) && attachmentIds.length > 0;
 
-  const hasCallbackData = typeof body.callbackData === 'string' && body.callbackData.length > 0;
+  const hasCallbackData =
+    typeof body.callbackData === "string" && body.callbackData.length > 0;
 
-  if (trimmedContent.length === 0 && !hasAttachments && !isEdit && !hasCallbackData) {
-    return httpError('BAD_REQUEST', 'content or attachmentIds is required', 400);
+  if (
+    trimmedContent.length === 0 &&
+    !hasAttachments &&
+    !isEdit &&
+    !hasCallbackData
+  ) {
+    return httpError(
+      "BAD_REQUEST",
+      "content or attachmentIds is required",
+      400,
+    );
   }
 
   // Canonicalize the assistant ID so all DB-facing operations use the
   // consistent 'self' key regardless of what the gateway sent.
   const canonicalAssistantId = canonicalChannelAssistantId(assistantId);
   if (canonicalAssistantId !== assistantId) {
-    log.debug({ raw: assistantId, canonical: canonicalAssistantId }, 'Canonicalized channel assistant ID');
+    log.debug(
+      { raw: assistantId, canonical: canonicalAssistantId },
+      "Canonicalized channel assistant ID",
+    );
   }
 
   // Coerce actorExternalId to a string at the boundary — the field
   // comes from unvalidated JSON and may be a number, object, or other
   // non-string type. Non-string truthy values would throw inside
   // canonicalizeInboundIdentity when it calls .trim().
-  const rawSenderId = body.actorExternalId != null
-    ? String(body.actorExternalId)
-    : undefined;
+  const rawSenderId =
+    body.actorExternalId != null ? String(body.actorExternalId) : undefined;
 
   // Canonicalize the sender identity so all trust lookups, member matching,
   // and guardian binding comparisons use a normalized form. Phone-like
@@ -212,255 +193,24 @@ export async function handleChannelInbound(
   const hasSenderIdentityClaim = rawSenderId !== undefined;
 
   // ── Ingress ACL enforcement ──
-  // Track the resolved member so the escalate branch can reference it after
-  // recordInbound (where we have a conversationId).
-  let resolvedMember: ReturnType<typeof findMember> = null;
-
-  // Verification codes must bypass the ACL membership check — users without a
-  // member record need to verify before they can be recognized as members.
-  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.
-  const rawCommandIntentForAcl = sourceMetadata?.commandIntent;
-  const isBootstrapCommand = rawCommandIntentForAcl &&
-    typeof rawCommandIntentForAcl === 'object' &&
-    !Array.isArray(rawCommandIntentForAcl) &&
-    (rawCommandIntentForAcl as Record<string, unknown>).type === 'start' &&
-    typeof (rawCommandIntentForAcl as Record<string, unknown>).payload === 'string' &&
-    ((rawCommandIntentForAcl as Record<string, unknown>).payload as string).startsWith('gv_');
-
-  // Parse invite token from /start payloads using the channel transport
-  // adapter. The token is extracted once here so both the ACL bypass and
-  // the intercept handler can reference it without re-parsing.
-  const commandIntentForAcl = rawCommandIntentForAcl && typeof rawCommandIntentForAcl === 'object' && !Array.isArray(rawCommandIntentForAcl)
-    ? rawCommandIntentForAcl as Record<string, unknown>
-    : undefined;
-  const inviteTransport = getTransport(sourceChannel);
-  const inviteToken = inviteTransport?.extractInboundToken({
-    commandIntent: commandIntentForAcl,
-    content: trimmedContent,
+  const aclResult = await enforceIngressAcl({
+    canonicalSenderId,
+    hasSenderIdentityClaim,
+    rawSenderId,
+    sourceChannel,
+    conversationExternalId,
+    canonicalAssistantId,
+    trimmedContent,
     sourceMetadata: body.sourceMetadata,
+    actorDisplayName: body.actorDisplayName,
+    actorUsername: body.actorUsername,
+    replyCallbackUrl: body.replyCallbackUrl,
+    mintBearerToken,
+    assistantId,
+    externalMessageId,
   });
-
-  if (canonicalSenderId || hasSenderIdentityClaim) {
-    // Only perform member lookup when we have a usable canonical ID.
-    // Whitespace-only senders (hasSenderIdentityClaim=true but
-    // canonicalSenderId=null) skip the lookup and fall into the deny path.
-    if (canonicalSenderId) {
-      resolvedMember = findMember({
-        assistantId: canonicalAssistantId,
-        sourceChannel,
-        externalUserId: canonicalSenderId,
-        externalChatId: conversationExternalId,
-      });
-    }
-
-    if (!resolvedMember) {
-      // 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 (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
-        // binding already exists, and the identity check inside
-        // validateAndConsumeChallenge prevents unauthorized takeovers.
-        const hasPendingChallenge = !!getPendingChallenge(canonicalAssistantId, sourceChannel);
-        const hasActiveOutboundSession = !!findActiveSession(canonicalAssistantId, sourceChannel);
-        if (hasPendingChallenge || hasActiveOutboundSession) {
-          denyNonMember = false;
-        } else {
-          log.info({ sourceChannel, hasPendingChallenge, hasActiveOutboundSession }, 'Ingress ACL: guardian verification bypass denied');
-        }
-      }
-
-      // Bootstrap deep-link commands bypass ACL only when the token
-      // resolves to a real pending_bootstrap session. Without this check,
-      // any `/start gv_<garbage>` would bypass the not_a_member gate and
-      // fall through to normal /start processing.
-      if (isBootstrapCommand) {
-        const bootstrapPayload = (rawCommandIntentForAcl as Record<string, unknown>).payload as string;
-        const bootstrapTokenForAcl = bootstrapPayload.slice(3); // strip 'gv_' prefix
-        const bootstrapSessionForAcl = resolveBootstrapToken(canonicalAssistantId, sourceChannel, bootstrapTokenForAcl);
-        if (bootstrapSessionForAcl && bootstrapSessionForAcl.status === 'pending_bootstrap') {
-          denyNonMember = false;
-        } else {
-          log.info({ sourceChannel, hasValidBootstrapSession: false }, 'Ingress ACL: bootstrap command bypass denied — no valid pending_bootstrap session');
-        }
-      }
-
-      // ── Invite token intercept (non-member) ──
-      // /start invite deep links grant access without guardian approval.
-      // Intercept here — before the deny gate — so valid invites short-circuit
-      // the ACL rejection and never reach the agent pipeline.
-      if (inviteToken && denyNonMember) {
-        const inviteResult = await handleInviteTokenIntercept({
-          rawToken: inviteToken,
-          sourceChannel,
-          externalChatId: conversationExternalId,
-          externalMessageId,
-          senderExternalUserId: canonicalSenderId ?? rawSenderId,
-          senderName: body.actorDisplayName,
-          senderUsername: body.actorUsername,
-          replyCallbackUrl: body.replyCallbackUrl,
-          bearerToken: mintBearerToken(),
-          assistantId,
-          canonicalAssistantId,
-        });
-        if (inviteResult) return inviteResult;
-      }
-
-      if (denyNonMember) {
-        log.info({ sourceChannel, externalUserId: canonicalSenderId }, 'Ingress ACL: no member record, denying');
-
-        // Notify the guardian about the access request so they can approve/deny.
-        // Uses the shared helper which handles guardian binding lookup,
-        // deduplication, canonical request creation, and notification emission.
-        let guardianNotified = false;
-        try {
-          const accessResult = notifyGuardianOfAccessRequest({
-            canonicalAssistantId,
-            sourceChannel,
-            conversationExternalId,
-            actorExternalId: canonicalSenderId ?? rawSenderId,
-            actorDisplayName: body.actorDisplayName,
-            actorUsername: body.actorUsername,
-          });
-          guardianNotified = accessResult.notified;
-        } catch (err) {
-          log.error({ err, sourceChannel, conversationExternalId }, '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: conversationExternalId,
-              text: replyText,
-              assistantId,
-            }, mintBearerToken());
-          } catch (err) {
-            log.error({ err, conversationExternalId }, 'Failed to deliver ACL rejection reply');
-          }
-        }
-
-        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: conversationExternalId,
-            externalMessageId,
-            senderExternalUserId: canonicalSenderId ?? rawSenderId,
-            senderName: body.actorDisplayName,
-            senderUsername: body.actorUsername,
-            replyCallbackUrl: body.replyCallbackUrl,
-            bearerToken: mintBearerToken(),
-            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 {
-              const accessResult = notifyGuardianOfAccessRequest({
-                canonicalAssistantId,
-                sourceChannel,
-                conversationExternalId,
-                actorExternalId: canonicalSenderId ?? rawSenderId,
-                actorDisplayName: body.actorDisplayName,
-                actorUsername: body.actorUsername,
-                previousMemberStatus: resolvedMember.status,
-              });
-              guardianNotified = accessResult.notified;
-            } catch (err) {
-              log.error({ err, sourceChannel, conversationExternalId }, '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: conversationExternalId,
-                text: replyText,
-                assistantId,
-              }, mintBearerToken());
-            } catch (err) {
-              log.error({ err, conversationExternalId }, 'Failed to deliver ACL rejection reply');
-            }
-          }
-          return Response.json({ accepted: true, denied: true, reason: `member_${resolvedMember.status}` });
-        }
-      }
-
-      if (resolvedMember.policy === 'deny') {
-        log.info({ sourceChannel, memberId: resolvedMember.id }, 'Ingress ACL: member policy deny');
-        if (body.replyCallbackUrl) {
-          try {
-            await deliverChannelReply(body.replyCallbackUrl, {
-              chatId: conversationExternalId,
-              text: "Sorry, you haven't been approved to message this assistant.",
-              assistantId,
-            }, mintBearerToken());
-          } catch (err) {
-            log.error({ err, conversationExternalId }, 'Failed to deliver ACL rejection reply');
-          }
-        }
-        return Response.json({ accepted: true, denied: true, reason: 'policy_deny' });
-      }
-
-      // 'allow' or 'escalate' — update last seen and continue
-      updateLastSeen(resolvedMember.id);
-    }
-  }
+  if (aclResult.earlyResponse) return aclResult.earlyResponse;
+  const { resolvedMember, guardianVerifyCode } = aclResult;
 
   if (hasAttachments) {
     const resolved = attachmentsStore.getAttachmentsByIds(attachmentIds);
@@ -468,78 +218,35 @@ export async function handleChannelInbound(
       const resolvedIds = new Set(resolved.map((a) => a.id));
       const missing = attachmentIds.filter((id) => !resolvedIds.has(id));
       return Response.json(
-        { error: `Attachment IDs not found: ${missing.join(', ')}` },
+        { error: `Attachment IDs not found: ${missing.join(", ")}` },
         { status: 400 },
       );
     }
   }
 
-  const sourceMessageId = typeof sourceMetadata?.messageId === 'string'
-    ? sourceMetadata.messageId
-    : undefined;
+  const sourceMessageId =
+    typeof sourceMetadata?.messageId === "string"
+      ? sourceMetadata.messageId
+      : undefined;
 
   if (isEdit && !sourceMessageId) {
-    return httpError('BAD_REQUEST', 'sourceMetadata.messageId is required for edits', 400);
+    return httpError(
+      "BAD_REQUEST",
+      "sourceMetadata.messageId is required for edits",
+      400,
+    );
   }
 
   // ── Edit path: update existing message content, no new agent loop ──
   if (isEdit && sourceMessageId) {
-    // Dedup the edit event itself (retried edited_message webhooks)
-    const editResult = channelDeliveryStore.recordInbound(
+    return handleEditIntercept({
       sourceChannel,
       conversationExternalId,
       externalMessageId,
-      { sourceMessageId, assistantId: canonicalAssistantId },
-    );
-
-    if (editResult.duplicate) {
-      return Response.json({
-        accepted: true,
-        duplicate: true,
-        eventId: editResult.eventId,
-      });
-    }
-
-    // Retry lookup a few times — the original message may still be processing
-    // (linkMessage hasn't been called yet). Short backoff avoids losing edits
-    // that arrive while the original agent loop is in progress.
-    const EDIT_LOOKUP_RETRIES = 5;
-    const EDIT_LOOKUP_DELAY_MS = 2000;
-
-    let original: { messageId: string; conversationId: string } | null = null;
-    for (let attempt = 0; attempt <= EDIT_LOOKUP_RETRIES; attempt++) {
-      original = channelDeliveryStore.findMessageBySourceId(
-        sourceChannel,
-        conversationExternalId,
-        sourceMessageId,
-      );
-      if (original) break;
-      if (attempt < EDIT_LOOKUP_RETRIES) {
-        log.info(
-          { assistantId, sourceMessageId, attempt: attempt + 1, maxAttempts: EDIT_LOOKUP_RETRIES },
-          'Original message not linked yet, retrying edit lookup',
-        );
-        await new Promise((resolve) => setTimeout(resolve, EDIT_LOOKUP_DELAY_MS));
-      }
-    }
-
-    if (original) {
-      conversationStore.updateMessageContent(original.messageId, content ?? '');
-      log.info(
-        { assistantId, sourceMessageId, messageId: original.messageId },
-        'Updated message content from edited_message',
-      );
-    } else {
-      log.warn(
-        { assistantId, sourceChannel, conversationExternalId, sourceMessageId },
-        'Could not find original message for edit after retries, ignoring',
-      );
-    }
-
-    return Response.json({
-      accepted: true,
-      duplicate: false,
-      eventId: editResult.eventId,
+      sourceMessageId,
+      canonicalAssistantId,
+      assistantId,
+      content,
     });
   }
 
@@ -558,18 +265,30 @@ export async function handleChannelInbound(
   // gateway retries (duplicates) re-attempt delivery here. On success the
   // pending marker is cleared so further duplicates short-circuit normally.
   if (result.duplicate && replyCallbackUrl) {
-    const pendingReply = channelDeliveryStore.getPendingVerificationReply(result.eventId);
+    const pendingReply = channelDeliveryStore.getPendingVerificationReply(
+      result.eventId,
+    );
     if (pendingReply) {
       try {
-        await deliverChannelReply(replyCallbackUrl, {
-          chatId: pendingReply.chatId,
-          text: pendingReply.text,
-          assistantId: pendingReply.assistantId,
-        }, mintBearerToken());
+        await deliverChannelReply(
+          replyCallbackUrl,
+          {
+            chatId: pendingReply.chatId,
+            text: pendingReply.text,
+            assistantId: pendingReply.assistantId,
+          },
+          mintBearerToken(),
+        );
         channelDeliveryStore.clearPendingVerificationReply(result.eventId);
-        log.info({ eventId: result.eventId }, 'Retried pending verification reply: delivered');
+        log.info(
+          { eventId: result.eventId },
+          "Retried pending verification reply: delivered",
+        );
       } catch (retryErr) {
-        log.error({ err: retryErr, eventId: result.eventId }, 'Retry of pending verification reply failed; will retry on next duplicate');
+        log.error(
+          { err: retryErr, eventId: result.eventId },
+          "Retry of pending verification reply failed; will retry on next duplicate",
+        );
       }
       return Response.json({
         accepted: true,
@@ -594,322 +313,86 @@ export async function handleChannelInbound(
   }
 
   // ── Ingress escalation ──
-  // When the member's policy is 'escalate', create a pending guardian
-  // approval request and halt the run. This check runs after recordInbound
-  // so we have a conversationId for the approval record.
-  if (resolvedMember?.policy === 'escalate') {
-    const binding = getGuardianBinding(canonicalAssistantId, sourceChannel);
-    if (!binding) {
-      // Fail-closed: can't escalate without a guardian to route to
-      log.info({ sourceChannel, memberId: resolvedMember.id }, 'Ingress ACL: escalate policy but no guardian binding, denying');
-      return Response.json({ accepted: true, denied: true, reason: 'escalate_no_guardian' });
-    }
-
-    // Persist the raw payload so the decide handler can recover the original
-    // message content when the escalation is approved.
-    channelDeliveryStore.storePayload(result.eventId, {
-      sourceChannel, interface: sourceInterface, externalChatId: conversationExternalId, externalMessageId, content,
-      attachmentIds, sourceMetadata: body.sourceMetadata,
-      senderName: body.actorDisplayName,
-      senderExternalUserId: body.actorExternalId,
-      senderUsername: body.actorUsername,
-      replyCallbackUrl: body.replyCallbackUrl,
-      assistantId: canonicalAssistantId,
-    });
-
-    try {
-      createCanonicalGuardianRequest({
-        kind: 'tool_approval',
-        sourceType: 'channel',
-        sourceChannel,
-        conversationId: result.conversationId,
-        requesterExternalUserId: canonicalSenderId ?? rawSenderId ?? undefined,
-        guardianExternalUserId: binding.guardianExternalUserId,
-        guardianPrincipalId: binding.guardianPrincipalId,
-        toolName: 'ingress_message',
-        questionText: 'Ingress policy requires guardian approval',
-        expiresAt: new Date(Date.now() + GUARDIAN_APPROVAL_TTL_MS).toISOString(),
-      });
-    } catch (err) {
-      log.warn(
-        { err, conversationId: result.conversationId, sourceChannel },
-        'Failed to create canonical guardian request for ingress escalation — escalation continues via notification pipeline',
-      );
-    }
-
-    // Emit notification signal through the unified pipeline (fire-and-forget).
-    // This lets the decision engine route escalation alerts to all configured
-    // channels, supplementing the direct guardian notification below.
-    void emitNotificationSignal({
-      sourceEventName: 'ingress.escalation',
-      sourceChannel: sourceChannel,
-      sourceSessionId: result.conversationId,
-      assistantId: canonicalAssistantId,
-      attentionHints: {
-        requiresAction: true,
-        urgency: 'high',
-        isAsyncBackground: false,
-        visibleInSourceNow: false,
-      },
-      contextPayload: {
-        conversationId: result.conversationId,
-        sourceChannel,
-        conversationExternalId,
-        senderIdentifier: body.actorDisplayName || body.actorUsername || rawSenderId || 'Unknown sender',
-        eventId: result.eventId,
-      },
-      dedupeKey: `escalation:${result.eventId}`,
-    });
-
-    // Guardian escalation channel delivery is handled by the notification
-    // pipeline — no legacy callback dispatch needed.
-    log.info(
-      { conversationId: result.conversationId },
-      'Guardian escalation created — notification pipeline handles channel delivery',
-    );
-
-    return Response.json({ accepted: true, escalated: true, reason: 'policy_escalate' });
-  }
+  const escalationResponse = handleEscalationIntercept({
+    resolvedMember,
+    canonicalAssistantId,
+    sourceChannel,
+    sourceInterface,
+    conversationExternalId,
+    externalMessageId,
+    conversationId: result.conversationId,
+    eventId: result.eventId,
+    content,
+    attachmentIds,
+    sourceMetadata: body.sourceMetadata,
+    actorDisplayName: body.actorDisplayName,
+    actorExternalId: body.actorExternalId,
+    actorUsername: body.actorUsername,
+    replyCallbackUrl: body.replyCallbackUrl,
+    canonicalSenderId,
+    rawSenderId,
+  });
+  if (escalationResponse) return escalationResponse;
 
   const metadataHintsRaw = sourceMetadata?.hints;
   const metadataHints = Array.isArray(metadataHintsRaw)
-    ? metadataHintsRaw.filter((hint): hint is string => typeof hint === 'string' && hint.trim().length > 0)
+    ? metadataHintsRaw.filter(
+        (hint): hint is string =>
+          typeof hint === "string" && hint.trim().length > 0,
+      )
     : [];
-  const metadataUxBrief = typeof sourceMetadata?.uxBrief === 'string' && sourceMetadata.uxBrief.trim().length > 0
-    ? sourceMetadata.uxBrief.trim()
-    : undefined;
+  const metadataUxBrief =
+    typeof sourceMetadata?.uxBrief === "string" &&
+    sourceMetadata.uxBrief.trim().length > 0
+      ? sourceMetadata.uxBrief.trim()
+      : undefined;
 
   // Extract channel command intent (e.g. /start from Telegram)
   const rawCommandIntent = sourceMetadata?.commandIntent;
-  const commandIntent = rawCommandIntent && typeof rawCommandIntent === 'object' && !Array.isArray(rawCommandIntent)
-    ? rawCommandIntent as Record<string, unknown>
-    : undefined;
+  const commandIntent =
+    rawCommandIntent &&
+    typeof rawCommandIntent === "object" &&
+    !Array.isArray(rawCommandIntent)
+      ? (rawCommandIntent as Record<string, unknown>)
+      : undefined;
 
   // Preserve locale from sourceMetadata so the model can greet in the user's language
-  const sourceLanguageCode = typeof sourceMetadata?.languageCode === 'string' && sourceMetadata.languageCode.trim().length > 0
-    ? sourceMetadata.languageCode.trim()
-    : undefined;
+  const sourceLanguageCode =
+    typeof sourceMetadata?.languageCode === "string" &&
+    sourceMetadata.languageCode.trim().length > 0
+      ? sourceMetadata.languageCode.trim()
+      : undefined;
 
   // ── Telegram bootstrap deep-link handling ──
-  // 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
-  // identity-bound session with a fresh verification code, send it, and return.
-  if (
-    !result.duplicate &&
-    commandIntent?.type === 'start' &&
-    typeof commandIntent.payload === 'string' &&
-    (commandIntent.payload as string).startsWith('gv_') &&
-    rawSenderId
-  ) {
-    const bootstrapToken = (commandIntent.payload as string).slice(3);
-    const bootstrapSession = resolveBootstrapToken(canonicalAssistantId, sourceChannel, bootstrapToken);
-
-    if (bootstrapSession && bootstrapSession.status === 'pending_bootstrap') {
-      // Bind the pending_bootstrap session to the sender's identity
-      bindSessionIdentity(bootstrapSession.id, rawSenderId!, conversationExternalId);
-
-      // Transition bootstrap session to awaiting_response
-      updateSessionStatus(bootstrapSession.id, 'awaiting_response');
-
-      // Create a new identity-bound outbound session with a fresh secret.
-      // The old bootstrap session is auto-revoked by createOutboundSession.
-      const newSession = createOutboundSession({
-        assistantId: canonicalAssistantId,
-        channel: sourceChannel,
-        expectedExternalUserId: rawSenderId!,
-        expectedChatId: conversationExternalId,
-        identityBindingStatus: 'bound',
-        destinationAddress: conversationExternalId,
-      });
-
-      // Compose and send the verification prompt via Telegram
-      const telegramBody = composeVerificationTelegram(
-        GUARDIAN_VERIFY_TEMPLATE_KEYS.TELEGRAM_CHALLENGE_REQUEST,
-        {
-          code: newSession.secret,
-          expiresInMinutes: Math.floor((newSession.expiresAt - Date.now()) / 60_000),
-        },
-      );
-
-      // Deliver verification Telegram message via the gateway (fire-and-forget)
-      deliverBootstrapVerificationTelegram(conversationExternalId, telegramBody, canonicalAssistantId);
-
-      // Update delivery tracking
-      const now = Date.now();
-      updateSessionDelivery(newSession.sessionId, now, 1, now + RESEND_COOLDOWN_MS);
-
-      return Response.json({
-        accepted: true,
-        duplicate: false,
-        eventId: result.eventId,
-        guardianVerification: 'bootstrap_bound',
-      });
-    }
-    // If not found or expired, fall through to normal /start handling
-  }
+  const bootstrapResponse = await handleBootstrapIntercept({
+    isDuplicate: result.duplicate,
+    commandIntent,
+    rawSenderId,
+    canonicalAssistantId,
+    sourceChannel,
+    conversationExternalId,
+    eventId: result.eventId,
+  });
+  if (bootstrapResponse) return bootstrapResponse;
 
   // ── 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 code
-  // is short-circuited — it NEVER enters the agent pipeline. This
-  // 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.
-  const shouldInterceptVerification = guardianVerifyCode !== undefined &&
-    (!!getPendingChallenge(canonicalAssistantId, sourceChannel) ||
-     !!findActiveSession(canonicalAssistantId, sourceChannel));
-
-  if (
-    !result.duplicate &&
-    shouldInterceptVerification &&
-    guardianVerifyCode !== undefined &&
-    rawSenderId
-  ) {
-    const verifyResult = validateAndConsumeChallenge(
-      canonicalAssistantId,
-      sourceChannel,
-      guardianVerifyCode,
-      canonicalSenderId ?? rawSenderId!,
-      conversationExternalId,
-      body.actorUsername,
-      body.actorDisplayName,
-    );
-
-    const guardianVerifyOutcome: 'verified' | 'failed' = verifyResult.success ? 'verified' : 'failed';
-
-    if (verifyResult.success) {
-      const existingMember = (canonicalSenderId ?? rawSenderId)
-        ? findMember({
-          assistantId: canonicalAssistantId,
-          sourceChannel,
-          externalUserId: canonicalSenderId ?? rawSenderId!,
-          externalChatId: conversationExternalId,
-        })
-        : null;
-      const memberMatchesSender = existingMember?.externalUserId
-        ? canonicalizeInboundIdentity(sourceChannel, existingMember.externalUserId) === (canonicalSenderId ?? rawSenderId)
-        : false;
-      const preservedDisplayName = memberMatchesSender && existingMember?.displayName?.trim().length
-        ? existingMember.displayName
-        : body.actorDisplayName;
-
-      upsertMember({
-        assistantId: canonicalAssistantId,
-        sourceChannel,
-        externalUserId: canonicalSenderId ?? rawSenderId!,
-        externalChatId: conversationExternalId,
-        status: 'active',
-        policy: 'allow',
-        // Keep guardian-curated member name stable across re-verification.
-        displayName: preservedDisplayName,
-        username: body.actorUsername,
-      });
-
-      const verifyLogLabel = verifyResult.verificationType === 'trusted_contact'
-        ? 'Trusted contact verified'
-        : 'Guardian verified';
-      log.info({ sourceChannel, externalUserId: canonicalSenderId, verificationType: verifyResult.verificationType }, `${verifyLogLabel}: auto-upserted ingress member`);
-
-      // Emit activated signal when a trusted contact completes verification.
-      // Member record is persisted above before this event fires, satisfying
-      // 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,
-            actorExternalId: canonicalSenderId ?? rawSenderId!,
-            conversationExternalId,
-            actorDisplayName: body.actorDisplayName ?? null,
-            actorUsername: body.actorUsername ?? null,
-          },
-          dedupeKey: `trusted-contact:activated:${canonicalAssistantId}:${sourceChannel}:${canonicalSenderId ?? rawSenderId!}`,
-        });
-      }
-    }
-
-    // Deliver a deterministic template-driven reply and short-circuit.
-    // Verification code messages must never produce agent-generated copy.
-    if (replyCallbackUrl) {
-      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: conversationExternalId,
-          text: replyText,
-          assistantId,
-        }, mintBearerToken());
-      } catch (err) {
-        // The challenge is already consumed and side effects applied, so
-        // we cannot simply re-throw and let the gateway retry the full
-        // flow. Instead, persist the reply so that gateway retries
-        // (which arrive as duplicates) can re-attempt delivery.
-        log.error({ err, conversationExternalId }, 'Failed to deliver deterministic verification reply; persisting for retry');
-        channelDeliveryStore.storePendingVerificationReply(result.eventId, {
-          chatId: conversationExternalId,
-          text: replyText,
-          assistantId,
-        });
-
-        // Self-retry after a short delay. The gateway deduplicates
-        // inbound webhooks after a successful forward, so duplicate
-        // retries may never arrive. This fire-and-forget retry ensures
-        // delivery is re-attempted even without a gateway duplicate.
-        setTimeout(async () => {
-          try {
-            await deliverChannelReply(replyCallbackUrl, {
-              chatId: conversationExternalId,
-              text: replyText,
-              assistantId,
-            }, mintBearerToken());
-            log.info({ eventId: result.eventId }, 'Verification reply delivered on self-retry');
-            channelDeliveryStore.clearPendingVerificationReply(result.eventId);
-          } catch (retryErr) {
-            log.error({ err: retryErr, eventId: result.eventId }, 'Verification reply self-retry also failed; pending reply remains as fallback');
-          }
-        }, 3000);
-
-        return Response.json({
-          accepted: true,
-          duplicate: false,
-          eventId: result.eventId,
-          guardianVerification: guardianVerifyOutcome,
-          deliveryPending: true,
-        });
-      }
-    }
-
-    return Response.json({
-      accepted: true,
-      duplicate: false,
-      eventId: result.eventId,
-      guardianVerification: guardianVerifyOutcome,
-    });
-  }
+  const verificationResponse = await handleVerificationIntercept({
+    isDuplicate: result.duplicate,
+    guardianVerifyCode,
+    rawSenderId,
+    canonicalSenderId,
+    canonicalAssistantId,
+    sourceChannel,
+    conversationExternalId,
+    conversationId: result.conversationId,
+    eventId: result.eventId,
+    replyCallbackUrl,
+    mintBearerToken,
+    assistantId,
+    actorDisplayName: body.actorDisplayName,
+    actorUsername: body.actorUsername,
+  });
+  if (verificationResponse) return verificationResponse;
 
   // Legacy voice guardian action interception removed — all guardian reply
   // routing now flows through the canonical router below (routeGuardianReply),
@@ -919,7 +402,7 @@ export async function handleChannelInbound(
   // ── Actor role resolution ──
   // Uses shared channel-agnostic resolution so all ingress paths classify
   // guardian vs non-guardian actors the same way.
-  const guardianCtx: GuardianContext = resolveGuardianContext({
+  const trustCtx: TrustContext = resolveTrustContext({
     assistantId: canonicalAssistantId,
     sourceChannel,
     conversationExternalId,
@@ -928,99 +411,26 @@ export async function handleChannelInbound(
     actorDisplayName: body.actorDisplayName,
   });
 
-  // Hoisted flag: set by the canonical guardian reply router when the invite
-  // handoff bypass fires. Prevents legacy approval interception from swallowing
-  // the message when other approvals are pending in the same chat.
-  let skipApprovalInterception = false;
-
   // ── Canonical guardian reply router ──
-  // Attempts to route inbound messages through the canonical decision pipeline
-  // before falling through to the legacy approval interception. Handles
-  // deterministic callbacks (button presses), request code prefixes, and
-  // NL classification via the conversational approval engine.
-  if (
-    !result.duplicate &&
-    replyCallbackUrl &&
-    (trimmedContent.length > 0 || hasCallbackData) &&
-    rawSenderId &&
-    guardianCtx.trustClass === 'guardian'
-  ) {
-    // Compute destination-scoped pending request hints so the router can
-    // discover canonical requests delivered to this chat even when the
-    // request lacks a guardianExternalUserId (e.g. voice-originated
-    // pending_question requests).
-    //
-    // When delivery-scoped matches exist, union them with any identity-
-    // based pending requests so that requests without delivery rows (e.g.
-    // tool_approval requests created inline) are not silently excluded.
-    // Pass undefined (not []) when there are zero combined results so the
-    // router's own identity-based fallback stays active.
-    const deliveryScopedPendingRequests = listPendingCanonicalGuardianRequestsByDestinationChat(
-      sourceChannel,
-      conversationExternalId,
-    );
-    let pendingRequestIds: string[] | undefined;
-    if (deliveryScopedPendingRequests.length > 0) {
-      const deliveryIds = new Set(deliveryScopedPendingRequests.map(r => r.id));
-      // Also include identity-based pending requests so we don't hide them
-      const identityId = canonicalSenderId ?? rawSenderId!;
-      const identityPending = listCanonicalGuardianRequests({
-        status: 'pending',
-        guardianExternalUserId: identityId,
-      });
-      for (const r of identityPending) {
-        deliveryIds.add(r.id);
-      }
-      pendingRequestIds = [...deliveryIds];
-    }
-
-    const routerResult = await routeGuardianReply({
-      messageText: trimmedContent,
-      channel: sourceChannel,
-      actor: {
-        externalUserId: canonicalSenderId ?? rawSenderId!,
-        channel: sourceChannel,
-        guardianPrincipalId: guardianCtx.guardianPrincipalId ?? undefined,
-      },
-      conversationId: result.conversationId,
-      callbackData: body.callbackData,
-      pendingRequestIds,
-      approvalConversationGenerator,
-      channelDeliveryContext: {
-        replyCallbackUrl,
-        guardianChatId: conversationExternalId,
-        assistantId: canonicalAssistantId,
-        bearerToken: mintBearerToken(),
-      },
-    });
-
-    if (routerResult.consumed) {
-      // Deliver reply text if the router produced one
-      if (routerResult.replyText) {
-        try {
-          await deliverChannelReply(replyCallbackUrl, {
-            chatId: conversationExternalId,
-            text: routerResult.replyText,
-            assistantId: canonicalAssistantId,
-          }, mintBearerToken());
-        } catch (err) {
-          log.error({ err, conversationExternalId }, 'Failed to deliver canonical router reply');
-        }
-      }
-
-      return Response.json({
-        accepted: true,
-        duplicate: false,
-        eventId: result.eventId,
-        canonicalRouter: routerResult.type,
-        requestId: routerResult.requestId,
-      });
-    }
-
-    if (routerResult.skipApprovalInterception) {
-      skipApprovalInterception = true;
-    }
-  }
+  const guardianReplyResult = await handleGuardianReplyIntercept({
+    isDuplicate: result.duplicate,
+    trimmedContent,
+    hasCallbackData,
+    callbackData: body.callbackData,
+    rawSenderId,
+    canonicalSenderId,
+    canonicalAssistantId,
+    sourceChannel,
+    conversationExternalId,
+    conversationId: result.conversationId,
+    eventId: result.eventId,
+    replyCallbackUrl,
+    mintBearerToken,
+    trustClass: trustCtx.trustClass,
+    guardianPrincipalId: trustCtx.guardianPrincipalId,
+    approvalConversationGenerator,
+  });
+  if (guardianReplyResult.response) return guardianReplyResult.response;
 
   // ── Approval interception ──
   // Keep this active whenever callback context is available.
@@ -1030,7 +440,7 @@ export async function handleChannelInbound(
   if (
     replyCallbackUrl &&
     !result.duplicate &&
-    !skipApprovalInterception
+    !guardianReplyResult.skipApprovalInterception
   ) {
     const approvalResult = await handleApprovalInterception({
       conversationId: result.conversationId,
@@ -1041,7 +451,7 @@ export async function handleChannelInbound(
       actorExternalId: canonicalSenderId ?? rawSenderId,
       replyCallbackUrl,
       bearerToken: mintBearerToken(),
-      guardianCtx,
+      trustCtx,
       assistantId: canonicalAssistantId,
       approvalCopyGenerator,
       approvalConversationGenerator,
@@ -1049,37 +459,42 @@ export async function handleChannelInbound(
 
     if (approvalResult.handled) {
       // Record inferred seen signal for all handled Telegram approval interactions
-      if (sourceChannel === 'telegram') {
+      if (sourceChannel === "telegram") {
         try {
           if (hasCallbackData) {
-            const cbPreview = body.callbackData!.length > 80
-              ? body.callbackData!.slice(0, 80) + '...'
-              : body.callbackData!;
+            const cbPreview =
+              body.callbackData!.length > 80
+                ? body.callbackData!.slice(0, 80) + "..."
+                : body.callbackData!;
             recordConversationSeenSignal({
               conversationId: result.conversationId,
               assistantId: canonicalAssistantId,
-              signalType: 'telegram_callback',
-              confidence: 'inferred',
-              sourceChannel: 'telegram',
-              source: 'inbound-message-handler',
+              signalType: "telegram_callback",
+              confidence: "inferred",
+              sourceChannel: "telegram",
+              source: "inbound-message-handler",
               evidenceText: `User tapped callback: '${cbPreview}'`,
             });
           } else {
-            const msgPreview = trimmedContent.length > 80
-              ? trimmedContent.slice(0, 80) + '...'
-              : trimmedContent;
+            const msgPreview =
+              trimmedContent.length > 80
+                ? trimmedContent.slice(0, 80) + "..."
+                : trimmedContent;
             recordConversationSeenSignal({
               conversationId: result.conversationId,
               assistantId: canonicalAssistantId,
-              signalType: 'telegram_inbound_message',
-              confidence: 'inferred',
-              sourceChannel: 'telegram',
-              source: 'inbound-message-handler',
+              signalType: "telegram_inbound_message",
+              confidence: "inferred",
+              sourceChannel: "telegram",
+              source: "inbound-message-handler",
               evidenceText: `User sent plain-text approval reply: '${msgPreview}'`,
             });
           }
         } catch (err) {
-          log.warn({ err, conversationId: result.conversationId }, 'Failed to record seen signal for Telegram approval interaction');
+          log.warn(
+            { err, conversationId: result.conversationId },
+            "Failed to record seen signal for Telegram approval interaction",
+          );
         }
       }
 
@@ -1098,22 +513,26 @@ export async function handleChannelInbound(
     // so checking for empty content alone would miss stale callbacks.
     if (hasCallbackData) {
       // Record seen signal even for stale callbacks — the user still interacted
-      if (sourceChannel === 'telegram') {
+      if (sourceChannel === "telegram") {
         try {
-          const cbPreview = body.callbackData!.length > 80
-            ? body.callbackData!.slice(0, 80) + '...'
-            : body.callbackData!;
+          const cbPreview =
+            body.callbackData!.length > 80
+              ? body.callbackData!.slice(0, 80) + "..."
+              : body.callbackData!;
           recordConversationSeenSignal({
             conversationId: result.conversationId,
             assistantId: canonicalAssistantId,
-            signalType: 'telegram_callback',
-            confidence: 'inferred',
-            sourceChannel: 'telegram',
-            source: 'inbound-message-handler',
+            signalType: "telegram_callback",
+            confidence: "inferred",
+            sourceChannel: "telegram",
+            source: "inbound-message-handler",
             evidenceText: `User tapped stale callback: '${cbPreview}'`,
           });
         } catch (err) {
-          log.warn({ err, conversationId: result.conversationId }, 'Failed to record seen signal for stale Telegram callback');
+          log.warn(
+            { err, conversationId: result.conversationId },
+            "Failed to record seen signal for stale Telegram callback",
+          );
         }
       }
 
@@ -1121,7 +540,7 @@ export async function handleChannelInbound(
         accepted: true,
         duplicate: false,
         eventId: result.eventId,
-        approval: 'stale_ignored',
+        approval: "stale_ignored",
       });
     }
   }
@@ -1129,56 +548,24 @@ export async function handleChannelInbound(
   // For new (non-duplicate) messages, run the secret ingress check
   // synchronously, then fire off the agent loop in the background.
   if (!result.duplicate && processMessage) {
-    // Persist the raw payload first so dead-lettered events can always be
-    // replayed. If the ingress check later detects secrets we clear it
-    // before throwing, so secret-bearing content is never left on disk.
-    channelDeliveryStore.storePayload(result.eventId, {
-      sourceChannel, externalChatId: conversationExternalId, externalMessageId, content,
-      attachmentIds, sourceMetadata: body.sourceMetadata,
-      senderName: body.actorDisplayName,
-      senderExternalUserId: body.actorExternalId,
-      senderUsername: body.actorUsername,
-      guardianCtx,
+    runSecretIngressCheck({
+      eventId: result.eventId,
+      sourceChannel,
+      conversationExternalId,
+      externalMessageId,
+      conversationId: result.conversationId,
+      content,
+      trimmedContent,
+      attachmentIds,
+      sourceMetadata: body.sourceMetadata,
+      actorDisplayName: body.actorDisplayName,
+      actorExternalId: body.actorExternalId,
+      actorUsername: body.actorUsername,
+      trustCtx,
       replyCallbackUrl,
-      assistantId: canonicalAssistantId,
+      canonicalAssistantId,
     });
 
-    const contentToCheck = content ?? '';
-    let ingressCheck: ReturnType<typeof checkIngressForSecrets>;
-    try {
-      ingressCheck = checkIngressForSecrets(contentToCheck);
-    } catch (checkErr) {
-      channelDeliveryStore.clearPayload(result.eventId);
-      throw checkErr;
-    }
-    if (ingressCheck.blocked) {
-      channelDeliveryStore.clearPayload(result.eventId);
-      throw new IngressBlockedError(ingressCheck.userNotice!, ingressCheck.detectedTypes);
-    }
-
-    // Record inferred seen signal for non-duplicate Telegram inbound messages
-    if (sourceChannel === 'telegram') {
-      try {
-        const msgPreview = trimmedContent.length > 80
-          ? trimmedContent.slice(0, 80) + '...'
-          : trimmedContent;
-        const evidence = trimmedContent.length > 0
-          ? `User sent message: '${msgPreview}'`
-          : 'User sent media attachment';
-        recordConversationSeenSignal({
-          conversationId: result.conversationId,
-          assistantId: canonicalAssistantId,
-          signalType: 'telegram_inbound_message',
-          confidence: 'inferred',
-          sourceChannel: 'telegram',
-          source: 'inbound-message-handler',
-          evidenceText: evidence,
-        });
-      } catch (err) {
-        log.warn({ err, conversationId: result.conversationId }, 'Failed to record seen signal for Telegram inbound message');
-      }
-    }
-
     // Fire-and-forget: process the message and deliver the reply in the background.
     // The HTTP response returns immediately so the gateway webhook is not blocked.
     // The onEvent callback in processMessage registers pending interactions, and
@@ -1187,12 +574,12 @@ export async function handleChannelInbound(
       processMessage,
       conversationId: result.conversationId,
       eventId: result.eventId,
-      content: content ?? '',
+      content: content ?? "",
       attachmentIds: hasAttachments ? attachmentIds : undefined,
       sourceChannel,
       sourceInterface,
       externalChatId: conversationExternalId,
-      guardianCtx,
+      trustCtx,
       metadataHints,
       metadataUxBrief,
       commandIntent,
@@ -1210,572 +597,3 @@ export async function handleChannelInbound(
     eventId: result.eventId,
   });
 }
-
-// ---------------------------------------------------------------------------
-// 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: params.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 });
-}
-
-// ---------------------------------------------------------------------------
-// Background message processing
-// ---------------------------------------------------------------------------
-
-interface BackgroundProcessingParams {
-  processMessage: MessageProcessor;
-  conversationId: string;
-  eventId: string;
-  content: string;
-  attachmentIds?: string[];
-  sourceChannel: ChannelId;
-  sourceInterface: InterfaceId;
-  externalChatId: string;
-  guardianCtx: GuardianContext;
-  metadataHints: string[];
-  metadataUxBrief?: string;
-  replyCallbackUrl?: string;
-  /** Factory that mints a fresh delivery JWT for each HTTP attempt. */
-  mintBearerToken: () => string;
-  assistantId?: string;
-  approvalCopyGenerator?: ApprovalCopyGenerator;
-  commandIntent?: Record<string, unknown>;
-  sourceLanguageCode?: string;
-}
-
-const TELEGRAM_TYPING_INTERVAL_MS = 4_000;
-const PENDING_APPROVAL_POLL_INTERVAL_MS = 300;
-
-// Module-level map tracking which approval requestIds have already been
-// notified to trusted contacts. Maps requestId -> conversationId so that
-// cleanup can be scoped to the owning conversation's poller, preventing
-// concurrent pollers from different conversations from evicting each
-// other's entries.
-const globalNotifiedApprovalRequestIds = new Map<string, string>();
-
-function delay(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-function shouldEmitTelegramTyping(
-  sourceChannel: ChannelId,
-  replyCallbackUrl?: string,
-): boolean {
-  if (sourceChannel !== 'telegram' || !replyCallbackUrl) return false;
-  try {
-    return new URL(replyCallbackUrl).pathname.endsWith('/deliver/telegram');
-  } catch {
-    return replyCallbackUrl.endsWith('/deliver/telegram');
-  }
-}
-
-function startTelegramTypingHeartbeat(
-  callbackUrl: string,
-  chatId: string,
-  mintBearerToken: () => string,
-  assistantId?: string,
-): () => void {
-  let active = true;
-  let inFlight = false;
-
-  const emitTyping = (): void => {
-    if (!active || inFlight) return;
-    inFlight = true;
-    void deliverChannelReply(
-      callbackUrl,
-      { chatId, chatAction: 'typing', assistantId },
-      mintBearerToken(),
-    ).catch((err) => {
-      log.debug({ err, chatId }, 'Failed to deliver Telegram typing indicator');
-    }).finally(() => {
-      inFlight = false;
-    });
-  };
-
-  emitTyping();
-
-  const interval = setInterval(emitTyping, TELEGRAM_TYPING_INTERVAL_MS);
-  (interval as { unref?: () => void }).unref?.();
-
-  return () => {
-    active = false;
-    clearInterval(interval);
-  };
-}
-
-function startPendingApprovalPromptWatcher(params: {
-  conversationId: string;
-  sourceChannel: ChannelId;
-  externalChatId: string;
-  guardianTrustClass: GuardianContext['trustClass'];
-  guardianExternalUserId?: string;
-  requesterExternalUserId?: string;
-  replyCallbackUrl: string;
-  mintBearerToken: () => string;
-  assistantId?: string;
-  approvalCopyGenerator?: ApprovalCopyGenerator;
-}): () => void {
-  const {
-    conversationId,
-    sourceChannel,
-    externalChatId,
-    guardianTrustClass,
-    guardianExternalUserId,
-    requesterExternalUserId,
-    replyCallbackUrl,
-    mintBearerToken,
-    assistantId,
-    approvalCopyGenerator,
-  } = params;
-
-  // Approval prompt delivery is guardian-only. Non-guardian and unverified
-  // actors must never receive approval prompt broadcasts for the conversation.
-  // We also require an explicit identity match against the bound guardian to
-  // avoid broadcasting prompts when trustClass is stale/mis-scoped.
-  const isBoundGuardianActor = guardianTrustClass === 'guardian'
-    && !!guardianExternalUserId
-    && requesterExternalUserId === guardianExternalUserId;
-  if (!isBoundGuardianActor) {
-    return () => {};
-  }
-
-  let active = true;
-  const deliveredRequestIds = new Set<string>();
-
-  const poll = async (): Promise<void> => {
-    while (active) {
-      try {
-        const prompt = getChannelApprovalPrompt(conversationId);
-        const pending = getApprovalInfoByConversation(conversationId);
-        const info = pending[0];
-        if (prompt && info && !deliveredRequestIds.has(info.requestId)) {
-          deliveredRequestIds.add(info.requestId);
-          const delivered = await deliverGeneratedApprovalPrompt({
-            replyCallbackUrl,
-            chatId: externalChatId,
-            sourceChannel,
-            assistantId: assistantId ?? DAEMON_INTERNAL_ASSISTANT_ID,
-            bearerToken: mintBearerToken(),
-            prompt,
-            uiMetadata: buildApprovalUIMetadata(prompt, info),
-            messageContext: {
-              scenario: 'standard_prompt',
-              toolName: info.toolName,
-              channel: sourceChannel,
-            },
-            approvalCopyGenerator,
-          });
-          if (!delivered) {
-            // Delivery can fail transiently (network or gateway outage).
-            // Keep polling and retry prompt delivery for the same request.
-            deliveredRequestIds.delete(info.requestId);
-          }
-        }
-      } catch (err) {
-        log.warn({ err, conversationId }, 'Pending approval prompt watcher failed');
-      }
-      await delay(PENDING_APPROVAL_POLL_INTERVAL_MS);
-    }
-  };
-
-  void poll();
-  return () => {
-    active = false;
-  };
-}
-
-/**
- * Resolve a human-readable guardian name from the guardian binding metadata.
- * Returns the display name, username (prefixed with @), or undefined if
- * no name is available.
- */
-function resolveGuardianDisplayName(
-  assistantId: string,
-  sourceChannel: ChannelId,
-): string | undefined {
-  const binding = getGuardianBinding(assistantId, sourceChannel);
-  if (!binding?.metadataJson) return undefined;
-  try {
-    const parsed = JSON.parse(binding.metadataJson) as Record<string, unknown>;
-    if (typeof parsed.displayName === 'string' && parsed.displayName.trim().length > 0) {
-      return parsed.displayName.trim();
-    }
-    if (typeof parsed.username === 'string' && parsed.username.trim().length > 0) {
-      return `@${parsed.username.trim()}`;
-    }
-  } catch {
-    // ignore malformed metadata
-  }
-  return undefined;
-}
-
-/**
- * Start a poller that sends a one-shot "waiting for guardian approval" message
- * to the trusted contact when a confirmation_request enters guardian approval
- * wait. Deduplicates by requestId so each request only produces one message.
- *
- * Only activates for trusted-contact actors with a resolvable guardian route.
- */
-function startTrustedContactApprovalNotifier(params: {
-  conversationId: string;
-  sourceChannel: ChannelId;
-  externalChatId: string;
-  guardianTrustClass: GuardianContext['trustClass'];
-  guardianExternalUserId?: string;
-  replyCallbackUrl: string;
-  mintBearerToken: () => string;
-  assistantId?: string;
-}): () => void {
-  const {
-    conversationId,
-    sourceChannel,
-    externalChatId,
-    guardianTrustClass,
-    guardianExternalUserId,
-    replyCallbackUrl,
-    mintBearerToken,
-    assistantId,
-  } = params;
-
-  // Only notify trusted contacts who have a resolvable guardian route.
-  if (guardianTrustClass !== 'trusted_contact' || !guardianExternalUserId) {
-    return () => {};
-  }
-
-  let active = true;
-
-  const poll = async (): Promise<void> => {
-    while (active) {
-      try {
-        const pending = getApprovalInfoByConversation(conversationId);
-        const info = pending[0];
-
-        // Clean up resolved requests from the module-level dedupe map.
-        // Only remove entries that belong to THIS conversation — other
-        // conversations' pollers own their own entries. Without this
-        // scoping, concurrent pollers would evict each other's request
-        // IDs and cause duplicate notifications.
-        const currentPendingIds = new Set(pending.map(p => p.requestId));
-        for (const [rid, cid] of globalNotifiedApprovalRequestIds) {
-          if (cid === conversationId && !currentPendingIds.has(rid)) {
-            globalNotifiedApprovalRequestIds.delete(rid);
-          }
-        }
-
-        if (info && !globalNotifiedApprovalRequestIds.has(info.requestId)) {
-          globalNotifiedApprovalRequestIds.set(info.requestId, conversationId);
-          const guardianName = resolveGuardianDisplayName(
-            assistantId ?? DAEMON_INTERNAL_ASSISTANT_ID,
-            sourceChannel,
-          ) ?? resolveUserReference();
-          const waitingText = `Waiting for ${guardianName}'s approval...`;
-          try {
-            await deliverChannelReply(replyCallbackUrl, {
-              chatId: externalChatId,
-              text: waitingText,
-              assistantId: assistantId ?? DAEMON_INTERNAL_ASSISTANT_ID,
-            }, mintBearerToken());
-          } catch (err) {
-            log.warn({ err, conversationId }, 'Failed to deliver trusted-contact pending-approval notification');
-            // Remove from notified set so delivery is retried on next poll
-            globalNotifiedApprovalRequestIds.delete(info.requestId);
-          }
-        }
-      } catch (err) {
-        log.warn({ err, conversationId }, 'Trusted-contact approval notifier poll failed');
-      }
-      await delay(PENDING_APPROVAL_POLL_INTERVAL_MS);
-    }
-  };
-
-  void poll();
-  return () => {
-    active = false;
-
-    // Evict all dedupe entries owned by this conversation so the
-    // module-level map doesn't grow unboundedly after the poller stops.
-    for (const [rid, cid] of globalNotifiedApprovalRequestIds) {
-      if (cid === conversationId) {
-        globalNotifiedApprovalRequestIds.delete(rid);
-      }
-    }
-  };
-}
-
-function processChannelMessageInBackground(params: BackgroundProcessingParams): void {
-  const {
-    processMessage,
-    conversationId,
-    eventId,
-    content,
-    attachmentIds,
-    sourceChannel,
-    sourceInterface,
-    externalChatId,
-    guardianCtx,
-    metadataHints,
-    metadataUxBrief,
-    replyCallbackUrl,
-    mintBearerToken,
-    assistantId,
-    approvalCopyGenerator,
-    commandIntent,
-    sourceLanguageCode,
-  } = params;
-
-  (async () => {
-    const typingCallbackUrl = shouldEmitTelegramTyping(sourceChannel, replyCallbackUrl)
-      ? replyCallbackUrl
-      : undefined;
-    const stopTypingHeartbeat = typingCallbackUrl
-      ? startTelegramTypingHeartbeat(typingCallbackUrl, externalChatId, mintBearerToken, assistantId)
-      : undefined;
-    const stopApprovalWatcher = replyCallbackUrl
-      ? startPendingApprovalPromptWatcher({
-        conversationId,
-        sourceChannel,
-        externalChatId,
-        guardianTrustClass: guardianCtx.trustClass,
-        guardianExternalUserId: guardianCtx.guardianExternalUserId,
-        requesterExternalUserId: guardianCtx.requesterExternalUserId,
-        replyCallbackUrl,
-        mintBearerToken,
-        assistantId,
-        approvalCopyGenerator,
-      })
-      : undefined;
-    const stopTcApprovalNotifier = replyCallbackUrl
-      ? startTrustedContactApprovalNotifier({
-        conversationId,
-        sourceChannel,
-        externalChatId,
-        guardianTrustClass: guardianCtx.trustClass,
-        guardianExternalUserId: guardianCtx.guardianExternalUserId,
-        replyCallbackUrl,
-        mintBearerToken,
-        assistantId,
-      })
-      : undefined;
-
-    try {
-      const cmdIntent = commandIntent && typeof commandIntent.type === 'string'
-        ? { type: commandIntent.type as string, ...(typeof commandIntent.payload === 'string' ? { payload: commandIntent.payload } : {}), ...(sourceLanguageCode ? { languageCode: sourceLanguageCode } : {}) }
-        : undefined;
-      const { messageId: userMessageId } = await processMessage(
-        conversationId,
-        content,
-        attachmentIds,
-        {
-          transport: {
-            channelId: sourceChannel,
-            hints: metadataHints.length > 0 ? metadataHints : undefined,
-            uxBrief: metadataUxBrief,
-          },
-          assistantId,
-          guardianContext: guardianCtx,
-          isInteractive: resolveRoutingState(guardianCtx).promptWaitingAllowed,
-          ...(cmdIntent ? { commandIntent: cmdIntent } : {}),
-        },
-        sourceChannel,
-        sourceInterface,
-      );
-      channelDeliveryStore.linkMessage(eventId, userMessageId);
-      channelDeliveryStore.markProcessed(eventId);
-
-      if (replyCallbackUrl) {
-        await deliverReplyViaCallback(
-          conversationId,
-          externalChatId,
-          replyCallbackUrl,
-          mintBearerToken(),
-          assistantId,
-          {
-            onSegmentDelivered: (count) =>
-              channelDeliveryStore.updateDeliveredSegmentCount(eventId, count),
-          },
-        );
-      }
-    } catch (err) {
-      log.error({ err, conversationId }, 'Background channel message processing failed');
-      channelDeliveryStore.recordProcessingFailure(eventId, err);
-    } finally {
-      stopTypingHeartbeat?.();
-      stopApprovalWatcher?.();
-      stopTcApprovalNotifier?.();
-    }
-  })();
-}
-
-// ---------------------------------------------------------------------------
-// Bootstrap verification Telegram delivery helper
-// ---------------------------------------------------------------------------
-
-/**
- * Deliver a verification Telegram message during bootstrap.
- * Fire-and-forget with error logging and a single self-retry on failure.
- */
-function deliverBootstrapVerificationTelegram(
-  chatId: string,
-  text: string,
-  assistantId: string,
-): void {
-  const attemptDelivery = async (): Promise<boolean> => {
-    const gatewayUrl = getGatewayInternalBaseUrl();
-    const bearerToken = mintDaemonDeliveryToken();
-    const url = `${gatewayUrl}/deliver/telegram`;
-    const resp = await fetch(url, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${bearerToken}`,
-      },
-      body: JSON.stringify({ chatId, text, assistantId }),
-    });
-    if (!resp.ok) {
-      const body = await resp.text().catch(() => '<unreadable>');
-      log.error({ chatId, assistantId, status: resp.status, body }, 'Gateway /deliver/telegram failed for bootstrap verification');
-      return false;
-    }
-    return true;
-  };
-
-  (async () => {
-    try {
-      const delivered = await attemptDelivery();
-      if (delivered) {
-        log.info({ chatId, assistantId }, 'Bootstrap verification Telegram message delivered');
-        return;
-      }
-    } catch (err) {
-      log.error({ err, chatId, assistantId }, 'Failed to deliver bootstrap verification Telegram message');
-    }
-
-    // Self-retry after a short delay. The gateway deduplicates inbound
-    // webhooks after a successful forward, so duplicate retries from the
-    // user re-clicking the deep link may never arrive. This ensures
-    // delivery is re-attempted even without a gateway duplicate.
-    setTimeout(async () => {
-      try {
-        const delivered = await attemptDelivery();
-        if (delivered) {
-          log.info({ chatId, assistantId }, 'Bootstrap verification Telegram message delivered on self-retry');
-        } else {
-          log.error({ chatId, assistantId }, 'Bootstrap verification Telegram self-retry also failed');
-        }
-      } catch (retryErr) {
-        log.error({ err: retryErr, chatId, assistantId }, 'Bootstrap verification Telegram self-retry threw; giving up');
-      }
-    }, 3000);
-  })();
-}