@vellumai/assistant 0.3.4 → 0.3.6

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

@@ -54,6 +54,7 @@ import * as conversationStore from '../memory/conversation-store.js';
 import {
   createBinding,
   createApprovalRequest,
+  getAllPendingApprovalsByGuardianChat,
   getPendingApprovalForRun,
   getUnresolvedApprovalForRun,
 } from '../memory/channel-guardian-store.js';
@@ -355,10 +356,10 @@ describe('inbound text matching approval phrases triggers decision handling', ()
 });
 
 // ═══════════════════════════════════════════════════════════════════════════
-// 4. Non-decision messages during pending approval trigger reminder
+// 4. Non-decision messages during pending approval (no conversational engine)
 // ═══════════════════════════════════════════════════════════════════════════
 
-describe('non-decision messages during pending approval trigger reminder', () => {
+describe('non-decision messages during pending approval (legacy fallback)', () => {
   beforeEach(() => {
     createBinding({
       assistantId: 'self',
@@ -368,9 +369,8 @@ describe('non-decision messages during pending approval trigger reminder', () =>
     });
   });
 
-  test('sends a reminder prompt when message is not a decision', async () => {
+  test('sends a status reply when message is not a decision and no conversational engine', async () => {
     const orchestrator = makeMockOrchestrator();
-    const deliverSpy = spyOn(gatewayClient, 'deliverApprovalPrompt').mockResolvedValue(undefined);
     const replySpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
 
     const initReq = makeInboundRequest({ content: 'init' });
@@ -391,18 +391,19 @@ describe('non-decision messages during pending approval trigger reminder', () =>
     const body = await res.json() as Record<string, unknown>;
 
     expect(body.accepted).toBe(true);
-    expect(body.approval).toBe('reminder_sent');
+    expect(body.approval).toBe('assistant_turn');
 
-    // The approval prompt delivery should have been called
-    expect(deliverSpy).toHaveBeenCalled();
-    const callArgs = deliverSpy.mock.calls[0];
-    // The text should contain the reminder prefix
-    expect(callArgs[2]).toContain("I'm still waiting");
-    // The approval UI metadata should be present
-    expect(callArgs[3]).toBeDefined();
-    expect(callArgs[3]!.runId).toBe(run.id);
+    // A status reply should have been delivered via deliverChannelReply
+    expect(replySpy).toHaveBeenCalled();
+    const statusCall = replySpy.mock.calls.find(
+      (call) => typeof call[1] === 'object' && (call[1] as { chatId?: string }).chatId === 'chat-123',
+    );
+    expect(statusCall).toBeDefined();
+    const statusPayload = statusCall![1] as { text?: string };
+    // The status text is generated by composeApprovalMessageGenerative
+    // with reminder_prompt scenario — it should mention a pending approval.
+    expect(statusPayload.text).toContain('pending approval request');
 
-    deliverSpy.mockRestore();
     replySpy.mockRestore();
   });
 });
@@ -1522,10 +1523,10 @@ describe('SMS channel approval decisions', () => {
     deliverSpy.mockRestore();
   });
 
-  test('non-decision SMS message during pending approval triggers reminder with plain-text fallback', async () => {
+  test('non-decision SMS message during pending approval sends status reply', async () => {
     const orchestrator = makeMockOrchestrator();
-    const deliverSpy = spyOn(gatewayClient, 'deliverApprovalPrompt').mockResolvedValue(undefined);
-    const replySpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+    const approvalSpy = spyOn(gatewayClient, 'deliverApprovalPrompt').mockResolvedValue(undefined);
 
     const initReq = makeSmsInboundRequest({ content: 'init' });
     await handleChannelInbound(initReq, noopProcessMessage, 'token', orchestrator);
@@ -1543,17 +1544,23 @@ describe('SMS channel approval decisions', () => {
     const body = await res.json() as Record<string, unknown>;
 
     expect(body.accepted).toBe(true);
-    expect(body.approval).toBe('reminder_sent');
+    expect(body.approval).toBe('assistant_turn');
 
-    // SMS is a non-rich channel so the delivered text should include plain-text fallback
+    // SMS non-decision: status reply delivered via plain text
     expect(deliverSpy).toHaveBeenCalled();
-    const callArgs = deliverSpy.mock.calls[0];
-    const deliveredText = callArgs[2] as string;
-    expect(deliveredText).toContain("I'm still waiting");
-    expect(deliveredText).toContain('Reply "yes"');
+    expect(approvalSpy).not.toHaveBeenCalled();
+    const statusCall = deliverSpy.mock.calls.find(
+      (call) => typeof call[1] === 'object' && (call[1] as { chatId?: string }).chatId === 'sms-chat-123',
+    );
+    expect(statusCall).toBeDefined();
+    const statusPayload = statusCall![1] as { text?: string; approval?: unknown };
+    const deliveredText = statusPayload.text ?? '';
+    // Status text from composeApprovalMessageGenerative with reminder_prompt scenario
+    expect(deliveredText).toContain('pending approval request');
+    expect(statusPayload.approval).toBeUndefined();
 
     deliverSpy.mockRestore();
-    replySpy.mockRestore();
+    approvalSpy.mockRestore();
   });
 
   test('sourceChannel "sms" is passed to orchestrator.startRun', async () => {
@@ -1635,7 +1642,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();
   });
@@ -1668,7 +1677,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();
   });
@@ -1751,7 +1762,7 @@ describe('SMS non-guardian actor gating', () => {
   });
 });
 
-describe('plain-text fallback surfacing for non-rich channels', () => {
+describe('non-decision status reply for different channels', () => {
   beforeEach(() => {
     createBinding({
       assistantId: 'self',
@@ -1761,19 +1772,18 @@ describe('plain-text fallback surfacing for non-rich channels', () => {
     });
     createBinding({
       assistantId: 'self',
-      channel: 'http-api',
+      channel: 'sms',
       guardianExternalUserId: 'telegram-user-default',
       guardianDeliveryChatId: 'chat-123',
     });
   });
 
-  test('reminder prompt includes plainTextFallback for non-rich channel (http-api)', async () => {
+  test('non-decision message on non-rich channel (sms) sends status reply', async () => {
     const orchestrator = makeMockOrchestrator();
-    const deliverSpy = spyOn(gatewayClient, 'deliverApprovalPrompt').mockResolvedValue(undefined);
-    const replySpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
 
-    // Establish the conversation using http-api (non-rich channel)
-    const initReq = makeInboundRequest({ content: 'init', sourceChannel: 'http-api' });
+    // Establish the conversation using sms (non-rich channel)
+    const initReq = makeInboundRequest({ content: 'init', sourceChannel: 'sms' });
     await handleChannelInbound(initReq, noopProcessMessage, 'token', orchestrator);
 
     const db = getDb();
@@ -1784,30 +1794,28 @@ describe('plain-text fallback surfacing for non-rich channels', () => {
     const run = createRun(conversationId!);
     setRunConfirmation(run.id, sampleConfirmation);
 
-    // Send a non-decision message to trigger a reminder
-    const req = makeInboundRequest({ content: 'what is happening?', sourceChannel: 'http-api' });
+    // Send a non-decision message
+    const req = makeInboundRequest({ content: 'what is happening?', sourceChannel: 'sms' });
     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('reminder_sent');
+    expect(body.approval).toBe('assistant_turn');
 
-    // The delivered text should include the plainTextFallback instructions
+    // Status reply delivered via deliverChannelReply
     expect(deliverSpy).toHaveBeenCalled();
-    const callArgs = deliverSpy.mock.calls[0];
-    const deliveredText = callArgs[2] as string;
-    // For non-rich channels, the text should contain both the reminder prefix
-    // AND the plainTextFallback instructions (e.g. "Reply yes to approve")
-    expect(deliveredText).toContain("I'm still waiting");
-    expect(deliveredText).toContain('Reply "yes"');
+    const statusCall = deliverSpy.mock.calls.find(
+      (call) => typeof call[1] === 'object' && (call[1] as { chatId?: string }).chatId === 'chat-123',
+    );
+    expect(statusCall).toBeDefined();
+    const statusPayload = statusCall![1] as { text?: string };
+    expect(statusPayload.text).toContain('pending approval request');
 
     deliverSpy.mockRestore();
-    replySpy.mockRestore();
   });
 
-  test('reminder prompt does NOT include plainTextFallback for telegram (rich channel)', async () => {
+  test('non-decision message on telegram sends status reply', async () => {
     const orchestrator = makeMockOrchestrator();
-    const deliverSpy = spyOn(gatewayClient, 'deliverApprovalPrompt').mockResolvedValue(undefined);
     const replySpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
 
     // Establish the conversation using telegram (rich channel)
@@ -1822,25 +1830,23 @@ describe('plain-text fallback surfacing for non-rich channels', () => {
     const run = createRun(conversationId!);
     setRunConfirmation(run.id, sampleConfirmation);
 
-    // Send a non-decision message to trigger a reminder
+    // Send a non-decision message
     const req = makeInboundRequest({ content: 'what is happening?', sourceChannel: 'telegram' });
     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('reminder_sent');
+    expect(body.approval).toBe('assistant_turn');
 
-    // For rich channels (telegram), the delivered text should be just the
-    // promptText (with reminder prefix) — NOT the plainTextFallback.
-    expect(deliverSpy).toHaveBeenCalled();
-    const callArgs = deliverSpy.mock.calls[0];
-    const deliveredText = callArgs[2] as string;
-    expect(deliveredText).toContain("I'm still waiting");
-    // The raw promptText does not contain "Reply" instructions — those are
-    // only in the plainTextFallback.
-    expect(deliveredText).not.toContain('Reply "yes"');
+    // Status reply delivered via deliverChannelReply
+    expect(replySpy).toHaveBeenCalled();
+    const statusCall = replySpy.mock.calls.find(
+      (call) => typeof call[1] === 'object' && (call[1] as { chatId?: string }).chatId === 'chat-123',
+    );
+    expect(statusCall).toBeDefined();
+    const statusPayload = statusCall![1] as { text?: string };
+    expect(statusPayload.text).toContain('pending approval request');
 
-    deliverSpy.mockRestore();
     replySpy.mockRestore();
   });
 });
@@ -1944,11 +1950,11 @@ describe('fail-closed guardian gate — unverified channel', () => {
 
     // 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');
+    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?.includes('no guardian has been set up'),
+      (call) => typeof call[1] === 'object' && (call[1] as { text?: string }).text?.toLowerCase().includes('no guardian'),
     );
     expect(deterministicNoticeCalls.length).toBe(0);
 
@@ -2045,11 +2051,11 @@ describe('fail-closed guardian gate — unverified channel', () => {
     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');
+    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).toBe(0);
 
@@ -2092,9 +2098,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);
 
@@ -2184,14 +2190,14 @@ describe('guardian-with-binding path regression', () => {
 });
 
 // ═══════════════════════════════════════════════════════════════════════════
-// 20. Guardian delivery failure denial (WS-2)
+// 20. Guardian rich-delivery failure fallback (WS-2)
 // ═══════════════════════════════════════════════════════════════════════════
 
-describe('guardian delivery failure → denial', () => {
+describe('guardian delivery failure → text fallback', () => {
   beforeEach(() => {
   });
 
-  test('delivery failure denies run and notifies requester', async () => {
+  test('rich delivery failure falls back to plain text and keeps request pending', async () => {
     createBinding({
       assistantId: 'self',
       channel: 'telegram',
@@ -2216,29 +2222,30 @@ describe('guardian delivery failure → denial', () => {
     await handleChannelInbound(req, noopProcessMessage, 'token', orchestrator);
     await new Promise((resolve) => setTimeout(resolve, 1200));
 
-    // The run should have been denied
-    expect(orchestrator.submitDecision).toHaveBeenCalled();
-    const decisionArgs = (orchestrator.submitDecision as ReturnType<typeof mock>).mock.calls[0];
-    expect(decisionArgs[1]).toBe('deny');
+    // Rich button delivery failed, but plain-text fallback succeeded.
+    expect(orchestrator.submitDecision).not.toHaveBeenCalled();
+    expect(approvalSpy).toHaveBeenCalled();
 
-    // 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'),
+    // Guardian should have received a parser-compatible plain-text approval prompt.
+    const guardianPromptCalls = deliverSpy.mock.calls.filter(
+      (call) =>
+        typeof call[1] === 'object' &&
+        (call[1] as { chatId?: string; text?: string }).chatId === 'guardian-chat-df' &&
+        ((call[1] as { text?: string }).text ?? '').includes('Reply "yes"'),
     );
-    expect(failureCalls.length).toBeGreaterThanOrEqual(1);
+    expect(guardianPromptCalls.length).toBeGreaterThanOrEqual(1);
 
-    // The "has been sent to the guardian for approval" success notice should
-    // NOT have been delivered (since delivery failed).
+    // Requester should still get the forwarded notice once fallback delivery works.
     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);
+    expect(successCalls.length).toBeGreaterThanOrEqual(1);
 
     deliverSpy.mockRestore();
     approvalSpy.mockRestore();
   });
 
-  test('no pending/unresolved approvals remain after delivery failure', async () => {
+  test('terminal run resolution clears approvals even when rich delivery falls back to text', async () => {
     createBinding({
       assistantId: 'self',
       channel: 'telegram',
@@ -2261,15 +2268,19 @@ describe('guardian delivery failure → denial', () => {
     await handleChannelInbound(req, noopProcessMessage, 'token', orchestrator);
     await new Promise((resolve) => setTimeout(resolve, 1200));
 
+    // Rich delivery failure alone should not apply an explicit deny decision.
+    expect(orchestrator.submitDecision).not.toHaveBeenCalled();
+
     // Verify the run ID was created
     const runId = orchestrator.realRunId();
     expect(runId).toBeTruthy();
 
-    // After delivery failure, there should be NO pending approval for the run
+    // This test orchestrator transitions the run to a terminal failed state,
+    // which resolves the approval record via run-completion cleanup.
     const pendingApproval = getPendingApprovalForRun(runId!);
     expect(pendingApproval).toBeNull();
 
-    // There should also be NO unresolved approval (it was set to 'denied')
+    // No unresolved approval should remain after terminal resolution.
     const unresolvedApproval = getUnresolvedApprovalForRun(runId!);
     expect(unresolvedApproval).toBeNull();
 
@@ -2279,14 +2290,14 @@ describe('guardian delivery failure → denial', () => {
 });
 
 // ═══════════════════════════════════════════════════════════════════════════
-// 20b. Standard approval prompt delivery failure → auto-deny (WS-B)
+// 20b. Standard rich prompt delivery failure → text fallback (WS-B)
 // ═══════════════════════════════════════════════════════════════════════════
 
-describe('standard approval prompt delivery failure → auto-deny', () => {
+describe('standard approval prompt delivery failure → text fallback', () => {
   beforeEach(() => {
   });
 
-  test('standard prompt delivery failure auto-denies the run (fail-closed)', async () => {
+  test('standard prompt rich-delivery failure falls back to plain text without auto-deny', 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(
@@ -2313,10 +2324,16 @@ describe('standard approval prompt delivery failure → auto-deny', () => {
     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');
+    expect(approvalSpy).toHaveBeenCalled();
+    expect(orchestrator.submitDecision).not.toHaveBeenCalled();
+
+    const fallbackCalls = deliverSpy.mock.calls.filter(
+      (call) =>
+        typeof call[1] === 'object' &&
+        (call[1] as { chatId?: string; text?: string }).chatId === 'chat-123' &&
+        ((call[1] as { text?: string }).text ?? '').includes('Reply "yes"'),
+    );
+    expect(fallbackCalls.length).toBeGreaterThanOrEqual(1);
 
     deliverSpy.mockRestore();
     approvalSpy.mockRestore();
@@ -2463,18 +2480,28 @@ describe('ambiguous plain-text decision with multiple pending requests', () => {
 
     const orchestrator = makeMockOrchestrator();
 
-    // Guardian sends plain-text "yes" — ambiguous because two approvals are pending
+    // Conversational engine that returns keep_pending for disambiguation
+    const mockConversationGenerator = mock(async (_ctx: unknown) => ({
+      disposition: 'keep_pending' as const,
+      replyText: 'You have 2 pending requests. Which one?',
+    }));
+
+    // Guardian sends plain-text "yes" — ambiguous because two approvals are pending.
+    // The conversational engine handles disambiguation by returning keep_pending.
     const req = makeInboundRequest({
       content: 'yes',
       externalChatId: 'guardian-ambig-chat',
       senderExternalUserId: 'guardian-ambig-user',
     });
 
-    const res = await handleChannelInbound(req, noopProcessMessage, 'token', orchestrator);
+    const res = await handleChannelInbound(
+      req, noopProcessMessage, 'token', orchestrator, 'self', undefined, undefined,
+      mockConversationGenerator,
+    );
     const body = await res.json() as Record<string, unknown>;
 
     expect(body.accepted).toBe(true);
-    expect(body.approval).toBe('guardian_decision_applied');
+    expect(body.approval).toBe('assistant_turn');
 
     // Neither approval should have been resolved — disambiguation was required
     const approvalA = getPendingApprovalForRun(runA.id);
@@ -2485,9 +2512,14 @@ describe('ambiguous plain-text decision with multiple pending requests', () => {
     // submitDecision should NOT have been called — no decision was applied
     expect(orchestrator.submitDecision).not.toHaveBeenCalled();
 
-    // A disambiguation message should have been sent to the guardian
+    // The conversational engine should have been called with both pending approvals
+    expect(mockConversationGenerator).toHaveBeenCalledTimes(1);
+    const engineCtx = mockConversationGenerator.mock.calls[0][0] as Record<string, unknown>;
+    expect((engineCtx.pendingApprovals as Array<unknown>)).toHaveLength(2);
+
+    // A disambiguation reply 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?.includes('pending'),
     );
     expect(disambigCalls.length).toBeGreaterThanOrEqual(1);
 
@@ -3178,12 +3210,12 @@ describe('guardian enforcement behavior', () => {
     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');
+    expect((lastDecision[2] as string).toLowerCase()).toContain('identity');
 
     // 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'),
+        && ((call[1] as { text?: string }).text ?? '').toLowerCase().includes('identity'),
     );
     expect(denialCalls.length).toBe(0);
 
@@ -3217,11 +3249,11 @@ describe('guardian enforcement behavior', () => {
     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');
+    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 ?? '').includes('identity could not be determined'),
+        && ((call[1] as { text?: string }).text ?? '').toLowerCase().includes('identity'),
     );
     expect(denialCalls.length).toBe(0);
     expect(approvalSpy).not.toHaveBeenCalled();
@@ -3534,3 +3566,1150 @@ describe('unknown actor identity — forceStrictSideEffects', () => {
     deliverSpy.mockRestore();
   });
 });
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Conversational approval engine — standard path
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe('conversational approval engine — standard path', () => {
+  beforeEach(() => {
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'telegram-user-default',
+      guardianDeliveryChatId: 'chat-123',
+    });
+  });
+
+  test('non-decision follow-up → engine returns keep_pending → assistant reply sent, run remains pending', async () => {
+    const orchestrator = makeMockOrchestrator();
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    const initReq = makeInboundRequest({ content: 'init' });
+    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);
+
+    deliverSpy.mockClear();
+
+    // Mock conversational engine that returns keep_pending
+    const mockConversationGenerator = mock(async (_ctx: unknown) => ({
+      disposition: 'keep_pending' as const,
+      replyText: 'There is a pending shell command. Would you like to approve or deny it?',
+    }));
+
+    const req = makeInboundRequest({ content: 'what does this command do?' });
+    const res = await handleChannelInbound(
+      req, noopProcessMessage, 'token', orchestrator, 'self', undefined, undefined,
+      mockConversationGenerator,
+    );
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(body.accepted).toBe(true);
+    expect(body.approval).toBe('assistant_turn');
+
+    // The engine reply should have been delivered
+    expect(deliverSpy).toHaveBeenCalled();
+    const replyCall = deliverSpy.mock.calls.find(
+      (call) => typeof call[1] === 'object' && (call[1] as { text?: string }).text?.includes('pending shell command'),
+    );
+    expect(replyCall).toBeDefined();
+
+    // The orchestrator should NOT have received a decision
+    expect(orchestrator.submitDecision).not.toHaveBeenCalled();
+
+    deliverSpy.mockRestore();
+  });
+
+  test('natural-language approval → engine returns approve_once → decision applied', async () => {
+    const orchestrator = makeMockOrchestrator();
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    const initReq = makeInboundRequest({ content: 'init' });
+    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);
+
+    deliverSpy.mockClear();
+
+    // Mock conversational engine that returns approve_once
+    const mockConversationGenerator = mock(async (_ctx: unknown) => ({
+      disposition: 'approve_once' as const,
+      replyText: 'Got it, approving the shell command.',
+    }));
+
+    const req = makeInboundRequest({ content: 'yeah go ahead and run it' });
+    const res = await handleChannelInbound(
+      req, noopProcessMessage, 'token', orchestrator, 'self', undefined, undefined,
+      mockConversationGenerator,
+    );
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(body.accepted).toBe(true);
+    expect(body.approval).toBe('decision_applied');
+
+    // The orchestrator should have received an allow decision
+    expect(orchestrator.submitDecision).toHaveBeenCalledWith(run.id, 'allow');
+
+    // The engine reply should have been delivered
+    const replyCall = deliverSpy.mock.calls.find(
+      (call) => typeof call[1] === 'object' && (call[1] as { text?: string }).text?.includes('approving the shell command'),
+    );
+    expect(replyCall).toBeDefined();
+
+    deliverSpy.mockRestore();
+  });
+
+  test('"nevermind" style message → engine returns reject → rejection applied', async () => {
+    const orchestrator = makeMockOrchestrator();
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    const initReq = makeInboundRequest({ content: 'init' });
+    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);
+
+    deliverSpy.mockClear();
+
+    // Mock conversational engine that returns reject
+    const mockConversationGenerator = mock(async (_ctx: unknown) => ({
+      disposition: 'reject' as const,
+      replyText: 'No problem, I\'ve cancelled the shell command.',
+    }));
+
+    const req = makeInboundRequest({ content: 'nevermind, don\'t run that' });
+    const res = await handleChannelInbound(
+      req, noopProcessMessage, 'token', orchestrator, 'self', undefined, undefined,
+      mockConversationGenerator,
+    );
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(body.accepted).toBe(true);
+    expect(body.approval).toBe('decision_applied');
+
+    // The orchestrator should have received a deny decision
+    expect(orchestrator.submitDecision).toHaveBeenCalledWith(run.id, 'deny');
+
+    // The engine reply should have been delivered
+    const replyCall = deliverSpy.mock.calls.find(
+      (call) => typeof call[1] === 'object' && (call[1] as { text?: string }).text?.includes('cancelled the shell command'),
+    );
+    expect(replyCall).toBeDefined();
+
+    deliverSpy.mockRestore();
+  });
+
+  test('callback button still takes priority even with conversational engine present', async () => {
+    const orchestrator = makeMockOrchestrator();
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    const initReq = makeInboundRequest({ content: 'init' });
+    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);
+
+    // Mock conversational engine — should NOT be called for callback buttons
+    const mockConversationGenerator = mock(async (_ctx: unknown) => ({
+      disposition: 'keep_pending' as const,
+      replyText: 'This should not be called',
+    }));
+
+    const req = makeInboundRequest({
+      content: '',
+      callbackData: `apr:${run.id}:approve_once`,
+    });
+
+    const res = await handleChannelInbound(
+      req, noopProcessMessage, 'token', orchestrator, 'self', undefined, undefined,
+      mockConversationGenerator,
+    );
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(body.accepted).toBe(true);
+    expect(body.approval).toBe('decision_applied');
+
+    // The callback button should have been used directly, not the engine
+    expect(mockConversationGenerator).not.toHaveBeenCalled();
+    expect(orchestrator.submitDecision).toHaveBeenCalledWith(run.id, 'allow');
+
+    deliverSpy.mockRestore();
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Guardian conversational approval engine tests
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe('guardian conversational approval via conversation engine', () => {
+  beforeEach(() => {
+  });
+
+  test('guardian follow-up clarification: engine returns keep_pending, reply sent, run remains pending', async () => {
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'guardian-conv-user',
+      guardianDeliveryChatId: 'guardian-conv-chat',
+    });
+
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    const convId = 'conv-guardian-clarify';
+    ensureConversation(convId);
+    const run = createRun(convId);
+    setRunConfirmation(run.id, sampleConfirmation);
+
+    createApprovalRequest({
+      runId: run.id,
+      conversationId: convId,
+      channel: 'telegram',
+      requesterExternalUserId: 'requester-clarify',
+      requesterChatId: 'chat-requester-clarify',
+      guardianExternalUserId: 'guardian-conv-user',
+      guardianChatId: 'guardian-conv-chat',
+      toolName: 'shell',
+      expiresAt: Date.now() + 300_000,
+    });
+
+    const orchestrator = makeMockOrchestrator();
+
+    // Engine returns keep_pending for a clarification question
+    const mockConversationGenerator = mock(async (_ctx: unknown) => ({
+      disposition: 'keep_pending' as const,
+      replyText: 'Could you clarify which action you want me to approve?',
+    }));
+
+    const req = makeInboundRequest({
+      content: 'hmm what does this do?',
+      externalChatId: 'guardian-conv-chat',
+      senderExternalUserId: 'guardian-conv-user',
+    });
+
+    const res = await handleChannelInbound(
+      req, noopProcessMessage, 'token', orchestrator, 'self', undefined, undefined,
+      mockConversationGenerator,
+    );
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(body.accepted).toBe(true);
+    expect(body.approval).toBe('assistant_turn');
+
+    // The engine should have been called with role: 'guardian'
+    expect(mockConversationGenerator).toHaveBeenCalledTimes(1);
+    const callCtx = mockConversationGenerator.mock.calls[0][0] as Record<string, unknown>;
+    expect(callCtx.role).toBe('guardian');
+    expect(callCtx.allowedActions).toEqual(['approve_once', 'reject']);
+    expect(callCtx.userMessage).toBe('hmm what does this do?');
+
+    // Clarification reply delivered to the guardian's chat
+    const replyCall = deliverSpy.mock.calls.find(
+      (call) => (call[1] as { text?: string }).text === 'Could you clarify which action you want me to approve?',
+    );
+    expect(replyCall).toBeTruthy();
+
+    // The orchestrator should NOT have received a decision
+    expect(orchestrator.submitDecision).not.toHaveBeenCalled();
+
+    // The approval should still be pending
+    const pending = getAllPendingApprovalsByGuardianChat('telegram', 'guardian-conv-chat', 'self');
+    expect(pending).toHaveLength(1);
+
+    deliverSpy.mockRestore();
+  });
+
+  test('guardian natural-language approval: engine returns approve_once, decision applied', async () => {
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'guardian-nlp-user',
+      guardianDeliveryChatId: 'guardian-nlp-chat',
+    });
+
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    const convId = 'conv-guardian-nlp';
+    ensureConversation(convId);
+    const run = createRun(convId);
+    setRunConfirmation(run.id, sampleConfirmation);
+
+    createApprovalRequest({
+      runId: run.id,
+      conversationId: convId,
+      channel: 'telegram',
+      requesterExternalUserId: 'requester-nlp',
+      requesterChatId: 'chat-requester-nlp',
+      guardianExternalUserId: 'guardian-nlp-user',
+      guardianChatId: 'guardian-nlp-chat',
+      toolName: 'shell',
+      expiresAt: Date.now() + 300_000,
+    });
+
+    const orchestrator = makeMockOrchestrator();
+
+    // Engine returns approve_once decision
+    const mockConversationGenerator = mock(async (_ctx: unknown) => ({
+      disposition: 'approve_once' as const,
+      replyText: 'Approved! The shell command will proceed.',
+    }));
+
+    const req = makeInboundRequest({
+      content: 'yes go ahead and run it',
+      externalChatId: 'guardian-nlp-chat',
+      senderExternalUserId: 'guardian-nlp-user',
+    });
+
+    const res = await handleChannelInbound(
+      req, noopProcessMessage, 'token', orchestrator, 'self', undefined, undefined,
+      mockConversationGenerator,
+    );
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(body.accepted).toBe(true);
+    expect(body.approval).toBe('guardian_decision_applied');
+
+    // The orchestrator should have received an 'allow' decision
+    expect(orchestrator.submitDecision).toHaveBeenCalledTimes(1);
+    expect(orchestrator.submitDecision).toHaveBeenCalledWith(run.id, 'allow');
+
+    // The approval record should have been updated (no longer pending)
+    const pending = getAllPendingApprovalsByGuardianChat('telegram', 'guardian-nlp-chat', 'self');
+    expect(pending).toHaveLength(0);
+
+    // The engine context excluded approve_always for guardians
+    const callCtx = mockConversationGenerator.mock.calls[0][0] as Record<string, unknown>;
+    expect(callCtx.allowedActions).toEqual(['approve_once', 'reject']);
+    expect((callCtx.allowedActions as string[])).not.toContain('approve_always');
+
+    deliverSpy.mockRestore();
+  });
+
+  test('guardian callback button approve_always is downgraded to approve_once', async () => {
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'guardian-dg-user',
+      guardianDeliveryChatId: 'guardian-dg-chat',
+    });
+
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    const convId = 'conv-guardian-downgrade';
+    ensureConversation(convId);
+    const run = createRun(convId);
+    setRunConfirmation(run.id, sampleConfirmation);
+
+    createApprovalRequest({
+      runId: run.id,
+      conversationId: convId,
+      channel: 'telegram',
+      requesterExternalUserId: 'requester-dg',
+      requesterChatId: 'chat-requester-dg',
+      guardianExternalUserId: 'guardian-dg-user',
+      guardianChatId: 'guardian-dg-chat',
+      toolName: 'shell',
+      expiresAt: Date.now() + 300_000,
+    });
+
+    const orchestrator = makeMockOrchestrator();
+
+    // Guardian clicks approve_always via callback button
+    const req = makeInboundRequest({
+      content: '',
+      externalChatId: 'guardian-dg-chat',
+      callbackData: `apr:${run.id}:approve_always`,
+      senderExternalUserId: 'guardian-dg-user',
+    });
+
+    const res = await handleChannelInbound(
+      req, noopProcessMessage, 'token', orchestrator, 'self', undefined, undefined,
+      undefined,
+    );
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(body.accepted).toBe(true);
+    expect(body.approval).toBe('guardian_decision_applied');
+
+    // approve_always should have been downgraded to approve_once ('allow')
+    expect(orchestrator.submitDecision).toHaveBeenCalledTimes(1);
+    expect(orchestrator.submitDecision).toHaveBeenCalledWith(run.id, 'allow');
+
+    deliverSpy.mockRestore();
+  });
+
+  test('multi-pending guardian disambiguation: engine requests clarification', async () => {
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'guardian-multi-user',
+      guardianDeliveryChatId: 'guardian-multi-chat',
+    });
+
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    const convA = 'conv-multi-a';
+    const convB = 'conv-multi-b';
+    ensureConversation(convA);
+    ensureConversation(convB);
+
+    const runA = createRun(convA);
+    setRunConfirmation(runA.id, { ...sampleConfirmation, toolUseId: 'req-multi-a' });
+
+    const runB = createRun(convB);
+    setRunConfirmation(runB.id, { ...sampleConfirmation, toolName: 'file_edit', toolUseId: 'req-multi-b' });
+
+    createApprovalRequest({
+      runId: runA.id,
+      conversationId: convA,
+      channel: 'telegram',
+      requesterExternalUserId: 'requester-multi-a',
+      requesterChatId: 'chat-requester-multi-a',
+      guardianExternalUserId: 'guardian-multi-user',
+      guardianChatId: 'guardian-multi-chat',
+      toolName: 'shell',
+      expiresAt: Date.now() + 300_000,
+    });
+
+    createApprovalRequest({
+      runId: runB.id,
+      conversationId: convB,
+      channel: 'telegram',
+      requesterExternalUserId: 'requester-multi-b',
+      requesterChatId: 'chat-requester-multi-b',
+      guardianExternalUserId: 'guardian-multi-user',
+      guardianChatId: 'guardian-multi-chat',
+      toolName: 'file_edit',
+      expiresAt: Date.now() + 300_000,
+    });
+
+    const orchestrator = makeMockOrchestrator();
+
+    // Engine returns keep_pending for disambiguation
+    const mockConversationGenerator = mock(async (_ctx: unknown) => ({
+      disposition: 'keep_pending' as const,
+      replyText: 'You have 2 pending requests: shell and file_edit. Which one?',
+    }));
+
+    const req = makeInboundRequest({
+      content: 'approve it',
+      externalChatId: 'guardian-multi-chat',
+      senderExternalUserId: 'guardian-multi-user',
+    });
+
+    const res = await handleChannelInbound(
+      req, noopProcessMessage, 'token', orchestrator, 'self', undefined, undefined,
+      mockConversationGenerator,
+    );
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(body.accepted).toBe(true);
+    expect(body.approval).toBe('assistant_turn');
+
+    // The engine should have received both pending approvals
+    expect(mockConversationGenerator).toHaveBeenCalledTimes(1);
+    const engineCtx = mockConversationGenerator.mock.calls[0][0] as Record<string, unknown>;
+    expect((engineCtx.pendingApprovals as Array<unknown>)).toHaveLength(2);
+    expect(engineCtx.role).toBe('guardian');
+
+    // Both approvals should remain pending
+    const pendingA = getPendingApprovalForRun(runA.id);
+    const pendingB = getPendingApprovalForRun(runB.id);
+    expect(pendingA).not.toBeNull();
+    expect(pendingB).not.toBeNull();
+
+    // submitDecision should NOT have been called
+    expect(orchestrator.submitDecision).not.toHaveBeenCalled();
+
+    // Disambiguation reply delivered to guardian
+    const disambigCall = deliverSpy.mock.calls.find(
+      (call) => (call[1] as { text?: string }).text?.includes('2 pending requests'),
+    );
+    expect(disambigCall).toBeTruthy();
+
+    deliverSpy.mockRestore();
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// keep_pending must remain conversational (no deterministic fallback)
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe('keep_pending remains conversational — standard path', () => {
+  beforeEach(() => {
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'telegram-user-default',
+      guardianDeliveryChatId: 'chat-123',
+    });
+  });
+
+  test('explicit "approve" with keep_pending returns assistant_turn and does not auto-decide', async () => {
+    const orchestrator = makeMockOrchestrator();
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    const initReq = makeInboundRequest({ content: 'init' });
+    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);
+
+    const mockConversationGenerator = mock(async (_ctx: unknown) => ({
+      disposition: 'keep_pending' as const,
+      replyText: 'Before deciding, can you confirm the intent?',
+    }));
+
+    const req = makeInboundRequest({ content: 'approve' });
+    const res = await handleChannelInbound(
+      req, noopProcessMessage, 'token', orchestrator, 'self', undefined, undefined,
+      mockConversationGenerator,
+    );
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(body.accepted).toBe(true);
+    expect(body.approval).toBe('assistant_turn');
+    expect(orchestrator.submitDecision).not.toHaveBeenCalled();
+
+    const followupReply = deliverSpy.mock.calls.find(
+      (call) => (call[1] as { text?: string }).text?.includes('confirm the intent'),
+    );
+    expect(followupReply).toBeDefined();
+
+    deliverSpy.mockRestore();
+  });
+
+  test('keep_pending stays assistant_turn even if pending confirmation disappears mid-turn', async () => {
+    const orchestrator = makeMockOrchestrator();
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    const initReq = makeInboundRequest({ content: 'init' });
+    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);
+
+    const mockConversationGenerator = mock(async (_ctx: unknown) => {
+      db.$client.prepare('UPDATE message_runs SET pending_confirmation = NULL WHERE id = ?').run(run.id);
+      return {
+        disposition: 'keep_pending' as const,
+        replyText: 'Looks like that request is no longer pending.',
+      };
+    });
+
+    const req = makeInboundRequest({ content: 'deny' });
+    const res = await handleChannelInbound(
+      req, noopProcessMessage, 'token', orchestrator, 'self', undefined, undefined,
+      mockConversationGenerator,
+    );
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(body.accepted).toBe(true);
+    expect(body.approval).toBe('assistant_turn');
+    expect(orchestrator.submitDecision).not.toHaveBeenCalled();
+
+    const followupReply = deliverSpy.mock.calls.find(
+      (call) => (call[1] as { text?: string }).text?.includes('no longer pending'),
+    );
+    expect(followupReply).toBeDefined();
+
+    deliverSpy.mockRestore();
+  });
+});
+
+describe('keep_pending remains conversational — guardian path', () => {
+  test('guardian explicit "yes" with keep_pending returns assistant_turn without applying a decision', async () => {
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'guardian-user-fb',
+      guardianDeliveryChatId: 'guardian-chat-fb',
+    });
+
+    const orchestrator = makeMockOrchestrator();
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    const initReq = makeInboundRequest({
+      content: 'init',
+      externalChatId: 'requester-chat-fb',
+      senderExternalUserId: 'requester-user-fb',
+    });
+    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);
+
+    createApprovalRequest({
+      runId: run.id,
+      conversationId: conversationId!,
+      assistantId: 'self',
+      channel: 'telegram',
+      requesterExternalUserId: 'requester-user-fb',
+      requesterChatId: 'requester-chat-fb',
+      guardianExternalUserId: 'guardian-user-fb',
+      guardianChatId: 'guardian-chat-fb',
+      toolName: 'shell',
+      expiresAt: Date.now() + 300_000,
+    });
+
+    const mockConversationGenerator = mock(async (_ctx: unknown) => ({
+      disposition: 'keep_pending' as const,
+      replyText: 'Which run are you approving?',
+    }));
+
+    const guardianReq = makeInboundRequest({
+      content: 'yes',
+      externalChatId: 'guardian-chat-fb',
+      senderExternalUserId: 'guardian-user-fb',
+    });
+    const res = await handleChannelInbound(
+      guardianReq, noopProcessMessage, 'token', orchestrator, 'self', undefined, undefined,
+      mockConversationGenerator,
+    );
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(body.accepted).toBe(true);
+    expect(body.approval).toBe('assistant_turn');
+    expect(orchestrator.submitDecision).not.toHaveBeenCalled();
+
+    const followupReply = deliverSpy.mock.calls.find(
+      (call) => (call[1] as { text?: string }).text?.includes('Which run are you approving'),
+    );
+    expect(followupReply).toBeDefined();
+
+    deliverSpy.mockRestore();
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Fix: requester cancel of guardian-gated pending request (P2)
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe('requester cancel of guardian-gated pending request', () => {
+  beforeEach(() => {
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'guardian-cancel',
+      guardianDeliveryChatId: 'guardian-cancel-chat',
+    });
+  });
+
+  test('requester explicit "deny" can cancel when the conversation engine returns reject', async () => {
+    const orchestrator = makeMockOrchestrator();
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    // Create requester conversation and run
+    const initReq = makeInboundRequest({
+      content: 'init',
+      externalChatId: 'requester-cancel-chat',
+      senderExternalUserId: 'requester-cancel-user',
+    });
+    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);
+
+    // Create guardian approval request
+    createApprovalRequest({
+      runId: run.id,
+      conversationId: conversationId!,
+      assistantId: 'self',
+      channel: 'telegram',
+      requesterExternalUserId: 'requester-cancel-user',
+      requesterChatId: 'requester-cancel-chat',
+      guardianExternalUserId: 'guardian-cancel',
+      guardianChatId: 'guardian-cancel-chat',
+      toolName: 'shell',
+      expiresAt: Date.now() + 300_000,
+    });
+
+    deliverSpy.mockClear();
+
+    const mockConversationGenerator = mock(async (_ctx: unknown) => ({
+      disposition: 'reject' as const,
+      replyText: 'Cancelling this request now.',
+    }));
+
+    // Requester sends "deny" and the engine classifies it as reject.
+    const req = makeInboundRequest({
+      content: 'deny',
+      externalChatId: 'requester-cancel-chat',
+      senderExternalUserId: 'requester-cancel-user',
+    });
+    const res = await handleChannelInbound(
+      req, noopProcessMessage, 'token', orchestrator, 'self', undefined, undefined,
+      mockConversationGenerator,
+    );
+    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, 'deny');
+
+    // Guardian approval should be resolved
+    const approval = getPendingApprovalForRun(run.id);
+    expect(approval).toBeNull();
+
+    // Requester should have been notified (cancel notice)
+    const requesterReply = deliverSpy.mock.calls.find(
+      (call) => (call[1] as { chatId?: string }).chatId === 'requester-cancel-chat',
+    );
+    expect(requesterReply).toBeDefined();
+
+    // Guardian should have been notified of the cancellation
+    const guardianNotice = deliverSpy.mock.calls.find(
+      (call) => (call[1] as { chatId?: string }).chatId === 'guardian-cancel-chat',
+    );
+    expect(guardianNotice).toBeDefined();
+
+    deliverSpy.mockRestore();
+  });
+
+  test('requester "nevermind" via conversational engine cancels guardian-gated request', async () => {
+    const orchestrator = makeMockOrchestrator();
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    const initReq = makeInboundRequest({
+      content: 'init',
+      externalChatId: 'requester-cancel-chat',
+      senderExternalUserId: 'requester-cancel-user',
+    });
+    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);
+
+    createApprovalRequest({
+      runId: run.id,
+      conversationId: conversationId!,
+      assistantId: 'self',
+      channel: 'telegram',
+      requesterExternalUserId: 'requester-cancel-user',
+      requesterChatId: 'requester-cancel-chat',
+      guardianExternalUserId: 'guardian-cancel',
+      guardianChatId: 'guardian-cancel-chat',
+      toolName: 'shell',
+      expiresAt: Date.now() + 300_000,
+    });
+
+    deliverSpy.mockClear();
+
+    // Conversational engine recognises cancel intent and returns reject
+    const mockConversationGenerator = mock(async (_ctx: unknown) => ({
+      disposition: 'reject' as const,
+      replyText: 'OK, I have cancelled the pending request.',
+    }));
+
+    const req = makeInboundRequest({
+      content: 'actually never mind, cancel it',
+      externalChatId: 'requester-cancel-chat',
+      senderExternalUserId: 'requester-cancel-user',
+    });
+    const res = await handleChannelInbound(
+      req, noopProcessMessage, 'token', orchestrator, 'self', undefined, undefined,
+      mockConversationGenerator,
+    );
+    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, 'deny');
+
+    // Engine should have been called with reject-only allowed actions
+    expect(mockConversationGenerator).toHaveBeenCalledTimes(1);
+    const engineCtx = mockConversationGenerator.mock.calls[0][0] as Record<string, unknown>;
+    expect(engineCtx.allowedActions).toEqual(['reject']);
+
+    // Engine reply should have been delivered to requester
+    const replyCall = deliverSpy.mock.calls.find(
+      (call) => (call[1] as { text?: string }).text?.includes('cancelled the pending request'),
+    );
+    expect(replyCall).toBeDefined();
+
+    deliverSpy.mockRestore();
+  });
+
+  test('requester cancel returns stale_ignored when pending disappears before apply', async () => {
+    const orchestrator = makeMockOrchestrator();
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    const initReq = makeInboundRequest({
+      content: 'init',
+      externalChatId: 'requester-cancel-race-chat',
+      senderExternalUserId: 'requester-cancel-race-user',
+    });
+    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);
+
+    createApprovalRequest({
+      runId: run.id,
+      conversationId: conversationId!,
+      assistantId: 'self',
+      channel: 'telegram',
+      requesterExternalUserId: 'requester-cancel-race-user',
+      requesterChatId: 'requester-cancel-race-chat',
+      guardianExternalUserId: 'guardian-cancel',
+      guardianChatId: 'guardian-cancel-chat',
+      toolName: 'shell',
+      expiresAt: Date.now() + 300_000,
+    });
+
+    deliverSpy.mockClear();
+
+    const mockConversationGenerator = mock(async (_ctx: unknown) => {
+      db.$client.prepare('UPDATE message_runs SET pending_confirmation = NULL WHERE id = ?').run(run.id);
+      return {
+        disposition: 'reject' as const,
+        replyText: 'Cancelling that now.',
+      };
+    });
+
+    const req = makeInboundRequest({
+      content: 'never mind cancel',
+      externalChatId: 'requester-cancel-race-chat',
+      senderExternalUserId: 'requester-cancel-race-user',
+    });
+    const res = await handleChannelInbound(
+      req, noopProcessMessage, 'token', orchestrator, 'self', undefined, undefined,
+      mockConversationGenerator,
+    );
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(body.accepted).toBe(true);
+    expect(body.approval).toBe('stale_ignored');
+    expect(orchestrator.submitDecision).not.toHaveBeenCalled();
+
+    const staleReply = deliverSpy.mock.calls.find(
+      (call) => (call[1] as { text?: string }).text?.includes('already been resolved'),
+    );
+    expect(staleReply).toBeDefined();
+
+    deliverSpy.mockRestore();
+  });
+
+  test('requester non-cancel message with keep_pending returns conversational reply', async () => {
+    const orchestrator = makeMockOrchestrator();
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    const initReq = makeInboundRequest({
+      content: 'init',
+      externalChatId: 'requester-cancel-chat',
+      senderExternalUserId: 'requester-cancel-user',
+    });
+    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);
+
+    createApprovalRequest({
+      runId: run.id,
+      conversationId: conversationId!,
+      assistantId: 'self',
+      channel: 'telegram',
+      requesterExternalUserId: 'requester-cancel-user',
+      requesterChatId: 'requester-cancel-chat',
+      guardianExternalUserId: 'guardian-cancel',
+      guardianChatId: 'guardian-cancel-chat',
+      toolName: 'shell',
+      expiresAt: Date.now() + 300_000,
+    });
+
+    deliverSpy.mockClear();
+
+    // Engine returns keep_pending (not a cancel intent)
+    const mockConversationGenerator = mock(async (_ctx: unknown) => ({
+      disposition: 'keep_pending' as const,
+      replyText: 'Still waiting.',
+    }));
+
+    const req = makeInboundRequest({
+      content: 'what is happening?',
+      externalChatId: 'requester-cancel-chat',
+      senderExternalUserId: 'requester-cancel-user',
+    });
+    const res = await handleChannelInbound(
+      req, noopProcessMessage, 'token', orchestrator, 'self', undefined, undefined,
+      mockConversationGenerator,
+    );
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(body.accepted).toBe(true);
+    expect(body.approval).toBe('assistant_turn');
+    expect(orchestrator.submitDecision).not.toHaveBeenCalled();
+
+    // Should have received the conversational keep_pending reply
+    const pendingReply = deliverSpy.mock.calls.find(
+      (call) => (call[1] as { text?: string }).text?.includes('Still waiting.'),
+    );
+    expect(pendingReply).toBeDefined();
+
+    deliverSpy.mockRestore();
+  });
+
+  test('requester "approve" is blocked — self-approval not allowed even during cancel check', async () => {
+    const orchestrator = makeMockOrchestrator();
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    const initReq = makeInboundRequest({
+      content: 'init',
+      externalChatId: 'requester-cancel-chat',
+      senderExternalUserId: 'requester-cancel-user',
+    });
+    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);
+
+    createApprovalRequest({
+      runId: run.id,
+      conversationId: conversationId!,
+      assistantId: 'self',
+      channel: 'telegram',
+      requesterExternalUserId: 'requester-cancel-user',
+      requesterChatId: 'requester-cancel-chat',
+      guardianExternalUserId: 'guardian-cancel',
+      guardianChatId: 'guardian-cancel-chat',
+      toolName: 'shell',
+      expiresAt: Date.now() + 300_000,
+    });
+
+    deliverSpy.mockClear();
+
+    // Requester tries to self-approve while guardian approval is pending.
+    // Self-approval stays blocked in the requester-cancel path.
+    const req = makeInboundRequest({
+      content: 'approve',
+      externalChatId: 'requester-cancel-chat',
+      senderExternalUserId: 'requester-cancel-user',
+    });
+    const res = await handleChannelInbound(req, noopProcessMessage, 'token', orchestrator);
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(body.accepted).toBe(true);
+    // Should get the guardian-pending notice, NOT decision_applied
+    expect(body.approval).toBe('assistant_turn');
+    expect(orchestrator.submitDecision).not.toHaveBeenCalled();
+
+    deliverSpy.mockRestore();
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Fix: stale_ignored when engine decision races with concurrent resolution
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe('engine decision race condition — standard path', () => {
+  beforeEach(() => {
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'telegram-user-default',
+      guardianDeliveryChatId: 'chat-123',
+    });
+  });
+
+  test('returns stale_ignored when engine approves but run was already resolved', async () => {
+    const orchestrator = makeMockOrchestrator();
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    const initReq = makeInboundRequest({ content: 'init' });
+    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);
+
+    deliverSpy.mockClear();
+
+    // Engine returns approve_once, but clears the pending confirmation
+    // before handleChannelDecision is called (simulating race condition)
+    const mockConversationGenerator = mock(async (_ctx: unknown) => {
+      db.$client.prepare('UPDATE message_runs SET pending_confirmation = NULL WHERE id = ?').run(run.id);
+      return {
+        disposition: 'approve_once' as const,
+        replyText: 'Approved! Running the command now.',
+      };
+    });
+
+    const req = makeInboundRequest({ content: 'go ahead' });
+    const res = await handleChannelInbound(
+      req, noopProcessMessage, 'token', orchestrator, 'self', undefined, undefined,
+      mockConversationGenerator,
+    );
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(body.accepted).toBe(true);
+    expect(body.approval).toBe('stale_ignored');
+
+    // submitDecision should NOT have been called since there was no pending
+    expect(orchestrator.submitDecision).not.toHaveBeenCalled();
+
+    // The engine's optimistic "Approved!" reply should NOT have been delivered
+    const approvedReply = deliverSpy.mock.calls.find(
+      (call) => (call[1] as { text?: string }).text?.includes('Approved!'),
+    );
+    expect(approvedReply).toBeUndefined();
+
+    // A stale notice should have been delivered instead
+    const staleReply = deliverSpy.mock.calls.find(
+      (call) => (call[1] as { text?: string }).text?.includes('already been resolved'),
+    );
+    expect(staleReply).toBeDefined();
+
+    deliverSpy.mockRestore();
+  });
+});
+
+describe('engine decision race condition — guardian path', () => {
+  test('returns stale_ignored when guardian engine approves but run was already resolved', async () => {
+    createBinding({
+      assistantId: 'self',
+      channel: 'telegram',
+      guardianExternalUserId: 'guardian-race-user',
+      guardianDeliveryChatId: 'guardian-race-chat',
+    });
+
+    const orchestrator = makeMockOrchestrator();
+    const deliverSpy = spyOn(gatewayClient, 'deliverChannelReply').mockResolvedValue(undefined);
+
+    const initReq = makeInboundRequest({
+      content: 'init',
+      externalChatId: 'requester-race-chat',
+      senderExternalUserId: 'requester-race-user',
+    });
+    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);
+
+    createApprovalRequest({
+      runId: run.id,
+      conversationId: conversationId!,
+      assistantId: 'self',
+      channel: 'telegram',
+      requesterExternalUserId: 'requester-race-user',
+      requesterChatId: 'requester-race-chat',
+      guardianExternalUserId: 'guardian-race-user',
+      guardianChatId: 'guardian-race-chat',
+      toolName: 'shell',
+      expiresAt: Date.now() + 300_000,
+    });
+
+    deliverSpy.mockClear();
+
+    // Guardian engine returns approve_once, but clears pending confirmation
+    // to simulate a concurrent resolution (expiry sweep or requester cancel)
+    const mockConversationGenerator = mock(async (_ctx: unknown) => {
+      db.$client.prepare('UPDATE message_runs SET pending_confirmation = NULL WHERE id = ?').run(run.id);
+      return {
+        disposition: 'approve_once' as const,
+        replyText: 'Approved the request.',
+      };
+    });
+
+    const guardianReq = makeInboundRequest({
+      content: 'approve it',
+      externalChatId: 'guardian-race-chat',
+      senderExternalUserId: 'guardian-race-user',
+    });
+    const res = await handleChannelInbound(
+      guardianReq, noopProcessMessage, 'token', orchestrator, 'self', undefined, undefined,
+      mockConversationGenerator,
+    );
+    const body = await res.json() as Record<string, unknown>;
+
+    expect(body.accepted).toBe(true);
+    expect(body.approval).toBe('stale_ignored');
+
+    // submitDecision should NOT have been called
+    expect(orchestrator.submitDecision).not.toHaveBeenCalled();
+
+    // The engine's "Approved the request." should NOT be delivered
+    const optimisticReply = deliverSpy.mock.calls.find(
+      (call) => (call[1] as { text?: string }).text?.includes('Approved the request'),
+    );
+    expect(optimisticReply).toBeUndefined();
+
+    // A stale notice should have been delivered instead
+    const staleReply = deliverSpy.mock.calls.find(
+      (call) => (call[1] as { text?: string }).text?.includes('already been resolved'),
+    );
+    expect(staleReply).toBeDefined();
+
+    deliverSpy.mockRestore();
+  });
+});