@vellumai/assistant 0.3.16 → 0.3.18

package/src/__tests__/config-watcher.test.ts

@@ -73,6 +73,7 @@ const fakeWatcher = {
 };
 
 mock.module('node:fs', () => {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
   const actual = require('node:fs');
   return {
     ...actual,
@@ -93,10 +94,6 @@ mock.module('node:fs', () => {
   };
 });
 
-// Track refreshConfigFromSources calls
-let refreshConfigCalled = false;
-let refreshConfigReturn = false;
-
 // Mock config/loader and other dependencies that ConfigWatcher imports
 mock.module('../config/loader.js', () => ({
   getConfig: () => ({}),
@@ -107,16 +104,18 @@ mock.module('../memory/embedding-backend.js', () => ({
   clearEmbeddingBackendCache: () => {},
 }));
 
+let trustClearCacheCallCount = 0;
 mock.module('../permissions/trust-store.js', () => ({
-  clearCache: () => {},
+  clearCache: () => { trustClearCacheCallCount++; },
 }));
 
 mock.module('../providers/registry.js', () => ({
   initializeProviders: () => {},
 }));
 
+let resetAllowlistCallCount = 0;
 mock.module('../security/secret-allowlist.js', () => ({
-  resetAllowlist: () => {},
+  resetAllowlist: () => { resetAllowlistCallCount++; },
   validateAllowlistFile: () => [],
 }));
 
@@ -159,6 +158,8 @@ const onSessionEvict = () => { evictCallCount++; };
 beforeEach(() => {
   capturedWatchers.length = 0;
   evictCallCount = 0;
+  trustClearCacheCallCount = 0;
+  resetAllowlistCallCount = 0;
   watcher = new ConfigWatcher();
 });
 
@@ -209,8 +210,6 @@ describe('ConfigWatcher workspace file handlers', () => {
   });
 
   test('config.json change calls refreshConfigFromSources', async () => {
-    // Spy on refreshConfigFromSources to verify it is called
-    const originalRefresh = watcher.refreshConfigFromSources.bind(watcher);
     let refreshCalled = false;
     watcher.refreshConfigFromSources = () => {
       refreshCalled = true;
@@ -273,11 +272,6 @@ describe('ConfigWatcher workspace file handlers', () => {
 
 describe('ConfigWatcher protected directory handlers', () => {
   test('trust.json change calls clearTrustCache', async () => {
-    let trustCacheClearCalled = false;
-
-    // Re-mock trust-store to track calls
-    const { clearCache } = await import('../permissions/trust-store.js');
-
     watcher.start(onSessionEvict);
     const protectedWatcher = findWatcher(PROTECTED_DIR);
     expect(protectedWatcher).toBeDefined();
@@ -286,6 +280,8 @@ describe('ConfigWatcher protected directory handlers', () => {
     await new Promise((r) => setTimeout(r, 300));
     // trust.json should NOT trigger session eviction
     expect(evictCallCount).toBe(0);
+    // but clearCache should have been called
+    expect(trustClearCacheCallCount).toBe(1);
   });
 
   test('secret-allowlist.json change calls resetAllowlist', async () => {
@@ -297,6 +293,8 @@ describe('ConfigWatcher protected directory handlers', () => {
     await new Promise((r) => setTimeout(r, 300));
     // secret-allowlist.json should NOT trigger session eviction
     expect(evictCallCount).toBe(0);
+    // but resetAllowlist should have been called
+    expect(resetAllowlistCallCount).toBe(1);
   });
 });
 

package/src/__tests__/conversation-pairing.test.ts

@@ -2,8 +2,9 @@
  * Regression tests for notification conversation pairing.
  *
  * Validates that pairDeliveryWithConversation materializes conversations
- * and messages according to the channel's conversation strategy, and that
- * errors in pairing never break the notification pipeline.
+ * and messages according to the channel's conversation strategy, handles
+ * thread reuse decisions, and that errors in pairing never break the
+ * notification pipeline.
  */
 
 import { beforeEach, describe, expect, mock, test } from 'bun:test';
@@ -22,6 +23,9 @@ let mockMessageId = 'msg-001';
 let createConversationShouldThrow = false;
 let addMessageShouldThrow = false;
 
+/** Simulated existing conversations for getConversation mock. */
+let mockExistingConversations: Record<string, { id: string; source: string; title: string | null }> = {};
+
 const createConversationMock = mock((_opts?: unknown) => {
   if (createConversationShouldThrow) throw new Error('DB write failed');
   return { id: mockConversationId };
@@ -40,14 +44,19 @@ const addMessageMock = mock(
   },
 );
 
+const getConversationMock = mock((id: string) => {
+  return mockExistingConversations[id] ?? null;
+});
+
 mock.module('../memory/conversation-store.js', () => ({
   createConversation: createConversationMock,
   addMessage: addMessageMock,
+  getConversation: getConversationMock,
 }));
 
 import { pairDeliveryWithConversation } from '../notifications/conversation-pairing.js';
 import type { NotificationSignal } from '../notifications/signal.js';
-import type { NotificationChannel, RenderedChannelCopy } from '../notifications/types.js';
+import type { NotificationChannel, RenderedChannelCopy, ThreadAction } from '../notifications/types.js';
 
 // ── Test helpers ────────────────────────────────────────────────────────
 
@@ -82,10 +91,12 @@ describe('pairDeliveryWithConversation', () => {
   beforeEach(() => {
     createConversationMock.mockClear();
     addMessageMock.mockClear();
+    getConversationMock.mockClear();
     mockConversationId = 'conv-001';
     mockMessageId = 'msg-001';
     createConversationShouldThrow = false;
     addMessageShouldThrow = false;
+    mockExistingConversations = {};
   });
 
   // ── start_new_conversation (vellum) ─────────────────────────────────
@@ -99,6 +110,8 @@ describe('pairDeliveryWithConversation', () => {
     expect(result.conversationId).toBe('conv-001');
     expect(result.messageId).toBe('msg-001');
     expect(result.strategy).toBe('start_new_conversation');
+    expect(result.createdNewConversation).toBe(true);
+    expect(result.threadDecisionFallbackUsed).toBe(false);
     expect(createConversationMock).toHaveBeenCalledTimes(1);
     expect(addMessageMock).toHaveBeenCalledTimes(1);
     const callArgs = createConversationMock.mock.calls[0]![0] as Record<string, unknown>;
@@ -195,6 +208,7 @@ describe('pairDeliveryWithConversation', () => {
     expect(result.conversationId).toBe('conv-001');
     expect(result.messageId).toBe('msg-001');
     expect(result.strategy).toBe('continue_existing_conversation');
+    expect(result.createdNewConversation).toBe(true);
     expect(createConversationMock).toHaveBeenCalledTimes(1);
     const callArgs = createConversationMock.mock.calls[0]![0] as Record<string, unknown>;
     expect(callArgs.threadType).toBe('background');
@@ -218,10 +232,95 @@ describe('pairDeliveryWithConversation', () => {
     expect(result.conversationId).toBeNull();
     expect(result.messageId).toBeNull();
     expect(result.strategy).toBe('not_deliverable');
+    expect(result.createdNewConversation).toBe(false);
     expect(createConversationMock).not.toHaveBeenCalled();
     expect(addMessageMock).not.toHaveBeenCalled();
   });
 
+  // ── Thread reuse (reuse_existing) ─────────────────────────────────
+
+  test('reuses existing conversation when threadAction is reuse_existing and target is valid', async () => {
+    mockExistingConversations['conv-existing'] = {
+      id: 'conv-existing',
+      source: 'notification',
+      title: 'Previous Thread',
+    };
+
+    const signal = makeSignal();
+    const copy = makeCopy({ threadSeedMessage: 'Follow-up notification message content' });
+    const threadAction: ThreadAction = { action: 'reuse_existing', conversationId: 'conv-existing' };
+
+    const result = await pairDeliveryWithConversation(signal, 'vellum' as NotificationChannel, copy, { threadAction });
+
+    expect(result.conversationId).toBe('conv-existing');
+    expect(result.messageId).toBe('msg-001');
+    expect(result.createdNewConversation).toBe(false);
+    expect(result.threadDecisionFallbackUsed).toBe(false);
+    // Should NOT have created a new conversation — only addMessage should be called
+    expect(createConversationMock).not.toHaveBeenCalled();
+    expect(addMessageMock).toHaveBeenCalledTimes(1);
+    // Verify addMessage was called with the existing conversation ID
+    expect(addMessageMock.mock.calls[0]![0]).toBe('conv-existing');
+  });
+
+  test('falls back to new conversation when reuse target does not exist', async () => {
+    // No existing conversations — target is stale/invalid
+    const signal = makeSignal();
+    const copy = makeCopy();
+    const threadAction: ThreadAction = { action: 'reuse_existing', conversationId: 'conv-nonexistent' };
+
+    const result = await pairDeliveryWithConversation(signal, 'vellum' as NotificationChannel, copy, { threadAction });
+
+    expect(result.conversationId).toBe('conv-001');
+    expect(result.messageId).toBe('msg-001');
+    expect(result.createdNewConversation).toBe(true);
+    expect(result.threadDecisionFallbackUsed).toBe(true);
+    expect(createConversationMock).toHaveBeenCalledTimes(1);
+  });
+
+  test('falls back to new conversation when reuse target has wrong source', async () => {
+    // Conversation exists but was created by user, not notification
+    mockExistingConversations['conv-user'] = {
+      id: 'conv-user',
+      source: 'user',
+      title: 'User Thread',
+    };
+
+    const signal = makeSignal();
+    const copy = makeCopy();
+    const threadAction: ThreadAction = { action: 'reuse_existing', conversationId: 'conv-user' };
+
+    const result = await pairDeliveryWithConversation(signal, 'vellum' as NotificationChannel, copy, { threadAction });
+
+    expect(result.conversationId).toBe('conv-001');
+    expect(result.createdNewConversation).toBe(true);
+    expect(result.threadDecisionFallbackUsed).toBe(true);
+  });
+
+  test('creates new conversation when threadAction is start_new', async () => {
+    const signal = makeSignal();
+    const copy = makeCopy();
+    const threadAction: ThreadAction = { action: 'start_new' };
+
+    const result = await pairDeliveryWithConversation(signal, 'vellum' as NotificationChannel, copy, { threadAction });
+
+    expect(result.conversationId).toBe('conv-001');
+    expect(result.createdNewConversation).toBe(true);
+    expect(result.threadDecisionFallbackUsed).toBe(false);
+    expect(createConversationMock).toHaveBeenCalledTimes(1);
+  });
+
+  test('creates new conversation when threadAction is undefined (default)', async () => {
+    const signal = makeSignal();
+    const copy = makeCopy();
+
+    const result = await pairDeliveryWithConversation(signal, 'vellum' as NotificationChannel, copy);
+
+    expect(result.conversationId).toBe('conv-001');
+    expect(result.createdNewConversation).toBe(true);
+    expect(result.threadDecisionFallbackUsed).toBe(false);
+  });
+
   // ── Error resilience ──────────────────────────────────────────────
 
   test('catches createConversation errors and returns null IDs without throwing', async () => {
@@ -236,6 +335,7 @@ describe('pairDeliveryWithConversation', () => {
     expect(result.messageId).toBeNull();
     // Strategy should still be resolved from the policy registry
     expect(result.strategy).toBe('start_new_conversation');
+    expect(result.createdNewConversation).toBe(false);
   });
 
   test('catches addMessage errors and returns null IDs without throwing', async () => {

package/src/__tests__/guardian-action-conversation-turn.test.ts

@@ -39,13 +39,13 @@ import {
   startFollowupFromExpiredRequest,
   updateDeliveryStatus,
 } from '../memory/guardian-action-store.js';
+import { conversations } from '../memory/schema.js';
 import { processGuardianFollowUpTurn } from '../runtime/guardian-action-conversation-turn.js';
 import type {
   GuardianFollowUpConversationContext,
   GuardianFollowUpConversationGenerator,
   GuardianFollowUpTurnResult,
 } from '../runtime/http-types.js';
-import { conversations } from '../memory/schema.js';
 
 initializeDb();
 

package/src/__tests__/guardian-action-followup-executor.test.ts

@@ -71,9 +71,9 @@ import {
   startFollowupFromExpiredRequest,
   updateDeliveryStatus,
 } from '../memory/guardian-action-store.js';
+import { conversations } from '../memory/schema.js';
 import { executeFollowupAction } from '../runtime/guardian-action-followup-executor.js';
 import { resolveCounterparty } from '../runtime/guardian-action-followup-executor.js';
-import { conversations } from '../memory/schema.js';
 
 initializeDb();
 

package/src/__tests__/guardian-action-late-reply.test.ts

@@ -35,9 +35,12 @@ import {
   createGuardianActionDelivery,
   createGuardianActionRequest,
   expireGuardianActionRequest,
+  getExpiredDeliveriesByConversation,
   getExpiredDeliveriesByDestination,
   getExpiredDeliveryByConversation,
+  getFollowupDeliveriesByConversation,
   getGuardianActionRequest,
+  getPendingDeliveriesByConversation,
   resolveGuardianActionRequest,
   startFollowupFromExpiredRequest,
   updateDeliveryStatus,
@@ -291,4 +294,132 @@ describe('guardian-action-late-reply', () => {
 
     expect(text).toContain('expired');
   });
+
+  // ── Multiple deliveries in one conversation (disambiguation) ──────
+
+  describe('multi-delivery disambiguation in reused conversations', () => {
+    // Helper to create a pending request with delivery in a shared conversation
+    function createPendingInSharedConv(sourceConvId: string, sharedDeliveryConvId: string) {
+      ensureConversation(sourceConvId);
+      const session = createCallSession({
+        conversationId: sourceConvId,
+        provider: 'twilio',
+        fromNumber: '+15550001111',
+        toNumber: '+15550002222',
+      });
+      const pq = createPendingQuestion(session.id, `Question from ${sourceConvId}`);
+      const request = createGuardianActionRequest({
+        kind: 'ask_guardian',
+        sourceChannel: 'voice',
+        sourceConversationId: sourceConvId,
+        callSessionId: session.id,
+        pendingQuestionId: pq.id,
+        questionText: pq.questionText,
+        expiresAt: Date.now() + 60_000,
+      });
+      const delivery = createGuardianActionDelivery({
+        requestId: request.id,
+        destinationChannel: 'vellum',
+        destinationConversationId: sharedDeliveryConvId,
+      });
+      updateDeliveryStatus(delivery.id, 'sent');
+      return { request, delivery };
+    }
+
+    test('multiple pending deliveries in same conversation are returned by getPendingDeliveriesByConversation', () => {
+      const sharedConv = 'shared-reused-conv-pending';
+      ensureConversation(sharedConv);
+
+      const { request: req1 } = createPendingInSharedConv('src-p1', sharedConv);
+      const { request: req2 } = createPendingInSharedConv('src-p2', sharedConv);
+
+      const deliveries = getPendingDeliveriesByConversation(sharedConv);
+      expect(deliveries).toHaveLength(2);
+
+      const requestIds = deliveries.map((d) => d.requestId);
+      expect(requestIds).toContain(req1.id);
+      expect(requestIds).toContain(req2.id);
+    });
+
+    test('request codes are unique across multiple requests in same conversation', () => {
+      const sharedConv = 'shared-reused-conv-codes';
+      ensureConversation(sharedConv);
+
+      const { request: req1 } = createPendingInSharedConv('src-code1', sharedConv);
+      const { request: req2 } = createPendingInSharedConv('src-code2', sharedConv);
+
+      expect(req1.requestCode).not.toBe(req2.requestCode);
+      expect(req1.requestCode).toHaveLength(6);
+      expect(req2.requestCode).toHaveLength(6);
+    });
+
+    test('multiple expired deliveries in same conversation are returned by getExpiredDeliveriesByConversation', () => {
+      const sharedConv = 'shared-reused-conv-expired';
+      ensureConversation(sharedConv);
+
+      const { request: req1 } = createPendingInSharedConv('src-e1', sharedConv);
+      const { request: req2 } = createPendingInSharedConv('src-e2', sharedConv);
+
+      expireGuardianActionRequest(req1.id, 'sweep_timeout');
+      expireGuardianActionRequest(req2.id, 'sweep_timeout');
+
+      const deliveries = getExpiredDeliveriesByConversation(sharedConv);
+      expect(deliveries).toHaveLength(2);
+
+      const requestIds = deliveries.map((d) => d.requestId);
+      expect(requestIds).toContain(req1.id);
+      expect(requestIds).toContain(req2.id);
+    });
+
+    test('multiple followup deliveries in same conversation are returned by getFollowupDeliveriesByConversation', () => {
+      const sharedConv = 'shared-reused-conv-followup';
+      ensureConversation(sharedConv);
+
+      const { request: req1 } = createPendingInSharedConv('src-fu1', sharedConv);
+      const { request: req2 } = createPendingInSharedConv('src-fu2', sharedConv);
+
+      expireGuardianActionRequest(req1.id, 'sweep_timeout');
+      expireGuardianActionRequest(req2.id, 'sweep_timeout');
+      startFollowupFromExpiredRequest(req1.id, 'late answer 1');
+      startFollowupFromExpiredRequest(req2.id, 'late answer 2');
+
+      const deliveries = getFollowupDeliveriesByConversation(sharedConv);
+      expect(deliveries).toHaveLength(2);
+
+      const requestIds = deliveries.map((d) => d.requestId);
+      expect(requestIds).toContain(req1.id);
+      expect(requestIds).toContain(req2.id);
+    });
+
+    test('resolving one pending request leaves the other still pending in shared conversation', () => {
+      const sharedConv = 'shared-reused-conv-resolve-one';
+      ensureConversation(sharedConv);
+
+      const { request: req1 } = createPendingInSharedConv('src-r1', sharedConv);
+      const { request: req2 } = createPendingInSharedConv('src-r2', sharedConv);
+
+      resolveGuardianActionRequest(req1.id, 'answer to first', 'vellum');
+
+      const remaining = getPendingDeliveriesByConversation(sharedConv);
+      expect(remaining).toHaveLength(1);
+      expect(remaining[0].requestId).toBe(req2.id);
+    });
+
+    test('request code prefix matching is case-insensitive', () => {
+      const sharedConv = 'shared-reused-conv-case';
+      ensureConversation(sharedConv);
+
+      const { request: req1 } = createPendingInSharedConv('src-case1', sharedConv);
+      const code = req1.requestCode; // e.g. "A1B2C3"
+
+      // Simulate case-insensitive prefix matching as done in session-process.ts
+      const userInput = `${code.toLowerCase()} the answer is 42`;
+      const matched = userInput.toUpperCase().startsWith(code);
+      expect(matched).toBe(true);
+
+      // After stripping the code prefix, the answer text is extracted
+      const answerText = userInput.slice(code.length).trim();
+      expect(answerText).toBe('the answer is 42');
+    });
+  });
 });

package/src/__tests__/guardian-action-store.test.ts

@@ -31,8 +31,16 @@ import {
   cancelGuardianActionRequest,
   createGuardianActionDelivery,
   createGuardianActionRequest,
+  expireGuardianActionRequest,
   getDeliveriesByRequestId,
+  getExpiredDeliveriesByConversation,
+  getExpiredDeliveryByConversation,
+  getFollowupDeliveriesByConversation,
+  getFollowupDeliveryByConversation,
   getGuardianActionRequest,
+  getPendingDeliveriesByConversation,
+  getPendingDeliveryByConversation,
+  startFollowupFromExpiredRequest,
   updateDeliveryStatus,
 } from '../memory/guardian-action-store.js';
 import { conversations } from '../memory/schema.js';
@@ -74,6 +82,180 @@ describe('guardian-action-store', () => {
     }
   });
 
+  // ── Helper to create a pending request+delivery targeting a conversation ──
+  function createPendingRequestWithDelivery(convId: string, deliveryConvId: string) {
+    ensureConversation(convId);
+    const session = createCallSession({
+      conversationId: convId,
+      provider: 'twilio',
+      fromNumber: '+15550001111',
+      toNumber: '+15550002222',
+    });
+    const pq = createPendingQuestion(session.id, `Question for ${convId}`);
+    const request = createGuardianActionRequest({
+      kind: 'ask_guardian',
+      sourceChannel: 'voice',
+      sourceConversationId: convId,
+      callSessionId: session.id,
+      pendingQuestionId: pq.id,
+      questionText: pq.questionText,
+      expiresAt: Date.now() + 60_000,
+    });
+    const delivery = createGuardianActionDelivery({
+      requestId: request.id,
+      destinationChannel: 'vellum',
+      destinationConversationId: deliveryConvId,
+    });
+    updateDeliveryStatus(delivery.id, 'sent');
+    return { request, delivery };
+  }
+
+  // ── getPendingDeliveriesByConversation ──────────────────────────────
+
+  test('getPendingDeliveriesByConversation returns all pending deliveries for a conversation', () => {
+    const sharedConvId = 'shared-pending-conv';
+    ensureConversation(sharedConvId);
+
+    const { request: req1 } = createPendingRequestWithDelivery('source-conv-p1', sharedConvId);
+    const { request: req2 } = createPendingRequestWithDelivery('source-conv-p2', sharedConvId);
+
+    const deliveries = getPendingDeliveriesByConversation(sharedConvId);
+    expect(deliveries).toHaveLength(2);
+
+    const requestIds = deliveries.map((d) => d.requestId);
+    expect(requestIds).toContain(req1.id);
+    expect(requestIds).toContain(req2.id);
+  });
+
+  test('getPendingDeliveriesByConversation returns single delivery (fast path preserved)', () => {
+    const convId = 'single-pending-conv';
+    ensureConversation(convId);
+
+    const { request } = createPendingRequestWithDelivery('source-conv-single-p', convId);
+
+    const deliveries = getPendingDeliveriesByConversation(convId);
+    expect(deliveries).toHaveLength(1);
+    expect(deliveries[0].requestId).toBe(request.id);
+  });
+
+  test('getPendingDeliveryByConversation returns first from multiple (backward compat)', () => {
+    const convId = 'compat-pending-conv';
+    ensureConversation(convId);
+
+    createPendingRequestWithDelivery('source-conv-compat-p1', convId);
+    createPendingRequestWithDelivery('source-conv-compat-p2', convId);
+
+    const single = getPendingDeliveryByConversation(convId);
+    expect(single).not.toBeNull();
+  });
+
+  test('getPendingDeliveriesByConversation returns empty for non-matching conversation', () => {
+    ensureConversation('other-conv');
+    createPendingRequestWithDelivery('source-conv-no-match', 'other-conv');
+
+    const deliveries = getPendingDeliveriesByConversation('nonexistent-conv');
+    expect(deliveries).toHaveLength(0);
+  });
+
+  // ── getExpiredDeliveriesByConversation ──────────────────────────────
+
+  test('getExpiredDeliveriesByConversation returns all expired deliveries for a conversation', () => {
+    const sharedConvId = 'shared-expired-conv';
+    ensureConversation(sharedConvId);
+
+    const { request: req1 } = createPendingRequestWithDelivery('source-conv-e1', sharedConvId);
+    const { request: req2 } = createPendingRequestWithDelivery('source-conv-e2', sharedConvId);
+
+    expireGuardianActionRequest(req1.id, 'sweep_timeout');
+    expireGuardianActionRequest(req2.id, 'sweep_timeout');
+
+    const deliveries = getExpiredDeliveriesByConversation(sharedConvId);
+    expect(deliveries).toHaveLength(2);
+
+    const requestIds = deliveries.map((d) => d.requestId);
+    expect(requestIds).toContain(req1.id);
+    expect(requestIds).toContain(req2.id);
+  });
+
+  test('getExpiredDeliveryByConversation returns first from multiple (backward compat)', () => {
+    const convId = 'compat-expired-conv';
+    ensureConversation(convId);
+
+    const { request: req1 } = createPendingRequestWithDelivery('source-conv-compat-e1', convId);
+    const { request: req2 } = createPendingRequestWithDelivery('source-conv-compat-e2', convId);
+
+    expireGuardianActionRequest(req1.id, 'sweep_timeout');
+    expireGuardianActionRequest(req2.id, 'sweep_timeout');
+
+    const single = getExpiredDeliveryByConversation(convId);
+    expect(single).not.toBeNull();
+  });
+
+  test('getExpiredDeliveriesByConversation excludes deliveries with followup already started', () => {
+    const convId = 'expired-with-followup-conv';
+    ensureConversation(convId);
+
+    const { request: req1 } = createPendingRequestWithDelivery('source-conv-ef1', convId);
+    const { request: req2 } = createPendingRequestWithDelivery('source-conv-ef2', convId);
+
+    expireGuardianActionRequest(req1.id, 'sweep_timeout');
+    expireGuardianActionRequest(req2.id, 'sweep_timeout');
+
+    // Start followup on req1 — only req2 should remain in the expired query
+    startFollowupFromExpiredRequest(req1.id, 'late answer');
+
+    const deliveries = getExpiredDeliveriesByConversation(convId);
+    expect(deliveries).toHaveLength(1);
+    expect(deliveries[0].requestId).toBe(req2.id);
+  });
+
+  // ── getFollowupDeliveriesByConversation ─────────────────────────────
+
+  test('getFollowupDeliveriesByConversation returns all awaiting_guardian_choice deliveries', () => {
+    const convId = 'shared-followup-conv';
+    ensureConversation(convId);
+
+    const { request: req1 } = createPendingRequestWithDelivery('source-conv-f1', convId);
+    const { request: req2 } = createPendingRequestWithDelivery('source-conv-f2', convId);
+
+    expireGuardianActionRequest(req1.id, 'sweep_timeout');
+    expireGuardianActionRequest(req2.id, 'sweep_timeout');
+
+    startFollowupFromExpiredRequest(req1.id, 'late answer 1');
+    startFollowupFromExpiredRequest(req2.id, 'late answer 2');
+
+    const deliveries = getFollowupDeliveriesByConversation(convId);
+    expect(deliveries).toHaveLength(2);
+
+    const requestIds = deliveries.map((d) => d.requestId);
+    expect(requestIds).toContain(req1.id);
+    expect(requestIds).toContain(req2.id);
+  });
+
+  test('getFollowupDeliveryByConversation returns first from multiple (backward compat)', () => {
+    const convId = 'compat-followup-conv';
+    ensureConversation(convId);
+
+    const { request: req1 } = createPendingRequestWithDelivery('source-conv-compat-f1', convId);
+    const { request: req2 } = createPendingRequestWithDelivery('source-conv-compat-f2', convId);
+
+    expireGuardianActionRequest(req1.id, 'sweep_timeout');
+    expireGuardianActionRequest(req2.id, 'sweep_timeout');
+
+    startFollowupFromExpiredRequest(req1.id, 'late 1');
+    startFollowupFromExpiredRequest(req2.id, 'late 2');
+
+    const single = getFollowupDeliveryByConversation(convId);
+    expect(single).not.toBeNull();
+  });
+
+  test('getFollowupDeliveriesByConversation returns empty for non-matching conversation', () => {
+    const deliveries = getFollowupDeliveriesByConversation('nonexistent-conv');
+    expect(deliveries).toHaveLength(0);
+  });
+
+  // ── cancelGuardianActionRequest ─────────────────────────────────────
+
   test('cancelGuardianActionRequest cancels both pending and sent deliveries', () => {
     const conversationId = 'conv-guardian-cancel';
     ensureConversation(conversationId);