@vellumai/assistant 0.3.16 → 0.3.19

package/src/daemon/session-process.ts

@@ -15,21 +15,22 @@ import * as conversationStore from '../memory/conversation-store.js';
 import { provenanceFromGuardianContext } from '../memory/conversation-store.js';
 import {
   finalizeFollowup,
-  getExpiredDeliveryByConversation,
-  getFollowupDeliveryByConversation,
+  getExpiredDeliveriesByConversation,
+  getFollowupDeliveriesByConversation,
   getGuardianActionRequest,
-  getPendingDeliveryByConversation,
+  getPendingDeliveriesByConversation,
   progressFollowupState,
   resolveGuardianActionRequest,
   startFollowupFromExpiredRequest,
 } from '../memory/guardian-action-store.js';
+import { extractPreferences } from '../notifications/preference-extractor.js';
+import { createPreference } from '../notifications/preferences-store.js';
+import type { Message } from '../providers/types.js';
 import { processGuardianFollowUpTurn } from '../runtime/guardian-action-conversation-turn.js';
 import { executeFollowupAction } from '../runtime/guardian-action-followup-executor.js';
+import { tryMintGuardianActionGrant } from '../runtime/guardian-action-grant-minter.js';
 import { composeGuardianActionMessageGenerative } from '../runtime/guardian-action-message-composer.js';
 import type { GuardianActionCopyGenerator, GuardianFollowUpConversationGenerator } from '../runtime/http-types.js';
-import { extractPreferences } from '../notifications/preference-extractor.js';
-import { createPreference } from '../notifications/preferences-store.js';
-import type { Message } from '../providers/types.js';
 import { getLogger } from '../util/logger.js';
 import { resolveGuardianVerificationIntent } from './guardian-verification-intent.js';
 import type { UsageStats } from './ipc-contract.js';
@@ -383,213 +384,478 @@ export async function processMessage(
   session.currentPage = currentPage;
 
   // ── Guardian action answer interception (mac channel) ──
-  // If this conversation has a pending guardian action delivery, treat the
+  // If this conversation has pending guardian action deliveries, treat the
   // user message as the guardian's answer instead of running the agent loop.
-  const guardianDelivery = getPendingDeliveryByConversation(session.conversationId);
-  if (guardianDelivery) {
-    const guardianRequest = getGuardianActionRequest(guardianDelivery.requestId);
-    if (guardianRequest && guardianRequest.status === 'pending') {
-      const guardianIfCtx = session.getTurnInterfaceContext();
-      const guardianChannelMeta = { userMessageChannel: 'vellum' as const, assistantMessageChannel: 'vellum' as const, userMessageInterface: guardianIfCtx?.userMessageInterface ?? 'vellum', assistantMessageInterface: guardianIfCtx?.assistantMessageInterface ?? 'vellum', provenanceActorRole: 'guardian' as const };
-      const userMsg = createUserMessage(content, attachments);
-      const persisted = await conversationStore.addMessage(
-        session.conversationId,
-        'user',
-        JSON.stringify(userMsg.content),
-        guardianChannelMeta,
-      );
-      session.messages.push(userMsg);
+  // When multiple deliveries exist in the same reused thread, require a
+  // request-code prefix for disambiguation (matching the channel path pattern).
+  const pendingDeliveries = getPendingDeliveriesByConversation(session.conversationId);
+  if (pendingDeliveries.length > 0) {
+    // Before auto-selecting a lone pending delivery, check if expired or
+    // follow-up deliveries also exist in this conversation. When the total
+    // count across all states exceeds 1, require request-code disambiguation
+    // even if only one pending delivery exists — otherwise a reply prefixed
+    // with an expired/follow-up request code would be silently routed to
+    // the pending delivery instead of being correctly rejected or routed.
+    const crossStateExpired = getExpiredDeliveriesByConversation(session.conversationId);
+    const crossStateFollowup = getFollowupDeliveriesByConversation(session.conversationId);
+    const totalCrossStateCount = pendingDeliveries.length + crossStateExpired.length + crossStateFollowup.length;
+    let matchedDelivery = (pendingDeliveries.length === 1 && totalCrossStateCount === 1) ? pendingDeliveries[0] : null;
+    let answerText = content;
+
+    // Strip the request code prefix from the answer text when the single
+    // pending delivery is auto-matched (content may include a code prefix
+    // if the guardian uses it out of habit after a previous disambiguation round).
+    if (matchedDelivery) {
+      const req = getGuardianActionRequest(matchedDelivery.requestId);
+      if (req && content.toUpperCase().startsWith(req.requestCode)) {
+        answerText = content.slice(req.requestCode.length).trim();
+      }
+    }
 
-      // Attempt to deliver the answer to the call first. Only resolve
-      // the guardian action request if answerCall succeeds, so that a
-      // failed delivery leaves the request pending for retry from
-      // another channel.
-      const answerResult = await answerCall({ callSessionId: guardianRequest.callSessionId, answer: content });
-
-      if ('ok' in answerResult && answerResult.ok) {
-        const resolved = resolveGuardianActionRequest(guardianRequest.id, content, 'vellum');
-        const replyText = resolved
-          ? 'Your answer has been relayed to the call.'
-          : await composeGuardianActionMessageGenerative({ scenario: 'guardian_stale_answered' }, {}, _guardianActionCopyGenerator);
-        const replyMsg = createAssistantMessage(replyText);
-        await conversationStore.addMessage(
-          session.conversationId,
-          'assistant',
-          JSON.stringify(replyMsg.content),
-          guardianChannelMeta,
-        );
-        session.messages.push(replyMsg);
-        onEvent({ type: 'assistant_text_delta', text: replyText });
-      } else {
-        const errorDetail = 'error' in answerResult ? answerResult.error : 'Unknown error';
-        log.warn({ callSessionId: guardianRequest.callSessionId, error: errorDetail }, 'answerCall failed for mac guardian answer');
-        const failureText = await composeGuardianActionMessageGenerative(
-          { scenario: 'guardian_answer_delivery_failed' },
-          {},
-          _guardianActionCopyGenerator,
-        );
-        const failMsg = createAssistantMessage(failureText);
-        await conversationStore.addMessage(
+    // Multiple deliveries across any state: require request code prefix for disambiguation
+    if (!matchedDelivery && pendingDeliveries.length >= 1) {
+      for (const d of pendingDeliveries) {
+        const req = getGuardianActionRequest(d.requestId);
+        if (req && content.toUpperCase().startsWith(req.requestCode)) {
+          matchedDelivery = d;
+          answerText = content.slice(req.requestCode.length).trim();
+          break;
+        }
+      }
+
+      // If no pending delivery matched, check whether the code targets an
+      // expired or follow-up delivery. If so, skip the pending section entirely
+      // and let the message fall through to the expired/follow-up handlers below.
+      if (!matchedDelivery) {
+        let matchesOtherState = false;
+        for (const d of [...crossStateExpired, ...crossStateFollowup]) {
+          const req = getGuardianActionRequest(d.requestId);
+          if (req && content.toUpperCase().startsWith(req.requestCode)) {
+            matchesOtherState = true;
+            break;
+          }
+        }
+
+        if (!matchesOtherState) {
+          const guardianIfCtx = session.getTurnInterfaceContext();
+          const guardianChannelMeta = { userMessageChannel: 'vellum' as const, assistantMessageChannel: 'vellum' as const, userMessageInterface: guardianIfCtx?.userMessageInterface ?? 'vellum', assistantMessageInterface: guardianIfCtx?.assistantMessageInterface ?? 'vellum', provenanceActorRole: 'guardian' as const };
+          const userMsg = createUserMessage(content, attachments);
+          const persisted = await conversationStore.addMessage(
+            session.conversationId,
+            'user',
+            JSON.stringify(userMsg.content),
+            guardianChannelMeta,
+          );
+          session.messages.push(userMsg);
+
+          // Include codes from all states so the guardian sees all options
+          const allDeliveries = [...pendingDeliveries, ...crossStateExpired, ...crossStateFollowup];
+          const codes = allDeliveries
+            .map((d) => { const req = getGuardianActionRequest(d.requestId); return req ? req.requestCode : null; })
+            .filter((code): code is string => typeof code === 'string' && code.length > 0);
+          const disambiguationText = `You have multiple pending guardian questions. Please prefix your reply with the reference code (${codes.join(', ')}) to indicate which question you are answering.`;
+          const disambiguationMsg = createAssistantMessage(disambiguationText);
+          await conversationStore.addMessage(
+            session.conversationId,
+            'assistant',
+            JSON.stringify(disambiguationMsg.content),
+            guardianChannelMeta,
+          );
+          session.messages.push(disambiguationMsg);
+          onEvent({ type: 'assistant_text_delta', text: disambiguationText });
+          onEvent({ type: 'message_complete', sessionId: session.conversationId });
+          return persisted.id;
+        }
+        // Code matched an expired/follow-up delivery — fall through to those handlers
+      }
+    }
+
+    if (matchedDelivery) {
+      const guardianRequest = getGuardianActionRequest(matchedDelivery.requestId);
+      if (guardianRequest && guardianRequest.status === 'pending') {
+        const guardianIfCtx = session.getTurnInterfaceContext();
+        const guardianChannelMeta = { userMessageChannel: 'vellum' as const, assistantMessageChannel: 'vellum' as const, userMessageInterface: guardianIfCtx?.userMessageInterface ?? 'vellum', assistantMessageInterface: guardianIfCtx?.assistantMessageInterface ?? 'vellum', provenanceActorRole: 'guardian' as const };
+        const userMsg = createUserMessage(content, attachments);
+        const persisted = await conversationStore.addMessage(
           session.conversationId,
-          'assistant',
-          JSON.stringify(failMsg.content),
+          'user',
+          JSON.stringify(userMsg.content),
           guardianChannelMeta,
         );
-        session.messages.push(failMsg);
-        onEvent({ type: 'assistant_text_delta', text: failureText });
+        session.messages.push(userMsg);
+
+        // Attempt to deliver the answer to the call first. Only resolve
+        // the guardian action request if answerCall succeeds, so that a
+        // failed delivery leaves the request pending for retry from
+        // another channel.
+        const answerResult = await answerCall({ callSessionId: guardianRequest.callSessionId, answer: answerText });
+
+        if ('ok' in answerResult && answerResult.ok) {
+          const resolved = resolveGuardianActionRequest(guardianRequest.id, answerText, 'vellum');
+
+          // Mint a scoped grant so the voice call can consume it
+          // for subsequent tool confirmations.
+          if (resolved) {
+            tryMintGuardianActionGrant({
+              resolvedRequest: resolved,
+              answerText,
+              decisionChannel: 'vellum',
+            });
+          }
+
+          const replyText = resolved
+            ? 'Your answer has been relayed to the call.'
+            : await composeGuardianActionMessageGenerative({ scenario: 'guardian_stale_answered' }, {}, _guardianActionCopyGenerator);
+          const replyMsg = createAssistantMessage(replyText);
+          await conversationStore.addMessage(
+            session.conversationId,
+            'assistant',
+            JSON.stringify(replyMsg.content),
+            guardianChannelMeta,
+          );
+          session.messages.push(replyMsg);
+          onEvent({ type: 'assistant_text_delta', text: replyText });
+        } else {
+          const errorDetail = 'error' in answerResult ? answerResult.error : 'Unknown error';
+          log.warn({ callSessionId: guardianRequest.callSessionId, error: errorDetail }, 'answerCall failed for mac guardian answer');
+          const failureText = await composeGuardianActionMessageGenerative(
+            { scenario: 'guardian_answer_delivery_failed' },
+            {},
+            _guardianActionCopyGenerator,
+          );
+          const failMsg = createAssistantMessage(failureText);
+          await conversationStore.addMessage(
+            session.conversationId,
+            'assistant',
+            JSON.stringify(failMsg.content),
+            guardianChannelMeta,
+          );
+          session.messages.push(failMsg);
+          onEvent({ type: 'assistant_text_delta', text: failureText });
+        }
+        onEvent({ type: 'message_complete', sessionId: session.conversationId });
+        return persisted.id;
       }
-      onEvent({ type: 'message_complete', sessionId: session.conversationId });
-      return persisted.id;
     }
   }
 
   // ── Expired guardian action late answer interception (mac channel) ──
   // If no pending delivery was found, check for expired requests eligible
-  // for follow-up (status='expired', followup_state='none').
-  const expiredDelivery = getExpiredDeliveryByConversation(session.conversationId);
-  if (expiredDelivery) {
-    const expiredRequest = getGuardianActionRequest(expiredDelivery.requestId);
-    if (expiredRequest && expiredRequest.status === 'expired' && expiredRequest.followupState === 'none') {
-      const guardianIfCtx = session.getTurnInterfaceContext();
-      const guardianChannelMeta = { userMessageChannel: 'vellum' as const, assistantMessageChannel: 'vellum' as const, userMessageInterface: guardianIfCtx?.userMessageInterface ?? 'vellum', assistantMessageInterface: guardianIfCtx?.assistantMessageInterface ?? 'vellum', provenanceActorRole: 'guardian' as const };
-      const userMsg = createUserMessage(content, attachments);
-      const persisted = await conversationStore.addMessage(
-        session.conversationId,
-        'user',
-        JSON.stringify(userMsg.content),
-        guardianChannelMeta,
-      );
-      session.messages.push(userMsg);
+  // for follow-up (status='expired', followup_state='none'). When multiple
+  // expired deliveries exist, require request-code prefix for disambiguation.
+  const expiredDeliveries = getExpiredDeliveriesByConversation(session.conversationId);
+  if (expiredDeliveries.length > 0) {
+    // Cross-state disambiguation: check total deliveries across all states
+    // (pending + expired + follow-up). When the total exceeds 1, require
+    // request-code disambiguation even for a lone expired delivery — otherwise
+    // a reply targeting a different state's delivery gets silently misrouted.
+    const expCrossStatePending = getPendingDeliveriesByConversation(session.conversationId);
+    const expCrossStateFollowup = getFollowupDeliveriesByConversation(session.conversationId);
+    const expTotalCrossStateCount = expiredDeliveries.length + expCrossStatePending.length + expCrossStateFollowup.length;
+    let matchedExpired = (expiredDeliveries.length === 1 && expTotalCrossStateCount === 1) ? expiredDeliveries[0] : null;
+    let expiredAnswerText = content;
+
+    // Strip the request code prefix from the answer text when the single
+    // expired delivery is auto-matched (content may include a code prefix
+    // if the pending section fell through via matchesOtherState).
+    if (matchedExpired) {
+      const req = getGuardianActionRequest(matchedExpired.requestId);
+      if (req && content.toUpperCase().startsWith(req.requestCode)) {
+        expiredAnswerText = content.slice(req.requestCode.length).trim();
+      }
+    }
 
-      const followupResult = startFollowupFromExpiredRequest(expiredRequest.id, content);
-      if (followupResult) {
-        const followupText = await composeGuardianActionMessageGenerative(
-          {
-            scenario: 'guardian_late_answer_followup',
-            questionText: expiredRequest.questionText,
-            lateAnswerText: content,
-          },
-          {},
-          _guardianActionCopyGenerator,
-        );
-        const replyMsg = createAssistantMessage(followupText);
-        await conversationStore.addMessage(
-          session.conversationId,
-          'assistant',
-          JSON.stringify(replyMsg.content),
-          guardianChannelMeta,
-        );
-        session.messages.push(replyMsg);
-        onEvent({ type: 'assistant_text_delta', text: followupText });
-      } else {
-        // Follow-up already started or conflict — send stale message
-        const staleText = await composeGuardianActionMessageGenerative(
-          { scenario: 'guardian_stale_expired' },
-          {},
-          _guardianActionCopyGenerator,
-        );
-        const staleMsg = createAssistantMessage(staleText);
-        await conversationStore.addMessage(
+    // Multiple expired deliveries (or cross-state disambiguation needed):
+    // require request code prefix for disambiguation
+    if (!matchedExpired && expiredDeliveries.length >= 1) {
+      for (const d of expiredDeliveries) {
+        const req = getGuardianActionRequest(d.requestId);
+        if (req && content.toUpperCase().startsWith(req.requestCode)) {
+          matchedExpired = d;
+          expiredAnswerText = content.slice(req.requestCode.length).trim();
+          break;
+        }
+      }
+
+      if (!matchedExpired) {
+        // Before disambiguating, check if the code matches a follow-up or
+        // pending delivery. If so, fall through to let those handlers process it.
+        let matchesFollowupState = false;
+        for (const d of [...expCrossStateFollowup, ...expCrossStatePending]) {
+          const req = getGuardianActionRequest(d.requestId);
+          if (req && content.toUpperCase().startsWith(req.requestCode)) {
+            matchesFollowupState = true;
+            break;
+          }
+        }
+
+        if (!matchesFollowupState) {
+          const guardianIfCtx = session.getTurnInterfaceContext();
+          const guardianChannelMeta = { userMessageChannel: 'vellum' as const, assistantMessageChannel: 'vellum' as const, userMessageInterface: guardianIfCtx?.userMessageInterface ?? 'vellum', assistantMessageInterface: guardianIfCtx?.assistantMessageInterface ?? 'vellum', provenanceActorRole: 'guardian' as const };
+          const userMsg = createUserMessage(content, attachments);
+          const persisted = await conversationStore.addMessage(
+            session.conversationId,
+            'user',
+            JSON.stringify(userMsg.content),
+            guardianChannelMeta,
+          );
+          session.messages.push(userMsg);
+
+          // Include codes from all states so the guardian sees all options
+          const allExpiredDeliveries = [...expiredDeliveries, ...expCrossStatePending, ...expCrossStateFollowup];
+          const codes = allExpiredDeliveries
+            .map((d) => { const req = getGuardianActionRequest(d.requestId); return req ? req.requestCode : null; })
+            .filter((code): code is string => typeof code === 'string' && code.length > 0);
+          const disambiguationText = await composeGuardianActionMessageGenerative(
+            { scenario: 'guardian_expired_disambiguation', requestCodes: codes },
+            { requiredKeywords: codes },
+            _guardianActionCopyGenerator,
+          );
+          const disambiguationMsg = createAssistantMessage(disambiguationText);
+          await conversationStore.addMessage(
+            session.conversationId,
+            'assistant',
+            JSON.stringify(disambiguationMsg.content),
+            guardianChannelMeta,
+          );
+          session.messages.push(disambiguationMsg);
+          onEvent({ type: 'assistant_text_delta', text: disambiguationText });
+          onEvent({ type: 'message_complete', sessionId: session.conversationId });
+          return persisted.id;
+        }
+        // Code matched a follow-up or pending delivery — fall through to those handlers
+      }
+    }
+
+    if (matchedExpired) {
+      const expiredRequest = getGuardianActionRequest(matchedExpired.requestId);
+      if (expiredRequest && expiredRequest.status === 'expired' && expiredRequest.followupState === 'none') {
+        const guardianIfCtx = session.getTurnInterfaceContext();
+        const guardianChannelMeta = { userMessageChannel: 'vellum' as const, assistantMessageChannel: 'vellum' as const, userMessageInterface: guardianIfCtx?.userMessageInterface ?? 'vellum', assistantMessageInterface: guardianIfCtx?.assistantMessageInterface ?? 'vellum', provenanceActorRole: 'guardian' as const };
+        const userMsg = createUserMessage(content, attachments);
+        const persisted = await conversationStore.addMessage(
           session.conversationId,
-          'assistant',
-          JSON.stringify(staleMsg.content),
+          'user',
+          JSON.stringify(userMsg.content),
           guardianChannelMeta,
         );
-        session.messages.push(staleMsg);
-        onEvent({ type: 'assistant_text_delta', text: staleText });
+        session.messages.push(userMsg);
+
+        const followupResult = startFollowupFromExpiredRequest(expiredRequest.id, expiredAnswerText);
+        if (followupResult) {
+          const followupText = await composeGuardianActionMessageGenerative(
+            {
+              scenario: 'guardian_late_answer_followup',
+              questionText: expiredRequest.questionText,
+              lateAnswerText: expiredAnswerText,
+            },
+            {},
+            _guardianActionCopyGenerator,
+          );
+          const replyMsg = createAssistantMessage(followupText);
+          await conversationStore.addMessage(
+            session.conversationId,
+            'assistant',
+            JSON.stringify(replyMsg.content),
+            guardianChannelMeta,
+          );
+          session.messages.push(replyMsg);
+          onEvent({ type: 'assistant_text_delta', text: followupText });
+        } else {
+          // Follow-up already started or conflict — send stale message
+          const staleText = await composeGuardianActionMessageGenerative(
+            { scenario: 'guardian_stale_expired' },
+            {},
+            _guardianActionCopyGenerator,
+          );
+          const staleMsg = createAssistantMessage(staleText);
+          await conversationStore.addMessage(
+            session.conversationId,
+            'assistant',
+            JSON.stringify(staleMsg.content),
+            guardianChannelMeta,
+          );
+          session.messages.push(staleMsg);
+          onEvent({ type: 'assistant_text_delta', text: staleText });
+        }
+        onEvent({ type: 'message_complete', sessionId: session.conversationId });
+        return persisted.id;
       }
-      onEvent({ type: 'message_complete', sessionId: session.conversationId });
-      return persisted.id;
     }
   }
 
   // ── Guardian follow-up conversation interception (mac channel) ──
   // When a request is in `awaiting_guardian_choice` state, the guardian has
   // already been asked "call back or send a message?". Their next message
-  // is the reply — route it through the conversation engine.
-  const followupDelivery = getFollowupDeliveryByConversation(session.conversationId);
-  if (followupDelivery) {
-    const followupRequest = getGuardianActionRequest(followupDelivery.requestId);
-    if (followupRequest && followupRequest.followupState === 'awaiting_guardian_choice') {
-      const guardianIfCtx = session.getTurnInterfaceContext();
-      const guardianChannelMeta = { userMessageChannel: 'vellum' as const, assistantMessageChannel: 'vellum' as const, userMessageInterface: guardianIfCtx?.userMessageInterface ?? 'vellum', assistantMessageInterface: guardianIfCtx?.assistantMessageInterface ?? 'vellum', provenanceActorRole: 'guardian' as const };
-      const userMsg = createUserMessage(content, attachments);
-      const persisted = await conversationStore.addMessage(
-        session.conversationId,
-        'user',
-        JSON.stringify(userMsg.content),
-        guardianChannelMeta,
-      );
-      session.messages.push(userMsg);
-
-      const turnResult = await processGuardianFollowUpTurn(
-        {
-          questionText: followupRequest.questionText,
-          lateAnswerText: followupRequest.lateAnswerText ?? '',
-          guardianReply: content,
-        },
-        _guardianFollowUpGenerator,
-      );
-
-      // Apply the disposition to the follow-up state machine.
-      // Both progressFollowupState and finalizeFollowup are compare-and-set:
-      // they return null when the transition was not applied (e.g. a concurrent
-      // reply already advanced the state). In that case we notify the guardian
-      // that the request was already resolved and skip action execution.
-      let stateApplied = true;
-      if (turnResult.disposition === 'call_back' || turnResult.disposition === 'message_back') {
-        stateApplied = progressFollowupState(followupRequest.id, 'dispatching', turnResult.disposition) !== null;
-      } else if (turnResult.disposition === 'decline') {
-        stateApplied = finalizeFollowup(followupRequest.id, 'declined') !== null;
+  // is the reply — route it through the conversation engine. When multiple
+  // follow-up deliveries exist, require request-code prefix for disambiguation.
+  const followupDeliveries = getFollowupDeliveriesByConversation(session.conversationId);
+  if (followupDeliveries.length > 0) {
+    // Cross-state disambiguation: check total deliveries across all states
+    // (pending + expired + follow-up). When the total exceeds 1, require
+    // request-code disambiguation even for a lone follow-up delivery.
+    const fuCrossStatePending = getPendingDeliveriesByConversation(session.conversationId);
+    const fuCrossStateExpired = getExpiredDeliveriesByConversation(session.conversationId);
+    const fuTotalCrossStateCount = followupDeliveries.length + fuCrossStatePending.length + fuCrossStateExpired.length;
+    let matchedFollowup = (followupDeliveries.length === 1 && fuTotalCrossStateCount === 1) ? followupDeliveries[0] : null;
+    let followupReplyText = content;
+
+    // Strip the request code prefix from the reply text when the single
+    // follow-up delivery is auto-matched (content may include a code prefix
+    // if the pending section fell through via matchesOtherState).
+    if (matchedFollowup) {
+      const req = getGuardianActionRequest(matchedFollowup.requestId);
+      if (req && content.toUpperCase().startsWith(req.requestCode)) {
+        followupReplyText = content.slice(req.requestCode.length).trim();
       }
-      // keep_pending: no state change — guardian can reply again
+    }
 
-      if (!stateApplied) {
-        log.warn({ requestId: followupRequest.id, disposition: turnResult.disposition }, 'Follow-up state transition failed (already resolved)');
+    // Multiple follow-up deliveries (or cross-state disambiguation needed):
+    // require request code prefix for disambiguation
+    if (!matchedFollowup && followupDeliveries.length >= 1) {
+      for (const d of followupDeliveries) {
+        const req = getGuardianActionRequest(d.requestId);
+        if (req && content.toUpperCase().startsWith(req.requestCode)) {
+          matchedFollowup = d;
+          followupReplyText = content.slice(req.requestCode.length).trim();
+          break;
+        }
       }
 
-      const replyText = stateApplied
-        ? turnResult.replyText
-        : await composeGuardianActionMessageGenerative({ scenario: 'guardian_stale_followup' }, {}, _guardianActionCopyGenerator);
-      const replyMsg = createAssistantMessage(replyText);
-      await conversationStore.addMessage(
-        session.conversationId,
-        'assistant',
-        JSON.stringify(replyMsg.content),
-        guardianChannelMeta,
-      );
-      session.messages.push(replyMsg);
-      onEvent({ type: 'assistant_text_delta', text: replyText });
-      onEvent({ type: 'message_complete', sessionId: session.conversationId });
-
-      // Execute the action and send a completion/failure message (fire-and-forget).
-      // The initial reply above acknowledges the guardian's choice; the executor
-      // carries out the actual call_back or message_back and posts a second message.
-      if (stateApplied && (turnResult.disposition === 'call_back' || turnResult.disposition === 'message_back')) {
-        void (async () => {
-          try {
-            const execResult = await executeFollowupAction(
-              followupRequest.id,
-              turnResult.disposition as 'call_back' | 'message_back',
-              _guardianActionCopyGenerator,
-            );
-            const completionMsg = createAssistantMessage(execResult.guardianReplyText);
-            await conversationStore.addMessage(
-              session.conversationId,
-              'assistant',
-              JSON.stringify(completionMsg.content),
-              guardianChannelMeta,
-            );
-            session.messages.push(completionMsg);
-            onEvent({ type: 'assistant_text_delta', text: execResult.guardianReplyText });
-            onEvent({ type: 'message_complete', sessionId: session.conversationId });
-          } catch (execErr) {
-            log.error({ err: execErr, requestId: followupRequest.id }, 'Follow-up action execution or completion message failed');
+      if (!matchedFollowup) {
+        // Before disambiguating, check if the code matches an expired or
+        // pending delivery. If so, fall through to let the normal agent loop
+        // handle it (expired/pending blocks already ran and didn't match).
+        let matchesOtherFollowupState = false;
+        for (const d of [...fuCrossStateExpired, ...fuCrossStatePending]) {
+          const req = getGuardianActionRequest(d.requestId);
+          if (req && content.toUpperCase().startsWith(req.requestCode)) {
+            matchesOtherFollowupState = true;
+            break;
           }
-        })();
+        }
+
+        if (!matchesOtherFollowupState) {
+          const guardianIfCtx = session.getTurnInterfaceContext();
+          const guardianChannelMeta = { userMessageChannel: 'vellum' as const, assistantMessageChannel: 'vellum' as const, userMessageInterface: guardianIfCtx?.userMessageInterface ?? 'vellum', assistantMessageInterface: guardianIfCtx?.assistantMessageInterface ?? 'vellum', provenanceActorRole: 'guardian' as const };
+          const userMsg = createUserMessage(content, attachments);
+          const persisted = await conversationStore.addMessage(
+            session.conversationId,
+            'user',
+            JSON.stringify(userMsg.content),
+            guardianChannelMeta,
+          );
+          session.messages.push(userMsg);
+
+          // Include codes from all states so the guardian sees all options
+          const allFollowupDeliveries = [...followupDeliveries, ...fuCrossStatePending, ...fuCrossStateExpired];
+          const codes = allFollowupDeliveries
+            .map((d) => { const req = getGuardianActionRequest(d.requestId); return req ? req.requestCode : null; })
+            .filter((code): code is string => typeof code === 'string' && code.length > 0);
+          const disambiguationText = await composeGuardianActionMessageGenerative(
+            { scenario: 'guardian_followup_disambiguation', requestCodes: codes },
+            { requiredKeywords: codes },
+            _guardianActionCopyGenerator,
+          );
+          const disambiguationMsg = createAssistantMessage(disambiguationText);
+          await conversationStore.addMessage(
+            session.conversationId,
+            'assistant',
+            JSON.stringify(disambiguationMsg.content),
+            guardianChannelMeta,
+          );
+          session.messages.push(disambiguationMsg);
+          onEvent({ type: 'assistant_text_delta', text: disambiguationText });
+          onEvent({ type: 'message_complete', sessionId: session.conversationId });
+          return persisted.id;
+        }
+        // Code matched an expired or pending delivery — fall through to agent loop
       }
+    }
+
+    if (matchedFollowup) {
+      const followupRequest = getGuardianActionRequest(matchedFollowup.requestId);
+      if (followupRequest && followupRequest.followupState === 'awaiting_guardian_choice') {
+        const guardianIfCtx = session.getTurnInterfaceContext();
+        const guardianChannelMeta = { userMessageChannel: 'vellum' as const, assistantMessageChannel: 'vellum' as const, userMessageInterface: guardianIfCtx?.userMessageInterface ?? 'vellum', assistantMessageInterface: guardianIfCtx?.assistantMessageInterface ?? 'vellum', provenanceActorRole: 'guardian' as const };
+        const userMsg = createUserMessage(content, attachments);
+        const persisted = await conversationStore.addMessage(
+          session.conversationId,
+          'user',
+          JSON.stringify(userMsg.content),
+          guardianChannelMeta,
+        );
+        session.messages.push(userMsg);
 
-      return persisted.id;
+        const turnResult = await processGuardianFollowUpTurn(
+          {
+            questionText: followupRequest.questionText,
+            lateAnswerText: followupRequest.lateAnswerText ?? '',
+            guardianReply: followupReplyText,
+          },
+          _guardianFollowUpGenerator,
+        );
+
+        // Apply the disposition to the follow-up state machine.
+        // Both progressFollowupState and finalizeFollowup are compare-and-set:
+        // they return null when the transition was not applied (e.g. a concurrent
+        // reply already advanced the state). In that case we notify the guardian
+        // that the request was already resolved and skip action execution.
+        let stateApplied = true;
+        if (turnResult.disposition === 'call_back' || turnResult.disposition === 'message_back') {
+          stateApplied = progressFollowupState(followupRequest.id, 'dispatching', turnResult.disposition) !== undefined;
+        } else if (turnResult.disposition === 'decline') {
+          stateApplied = finalizeFollowup(followupRequest.id, 'declined') !== undefined;
+        }
+        // keep_pending: no state change — guardian can reply again
+
+        if (!stateApplied) {
+          log.warn({ requestId: followupRequest.id, disposition: turnResult.disposition }, 'Follow-up state transition failed (already resolved)');
+        }
+
+        const replyText = stateApplied
+          ? turnResult.replyText
+          : await composeGuardianActionMessageGenerative({ scenario: 'guardian_stale_followup' }, {}, _guardianActionCopyGenerator);
+        const replyMsg = createAssistantMessage(replyText);
+        await conversationStore.addMessage(
+          session.conversationId,
+          'assistant',
+          JSON.stringify(replyMsg.content),
+          guardianChannelMeta,
+        );
+        session.messages.push(replyMsg);
+        onEvent({ type: 'assistant_text_delta', text: replyText });
+        onEvent({ type: 'message_complete', sessionId: session.conversationId });
+
+        // Execute the action and send a completion/failure message (fire-and-forget).
+        // The initial reply above acknowledges the guardian's choice; the executor
+        // carries out the actual call_back or message_back and posts a second message.
+        if (stateApplied && (turnResult.disposition === 'call_back' || turnResult.disposition === 'message_back')) {
+          void (async () => {
+            try {
+              const execResult = await executeFollowupAction(
+                followupRequest.id,
+                turnResult.disposition as 'call_back' | 'message_back',
+                _guardianActionCopyGenerator,
+              );
+              const completionMsg = createAssistantMessage(execResult.guardianReplyText);
+              await conversationStore.addMessage(
+                session.conversationId,
+                'assistant',
+                JSON.stringify(completionMsg.content),
+                guardianChannelMeta,
+              );
+              session.messages.push(completionMsg);
+              onEvent({ type: 'assistant_text_delta', text: execResult.guardianReplyText });
+              onEvent({ type: 'message_complete', sessionId: session.conversationId });
+            } catch (execErr) {
+              log.error({ err: execErr, requestId: followupRequest.id }, 'Follow-up action execution or completion message failed');
+            }
+          })();
+        }
+
+        return persisted.id;
+      }
     }
   }