@vellumai/assistant 0.3.2 → 0.3.4

package/src/__tests__/channel-approval-routes.test.ts

@@ -1,7 +1,8 @@
-import { describe, test, expect, beforeEach, afterAll, afterEach, mock, spyOn } from 'bun:test';
+import { describe, test, expect, beforeEach, afterAll, mock, spyOn } from 'bun:test';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { eq } from 'drizzle-orm';
 
 // ---------------------------------------------------------------------------
 // Test isolation: in-memory SQLite via temp directory
@@ -41,12 +42,13 @@ mock.module('../daemon/handlers.js', () => ({
 }));
 
 import { initializeDb, getDb, resetDb } from '../memory/db.js';
-import { conversations } from '../memory/schema.js';
+import { conversations, externalConversationBindings } from '../memory/schema.js';
 import {
   createRun,
   setRunConfirmation,
 } from '../memory/runs-store.js';
 import type { PendingConfirmation } from '../memory/runs-store.js';
+import { setConversationKeyIfAbsent } from '../memory/conversation-key-store.js';
 import * as channelDeliveryStore from '../memory/channel-delivery-store.js';
 import * as conversationStore from '../memory/conversation-store.js';
 import {
@@ -54,14 +56,13 @@ import {
   createApprovalRequest,
   getPendingApprovalForRun,
   getUnresolvedApprovalForRun,
-  getExpiredPendingApprovals,
-  updateApprovalDecision,
 } from '../memory/channel-guardian-store.js';
 import type { RunOrchestrator } from '../runtime/run-orchestrator.js';
 import {
   handleChannelInbound,
-  isChannelApprovalsEnabled,
   sweepExpiredGuardianApprovals,
+  verifyGatewayOrigin,
+  _setTestPollMaxWait,
 } from '../runtime/routes/channel-routes.js';
 import * as gatewayClient from '../runtime/gateway-client.js';
 
@@ -94,10 +95,12 @@ function resetTables(): void {
   db.run('DELETE FROM channel_guardian_approval_requests');
   db.run('DELETE FROM channel_guardian_verification_challenges');
   db.run('DELETE FROM channel_guardian_bindings');
+  db.run('DELETE FROM conversation_keys');
   db.run('DELETE FROM message_runs');
   db.run('DELETE FROM channel_inbound_events');
   db.run('DELETE FROM messages');
   db.run('DELETE FROM conversations');
+  channelDeliveryStore.resetAllRunDeliveryClaims();
 }
 
 const sampleConfirmation: PendingConfirmation = {
@@ -132,10 +135,15 @@ function makeMockOrchestrator(
   } as unknown as RunOrchestrator;
 }
 
+/** Default bearer token used by tests. Include the X-Gateway-Origin header
+ *  so that verifyGatewayOrigin does not reject the request. */
+const TEST_BEARER_TOKEN = 'token';
+
 function makeInboundRequest(overrides: Record<string, unknown> = {}): Request {
   const body = {
     sourceChannel: 'telegram',
     externalChatId: 'chat-123',
+    senderExternalUserId: 'telegram-user-default',
     externalMessageId: `msg-${Date.now()}-${Math.random()}`,
     content: 'hello',
     replyCallbackUrl: 'https://gateway.test/deliver',
@@ -143,60 +151,22 @@ function makeInboundRequest(overrides: Record<string, unknown> = {}): Request {
   };
   return new Request('http://localhost/channels/inbound', {
     method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
+    headers: {
+      'Content-Type': 'application/json',
+      'X-Gateway-Origin': TEST_BEARER_TOKEN,
+    },
     body: JSON.stringify(body),
   });
 }
 
 const noopProcessMessage = mock(async () => ({ messageId: 'msg-1' }));
 
-// ---------------------------------------------------------------------------
-// Set up / tear down feature flag for each test
-// ---------------------------------------------------------------------------
-
-let originalEnv: string | undefined;
-
 beforeEach(() => {
   resetTables();
-  originalEnv = process.env.CHANNEL_APPROVALS_ENABLED;
   noopProcessMessage.mockClear();
 });
-
-afterEach(() => {
-  if (originalEnv === undefined) {
-    delete process.env.CHANNEL_APPROVALS_ENABLED;
-  } else {
-    process.env.CHANNEL_APPROVALS_ENABLED = originalEnv;
-  }
-});
-
-// ═══════════════════════════════════════════════════════════════════════════
-// 1. Feature flag gating
-// ═══════════════════════════════════════════════════════════════════════════
-
-describe('isChannelApprovalsEnabled', () => {
-  test('returns false when env var is not set', () => {
-    delete process.env.CHANNEL_APPROVALS_ENABLED;
-    expect(isChannelApprovalsEnabled()).toBe(false);
-  });
-
-  test('returns false when env var is "false"', () => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'false';
-    expect(isChannelApprovalsEnabled()).toBe(false);
-  });
-
-  test('returns true when env var is "true"', () => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
-    expect(isChannelApprovalsEnabled()).toBe(true);
-  });
-});
-
-describe('feature flag disabled → normal flow', () => {
-  beforeEach(() => {
-    delete process.env.CHANNEL_APPROVALS_ENABLED;
-  });
-
-  test('proceeds normally even when pending approvals exist', async () => {
+describe('stale callback handling without matching pending approval', () => {
+  test('ignores stale callback payloads even when pending approvals exist', async () => {
     ensureConversation('conv-1');
     const run = createRun('conv-1');
     setRunConfirmation(run.id, sampleConfirmation);
@@ -210,9 +180,10 @@ describe('feature flag disabled → normal flow', () => {
     const res = await handleChannelInbound(req, noopProcessMessage, undefined, orchestrator);
     const body = await res.json() as Record<string, unknown>;
 
-    // Should proceed normally — no approval interception
+    // Callback payloads without a matching pending approval are treated as
+    // stale and ignored.
     expect(body.accepted).toBe(true);
-    expect(body.approval).toBeUndefined();
+    expect(body.approval).toBe('stale_ignored');
   });
 });
 
@@ -222,7 +193,12 @@ describe('feature flag disabled → normal flow', () => {
 
 describe('inbound callback metadata triggers decision handling', () => {
   beforeEach(() => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'telegram-user-default',
+      guardianDeliveryChatId: 'chat-123',
+    });
   });
 
   test('callback data "apr:<runId>:approve_once" is parsed and applied', async () => {
@@ -314,7 +290,12 @@ describe('inbound callback metadata triggers decision handling', () => {
 
 describe('inbound text matching approval phrases triggers decision handling', () => {
   beforeEach(() => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'telegram-user-default',
+      guardianDeliveryChatId: 'chat-123',
+    });
   });
 
   test('text "approve" triggers approve_once decision', async () => {
@@ -379,7 +360,12 @@ describe('inbound text matching approval phrases triggers decision handling', ()
 
 describe('non-decision messages during pending approval trigger reminder', () => {
   beforeEach(() => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'telegram-user-default',
+      guardianDeliveryChatId: 'chat-123',
+    });
   });
 
   test('sends a reminder prompt when message is not a decision', async () => {
@@ -427,7 +413,6 @@ describe('non-decision messages during pending approval trigger reminder', () =>
 
 describe('messages without pending approval proceed normally', () => {
   beforeEach(() => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
   });
 
   test('proceeds to normal processing when no pending approval exists', async () => {
@@ -471,7 +456,6 @@ describe('empty content with callbackData bypasses validation', () => {
   });
 
   test('allows empty content when callbackData is present', async () => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
     const orchestrator = makeMockOrchestrator();
 
     // Establish the conversation first
@@ -504,7 +488,6 @@ describe('empty content with callbackData bypasses validation', () => {
   });
 
   test('allows undefined content when callbackData is present', async () => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
     const orchestrator = makeMockOrchestrator();
 
     // Establish the conversation first
@@ -531,11 +514,14 @@ describe('empty content with callbackData bypasses validation', () => {
     };
     const req = new Request('http://localhost/channels/inbound', {
       method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Gateway-Origin': TEST_BEARER_TOKEN,
+      },
       body: JSON.stringify(body),
     });
 
-    const res = await handleChannelInbound(req, noopProcessMessage, 'token', orchestrator);
+    const res = await handleChannelInbound(req, noopProcessMessage, TEST_BEARER_TOKEN, orchestrator);
     expect(res.status).toBe(200);
     const resBody = await res.json() as Record<string, unknown>;
     expect(resBody.accepted).toBe(true);
@@ -550,7 +536,12 @@ describe('empty content with callbackData bypasses validation', () => {
 
 describe('callback run ID validation', () => {
   beforeEach(() => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'telegram-user-default',
+      guardianDeliveryChatId: 'chat-123',
+    });
   });
 
   test('ignores stale callback when run ID does not match pending run', async () => {
@@ -658,7 +649,6 @@ describe('callback run ID validation', () => {
 
 describe('linkMessage in approval-aware processing path', () => {
   beforeEach(() => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
   });
 
   test('linkMessage is called when run has a messageId and reaches terminal state', async () => {
@@ -715,7 +705,6 @@ describe('linkMessage in approval-aware processing path', () => {
 
 describe('terminal state check before markProcessed', () => {
   beforeEach(() => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
   });
 
   test('records processing failure when run disappears (non-approval non-terminal state)', async () => {
@@ -854,7 +843,12 @@ describe('terminal state check before markProcessed', () => {
 
 describe('no immediate reply after approval decision', () => {
   beforeEach(() => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'telegram-user-default',
+      guardianDeliveryChatId: 'chat-123',
+    });
   });
 
   test('deliverChannelReply is NOT called from interception after decision is applied', async () => {
@@ -932,7 +926,6 @@ describe('no immediate reply after approval decision', () => {
 
 describe('stale callback handling', () => {
   beforeEach(() => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
   });
 
   test('callback with no pending approval returns stale_ignored and does not start a run', async () => {
@@ -996,7 +989,6 @@ describe('stale callback handling', () => {
 
 describe('poll timeout handling by run state', () => {
   beforeEach(() => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
   });
 
   test('records processing failure when run disappears (getRun returns null) before terminal state', async () => {
@@ -1048,6 +1040,10 @@ describe('poll timeout handling by run state', () => {
   });
 
   test('marks event as processed when run is in needs_confirmation state after poll timeout', async () => {
+    // Use a short poll timeout so the test can exercise the timeout path
+    // without waiting 5 minutes. Must exceed one poll interval (500ms).
+    _setTestPollMaxWait(700);
+
     const linkSpy = spyOn(channelDeliveryStore, 'linkMessage').mockImplementation(() => {});
     const markSpy = spyOn(channelDeliveryStore, 'markProcessed');
     const failureSpy = spyOn(channelDeliveryStore, 'recordProcessingFailure').mockImplementation(() => {});
@@ -1068,12 +1064,18 @@ describe('poll timeout handling by run state', () => {
       updatedAt: Date.now(),
     };
 
-    // getRun returns needs_confirmation — run is waiting for approval decision.
-    // The event should be marked as processed because the post-decision delivery
-    // in handleApprovalInterception will deliver the reply when the user decides.
+    // getRun returns null on the first call (causing the poll loop to break
+    // immediately), then returns needs_confirmation on the post-loop call.
+    // This exercises the timeout path deterministically without spinning for
+    // the full poll duration.
+    let getRunCalls = 0;
     const orchestrator = {
       submitDecision: mock(() => 'applied' as const),
-      getRun: mock(() => ({ ...mockRun, status: 'needs_confirmation' as const })),
+      getRun: mock(() => {
+        getRunCalls++;
+        if (getRunCalls <= 1) return null;
+        return { ...mockRun, status: 'needs_confirmation' as const };
+      }),
       startRun: mock(async () => mockRun),
     } as unknown as RunOrchestrator;
 
@@ -1094,6 +1096,126 @@ describe('poll timeout handling by run state', () => {
     markSpy.mockRestore();
     failureSpy.mockRestore();
     deliverSpy.mockRestore();
+    _setTestPollMaxWait(null);
+  });
+
+  test('marks event as processed when run transitions from needs_confirmation to running at poll timeout', async () => {
+    // When an approval is applied near the poll deadline, the run transitions
+    // from needs_confirmation to running. The post-decision delivery path
+    // in handleApprovalInterception handles the final reply, so the main poll
+    // should mark the event as processed rather than recording a failure.
+    //
+    // The hasPostDecisionDelivery flag is only set when the approval prompt
+    // is actually delivered successfully — not in auto-deny paths. This test
+    // sets up a guardian actor with a real DB run so the standard approval
+    // prompt is delivered and the flag is set.
+    _setTestPollMaxWait(100);
+
+    const linkSpy = spyOn(channelDeliveryStore, 'linkMessage').mockImplementation(() => {});
+    const markSpy = spyOn(channelDeliveryStore, 'markProcessed');
+    const failureSpy = spyOn(channelDeliveryStore, 'recordProcessingFailure').mockImplementation(() => {});
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+    const approvalSpy = spyOn(gatewayClient, 'deliverApprovalPrompt').mockResolvedValue(undefined);
+
+    // Set up a guardian binding so the sender is a guardian (standard approval
+    // path, not auto-deny). This ensures the approval prompt is delivered and
+    // hasPostDecisionDelivery is set to true.
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'telegram-user-default',
+      guardianDeliveryChatId: 'chat-123',
+    });
+
+    const conversationId = `conv-post-approval-${Date.now()}`;
+    ensureConversation(conversationId);
+    setConversationKeyIfAbsent('asst:self:telegram:chat-123', conversationId);
+    setConversationKeyIfAbsent('telegram:chat-123', conversationId);
+
+    let realRunId: string | undefined;
+
+    // Simulate a run that transitions from needs_confirmation back to running
+    // (approval applied) before the poll exits, then stays running past timeout.
+    let getRunCalls = 0;
+    const orchestrator = {
+      submitDecision: mock(() => 'applied' as const),
+      getRun: mock(() => {
+        getRunCalls++;
+        // First call inside the loop: needs_confirmation (triggers approval prompt delivery)
+        if (getRunCalls <= 1) return {
+          id: realRunId ?? 'run-post-approval',
+          conversationId,
+          messageId: 'user-msg-203',
+          status: 'needs_confirmation' as const,
+          pendingConfirmation: sampleConfirmation,
+          pendingSecret: null,
+          inputTokens: 0,
+          outputTokens: 0,
+          estimatedCost: 0,
+          error: null,
+          createdAt: Date.now(),
+          updatedAt: Date.now(),
+        };
+        // Subsequent calls: running (approval was applied, run resumed)
+        return {
+          id: realRunId ?? 'run-post-approval',
+          conversationId,
+          messageId: 'user-msg-203',
+          status: 'running' as const,
+          pendingConfirmation: null,
+          pendingSecret: null,
+          inputTokens: 0,
+          outputTokens: 0,
+          estimatedCost: 0,
+          error: null,
+          createdAt: Date.now(),
+          updatedAt: Date.now(),
+        };
+      }),
+      startRun: mock(async (_convId: string) => {
+        const run = createRun(conversationId);
+        realRunId = run.id;
+        setRunConfirmation(run.id, sampleConfirmation);
+        return {
+          id: run.id,
+          conversationId,
+          messageId: null,
+          status: 'running' as const,
+          pendingConfirmation: null,
+          pendingSecret: null,
+          inputTokens: 0,
+          outputTokens: 0,
+          estimatedCost: 0,
+          error: null,
+          createdAt: Date.now(),
+          updatedAt: Date.now(),
+        };
+      }),
+    } as unknown as RunOrchestrator;
+
+    const req = makeInboundRequest({ content: 'hello post-approval running' });
+    await handleChannelInbound(req, noopProcessMessage, 'token', orchestrator);
+
+    // Wait for background async to complete (poll timeout + buffer)
+    await new Promise((resolve) => setTimeout(resolve, 1500));
+
+    // The approval prompt should have been delivered (standard path for guardian actor)
+    expect(approvalSpy).toHaveBeenCalled();
+
+    // markProcessed SHOULD have been called — the approval prompt was delivered
+    // (hasPostDecisionDelivery is true) and the run transitioned to running
+    // (post-approval), so the post-decision delivery path handles the final reply.
+    expect(markSpy).toHaveBeenCalled();
+
+    // recordProcessingFailure should NOT have been called
+    expect(failureSpy).not.toHaveBeenCalled();
+
+    linkSpy.mockRestore();
+    markSpy.mockRestore();
+    failureSpy.mockRestore();
+    deliverSpy.mockRestore();
+    approvalSpy.mockRestore();
+    _setTestPollMaxWait(null);
   });
 
   test('does NOT call recordProcessingFailure when run reaches terminal state', async () => {
@@ -1149,7 +1271,6 @@ describe('poll timeout handling by run state', () => {
 
 describe('post-decision delivery after poll timeout', () => {
   beforeEach(() => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
   });
 
   test('delivers reply via callback after a late approval decision', async () => {
@@ -1263,7 +1384,6 @@ describe('post-decision delivery after poll timeout', () => {
 
 describe('sourceChannel passed to orchestrator.startRun', () => {
   beforeEach(() => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
   });
 
   test('startRun is called with sourceChannel from inbound event', async () => {
@@ -1321,13 +1441,19 @@ describe('sourceChannel passed to orchestrator.startRun', () => {
 
 describe('SMS channel approval decisions', () => {
   beforeEach(() => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
+    createBinding({
+      assistantId: 'self',
+      channel: 'sms',
+      guardianExternalUserId: 'sms-user-default',
+      guardianDeliveryChatId: 'sms-chat-123',
+    });
   });
 
   function makeSmsInboundRequest(overrides: Record<string, unknown> = {}): Request {
     const body = {
       sourceChannel: 'sms',
       externalChatId: 'sms-chat-123',
+      senderExternalUserId: 'sms-user-default',
       externalMessageId: `msg-${Date.now()}-${Math.random()}`,
       content: 'hello',
       replyCallbackUrl: 'https://gateway.test/deliver',
@@ -1335,7 +1461,10 @@ describe('SMS channel approval decisions', () => {
     };
     return new Request('http://localhost/channels/inbound', {
       method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Gateway-Origin': TEST_BEARER_TOKEN,
+      },
       body: JSON.stringify(body),
     });
   }
@@ -1481,7 +1610,10 @@ describe('SMS guardian verify intercept', () => {
 
     const req = new Request('http://localhost/channels/inbound', {
       method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Gateway-Origin': TEST_BEARER_TOKEN,
+      },
       body: JSON.stringify({
         sourceChannel: 'sms',
         externalChatId: 'sms-chat-verify',
@@ -1492,7 +1624,7 @@ describe('SMS guardian verify intercept', () => {
       }),
     });
 
-    const res = await handleChannelInbound(req, noopProcessMessage, 'token');
+    const res = await handleChannelInbound(req, noopProcessMessage, TEST_BEARER_TOKEN);
     const body = await res.json() as Record<string, unknown>;
 
     expect(body.accepted).toBe(true);
@@ -1513,7 +1645,10 @@ describe('SMS guardian verify intercept', () => {
 
     const req = new Request('http://localhost/channels/inbound', {
       method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Gateway-Origin': TEST_BEARER_TOKEN,
+      },
       body: JSON.stringify({
         sourceChannel: 'sms',
         externalChatId: 'sms-chat-verify-fail',
@@ -1524,7 +1659,7 @@ describe('SMS guardian verify intercept', () => {
       }),
     });
 
-    const res = await handleChannelInbound(req, noopProcessMessage, 'token');
+    const res = await handleChannelInbound(req, noopProcessMessage, TEST_BEARER_TOKEN);
     const body = await res.json() as Record<string, unknown>;
 
     expect(body.accepted).toBe(true);
@@ -1545,7 +1680,6 @@ describe('SMS guardian verify intercept', () => {
 
 describe('SMS non-guardian actor gating', () => {
   beforeEach(() => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
   });
 
   test('non-guardian SMS actor gets stricter controls when guardian binding exists', async () => {
@@ -1585,7 +1719,10 @@ describe('SMS non-guardian actor gating', () => {
     // Send message from a NON-guardian sms user
     const req = new Request('http://localhost/channels/inbound', {
       method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Gateway-Origin': TEST_BEARER_TOKEN,
+      },
       body: JSON.stringify({
         sourceChannel: 'sms',
         externalChatId: 'sms-other-chat',
@@ -1596,7 +1733,7 @@ describe('SMS non-guardian actor gating', () => {
       }),
     });
 
-    await handleChannelInbound(req, noopProcessMessage, 'token', orchestrator);
+    await handleChannelInbound(req, noopProcessMessage, TEST_BEARER_TOKEN, orchestrator);
 
     // Wait for the background async to fire
     await new Promise((resolve) => setTimeout(resolve, 800));
@@ -1616,7 +1753,18 @@ describe('SMS non-guardian actor gating', () => {
 
 describe('plain-text fallback surfacing for non-rich channels', () => {
   beforeEach(() => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'telegram-user-default',
+      guardianDeliveryChatId: 'chat-123',
+    });
+    createBinding({
+      assistantId: 'self',
+      channel: 'http-api',
+      guardianExternalUserId: 'telegram-user-default',
+      guardianDeliveryChatId: 'chat-123',
+    });
   });
 
   test('reminder prompt includes plainTextFallback for non-rich channel (http-api)', async () => {
@@ -1772,10 +1920,9 @@ function makeSensitiveOrchestrator(opts: {
 
 describe('fail-closed guardian gate — unverified channel', () => {
   beforeEach(() => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
   });
 
-  test('no binding + sensitive action → auto-deny and setup notice', async () => {
+  test('no binding + sensitive action → auto-deny with contextual assistant guidance', async () => {
     const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
     const approvalSpy = spyOn(gatewayClient, 'deliverApprovalPrompt').mockResolvedValue(undefined);
 
@@ -1795,11 +1942,15 @@ describe('fail-closed guardian gate — unverified channel', () => {
     const decisionArgs = (orchestrator.submitDecision as ReturnType<typeof mock>).mock.calls[0];
     expect(decisionArgs[1]).toBe('deny');
 
-    // The requester should have been notified about missing guardian setup
-    const replyCalls = deliverSpy.mock.calls.filter(
+    // The deny decision should carry guardian setup context for assistant reply generation.
+    expect(typeof decisionArgs[2]).toBe('string');
+    expect((decisionArgs[2] as string)).toContain('no guardian is configured');
+
+    // The runtime should not send a second deterministic denial notice.
+    const deterministicNoticeCalls = deliverSpy.mock.calls.filter(
       (call) => typeof call[1] === 'object' && (call[1] as { text?: string }).text?.includes('no guardian has been set up'),
     );
-    expect(replyCalls.length).toBeGreaterThanOrEqual(1);
+    expect(deterministicNoticeCalls.length).toBe(0);
 
     // No approval prompt should have been sent to a guardian (none exists)
     expect(approvalSpy).not.toHaveBeenCalled();
@@ -1888,11 +2039,19 @@ describe('fail-closed guardian gate — unverified channel', () => {
     expect(body.accepted).toBe(true);
     expect(body.approval).toBe('decision_applied');
 
-    // The denial notice should have been sent
+    // The deny decision should carry guardian setup context for the assistant.
+    const submitCalls = (orchestrator.submitDecision as ReturnType<typeof mock>).mock.calls;
+    expect(submitCalls.length).toBeGreaterThanOrEqual(1);
+    const lastDecision = submitCalls[submitCalls.length - 1];
+    expect(lastDecision[1]).toBe('deny');
+    expect(typeof lastDecision[2]).toBe('string');
+    expect((lastDecision[2] as string)).toContain('no guardian is configured');
+
+    // Interception should not emit a separate deterministic denial notice.
     const denialCalls = deliverSpy.mock.calls.filter(
       (call) => typeof call[1] === 'object' && (call[1] as { text?: string }).text?.includes('no guardian has been set up'),
     );
-    expect(denialCalls.length).toBeGreaterThanOrEqual(1);
+    expect(denialCalls.length).toBe(0);
 
     deliverSpy.mockRestore();
   });
@@ -1904,7 +2063,6 @@ describe('fail-closed guardian gate — unverified channel', () => {
 
 describe('guardian-with-binding path regression', () => {
   beforeEach(() => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
   });
 
   test('non-guardian with binding routes approval to guardian chat', async () => {
@@ -1976,6 +2134,53 @@ describe('guardian-with-binding path regression', () => {
     deliverSpy.mockRestore();
     approvalSpy.mockRestore();
   });
+
+  test('guardian callback for own pending run is handled by standard interception', async () => {
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'guardian-user-self-callback',
+      guardianDeliveryChatId: 'chat-123',
+    });
+
+    const orchestrator = makeMockOrchestrator();
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    // Establish the conversation mapping for chat-123.
+    const initReq = makeInboundRequest({
+      content: 'init',
+      senderExternalUserId: 'guardian-user-self-callback',
+      externalChatId: 'chat-123',
+    });
+    await handleChannelInbound(initReq, noopProcessMessage, 'token', orchestrator);
+
+    const db = getDb();
+    const events = db.$client.prepare('SELECT conversation_id FROM channel_inbound_events').all() as Array<{ conversation_id: string }>;
+    const conversationId = events[0]?.conversation_id;
+    ensureConversation(conversationId!);
+
+    const run = createRun(conversationId!);
+    setRunConfirmation(run.id, sampleConfirmation);
+
+    // Button callback includes a runId but there is no guardian approval request
+    // because this is the guardian's own approval flow.
+    const req = makeInboundRequest({
+      content: '',
+      senderExternalUserId: 'guardian-user-self-callback',
+      externalChatId: 'chat-123',
+      callbackData: `apr:${run.id}:approve_once`,
+    });
+
+    const res = await handleChannelInbound(req, noopProcessMessage, 'token', orchestrator);
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(body.accepted).toBe(true);
+    expect(body.approval).toBe('decision_applied');
+    expect(orchestrator.submitDecision).toHaveBeenCalledWith(run.id, 'allow');
+    expect(getPendingApprovalForRun(run.id)).toBeNull();
+
+    deliverSpy.mockRestore();
+  });
 });
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -1984,7 +2189,6 @@ describe('guardian-with-binding path regression', () => {
 
 describe('guardian delivery failure → denial', () => {
   beforeEach(() => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
   });
 
   test('delivery failure denies run and notifies requester', async () => {
@@ -2074,13 +2278,57 @@ describe('guardian delivery failure → denial', () => {
   });
 });
 
+// ═══════════════════════════════════════════════════════════════════════════
+// 20b. Standard approval prompt delivery failure → auto-deny (WS-B)
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe('standard approval prompt delivery failure → auto-deny', () => {
+  beforeEach(() => {
+  });
+
+  test('standard prompt delivery failure auto-denies the run (fail-closed)', async () => {
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+    // Make the approval prompt delivery fail for the standard (self-approval) path
+    const approvalSpy = spyOn(gatewayClient, 'deliverApprovalPrompt').mockRejectedValue(
+      new Error('Network error: approval prompt unreachable'),
+    );
+
+    // No guardian binding — sender is a guardian (default role), so the
+    // standard self-approval path is used.
+    const orchestrator = makeSensitiveOrchestrator({ runId: 'run-std-fail', terminalStatus: 'failed' });
+
+    const req = makeInboundRequest({
+      content: 'do something dangerous',
+      senderExternalUserId: 'guardian-std-user',
+    });
+
+    // Set up a guardian binding so the sender is recognized as guardian
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'guardian-std-user',
+      guardianDeliveryChatId: 'chat-123',
+    });
+
+    await handleChannelInbound(req, noopProcessMessage, 'token', orchestrator);
+    await new Promise((resolve) => setTimeout(resolve, 1200));
+
+    // The run should have been auto-denied because the prompt could not be delivered
+    expect(orchestrator.submitDecision).toHaveBeenCalled();
+    const decisionArgs = (orchestrator.submitDecision as ReturnType<typeof mock>).mock.calls[0];
+    expect(decisionArgs[1]).toBe('deny');
+
+    deliverSpy.mockRestore();
+    approvalSpy.mockRestore();
+  });
+});
+
 // ═══════════════════════════════════════════════════════════════════════════
 // 21. Guardian decision scoping — callback for older run resolves correctly
 // ═══════════════════════════════════════════════════════════════════════════
 
 describe('guardian decision scoping — multiple pending approvals', () => {
   beforeEach(() => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
   });
 
   test('callback for older run resolves to the correct approval request', async () => {
@@ -2167,7 +2415,6 @@ describe('guardian decision scoping — multiple pending approvals', () => {
 
 describe('ambiguous plain-text decision with multiple pending requests', () => {
   beforeEach(() => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
   });
 
   test('does not apply plain-text decision to wrong run when multiple pending', async () => {
@@ -2254,7 +2501,6 @@ describe('ambiguous plain-text decision with multiple pending requests', () => {
 
 describe('expired guardian approval auto-denies via sweep', () => {
   beforeEach(() => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
   });
 
   test('sweepExpiredGuardianApprovals auto-denies and notifies both parties', async () => {
@@ -2360,3 +2606,931 @@ describe('expired guardian approval auto-denies via sweep', () => {
     deliverSpy.mockRestore();
   });
 });
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 24. Deliver-once idempotency guard
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe('deliver-once idempotency guard', () => {
+  test('claimRunDelivery returns true on first call, false on subsequent calls', () => {
+    const runId = 'run-idem-unit';
+    expect(channelDeliveryStore.claimRunDelivery(runId)).toBe(true);
+    expect(channelDeliveryStore.claimRunDelivery(runId)).toBe(false);
+    expect(channelDeliveryStore.claimRunDelivery(runId)).toBe(false);
+    channelDeliveryStore.resetRunDeliveryClaim(runId);
+  });
+
+  test('different run IDs are independent', () => {
+    expect(channelDeliveryStore.claimRunDelivery('run-a')).toBe(true);
+    expect(channelDeliveryStore.claimRunDelivery('run-b')).toBe(true);
+    expect(channelDeliveryStore.claimRunDelivery('run-a')).toBe(false);
+    expect(channelDeliveryStore.claimRunDelivery('run-b')).toBe(false);
+    channelDeliveryStore.resetRunDeliveryClaim('run-a');
+    channelDeliveryStore.resetRunDeliveryClaim('run-b');
+  });
+
+  test('resetRunDeliveryClaim allows re-claim', () => {
+    const runId = 'run-idem-reset';
+    expect(channelDeliveryStore.claimRunDelivery(runId)).toBe(true);
+    channelDeliveryStore.resetRunDeliveryClaim(runId);
+    expect(channelDeliveryStore.claimRunDelivery(runId)).toBe(true);
+    channelDeliveryStore.resetRunDeliveryClaim(runId);
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 25. Final reply idempotency — main poll wins vs post-decision poll wins
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe('final reply idempotency — no duplicate delivery', () => {
+  beforeEach(() => {
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'telegram-user-default',
+      guardianDeliveryChatId: 'chat-123',
+    });
+  });
+
+  test('main poll wins: deliverChannelReply called exactly once when main poll delivers first', async () => {
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    // Establish the conversation
+    const initReq = makeInboundRequest({ content: 'init' });
+    const orchestrator = makeMockOrchestrator();
+    await handleChannelInbound(initReq, noopProcessMessage, 'token', orchestrator);
+
+    const db = getDb();
+    const events = db.$client.prepare('SELECT conversation_id FROM channel_inbound_events').all() as Array<{ conversation_id: string }>;
+    const conversationId = events[0]?.conversation_id;
+    ensureConversation(conversationId!);
+
+    // Create a pending run and add an assistant message for delivery
+    const run = createRun(conversationId!);
+    setRunConfirmation(run.id, sampleConfirmation);
+    conversationStore.addMessage(conversationId!, 'assistant', 'Main poll result.');
+
+    // Orchestrator: first getRun returns needs_confirmation (to trigger
+    // approval prompt delivery in the poll), subsequent calls return
+    // completed so the main poll can deliver the reply.
+    let getRunCount = 0;
+    const racingOrchestrator = {
+      submitDecision: mock(() => 'applied' as const),
+      getRun: mock(() => {
+        getRunCount++;
+        if (getRunCount <= 1) {
+          return {
+            id: run.id,
+            conversationId: conversationId!,
+            messageId: null,
+            status: 'needs_confirmation' as const,
+            pendingConfirmation: sampleConfirmation,
+            pendingSecret: null,
+            inputTokens: 0, outputTokens: 0, estimatedCost: 0,
+            error: null,
+            createdAt: Date.now(), updatedAt: Date.now(),
+          };
+        }
+        return {
+          id: run.id,
+          conversationId: conversationId!,
+          messageId: null,
+          status: 'completed' as const,
+          pendingConfirmation: null,
+          pendingSecret: null,
+          inputTokens: 0, outputTokens: 0, estimatedCost: 0,
+          error: null,
+          createdAt: Date.now(), updatedAt: Date.now(),
+        };
+      }),
+      startRun: mock(async () => ({
+        id: run.id,
+        conversationId: conversationId!,
+        messageId: null,
+        status: 'running' as const,
+        pendingConfirmation: null,
+        pendingSecret: null,
+        inputTokens: 0, outputTokens: 0, estimatedCost: 0,
+        error: null,
+        createdAt: Date.now(), updatedAt: Date.now(),
+      })),
+    } as unknown as RunOrchestrator;
+
+    deliverSpy.mockClear();
+
+    // Send a message that triggers the approval path, then send a decision
+    // to trigger the post-decision poll. Both pollers should compete for delivery.
+    const msgReq = makeInboundRequest({ content: 'do something' });
+    await handleChannelInbound(msgReq, noopProcessMessage, 'token', racingOrchestrator);
+
+    // Send the decision to start the post-decision delivery poll
+    const decisionReq = makeInboundRequest({
+      content: '',
+      callbackData: `apr:${run.id}:approve_once`,
+    });
+    await handleChannelInbound(decisionReq, noopProcessMessage, 'token', racingOrchestrator);
+
+    // Wait for both pollers to finish
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+
+    // Count deliverChannelReply calls that carry the assistant reply text.
+    // Approval-related notifications (e.g. "has been sent to the guardian")
+    // are separate from the final reply. The final reply call is the one
+    // that delivers the actual conversation content.
+    const replyDeliveryCalls = deliverSpy.mock.calls.filter(
+      (call) => typeof call[1] === 'object' &&
+        (call[1] as { text?: string }).text === 'Main poll result.',
+    );
+
+    // The guard should ensure at most one delivery of the final reply
+    expect(replyDeliveryCalls.length).toBeLessThanOrEqual(1);
+
+    deliverSpy.mockRestore();
+  });
+
+  test('post-decision poll wins: delivers exactly once when main poll already exited', async () => {
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    // Establish the conversation
+    const initReq = makeInboundRequest({ content: 'init-late' });
+    const orchestrator = makeMockOrchestrator();
+    await handleChannelInbound(initReq, noopProcessMessage, 'token', orchestrator);
+
+    const db = getDb();
+    const events = db.$client.prepare('SELECT conversation_id FROM channel_inbound_events').all() as Array<{ conversation_id: string }>;
+    const conversationId = events[events.length - 1]?.conversation_id;
+    ensureConversation(conversationId!);
+
+    // Create a pending run
+    const run = createRun(conversationId!);
+    setRunConfirmation(run.id, sampleConfirmation);
+    conversationStore.addMessage(conversationId!, 'assistant', 'Post-decision result.');
+
+    // Orchestrator: getRun always returns needs_confirmation for the main poll
+    // (so the main poll times out without delivering), then returns completed
+    // for the post-decision poll. We use a separate call counter per context.
+    let mainPollExited = false;
+    let postDecisionGetRunCount = 0;
+    const lateOrchestrator = {
+      submitDecision: mock(() => 'applied' as const),
+      getRun: mock(() => {
+        if (!mainPollExited) {
+          // Main poll context — always return needs_confirmation so it exits
+          // without delivering (the 5min timeout is simulated by having the
+          // main poll see needs_confirmation until it gives up).
+          return {
+            id: run.id,
+            conversationId: conversationId!,
+            messageId: null,
+            status: 'needs_confirmation' as const,
+            pendingConfirmation: sampleConfirmation,
+            pendingSecret: null,
+            inputTokens: 0, outputTokens: 0, estimatedCost: 0,
+            error: null,
+            createdAt: Date.now(), updatedAt: Date.now(),
+          };
+        }
+        // Post-decision poll — return completed after a short delay
+        postDecisionGetRunCount++;
+        if (postDecisionGetRunCount <= 1) {
+          return {
+            id: run.id,
+            conversationId: conversationId!,
+            messageId: null,
+            status: 'needs_confirmation' as const,
+            pendingConfirmation: null,
+            pendingSecret: null,
+            inputTokens: 0, outputTokens: 0, estimatedCost: 0,
+            error: null,
+            createdAt: Date.now(), updatedAt: Date.now(),
+          };
+        }
+        return {
+          id: run.id,
+          conversationId: conversationId!,
+          messageId: null,
+          status: 'completed' as const,
+          pendingConfirmation: null,
+          pendingSecret: null,
+          inputTokens: 0, outputTokens: 0, estimatedCost: 0,
+          error: null,
+          createdAt: Date.now(), updatedAt: Date.now(),
+        };
+      }),
+      startRun: mock(async () => ({
+        id: run.id,
+        conversationId: conversationId!,
+        messageId: null,
+        status: 'running' as const,
+        pendingConfirmation: null,
+        pendingSecret: null,
+        inputTokens: 0, outputTokens: 0, estimatedCost: 0,
+        error: null,
+        createdAt: Date.now(), updatedAt: Date.now(),
+      })),
+    } as unknown as RunOrchestrator;
+
+    deliverSpy.mockClear();
+
+    // Start the main poll — it will see needs_confirmation and exit after
+    // the first poll interval (marking the event as processed, not delivering).
+    const msgReq = makeInboundRequest({ content: 'do something late' });
+    await handleChannelInbound(msgReq, noopProcessMessage, 'token', lateOrchestrator);
+
+    // Wait for the main poll to see needs_confirmation and mark processed
+    await new Promise((resolve) => setTimeout(resolve, 800));
+    mainPollExited = true;
+
+    // Now send the decision to trigger the post-decision delivery
+    const decisionReq = makeInboundRequest({
+      content: '',
+      callbackData: `apr:${run.id}:approve_once`,
+    });
+    await handleChannelInbound(decisionReq, noopProcessMessage, 'token', lateOrchestrator);
+
+    // Wait for the post-decision poll to deliver
+    await new Promise((resolve) => setTimeout(resolve, 1500));
+
+    // Count deliveries of the final assistant reply
+    const replyDeliveryCalls = deliverSpy.mock.calls.filter(
+      (call) => typeof call[1] === 'object' &&
+        (call[1] as { text?: string }).text === 'Post-decision result.',
+    );
+
+    // Exactly one delivery should have occurred (from the post-decision poll)
+    expect(replyDeliveryCalls.length).toBe(1);
+
+    deliverSpy.mockRestore();
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 26. Assistant-scoped guardian verification via handleChannelInbound
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe('assistant-scoped guardian verification via handleChannelInbound', () => {
+  test('/guardian_verify uses the threaded assistantId (default: self)', async () => {
+    const { createVerificationChallenge } = await import('../runtime/channel-guardian-service.js');
+    const { secret } = createVerificationChallenge('self', 'telegram');
+
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    const req = makeInboundRequest({
+      content: `/guardian_verify ${secret}`,
+      senderExternalUserId: 'user-default-asst',
+    });
+
+    // No assistantId passed => defaults to 'self'
+    const res = await handleChannelInbound(req, noopProcessMessage, 'token');
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(body.accepted).toBe(true);
+    expect(body.guardianVerification).toBe('verified');
+
+    deliverSpy.mockRestore();
+  });
+
+  test('/guardian_verify with explicit assistantId resolves against that assistant', async () => {
+    const { createVerificationChallenge } = await import('../runtime/channel-guardian-service.js');
+    const { getGuardianBinding } = await import('../runtime/channel-guardian-service.js');
+
+    // Create a challenge for asst-route-X
+    const { secret } = createVerificationChallenge('asst-route-X', 'telegram');
+
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    const req = makeInboundRequest({
+      content: `/guardian_verify ${secret}`,
+      senderExternalUserId: 'user-for-asst-x',
+    });
+
+    // Pass assistantId = 'asst-route-X'
+    const res = await handleChannelInbound(req, noopProcessMessage, 'token', undefined, 'asst-route-X');
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(body.accepted).toBe(true);
+    expect(body.guardianVerification).toBe('verified');
+
+    // Binding should exist for asst-route-X, not for 'self'
+    const bindingX = getGuardianBinding('asst-route-X', 'telegram');
+    expect(bindingX).not.toBeNull();
+    expect(bindingX!.guardianExternalUserId).toBe('user-for-asst-x');
+
+    deliverSpy.mockRestore();
+  });
+
+  test('cross-assistant challenge verification fails', async () => {
+    const { createVerificationChallenge } = await import('../runtime/channel-guardian-service.js');
+
+    // Create challenge for asst-A
+    const { secret } = createVerificationChallenge('asst-A-cross', 'telegram');
+
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    const req = makeInboundRequest({
+      content: `/guardian_verify ${secret}`,
+      senderExternalUserId: 'user-cross-test',
+    });
+
+    // Try to verify using asst-B — should fail because the challenge is for asst-A
+    const res = await handleChannelInbound(req, noopProcessMessage, 'token', undefined, 'asst-B-cross');
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(body.accepted).toBe(true);
+    expect(body.guardianVerification).toBe('failed');
+
+    deliverSpy.mockRestore();
+  });
+
+  test('actor role resolution uses threaded assistantId', async () => {
+
+    // Create guardian binding for asst-role-X
+    createBinding({
+      assistantId: 'asst-role-X',
+      channel: 'telegram',
+      guardianExternalUserId: 'guardian-role-user',
+      guardianDeliveryChatId: 'guardian-role-chat',
+    });
+
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+    const approvalSpy = spyOn(gatewayClient, 'deliverApprovalPrompt').mockResolvedValue(undefined);
+
+    const orchestrator = makeSensitiveOrchestrator({ runId: 'run-role-scoped', terminalStatus: 'completed' });
+
+    // Non-guardian user sending to asst-role-X should be recognized as non-guardian
+    const req = makeInboundRequest({
+      content: 'do something dangerous',
+      senderExternalUserId: 'non-guardian-role-user',
+    });
+
+    await handleChannelInbound(req, noopProcessMessage, 'token', orchestrator, 'asst-role-X');
+    await new Promise((resolve) => setTimeout(resolve, 1200));
+
+    // The approval prompt should have been sent to the guardian's chat
+    expect(approvalSpy).toHaveBeenCalled();
+    const approvalArgs = approvalSpy.mock.calls[0];
+    expect(approvalArgs[1]).toBe('guardian-role-chat');
+
+    deliverSpy.mockRestore();
+    approvalSpy.mockRestore();
+  });
+
+  test('same user is guardian for one assistant but not another', async () => {
+
+    // user-multi is guardian for asst-M1 but not asst-M2
+    createBinding({
+      assistantId: 'asst-M1',
+      channel: 'telegram',
+      guardianExternalUserId: 'user-multi',
+      guardianDeliveryChatId: 'chat-multi',
+    });
+    createBinding({
+      assistantId: 'asst-M2',
+      channel: 'telegram',
+      guardianExternalUserId: 'user-other-guardian',
+      guardianDeliveryChatId: 'chat-other-guardian',
+    });
+
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+    const approvalSpy = spyOn(gatewayClient, 'deliverApprovalPrompt').mockResolvedValue(undefined);
+
+    // For asst-M1: user-multi is the guardian, so should get standard self-approval
+    const orch1 = makeSensitiveOrchestrator({ runId: 'run-m1', terminalStatus: 'completed' });
+    const req1 = makeInboundRequest({
+      content: 'dangerous action',
+      senderExternalUserId: 'user-multi',
+    });
+
+    await handleChannelInbound(req1, noopProcessMessage, 'token', orch1, 'asst-M1');
+    await new Promise((resolve) => setTimeout(resolve, 1200));
+
+    // For asst-M1, user-multi is guardian — approval prompt to own chat (standard flow)
+    expect(approvalSpy).toHaveBeenCalled();
+    const m1ApprovalArgs = approvalSpy.mock.calls[0];
+    // Should be sent to user-multi's own chat (chat-123 from makeInboundRequest default)
+    expect(m1ApprovalArgs[1]).toBe('chat-123');
+
+    approvalSpy.mockClear();
+    deliverSpy.mockClear();
+
+    // For asst-M2: user-multi is NOT the guardian, so approval should route to asst-M2's guardian
+    const orch2 = makeSensitiveOrchestrator({ runId: 'run-m2', terminalStatus: 'completed' });
+    const req2 = makeInboundRequest({
+      content: 'another dangerous action',
+      senderExternalUserId: 'user-multi',
+    });
+
+    await handleChannelInbound(req2, noopProcessMessage, 'token', orch2, 'asst-M2');
+    await new Promise((resolve) => setTimeout(resolve, 1200));
+
+    // For asst-M2, user-multi is non-guardian — approval should go to user-other-guardian's chat
+    expect(approvalSpy).toHaveBeenCalled();
+    const m2ApprovalArgs = approvalSpy.mock.calls[0];
+    expect(m2ApprovalArgs[1]).toBe('chat-other-guardian');
+
+    deliverSpy.mockRestore();
+    approvalSpy.mockRestore();
+  });
+
+  test('non-self assistant inbound does not mutate assistant-agnostic external bindings', async () => {
+    const db = getDb();
+    const now = Date.now();
+    ensureConversation('conv-existing-binding');
+    db.insert(externalConversationBindings).values({
+      conversationId: 'conv-existing-binding',
+      sourceChannel: 'telegram',
+      externalChatId: 'chat-123',
+      externalUserId: 'existing-user',
+      createdAt: now,
+      updatedAt: now,
+      lastInboundAt: now,
+    }).run();
+
+    const req = makeInboundRequest({
+      content: 'hello from non-self assistant',
+      senderExternalUserId: 'incoming-user',
+    });
+
+    const res = await handleChannelInbound(req, undefined, 'token', undefined, 'asst-non-self');
+    expect(res.status).toBe(200);
+
+    const binding = db
+      .select()
+      .from(externalConversationBindings)
+      .where(eq(externalConversationBindings.conversationId, 'conv-existing-binding'))
+      .get();
+    expect(binding).not.toBeNull();
+    expect(binding!.externalUserId).toBe('existing-user');
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 27. Guardian enforcement behavior
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe('guardian enforcement behavior', () => {
+  test('guardian sender on telegram uses approval-aware path', async () => {
+
+    // Default senderExternalUserId in makeInboundRequest is telegram-user-default.
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'telegram-user-default',
+      guardianDeliveryChatId: 'chat-123',
+    });
+
+    const processSpy = mock(async () => ({ messageId: 'msg-bg-guardian' }));
+    const approvalSpy = spyOn(gatewayClient, 'deliverApprovalPrompt').mockResolvedValue(undefined);
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    const orchestrator = makeSensitiveOrchestrator({
+      runId: 'run-guardian-flag-off-telegram',
+      terminalStatus: 'completed',
+    });
+
+    const req = makeInboundRequest({
+      content: 'place a call',
+      senderExternalUserId: 'telegram-user-default',
+      sourceChannel: 'telegram',
+    });
+
+    const res = await handleChannelInbound(req, processSpy, 'token', orchestrator);
+    expect(res.status).toBe(200);
+
+    await new Promise((resolve) => setTimeout(resolve, 1200));
+
+    // Regression guard: this must use the orchestrator approval path, not
+    // fire-and-forget processMessage, otherwise prompts can time out.
+    expect(orchestrator.startRun).toHaveBeenCalled();
+    expect(processSpy).not.toHaveBeenCalled();
+
+    // Guardian self-approval prompt should be delivered to the requester's chat.
+    expect(approvalSpy).toHaveBeenCalled();
+
+    approvalSpy.mockRestore();
+    deliverSpy.mockRestore();
+  });
+
+  test('non-guardian sensitive action routes approval to guardian', async () => {
+    // Create a guardian binding — user-guardian is the guardian
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'user-guardian',
+      guardianDeliveryChatId: 'chat-guardian',
+    });
+
+    const orchestrator = makeSensitiveOrchestrator({ runId: 'run-flag-off-guardian', terminalStatus: 'completed' });
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+    const approvalSpy = spyOn(gatewayClient, 'deliverApprovalPrompt').mockResolvedValue(undefined);
+
+    const req = makeInboundRequest({
+      content: 'do something dangerous',
+      senderExternalUserId: 'user-non-guardian',
+    });
+
+    const res = await handleChannelInbound(req, noopProcessMessage, 'token', orchestrator);
+    expect(res.status).toBe(200);
+    await new Promise((resolve) => setTimeout(resolve, 1200));
+
+    expect(approvalSpy).toHaveBeenCalled();
+    const approvalArgs = approvalSpy.mock.calls[0];
+    expect(approvalArgs[1]).toBe('chat-guardian');
+
+    deliverSpy.mockRestore();
+    approvalSpy.mockRestore();
+  });
+
+  test('missing senderExternalUserId with guardian binding fails closed', async () => {
+
+    // Create a guardian binding — guardian enforcement is active
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'user-guardian',
+      guardianDeliveryChatId: 'chat-guardian',
+    });
+
+    // Use makeSensitiveOrchestrator so that getRun returns needs_confirmation
+    // on the first poll (triggering the unverified_channel auto-deny path)
+    // and then returns terminal state.
+    const orchestrator = makeSensitiveOrchestrator({ runId: 'run-failclosed-1', terminalStatus: 'failed' });
+
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+    const approvalSpy = spyOn(gatewayClient, 'deliverApprovalPrompt').mockResolvedValue(undefined);
+
+    // Send a message WITHOUT senderExternalUserId
+    const req = makeInboundRequest({
+      content: 'do something dangerous',
+      senderExternalUserId: undefined,
+    });
+
+    const res = await handleChannelInbound(req, noopProcessMessage, 'token', orchestrator);
+    expect(res.status).toBe(200);
+
+    // Wait for background processing
+    await new Promise((resolve) => setTimeout(resolve, 1200));
+
+    // The unknown actor should be treated as unverified_channel and denied,
+    // with context passed into the tool-denial response for assistant phrasing.
+    const submitCalls = (orchestrator.submitDecision as ReturnType<typeof mock>).mock.calls;
+    expect(submitCalls.length).toBeGreaterThanOrEqual(1);
+    const lastDecision = submitCalls[submitCalls.length - 1];
+    expect(lastDecision[1]).toBe('deny');
+    expect(typeof lastDecision[2]).toBe('string');
+    expect((lastDecision[2] as string)).toContain('identity could not be verified');
+
+    // No separate deterministic denial notice should be emitted here.
+    const denialCalls = deliverSpy.mock.calls.filter(
+      (call) => typeof call[1] === 'object'
+        && ((call[1] as { text?: string }).text ?? '').includes('identity could not be determined'),
+    );
+    expect(denialCalls.length).toBe(0);
+
+    // Auto-deny path should never prompt for approval
+    expect(approvalSpy).not.toHaveBeenCalled();
+
+    deliverSpy.mockRestore();
+    approvalSpy.mockRestore();
+  });
+
+  test('missing senderExternalUserId without guardian binding fails closed', async () => {
+
+    // No guardian binding exists, but identity is missing — treat sender as
+    // unverified_channel and auto-deny sensitive actions.
+    const orchestrator = makeSensitiveOrchestrator({ runId: 'run-failclosed-noid-nobinding', terminalStatus: 'failed' });
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+    const approvalSpy = spyOn(gatewayClient, 'deliverApprovalPrompt').mockResolvedValue(undefined);
+
+    const req = makeInboundRequest({
+      content: 'do something dangerous',
+      senderExternalUserId: undefined,
+    });
+
+    const res = await handleChannelInbound(req, noopProcessMessage, 'token', orchestrator);
+    expect(res.status).toBe(200);
+
+    await new Promise((resolve) => setTimeout(resolve, 1200));
+
+    const submitCalls = (orchestrator.submitDecision as ReturnType<typeof mock>).mock.calls;
+    expect(submitCalls.length).toBeGreaterThanOrEqual(1);
+    const lastDecision = submitCalls[submitCalls.length - 1];
+    expect(lastDecision[1]).toBe('deny');
+    expect(typeof lastDecision[2]).toBe('string');
+    expect((lastDecision[2] as string)).toContain('identity could not be verified');
+
+    const denialCalls = deliverSpy.mock.calls.filter(
+      (call) => typeof call[1] === 'object'
+        && ((call[1] as { text?: string }).text ?? '').includes('identity could not be determined'),
+    );
+    expect(denialCalls.length).toBe(0);
+    expect(approvalSpy).not.toHaveBeenCalled();
+
+    deliverSpy.mockRestore();
+    approvalSpy.mockRestore();
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 28. Gateway-origin proof hardening — dedicated secret support
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe('verifyGatewayOrigin with dedicated gateway-origin secret', () => {
+  function makeReqWithHeader(value?: string): Request {
+    const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+    if (value !== undefined) {
+      headers['X-Gateway-Origin'] = value;
+    }
+    return new Request('http://localhost/channels/inbound', {
+      method: 'POST',
+      headers,
+      body: '{}',
+    });
+  }
+
+  test('returns true when no secrets configured (local dev)', () => {
+    expect(verifyGatewayOrigin(makeReqWithHeader(), undefined, undefined)).toBe(true);
+  });
+
+  test('falls back to bearerToken when no dedicated secret is set', () => {
+    expect(verifyGatewayOrigin(makeReqWithHeader('my-bearer'), 'my-bearer', undefined)).toBe(true);
+    expect(verifyGatewayOrigin(makeReqWithHeader('wrong'), 'my-bearer', undefined)).toBe(false);
+    expect(verifyGatewayOrigin(makeReqWithHeader(), 'my-bearer', undefined)).toBe(false);
+  });
+
+  test('uses dedicated secret when set, ignoring bearer token', () => {
+    // Dedicated secret matches — should pass even if bearer token differs
+    expect(verifyGatewayOrigin(makeReqWithHeader('dedicated-secret'), 'bearer-token', 'dedicated-secret')).toBe(true);
+    // Bearer token matches but dedicated secret doesn't — should fail
+    expect(verifyGatewayOrigin(makeReqWithHeader('bearer-token'), 'bearer-token', 'dedicated-secret')).toBe(false);
+  });
+
+  test('validates dedicated secret even when bearer token is not configured', () => {
+    // No bearer token but dedicated secret is set — should validate against it
+    expect(verifyGatewayOrigin(makeReqWithHeader('my-secret'), undefined, 'my-secret')).toBe(true);
+    expect(verifyGatewayOrigin(makeReqWithHeader('wrong'), undefined, 'my-secret')).toBe(false);
+  });
+
+  test('rejects missing header when any secret is configured', () => {
+    expect(verifyGatewayOrigin(makeReqWithHeader(), 'bearer', undefined)).toBe(false);
+    expect(verifyGatewayOrigin(makeReqWithHeader(), undefined, 'secret')).toBe(false);
+    expect(verifyGatewayOrigin(makeReqWithHeader(), 'bearer', 'secret')).toBe(false);
+  });
+
+  test('rejects mismatched length headers (constant-time comparison guard)', () => {
+    // Different lengths should be rejected without timing leaks
+    expect(verifyGatewayOrigin(makeReqWithHeader('short'), 'a-much-longer-secret', undefined)).toBe(false);
+    expect(verifyGatewayOrigin(makeReqWithHeader('a-much-longer-secret'), 'short', undefined)).toBe(false);
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 29. handleChannelInbound passes gatewayOriginSecret to verifyGatewayOrigin
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe('handleChannelInbound gatewayOriginSecret integration', () => {
+  test('rejects request when bearer token matches but dedicated secret does not', async () => {
+    const bearerToken = 'my-bearer';
+    const gatewaySecret = 'dedicated-gw-secret';
+
+    // Request carries the bearer token as X-Gateway-Origin, but the
+    // dedicated secret is configured — verifyGatewayOrigin should require
+    // the dedicated secret, not the bearer token.
+    const req = new Request('http://localhost/channels/inbound', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Gateway-Origin': bearerToken,
+      },
+      body: JSON.stringify({
+        sourceChannel: 'telegram',
+        externalChatId: 'chat-gw-secret-test',
+        externalMessageId: `msg-${Date.now()}-${Math.random()}`,
+        content: 'hello',
+      }),
+    });
+
+    const res = await handleChannelInbound(
+      req, noopProcessMessage, bearerToken, undefined, 'self', gatewaySecret,
+    );
+    expect(res.status).toBe(403);
+    const body = await res.json() as { code: string };
+    expect(body.code).toBe('GATEWAY_ORIGIN_REQUIRED');
+  });
+
+  test('accepts request when dedicated secret matches', async () => {
+    const bearerToken = 'my-bearer';
+    const gatewaySecret = 'dedicated-gw-secret';
+
+    const req = new Request('http://localhost/channels/inbound', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Gateway-Origin': gatewaySecret,
+      },
+      body: JSON.stringify({
+        sourceChannel: 'telegram',
+        externalChatId: 'chat-gw-secret-pass',
+        externalMessageId: `msg-${Date.now()}-${Math.random()}`,
+        content: 'hello',
+      }),
+    });
+
+    const res = await handleChannelInbound(
+      req, noopProcessMessage, bearerToken, undefined, 'self', gatewaySecret,
+    );
+    // Should pass the gateway-origin check and proceed to normal processing
+    expect(res.status).toBe(200);
+    const body = await res.json() as Record<string, unknown>;
+    expect(body.accepted).toBe(true);
+  });
+
+  test('falls back to bearer token when no dedicated secret is set', async () => {
+    const bearerToken = 'my-bearer';
+
+    const req = new Request('http://localhost/channels/inbound', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Gateway-Origin': bearerToken,
+      },
+      body: JSON.stringify({
+        sourceChannel: 'telegram',
+        externalChatId: 'chat-gw-fallback',
+        externalMessageId: `msg-${Date.now()}-${Math.random()}`,
+        content: 'hello',
+      }),
+    });
+
+    // No gatewayOriginSecret (6th param undefined) — should fall back to bearer
+    const res = await handleChannelInbound(
+      req, noopProcessMessage, bearerToken, undefined, 'self', undefined,
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as Record<string, unknown>;
+    expect(body.accepted).toBe(true);
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 30. Unknown actor identity — forceStrictSideEffects propagation
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe('unknown actor identity — forceStrictSideEffects', () => {
+  beforeEach(() => {
+  });
+
+  test('unknown sender (no senderExternalUserId) with guardian binding gets forceStrictSideEffects', async () => {
+    // Create a guardian binding so the channel is guardian-enforced
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'known-guardian',
+      guardianDeliveryChatId: 'guardian-chat',
+    });
+
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    const mockRun = {
+      id: 'run-unknown-actor',
+      conversationId: 'conv-1',
+      messageId: null,
+      status: 'running' as const,
+      pendingConfirmation: null,
+      pendingSecret: null,
+      inputTokens: 0,
+      outputTokens: 0,
+      estimatedCost: 0,
+      error: null,
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+    };
+
+    const orchestrator = {
+      submitDecision: mock(() => 'applied' as const),
+      getRun: mock(() => ({ ...mockRun, status: 'completed' as const })),
+      startRun: mock(async () => mockRun),
+    } as unknown as RunOrchestrator;
+
+    // Send message with no senderExternalUserId — the unknown actor should
+    // be classified as unverified_channel and forceStrictSideEffects set.
+    const req = makeInboundRequest({
+      content: 'do something',
+      senderExternalUserId: undefined,
+    });
+
+    await handleChannelInbound(req, noopProcessMessage, 'token', orchestrator);
+    await new Promise((resolve) => setTimeout(resolve, 800));
+
+    // startRun should have been called with forceStrictSideEffects: true
+    expect(orchestrator.startRun).toHaveBeenCalled();
+    const startRunArgs = (orchestrator.startRun as ReturnType<typeof mock>).mock.calls[0];
+    const options = startRunArgs[3] as { forceStrictSideEffects?: boolean } | undefined;
+    expect(options).toBeDefined();
+    expect(options!.forceStrictSideEffects).toBe(true);
+
+    deliverSpy.mockRestore();
+  });
+
+  test('known non-guardian sender with guardian binding gets forceStrictSideEffects', async () => {
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'the-guardian',
+      guardianDeliveryChatId: 'guardian-chat-2',
+    });
+
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+    const approvalSpy = spyOn(gatewayClient, 'deliverApprovalPrompt').mockResolvedValue(undefined);
+
+    const mockRun = {
+      id: 'run-nongrd-strict',
+      conversationId: 'conv-1',
+      messageId: null,
+      status: 'running' as const,
+      pendingConfirmation: null,
+      pendingSecret: null,
+      inputTokens: 0,
+      outputTokens: 0,
+      estimatedCost: 0,
+      error: null,
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+    };
+
+    const orchestrator = {
+      submitDecision: mock(() => 'applied' as const),
+      getRun: mock(() => ({ ...mockRun, status: 'completed' as const })),
+      startRun: mock(async () => mockRun),
+    } as unknown as RunOrchestrator;
+
+    // Non-guardian user sends a message
+    const req = makeInboundRequest({
+      content: 'do something',
+      senderExternalUserId: 'not-the-guardian',
+    });
+
+    await handleChannelInbound(req, noopProcessMessage, 'token', orchestrator);
+    await new Promise((resolve) => setTimeout(resolve, 800));
+
+    // startRun should have been called with forceStrictSideEffects: true
+    expect(orchestrator.startRun).toHaveBeenCalled();
+    const startRunArgs = (orchestrator.startRun as ReturnType<typeof mock>).mock.calls[0];
+    const options = startRunArgs[3] as { forceStrictSideEffects?: boolean } | undefined;
+    expect(options).toBeDefined();
+    expect(options!.forceStrictSideEffects).toBe(true);
+
+    deliverSpy.mockRestore();
+    approvalSpy.mockRestore();
+  });
+
+  test('guardian sender does NOT get forceStrictSideEffects', async () => {
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'the-guardian',
+      guardianDeliveryChatId: 'guardian-chat-3',
+    });
+
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    const mockRun = {
+      id: 'run-grd-no-strict',
+      conversationId: 'conv-1',
+      messageId: null,
+      status: 'running' as const,
+      pendingConfirmation: null,
+      pendingSecret: null,
+      inputTokens: 0,
+      outputTokens: 0,
+      estimatedCost: 0,
+      error: null,
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+    };
+
+    const orchestrator = {
+      submitDecision: mock(() => 'applied' as const),
+      getRun: mock(() => ({ ...mockRun, status: 'completed' as const })),
+      startRun: mock(async () => mockRun),
+    } as unknown as RunOrchestrator;
+
+    // The guardian sends a message — should NOT get forceStrictSideEffects
+    const req = makeInboundRequest({
+      content: 'do something',
+      senderExternalUserId: 'the-guardian',
+    });
+
+    await handleChannelInbound(req, noopProcessMessage, 'token', orchestrator);
+    await new Promise((resolve) => setTimeout(resolve, 800));
+
+    expect(orchestrator.startRun).toHaveBeenCalled();
+    const startRunArgs = (orchestrator.startRun as ReturnType<typeof mock>).mock.calls[0];
+    const options = startRunArgs[3] as { forceStrictSideEffects?: boolean; sourceChannel?: string } | undefined;
+    expect(options).toBeDefined();
+    // Guardian should NOT have forceStrictSideEffects set
+    expect(options!.forceStrictSideEffects).toBeUndefined();
+
+    deliverSpy.mockRestore();
+  });
+});