@vellumai/assistant 0.3.19 → 0.3.21

package/src/daemon/session-process.ts

@@ -8,6 +8,8 @@
 
 import { createAssistantMessage,createUserMessage } from '../agent/message-types.js';
 import { answerCall } from '../calls/call-domain.js';
+import { isTerminalState } from '../calls/call-state-machine.js';
+import { getCallSession } from '../calls/call-store.js';
 import type { TurnChannelContext, TurnInterfaceContext } from '../channels/types.js';
 import { parseChannelId, parseInterfaceId } from '../channels/types.js';
 import { getConfig } from '../config/loader.js';
@@ -15,10 +17,12 @@ import * as conversationStore from '../memory/conversation-store.js';
 import { provenanceFromGuardianContext } from '../memory/conversation-store.js';
 import {
   finalizeFollowup,
+  getDeliveriesByRequestId,
   getExpiredDeliveriesByConversation,
   getFollowupDeliveriesByConversation,
   getGuardianActionRequest,
   getPendingDeliveriesByConversation,
+  getPendingRequestByCallSessionId,
   progressFollowupState,
   resolveGuardianActionRequest,
   startFollowupFromExpiredRequest,
@@ -30,8 +34,9 @@ import { processGuardianFollowUpTurn } from '../runtime/guardian-action-conversa
 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 type { ApprovalConversationGenerator, GuardianActionCopyGenerator, GuardianFollowUpConversationGenerator } from '../runtime/http-types.js';
 import { getLogger } from '../util/logger.js';
+import { resolveGuardianInviteIntent } from './guardian-invite-intent.js';
 import { resolveGuardianVerificationIntent } from './guardian-verification-intent.js';
 import type { UsageStats } from './ipc-contract.js';
 import type { ServerMessage, UserMessageAttachment } from './ipc-protocol.js';
@@ -51,6 +56,7 @@ const log = getLogger('session-process');
 // generator through Session / DaemonServer constructors.
 let _guardianFollowUpGenerator: GuardianFollowUpConversationGenerator | undefined;
 let _guardianActionCopyGenerator: GuardianActionCopyGenerator | undefined;
+let _approvalConversationGenerator: ApprovalConversationGenerator | undefined;
 
 /** Inject the guardian follow-up conversation generator (called from lifecycle.ts). */
 export function setGuardianFollowUpConversationGenerator(gen: GuardianFollowUpConversationGenerator): void {
@@ -62,6 +68,11 @@ export function setGuardianActionCopyGenerator(gen: GuardianActionCopyGenerator)
   _guardianActionCopyGenerator = gen;
 }
 
+/** Inject the approval conversation generator (called from lifecycle.ts). */
+export function setApprovalConversationGenerator(gen: ApprovalConversationGenerator): void {
+  _approvalConversationGenerator = gen;
+}
+
 /** Build a model_info event with fresh config data. */
 function buildModelInfoEvent(): ServerMessage {
   const config = getConfig();
@@ -105,6 +116,7 @@ export interface ProcessSessionContext {
   /** Assistant identity — used for scoping notification preferences. */
   readonly assistantId?: string;
   guardianContext?: GuardianRuntimeContext;
+  ensureActorScopedHistory(): Promise<void>;
   persistUserMessage(content: string, attachments: UserMessageAttachment[], requestId?: string, metadata?: Record<string, unknown>, displayContent?: string): Promise<string>;
   runAgentLoop(
     content: string,
@@ -294,6 +306,15 @@ export async function drainQueue(session: ProcessSessionContext, reason: QueueDr
       log.info({ conversationId: session.conversationId, channelHint: guardianIntent.channelHint }, 'Guardian verification intent intercepted in queue — forcing skill flow');
       agentLoopContent = guardianIntent.rewrittenContent;
       session.preactivatedSkillIds = ['guardian-verify-setup'];
+    } else {
+      // Guardian invite intent interception — force invite management
+      // requests into the trusted-contacts skill flow.
+      const inviteIntent = resolveGuardianInviteIntent(resolvedContent);
+      if (inviteIntent.kind === 'invite_management') {
+        log.info({ conversationId: session.conversationId, action: inviteIntent.action }, 'Guardian invite intent intercepted in queue — forcing skill flow');
+        agentLoopContent = inviteIntent.rewrittenContent;
+        session.preactivatedSkillIds = ['trusted-contacts'];
+      }
     }
   }
 
@@ -380,481 +401,277 @@ export async function processMessage(
   options?: { isInteractive?: boolean },
   displayContent?: string,
 ): Promise<string> {
+  await session.ensureActorScopedHistory();
   session.currentActiveSurfaceId = activeSurfaceId;
   session.currentPage = currentPage;
 
-  // ── Guardian action answer interception (mac channel) ──
-  // If this conversation has pending guardian action deliveries, treat the
-  // user message as the guardian's answer instead of running the agent loop.
-  // 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();
-      }
-    }
-
-    // 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]) {
+  // ── Unified guardian action answer interception (mac channel) ──
+  // Deterministic priority matching: pending → follow-up → expired.
+  // When the guardian includes an explicit request code, match it across all
+  // states in priority order. When only one actionable request exists,
+  // auto-match without requiring a code prefix.
+  {
+    const allPending = getPendingDeliveriesByConversation(session.conversationId);
+    const allFollowup = getFollowupDeliveriesByConversation(session.conversationId);
+    const allExpired = getExpiredDeliveriesByConversation(session.conversationId);
+    const totalActionable = allPending.length + allFollowup.length + allExpired.length;
+
+    if (totalActionable > 0) {
+      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 };
+
+      // Try to parse an explicit request code from the message, in priority order
+      type CodeMatch = { delivery: typeof allPending[0]; request: NonNullable<ReturnType<typeof getGuardianActionRequest>>; state: 'pending' | 'followup' | 'expired'; answerText: string };
+      let codeMatch: CodeMatch | null = null;
+      const upperContent = content.toUpperCase();
+      const orderedSets: Array<{ deliveries: typeof allPending; state: 'pending' | 'followup' | 'expired' }> = [
+        { deliveries: allPending, state: 'pending' },
+        { deliveries: allFollowup, state: 'followup' },
+        { deliveries: allExpired, state: 'expired' },
+      ];
+      for (const { deliveries, state } of orderedSets) {
+        for (const d of deliveries) {
           const req = getGuardianActionRequest(d.requestId);
-          if (req && content.toUpperCase().startsWith(req.requestCode)) {
-            matchesOtherState = true;
+          if (req && upperContent.startsWith(req.requestCode)) {
+            codeMatch = { delivery: d, request: req, state, answerText: content.slice(req.requestCode.length).trim() };
             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 (codeMatch) break;
       }
-    }
 
-    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,
-          'user',
-          JSON.stringify(userMsg.content),
-          guardianChannelMeta,
-        );
-        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',
-            });
+      // Explicit code targets a non-pending state: handle terminal superseded
+      if (codeMatch && codeMatch.state !== 'pending') {
+        const targetReq = codeMatch.request;
+        if (targetReq.status === 'expired' && targetReq.expiredReason === 'superseded') {
+          const callSession = getCallSession(targetReq.callSessionId);
+          const callStillActive = callSession && !isTerminalState(callSession.status);
+          if (!callStillActive) {
+            const userMsg = createUserMessage(content, attachments);
+            const persisted = await conversationStore.addMessage(session.conversationId, 'user', JSON.stringify(userMsg.content), guardianChannelMeta);
+            session.messages.push(userMsg);
+            const staleText = await composeGuardianActionMessageGenerative({ scenario: 'guardian_stale_superseded' }, {}, _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;
           }
-
-          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;
       }
-    }
-  }
 
-  // ── 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'). 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();
-      }
-    }
-
-    // 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;
+      // Auto-match: single actionable request across all states
+      if (!codeMatch && totalActionable === 1) {
+        const singleDelivery = allPending[0] ?? allFollowup[0] ?? allExpired[0];
+        const singleReq = getGuardianActionRequest(singleDelivery.requestId);
+        if (singleReq) {
+          const state: 'pending' | 'followup' | 'expired' = allPending.length === 1 ? 'pending' : allFollowup.length === 1 ? 'followup' : 'expired';
+          let text = content;
+          if (upperContent.startsWith(singleReq.requestCode)) {
+            text = content.slice(singleReq.requestCode.length).trim();
+          }
+          codeMatch = { delivery: singleDelivery, request: singleReq, state, answerText: text };
         }
       }
 
-      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;
+      // Unknown code: message starts with a 6-char alphanumeric token that doesn't match
+      if (!codeMatch && totalActionable > 0) {
+        const possibleCodeMatch = content.match(/^([A-F0-9]{6})\s/i);
+        if (possibleCodeMatch) {
+          const candidateCode = possibleCodeMatch[1].toUpperCase();
+          const allDeliveries = [...allPending, ...allFollowup, ...allExpired];
+          const knownCodes = allDeliveries
+            .map((d) => { const req = getGuardianActionRequest(d.requestId); return req?.requestCode; })
+            .filter((code): code is string => typeof code === 'string');
+          if (!knownCodes.includes(candidateCode)) {
+            const userMsg = createUserMessage(content, attachments);
+            const persisted = await conversationStore.addMessage(session.conversationId, 'user', JSON.stringify(userMsg.content), guardianChannelMeta);
+            session.messages.push(userMsg);
+            const unknownText = await composeGuardianActionMessageGenerative({ scenario: 'guardian_unknown_code', unknownCode: candidateCode }, {}, _guardianActionCopyGenerator);
+            const unknownMsg = createAssistantMessage(unknownText);
+            await conversationStore.addMessage(session.conversationId, 'assistant', JSON.stringify(unknownMsg.content), guardianChannelMeta);
+            session.messages.push(unknownMsg);
+            onEvent({ type: 'assistant_text_delta', text: unknownText });
+            onEvent({ type: 'message_complete', sessionId: session.conversationId });
+            return persisted.id;
           }
         }
-
-        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 };
+      // No match and multiple actionable requests → disambiguation
+      if (!codeMatch && totalActionable > 1) {
         const userMsg = createUserMessage(content, attachments);
-        const persisted = await conversationStore.addMessage(
-          session.conversationId,
-          'user',
-          JSON.stringify(userMsg.content),
-          guardianChannelMeta,
-        );
+        const persisted = await conversationStore.addMessage(session.conversationId, 'user', JSON.stringify(userMsg.content), guardianChannelMeta);
         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 });
-        }
+        const allDeliveries = [...allPending, ...allFollowup, ...allExpired];
+        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 disambiguationScenario = allPending.length > 0
+          ? 'guardian_pending_disambiguation' as const
+          : allFollowup.length > 0
+            ? 'guardian_followup_disambiguation' as const
+            : 'guardian_expired_disambiguation' as const;
+        const disambiguationText = await composeGuardianActionMessageGenerative(
+          { scenario: disambiguationScenario, 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;
       }
-    }
-  }
 
-  // ── 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. 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();
-      }
-    }
+      // Dispatch matched delivery by state
+      if (codeMatch) {
+        const { request, state, answerText } = codeMatch;
 
-    // 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;
-        }
-      }
+        // PENDING state handler
+        if (state === 'pending' && request.status === 'pending') {
+          const userMsg = createUserMessage(content, attachments);
+          const persisted = await conversationStore.addMessage(session.conversationId, 'user', JSON.stringify(userMsg.content), guardianChannelMeta);
+          session.messages.push(userMsg);
 
-      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;
+          const answerResult = await answerCall({ callSessionId: request.callSessionId, answer: answerText, pendingQuestionId: request.pendingQuestionId });
+
+          if ('ok' in answerResult && answerResult.ok) {
+            const resolved = resolveGuardianActionRequest(request.id, answerText, 'vellum');
+            if (resolved) {
+              await tryMintGuardianActionGrant({ request, answerText, decisionChannel: 'vellum', approvalConversationGenerator: _approvalConversationGenerator });
+            }
+            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: request.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;
         }
 
-        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 };
+        // FOLLOW-UP state handler
+        if (state === 'followup' && request.followupState === 'awaiting_guardian_choice') {
           const userMsg = createUserMessage(content, attachments);
-          const persisted = await conversationStore.addMessage(
-            session.conversationId,
-            'user',
-            JSON.stringify(userMsg.content),
-            guardianChannelMeta,
-          );
+          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,
+          const turnResult = await processGuardianFollowUpTurn(
+            { questionText: request.questionText, lateAnswerText: request.lateAnswerText ?? '', guardianReply: answerText },
+            _guardianFollowUpGenerator,
           );
-          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);
+          let stateApplied = true;
+          if (turnResult.disposition === 'call_back' || turnResult.disposition === 'message_back') {
+            stateApplied = progressFollowupState(request.id, 'dispatching', turnResult.disposition) !== undefined;
+          } else if (turnResult.disposition === 'decline') {
+            stateApplied = finalizeFollowup(request.id, 'declined') !== undefined;
+          }
 
-        const turnResult = await processGuardianFollowUpTurn(
-          {
-            questionText: followupRequest.questionText,
-            lateAnswerText: followupRequest.lateAnswerText ?? '',
-            guardianReply: followupReplyText,
-          },
-          _guardianFollowUpGenerator,
-        );
+          if (!stateApplied) {
+            log.warn({ requestId: request.id, disposition: turnResult.disposition }, 'Follow-up state transition failed (already resolved)');
+          }
 
-        // 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
+          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 });
 
-        if (!stateApplied) {
-          log.warn({ requestId: followupRequest.id, disposition: turnResult.disposition }, 'Follow-up state transition failed (already resolved)');
+          if (stateApplied && (turnResult.disposition === 'call_back' || turnResult.disposition === 'message_back')) {
+            void (async () => {
+              try {
+                const execResult = await executeFollowupAction(request.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: request.id }, 'Follow-up action execution or completion message failed');
+              }
+            })();
+          }
+          return persisted.id;
         }
 
-        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 });
+        // EXPIRED state handler
+        if (state === 'expired' && request.status === 'expired' && request.followupState === 'none') {
+          const userMsg = createUserMessage(content, attachments);
+          const persisted = await conversationStore.addMessage(session.conversationId, 'user', JSON.stringify(userMsg.content), guardianChannelMeta);
+          session.messages.push(userMsg);
 
-        // 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');
+          // Superseded remap
+          if (request.expiredReason === 'superseded') {
+            const callSession = getCallSession(request.callSessionId);
+            const callStillActive = callSession && !isTerminalState(callSession.status);
+            const currentPending = callStillActive ? getPendingRequestByCallSessionId(request.callSessionId) : null;
+
+            if (callStillActive && currentPending) {
+              const currentDeliveries = getDeliveriesByRequestId(currentPending.id);
+              const guardianExtUserId = session.guardianContext?.guardianExternalUserId;
+              // When guardianExternalUserId is present, verify the sender has a
+              // matching delivery on the current pending request. When it's absent
+              // (trusted Vellum/HTTP session), allow the remap without delivery check.
+              const senderHasDelivery = guardianExtUserId
+                ? currentDeliveries.some((d) => d.destinationExternalUserId === guardianExtUserId)
+                : true;
+              if (!senderHasDelivery) {
+                log.info({ supersededRequestId: request.id, currentRequestId: currentPending.id, guardianExternalUserId: guardianExtUserId }, 'Superseded remap skipped: sender has no delivery on current pending request');
+              } else {
+                const remapResult = await answerCall({ callSessionId: currentPending.callSessionId, answer: answerText, pendingQuestionId: currentPending.pendingQuestionId });
+                if ('ok' in remapResult && remapResult.ok) {
+                  const resolved = resolveGuardianActionRequest(currentPending.id, answerText, 'vellum');
+                  if (resolved) {
+                    await tryMintGuardianActionGrant({ request: currentPending, answerText, decisionChannel: 'vellum', approvalConversationGenerator: _approvalConversationGenerator });
+                  }
+                  const remapText = await composeGuardianActionMessageGenerative({ scenario: 'guardian_superseded_remap', questionText: currentPending.questionText }, {}, _guardianActionCopyGenerator);
+                  const remapMsg = createAssistantMessage(remapText);
+                  await conversationStore.addMessage(session.conversationId, 'assistant', JSON.stringify(remapMsg.content), guardianChannelMeta);
+                  session.messages.push(remapMsg);
+                  onEvent({ type: 'assistant_text_delta', text: remapText });
+                  onEvent({ type: 'message_complete', sessionId: session.conversationId });
+                  log.info({ supersededRequestId: request.id, remappedToRequestId: currentPending.id }, 'Late approval for superseded request remapped to current pending request');
+                  return persisted.id;
+                }
+                log.warn({ callSessionId: currentPending.callSessionId, error: 'error' in remapResult ? remapResult.error : 'unknown' }, 'Superseded remap answerCall failed, falling through to follow-up');
+              }
             }
-          })();
-        }
+          }
 
-        return persisted.id;
+          const followupResult = startFollowupFromExpiredRequest(request.id, answerText);
+          if (followupResult) {
+            const followupText = await composeGuardianActionMessageGenerative({ scenario: 'guardian_late_answer_followup', questionText: request.questionText, lateAnswerText: answerText }, {}, _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 {
+            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;
+        }
       }
     }
   }
@@ -942,6 +759,15 @@ export async function processMessage(
       log.info({ conversationId: session.conversationId, channelHint: guardianIntent.channelHint }, 'Guardian verification intent intercepted — forcing skill flow');
       agentLoopContent = guardianIntent.rewrittenContent;
       session.preactivatedSkillIds = ['guardian-verify-setup'];
+    } else {
+      // Guardian invite intent interception — force invite management
+      // requests into the trusted-contacts skill flow.
+      const inviteIntent = resolveGuardianInviteIntent(resolvedContent);
+      if (inviteIntent.kind === 'invite_management') {
+        log.info({ conversationId: session.conversationId, action: inviteIntent.action }, 'Guardian invite intent intercepted — forcing skill flow');
+        agentLoopContent = inviteIntent.rewrittenContent;
+        session.preactivatedSkillIds = ['trusted-contacts'];
+      }
     }
   }