@vellumai/assistant 0.3.2 → 0.3.3

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

@@ -54,14 +54,14 @@ 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';
 
@@ -98,6 +98,7 @@ function resetTables(): void {
   db.run('DELETE FROM channel_inbound_events');
   db.run('DELETE FROM messages');
   db.run('DELETE FROM conversations');
+  channelDeliveryStore.resetAllRunDeliveryClaims();
 }
 
 const sampleConfirmation: PendingConfirmation = {
@@ -132,6 +133,10 @@ 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',
@@ -143,7 +148,10 @@ 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),
   });
 }
@@ -531,11 +539,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);
@@ -1048,6 +1059,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.
+    _setTestPollMaxWait(600);
+
     const linkSpy = spyOn(channelDeliveryStore, 'linkMessage').mockImplementation(() => {});
     const markSpy = spyOn(channelDeliveryStore, 'markProcessed');
     const failureSpy = spyOn(channelDeliveryStore, 'recordProcessingFailure').mockImplementation(() => {});
@@ -1080,8 +1095,8 @@ describe('poll timeout handling by run state', () => {
     const req = makeInboundRequest({ content: 'hello needs_confirm' });
     await handleChannelInbound(req, noopProcessMessage, 'token', orchestrator);
 
-    // Wait for the background async to complete
-    await new Promise((resolve) => setTimeout(resolve, 800));
+    // Wait for the background async to complete (poll timeout is 600ms + one poll interval of 500ms)
+    await new Promise((resolve) => setTimeout(resolve, 1500));
 
     // markProcessed SHOULD have been called — the run is waiting for approval,
     // and the post-decision delivery path will handle the final reply.
@@ -1094,6 +1109,7 @@ describe('poll timeout handling by run state', () => {
     markSpy.mockRestore();
     failureSpy.mockRestore();
     deliverSpy.mockRestore();
+    _setTestPollMaxWait(null);
   });
 
   test('does NOT call recordProcessingFailure when run reaches terminal state', async () => {
@@ -1335,7 +1351,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 +1500,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 +1514,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 +1535,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 +1549,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);
@@ -1585,7 +1610,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 +1624,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));
@@ -2074,6 +2102,52 @@ describe('guardian delivery failure → denial', () => {
   });
 });
 
+// ═══════════════════════════════════════════════════════════════════════════
+// 20b. Standard approval prompt delivery failure → auto-deny (WS-B)
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe('standard approval prompt delivery failure → auto-deny', () => {
+  beforeEach(() => {
+    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
+  });
+
+  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
 // ═══════════════════════════════════════════════════════════════════════════
@@ -2360,3 +2434,845 @@ 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(() => {
+    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
+  });
+
+  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 () => {
+    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
+
+    // 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 () => {
+    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
+
+    // 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();
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 27. Guardian enforcement decoupled from CHANNEL_APPROVALS_ENABLED
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe('guardian enforcement independence from approval flag', () => {
+  test('actor role resolution runs when CHANNEL_APPROVALS_ENABLED is off', async () => {
+    delete process.env.CHANNEL_APPROVALS_ENABLED;
+
+    // Create a guardian binding — user-guardian is the guardian
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'user-guardian',
+      guardianDeliveryChatId: 'chat-guardian',
+    });
+
+    // A non-guardian user sends a message with approvals disabled.
+    // Actor role resolution should still classify them as non-guardian
+    // even though the approval UX is off.
+    const orchestrator = makeMockOrchestrator();
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    const req = makeInboundRequest({
+      content: 'hello world',
+      senderExternalUserId: 'user-non-guardian',
+    });
+
+    const res = await handleChannelInbound(req, noopProcessMessage, 'token', orchestrator);
+    expect(res.status).toBe(200);
+
+    // The message should proceed normally since approval UX is off,
+    // but actor role resolution still ran (verified by the fact that
+    // the message processed successfully without error)
+    const body = await res.json() as Record<string, unknown>;
+    expect(body.accepted).toBe(true);
+
+    deliverSpy.mockRestore();
+  });
+
+  test('missing senderExternalUserId with guardian binding fails closed', async () => {
+    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
+
+    // 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
+    // sensitive actions should be auto-denied via the no_identity branch.
+    // deliverChannelReply args: (callbackUrl, payload, bearerToken?)
+    // The denial notice is in payload.text (index 1 of the call args).
+    expect(deliverSpy).toHaveBeenCalled();
+    const denialCalls = deliverSpy.mock.calls.filter(
+      (call) => {
+        if (typeof call[1] !== 'object') return false;
+        const text = (call[1] as { text?: string }).text ?? '';
+        return text.includes('requires guardian approval') &&
+          (text.includes('identity could not be determined') || text.includes('no guardian has been set up'));
+      },
+    );
+    expect(denialCalls.length).toBeGreaterThanOrEqual(1);
+
+    // Auto-deny path should never prompt for approval
+    expect(approvalSpy).not.toHaveBeenCalled();
+
+    deliverSpy.mockRestore();
+    approvalSpy.mockRestore();
+  });
+
+  test('missing senderExternalUserId without guardian binding uses default flow', async () => {
+    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
+
+    // No guardian binding exists — default behavior should be preserved
+    const orchestrator = makeMockOrchestrator();
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    const req = makeInboundRequest({
+      content: 'hello world',
+      senderExternalUserId: undefined,
+    });
+
+    const res = await handleChannelInbound(req, noopProcessMessage, 'token', orchestrator);
+    expect(res.status).toBe(200);
+
+    const body = await res.json() as Record<string, unknown>;
+    expect(body.accepted).toBe(true);
+
+    deliverSpy.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(() => {
+    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
+  });
+
+  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();
+  });
+});