@ouro.bot/cli 0.1.0-alpha.724 → 0.1.0-alpha.726

package/dist/senses/bluebubbles/index.js

@@ -79,8 +79,10 @@ const client_1 = require("./client");
 const inbound_log_1 = require("./inbound-log");
 const mutation_log_1 = require("./mutation-log");
 const processed_log_1 = require("./processed-log");
+const semantic_receipts_1 = require("./semantic-receipts");
 const runtime_state_1 = require("./runtime-state");
 const session_cleanup_1 = require("./session-cleanup");
+const reaction_policy_1 = require("./reaction-policy");
 const active_turns_1 = require("./active-turns");
 const trust_gate_1 = require("../trust-gate");
 const pipeline_1 = require("../pipeline");
@@ -358,8 +360,8 @@ function resolveFriendParams(event) {
     }
     return {
         provider: "imessage-handle",
-        externalId: event.sender.externalId || event.sender.rawId,
-        displayName: event.sender.displayName || "Unknown",
+        externalId: event.sender.externalId,
+        displayName: event.sender.displayName,
         channel: "bluebubbles",
     };
 }
@@ -463,11 +465,49 @@ function extractHistoricalLaneSummary(messages) {
     }
     return summaries;
 }
-function buildBlueBubblesOrientationSource(event, existingMessages, repliedToText) {
+function buildBlueBubblesOrientationSource(event, existingMessages, evidence, conversationKind, repliedToText) {
     const repairNotice = event.repairNotice?.trim();
+    const actor = evidence.actor;
+    const participants = evidence.participants
+        .filter((participant) => !(participant.provider === actor.provider
+        && participant.externalId === actor.externalId))
+        .map((participant) => ({
+        role: "group_participant_only",
+        provider: participant.provider,
+        externalId: participant.externalId,
+        displayName: participant.displayName,
+    }));
+    const targetGuid = evidence.targetGuid;
+    const targetAuthorship = evidence.targetAuthorship;
+    const presentation = {
+        authority: "presentation_only",
+        conversationKind,
+        event: {
+            provider: evidence.provider,
+            kind: evidence.kind,
+            sourceEventType: evidence.sourceEventType,
+            fromMe: evidence.fromMe,
+        },
+        actor: {
+            role: "observed_actor",
+            provider: actor.provider,
+            externalId: actor.externalId,
+            displayName: actor.displayName,
+        },
+        participants,
+        ...(targetGuid
+            ? {
+                target: {
+                    messageGuid: targetGuid,
+                    authorship: targetAuthorship ?? "unknown",
+                },
+            }
+            : {}),
+    };
     if (event.kind !== "message") {
         return {
             kind: "bluebubbles",
+            ...presentation,
             lane: "mutation",
             ...(repairNotice ? { repairNotice } : {}),
         };
@@ -477,6 +517,7 @@ function buildBlueBubblesOrientationSource(event, existingMessages, repliedToTex
     const hasThreadRoute = !!threadId || summaries.some((summary) => summary.key.startsWith("thread:"));
     return {
         kind: "bluebubbles",
+        ...presentation,
         lane: threadId ? "thread" : "top_level",
         defaultReplyTarget: threadId ? "current_lane" : "top_level",
         ...(threadId ? { threadId } : {}),
@@ -518,37 +559,6 @@ function sessionLikelyContainsMessage(event, existingMessages) {
         return extractMessageText(message.content).includes(fragment);
     });
 }
-function mutationEntryToEvent(entry) {
-    return {
-        kind: "mutation",
-        eventType: entry.eventType,
-        mutationType: entry.mutationType,
-        messageGuid: entry.messageGuid,
-        targetMessageGuid: entry.targetMessageGuid ?? undefined,
-        timestamp: Date.parse(entry.recordedAt) || Date.now(),
-        fromMe: entry.fromMe,
-        sender: {
-            provider: "imessage-handle",
-            externalId: entry.chatIdentifier ?? entry.chatGuid ?? "unknown",
-            rawId: entry.chatIdentifier ?? entry.chatGuid ?? "unknown",
-            displayName: entry.chatIdentifier ?? entry.chatGuid ?? "Unknown",
-        },
-        chat: {
-            chatGuid: entry.chatGuid ?? undefined,
-            chatIdentifier: entry.chatIdentifier ?? undefined,
-            displayName: undefined,
-            isGroup: Boolean(entry.chatGuid?.includes(";+;")),
-            sessionKey: entry.sessionKey,
-            sendTarget: entry.chatGuid
-                ? { kind: "chat_guid", value: entry.chatGuid }
-                : { kind: "chat_identifier", value: entry.chatIdentifier ?? "unknown" },
-            participantHandles: [],
-        },
-        shouldNotifyAgent: entry.shouldNotifyAgent,
-        textForAgent: entry.textForAgent,
-        requiresRepair: true,
-    };
-}
 function getBlueBubblesContinuityIngressTexts(event) {
     if (event.kind !== "message")
         return [];
@@ -603,7 +613,10 @@ function shouldUseBlueBubblesRecoveryBudget(source, options) {
         || source === "recovery-bootstrap";
 }
 function shouldCountBlueBubblesRecoveryResultAsSkipped(reason) {
-    return reason === "already_processed" || reason === "autonomy_budget_blocked";
+    return reason === "already_processed"
+        || reason === "autonomy_budget_blocked"
+        || reason === "mutation_state_only"
+        || reason === "from_me";
 }
 function recordBlueBubblesRecoveryFailureForBudget(agentName, event, source) {
     try {
@@ -731,7 +744,7 @@ function emitBlueBubblesMarkReadWarning(chat, error) {
         },
     });
 }
-function createBlueBubblesCallbacks(client, chat, replyTarget, isGroupChat, onVisibleActivity) {
+function createBlueBubblesCallbacks(client, chat, replyTarget, isGroupChat, onVisibleActivity, options = {}) {
     let textBuffer = "";
     let typingActive = false;
     let queue = Promise.resolve();
@@ -885,11 +898,13 @@ function createBlueBubblesCallbacks(client, chat, replyTarget, isGroupChat, onVi
         });
     }
     return {
+        settleOutputMode: "retractable_buffer",
         onModelStart() {
             if (outboundClosed)
                 return;
-            startSilenceWatchdog();
-            if (!isGroupChat)
+            if (options.enableSilenceWatchdog !== false)
+                startSilenceWatchdog();
+            if (options.enableActivitySignals !== false && !isGroupChat)
                 startTypingNow();
             (0, runtime_1.emitNervesEvent)({
                 component: "senses",
@@ -909,7 +924,7 @@ function createBlueBubblesCallbacks(client, chat, replyTarget, isGroupChat, onVi
         onTextChunk(text) {
             if (outboundClosed)
                 return;
-            if (isGroupChat && !typingActive)
+            if (options.enableActivitySignals !== false && isGroupChat && !typingActive)
                 startTypingNow();
             textBuffer += text;
         },
@@ -921,7 +936,7 @@ function createBlueBubblesCallbacks(client, chat, replyTarget, isGroupChat, onVi
             // console. Keep the human-facing thread quiet until the agent has real
             // text (or the generic silence watchdog fires), while preserving native
             // read/typing signals and nerves telemetry for debugging.
-            if (!typingActive && name !== "observe" && name !== "speak")
+            if (options.enableActivitySignals !== false && !typingActive && name !== "observe" && name !== "speak")
                 startTypingNow();
             (0, runtime_1.emitNervesEvent)({
                 component: "senses",
@@ -993,7 +1008,7 @@ function createBlueBubblesCallbacks(client, chat, replyTarget, isGroupChat, onVi
                 meta: { messageLength: trimmed.length },
             });
         },
-        async flush() {
+        async flush(flushOptions = {}) {
             if (outboundClosed) {
                 textBuffer = "";
                 await waitForBlueBubblesCallbackCleanup(queue, BLUEBUBBLES_CALLBACK_CLEANUP_TIMEOUT_MS, {
@@ -1038,6 +1053,7 @@ function createBlueBubblesCallbacks(client, chat, replyTarget, isGroupChat, onVi
                 chat,
                 text: trimmed,
                 replyToMessageGuid: replyTarget.getReplyToMessageGuid(),
+                ...(flushOptions.signal ? { signal: flushOptions.signal } : {}),
             });
             recordVisibleActivity();
         },
@@ -1078,6 +1094,11 @@ function writeJson(res, statusCode, payload) {
     res.setHeader("Content-Type", "application/json; charset=utf-8");
     res.end(JSON.stringify(payload));
 }
+function writeSemanticCaptureFailure(res) {
+    res.statusCode = 503;
+    res.setHeader("Content-Type", "application/json");
+    res.end('{"ok":false,"error":"semantic_capture_failed"}');
+}
 function isWebhookPasswordValid(url, expectedPassword) {
     const provided = url.searchParams.get("password");
     return !provided || provided === expectedPassword;
@@ -1183,7 +1204,10 @@ async function shouldFilterAgentSelfHandle(event, resolvedDeps) {
     }
     return true;
 }
-async function handleBlueBubblesNormalizedEvent(event, resolvedDeps, source, options = {}) {
+function hasObservedBlueBubblesDirection(event) {
+    return typeof event.fromMe === "boolean";
+}
+async function handleBlueBubblesNormalizedEvent(event, resolvedDeps, source, options) {
     const client = resolvedDeps.createClient();
     const agentName = resolvedDeps.getAgentName();
     (0, runtime_cwd_1.recoverRuntimeCwd)();
@@ -1222,24 +1246,6 @@ async function handleBlueBubblesNormalizedEvent(event, resolvedDeps, source, opt
         });
         return { handled: true, notifiedAgent: false, kind: event.kind, reason: "from_me" };
     }
-    if (event.kind === "mutation") {
-        try {
-            resolvedDeps.recordMutation(resolvedDeps.getAgentName(), event);
-        }
-        catch (error) {
-            (0, runtime_1.emitNervesEvent)({
-                level: "error",
-                component: "senses",
-                event: "senses.bluebubbles_mutation_log_error",
-                message: "failed recording bluebubbles mutation sidecar",
-                meta: {
-                    messageGuid: event.messageGuid,
-                    mutationType: event.mutationType,
-                    reason: error instanceof Error ? error.message : String(error),
-                },
-            });
-        }
-    }
     if (event.kind === "mutation" && !event.shouldNotifyAgent) {
         (0, runtime_1.emitNervesEvent)({
             component: "senses",
@@ -1252,52 +1258,7 @@ async function handleBlueBubblesNormalizedEvent(event, resolvedDeps, source, opt
         });
         return { handled: true, notifiedAgent: false, kind: event.kind, reason: "mutation_state_only" };
     }
-    let ownsInFlightMessage = false;
     let activeTurnId = null;
-    const inFlightKey = event.kind === "message"
-        ? {
-            sessionKey: options.preclaimedInFlight?.sessionKey ?? event.chat.sessionKey,
-            messageGuid: options.preclaimedInFlight?.messageGuid ?? event.messageGuid,
-        }
-        : null;
-    if (event.kind === "message") {
-        if ((0, processed_log_1.hasProcessedBlueBubblesMessage)(agentName, event.chat.sessionKey, event.messageGuid)
-            || (0, processed_log_1.hasProcessedBlueBubblesMessageGuid)(agentName, event.messageGuid)) {
-            if (inFlightKey && options.preclaimedInFlight) {
-                endBlueBubblesMessageInFlight(inFlightKey.sessionKey, inFlightKey.messageGuid);
-            }
-            (0, runtime_1.emitNervesEvent)({
-                component: "senses",
-                event: "senses.bluebubbles_recovery_skip",
-                message: "skipped bluebubbles message already marked as handled",
-                meta: {
-                    messageGuid: event.messageGuid,
-                    sessionKey: event.chat.sessionKey,
-                    source,
-                    dedupeReason: "processed",
-                },
-            });
-            return { handled: true, notifiedAgent: false, kind: event.kind, reason: "already_processed" };
-        }
-        if (options.preclaimedInFlight) {
-            ownsInFlightMessage = true;
-        }
-        else if (!beginBlueBubblesMessageInFlight(inFlightKey.sessionKey, inFlightKey.messageGuid)) {
-            (0, runtime_1.emitNervesEvent)({
-                component: "senses",
-                event: "senses.bluebubbles_recovery_skip",
-                message: "skipped bluebubbles message already in flight",
-                meta: {
-                    messageGuid: event.messageGuid,
-                    sessionKey: event.chat.sessionKey,
-                    source,
-                    dedupeReason: "in_flight",
-                },
-            });
-            return { handled: true, notifiedAgent: false, kind: event.kind, reason: "already_processed" };
-        }
-        ownsInFlightMessage = true;
-    }
     if (event.kind === "message" && shouldUseBlueBubblesRecoveryBudget(source, options)) {
         const decision = (0, autonomy_budget_1.reserveAutonomyBudget)((0, identity_1.getAgentRoot)(agentName), {
             agent: agentName,
@@ -1310,8 +1271,6 @@ async function handleBlueBubblesNormalizedEvent(event, resolvedDeps, source, opt
             storm: blueBubblesRecoveryStormInput(agentName, event, source),
         });
         if (!decision.allowed) {
-            endBlueBubblesMessageInFlight(inFlightKey.sessionKey, inFlightKey.messageGuid);
-            ownsInFlightMessage = false;
             return { handled: true, notifiedAgent: false, kind: event.kind, reason: "autonomy_budget_blocked" };
         }
     }
@@ -1352,7 +1311,8 @@ async function handleBlueBubblesNormalizedEvent(event, resolvedDeps, source, opt
             if (event.kind === "message") {
                 // Record EARLY for audit and crash recovery. This is capture truth, not
                 // a claim that the agent turn completed successfully.
-                const inboundSource = source !== "webhook" && sessionLikelyContainsMessage(event, existing?.messages ?? sessionMessages)
+                const inboundSource = (options.semanticRecovery || source !== "webhook")
+                    && sessionLikelyContainsMessage(event, existing?.messages ?? sessionMessages)
                     ? "recovery-bootstrap"
                     : source;
                 (0, inbound_log_1.recordBlueBubblesInbound)(agentName, event, inboundSource);
@@ -1393,16 +1353,6 @@ async function handleBlueBubblesNormalizedEvent(event, resolvedDeps, source, opt
                     meta: { threadGuid, hasText: !!repliedToText },
                 });
             }
-            // Anchor reaction mutations to the message they point at, including whose
-            // message it was. Unresolved targets keep the explicit "unidentified message"
-            // wording that normalizeBlueBubblesEvent already produced.
-            const isReaction = event.kind === "mutation" && event.mutationType === "reaction";
-            if (isReaction && event.reaction && event.targetMessageGuid) {
-                /* v8 ignore start -- best-effort network lookup; resolveReactionTarget and renderBlueBubblesReactionText are covered by unit tests @preserve */
-                const target = await resolveReactionTarget(client, event.targetMessageGuid);
-                event.textForAgent = (0, model_1.renderBlueBubblesReactionText)(event.reaction, target);
-                /* v8 ignore stop */
-            }
             // Build inbound user message as user-visible speech only; source/routing facts live in the orientation frame.
             const priorMessages = existing?.messages ?? sessionMessages;
             const userMessage = {
@@ -1414,8 +1364,7 @@ async function handleBlueBubblesNormalizedEvent(event, resolvedDeps, source, opt
                 messages: [...priorMessages, userMessage],
                 currentUserMessages: [userMessage],
                 structuredOutputs: existing?.structuredOutputs ?? [],
-                source: buildBlueBubblesOrientationSource(event, priorMessages, repliedToText),
-                ...(isReaction ? { speechKind: "reaction" } : {}),
+                source: buildBlueBubblesOrientationSource(event, priorMessages, options.orientationEvidence, options.orientationConversationKind, repliedToText),
             });
             const visibleActivityTurnId = activeTurnId;
             const callbacks = createBlueBubblesCallbacks(client, event.chat, replyTarget, event.chat.isGroup, visibleActivityTurnId
@@ -1463,10 +1412,6 @@ async function handleBlueBubblesNormalizedEvent(event, resolvedDeps, source, opt
                     timeoutReason = reason;
                     recoveryTimedOut = true;
                     callbacks.cancelOutbound("turn_timeout");
-                    if (ownsInFlightMessage && inFlightKey) {
-                        endBlueBubblesMessageInFlight(inFlightKey.sessionKey, inFlightKey.messageGuid);
-                        ownsInFlightMessage = false;
-                    }
                     controller.abort(reason);
                     timeoutReject?.(reason);
                     (0, runtime_1.emitNervesEvent)({
@@ -1509,7 +1454,7 @@ async function handleBlueBubblesNormalizedEvent(event, resolvedDeps, source, opt
                     pendingDir,
                     friendStore: store,
                     provider: "imessage-handle",
-                    externalId: event.sender.externalId || event.sender.rawId,
+                    externalId: event.sender.externalId,
                     isGroupChat: event.chat.isGroup,
                     groupHasFamilyMember,
                     hasExistingGroupWithFamily,
@@ -1560,7 +1505,15 @@ async function handleBlueBubblesNormalizedEvent(event, resolvedDeps, source, opt
                     },
                     accumulateFriendTokens: resolvedDeps.accumulateFriendTokens,
                     signal: controller.signal,
-                    runAgentOptions: { mcpManager, orientationFrame, ...(isReaction ? { isReactionSignal: true } : {}) },
+                    runAgentOptions: {
+                        mcpManager,
+                        orientationFrame,
+                        toolContext: {
+                            signin: async () => undefined,
+                            agentRoot: (0, identity_1.getAgentRoot)(),
+                            currentIngressEvidence: options.currentIngressEvidence,
+                        },
+                    },
                     callbacks: failoverAwareCallbacks,
                     failoverState: (() => {
                         if (!bbFailoverStates.has(event.chat.sessionKey)) {
@@ -1705,204 +1658,531 @@ async function handleBlueBubblesNormalizedEvent(event, resolvedDeps, source, opt
     finally {
         if (activeTurnId)
             (0, active_turns_1.finishBlueBubblesActiveTurn)(agentName, activeTurnId);
-        if (ownsInFlightMessage && inFlightKey) {
-            endBlueBubblesMessageInFlight(inFlightKey.sessionKey, inFlightKey.messageGuid);
-        }
     }
 }
-async function handleBlueBubblesEvent(payload, deps = {}) {
-    const resolvedDeps = { ...defaultDeps, ...deps };
-    const client = resolvedDeps.createClient();
-    let normalized;
+function recordBlueBubblesAuditSidecar(agentName, event, source, resolvedDeps) {
+    if (event.kind === "message") {
+        if (event.fromMe !== true)
+            (0, inbound_log_1.recordBlueBubblesInbound)(agentName, event, source);
+        return;
+    }
     try {
-        normalized = (0, model_1.normalizeBlueBubblesEvent)(payload);
+        resolvedDeps.recordMutation(agentName, event);
     }
     catch (error) {
-        if (error instanceof model_1.BlueBubblesIgnoredEventError) {
-            (0, runtime_1.emitNervesEvent)({
-                component: "senses",
-                event: "senses.bluebubbles_event_skipped",
-                message: "skipped ignorable bluebubbles event",
-                meta: {
-                    eventType: error.eventType,
-                },
-            });
-            return {
-                handled: true,
-                notifiedAgent: false,
-                reason: "ignored",
-            };
-        }
-        throw error;
+        (0, runtime_1.emitNervesEvent)({
+            level: "error",
+            component: "senses",
+            event: "senses.bluebubbles_mutation_log_error",
+            message: "failed recording bluebubbles mutation sidecar",
+            meta: {
+                messageGuid: event.messageGuid,
+                mutationType: event.mutationType,
+                reason: error instanceof Error ? error.message : String(error),
+            },
+        });
     }
-    // Pre-repair dedup: if we've already processed this messageGuid, skip the
-    // repair+hydrate path entirely. Applies to BOTH `kind: "message"` AND
-    // `kind: "mutation"` events — BlueBubbles often sends a `new-message`
-    // webhook for a fresh message AND one or more follow-up `updated-message`
-    // webhooks for delivery/read status. The mutation path (inside repairEvent)
-    // can promote an updated-message back to a message if it has recoverable
-    // content, which then re-runs the full VLM-describe pipeline on the same
-    // attachment.
-    //
-    // Without this early check, we paid DOUBLE latency and double tokens on
-    // every image-bearing message. Verified live on 2026-04-08T00:58Z: two
-    // sequential VLM describes for attachment guid 317E37EB-..., 13.7s +
-    // 14.0s each, for the exact same 291KB JPEG — triggered by a sequence of
-    // `new-message` followed ~3s later by `updated-message` for the same guid.
-    //
-    // We still route the skip through `handleBlueBubblesNormalizedEvent` so
-    // the downstream `already_processed` path fires its observability events
-    // and the caller sees a consistent return shape.
+}
+function reactionTargetAuthorship(target) {
+    return target.fromMe === true ? "agent" : "non_agent_unknown";
+}
+async function captureBlueBubblesSemanticEvent(normalized, resolvedDeps, source) {
     const agentName = resolvedDeps.getAgentName();
-    // normalizeBlueBubblesEvent rejects guidless payloads, so duplicate handling
-    // only needs to discriminate between known processed, in-flight, or new.
-    const duplicateReason = (0, processed_log_1.hasProcessedBlueBubblesMessage)(agentName, normalized.chat.sessionKey, normalized.messageGuid)
-        || (0, processed_log_1.hasProcessedBlueBubblesMessageGuid)(agentName, normalized.messageGuid)
-        ? "processed"
-        : isBlueBubblesMessageInFlight(normalized.chat.sessionKey, normalized.messageGuid)
-            ? "in_flight"
-            : null;
-    if (normalized.messageGuid
-        && duplicateReason) {
+    if (!hasObservedBlueBubblesDirection(normalized)) {
         (0, runtime_1.emitNervesEvent)({
             level: "warn",
             component: "senses",
-            event: "senses.bluebubbles_repair_skipped_duplicate",
-            message: "skipped repair+hydrate for already-processed bluebubbles messageGuid",
+            event: "senses.bluebubbles_direction_unobserved",
+            message: "kept bluebubbles event audit-only because message direction was unobserved",
             meta: {
                 messageGuid: normalized.messageGuid,
-                sessionKey: normalized.chat.sessionKey,
-                eventType: normalized.eventType,
-                normalizedKind: normalized.kind,
-                dedupeReason: duplicateReason,
+                kind: normalized.kind,
+                source,
             },
         });
-        return handleBlueBubblesNormalizedEvent(normalized, resolvedDeps, "webhook");
-    }
-    let preclaimedInFlight = false;
-    let handedPreclaimToTurn = false;
-    if (normalized.kind === "message") {
-        beginBlueBubblesMessageInFlight(normalized.chat.sessionKey, normalized.messageGuid);
-        preclaimedInFlight = true;
-    }
-    try {
-        const event = await client.repairEvent(normalized);
-        handedPreclaimToTurn = preclaimedInFlight && event.kind === "message";
-        return handleBlueBubblesNormalizedEvent(event, resolvedDeps, "webhook", handedPreclaimToTurn
-            ? { preclaimedInFlight: { sessionKey: normalized.chat.sessionKey, messageGuid: normalized.messageGuid } }
-            : {});
-    }
-    finally {
-        if (preclaimedInFlight && !handedPreclaimToTurn) {
-            endBlueBubblesMessageInFlight(normalized.chat.sessionKey, normalized.messageGuid);
+        recordBlueBubblesAuditSidecar(agentName, normalized, source, resolvedDeps);
+        return { status: "audit_only", normalized };
+    }
+    const observed = normalized;
+    const cutover = (0, semantic_receipts_1.initializeBlueBubblesSemanticCutover)(agentName);
+    let resolvedReactionTarget;
+    let targetAuthorship = null;
+    if (observed.kind === "mutation"
+        && observed.mutationType === "reaction"
+        && observed.targetMessageGuid) {
+        resolvedReactionTarget = await resolveReactionTarget(resolvedDeps.createClient(), observed.targetMessageGuid);
+        targetAuthorship = reactionTargetAuthorship(resolvedReactionTarget);
+    }
+    let coordinateGeneration;
+    if (observed.kind === "mutation"
+        && observed.mutationType === "reaction"
+        && observed.reaction
+        && !observed.revision
+        && !Number.isFinite(observed.effectiveTimestamp)
+        && observed.sender.observed === true) {
+        const identity = (0, semantic_receipts_1.buildBlueBubblesSemanticIdentity)({
+            providerNamespace: cutover.providerNamespace,
+            kind: "reaction",
+            eventGuid: observed.messageGuid,
+            targetGuid: observed.targetMessageGuid,
+            actorExternalId: observed.sender.externalId,
+            canonicalValue: observed.reaction.canonicalValue,
+            canonicalAction: observed.reaction.action,
+            coordinateGeneration: 0,
+        });
+        if (identity?.coordinateKey && identity.coordinateHash) {
+            const coordinate = await (0, semantic_receipts_1.allocateBlueBubblesReactionCoordinate)(agentName, {
+                coordinateKey: identity.coordinateKey,
+                coordinateHash: identity.coordinateHash,
+                canonicalAction: observed.reaction.action,
+            });
+            coordinateGeneration = coordinate.generation;
         }
     }
-}
-function listPendingCapturedInboundMessages(agentName) {
-    const seenMessageGuids = new Set();
-    return (0, inbound_log_1.listRecordedBlueBubblesInbound)(agentName)
-        .filter((entry) => {
-        if (seenMessageGuids.has(entry.messageGuid))
-            return false;
-        seenMessageGuids.add(entry.messageGuid);
-        return true;
-    })
-        .filter((entry) => {
-        if ((0, processed_log_1.hasProcessedBlueBubblesMessageGuid)(agentName, entry.messageGuid))
-            return false;
-        return !markCapturedInboundSuperseded(agentName, entry);
+    const capture = (0, semantic_receipts_1.buildBlueBubblesSemanticCapture)({
+        cutover,
+        capturedAt: new Date().toISOString(),
+        event: observed,
+        targetAuthorship,
+        coordinateGeneration,
     });
-}
-function listPendingRecoveryEntries(agentName) {
-    const pendingByGuid = new Map();
-    const add = (messageGuid, recordedAt) => {
-        if ((0, processed_log_1.hasProcessedBlueBubblesMessageGuid)(agentName, messageGuid))
-            return;
-        const previous = pendingByGuid.get(messageGuid);
-        if (!previous) {
-            pendingByGuid.set(messageGuid, recordedAt);
-            return;
-        }
-        const previousMs = Date.parse(previous);
-        const nextMs = Date.parse(recordedAt);
-        if (Number.isFinite(nextMs) && (!Number.isFinite(previousMs) || nextMs < previousMs)) {
-            pendingByGuid.set(messageGuid, recordedAt);
-        }
-    };
-    for (const entry of listPendingCapturedInboundMessages(agentName)) {
-        add(entry.messageGuid, entry.recordedAt);
+    if (!capture) {
+        (0, semantic_receipts_1.classifyBlueBubblesRecoveryRecord)(observed, cutover);
+        recordBlueBubblesAuditSidecar(agentName, observed, source, resolvedDeps);
+        return { status: "audit_only", normalized: observed };
     }
-    for (const entry of (0, mutation_log_1.listBlueBubblesRecoveryCandidates)(agentName)) {
-        add(entry.messageGuid, entry.recordedAt);
+    const writeResult = (0, semantic_receipts_1.writeBlueBubblesSemanticCapture)(agentName, capture);
+    if (writeResult === "semantic_identity_collision") {
+        throw new Error("semantic_capture_failed");
     }
-    return [...pendingByGuid].map(([messageGuid, recordedAt]) => ({ messageGuid, recordedAt }));
+    recordBlueBubblesAuditSidecar(agentName, observed, source, resolvedDeps);
+    return {
+        status: "captured",
+        capture,
+        normalized: observed,
+        writeResult,
+        ...(resolvedReactionTarget ? { resolvedReactionTarget } : {}),
+    };
 }
-function parseTimestampMs(value) {
-    if (!value)
+function semanticCaptureChat(capture) {
+    const event = capture.event;
+    const sessionKey = event.sessionKey?.trim();
+    const chatGuid = event.chatGuid?.trim() || undefined;
+    const chatIdentifier = event.chatIdentifier?.trim() || undefined;
+    if (!sessionKey)
         return null;
-    const parsed = Date.parse(value);
-    return Number.isFinite(parsed) ? parsed : null;
+    const fallbackSendTarget = sessionKey.startsWith("chat:")
+        ? { kind: "chat_guid", value: sessionKey.slice("chat:".length).trim() }
+        : sessionKey.startsWith("chat_identifier:")
+            ? { kind: "chat_identifier", value: sessionKey.slice("chat_identifier:".length).trim() }
+            : null;
+    const sendTarget = chatGuid
+        ? { kind: "chat_guid", value: chatGuid }
+        : chatIdentifier
+            ? { kind: "chat_identifier", value: chatIdentifier }
+            : fallbackSendTarget;
+    if (!sendTarget?.value)
+        return null;
+    return {
+        chatGuid,
+        chatIdentifier,
+        isGroup: Boolean(chatGuid?.includes(";+;") || event.participants.length > 1),
+        sessionKey,
+        sendTarget,
+        participantHandles: event.participants.map((participant) => participant.externalId),
+    };
+}
+function semanticCaptureRequiresRoutingRepair(capture) {
+    return !capture.event.chatGuid?.trim() && !capture.event.chatIdentifier?.trim();
+}
+function hasResolvedBlueBubblesRouting(event) {
+    return Boolean(event.chat.chatGuid?.trim() || event.chat.chatIdentifier?.trim());
+}
+function isAuditOnlySemanticCapture(capture) {
+    return capture.event.kind === "read" || capture.event.kind === "delivery";
+}
+function semanticCaptureToNormalizedEvent(capture) {
+    const event = capture.event;
+    const messageGuid = event.eventGuid?.trim();
+    const chat = semanticCaptureChat(capture);
+    if (!messageGuid || !chat)
+        return null;
+    const sender = {
+        provider: "imessage-handle",
+        externalId: event.actor.externalId,
+        rawId: event.actor.externalId,
+        displayName: event.actor.displayName ?? event.actor.externalId,
+        observed: true,
+    };
+    const timestamp = Date.parse(event.effectiveAt ?? capture.capturedAt);
+    if (event.kind === "message") {
+        const text = event.text ?? "";
+        return {
+            kind: "message",
+            eventType: event.sourceEventType,
+            messageGuid,
+            timestamp,
+            fromMe: event.fromMe,
+            sender,
+            chat,
+            text,
+            textForAgent: text,
+            attachments: [],
+            hasPayloadData: false,
+            requiresRepair: true,
+        };
+    }
+    const shouldNotifyAgent = event.kind === "reaction" || event.kind === "edit" || event.kind === "unsend";
+    const targetMessageGuid = event.targetGuid ?? undefined;
+    const reaction = event.kind === "reaction" && event.canonicalAction && event.canonicalValue
+        ? {
+            ...(0, model_1.describeBlueBubblesReaction)(event.rawTransportValue ?? event.canonicalValue, event.rawTransportValue ?? event.canonicalValue),
+            canonicalValue: event.canonicalValue,
+            action: event.canonicalAction,
+        }
+        : undefined;
+    const textForAgent = reaction
+        ? (0, model_1.renderBlueBubblesReactionText)(reaction, { guid: targetMessageGuid })
+        : event.kind === "edit"
+            ? event.text ? `edited message: ${event.text}` : "edited a message"
+            : event.kind === "unsend"
+                ? "unsent a message"
+                : event.kind === "read"
+                    ? "message marked as read"
+                    : "message marked as delivered";
+    return {
+        kind: "mutation",
+        eventType: event.sourceEventType,
+        mutationType: event.kind,
+        messageGuid,
+        targetMessageGuid,
+        timestamp,
+        fromMe: event.fromMe,
+        sender,
+        chat,
+        shouldNotifyAgent,
+        textForAgent,
+        requiresRepair: true,
+        ...(reaction ? { reaction } : {}),
+        ...(event.kind === "edit" && event.text !== null ? { editedText: event.text } : {}),
+        ...(event.revision ? { revision: event.revision } : {}),
+        ...(event.effectiveAt ? { effectiveTimestamp: Date.parse(event.effectiveAt) } : {}),
+        ...(event.kind === "unsend" && event.effectiveAt
+            ? { retractionTimestamp: Date.parse(event.effectiveAt) }
+            : {}),
+    };
 }
-function eventRecordedAtMs(event) {
-    return parseTimestampMs(event.time?.recordedAt ?? undefined);
+function semanticHandledOutcome(event, result) {
+    if (result.reason === "from_me")
+        return "ignored_self";
+    if (event.kind === "message") {
+        return result.notifiedAgent ? "message_completed" : "message_observed";
+    }
+    switch (event.mutationType) {
+        case "edit": return "edit_capture_only";
+        case "unsend": return "unsend_capture_only";
+        case "read": return "read_audit_only";
+        case "delivery": return "delivery_audit_only";
+        case "reaction":
+            if (result.reason === "restricted_feedback_settled")
+                return "restricted_feedback_settled";
+            if (result.reason === "restricted_feedback_observed")
+                return "restricted_feedback_observed";
+            return "restricted_feedback_failed";
+    }
+}
+function materializeRestrictedBlueBubblesReactionEvent(captured, repaired) {
+    // Classification reached `restricted_feedback` from the validated v1
+    // capture's reaction tuple. Direct capture and recovery both construct the
+    // paired normalized event from that same tuple, so it is the authoritative
+    // reaction object; repair contributes routing only and may legitimately
+    // promote its own transport-shaped result to `message`.
+    const event = captured.normalized;
+    return {
+        ...event,
+        mutationType: "reaction",
+        reaction: event.reaction,
+        targetMessageGuid: event.targetMessageGuid,
+        chat: repaired.chat,
+        requiresRepair: repaired.requiresRepair,
+        repairNotice: repaired.repairNotice,
+    };
 }
-function blueBubblesSessionPathsForKey(agentName, sessionKey) {
-    const sessionsRoot = path.join((0, identity_1.getAgentRoot)(agentName), "state", "sessions");
-    const fileName = `${(0, config_1.sanitizeKey)(sessionKey)}.json`;
-    let friendDirs;
+async function classifyCapturedBlueBubblesReaction(captured, resolvedDeps) {
+    const event = captured.capture.event;
+    if (event.kind !== "reaction" || !event.canonicalAction || !event.canonicalValue)
+        return null;
+    const input = {
+        fromMe: event.fromMe,
+        action: event.canonicalAction,
+        canonicalValue: event.canonicalValue,
+        targetAuthorship: event.targetAuthorship,
+    };
+    const initial = (0, reaction_policy_1.classifyBlueBubblesReaction)(input);
+    if (initial.route !== "trust_required") {
+        return { decision: initial, trustedFriend: null };
+    }
+    let trustedActor = false;
+    let trustedFriend = null;
     try {
-        friendDirs = fs.readdirSync(sessionsRoot, { withFileTypes: true });
+        const friend = await resolvedDeps.createFriendStore().findByExternalId("imessage-handle", event.actor.externalId);
+        trustedActor = friends_1.TRUSTED_LEVELS.has(friend?.trustLevel ?? "stranger");
+        if (trustedActor && friend)
+            trustedFriend = friend;
     }
-    catch {
-        return [];
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.bluebubbles_reaction_trust_lookup_error",
+            message: "failed direct actor trust lookup for bluebubbles reaction",
+            meta: {
+                keyHash: captured.capture.keyHash,
+                provider: event.actor.provider,
+                reason: error instanceof Error ? error.message : String(error),
+            },
+        });
     }
-    return friendDirs
-        .filter((entry) => entry.isDirectory())
-        .map((entry) => path.join(sessionsRoot, entry.name, "bluebubbles", fileName))
-        .filter((filePath) => {
-        try {
-            return fs.statSync(filePath).isFile();
+    return {
+        decision: (0, reaction_policy_1.classifyBlueBubblesReaction)({ ...input, trustedActor }),
+        trustedFriend,
+    };
+}
+async function handleRestrictedBlueBubblesReactionFeedback(input) {
+    const { event, trustedFriend, client, resolvedDeps, options } = input;
+    const target = input.resolvedReactionTarget
+        ?? await resolveReactionTarget(client, event.targetMessageGuid);
+    event.textForAgent = (0, model_1.renderBlueBubblesReactionText)(event.reaction, target);
+    const channel = (0, friends_1.getChannelCapabilities)("bluebubbles");
+    const context = { friend: trustedFriend, channel, isGroupChat: event.chat.isGroup };
+    const userMessage = {
+        role: "user",
+        content: buildInboundContent(event),
+    };
+    const orientationFrame = (0, orientation_frame_1.buildOrientationFrame)({
+        channel: "bluebubbles",
+        messages: [userMessage],
+        currentUserMessages: [userMessage],
+        source: buildBlueBubblesOrientationSource(event, [], options.orientationEvidence, options.orientationConversationKind),
+        speechKind: "reaction",
+    });
+    const callbacks = createBlueBubblesCallbacks(client, event.chat, createReplyTargetController(event), event.chat.isGroup, undefined, { enableSilenceWatchdog: false, enableActivitySignals: false });
+    const controller = new AbortController();
+    const timeoutMs = options.timeoutMs ?? BLUEBUBBLES_LIVE_TURN_TIMEOUT_MS;
+    let timeoutTimer;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeoutTimer = setTimeout(() => {
+            const error = new BlueBubblesRecoveryTurnTimeoutError(timeoutMs);
+            callbacks.cancelOutbound("turn_timeout");
+            controller.abort(error);
+            reject(error);
+        }, timeoutMs);
+        if (typeof timeoutTimer.unref === "function") {
+            timeoutTimer.unref();
         }
-        catch {
-            return false;
+    });
+    try {
+        const restrictedTurnAndDelivery = async () => {
+            const result = await resolvedDeps.runAgent([userMessage], callbacks, "bluebubbles", controller.signal, {
+                isReactionSignal: true,
+                restrictedReactionFeedback: true,
+                skipKeptNotes: true,
+                orientationFrame,
+                toolContext: {
+                    signin: async () => undefined,
+                    context,
+                    currentIngressEvidence: options.currentIngressEvidence,
+                },
+            });
+            if (result.outcome === "settled" || result.outcome === "blocked") {
+                await callbacks.flush({ signal: controller.signal });
+            }
+            return result;
+        };
+        const result = await Promise.race([
+            restrictedTurnAndDelivery(),
+            timeoutPromise,
+        ]);
+        if (result.outcome === "settled" || result.outcome === "blocked") {
+            return {
+                handled: true,
+                notifiedAgent: true,
+                kind: event.kind,
+                reason: "restricted_feedback_settled",
+            };
+        }
+        if (result.outcome === "observed") {
+            return {
+                handled: true,
+                notifiedAgent: false,
+                kind: event.kind,
+                reason: "restricted_feedback_observed",
+            };
         }
+        return {
+            handled: true,
+            notifiedAgent: false,
+            kind: event.kind,
+            reason: "restricted_feedback_failed",
+        };
+    }
+    catch (error) {
+        callbacks.onError(error instanceof Error ? error : new Error(String(error)), "terminal");
+        return {
+            handled: true,
+            notifiedAgent: false,
+            kind: event.kind,
+            reason: "restricted_feedback_failed",
+        };
+    }
+    finally {
+        clearTimeout(timeoutTimer);
+        await callbacks.finish({ timeoutMs: BLUEBUBBLES_CALLBACK_CLEANUP_TIMEOUT_MS });
+    }
+}
+function writeCapturedBlueBubblesHandled(agentName, capture, outcome) {
+    const handledResult = (0, semantic_receipts_1.writeBlueBubblesSemanticHandled)(agentName, {
+        schemaVersion: 1,
+        canonicalKey: capture.canonicalKey,
+        keyHash: capture.keyHash,
+        handledAt: new Date().toISOString(),
+        outcome,
+        detailCode: null,
     });
+    if (handledResult === "semantic_handled_collision") {
+        throw new Error("semantic_handled_collision");
+    }
 }
-function hasNewerBlueBubblesSessionActivity(agentName, sessionKey, recordedAt) {
-    const recordedAtMs = parseTimestampMs(recordedAt);
-    if (recordedAtMs === null)
-        return false;
-    for (const sessionFilePath of blueBubblesSessionPathsForKey(agentName, sessionKey)) {
-        const session = (0, context_1.loadSession)(sessionFilePath);
-        for (const event of session?.events ?? []) {
-            if (event.role === "system")
-                continue;
-            const nextRecordedAtMs = eventRecordedAtMs(event);
-            if (nextRecordedAtMs !== null && nextRecordedAtMs > recordedAtMs) {
-                return true;
+async function handleCapturedBlueBubblesSemanticEvent(captured, resolvedDeps, source, options = {}) {
+    const agentName = resolvedDeps.getAgentName();
+    const identity = {
+        canonicalKey: captured.capture.canonicalKey,
+        keyHash: captured.capture.keyHash,
+    };
+    const claim = await (0, semantic_receipts_1.acquireBlueBubblesSemanticClaim)(agentName, identity);
+    if (claim.status === "already_handled") {
+        return {
+            handled: true,
+            notifiedAgent: false,
+            kind: captured.normalized.kind,
+            reason: "already_processed",
+        };
+    }
+    if (claim.status === "timeout") {
+        return {
+            handled: false,
+            notifiedAgent: false,
+            kind: captured.normalized.kind,
+            reason: "semantic_claim_timeout",
+        };
+    }
+    try {
+        const capturedOptions = {
+            ...options,
+            currentIngressEvidence: Object.freeze({
+                schemaVersion: 1,
+                provider: "bluebubbles",
+                captureKeyHash: captured.capture.keyHash,
+            }),
+            orientationEvidence: captured.capture.event,
+            orientationConversationKind: captured.normalized.chat.isGroup ? "group" : "one_to_one",
+        };
+        const reactionClassification = await classifyCapturedBlueBubblesReaction(captured, resolvedDeps);
+        const reactionDecision = reactionClassification?.decision ?? null;
+        if (reactionDecision?.route === "capture_only") {
+            const result = {
+                handled: true,
+                notifiedAgent: false,
+                kind: captured.normalized.kind,
+                reason: reactionDecision.outcome === "ignored_self" ? "from_me" : "mutation_state_only",
+            };
+            writeCapturedBlueBubblesHandled(agentName, captured.capture, reactionDecision.outcome);
+            return result;
+        }
+        let handledEvent = captured.normalized;
+        let result;
+        if (isAuditOnlySemanticCapture(captured.capture)) {
+            result = {
+                handled: true,
+                notifiedAgent: false,
+                kind: captured.normalized.kind,
+                reason: "mutation_state_only",
+            };
+        }
+        else {
+            const client = resolvedDeps.createClient();
+            const repaired = await client.repairEvent(captured.normalized);
+            if (semanticCaptureRequiresRoutingRepair(captured.capture)
+                && !hasResolvedBlueBubblesRouting(repaired)) {
+                throw new Error("semantic_capture_routing_invalid");
+            }
+            const identityGroundedRepaired = {
+                ...repaired,
+                fromMe: captured.normalized.fromMe,
+                sender: captured.normalized.sender,
+            };
+            handledEvent = identityGroundedRepaired;
+            if (reactionDecision?.route === "restricted_feedback") {
+                const restrictedEvent = materializeRestrictedBlueBubblesReactionEvent(captured, repaired);
+                handledEvent = restrictedEvent;
+                result = await handleRestrictedBlueBubblesReactionFeedback({
+                    event: restrictedEvent,
+                    trustedFriend: reactionClassification.trustedFriend,
+                    client,
+                    resolvedDeps,
+                    options: capturedOptions,
+                    resolvedReactionTarget: captured.resolvedReactionTarget ?? options.resolvedReactionTarget,
+                });
+            }
+            else {
+                result = await handleBlueBubblesNormalizedEvent(identityGroundedRepaired, resolvedDeps, source, {
+                    ...capturedOptions,
+                    resolvedReactionTarget: captured.resolvedReactionTarget ?? options.resolvedReactionTarget,
+                });
             }
         }
+        writeCapturedBlueBubblesHandled(agentName, captured.capture, semanticHandledOutcome(handledEvent, result));
+        return result;
+    }
+    finally {
+        (0, semantic_receipts_1.releaseBlueBubblesSemanticClaim)(agentName, claim);
     }
-    return false;
 }
-function markCapturedInboundSuperseded(agentName, entry) {
-    if (!entry.messageGuid.trim())
-        return false;
-    if (!hasNewerBlueBubblesSessionActivity(agentName, entry.sessionKey, entry.recordedAt))
-        return false;
-    (0, processed_log_1.recordProcessedBlueBubblesMessage)(agentName, inboundEntryToRecoveryEvent(entry), entry.source, "recovery-superseded");
-    (0, runtime_1.emitNervesEvent)({
-        component: "senses",
-        event: "senses.bluebubbles_recovery_skip",
-        message: "skipped stale captured bluebubbles recovery because the session already advanced",
-        meta: {
-            messageGuid: entry.messageGuid,
-            sessionKey: entry.sessionKey,
-            source: entry.source,
-            dedupeReason: "session_superseded",
-        },
-    });
-    return true;
+async function handleBlueBubblesEvent(payload, deps = {}) {
+    const resolvedDeps = { ...defaultDeps, ...deps };
+    let normalized;
+    try {
+        normalized = (0, model_1.normalizeBlueBubblesEvent)(payload);
+    }
+    catch (error) {
+        if (error instanceof model_1.BlueBubblesIgnoredEventError) {
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "senses.bluebubbles_event_skipped",
+                message: "skipped ignorable bluebubbles event",
+                meta: {
+                    eventType: error.eventType,
+                },
+            });
+            return {
+                handled: true,
+                notifiedAgent: false,
+                reason: "ignored",
+            };
+        }
+        throw error;
+    }
+    const captured = await captureBlueBubblesSemanticEvent(normalized, resolvedDeps, "webhook");
+    if (captured.status === "audit_only") {
+        return { handled: true, notifiedAgent: false, kind: normalized.kind, reason: "ignored" };
+    }
+    return handleCapturedBlueBubblesSemanticEvent(captured, resolvedDeps, "webhook");
+}
+function parseTimestampMs(value) {
+    if (!value)
+        return null;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
 }
 function resolveBlueBubblesCatchUpSince(previousState, nowMs = Date.now()) {
     if (previousState.upstreamStatus === "error") {
@@ -1927,9 +2207,9 @@ function formatBlueBubblesRuntimeDetail(queued, failed, active) {
     return "upstream reachable";
 }
 function blueBubblesPendingRecoverySnapshot(agentName, nowMs = Date.now()) {
-    const pendingEntries = listPendingRecoveryEntries(agentName);
+    const pendingEntries = (0, semantic_receipts_1.listPendingBlueBubblesSemanticCaptures)(agentName);
     const pendingRecordedAt = pendingEntries
-        .map((entry) => entry.recordedAt)
+        .map((entry) => entry.capturedAt)
         .map((value) => ({ value, ms: Date.parse(value) }))
         .filter((entry) => Number.isFinite(entry.ms))
         .sort((left, right) => left.ms - right.ms);
@@ -2048,7 +2328,8 @@ async function catchUpMissedBlueBubblesMessages(deps = {}, previousState, option
     const client = resolvedDeps.createClient();
     const result = { inspected: 0, recovered: 0, skipped: 0, failed: 0 };
     const state = previousState ?? (0, runtime_state_1.readBlueBubblesRuntimeState)(agentName);
-    const catchUpSince = resolveBlueBubblesCatchUpSince(state);
+    const cutover = (0, semantic_receipts_1.initializeBlueBubblesSemanticCutover)(agentName);
+    const catchUpSince = Math.max(resolveBlueBubblesCatchUpSince(state), Date.parse(cutover.effectiveAt));
     const processTurns = options.processTurns !== false;
     /* v8 ignore next -- older injected test doubles may omit the catch-up query method */
     if (!client.listRecentMessages)
@@ -2121,37 +2402,38 @@ async function catchUpMissedBlueBubblesMessages(deps = {}, previousState, option
     for (const event of candidates) {
         result.inspected++;
         if (event.fromMe
-            || event.timestamp < catchUpSince
-            || (0, processed_log_1.hasProcessedBlueBubblesMessageGuid)(agentName, event.messageGuid)
-            || isBlueBubblesMessageInFlight(event.chat.sessionKey, event.messageGuid)) {
+            || event.timestamp < catchUpSince) {
             result.skipped++;
             continue;
         }
-        if (!processTurns) {
-            if ((0, inbound_log_1.hasRecordedBlueBubblesInbound)(agentName, event.chat.sessionKey, event.messageGuid)) {
+        try {
+            const captured = await captureBlueBubblesSemanticEvent(event, resolvedDeps, "upstream-catchup");
+            if (captured.status === "audit_only") {
                 result.skipped++;
                 continue;
             }
-            (0, inbound_log_1.recordBlueBubblesInbound)(agentName, event, "upstream-catchup");
-            result.queued = (result.queued ?? 0) + 1;
-            continue;
-        }
-        try {
-            const repaired = await client.repairEvent(event);
-            if (repaired.kind !== "message") {
-                result.skipped++;
+            if (!processTurns) {
+                if (captured.writeResult === "semantic_capture_duplicate") {
+                    result.skipped++;
+                }
+                else {
+                    result.queued = (result.queued ?? 0) + 1;
+                }
                 continue;
             }
-            const handled = await handleBlueBubblesNormalizedEvent(repaired, resolvedDeps, "upstream-catchup", {
+            const handled = await handleCapturedBlueBubblesSemanticEvent(captured, resolvedDeps, "upstream-catchup", {
                 timeoutMs: BLUEBUBBLES_RECOVERY_TURN_TIMEOUT_MS,
                 autonomyBudgetTrigger: "recovery",
             });
-            if (shouldCountBlueBubblesRecoveryResultAsSkipped(handled.reason)) {
+            if (handled.reason === "semantic_claim_timeout") {
+                continue;
+            }
+            if (shouldCountBlueBubblesRecoveryResultAsSkipped(handled.reason) || !handled.notifiedAgent) {
                 result.skipped++;
             }
             else {
                 result.recovered++;
-                result.lastRecoveredMessageGuid = repaired.messageGuid;
+                result.lastRecoveredMessageGuid = event.messageGuid;
             }
         }
         catch (error) {
@@ -2179,72 +2461,43 @@ async function catchUpMissedBlueBubblesMessages(deps = {}, previousState, option
     }
     return result;
 }
-function inboundEntryToRecoveryEvent(entry) {
-    const chatIdentifier = entry.chatIdentifier ?? extractChatIdentifierFromSessionKey(entry.sessionKey) ?? "unknown";
-    const normalizedSessionKey = normalizeBlueBubblesSessionKey(entry.sessionKey);
-    const chatGuid = entry.chatGuid ?? (normalizedSessionKey.startsWith("chat:") ? normalizedSessionKey.slice("chat:".length) : undefined);
-    const isGroup = normalizedSessionKey.includes("+;");
-    return {
-        kind: "message",
-        eventType: "new-message",
-        messageGuid: entry.messageGuid,
-        timestamp: parseTimestampMs(entry.recordedAt) ?? Date.now(),
-        fromMe: false,
-        sender: {
-            provider: "imessage-handle",
-            externalId: chatIdentifier,
-            rawId: chatIdentifier,
-            displayName: chatIdentifier,
-        },
-        chat: {
-            chatGuid,
-            chatIdentifier,
-            isGroup,
-            sessionKey: normalizedSessionKey,
-            sendTarget: chatGuid
-                ? { kind: "chat_guid", value: chatGuid }
-                : { kind: "chat_identifier", value: chatIdentifier },
-            participantHandles: [],
-        },
-        text: entry.textForAgent,
-        textForAgent: entry.textForAgent,
-        attachments: [],
-        hasPayloadData: false,
-        requiresRepair: true,
-    };
-}
 async function recoverCapturedBlueBubblesInboundMessages(deps = {}) {
     const resolvedDeps = { ...defaultDeps, ...deps };
     const agentName = resolvedDeps.getAgentName();
-    const client = resolvedDeps.createClient();
+    const cutover = (0, semantic_receipts_1.initializeBlueBubblesSemanticCutover)(agentName);
     const result = { recovered: 0, skipped: 0, failed: 0 };
-    const seenMessageGuids = new Set();
-    const candidates = (0, inbound_log_1.listRecordedBlueBubblesInbound)(agentName)
-        .filter((entry) => {
-        if (seenMessageGuids.has(entry.messageGuid))
-            return false;
-        seenMessageGuids.add(entry.messageGuid);
-        return true;
-    })
-        .sort((left, right) => (parseTimestampMs(left.recordedAt) ?? 0) - (parseTimestampMs(right.recordedAt) ?? 0));
-    for (const entry of candidates) {
-        if ((0, processed_log_1.hasProcessedBlueBubblesMessage)(agentName, entry.sessionKey, entry.messageGuid)
-            || (0, processed_log_1.hasProcessedBlueBubblesMessageGuid)(agentName, entry.messageGuid)
-            || isBlueBubblesMessageInFlight(entry.sessionKey, entry.messageGuid)) {
+    const seenKeyHashes = new Set();
+    const candidates = (0, semantic_receipts_1.listPendingBlueBubblesSemanticCaptures)(agentName)
+        .sort((left, right) => left.capturedAt.localeCompare(right.capturedAt));
+    for (const capture of candidates) {
+        if (seenKeyHashes.has(capture.keyHash)) {
+            result.skipped++;
+            continue;
+        }
+        seenKeyHashes.add(capture.keyHash);
+        const disposition = (0, semantic_receipts_1.classifyBlueBubblesRecoveryRecord)(capture, cutover);
+        if (disposition.disposition === "audit_only" && disposition.reason !== "audit_event") {
             result.skipped++;
             continue;
         }
+        const normalized = semanticCaptureToNormalizedEvent(capture);
         try {
-            const repaired = await client.repairEvent(inboundEntryToRecoveryEvent(entry));
-            if (repaired.kind !== "message") {
-                result.skipped++;
-                continue;
-            }
-            const handled = await handleBlueBubblesNormalizedEvent(repaired, resolvedDeps, entry.source, {
+            if (!normalized)
+                throw new Error("semantic_capture_routing_invalid");
+            const handled = await handleCapturedBlueBubblesSemanticEvent({
+                status: "captured",
+                capture,
+                normalized,
+                writeResult: "semantic_capture_duplicate",
+            }, resolvedDeps, "webhook", {
                 timeoutMs: BLUEBUBBLES_RECOVERY_TURN_TIMEOUT_MS,
                 autonomyBudgetTrigger: "recovery",
+                semanticRecovery: true,
             });
-            if (shouldCountBlueBubblesRecoveryResultAsSkipped(handled.reason)) {
+            if (handled.reason === "semantic_claim_timeout") {
+                continue;
+            }
+            if (shouldCountBlueBubblesRecoveryResultAsSkipped(handled.reason) || !handled.notifiedAgent) {
                 result.skipped++;
             }
             else {
@@ -2252,7 +2505,8 @@ async function recoverCapturedBlueBubblesInboundMessages(deps = {}) {
             }
         }
         catch (error) {
-            recordBlueBubblesRecoveryFailureForBudget(agentName, inboundEntryToRecoveryEvent(entry), entry.source);
+            if (normalized)
+                recordBlueBubblesRecoveryFailureForBudget(agentName, normalized, "webhook");
             result.failed++;
             (0, runtime_1.emitNervesEvent)({
                 level: "warn",
@@ -2260,58 +2514,33 @@ async function recoverCapturedBlueBubblesInboundMessages(deps = {}) {
                 event: "senses.bluebubbles_capture_recovery_error",
                 message: "captured bluebubbles message recovery failed",
                 meta: {
-                    messageGuid: entry.messageGuid,
-                    sessionKey: entry.sessionKey,
+                    messageGuid: capture.event.eventGuid,
+                    sessionKey: capture.event.sessionKey,
                     reason: error instanceof Error ? error.message : String(error),
                 },
             });
         }
     }
+    const semanticEventGuids = new Set(candidates
+        .map((capture) => capture.event.eventGuid)
+        .filter((eventGuid) => typeof eventGuid === "string")
+        .map((eventGuid) => eventGuid.trim().toLowerCase()));
+    for (const legacyEntry of (0, inbound_log_1.listRecordedBlueBubblesInbound)(agentName)) {
+        if (semanticEventGuids.has(legacyEntry.messageGuid.trim().toLowerCase()))
+            continue;
+        (0, semantic_receipts_1.classifyBlueBubblesRecoveryRecord)(legacyEntry, cutover);
+        result.skipped++;
+    }
     return result;
 }
 async function recoverMissedBlueBubblesMessages(deps = {}) {
     const resolvedDeps = { ...defaultDeps, ...deps };
     const agentName = resolvedDeps.getAgentName();
-    const client = resolvedDeps.createClient();
+    const cutover = (0, semantic_receipts_1.initializeBlueBubblesSemanticCutover)(agentName);
     const result = { recovered: 0, skipped: 0, pending: 0, failed: 0 };
     for (const candidate of (0, mutation_log_1.listBlueBubblesRecoveryCandidates)(agentName)) {
-        if ((0, processed_log_1.hasProcessedBlueBubblesMessage)(agentName, candidate.sessionKey, candidate.messageGuid)
-            || (0, processed_log_1.hasProcessedBlueBubblesMessageGuid)(agentName, candidate.messageGuid)
-            || isBlueBubblesMessageInFlight(candidate.sessionKey, candidate.messageGuid)) {
-            result.skipped++;
-            continue;
-        }
-        try {
-            const repaired = await client.repairEvent(mutationEntryToEvent(candidate));
-            if (repaired.kind !== "message") {
-                result.pending++;
-                continue;
-            }
-            const handled = await handleBlueBubblesNormalizedEvent(repaired, resolvedDeps, "mutation-recovery", {
-                timeoutMs: BLUEBUBBLES_RECOVERY_TURN_TIMEOUT_MS,
-                autonomyBudgetTrigger: "recovery",
-            });
-            if (shouldCountBlueBubblesRecoveryResultAsSkipped(handled.reason)) {
-                result.skipped++;
-            }
-            else {
-                result.recovered++;
-            }
-        }
-        catch (error) {
-            recordBlueBubblesRecoveryFailureForBudget(agentName, mutationEntryToEvent(candidate), "mutation-recovery");
-            result.failed++;
-            (0, runtime_1.emitNervesEvent)({
-                level: "warn",
-                component: "senses",
-                event: "senses.bluebubbles_recovery_error",
-                message: "bluebubbles backlog recovery failed",
-                meta: {
-                    messageGuid: candidate.messageGuid,
-                    reason: error instanceof Error ? error.message : String(error),
-                },
-            });
-        }
+        (0, semantic_receipts_1.classifyBlueBubblesRecoveryRecord)(candidate, cutover);
+        result.skipped++;
     }
     if (result.recovered > 0 || result.skipped > 0 || result.pending > 0 || result.failed > 0) {
         (0, runtime_1.emitNervesEvent)({
@@ -2404,26 +2633,33 @@ function createBlueBubblesWebhookHandler(deps = {}) {
             return;
         }
         const resolvedDeps = { ...defaultDeps, ...deps };
-        if (normalized.kind === "message" && !normalized.fromMe) {
-            (0, inbound_log_1.recordBlueBubblesInbound)(resolvedDeps.getAgentName(), normalized, "webhook");
+        let captured;
+        try {
+            captured = await captureBlueBubblesSemanticEvent(normalized, resolvedDeps, "webhook");
         }
-        else if (normalized.kind === "mutation") {
-            try {
-                resolvedDeps.recordMutation(resolvedDeps.getAgentName(), normalized);
-            }
-            catch (error) {
-                (0, runtime_1.emitNervesEvent)({
-                    level: "error",
-                    component: "senses",
-                    event: "senses.bluebubbles_mutation_log_error",
-                    message: "failed recording bluebubbles mutation sidecar",
-                    meta: {
-                        messageGuid: normalized.messageGuid,
-                        mutationType: normalized.mutationType,
-                        reason: error instanceof Error ? error.message : String(error),
-                    },
-                });
-            }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                component: "senses",
+                event: "senses.bluebubbles_webhook_error",
+                message: "bluebubbles semantic capture failed before acknowledgement",
+                meta: {
+                    messageGuid: normalized.messageGuid,
+                    reason: error instanceof Error ? error.message : String(error),
+                },
+            });
+            writeSemanticCaptureFailure(res);
+            return;
+        }
+        if (captured.status === "audit_only") {
+            writeJson(res, 200, {
+                handled: true,
+                notifiedAgent: false,
+                kind: normalized.kind,
+                queued: false,
+                reason: "ignored",
+            });
+            return;
         }
         writeJson(res, 200, {
             handled: true,
@@ -2433,7 +2669,7 @@ function createBlueBubblesWebhookHandler(deps = {}) {
             reason: "queued",
         });
         setTimeout(() => {
-            void handleBlueBubblesEvent(payload, deps).catch((error) => {
+            void handleCapturedBlueBubblesSemanticEvent(captured, resolvedDeps, "webhook").catch((error) => {
                 (0, runtime_1.emitNervesEvent)({
                     level: "error",
                     component: "senses",
@@ -2852,6 +3088,7 @@ async function drainAndSendPendingBlueBubbles(deps = {}, pendingRoot) {
 }
 function startBlueBubblesApp(deps = {}) {
     const resolvedDeps = { ...defaultDeps, ...deps };
+    (0, semantic_receipts_1.initializeBlueBubblesSemanticCutover)(resolvedDeps.getAgentName());
     resolvedDeps.createClient();
     const channelConfig = (0, config_1.getBlueBubblesChannelConfig)();
     const server = resolvedDeps.createServer(createBlueBubblesWebhookHandler(deps));