@vellumai/assistant 0.3.2 → 0.3.4

package/src/runtime/routes/channel-routes.ts

@@ -53,27 +53,34 @@ const log = getLogger('runtime-http');
 
 /**
  * Header name used by the gateway to prove a request originated from it.
- * The gateway sets this to the shared bearer token; the runtime validates
- * it using constant-time comparison. Requests to `/channels/inbound`
- * that lack a valid gateway-origin proof are rejected with 403.
+ * The gateway sends a dedicated gateway-origin secret (or the bearer token
+ * as fallback). The runtime validates it using constant-time comparison.
+ * Requests to `/channels/inbound` that lack a valid proof are rejected with 403.
  */
 export const GATEWAY_ORIGIN_HEADER = 'X-Gateway-Origin';
 
 /**
  * Validate that the request carries a valid gateway-origin proof.
- * Returns true when the header value matches the expected bearer token
- * using constant-time comparison to prevent timing attacks.
+ * Uses constant-time comparison to prevent timing attacks.
  *
- * When no bearer token is configured (e.g., local dev without auth),
- * gateway-origin validation is skipped — the server is already
- * unauthenticated, so there is no shared secret to verify against.
+ * The `gatewayOriginSecret` parameter is the dedicated secret configured
+ * via `RUNTIME_GATEWAY_ORIGIN_SECRET`. When set, only this value is
+ * accepted. When not set, the function falls back to `bearerToken` for
+ * backward compatibility. When neither is configured (local dev), validation
+ * is skipped entirely.
  */
-export function verifyGatewayOrigin(req: Request, bearerToken?: string): boolean {
-  if (!bearerToken) return true; // No shared secret configured — skip validation
+export function verifyGatewayOrigin(
+  req: Request,
+  bearerToken?: string,
+  gatewayOriginSecret?: string,
+): boolean {
+  // Determine the expected secret: prefer dedicated secret, fall back to bearer token
+  const expectedSecret = gatewayOriginSecret ?? bearerToken;
+  if (!expectedSecret) return true; // No shared secret configured — skip validation
   const provided = req.headers.get(GATEWAY_ORIGIN_HEADER);
   if (!provided) return false;
   const a = Buffer.from(provided);
-  const b = Buffer.from(bearerToken);
+  const b = Buffer.from(expectedSecret);
   if (a.length !== b.length) return false;
   return timingSafeEqual(a, b);
 }
@@ -84,6 +91,9 @@ export function verifyGatewayOrigin(req: Request, bearerToken?: string): boolean
 
 export type ActorRole = 'guardian' | 'non-guardian' | 'unverified_channel';
 
+/** Sub-reason for `unverified_channel` denials. */
+export type DenialReason = 'no_binding' | 'no_identity';
+
 export interface GuardianContext {
   actorRole: ActorRole;
   /** The guardian's delivery chat ID (from the guardian binding). */
@@ -96,6 +106,8 @@ export interface GuardianContext {
   requesterExternalUserId?: string;
   /** The requester's chat ID. */
   requesterChatId?: string;
+  /** Sub-reason when actorRole is 'unverified_channel'. */
+  denialReason?: DenialReason;
 }
 
 /** Guardian approval request expiry (30 minutes). */
@@ -115,12 +127,21 @@ function effectivePromptText(
   return plainTextFallback;
 }
 
-// ---------------------------------------------------------------------------
-// Feature flag
-// ---------------------------------------------------------------------------
+/**
+ * Build contextual deny guidance for guardian-gated auto-deny paths.
+ * This is passed through the confirmation pipeline so the assistant can
+ * produce a single, user-facing message with next steps.
+ */
+function buildGuardianDenyContext(
+  toolName: string,
+  denialReason: DenialReason,
+  sourceChannel: string,
+): string {
+  if (denialReason === 'no_identity') {
+    return `Permission denied: the action "${toolName}" requires guardian approval, but your identity could not be verified on ${sourceChannel}. Do not retry yet. Explain this clearly, ask the user to message from a verifiable direct account/chat, and then retry after identity is available.`;
+  }
 
-export function isChannelApprovalsEnabled(): boolean {
-  return process.env.CHANNEL_APPROVALS_ENABLED === 'true';
+  return `Permission denied: the action "${toolName}" requires guardian approval, but no guardian is configured for this ${sourceChannel} channel. Do not retry yet. Explain that a guardian must be set up first. The guardian/admin should open the Channels section in Settings and click "Verify Guardian", or ask the assistant to set up guardian verification. The setup flow will provide a verification token to send as /guardian_verify <token> in the ${sourceChannel} chat.`;
 }
 
 // ---------------------------------------------------------------------------
@@ -142,7 +163,7 @@ function parseCallbackData(data: string): ApprovalDecisionResult | null {
   return { action: action as ApprovalAction, source: 'telegram_button', runId };
 }
 
-export async function handleDeleteConversation(req: Request): Promise<Response> {
+export async function handleDeleteConversation(req: Request, assistantId: string = 'self'): Promise<Response> {
   const body = await req.json() as {
     sourceChannel?: string;
     externalChatId?: string;
@@ -157,9 +178,22 @@ export async function handleDeleteConversation(req: Request): Promise<Response>
     return Response.json({ error: 'externalChatId is required' }, { status: 400 });
   }
 
-  const conversationKey = `${sourceChannel}:${externalChatId}`;
-  deleteConversationKey(conversationKey);
-  externalConversationStore.deleteBindingByChannelChat(sourceChannel, externalChatId);
+  // Delete the assistant-scoped key unconditionally. The legacy key is
+  // canonical for the self assistant and must not be deleted from non-self
+  // routes, otherwise a non-self reset can accidentally reset self state.
+  const legacyKey = `${sourceChannel}:${externalChatId}`;
+  const scopedKey = `asst:${assistantId}:${sourceChannel}:${externalChatId}`;
+  deleteConversationKey(scopedKey);
+  if (assistantId === 'self') {
+    deleteConversationKey(legacyKey);
+  }
+  // external_conversation_bindings is currently assistant-agnostic
+  // (unique by sourceChannel + externalChatId). Restrict mutations to the
+  // canonical self-assistant route so multi-assistant legacy routes do not
+  // clobber each other's bindings.
+  if (assistantId === 'self') {
+    externalConversationStore.deleteBindingByChannelChat(sourceChannel, externalChatId);
+  }
 
   return Response.json({ ok: true });
 }
@@ -169,11 +203,13 @@ export async function handleChannelInbound(
   processMessage?: MessageProcessor,
   bearerToken?: string,
   runOrchestrator?: RunOrchestrator,
+  assistantId: string = 'self',
+  gatewayOriginSecret?: string,
 ): Promise<Response> {
   // Reject requests that lack valid gateway-origin proof. This ensures
   // channel inbound messages can only arrive via the gateway (which
   // performs webhook-level verification) and not via direct HTTP calls.
-  if (!verifyGatewayOrigin(req, bearerToken)) {
+  if (!verifyGatewayOrigin(req, bearerToken, gatewayOriginSecret)) {
     log.warn('Rejected channel inbound request: missing or invalid gateway-origin proof');
     return Response.json(
       { error: 'Forbidden: missing gateway-origin proof', code: 'GATEWAY_ORIGIN_REQUIRED' },
@@ -258,7 +294,7 @@ export async function handleChannelInbound(
       sourceChannel,
       externalChatId,
       externalMessageId,
-      { sourceMessageId },
+      { sourceMessageId, assistantId },
     );
 
     if (editResult.duplicate) {
@@ -285,7 +321,7 @@ export async function handleChannelInbound(
       if (original) break;
       if (attempt < EDIT_LOOKUP_RETRIES) {
         log.info(
-          { assistantId: "self", sourceMessageId, attempt: attempt + 1, maxAttempts: EDIT_LOOKUP_RETRIES },
+          { 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));
@@ -295,12 +331,12 @@ export async function handleChannelInbound(
     if (original) {
       conversationStore.updateMessageContent(original.messageId, content ?? '');
       log.info(
-        { assistantId: "self", sourceMessageId, messageId: original.messageId },
+        { assistantId, sourceMessageId, messageId: original.messageId },
         'Updated message content from edited_message',
       );
     } else {
       log.warn(
-        { assistantId: "self", sourceChannel, externalChatId, sourceMessageId },
+        { assistantId, sourceChannel, externalChatId, sourceMessageId },
         'Could not find original message for edit after retries, ignoring',
       );
     }
@@ -317,18 +353,22 @@ export async function handleChannelInbound(
     sourceChannel,
     externalChatId,
     externalMessageId,
-    { sourceMessageId },
+    { sourceMessageId, assistantId },
   );
 
-  // Upsert external conversation binding with sender metadata
-  externalConversationStore.upsertBinding({
-    conversationId: result.conversationId,
-    sourceChannel,
-    externalChatId,
-    externalUserId: body.senderExternalUserId ?? null,
-    displayName: body.senderName ?? null,
-    username: body.senderUsername ?? null,
-  });
+  // external_conversation_bindings is assistant-agnostic. Restrict writes to
+  // self so assistant-scoped legacy routes do not overwrite each other's
+  // channel binding metadata for the same chat.
+  if (assistantId === 'self') {
+    externalConversationStore.upsertBinding({
+      conversationId: result.conversationId,
+      sourceChannel,
+      externalChatId,
+      externalUserId: body.senderExternalUserId ?? null,
+      displayName: body.senderName ?? null,
+      username: body.senderUsername ?? null,
+    });
+  }
 
   const metadataHintsRaw = sourceMetadata?.hints;
   const metadataHints = Array.isArray(metadataHintsRaw)
@@ -351,7 +391,7 @@ export async function handleChannelInbound(
     const token = trimmedContent.slice('/guardian_verify '.length).trim();
     if (token.length > 0) {
       const verifyResult = validateAndConsumeChallenge(
-        'self',
+        assistantId,
         sourceChannel,
         token,
         body.senderExternalUserId,
@@ -366,6 +406,7 @@ export async function handleChannelInbound(
         await deliverChannelReply(replyCallbackUrl, {
           chatId: externalChatId,
           text: replyText,
+          assistantId,
         }, bearerToken);
       } catch (err) {
         log.error({ err, externalChatId }, 'Failed to deliver guardian verification reply');
@@ -384,11 +425,13 @@ export async function handleChannelInbound(
   // Determine whether the sender is the guardian for this channel.
   // When a guardian binding exists, non-guardian actors get stricter
   // side-effect controls and their approvals route to the guardian's chat.
+  //
+  // Guardian actor-role resolution always runs.
   let guardianCtx: GuardianContext = { actorRole: 'guardian' };
-  if (isChannelApprovalsEnabled() && body.senderExternalUserId) {
-    const senderIsGuardian = isGuardian('self', sourceChannel, body.senderExternalUserId);
+  if (body.senderExternalUserId) {
+    const senderIsGuardian = isGuardian(assistantId, sourceChannel, body.senderExternalUserId);
     if (!senderIsGuardian) {
-      const binding = getGuardianBinding('self', sourceChannel);
+      const binding = getGuardianBinding(assistantId, sourceChannel);
       if (binding) {
         const requesterLabel = body.senderUsername
           ? `@${body.senderUsername}`
@@ -406,16 +449,27 @@ export async function handleChannelInbound(
         // unverified. Sensitive actions will be auto-denied (fail-closed).
         guardianCtx = {
           actorRole: 'unverified_channel',
+          denialReason: 'no_binding',
           requesterExternalUserId: body.senderExternalUserId,
           requesterChatId: externalChatId,
         };
       }
     }
+  } else {
+    // No sender identity available — treat as unverified and fail closed.
+    // Multi-actor channels must not grant default guardian permissions when
+    // the inbound actor cannot be identified.
+    guardianCtx = {
+      actorRole: 'unverified_channel',
+      denialReason: 'no_identity',
+      requesterExternalUserId: undefined,
+      requesterChatId: externalChatId,
+    };
   }
 
-  // ── Approval interception (gated behind feature flag) ──
+  // ── Approval interception ──
+  // Keep this active whenever orchestrator + callback context are available.
   if (
-    isChannelApprovalsEnabled() &&
     runOrchestrator &&
     replyCallbackUrl &&
     !result.duplicate
@@ -431,6 +485,7 @@ export async function handleChannelInbound(
       bearerToken,
       orchestrator: runOrchestrator,
       guardianCtx,
+      assistantId,
     });
 
     if (approvalResult.handled) {
@@ -470,6 +525,7 @@ export async function handleChannelInbound(
       senderExternalUserId: body.senderExternalUserId,
       senderUsername: body.senderUsername,
       replyCallbackUrl,
+      assistantId,
     });
 
     const contentToCheck = content ?? '';
@@ -485,13 +541,15 @@ export async function handleChannelInbound(
       throw new IngressBlockedError(ingressCheck.userNotice!, ingressCheck.detectedTypes);
     }
 
-    // When approval flow is enabled and we have an orchestrator, use the
-    // orchestrator-backed path which properly intercepts confirmation_request
-    // events and sends proactive approval prompts to the channel.
-    const useApprovalPath =
-      isChannelApprovalsEnabled() && runOrchestrator && replyCallbackUrl;
+    // Use the approval-aware orchestrator path whenever orchestration and a
+    // callback delivery target are available. This keeps approval handling
+    // consistent across all channels and avoids silent prompt timeouts.
+    const useApprovalPath = Boolean(
+      runOrchestrator &&
+      replyCallbackUrl,
+    );
 
-    if (useApprovalPath) {
+    if (useApprovalPath && runOrchestrator && replyCallbackUrl) {
       processChannelMessageWithApprovals({
         orchestrator: runOrchestrator,
         conversationId: result.conversationId,
@@ -503,6 +561,7 @@ export async function handleChannelInbound(
         replyCallbackUrl,
         bearerToken,
         guardianCtx,
+        assistantId,
       });
     } else {
       // Fire-and-forget: process the message and deliver the reply in the background.
@@ -519,6 +578,7 @@ export async function handleChannelInbound(
         metadataUxBrief,
         replyCallbackUrl,
         bearerToken,
+        assistantId,
       });
     }
   }
@@ -542,6 +602,7 @@ interface BackgroundProcessingParams {
   metadataUxBrief?: string;
   replyCallbackUrl?: string;
   bearerToken?: string;
+  assistantId?: string;
 }
 
 function processChannelMessageInBackground(params: BackgroundProcessingParams): void {
@@ -557,6 +618,7 @@ function processChannelMessageInBackground(params: BackgroundProcessingParams):
     metadataUxBrief,
     replyCallbackUrl,
     bearerToken,
+    assistantId,
   } = params;
 
   (async () => {
@@ -578,7 +640,13 @@ function processChannelMessageInBackground(params: BackgroundProcessingParams):
       channelDeliveryStore.markProcessed(eventId);
 
       if (replyCallbackUrl) {
-        await deliverReplyViaCallback(conversationId, externalChatId, replyCallbackUrl, bearerToken);
+        await deliverReplyViaCallback(
+          conversationId,
+          externalChatId,
+          replyCallbackUrl,
+          bearerToken,
+          assistantId,
+        );
       }
     } catch (err) {
       log.error({ err, conversationId }, 'Background channel message processing failed');
@@ -599,6 +667,22 @@ const RUN_POLL_MAX_WAIT_MS = 300_000; // 5 minutes
 const POST_DECISION_POLL_INTERVAL_MS = 500;
 const POST_DECISION_POLL_MAX_WAIT_MS = RUN_POLL_MAX_WAIT_MS;
 
+/**
+ * Override the poll max-wait for tests. When set, used in place of
+ * RUN_POLL_MAX_WAIT_MS so tests can exercise timeout paths without
+ * waiting 5 minutes.
+ */
+let testPollMaxWaitOverride: number | null = null;
+
+/** @internal — test-only: set an override for the poll max-wait. */
+export function _setTestPollMaxWait(ms: number | null): void {
+  testPollMaxWaitOverride = ms;
+}
+
+function getEffectivePollMaxWait(): number {
+  return testPollMaxWaitOverride ?? RUN_POLL_MAX_WAIT_MS;
+}
+
 interface ApprovalProcessingParams {
   orchestrator: RunOrchestrator;
   conversationId: string;
@@ -610,6 +694,7 @@ interface ApprovalProcessingParams {
   replyCallbackUrl: string;
   bearerToken?: string;
   guardianCtx: GuardianContext;
+  assistantId: string;
 }
 
 /**
@@ -636,6 +721,7 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
     replyCallbackUrl,
     bearerToken,
     guardianCtx,
+    assistantId,
   } = params;
 
   const isNonGuardian = guardianCtx.actorRole === 'non-guardian';
@@ -656,9 +742,18 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
       // Poll the run until it reaches a terminal state, delivering approval
       // prompts when it transitions to needs_confirmation.
       const startTime = Date.now();
+      const pollMaxWait = getEffectivePollMaxWait();
       let lastStatus = run.status;
-
-      while (Date.now() - startTime < RUN_POLL_MAX_WAIT_MS) {
+      // Track whether a post-decision delivery path is guaranteed for this
+      // run. Set to true only when the approval prompt is successfully
+      // delivered (guardian or standard path), meaning
+      // handleApprovalInterception will schedule schedulePostDecisionDelivery
+      // when a decision arrives. Auto-deny paths (unverified channel, prompt
+      // delivery failures) do NOT set this flag because no post-decision
+      // delivery is scheduled in those cases.
+      let hasPostDecisionDelivery = false;
+
+      while (Date.now() - startTime < pollMaxWait) {
         await new Promise((resolve) => setTimeout(resolve, RUN_POLL_INTERVAL_MS));
 
         const current = orchestrator.getRun(run.id);
@@ -668,16 +763,17 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
           const pending = getPendingConfirmationsByConversation(conversationId);
 
           if (isUnverifiedChannel && pending.length > 0) {
-            // No guardian binding — auto-deny the sensitive action (fail-closed).
-            handleChannelDecision(conversationId, { action: 'reject', source: 'plain_text' }, orchestrator);
-            try {
-              await deliverChannelReply(replyCallbackUrl, {
-                chatId: externalChatId,
-                text: `The action "${pending[0].toolName}" requires guardian approval, but no guardian has been set up for this channel. The action has been denied. Please ask an administrator to configure a guardian.`,
-              }, bearerToken);
-            } catch (err) {
-              log.error({ err, runId: run.id }, 'Failed to deliver unverified-channel denial notice');
-            }
+            // Unverified channel — auto-deny the sensitive action (fail-closed).
+            handleChannelDecision(
+              conversationId,
+              { action: 'reject', source: 'plain_text' },
+              orchestrator,
+              buildGuardianDenyContext(
+                pending[0].toolName,
+                guardianCtx.denialReason ?? 'no_binding',
+                sourceChannel,
+              ),
+            );
           } else if (isNonGuardian && guardianCtx.guardianChatId && pending.length > 0) {
             // Non-guardian actor: route the approval prompt to the guardian's chat
             const guardianPrompt = buildGuardianApprovalPrompt(
@@ -691,6 +787,7 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
             const approvalReqRecord = createApprovalRequest({
               runId: run.id,
               conversationId,
+              assistantId,
               channel: sourceChannel,
               requesterExternalUserId: guardianCtx.requesterExternalUserId ?? '',
               requesterChatId: guardianCtx.requesterChatId ?? externalChatId,
@@ -713,9 +810,11 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
                 guardianCtx.guardianChatId,
                 guardianText,
                 uiMetadata,
+                assistantId,
                 bearerToken,
               );
               guardianNotified = true;
+              hasPostDecisionDelivery = true;
             } catch (err) {
               log.error({ err, runId: run.id }, 'Failed to deliver guardian approval prompt');
               // Deny the approval and the underlying run — fail-closed. If
@@ -728,6 +827,7 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
                 await deliverChannelReply(replyCallbackUrl, {
                   chatId: guardianCtx.requesterChatId ?? externalChatId,
                   text: `Your request to run "${pending[0].toolName}" could not be sent to the guardian for approval. The action has been denied.`,
+                  assistantId,
                 }, bearerToken);
               } catch (notifyErr) {
                 log.error({ err: notifyErr, runId: run.id }, 'Failed to notify requester of guardian delivery failure');
@@ -740,6 +840,7 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
                 await deliverChannelReply(replyCallbackUrl, {
                   chatId: guardianCtx.requesterChatId ?? externalChatId,
                   text: `Your request to run "${pending[0].toolName}" has been sent to the guardian for approval.`,
+                  assistantId,
                 }, bearerToken);
               } catch (err) {
                 log.error({ err, runId: run.id }, 'Failed to notify requester of pending guardian approval');
@@ -762,10 +863,19 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
                   externalChatId,
                   promptTextForChannel,
                   uiMetadata,
+                  assistantId,
                   bearerToken,
                 );
+                hasPostDecisionDelivery = true;
               } catch (err) {
-                log.error({ err, runId: run.id }, 'Failed to deliver approval prompt for channel run');
+                // Fail-closed: if we cannot deliver the approval prompt, the
+                // user will never see it and the run would hang indefinitely
+                // in needs_confirmation. Auto-deny to avoid silent wait states.
+                log.error(
+                  { err, runId: run.id, conversationId },
+                  'Failed to deliver standard approval prompt; auto-denying (fail-closed)',
+                );
+                handleChannelDecision(conversationId, { action: 'reject', source: 'plain_text' }, orchestrator);
               }
             }
           }
@@ -792,8 +902,25 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
 
         channelDeliveryStore.markProcessed(eventId);
 
-        // Deliver the final assistant reply to the requester's chat
-        await deliverReplyViaCallback(conversationId, externalChatId, replyCallbackUrl, bearerToken);
+        // Deliver the final assistant reply exactly once. The post-decision
+        // poll in schedulePostDecisionDelivery races with this path; the
+        // claimRunDelivery guard ensures only the winner sends the reply.
+        // If delivery fails, release the claim so the other poller can retry
+        // rather than permanently losing the reply.
+        if (channelDeliveryStore.claimRunDelivery(run.id)) {
+          try {
+            await deliverReplyViaCallback(
+              conversationId,
+              externalChatId,
+              replyCallbackUrl,
+              bearerToken,
+              assistantId,
+            );
+          } catch (deliveryErr) {
+            channelDeliveryStore.resetRunDeliveryClaim(run.id);
+            throw deliveryErr;
+          }
+        }
 
         // If this was a non-guardian run that went through guardian approval,
         // also notify the guardian's chat about the outcome.
@@ -805,25 +932,41 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
             updateApprovalDecision(approvalReq.id, { status: outcomeStatus });
           }
         }
-      } else if (finalRun?.status === 'needs_confirmation') {
-        // The run is waiting for an approval decision but the poll window has
-        // elapsed. Mark the event as processed rather than failed — the run
-        // will resume when the user clicks approve/reject, and
-        // `handleApprovalInterception` will deliver the reply via its own
-        // post-decision poll. Marking it failed would cause the generic retry
-        // sweep to replay through `processMessage`, which throws "Session is
+      } else if (
+        finalRun?.status === 'needs_confirmation' ||
+        (hasPostDecisionDelivery && finalRun?.status === 'running')
+      ) {
+        // The run is either still waiting for an approval decision or was
+        // recently approved and has resumed execution. In both cases, mark
+        // the event as processed rather than failed:
+        //
+        // - needs_confirmation: the run will resume when the user clicks
+        //   approve/reject, and `handleApprovalInterception` will deliver
+        //   the reply via `schedulePostDecisionDelivery`.
+        //
+        // - running (after successful prompt delivery): an approval was
+        //   applied near the poll deadline and the run resumed but hasn't
+        //   reached terminal state yet. `handleApprovalInterception` has
+        //   already scheduled post-decision delivery, so the final reply
+        //   will be delivered. This condition is only true when the approval
+        //   prompt was actually delivered (not in auto-deny paths), ensuring
+        //   we don't suppress retry/dead-letter for cases where no
+        //   post-decision delivery path exists.
+        //
+        // Marking either state as failed would cause the generic retry sweep
+        // to replay through `processMessage`, which throws "Session is
         // already processing a message" and dead-letters a valid conversation.
         log.warn(
-          { runId: run.id, status: finalRun.status, conversationId },
-          'Approval-path poll loop timed out while run awaits approval decision; marking event as processed',
+          { runId: run.id, status: finalRun.status, conversationId, hasPostDecisionDelivery },
+          'Approval-path poll loop timed out while run is in approval-related state; marking event as processed',
         );
         channelDeliveryStore.markProcessed(eventId);
       } else {
-        // The run is in a non-terminal, non-approval state (e.g. running,
-        // needs_secret, or disappeared). Record a processing failure so the
-        // retry/dead-letter machinery can handle it.
+        // The run is in a non-terminal, non-approval state (e.g. running
+        // without prior approval, needs_secret, or disappeared). Record a
+        // processing failure so the retry/dead-letter machinery can handle it.
         const timeoutErr = new Error(
-          `Approval poll timeout: run did not reach terminal state within ${RUN_POLL_MAX_WAIT_MS}ms (status: ${finalRun?.status ?? 'null'})`,
+          `Approval poll timeout: run did not reach terminal state within ${pollMaxWait}ms (status: ${finalRun?.status ?? 'null'})`,
         );
         log.warn(
           { runId: run.id, status: finalRun?.status, conversationId },
@@ -853,6 +996,7 @@ interface ApprovalInterceptionParams {
   bearerToken?: string;
   orchestrator: RunOrchestrator;
   guardianCtx: GuardianContext;
+  assistantId: string;
 }
 
 interface ApprovalInterceptionResult {
@@ -884,6 +1028,7 @@ async function handleApprovalInterception(
     bearerToken,
     orchestrator,
     guardianCtx,
+    assistantId,
   } = params;
 
   // ── Guardian approval decision path ──
@@ -909,19 +1054,20 @@ async function handleApprovalInterception(
     // the decision resolves to exactly the right approval even when
     // multiple approvals target the same guardian chat.
     let guardianApproval = decision?.runId
-      ? getPendingApprovalByRunAndGuardianChat(decision.runId, sourceChannel, externalChatId)
+      ? getPendingApprovalByRunAndGuardianChat(decision.runId, sourceChannel, externalChatId, assistantId)
       : null;
 
     // For plain-text decisions (no run ID), check how many pending
     // approvals exist for this guardian chat. If there are multiple,
     // the guardian must use buttons to disambiguate.
     if (!guardianApproval && decision && !decision.runId) {
-      const allPending = getAllPendingApprovalsByGuardianChat(sourceChannel, externalChatId);
+      const allPending = getAllPendingApprovalsByGuardianChat(sourceChannel, externalChatId, assistantId);
       if (allPending.length > 1) {
         try {
           await deliverChannelReply(replyCallbackUrl, {
             chatId: externalChatId,
             text: `You have ${allPending.length} pending approval requests. Please use the approval buttons to respond to a specific request.`,
+            assistantId,
           }, bearerToken);
         } catch (err) {
           log.error({ err, externalChatId }, 'Failed to deliver disambiguation notice');
@@ -936,7 +1082,7 @@ async function handleApprovalInterception(
     // Fall back to the single-result lookup for non-decision messages
     // (reminder path) or when the scoped lookup found nothing.
     if (!guardianApproval && !decision) {
-      guardianApproval = getPendingApprovalByGuardianChat(sourceChannel, externalChatId);
+      guardianApproval = getPendingApprovalByGuardianChat(sourceChannel, externalChatId, assistantId);
     }
 
     if (guardianApproval) {
@@ -954,6 +1100,7 @@ async function handleApprovalInterception(
           await deliverChannelReply(replyCallbackUrl, {
             chatId: externalChatId,
             text: 'Only the verified guardian can approve or deny this request.',
+            assistantId,
           }, bearerToken);
         } catch (err) {
           log.error({ err, externalChatId }, 'Failed to deliver guardian identity rejection notice');
@@ -994,6 +1141,7 @@ async function handleApprovalInterception(
             await deliverChannelReply(replyCallbackUrl, {
               chatId: guardianApproval.requesterChatId,
               text: outcomeText,
+              assistantId,
             }, bearerToken);
           } catch (err) {
             log.error({ err, conversationId: guardianApproval.conversationId }, 'Failed to notify requester of guardian decision');
@@ -1009,6 +1157,7 @@ async function handleApprovalInterception(
               guardianApproval.requesterChatId,
               replyCallbackUrl,
               bearerToken,
+              assistantId,
             );
           }
         }
@@ -1036,6 +1185,7 @@ async function handleApprovalInterception(
             externalChatId,
             reminderText,
             uiMetadata,
+            assistantId,
             bearerToken,
           );
         } catch (err) {
@@ -1045,30 +1195,37 @@ async function handleApprovalInterception(
 
       return { handled: true, type: 'reminder_sent' };
     }
-
-    // Callback with a run ID that no longer has a pending approval — stale button
-    if (decision?.runId) {
-      return { handled: true, type: 'stale_ignored' };
-    }
   }
 
   // ── Standard approval interception (existing flow) ──
   const pendingPrompt = getChannelApprovalPrompt(conversationId);
   if (!pendingPrompt) return { handled: false };
 
-  // When the sender is from an unverified channel (no guardian binding),
-  // auto-deny any pending confirmation and block self-approval.
+  // When the sender is from an unverified channel, auto-deny any pending
+  // confirmation and block self-approval.
   if (guardianCtx.actorRole === 'unverified_channel') {
     const pending = getPendingConfirmationsByConversation(conversationId);
     if (pending.length > 0) {
-      handleChannelDecision(conversationId, { action: 'reject', source: 'plain_text' }, orchestrator);
-      try {
-        await deliverChannelReply(replyCallbackUrl, {
-          chatId: externalChatId,
-          text: `The action "${pending[0].toolName}" requires guardian approval, but no guardian has been set up for this channel. The action has been denied.`,
-        }, bearerToken);
-      } catch (err) {
-        log.error({ err, conversationId }, 'Failed to deliver unverified-channel denial notice during interception');
+      const denyResult = handleChannelDecision(
+        conversationId,
+        { action: 'reject', source: 'plain_text' },
+        orchestrator,
+        buildGuardianDenyContext(
+          pending[0].toolName,
+          guardianCtx.denialReason ?? 'no_binding',
+          sourceChannel,
+        ),
+      );
+      if (denyResult.applied && denyResult.runId) {
+        schedulePostDecisionDelivery(
+          orchestrator,
+          denyResult.runId,
+          conversationId,
+          externalChatId,
+          replyCallbackUrl,
+          bearerToken,
+          assistantId,
+        );
       }
       return { handled: true, type: 'decision_applied' };
     }
@@ -1086,6 +1243,7 @@ async function handleApprovalInterception(
           await deliverChannelReply(replyCallbackUrl, {
             chatId: externalChatId,
             text: 'Your request is pending guardian approval. Only the verified guardian can approve or deny this request.',
+            assistantId,
           }, bearerToken);
         } catch (err) {
           log.error({ err, conversationId }, 'Failed to deliver guardian-pending notice to requester');
@@ -1112,6 +1270,7 @@ async function handleApprovalInterception(
           await deliverChannelReply(replyCallbackUrl, {
             chatId: externalChatId,
             text: 'Your guardian approval request has expired and the action has been denied. Please try again.',
+            assistantId,
           }, bearerToken);
         } catch (err) {
           log.error({ err, conversationId }, 'Failed to deliver guardian-expiry notice to requester');
@@ -1153,8 +1312,8 @@ async function handleApprovalInterception(
     // Schedule a background poll for run terminal state and deliver the reply.
     // This handles the case where the original poll in
     // processChannelMessageWithApprovals has already exited due to timeout.
-    // If the original poll is still running and delivers first, the duplicate
-    // delivery is acceptable (gateway deduplicates or user sees a repeat).
+    // The claimRunDelivery guard ensures at-most-once delivery when both
+    // pollers race to terminal state.
     if (result.applied && result.runId) {
       schedulePostDecisionDelivery(
         orchestrator,
@@ -1163,6 +1322,7 @@ async function handleApprovalInterception(
         externalChatId,
         replyCallbackUrl,
         bearerToken,
+        assistantId,
       );
     }
 
@@ -1185,6 +1345,7 @@ async function handleApprovalInterception(
         externalChatId,
         reminderText,
         uiMetadata,
+        assistantId,
         bearerToken,
       );
     } catch (err) {
@@ -1201,9 +1362,9 @@ async function handleApprovalInterception(
  * handles the case where the original poll in `processChannelMessageWithApprovals`
  * has already exited due to the 5-minute timeout.
  *
- * If the original poll already delivered the reply, delivering it again is
- * acceptable — the gateway will deduplicate or the user sees a duplicate
- * (better than seeing nothing).
+ * Uses the same `claimRunDelivery` guard as the main poll to guarantee
+ * at-most-once delivery: whichever poller reaches terminal state first
+ * claims the delivery, and the other silently skips it.
  */
 function schedulePostDecisionDelivery(
   orchestrator: RunOrchestrator,
@@ -1212,6 +1373,7 @@ function schedulePostDecisionDelivery(
   externalChatId: string,
   replyCallbackUrl: string,
   bearerToken?: string,
+  assistantId?: string,
 ): void {
   (async () => {
     try {
@@ -1221,7 +1383,20 @@ function schedulePostDecisionDelivery(
         const current = orchestrator.getRun(runId);
         if (!current) break;
         if (current.status === 'completed' || current.status === 'failed') {
-          await deliverReplyViaCallback(conversationId, externalChatId, replyCallbackUrl, bearerToken);
+          if (channelDeliveryStore.claimRunDelivery(runId)) {
+            try {
+              await deliverReplyViaCallback(
+                conversationId,
+                externalChatId,
+                replyCallbackUrl,
+                bearerToken,
+                assistantId,
+              );
+            } catch (deliveryErr) {
+              channelDeliveryStore.resetRunDeliveryClaim(runId);
+              throw deliveryErr;
+            }
+          }
           return;
         }
       }
@@ -1240,6 +1415,7 @@ async function deliverReplyViaCallback(
   externalChatId: string,
   callbackUrl: string,
   bearerToken?: string,
+  assistantId?: string,
 ): Promise<void> {
   const msgs = conversationStore.getMessages(conversationId);
   for (let i = msgs.length - 1; i >= 0; i--) {
@@ -1262,6 +1438,7 @@ async function deliverReplyViaCallback(
           chatId: externalChatId,
           text: rendered.text || undefined,
           attachments: replyAttachments.length > 0 ? replyAttachments : undefined,
+          assistantId,
         }, bearerToken);
       }
       break;
@@ -1362,6 +1539,7 @@ export function sweepExpiredGuardianApprovals(
     deliverChannelReply(deliverUrl, {
       chatId: approval.requesterChatId,
       text: `Your guardian approval request for "${approval.toolName}" has expired and the action has been denied. Please try again.`,
+      assistantId: approval.assistantId,
     }, bearerToken).catch((err) => {
       log.error({ err, runId: approval.runId }, 'Failed to notify requester of guardian approval expiry');
     });
@@ -1370,6 +1548,7 @@ export function sweepExpiredGuardianApprovals(
     deliverChannelReply(deliverUrl, {
       chatId: approval.guardianChatId,
       text: `The approval request for "${approval.toolName}" from user ${approval.requesterExternalUserId} has expired and was automatically denied.`,
+      assistantId: approval.assistantId,
     }, bearerToken).catch((err) => {
       log.error({ err, runId: approval.runId }, 'Failed to notify guardian of approval expiry');
     });