@murphai/murph 1.3.0 → 1.3.1

package/node_modules/@murphai/assistant-engine/dist/assistant/outbox.js

@@ -1,5 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { ASSISTANT_ANSWERED_MAILBOX_ITEM_ID_LIMIT, assistantChannelDeliverySchema, assistantOutboxIntentSchema, } from '@murphai/operator-config/assistant-cli-contracts';
+import { assistantResponseCardMatchesConversationAudience, assistantResponseCardSchema, renderAssistantResponseCardText, } from '@murphai/operator-config/assistant-response-cards';
 import {} from '@murphai/query';
 import { parseHostedEmailThreadTarget } from '@murphai/runtime-state';
 import { VaultCliError } from '@murphai/operator-config/vault-cli-errors';
@@ -13,13 +14,13 @@ import { withAssistantRuntimeWriteLock } from './runtime-write-lock.js';
 import { ensureAssistantState } from './store/persistence.js';
 import { getAssistantSession, resolveAssistantStatePaths, saveAssistantSession } from './store.js';
 import { appendAssistantTurnReceiptEvent } from './turns.js';
-import { buildAssistantOutboxPersistedTarget, buildAssistantOutboxRawTargetIdentity, hashAssistantOutboxIdentity, hashAssistantOutboxTargetFingerprint, resolveAssistantOutboxIntentPath, } from './outbox/intents.js';
+import { buildAssistantOutboxPersistedTarget, buildAssistantOutboxRawTargetIdentity, hashAssistantOutboxIdentity, hashAssistantOutboxLegacyMediaDedupeIdentity, hashAssistantOutboxTargetFingerprint, resolveAssistantOutboxIntentPath, } from './outbox/intents.js';
 import { assistantDeliveryErrorPreventsFreshIntentRetry, createAssistantDeliveryAmbiguousError, createAssistantDeliveryConfirmationPendingError, createAssistantDeliveryRetryExhaustedError, isAssistantOutboxRetryBudgetExhausted, isAssistantOutboxRetryableError, normalizeAssistantDeliveryError, shouldBeginAssistantOutboxDispatch, shouldDispatchAssistantOutboxIntent, } from './outbox/retry-policy.js';
 import { buildAssistantOutboxSummary as buildAssistantOutboxSummaryLocal } from './outbox/summary.js';
 import { repairAssistantOutboxReceiptForIntent } from './outbox/receipt-repair.js';
-import { findAssistantOutboxIntentByDedupeIdentity, listAssistantOutboxIntentsLocal as listAssistantOutboxIntentsLocalStore, readAssistantOutboxIntent as readAssistantOutboxIntentLocal, readAssistantOutboxIntentAtPath, saveAssistantOutboxIntent as saveAssistantOutboxIntentLocal, } from './outbox/store.js';
-import { buildAssistantOutboxIntentMirrorState, buildAssistantDeliveryIdempotencyKey, errorImpliesAssistantDeliveryMayHaveSucceeded, markAssistantOutboxIntentMirrorRetryable, markAssistantOutboxIntentMirrorSending, markAssistantOutboxIntentMirrorSendingPrepared, markAssistantOutboxIntentMirrorTerminal, markAssistantOutboxIntentSent, assistantOutboxIntentMatchesDispatchOwner, persistAssistantOutboxIntentDeliveryPendingConfirmation, resetAssistantOutboxPreparedDispatch, rescheduleAssistantOutboxConfirmationRetry, sameAssistantChannelDelivery, updateAssistantOutboxAfterDispatchFailure, } from './outbox/dispatch-state.js';
-import { normalizeNullableString, writeJsonFileAtomic, } from './shared.js';
+import { findAssistantOutboxIntentByDedupeIdentity, listAssistantOutboxIntentsForAutoReplyRoute as listAssistantOutboxIntentsForAutoReplyRouteStore, listAssistantOutboxIntentsForPrivateCompletionRoute as listAssistantOutboxIntentsForPrivateCompletionRouteStore, listAssistantOutboxIntentsLocal as listAssistantOutboxIntentsLocalStore, persistAssistantOutboxIntentAtPath, readAssistantOutboxIntent as readAssistantOutboxIntentLocal, readAssistantOutboxIntentAtPath, saveAssistantOutboxIntent as saveAssistantOutboxIntentLocal, } from './outbox/store.js';
+import { buildAssistantOutboxIntentMirrorState, buildAssistantDeliveryIdempotencyKey, errorImpliesAssistantDeliveryMayHaveSucceeded, markAssistantOutboxIntentMirrorRetryable, markAssistantOutboxIntentMirrorSending, markAssistantOutboxIntentMirrorSendingPrepared, markAssistantOutboxIntentMirrorTerminal, markAssistantOutboxIntentSent, assistantOutboxIntentMatchesDispatchOwner, persistAssistantOutboxIntentDeliveryPendingConfirmation, persistAssistantOutboxIntentLinqAppCardTextFallback, preserveAssistantOutboxAcceptedMediaDeliveryOrder, resetAssistantOutboxPreparedDispatch, rescheduleAssistantOutboxConfirmationRetry, sameAssistantChannelDelivery, updateAssistantOutboxAfterDispatchFailure, } from './outbox/dispatch-state.js';
+import { normalizeNullableString, writeJsonFileAtomic } from './shared.js';
 import { sanitizeAssistantOutboxIntentForPersistence } from './redaction.js';
 import { normalizeAssistantResponseMediaList, } from './response-media.js';
 import { writeAssistantAutoReplyIntentProvenance } from './automation/intent-provenance.js';
@@ -36,11 +37,19 @@ export async function createAssistantOutboxIntent(input) {
         const createdAt = input.createdAt ?? new Date().toISOString();
         const initialState = input.initialState ?? { status: 'pending' };
         const media = normalizeAssistantResponseMediaList(input.media ?? []);
+        const card = input.card == null
+            ? null
+            : assistantResponseCardSchema.parse(input.card);
         const operation = normalizeAssistantOutboxReactionOperation(input.operation ?? null);
-        const message = operation ? '' : normalizeOutboxMessage({
-            media,
-            message: input.message,
-        });
+        assertAssistantOutboxCardCompatible({ card, media, operation });
+        const message = operation
+            ? ''
+            : card
+                ? renderAssistantResponseCardText(card)
+                : normalizeOutboxMessage({
+                    media,
+                    message: input.message,
+                });
         assertAssistantOutboxResponseMediaSupported({
             channel: input.channel ?? null,
             media,
@@ -52,6 +61,22 @@ export async function createAssistantOutboxIntent(input) {
             ...input,
             replyToMessageId,
         });
+        if (card?.kind === 'challenge_standings' && !(assistantResponseCardMatchesConversationAudience({
+            card,
+            channel: persistedTarget.channel,
+            threadIsDirect: persistedTarget.threadIsDirect,
+        }))) {
+            throw new VaultCliError('ASSISTANT_CHALLENGE_RESPONSE_CARD_GROUP_AUDIENCE_REQUIRED', 'A challenge standings response card requires an authenticated Linq group conversation.');
+        }
+        if (card !== null &&
+            card.kind !== 'challenge_standings' &&
+            !assistantResponseCardMatchesConversationAudience({
+                card,
+                channel: persistedTarget.channel,
+                threadIsDirect: persistedTarget.threadIsDirect,
+            })) {
+            throw new VaultCliError('ASSISTANT_RESPONSE_CARD_DIRECT_AUDIENCE_REQUIRED', 'A response card requires a private direct conversation.');
+        }
         assertAssistantOutboxNativeReplyTarget({
             channel: persistedTarget.channel,
             nativeReplyRequested: persistedTarget.nativeReplyRequested,
@@ -69,6 +94,7 @@ export async function createAssistantOutboxIntent(input) {
         const rawTargetIdentity = buildAssistantOutboxRawTargetIdentity(persistedTarget);
         const dedupeKey = hashAssistantOutboxIdentity({
             dedupeToken: input.dedupeToken,
+            card,
             media,
             message,
             operation,
@@ -79,6 +105,10 @@ export async function createAssistantOutboxIntent(input) {
         });
         const deliveryIdempotencyKey = normalizeNullableString(input.deliveryIdempotencyKey);
         const answeredMailboxItemIds = normalizeAssistantOutboxAnsweredMailboxItemIds(input.answeredMailboxItemIds ?? []);
+        const automationContextReferences = input.automationContextReferences?.map((reference) => ({
+            entityId: reference.entityId,
+            entityKind: reference.entityKind,
+        })) ?? [];
         const deliveryTransportIdempotent = operation
             ? resolveAssistantOutboxReactionTransportIdempotent({
                 channel: input.channel ?? null,
@@ -92,10 +122,18 @@ export async function createAssistantOutboxIntent(input) {
                     media,
                     message,
                 });
+        const exactDeliveryIdempotencyKey = hasSharedHostedEmailGroupDeliveryIdentity(persistedTarget)
+            ? null
+            : deliveryIdempotencyKey;
         const existing = await findAssistantOutboxIntentByDedupeIdentity({
             dedupeKey,
-            deliveryIdempotencyKey,
             dedupeToken: input.dedupeToken,
+            deliveryIdempotencyKey: exactDeliveryIdempotencyKey,
+            legacyDedupeKey: hashAssistantOutboxLegacyMediaDedupeIdentity({
+                dedupeToken: input.dedupeToken,
+                media,
+            }),
+            skipLegacyMediaFallback: deliveryIdempotencyKey !== null,
             vault: input.vault,
         });
         const isAutoReplyIntent = input.turnTrigger === 'automation-auto-reply';
@@ -142,8 +180,12 @@ export async function createAssistantOutboxIntent(input) {
                 });
             }
             if (upgradedExisting !== existing) {
-                const persistedUpgradedExisting = sanitizeAssistantOutboxIntentForPersistence(upgradedExisting);
-                await writeJsonFileAtomic(resolveAssistantOutboxIntentPath(paths.outboxDirectory, upgradedExisting.intentId), persistedUpgradedExisting);
+                await persistAssistantOutboxIntentAtPath({
+                    dedupeIdentityOrigin: 'current',
+                    intent: upgradedExisting,
+                    intentPath: resolveAssistantOutboxIntentPath(paths.outboxDirectory, upgradedExisting.intentId),
+                    paths,
+                });
             }
             await repairAssistantOutboxReceiptForIntent({
                 at: upgradedExisting.updatedAt,
@@ -169,24 +211,34 @@ export async function createAssistantOutboxIntent(input) {
             message,
             emailHtml: input.emailHtml ?? null,
             media,
+            card,
             subject,
             operation,
             dedupeKey,
             targetFingerprint: hashAssistantOutboxTargetFingerprint(rawTargetIdentity),
             ...persistedTarget,
             automationAuthority: input.automationAuthority ?? null,
+            ...(automationContextReferences.length === 0
+                ? {}
+                : { automationContextReferences }),
+            plannedOccurrenceAt: input.plannedOccurrenceAt ?? null,
+            scheduledOccurrenceAt: input.scheduledOccurrenceAt ?? null,
             externalThreadRouteAuthority: input.externalThreadRouteAuthority ?? null,
             delivery: null,
             deliveryConfirmationPending: false,
             deliveryIdempotencyKey,
             deliveryTransportIdempotent,
-            newsletterAuthorizationProof: input.newsletterAuthorizationProof ?? null,
+            groupEmailAuthorizationProof: input.groupEmailAuthorizationProof ?? null,
             answeredMailboxItemIds,
             reviewedAssistantAskCompletionExpiresAt: input.reviewedAssistantAskCompletionExpiresAt ?? undefined,
+            ...(input.privateCompletionContinuitySessionId === undefined
+                ? {}
+                : {
+                    privateCompletionContinuitySessionId: input.privateCompletionContinuitySessionId,
+                }),
             lastError: null,
         });
         const persistedIntent = assistantOutboxIntentSchema.parse(sanitizeAssistantOutboxIntentForPersistence(intent));
-        const persistedIntentValue = sanitizeAssistantOutboxIntentForPersistence(persistedIntent);
         if (isAutoReplyIntent) {
             await writeAssistantAutoReplyIntentProvenance({
                 intentId: intent.intentId,
@@ -195,7 +247,12 @@ export async function createAssistantOutboxIntent(input) {
                 vault: input.vault,
             });
         }
-        await writeJsonFileAtomic(resolveAssistantOutboxIntentPath(paths.outboxDirectory, intent.intentId), persistedIntentValue);
+        await persistAssistantOutboxIntentAtPath({
+            dedupeIdentityOrigin: 'current',
+            intent: persistedIntent,
+            intentPath: resolveAssistantOutboxIntentPath(paths.outboxDirectory, intent.intentId),
+            paths,
+        });
         await repairAssistantOutboxReceiptForIntent({
             at: createdAt,
             intent: persistedIntent,
@@ -236,9 +293,9 @@ export async function saveAssistantOutboxIntent(vault, intent) {
     return saveAssistantOutboxIntentLocal(vault, intent);
 }
 /**
- * Compare-and-set persistence for state derived from a remote approval check.
- * A concurrent dispatcher or approval reconciliation always wins over a stale
- * snapshot, while action identity reuse still fails closed.
+ * Compare-and-set persistence for outbox-owner state transitions. The explicit
+ * outcome lets callers distinguish their own write from a concurrent owner;
+ * action identity reuse still fails closed.
  */
 export async function saveAssistantOutboxIntentIfUnchanged(input) {
     return withAssistantRuntimeWriteLock(input.vault, async (paths) => {
@@ -256,27 +313,42 @@ export async function saveAssistantOutboxIntentIfUnchanged(input) {
         }
         if (current.status !== input.expectedStatus
             || current.updatedAt !== input.expectedUpdatedAt) {
-            return current;
+            return {
+                applied: false,
+                intent: current,
+            };
         }
         const parsed = assistantOutboxIntentSchema.parse(sanitizeAssistantOutboxIntentForPersistence(input.intent));
         if (parsed.intentId !== current.intentId) {
             throw new VaultCliError('ASSISTANT_OUTBOX_IDENTITY_CONFLICT', 'Assistant outbox intent id changed during approval reconciliation.');
         }
-        const persisted = sanitizeAssistantOutboxIntentForPersistence(parsed);
-        await writeJsonFileAtomic(intentPath, persisted);
+        await persistAssistantOutboxIntentAtPath({
+            intent: parsed,
+            intentPath,
+            paths,
+        });
         await repairAssistantOutboxReceiptForIntent({
             at: parsed.updatedAt,
             intent: parsed,
             vault: input.vault,
         });
-        return parsed;
+        return {
+            applied: true,
+            intent: parsed,
+        };
     });
 }
-export async function listAssistantOutboxIntents(vault) {
-    return listAssistantOutboxIntentsLocalStore(vault);
+export async function listAssistantOutboxIntents(vault, onScan) {
+    return listAssistantOutboxIntentsLocalStore(vault, onScan);
+}
+export async function listAssistantOutboxIntentsLocal(vault, onScan) {
+    return listAssistantOutboxIntentsLocalStore(vault, onScan);
 }
-export async function listAssistantOutboxIntentsLocal(vault) {
-    return listAssistantOutboxIntentsLocalStore(vault);
+export async function listAssistantOutboxIntentsForAutoReplyRoute(input) {
+    return listAssistantOutboxIntentsForAutoReplyRouteStore(input);
+}
+export async function listAssistantOutboxIntentsForPrivateCompletionRoute(input) {
+    return listAssistantOutboxIntentsForPrivateCompletionRouteStore(input);
 }
 export async function dispatchAssistantOutboxIntent(input) {
     return dispatchAssistantOutboxIntentInternal({
@@ -295,6 +367,20 @@ async function dispatchAssistantOutboxIntentInternal(input) {
         if (!intent) {
             throw new Error(`Assistant outbox intent ${input.intentId} was not found.`);
         }
+        const pendingTerminalConfirmation = readAssistantOutboxPendingTerminalConfirmation({
+            dispatchHooks: input.dispatchHooks,
+            intent,
+            vault: input.vault,
+        });
+        if (pendingTerminalConfirmation &&
+            shouldBeginAssistantOutboxDispatch(intent, now, input.force === true)) {
+            return {
+                action: 'confirm-terminal',
+                intent,
+                intentPath,
+                outcome: pendingTerminalConfirmation,
+            };
+        }
         if (input.allowPreparedSending === true && intent.status === 'sending') {
             if (!input.preparedDispatch ||
                 !assistantOutboxIntentMatchesPreparedDispatch(intent, input.preparedDispatch)) {
@@ -316,6 +402,20 @@ async function dispatchAssistantOutboxIntentInternal(input) {
                 intent,
             };
         }
+        if (shouldFailClosedAssistantOutboxStaleSendingIntent(intent)) {
+            return {
+                action: 'recover-stale-non-idempotent',
+                intent,
+                intentPath,
+            };
+        }
+        if (resolvePersistedAssistantOutboxDelivery(intent)) {
+            return {
+                action: 'reconcile',
+                intent,
+                intentPath,
+            };
+        }
         if ((intent.status === 'retryable' ||
             (intent.status === 'sending' &&
                 inferAssistantOutboxDeliveryTransportIdempotent(intent))) &&
@@ -329,13 +429,6 @@ async function dispatchAssistantOutboxIntentInternal(input) {
                 intentPath,
             };
         }
-        if (shouldFailClosedAssistantOutboxStaleSendingIntent(intent)) {
-            return {
-                action: 'recover-stale-non-idempotent',
-                intent,
-                intentPath,
-            };
-        }
         if (shouldReconcileAssistantOutboxIntent(intent)) {
             return {
                 action: 'reconcile',
@@ -361,8 +454,11 @@ async function dispatchAssistantOutboxIntentInternal(input) {
             status: 'sending',
         }));
         const persistedSending = assistantOutboxIntentSchema.parse(sanitizeAssistantOutboxIntentForPersistence(sending));
-        const persistedSendingValue = sanitizeAssistantOutboxIntentForPersistence(persistedSending);
-        await writeJsonFileAtomic(intentPath, persistedSendingValue);
+        await persistAssistantOutboxIntentAtPath({
+            intent: persistedSending,
+            intentPath,
+            paths,
+        });
         await appendAssistantTurnReceiptEvent({
             vault: input.vault,
             turnId: persistedSending.turnId,
@@ -381,6 +477,20 @@ async function dispatchAssistantOutboxIntentInternal(input) {
             sending: persistedSending,
         };
     });
+    if (prepared.action === 'confirm-terminal') {
+        const confirmedIntent = await confirmAssistantOutboxTerminalIntent({
+            dispatchHooks: input.dispatchHooks,
+            intent: prepared.intent,
+            intentPath: prepared.intentPath,
+            outcome: prepared.outcome,
+            vault: input.vault,
+        });
+        return {
+            intent: confirmedIntent,
+            deliveryError: confirmedIntent.lastError,
+            session: null,
+        };
+    }
     if (prepared.action === 'skip') {
         await repairAssistantOutboxReceiptForIntent({
             intent: prepared.intent,
@@ -400,6 +510,10 @@ async function dispatchAssistantOutboxIntentInternal(input) {
             resolvePersistedAssistantOutboxDelivery(prepared.intent);
         if (recoveredDelivery) {
             const sentIntent = await markAssistantOutboxIntentSent({
+                completedAt: resolveRecoveredAssistantOutboxDeliveryCompletedAt({
+                    delivery: recoveredDelivery,
+                    intent: prepared.intent,
+                }),
                 delivery: recoveredDelivery,
                 intent: prepared.intent,
                 intentPath: prepared.intentPath,
@@ -411,15 +525,31 @@ async function dispatchAssistantOutboxIntentInternal(input) {
                 session: null,
             };
         }
-        const failedIntent = await markAssistantOutboxIntentMirrorTerminal({
-            error: createAssistantDeliveryRetryExhaustedError(prepared.intent.lastError),
-            failedAt: now,
+        const retryExhaustedError = createAssistantDeliveryRetryExhaustedError(prepared.intent.lastError);
+        const failedIntent = assistantOutboxIntentRequiresTerminalConfirmation({
+            dispatchHooks: input.dispatchHooks,
             intent: prepared.intent,
-            intentPath: prepared.intentPath,
-            onlyCurrentStatuses: ['retryable', 'sending'],
-            status: 'failed',
             vault: input.vault,
-        });
+        })
+            ? await finalizeAssistantOutboxTerminalFailure({
+                deliveryMayHaveSucceeded: false,
+                deliveryTransportIdempotent: prepared.intent.deliveryTransportIdempotent,
+                dispatchHooks: input.dispatchHooks,
+                error: retryExhaustedError,
+                failedAt: now,
+                intent: prepared.intent,
+                intentPath: prepared.intentPath,
+                vault: input.vault,
+            })
+            : await markAssistantOutboxIntentMirrorTerminal({
+                error: retryExhaustedError,
+                failedAt: now,
+                intent: prepared.intent,
+                intentPath: prepared.intentPath,
+                onlyCurrentStatuses: ['retryable', 'sending'],
+                status: 'failed',
+                vault: input.vault,
+            });
         return {
             intent: failedIntent,
             deliveryError: failedIntent.lastError,
@@ -449,32 +579,70 @@ async function dispatchAssistantOutboxIntentInternal(input) {
         });
     }
     if (prepared.action === 'recover-stale-non-idempotent') {
+        const terminalConfirmationRequired = assistantOutboxIntentRequiresTerminalConfirmation({
+            dispatchHooks: input.dispatchHooks,
+            intent: prepared.intent,
+            vault: input.vault,
+        });
         const recoveredDelivery = (await input.dispatchHooks?.resolveDeliveredIntent?.({
             intent: prepared.intent,
             vault: input.vault,
         })) ??
             resolvePersistedAssistantOutboxDelivery(prepared.intent);
         if (recoveredDelivery) {
-            const sentIntent = await markAssistantOutboxIntentSent({
+            const completedAt = resolveRecoveredAssistantOutboxDeliveryCompletedAt({
                 delivery: recoveredDelivery,
                 intent: prepared.intent,
-                intentPath: prepared.intentPath,
-                vault: input.vault,
             });
+            const sentIntent = terminalConfirmationRequired
+                ? await finalizeAssistantOutboxTerminalDelivery({
+                    completedAt,
+                    delivery: recoveredDelivery,
+                    dispatchHooks: input.dispatchHooks,
+                    intent: prepared.intent,
+                    intentPath: prepared.intentPath,
+                    vault: input.vault,
+                })
+                : await markAssistantOutboxIntentSent({
+                    completedAt,
+                    delivery: recoveredDelivery,
+                    intent: prepared.intent,
+                    intentPath: prepared.intentPath,
+                    vault: input.vault,
+                });
             return {
                 intent: sentIntent,
-                deliveryError: null,
+                deliveryError: sentIntent.status === 'sent' ? null : sentIntent.lastError,
                 session: null,
             };
         }
-        const failedIntent = await markAssistantOutboxIntentMirrorTerminal({
-            error: createAssistantDeliveryAmbiguousError(new Error('Stale non-idempotent outbound delivery had no persisted delivery to reconcile after restart.')),
-            failedAt: now,
-            intent: prepared.intent,
-            intentPath: prepared.intentPath,
-            status: 'failed',
-            vault: input.vault,
-        });
+        const staleDeliveryError = new Error('Stale non-idempotent outbound delivery had no persisted delivery to reconcile after restart.');
+        const ambiguousError = terminalConfirmationRequired &&
+            prepared.intent.channel === 'telegram'
+            ? Object.assign(new VaultCliError('ASSISTANT_TELEGRAM_DELIVERY_AMBIGUOUS', staleDeliveryError.message), {
+                deliveryMayHaveSucceeded: true,
+                retryable: false,
+            })
+            : createAssistantDeliveryAmbiguousError(staleDeliveryError);
+        const failedIntent = terminalConfirmationRequired
+            ? await finalizeAssistantOutboxTerminalFailure({
+                deliveryMayHaveSucceeded: true,
+                deliveryTransportIdempotent: false,
+                dispatchHooks: input.dispatchHooks,
+                error: ambiguousError,
+                failedAt: now,
+                intent: prepared.intent,
+                intentPath: prepared.intentPath,
+                vault: input.vault,
+            })
+            : await markAssistantOutboxIntentMirrorTerminal({
+                error: ambiguousError,
+                failedAt: now,
+                intent: prepared.intent,
+                intentPath: prepared.intentPath,
+                status: 'failed',
+                vault: input.vault,
+            });
         return {
             intent: failedIntent,
             deliveryError: failedIntent.lastError,
@@ -487,6 +655,12 @@ async function dispatchAssistantOutboxIntentInternal(input) {
     let deliveryTransportIdempotent = inferAssistantOutboxDeliveryTransportIdempotent(dispatchIntent);
     let preparedDispatchReserved = false;
     let dispatchFailureOwnerIntent = dispatchIntent;
+    let effectiveDispatchIntent = dispatchIntent;
+    const terminalConfirmationRequired = assistantOutboxIntentRequiresTerminalConfirmation({
+        dispatchHooks: input.dispatchHooks,
+        intent: dispatchIntent,
+        vault: input.vault,
+    });
     try {
         const reconciledDelivery = (await input.dispatchHooks?.resolveDeliveredIntent?.({
             intent: dispatchIntent,
@@ -495,6 +669,10 @@ async function dispatchAssistantOutboxIntentInternal(input) {
             resolvePersistedAssistantOutboxDelivery(dispatchIntent);
         if (reconciledDelivery) {
             const sentIntent = await markAssistantOutboxIntentSent({
+                completedAt: resolveRecoveredAssistantOutboxDeliveryCompletedAt({
+                    delivery: reconciledDelivery,
+                    intent: dispatchIntent,
+                }),
                 delivery: reconciledDelivery,
                 intent: dispatchIntent,
                 intentPath: dispatchIntentPath,
@@ -511,7 +689,6 @@ async function dispatchAssistantOutboxIntentInternal(input) {
             const retryIntent = await rescheduleAssistantOutboxConfirmationRetry({
                 error: createAssistantDeliveryConfirmationPendingError(),
                 intentPath: dispatchIntentPath,
-                scheduledAt: new Date(),
                 sending: dispatchIntent,
                 vault: input.vault,
             });
@@ -536,6 +713,9 @@ async function dispatchAssistantOutboxIntentInternal(input) {
                 vault: input.vault,
             }));
         if (authorityError) {
+            if (terminalConfirmationRequired) {
+                throw authorityError;
+            }
             const failedIntent = await markAssistantOutboxIntentMirrorTerminal({
                 error: authorityError,
                 // `now` may be the earlier drain-selection timestamp. Authority is
@@ -557,16 +737,37 @@ async function dispatchAssistantOutboxIntentInternal(input) {
             vault: input.vault,
         });
         preparedDispatchReserved = input.dispatchHooks?.prepareDispatchIntent !== undefined;
+        const dispatchDependencies = withAssistantOutboxSignal(input.dependencies, input.signal);
         const delivered = await sendAssistantOutboxDispatchIntent({
-            dependencies: withAssistantOutboxSignal(input.dependencies, input.signal),
+            dependencies: dispatchIntent.card === null
+                ? dispatchDependencies
+                : {
+                    ...(dispatchDependencies ?? {}),
+                    persistLinqAppCardTextFallback: async ({ idempotencyKey }) => {
+                        const persisted = await persistAssistantOutboxIntentLinqAppCardTextFallback({
+                            idempotencyKey,
+                            intentPath: dispatchIntentPath,
+                            persistedAt: new Date(),
+                            sending: dispatchIntent,
+                            vault: input.vault,
+                        });
+                        effectiveDispatchIntent = persisted;
+                        dispatchFailureOwnerIntent = persisted;
+                    },
+                },
             ...dispatchIntent,
             vault: input.vault,
         });
-        const delivery = assistantChannelDeliverySchema.parse({
+        const completedDelivery = assistantChannelDeliverySchema.parse({
             ...delivered.delivery,
             idempotencyKey: delivered.delivery.idempotencyKey ??
                 dispatchIntent.deliveryIdempotencyKey,
         });
+        const completedAt = completedDelivery.sentAt;
+        const delivery = preserveAssistantOutboxAcceptedMediaDeliveryOrder({
+            delivery: completedDelivery,
+            intent: effectiveDispatchIntent,
+        });
         deliveryTransportIdempotent =
             dispatchIntent.deliveryTransportIdempotent ||
                 delivered.deliveryTransportIdempotent === true;
@@ -574,8 +775,9 @@ async function dispatchAssistantOutboxIntentInternal(input) {
         const deliveredIntent = buildAssistantOutboxDeliveredIntent({
             delivery,
             deliveryTransportIdempotent,
-            intent: dispatchIntent,
+            intent: effectiveDispatchIntent,
             session: delivered.session ?? null,
+            trackMessageVolumeReceipt: input.trackMessageVolumeReceipt === true,
         });
         const deliveredOwnerIntent = assistantOutboxIntentSchema.parse(sanitizeAssistantOutboxIntentForPersistence({
             ...deliveredIntent,
@@ -584,19 +786,22 @@ async function dispatchAssistantOutboxIntentInternal(input) {
         }));
         dispatchFailureOwnerIntent = deliveredOwnerIntent;
         const durableDeliveredIntent = await persistAssistantOutboxIntentDeliveryPendingConfirmation({
+            completedAt,
             delivery,
             deliveryTransportIdempotent,
             intent: deliveredIntent,
             intentPath: dispatchIntentPath,
+            terminalConfirmationRequired,
             vault: input.vault,
         });
-        if (!assistantOutboxIntentMatchesDispatchOwner(durableDeliveredIntent, deliveredOwnerIntent, ['sending'], false)) {
+        if (!assistantOutboxIntentMatchesDispatchOwner(durableDeliveredIntent, deliveredOwnerIntent, terminalConfirmationRequired ? ['retryable'] : ['sending'], false)) {
             return {
                 intent: durableDeliveredIntent,
                 deliveryError: durableDeliveredIntent.lastError,
                 session: null,
             };
         }
+        dispatchFailureOwnerIntent = durableDeliveredIntent;
         if (delivered.session) {
             await saveAssistantSession(input.vault, delivered.session);
         }
@@ -606,12 +811,26 @@ async function dispatchAssistantOutboxIntentInternal(input) {
             vault: input.vault,
         });
         preparedDispatchReserved = false;
-        const sentIntent = await markAssistantOutboxIntentSent({
-            delivery,
-            intent: deliveredOwnerIntent,
-            intentPath: dispatchIntentPath,
+        const pendingTerminalConfirmation = readAssistantOutboxPendingTerminalConfirmation({
+            dispatchHooks: input.dispatchHooks,
+            intent: durableDeliveredIntent,
             vault: input.vault,
         });
+        const sentIntent = pendingTerminalConfirmation
+            ? await confirmAssistantOutboxTerminalIntent({
+                dispatchHooks: input.dispatchHooks,
+                intent: durableDeliveredIntent,
+                intentPath: dispatchIntentPath,
+                outcome: pendingTerminalConfirmation,
+                vault: input.vault,
+            })
+            : await markAssistantOutboxIntentSent({
+                completedAt,
+                delivery,
+                intent: deliveredOwnerIntent,
+                intentPath: dispatchIntentPath,
+                vault: input.vault,
+            });
         if (!sentIntent.delivery || !sameAssistantChannelDelivery(sentIntent.delivery, delivery)) {
             return {
                 intent: sentIntent,
@@ -621,7 +840,7 @@ async function dispatchAssistantOutboxIntentInternal(input) {
         }
         return {
             intent: sentIntent,
-            deliveryError: null,
+            deliveryError: sentIntent.status === 'sent' ? null : sentIntent.lastError,
             session: delivered.session ?? null,
         };
     }
@@ -660,15 +879,154 @@ async function dispatchAssistantOutboxIntentInternal(input) {
             failedAt: new Date(),
             intentPath: dispatchIntentPath,
             sending: dispatchFailureOwnerIntent,
+            terminalConfirmationRequired,
             vault: input.vault,
         });
-        return {
+        const pendingTerminalConfirmation = readAssistantOutboxPendingTerminalConfirmation({
+            dispatchHooks: input.dispatchHooks,
             intent: failedIntent,
-            deliveryError: failedIntent.lastError,
+            vault: input.vault,
+        });
+        const confirmedIntent = pendingTerminalConfirmation
+            ? await confirmAssistantOutboxTerminalIntent({
+                dispatchHooks: input.dispatchHooks,
+                intent: failedIntent,
+                intentPath: dispatchIntentPath,
+                outcome: pendingTerminalConfirmation,
+                vault: input.vault,
+            })
+            : failedIntent;
+        return {
+            intent: confirmedIntent,
+            deliveryError: confirmedIntent.lastError,
             session: null,
         };
     }
 }
+function assistantOutboxIntentRequiresTerminalConfirmation(input) {
+    return input.dispatchHooks?.confirmTerminalIntent !== undefined &&
+        input.dispatchHooks.requiresTerminalConfirmation?.({
+            intent: input.intent,
+            vault: input.vault,
+        }) === true;
+}
+function readAssistantOutboxPendingTerminalConfirmation(input) {
+    if (!input.intent.deliveryConfirmationPending ||
+        !assistantOutboxIntentRequiresTerminalConfirmation(input)) {
+        return null;
+    }
+    const deliveryError = input.intent.lastError;
+    if (deliveryError &&
+        deliveryError.code !== 'ASSISTANT_DELIVERY_CONFIRMATION_PENDING') {
+        return {
+            delivery: input.intent.delivery,
+            deliveryError,
+            status: deliveryError.code === 'ASSISTANT_DELIVERY_AMBIGUOUS'
+                ? 'failed_ambiguous'
+                : 'failed',
+        };
+    }
+    return input.intent.delivery
+        ? {
+            delivery: input.intent.delivery,
+            deliveryError: null,
+            status: 'sent',
+        }
+        : null;
+}
+async function confirmAssistantOutboxTerminalIntent(input) {
+    const confirmTerminalIntent = input.dispatchHooks?.confirmTerminalIntent;
+    if (!confirmTerminalIntent) {
+        return input.intent;
+    }
+    try {
+        await confirmTerminalIntent({
+            intent: input.intent,
+            outcome: input.outcome,
+            vault: input.vault,
+        });
+    }
+    catch {
+        return rescheduleAssistantOutboxConfirmationRetry({
+            error: input.intent.lastError ??
+                createAssistantDeliveryConfirmationPendingError(),
+            intentPath: input.intentPath,
+            sending: input.intent,
+            vault: input.vault,
+        });
+    }
+    if (input.outcome.status === 'sent') {
+        return markAssistantOutboxIntentSent({
+            completedAt: input.intent.updatedAt,
+            delivery: input.outcome.delivery,
+            intent: input.intent,
+            intentPath: input.intentPath,
+            vault: input.vault,
+        });
+    }
+    return markAssistantOutboxIntentMirrorTerminal({
+        error: input.outcome.deliveryError,
+        failedAt: new Date(),
+        intent: input.intent,
+        intentPath: input.intentPath,
+        onlyCurrentStatuses: ['retryable', 'sending'],
+        status: input.outcome.status === 'failed_ambiguous'
+            ? 'abandoned'
+            : 'failed',
+        vault: input.vault,
+    });
+}
+async function finalizeAssistantOutboxTerminalFailure(input) {
+    const pendingIntent = await updateAssistantOutboxAfterDispatchFailure({
+        deliveryMayHaveSucceeded: input.deliveryMayHaveSucceeded,
+        deliveryTransportIdempotent: input.deliveryTransportIdempotent,
+        error: input.error,
+        failedAt: input.failedAt,
+        intentPath: input.intentPath,
+        sending: input.intent,
+        terminalConfirmationRequired: true,
+        vault: input.vault,
+    });
+    const outcome = readAssistantOutboxPendingTerminalConfirmation({
+        dispatchHooks: input.dispatchHooks,
+        intent: pendingIntent,
+        vault: input.vault,
+    });
+    return outcome
+        ? confirmAssistantOutboxTerminalIntent({
+            dispatchHooks: input.dispatchHooks,
+            intent: pendingIntent,
+            intentPath: input.intentPath,
+            outcome,
+            vault: input.vault,
+        })
+        : pendingIntent;
+}
+async function finalizeAssistantOutboxTerminalDelivery(input) {
+    const pendingIntent = await persistAssistantOutboxIntentDeliveryPendingConfirmation({
+        completedAt: input.completedAt,
+        delivery: input.delivery,
+        deliveryTransportIdempotent: input.intent.deliveryTransportIdempotent,
+        intent: input.intent,
+        intentPath: input.intentPath,
+        terminalConfirmationRequired: true,
+        vault: input.vault,
+    });
+    const outcome = readAssistantOutboxPendingTerminalConfirmation({
+        dispatchHooks: input.dispatchHooks,
+        intent: pendingIntent,
+        vault: input.vault,
+    });
+    return outcome
+        ? confirmAssistantOutboxTerminalIntent({
+            dispatchHooks: input.dispatchHooks,
+            intent: pendingIntent,
+            intentPath: input.intentPath,
+            outcome,
+            vault: input.vault,
+        })
+        : pendingIntent;
+}
 function assistantOutboxIntentMatchesPreparedDispatch(intent, preparedDispatch) {
     return intent.preparedDispatchToken === preparedDispatch.preparedDispatchToken &&
         intent.deliveryIdempotencyKey === preparedDispatch.deliveryIdempotencyKey &&
@@ -708,8 +1066,14 @@ export async function deliverAssistantOutboxMessage(input) {
         answeredMailboxItemIds: input.answeredMailboxItemIds ?? [],
         reviewedAssistantAskCompletionExpiresAt: input.reviewedAssistantAskCompletionExpiresAt ?? null,
         automationAuthority: input.automationAuthority ?? null,
+        ...(input.automationContextReferences?.length
+            ? { automationContextReferences: input.automationContextReferences }
+            : {}),
+        plannedOccurrenceAt: input.plannedOccurrenceAt ?? null,
+        scheduledOccurrenceAt: input.scheduledOccurrenceAt ?? null,
         bindingDelivery: input.bindingDelivery,
         channel: input.channel,
+        card: input.card ?? null,
         dedupeToken: input.dedupeToken,
         deliveryIdempotencyKey: input.deliveryIdempotencyKey,
         deliverySource: input.deliverySource ?? null,
@@ -719,6 +1083,11 @@ export async function deliverAssistantOutboxMessage(input) {
         identityId: input.identityId,
         media: input.media,
         message: input.message,
+        ...(input.privateCompletionContinuitySessionId === undefined
+            ? {}
+            : {
+                privateCompletionContinuitySessionId: input.privateCompletionContinuitySessionId,
+            }),
         ...(input.nativeReplyRequested === undefined
             ? {}
             : { nativeReplyRequested: input.nativeReplyRequested }),
@@ -816,9 +1185,11 @@ export async function deliverAssistantOutboxReaction(input) {
         kind: 'message-reaction',
         reaction: input.reaction,
     };
+    const requestedAnsweredMailboxItemIds = normalizeAssistantOutboxAnsweredMailboxItemIds(input.answeredMailboxItemIds ?? []);
     const targetMessageId = normalizeRequiredReactionTargetMessageId(input.targetMessageId);
     const intent = await createAssistantOutboxIntent({
         actorId: input.actorId,
+        answeredMailboxItemIds: input.answeredMailboxItemIds ?? [],
         bindingDelivery: input.bindingDelivery,
         channel: input.channel,
         dedupeToken: input.dedupeToken,
@@ -840,6 +1211,20 @@ export async function deliverAssistantOutboxReaction(input) {
         turnTrigger: input.turnTrigger ?? null,
         vault: input.vault,
     });
+    const coveredAnsweredMailboxItemIds = new Set(intent.answeredMailboxItemIds);
+    if (requestedAnsweredMailboxItemIds.some((mailboxItemId) => !coveredAnsweredMailboxItemIds.has(mailboxItemId))) {
+        const error = Object.assign(new Error('The existing outbound delivery does not cover every requested input; retry after the current dispatch settles.'), {
+            code: ASSISTANT_OUTBOX_ANSWERED_ITEMS_UNCOVERED_CODE,
+            retryable: true,
+        });
+        return {
+            kind: 'failed',
+            intent,
+            delivery: null,
+            deliveryError: normalizeAssistantDeliveryError(error),
+            session: null,
+        };
+    }
     if (intent.status === 'sent' && intent.delivery) {
         return {
             kind: 'sent',
@@ -901,6 +1286,7 @@ async function sendAssistantOutboxDispatchIntent(input) {
     if (operation?.kind === 'message-reaction') {
         return sendAssistantOutboxDispatchReaction({
             actorId: input.actorId,
+            answeredMailboxItemIds: input.answeredMailboxItemIds,
             bindingDelivery: input.bindingDelivery,
             channel: input.channel,
             deliveryIdempotencyKey: input.deliveryIdempotencyKey,
@@ -925,6 +1311,7 @@ export async function sendAssistantOutboxDispatchMessage(input) {
         delivered: await deliverAssistantMessageOverBinding({
             vault: input.vault,
             sessionId: input.sessionId,
+            card: input.card ?? null,
             media: input.media ?? [],
             message: input.message,
             ...(input.nativeReplyRequested === undefined
@@ -1183,7 +1570,6 @@ export async function resetAssistantOutboxPreparedDispatchById(input) {
         return null;
     }
     return resetAssistantOutboxPreparedDispatch({
-        deliveryIdempotencyKey: input.deliveryIdempotencyKey,
         deliveryTransportIdempotent: input.deliveryTransportIdempotent,
         intent,
         intentPath,
@@ -1234,6 +1620,65 @@ export async function markAssistantOutboxIntentSentById(input) {
         vault: input.vault,
     });
 }
+export function hasPendingAssistantOutboxMessageVolumeReceipt(intent) {
+    return (intent.messageVolumeReceiptRecordedAt === null &&
+        intent.delivery !== null &&
+        assistantOutboxDeliveryCountsTowardMessageVolume({
+            delivery: intent.delivery,
+            intent,
+        }));
+}
+export async function markAssistantOutboxMessageVolumeReceiptRecorded(input) {
+    return withAssistantRuntimeWriteLock(input.vault, async (paths) => {
+        await ensureAssistantState(paths);
+        const intentPath = resolveAssistantOutboxIntentPath(paths.outboxDirectory, input.intentId);
+        const current = await readAssistantOutboxIntentAtPath(intentPath, {
+            vault: input.vault,
+        });
+        if (!current) {
+            return null;
+        }
+        if (current.messageVolumeReceiptRecordedAt !== null) {
+            return current;
+        }
+        if (current.dedupeKey !== input.dedupeKey ||
+            current.delivery === null ||
+            current.delivery.channel.trim().toLowerCase() !== input.channel ||
+            !assistantOutboxDeliveryCountsTowardMessageVolume({
+                delivery: current.delivery,
+                intent: current,
+            })) {
+            return current;
+        }
+        const recorded = assistantOutboxIntentSchema.parse(sanitizeAssistantOutboxIntentForPersistence({
+            ...current,
+            messageVolumeReceiptRecordedAt: input.recordedAt,
+            nextAttemptAt: null,
+        }));
+        await writeJsonFileAtomic(intentPath, sanitizeAssistantOutboxIntentForPersistence(recorded));
+        return recorded;
+    });
+}
+export async function rescheduleAssistantOutboxMessageVolumeReceipt(input) {
+    return withAssistantRuntimeWriteLock(input.vault, async (paths) => {
+        await ensureAssistantState(paths);
+        const intentPath = resolveAssistantOutboxIntentPath(paths.outboxDirectory, input.intentId);
+        const current = await readAssistantOutboxIntentAtPath(intentPath, {
+            vault: input.vault,
+        });
+        if (!current ||
+            current.dedupeKey !== input.dedupeKey ||
+            !hasPendingAssistantOutboxMessageVolumeReceipt(current)) {
+            return current;
+        }
+        const rescheduled = assistantOutboxIntentSchema.parse(sanitizeAssistantOutboxIntentForPersistence({
+            ...current,
+            nextAttemptAt: input.nextAttemptAt,
+        }));
+        await writeJsonFileAtomic(intentPath, sanitizeAssistantOutboxIntentForPersistence(rescheduled));
+        return rescheduled;
+    });
+}
 function assertAssistantOutboxNativeReplyTarget(input) {
     if (input.nativeReplyRequested === undefined) {
         return;
@@ -1280,6 +1725,14 @@ function assertAssistantOutboxDedupeEffectMatches(input) {
         throw createAssistantOutboxDedupeEffectMismatchError();
     }
 }
+function assertAssistantOutboxCardCompatible(input) {
+    if (input.card !== null && input.media.length > 0) {
+        throw new VaultCliError('ASSISTANT_RESPONSE_CARD_MEDIA_CONFLICT', 'A response card cannot be combined with response media.');
+    }
+    if (input.card !== null && input.operation !== null) {
+        throw new VaultCliError('ASSISTANT_RESPONSE_CARD_OPERATION_CONFLICT', 'A response card requires a normal message intent.');
+    }
+}
 function createAssistantOutboxDedupeEffectMismatchError() {
     return new VaultCliError('ASSISTANT_OUTBOX_DEDUPE_EFFECT_MISMATCH', 'Assistant outbox dedupe identity is already bound to a different delivery effect.');
 }
@@ -1322,17 +1775,41 @@ function assertAssistantOutboxResponseMediaSupported(input) {
 }
 function buildAssistantOutboxDeliveredIntent(input) {
     const sessionBinding = input.session?.binding ?? null;
+    const messageVolumeReceiptRecordedAt = input.intent.messageVolumeReceiptRecordedAt !== undefined
+        ? input.intent.messageVolumeReceiptRecordedAt
+        : input.trackMessageVolumeReceipt &&
+            assistantOutboxDeliveryCountsTowardMessageVolume(input)
+            ? null
+            : undefined;
     return assistantOutboxIntentSchema.parse(sanitizeAssistantOutboxIntentForPersistence({
         ...input.intent,
         actorId: sessionBinding?.actorId ?? input.intent.actorId,
         bindingDelivery: sessionBinding?.delivery ?? input.intent.bindingDelivery,
         channel: sessionBinding?.channel ?? input.intent.channel,
+        delivery: input.delivery,
         deliveryTransportIdempotent: input.deliveryTransportIdempotent,
         identityId: sessionBinding?.identityId ?? input.intent.identityId,
+        ...(messageVolumeReceiptRecordedAt === undefined
+            ? {}
+            : { messageVolumeReceiptRecordedAt }),
         threadId: sessionBinding?.threadId ?? input.intent.threadId,
         threadIsDirect: sessionBinding?.threadIsDirect ?? input.intent.threadIsDirect,
     }));
 }
+function assistantOutboxDeliveryCountsTowardMessageVolume(input) {
+    if (input.delivery.kind === 'message-reaction') {
+        return false;
+    }
+    const channel = input.delivery.channel.trim().toLowerCase();
+    if (channel === 'telegram') {
+        return true;
+    }
+    if (channel !== 'email') {
+        return false;
+    }
+    const target = parseHostedEmailThreadTarget(input.intent.explicitTarget ?? input.delivery.target);
+    return !(target?.targetKind === 'group' && target.recipientMemberId === null);
+}
 function shouldReconcileAssistantOutboxIntent(intent) {
     if (intent.deliveryTransportIdempotent) {
         return false;
@@ -1353,6 +1830,11 @@ function resolvePersistedAssistantOutboxDelivery(intent) {
     }
     return intent.delivery;
 }
+function resolveRecoveredAssistantOutboxDeliveryCompletedAt(input) {
+    return resolvePersistedAssistantOutboxDelivery(input.intent)
+        ? input.intent.updatedAt
+        : input.delivery.sentAt;
+}
 function shouldFailClosedAssistantOutboxStaleSendingIntent(intent) {
     return (intent.status === 'sending' &&
         !inferAssistantOutboxDeliveryTransportIdempotent(intent));
@@ -1425,6 +1907,16 @@ function isReplaySafeHostedEmailGroupFanoutPlanner(target) {
     return hostedTarget?.targetKind === 'group'
         && hostedTarget.recipientMemberId === null;
 }
+function hasSharedHostedEmailGroupDeliveryIdentity(target) {
+    if (normalizeNullableString(target.channel)?.toLowerCase() !== 'email') {
+        return false;
+    }
+    const serializedTarget = target.explicitTarget
+        ?? (target.bindingDelivery?.kind === 'thread'
+            ? target.bindingDelivery.target
+            : null);
+    return parseHostedEmailThreadTarget(serializedTarget)?.targetKind === 'group';
+}
 function maybeUpgradeAssistantOutboxIntentDeliveryIdempotency(input) {
     const deliveryIdempotencyKey = input.intent.deliveryIdempotencyKey ?? input.deliveryIdempotencyKey;
     const deliveryTransportIdempotent = input.intent.operation?.kind === 'message-reaction'
@@ -1443,7 +1935,9 @@ function maybeUpgradeAssistantOutboxIntentDeliveryIdempotency(input) {
 function maybeUpgradeAssistantOutboxIntentAnsweredMailboxItemIds(input) {
     if (input.answeredMailboxItemIds.length === 0
         || (input.intent.status !== 'pending'
-            && input.intent.status !== 'retryable')) {
+            && input.intent.status !== 'retryable')
+        || input.intent.delivery !== null
+        || input.intent.deliveryConfirmationPending) {
         return input.intent;
     }
     const answeredMailboxItemIds = normalizeAssistantOutboxAnsweredMailboxItemIds([