@vellumai/assistant 0.3.3 → 0.3.5

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 {
@@ -58,7 +60,6 @@ import {
 import type { RunOrchestrator } from '../runtime/run-orchestrator.js';
 import {
   handleChannelInbound,
-  isChannelApprovalsEnabled,
   sweepExpiredGuardianApprovals,
   verifyGatewayOrigin,
   _setTestPollMaxWait,
@@ -94,6 +95,7 @@ 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');
@@ -141,6 +143,7 @@ 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',
@@ -158,53 +161,12 @@ function makeInboundRequest(overrides: Record<string, unknown> = {}): Request {
 
 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);
@@ -218,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');
   });
 });
 
@@ -230,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 () => {
@@ -322,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 () => {
@@ -387,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 () => {
@@ -435,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 () => {
@@ -479,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
@@ -512,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
@@ -561,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 () => {
@@ -669,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 () => {
@@ -726,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 () => {
@@ -865,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 () => {
@@ -943,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 () => {
@@ -1007,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 () => {
@@ -1060,8 +1041,8 @@ 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);
+    // without waiting 5 minutes. Must exceed one poll interval (500ms).
+    _setTestPollMaxWait(700);
 
     const linkSpy = spyOn(channelDeliveryStore, 'linkMessage').mockImplementation(() => {});
     const markSpy = spyOn(channelDeliveryStore, 'markProcessed');
@@ -1083,20 +1064,26 @@ 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;
 
     const req = makeInboundRequest({ content: 'hello needs_confirm' });
     await handleChannelInbound(req, noopProcessMessage, 'token', orchestrator);
 
-    // Wait for the background async to complete (poll timeout is 600ms + one poll interval of 500ms)
-    await new Promise((resolve) => setTimeout(resolve, 1500));
+    // Wait for the background async to complete
+    await new Promise((resolve) => setTimeout(resolve, 800));
 
     // markProcessed SHOULD have been called — the run is waiting for approval,
     // and the post-decision delivery path will handle the final reply.
@@ -1112,6 +1099,125 @@ describe('poll timeout handling by run state', () => {
     _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 () => {
     const linkSpy = spyOn(channelDeliveryStore, 'linkMessage').mockImplementation(() => {});
     const markSpy = spyOn(channelDeliveryStore, 'markProcessed');
@@ -1165,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 () => {
@@ -1279,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 () => {
@@ -1337,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',
@@ -1525,7 +1635,9 @@ describe('SMS guardian verify intercept', () => {
     const replyArgs = deliverSpy.mock.calls[0];
     const replyPayload = replyArgs[1] as { chatId: string; text: string };
     expect(replyPayload.chatId).toBe('sms-chat-verify');
-    expect(replyPayload.text).toContain('Guardian verified successfully');
+    expect(typeof replyPayload.text).toBe('string');
+    expect(replyPayload.text.toLowerCase()).toContain('guardian');
+    expect(replyPayload.text.toLowerCase()).toContain('verif');
 
     deliverSpy.mockRestore();
   });
@@ -1558,7 +1670,9 @@ describe('SMS guardian verify intercept', () => {
     expect(deliverSpy).toHaveBeenCalled();
     const replyArgs = deliverSpy.mock.calls[0];
     const replyPayload = replyArgs[1] as { chatId: string; text: string };
-    expect(replyPayload.text).toContain('Verification failed');
+    expect(typeof replyPayload.text).toBe('string');
+    expect(replyPayload.text.toLowerCase()).toContain('verif');
+    expect(replyPayload.text.toLowerCase()).toContain('failed');
 
     deliverSpy.mockRestore();
   });
@@ -1570,7 +1684,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 () => {
@@ -1644,7 +1757,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 () => {
@@ -1800,10 +1924,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);
 
@@ -1823,11 +1946,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(
-      (call) => typeof call[1] === 'object' && (call[1] as { text?: string }).text?.includes('no guardian has been set up'),
+    // The deny decision should carry guardian setup context for assistant reply generation.
+    expect(typeof decisionArgs[2]).toBe('string');
+    expect((decisionArgs[2] as string).toLowerCase()).toContain('no guardian');
+
+    // 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?.toLowerCase().includes('no guardian'),
     );
-    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();
@@ -1916,11 +2043,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).toLowerCase()).toContain('no guardian');
+
+    // 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'),
+      (call) => typeof call[1] === 'object' && (call[1] as { text?: string }).text?.toLowerCase().includes('no guardian'),
     );
-    expect(denialCalls.length).toBeGreaterThanOrEqual(1);
+    expect(denialCalls.length).toBe(0);
 
     deliverSpy.mockRestore();
   });
@@ -1932,7 +2067,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 () => {
@@ -1962,9 +2096,9 @@ describe('guardian-with-binding path regression', () => {
     const approvalArgs = approvalSpy.mock.calls[0];
     expect(approvalArgs[1]).toBe('guardian-chat-1');
 
-    // Requester should have been notified the request was sent to the guardian
+    // Requester should have been notified the request was forwarded to the guardian
     const notifyCalls = deliverSpy.mock.calls.filter(
-      (call) => typeof call[1] === 'object' && (call[1] as { text?: string }).text?.includes('has been sent to the guardian for approval'),
+      (call) => typeof call[1] === 'object' && (call[1] as { text?: string }).text?.toLowerCase().includes('guardian'),
     );
     expect(notifyCalls.length).toBeGreaterThanOrEqual(1);
 
@@ -2004,6 +2138,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();
+  });
 });
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -2012,7 +2193,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 () => {
@@ -2047,14 +2227,14 @@ describe('guardian delivery failure → denial', () => {
 
     // Requester should have been notified that delivery failed
     const failureCalls = deliverSpy.mock.calls.filter(
-      (call) => typeof call[1] === 'object' && (call[1] as { text?: string }).text?.includes('could not be sent to the guardian for approval'),
+      (call) => typeof call[1] === 'object' && (call[1] as { text?: string }).text?.toLowerCase().includes('denied'),
     );
     expect(failureCalls.length).toBeGreaterThanOrEqual(1);
 
-    // The "has been sent to the guardian for approval" success notice should
-    // NOT have been delivered (since delivery failed).
+    // The guardian_request_forwarded success notice should NOT have been
+    // delivered (since delivery failed).
     const successCalls = deliverSpy.mock.calls.filter(
-      (call) => typeof call[1] === 'object' && (call[1] as { text?: string }).text?.includes('has been sent to the guardian for approval'),
+      (call) => typeof call[1] === 'object' && (call[1] as { text?: string }).text?.toLowerCase().includes('forwarded'),
     );
     expect(successCalls.length).toBe(0);
 
@@ -2108,7 +2288,6 @@ describe('guardian delivery failure → denial', () => {
 
 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 () => {
@@ -2154,7 +2333,6 @@ describe('standard approval prompt delivery failure → auto-deny', () => {
 
 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 () => {
@@ -2241,7 +2419,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 () => {
@@ -2314,7 +2491,7 @@ describe('ambiguous plain-text decision with multiple pending requests', () => {
 
     // A disambiguation message should have been sent to the guardian
     const disambigCalls = deliverSpy.mock.calls.filter(
-      (call) => typeof call[1] === 'object' && (call[1] as { text?: string }).text?.includes('pending approval requests'),
+      (call) => typeof call[1] === 'object' && (call[1] as { text?: string }).text?.toLowerCase().includes('pending'),
     );
     expect(disambigCalls.length).toBeGreaterThanOrEqual(1);
 
@@ -2328,7 +2505,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 () => {
@@ -2472,7 +2648,12 @@ describe('deliver-once idempotency guard', () => {
 
 describe('final reply idempotency — no duplicate delivery', () => {
   beforeEach(() => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
+    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 () => {
@@ -2766,7 +2947,6 @@ describe('assistant-scoped guardian verification via handleChannelInbound', () =
   });
 
   test('actor role resolution uses threaded assistantId', async () => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
 
     // Create guardian binding for asst-role-X
     createBinding({
@@ -2800,7 +2980,6 @@ describe('assistant-scoped guardian verification via handleChannelInbound', () =
   });
 
   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({
@@ -2856,16 +3035,87 @@ describe('assistant-scoped guardian verification via handleChannelInbound', () =
     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 decoupled from CHANNEL_APPROVALS_ENABLED
+// 27. Guardian enforcement behavior
 // ═══════════════════════════════════════════════════════════════════════════
 
-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;
+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',
@@ -2874,31 +3124,28 @@ describe('guardian enforcement independence from approval flag', () => {
       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 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: 'hello world',
+      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));
 
-    // 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);
+    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 () => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
 
     // Create a guardian binding — guardian enforcement is active
     createBinding({
@@ -2928,20 +3175,21 @@ describe('guardian enforcement independence from approval flag', () => {
     // 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();
+    // 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).toLowerCase()).toContain('identity');
+
+    // No separate deterministic denial notice should be emitted here.
     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'));
-      },
+      (call) => typeof call[1] === 'object'
+        && ((call[1] as { text?: string }).text ?? '').toLowerCase().includes('identity'),
     );
-    expect(denialCalls.length).toBeGreaterThanOrEqual(1);
+    expect(denialCalls.length).toBe(0);
 
     // Auto-deny path should never prompt for approval
     expect(approvalSpy).not.toHaveBeenCalled();
@@ -2950,25 +3198,40 @@ describe('guardian enforcement independence from approval flag', () => {
     approvalSpy.mockRestore();
   });
 
-  test('missing senderExternalUserId without guardian binding uses default flow', async () => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
+  test('missing senderExternalUserId without guardian binding fails closed', async () => {
 
-    // No guardian binding exists — default behavior should be preserved
-    const orchestrator = makeMockOrchestrator();
+    // 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: 'hello world',
+      content: 'do something dangerous',
       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);
+    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).toLowerCase()).toContain('identity');
+
+    const denialCalls = deliverSpy.mock.calls.filter(
+      (call) => typeof call[1] === 'object'
+        && ((call[1] as { text?: string }).text ?? '').toLowerCase().includes('identity'),
+    );
+    expect(denialCalls.length).toBe(0);
+    expect(approvalSpy).not.toHaveBeenCalled();
 
     deliverSpy.mockRestore();
+    approvalSpy.mockRestore();
   });
 });
 
@@ -3119,7 +3382,6 @@ describe('handleChannelInbound gatewayOriginSecret integration', () => {
 
 describe('unknown actor identity — forceStrictSideEffects', () => {
   beforeEach(() => {
-    process.env.CHANNEL_APPROVALS_ENABLED = 'true';
   });
 
   test('unknown sender (no senderExternalUserId) with guardian binding gets forceStrictSideEffects', async () => {