@ouro.bot/cli 0.1.0-alpha.13 → 0.1.0-alpha.131

package/dist/senses/bluebubbles.js

@@ -34,22 +34,40 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleBlueBubblesEvent = handleBlueBubblesEvent;
+exports.recoverMissedBlueBubblesMessages = recoverMissedBlueBubblesMessages;
 exports.createBlueBubblesWebhookHandler = createBlueBubblesWebhookHandler;
+exports.sendProactiveBlueBubblesMessageToSession = sendProactiveBlueBubblesMessageToSession;
+exports.drainAndSendPendingBlueBubbles = drainAndSendPendingBlueBubbles;
 exports.startBlueBubblesApp = startBlueBubblesApp;
+const fs = __importStar(require("node:fs"));
 const http = __importStar(require("node:http"));
 const path = __importStar(require("node:path"));
 const core_1 = require("../heart/core");
 const config_1 = require("../heart/config");
 const identity_1 = require("../heart/identity");
+const turn_coordinator_1 = require("../heart/turn-coordinator");
 const context_1 = require("../mind/context");
 const tokens_1 = require("../mind/friends/tokens");
+const group_context_1 = require("../mind/friends/group-context");
 const resolver_1 = require("../mind/friends/resolver");
 const store_file_1 = require("../mind/friends/store-file");
+const types_1 = require("../mind/friends/types");
+const channel_1 = require("../mind/friends/channel");
+const pending_1 = require("../mind/pending");
 const prompt_1 = require("../mind/prompt");
+const mcp_manager_1 = require("../repertoire/mcp-manager");
+const phrases_1 = require("../mind/phrases");
 const runtime_1 = require("../nerves/runtime");
 const bluebubbles_model_1 = require("./bluebubbles-model");
 const bluebubbles_client_1 = require("./bluebubbles-client");
+const bluebubbles_inbound_log_1 = require("./bluebubbles-inbound-log");
 const bluebubbles_mutation_log_1 = require("./bluebubbles-mutation-log");
+const bluebubbles_runtime_state_1 = require("./bluebubbles-runtime-state");
+const bluebubbles_session_cleanup_1 = require("./bluebubbles-session-cleanup");
+const debug_activity_1 = require("./debug-activity");
+const trust_gate_1 = require("./trust-gate");
+const pipeline_1 = require("./pipeline");
+const bbFailoverStates = new Map();
 const defaultDeps = {
     getAgentName: identity_1.getAgentName,
     buildSystem: prompt_1.buildSystem,
@@ -64,6 +82,7 @@ const defaultDeps = {
     createFriendResolver: (store, params) => new resolver_1.FriendResolver(store, params),
     createServer: http.createServer,
 };
+const BLUEBUBBLES_RUNTIME_SYNC_INTERVAL_MS = 30_000;
 function resolveFriendParams(event) {
     if (event.chat.isGroup) {
         const groupKey = event.chat.chatGuid ?? event.chat.chatIdentifier ?? event.sender.externalId;
@@ -81,21 +100,309 @@ function resolveFriendParams(event) {
         channel: "bluebubbles",
     };
 }
-function buildInboundText(event) {
+function resolveGroupExternalId(event) {
+    const groupKey = event.chat.chatGuid ?? event.chat.chatIdentifier ?? event.sender.externalId;
+    return `group:${groupKey}`;
+}
+/**
+ * Check if any participant in a group chat is a known family member.
+ * Looks up each participant handle in the friend store.
+ */
+async function checkGroupHasFamilyMember(store, event) {
+    if (!event.chat.isGroup)
+        return false;
+    for (const handle of event.chat.participantHandles ?? []) {
+        const friend = await store.findByExternalId("imessage-handle", handle);
+        if (friend?.trustLevel === "family")
+            return true;
+    }
+    return false;
+}
+/**
+ * Check if an acquaintance shares any group chat with a family member.
+ * Compares group-prefixed externalIds between the acquaintance and all family members.
+ */
+async function checkHasExistingGroupWithFamily(store, senderFriend) {
+    const trustLevel = senderFriend.trustLevel ?? "friend";
+    if (trustLevel !== "acquaintance")
+        return false;
+    const acquaintanceGroups = new Set((senderFriend.externalIds ?? [])
+        .filter((eid) => eid.externalId.startsWith("group:"))
+        .map((eid) => eid.externalId));
+    if (acquaintanceGroups.size === 0)
+        return false;
+    const allFriends = await (store.listAll?.() ?? Promise.resolve([]));
+    for (const friend of allFriends) {
+        if (friend.trustLevel !== "family")
+            continue;
+        const friendGroups = (friend.externalIds ?? [])
+            .filter((eid) => eid.externalId.startsWith("group:"))
+            .map((eid) => eid.externalId);
+        for (const group of friendGroups) {
+            if (acquaintanceGroups.has(group))
+                return true;
+        }
+    }
+    return false;
+}
+function extractMessageText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((part) => {
+        if (part && typeof part === "object" && "type" in part && part.type === "text" && typeof part.text === "string") {
+            return part.text;
+        }
+        return "";
+    })
+        .filter(Boolean)
+        .join("\n");
+}
+function isHistoricalLaneMetadataLine(line) {
+    return /^\[(conversation scope|recent active lanes|routing control):?/i.test(line)
+        || /^- (top_level|thread:[^:]+):/i.test(line);
+}
+function extractHistoricalLaneSummary(messages) {
+    const seen = new Set();
+    const summaries = [];
+    for (let index = messages.length - 1; index >= 0; index--) {
+        const message = messages[index];
+        if (message.role !== "user")
+            continue;
+        const text = extractMessageText(message.content);
+        if (!text)
+            continue;
+        const firstLine = text.split("\n")[0].trim();
+        const threadMatch = firstLine.match(/thread id: ([^\]|]+)/i);
+        const laneKey = threadMatch
+            ? `thread:${threadMatch[1].trim()}`
+            : /top[-_]level/i.test(firstLine)
+                ? "top_level"
+                : null;
+        if (!laneKey || seen.has(laneKey))
+            continue;
+        seen.add(laneKey);
+        const snippet = text
+            .split("\n")
+            .slice(1)
+            .map((line) => line.trim())
+            .find((line) => line.length > 0 && !isHistoricalLaneMetadataLine(line))
+            ?.slice(0, 80) ?? "(no recent text)";
+        summaries.push({
+            key: laneKey,
+            label: laneKey === "top_level" ? "top_level" : laneKey,
+            snippet,
+        });
+        if (summaries.length >= 5)
+            break;
+    }
+    return summaries;
+}
+function buildConversationScopePrefix(event, existingMessages) {
+    if (event.kind !== "message") {
+        return "";
+    }
+    const summaries = extractHistoricalLaneSummary(existingMessages);
+    const lines = [];
+    if (event.threadOriginatorGuid?.trim()) {
+        lines.push(`[conversation scope: existing chat trunk | current inbound lane: thread | current thread id: ${event.threadOriginatorGuid.trim()} | default outbound target for this turn: current_lane]`);
+    }
+    else {
+        lines.push("[conversation scope: existing chat trunk | current inbound lane: top_level | default outbound target for this turn: top_level]");
+    }
+    if (summaries.length > 0) {
+        lines.push("[recent active lanes]");
+        for (const summary of summaries) {
+            lines.push(`- ${summary.label}: ${summary.snippet}`);
+        }
+    }
+    if (event.threadOriginatorGuid?.trim() || summaries.some((summary) => summary.key.startsWith("thread:"))) {
+        lines.push("[routing control: use bluebubbles_set_reply_target with target=top_level to widen back out, or target=thread plus a listed thread id to route into a specific active thread]");
+    }
+    return lines.join("\n");
+}
+function buildInboundText(event, existingMessages) {
+    const metadataPrefix = buildConversationScopePrefix(event, existingMessages);
     const baseText = event.repairNotice?.trim()
         ? `${event.textForAgent}\n[${event.repairNotice.trim()}]`
         : event.textForAgent;
-    if (!event.chat.isGroup)
-        return baseText;
+    if (!event.chat.isGroup) {
+        return metadataPrefix ? `${metadataPrefix}\n${baseText}` : baseText;
+    }
+    const scopedText = metadataPrefix ? `${metadataPrefix}\n${baseText}` : baseText;
     if (event.kind === "mutation") {
-        return `${event.sender.displayName} ${baseText}`;
+        return `${event.sender.displayName} ${scopedText}`;
+    }
+    return `${event.sender.displayName}: ${scopedText}`;
+}
+function buildInboundContent(event, existingMessages) {
+    const text = buildInboundText(event, existingMessages);
+    if (event.kind !== "message" || !event.inputPartsForAgent || event.inputPartsForAgent.length === 0) {
+        return text;
     }
-    return `${event.sender.displayName}: ${baseText}`;
+    return [
+        { type: "text", text },
+        ...event.inputPartsForAgent,
+    ];
+}
+function sessionLikelyContainsMessage(event, existingMessages) {
+    const fragment = event.textForAgent.trim();
+    if (!fragment)
+        return false;
+    return existingMessages.some((message) => {
+        if (message.role !== "user")
+            return false;
+        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 [];
+    const text = event.textForAgent.trim();
+    if (text.length > 0)
+        return [text];
+    const fallbackText = (event.inputPartsForAgent ?? [])
+        .map((part) => {
+        if (part.type === "text" && typeof part.text === "string") {
+            return part.text.trim();
+        }
+        return "";
+    })
+        .filter(Boolean)
+        .join("\n");
+    return fallbackText ? [fallbackText] : [];
+}
+function createReplyTargetController(event) {
+    const defaultTargetLabel = event.kind === "message" && event.threadOriginatorGuid?.trim() ? "current_lane" : "top_level";
+    let selection = event.kind === "message" && event.threadOriginatorGuid?.trim()
+        ? { target: "current_lane" }
+        : { target: "top_level" };
+    return {
+        getReplyToMessageGuid() {
+            if (event.kind !== "message")
+                return undefined;
+            if (selection.target === "top_level")
+                return undefined;
+            if (selection.target === "thread")
+                return selection.threadOriginatorGuid.trim();
+            return event.threadOriginatorGuid?.trim() ? event.messageGuid : undefined;
+        },
+        setSelection(next) {
+            selection = next;
+            if (next.target === "top_level") {
+                return "bluebubbles reply target override: top_level";
+            }
+            if (next.target === "thread") {
+                return `bluebubbles reply target override: thread:${next.threadOriginatorGuid}`;
+            }
+            return `bluebubbles reply target: using default for this turn (${defaultTargetLabel})`;
+        },
+    };
+}
+function emitBlueBubblesMarkReadWarning(chat, error) {
+    (0, runtime_1.emitNervesEvent)({
+        level: "warn",
+        component: "senses",
+        event: "senses.bluebubbles_mark_read_error",
+        message: "failed to mark bluebubbles chat as read",
+        meta: {
+            chatGuid: chat.chatGuid ?? null,
+            reason: error instanceof Error ? error.message : String(error),
+        },
+    });
 }
-function createBlueBubblesCallbacks(client, chat, replyToMessageGuid) {
+function createBlueBubblesCallbacks(client, chat, replyTarget, isGroupChat) {
     let textBuffer = "";
+    const phrases = (0, phrases_1.getPhrases)();
+    const activity = (0, debug_activity_1.createDebugActivityController)({
+        thinkingPhrases: phrases.thinking,
+        followupPhrases: phrases.followup,
+        startTypingOnModelStart: !isGroupChat,
+        startTypingOnFirstTextChunk: isGroupChat,
+        suppressInitialModelStatus: true,
+        suppressFollowupPhraseStatus: true,
+        transport: {
+            sendStatus: async (text) => {
+                const sent = await client.sendText({
+                    chat,
+                    text,
+                    replyToMessageGuid: replyTarget.getReplyToMessageGuid(),
+                });
+                return sent.messageGuid;
+            },
+            editStatus: async (_messageGuid, text) => {
+                await client.sendText({
+                    chat,
+                    text,
+                    replyToMessageGuid: replyTarget.getReplyToMessageGuid(),
+                });
+            },
+            setTyping: async (active) => {
+                if (!active) {
+                    await client.setTyping(chat, false);
+                    return;
+                }
+                const [markReadResult, typingResult] = await Promise.allSettled([
+                    client.markChatRead(chat),
+                    client.setTyping(chat, true),
+                ]);
+                if (markReadResult.status === "rejected") {
+                    emitBlueBubblesMarkReadWarning(chat, markReadResult.reason);
+                }
+                if (typingResult.status === "rejected") {
+                    throw typingResult.reason;
+                }
+            },
+        },
+        onTransportError: (operation, error) => {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "senses",
+                event: "senses.bluebubbles_activity_error",
+                message: "bluebubbles activity transport failed",
+                meta: {
+                    operation,
+                    reason: error instanceof Error ? error.message : String(error),
+                },
+            });
+        },
+    });
     return {
         onModelStart() {
+            activity.onModelStart();
             (0, runtime_1.emitNervesEvent)({
                 component: "senses",
                 event: "senses.bluebubbles_turn_start",
@@ -112,10 +419,12 @@ function createBlueBubblesCallbacks(client, chat, replyToMessageGuid) {
             });
         },
         onTextChunk(text) {
+            activity.onTextChunk(text);
             textBuffer += text;
         },
         onReasoningChunk(_text) { },
         onToolStart(name, _args) {
+            activity.onToolStart(name, _args);
             (0, runtime_1.emitNervesEvent)({
                 component: "senses",
                 event: "senses.bluebubbles_tool_start",
@@ -124,6 +433,7 @@ function createBlueBubblesCallbacks(client, chat, replyToMessageGuid) {
             });
         },
         onToolEnd(name, summary, success) {
+            activity.onToolEnd(name, summary, success);
             (0, runtime_1.emitNervesEvent)({
                 component: "senses",
                 event: "senses.bluebubbles_tool_end",
@@ -132,6 +442,7 @@ function createBlueBubblesCallbacks(client, chat, replyToMessageGuid) {
             });
         },
         onError(error, severity) {
+            activity.onError(error);
             (0, runtime_1.emitNervesEvent)({
                 level: severity === "terminal" ? "error" : "warn",
                 component: "senses",
@@ -144,17 +455,23 @@ function createBlueBubblesCallbacks(client, chat, replyToMessageGuid) {
             textBuffer = "";
         },
         async flush() {
+            await activity.drain();
             const trimmed = textBuffer.trim();
             if (!trimmed) {
+                await activity.finish();
                 return;
             }
             textBuffer = "";
+            await activity.finish();
             await client.sendText({
                 chat,
                 text: trimmed,
-                replyToMessageGuid,
+                replyToMessageGuid: replyTarget.getReplyToMessageGuid(),
             });
         },
+        async finish() {
+            await activity.finish();
+        },
     };
 }
 async function readRequestBody(req) {
@@ -173,10 +490,8 @@ function isWebhookPasswordValid(url, expectedPassword) {
     const provided = url.searchParams.get("password");
     return !provided || provided === expectedPassword;
 }
-async function handleBlueBubblesEvent(payload, deps = {}) {
-    const resolvedDeps = { ...defaultDeps, ...deps };
+async function handleBlueBubblesNormalizedEvent(event, resolvedDeps, source) {
     const client = resolvedDeps.createClient();
-    const event = await client.repairEvent((0, bluebubbles_model_1.normalizeBlueBubblesEvent)(payload));
     if (event.fromMe) {
         (0, runtime_1.emitNervesEvent)({
             component: "senses",
@@ -219,46 +534,290 @@ async function handleBlueBubblesEvent(payload, deps = {}) {
         });
         return { handled: true, notifiedAgent: false, kind: event.kind, reason: "mutation_state_only" };
     }
+    // ── Adapter setup: friend, session, content, callbacks ──────────
     const store = resolvedDeps.createFriendStore();
     const resolver = resolvedDeps.createFriendResolver(store, resolveFriendParams(event));
-    const context = await resolver.resolve();
-    const toolContext = {
-        signin: async () => undefined,
-        friendStore: store,
-        summarize: (0, core_1.createSummarize)(),
-        context,
-    };
+    const baseContext = await resolver.resolve();
+    const context = { ...baseContext, isGroupChat: event.chat.isGroup };
+    const replyTarget = createReplyTargetController(event);
     const friendId = context.friend.id;
     const sessPath = resolvedDeps.sessionPath(friendId, "bluebubbles", event.chat.sessionKey);
-    const existing = resolvedDeps.loadSession(sessPath);
-    const messages = existing?.messages && existing.messages.length > 0
-        ? existing.messages
-        : [{ role: "system", content: await resolvedDeps.buildSystem("bluebubbles", undefined, context) }];
-    messages.push({ role: "user", content: buildInboundText(event) });
-    const callbacks = createBlueBubblesCallbacks(client, event.chat, event.kind === "message" ? event.messageGuid : undefined);
-    const controller = new AbortController();
-    const agentOptions = {
-        toolContext,
-    };
-    const result = await resolvedDeps.runAgent(messages, callbacks, "bluebubbles", controller.signal, agentOptions);
-    await callbacks.flush();
-    resolvedDeps.postTurn(messages, sessPath, result.usage);
-    await resolvedDeps.accumulateFriendTokens(store, friendId, result.usage);
-    (0, runtime_1.emitNervesEvent)({
-        component: "senses",
-        event: "senses.bluebubbles_turn_end",
-        message: "bluebubbles event handled",
-        meta: {
-            messageGuid: event.messageGuid,
-            kind: event.kind,
-            sessionKey: event.chat.sessionKey,
-        },
+    try {
+        (0, bluebubbles_session_cleanup_1.findObsoleteBlueBubblesThreadSessions)(sessPath);
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.bluebubbles_thread_lane_cleanup_error",
+            message: "failed to inspect obsolete bluebubbles thread-lane sessions",
+            meta: {
+                sessionPath: sessPath,
+                reason: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+    return (0, turn_coordinator_1.withSharedTurnLock)("bluebubbles", sessPath, async () => {
+        // Pre-load session inside the turn lock so same-chat deliveries cannot race on stale trunk state.
+        const existing = resolvedDeps.loadSession(sessPath);
+        const mcpManager = await (0, mcp_manager_1.getSharedMcpManager)() ?? undefined;
+        const sessionMessages = existing?.messages && existing.messages.length > 0
+            ? existing.messages
+            : [{ role: "system", content: await resolvedDeps.buildSystem("bluebubbles", { mcpManager }, context) }];
+        if (event.kind === "message") {
+            const agentName = resolvedDeps.getAgentName();
+            if ((0, bluebubbles_inbound_log_1.hasRecordedBlueBubblesInbound)(agentName, event.chat.sessionKey, event.messageGuid)) {
+                (0, runtime_1.emitNervesEvent)({
+                    component: "senses",
+                    event: "senses.bluebubbles_recovery_skip",
+                    message: "skipped bluebubbles message already recorded as handled",
+                    meta: {
+                        messageGuid: event.messageGuid,
+                        sessionKey: event.chat.sessionKey,
+                        source,
+                    },
+                });
+                return { handled: true, notifiedAgent: false, kind: event.kind, reason: "already_processed" };
+            }
+            // Record EARLY to prevent duplicate processing. BB webhooks can retry
+            // before the first turn completes — recording after the turn is too late.
+            (0, bluebubbles_inbound_log_1.recordBlueBubblesInbound)(agentName, event, source);
+            if (source !== "webhook" && sessionLikelyContainsMessage(event, existing?.messages ?? sessionMessages)) {
+                (0, bluebubbles_inbound_log_1.recordBlueBubblesInbound)(agentName, event, "recovery-bootstrap");
+                (0, runtime_1.emitNervesEvent)({
+                    component: "senses",
+                    event: "senses.bluebubbles_recovery_skip",
+                    message: "skipped bluebubbles recovery because the session already contains the message text",
+                    meta: {
+                        messageGuid: event.messageGuid,
+                        sessionKey: event.chat.sessionKey,
+                        source,
+                    },
+                });
+                return { handled: true, notifiedAgent: false, kind: event.kind, reason: "already_processed" };
+            }
+        }
+        if (event.kind === "message" && event.chat.isGroup) {
+            await (0, group_context_1.upsertGroupContextParticipants)({
+                store,
+                participants: (event.chat.participantHandles ?? []).map((externalId) => ({
+                    provider: "imessage-handle",
+                    externalId,
+                })),
+                groupExternalId: resolveGroupExternalId(event),
+            });
+        }
+        // Build inbound user message (adapter concern: BB-specific content formatting)
+        const userMessage = {
+            role: "user",
+            content: buildInboundContent(event, existing?.messages ?? sessionMessages),
+        };
+        const callbacks = createBlueBubblesCallbacks(client, event.chat, replyTarget, event.chat.isGroup);
+        const controller = new AbortController();
+        // BB-specific tool context wrappers
+        const summarize = (0, core_1.createSummarize)();
+        const bbCapabilities = (0, channel_1.getChannelCapabilities)("bluebubbles");
+        const pendingDir = (0, pending_1.getPendingDir)(resolvedDeps.getAgentName(), friendId, "bluebubbles", event.chat.sessionKey);
+        // ── Compute trust gate context for group/acquaintance rules ─────
+        const groupHasFamilyMember = await checkGroupHasFamilyMember(store, event);
+        const hasExistingGroupWithFamily = event.chat.isGroup
+            ? false
+            : await checkHasExistingGroupWithFamily(store, context.friend);
+        // ── Call shared pipeline ──────────────────────────────────────────
+        try {
+            const result = await (0, pipeline_1.handleInboundTurn)({
+                channel: "bluebubbles",
+                sessionKey: event.chat.sessionKey,
+                capabilities: bbCapabilities,
+                messages: [userMessage],
+                continuityIngressTexts: getBlueBubblesContinuityIngressTexts(event),
+                friendResolver: { resolve: () => Promise.resolve(context) },
+                sessionLoader: {
+                    loadOrCreate: () => Promise.resolve({
+                        messages: sessionMessages,
+                        sessionPath: sessPath,
+                        state: existing?.state,
+                    }),
+                },
+                pendingDir,
+                friendStore: store,
+                provider: "imessage-handle",
+                externalId: event.sender.externalId || event.sender.rawId,
+                isGroupChat: event.chat.isGroup,
+                groupHasFamilyMember,
+                hasExistingGroupWithFamily,
+                enforceTrustGate: trust_gate_1.enforceTrustGate,
+                drainPending: pending_1.drainPending,
+                drainDeferredReturns: (deferredFriendId) => (0, pending_1.drainDeferredReturns)(resolvedDeps.getAgentName(), deferredFriendId),
+                runAgent: (msgs, cb, channel, sig, opts) => resolvedDeps.runAgent(msgs, cb, channel, sig, {
+                    ...opts,
+                    toolContext: {
+                        /* v8 ignore next -- default no-op signin; pipeline provides the real one @preserve */
+                        signin: async () => undefined,
+                        ...opts?.toolContext,
+                        summarize,
+                        bluebubblesReplyTarget: {
+                            setSelection: (selection) => replyTarget.setSelection(selection),
+                        },
+                        codingFeedback: {
+                            send: async (message) => {
+                                await client.sendText({
+                                    chat: event.chat,
+                                    text: message,
+                                    replyToMessageGuid: replyTarget.getReplyToMessageGuid(),
+                                });
+                            },
+                        },
+                    },
+                }),
+                postTurn: resolvedDeps.postTurn,
+                accumulateFriendTokens: resolvedDeps.accumulateFriendTokens,
+                signal: controller.signal,
+                runAgentOptions: { mcpManager },
+                callbacks,
+                failoverState: (() => {
+                    if (!bbFailoverStates.has(event.chat.sessionKey)) {
+                        bbFailoverStates.set(event.chat.sessionKey, { pending: null });
+                    }
+                    return bbFailoverStates.get(event.chat.sessionKey);
+                })(),
+            });
+            /* v8 ignore start -- failover display: tested via pipeline integration tests @preserve */
+            if (result.failoverMessage) {
+                await client.sendText({ chat: event.chat, text: result.failoverMessage });
+            }
+            /* v8 ignore stop */
+            // ── Handle gate result ────────────────────────────────────────
+            if (!result.gateResult.allowed) {
+                // Send auto-reply via BB API if the gate provides one
+                if ("autoReply" in result.gateResult && result.gateResult.autoReply) {
+                    await client.sendText({
+                        chat: event.chat,
+                        text: result.gateResult.autoReply,
+                    });
+                }
+                if (event.kind === "message") {
+                    (0, bluebubbles_inbound_log_1.recordBlueBubblesInbound)(resolvedDeps.getAgentName(), event, source);
+                }
+                return {
+                    handled: true,
+                    notifiedAgent: false,
+                    kind: event.kind,
+                };
+            }
+            // Gate allowed — flush the agent's reply
+            await callbacks.flush();
+            if (event.kind === "message") {
+                (0, bluebubbles_inbound_log_1.recordBlueBubblesInbound)(resolvedDeps.getAgentName(), event, source);
+            }
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "senses.bluebubbles_turn_end",
+                message: "bluebubbles event handled",
+                meta: {
+                    messageGuid: event.messageGuid,
+                    kind: event.kind,
+                    sessionKey: event.chat.sessionKey,
+                },
+            });
+            return {
+                handled: true,
+                notifiedAgent: true,
+                kind: event.kind,
+            };
+        }
+        finally {
+            await callbacks.finish();
+        }
     });
-    return {
-        handled: true,
-        notifiedAgent: true,
-        kind: event.kind,
-    };
+}
+async function handleBlueBubblesEvent(payload, deps = {}) {
+    const resolvedDeps = { ...defaultDeps, ...deps };
+    const client = resolvedDeps.createClient();
+    const event = await client.repairEvent((0, bluebubbles_model_1.normalizeBlueBubblesEvent)(payload));
+    return handleBlueBubblesNormalizedEvent(event, resolvedDeps, "webhook");
+}
+function countPendingRecoveryCandidates(agentName) {
+    return (0, bluebubbles_mutation_log_1.listBlueBubblesRecoveryCandidates)(agentName)
+        .filter((entry) => !(0, bluebubbles_inbound_log_1.hasRecordedBlueBubblesInbound)(agentName, entry.sessionKey, entry.messageGuid))
+        .length;
+}
+async function syncBlueBubblesRuntime(deps = {}) {
+    const resolvedDeps = { ...defaultDeps, ...deps };
+    const agentName = resolvedDeps.getAgentName();
+    const client = resolvedDeps.createClient();
+    const checkedAt = new Date().toISOString();
+    try {
+        await client.checkHealth();
+        const recovery = await recoverMissedBlueBubblesMessages(resolvedDeps);
+        (0, bluebubbles_runtime_state_1.writeBlueBubblesRuntimeState)(agentName, {
+            upstreamStatus: recovery.pending > 0 || recovery.failed > 0 ? "error" : "ok",
+            detail: recovery.failed > 0
+                ? `recovery failures: ${recovery.failed}`
+                : recovery.pending > 0
+                    ? `pending recovery: ${recovery.pending}`
+                    : "upstream reachable",
+            lastCheckedAt: checkedAt,
+            pendingRecoveryCount: recovery.pending,
+            lastRecoveredAt: recovery.recovered > 0 ? checkedAt : undefined,
+        });
+    }
+    catch (error) {
+        (0, bluebubbles_runtime_state_1.writeBlueBubblesRuntimeState)(agentName, {
+            upstreamStatus: "error",
+            detail: error instanceof Error ? error.message : String(error),
+            lastCheckedAt: checkedAt,
+            pendingRecoveryCount: countPendingRecoveryCandidates(agentName),
+        });
+    }
+}
+async function recoverMissedBlueBubblesMessages(deps = {}) {
+    const resolvedDeps = { ...defaultDeps, ...deps };
+    const agentName = resolvedDeps.getAgentName();
+    const client = resolvedDeps.createClient();
+    const result = { recovered: 0, skipped: 0, pending: 0, failed: 0 };
+    for (const candidate of (0, bluebubbles_mutation_log_1.listBlueBubblesRecoveryCandidates)(agentName)) {
+        if ((0, bluebubbles_inbound_log_1.hasRecordedBlueBubblesInbound)(agentName, 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");
+            if (handled.reason === "already_processed") {
+                result.skipped++;
+            }
+            else {
+                result.recovered++;
+            }
+        }
+        catch (error) {
+            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),
+                },
+            });
+        }
+    }
+    if (result.recovered > 0 || result.skipped > 0 || result.pending > 0 || result.failed > 0) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.bluebubbles_recovery_complete",
+            message: "bluebubbles backlog recovery pass completed",
+            meta: { ...result },
+        });
+    }
+    return result;
 }
 function createBlueBubblesWebhookHandler(deps = {}) {
     return async (req, res) => {
@@ -315,11 +874,321 @@ function createBlueBubblesWebhookHandler(deps = {}) {
         }
     };
 }
+function findImessageHandle(friend) {
+    for (const ext of friend.externalIds) {
+        if (ext.provider === "imessage-handle" && !ext.externalId.startsWith("group:")) {
+            return ext.externalId;
+        }
+    }
+    return undefined;
+}
+function normalizeBlueBubblesSessionKey(sessionKey) {
+    const trimmed = sessionKey.trim();
+    if (trimmed.startsWith("chat_identifier_")) {
+        return `chat_identifier:${trimmed.slice("chat_identifier_".length)}`;
+    }
+    if (trimmed.startsWith("chat_")) {
+        return `chat:${trimmed.slice("chat_".length)}`;
+    }
+    return trimmed;
+}
+function extractChatIdentifierFromSessionKey(sessionKey) {
+    const normalizedKey = normalizeBlueBubblesSessionKey(sessionKey);
+    if (normalizedKey.startsWith("chat:")) {
+        const chatGuid = normalizedKey.slice("chat:".length).trim();
+        const parts = chatGuid.split(";");
+        return parts.length >= 3 ? parts[2]?.trim() || undefined : undefined;
+    }
+    if (normalizedKey.startsWith("chat_identifier:")) {
+        const identifier = normalizedKey.slice("chat_identifier:".length).trim();
+        return identifier || undefined;
+    }
+    return undefined;
+}
+function buildChatRefForSessionKey(friend, sessionKey) {
+    const normalizedKey = normalizeBlueBubblesSessionKey(sessionKey);
+    if (normalizedKey.startsWith("chat:")) {
+        const chatGuid = normalizedKey.slice("chat:".length).trim();
+        if (!chatGuid)
+            return null;
+        return {
+            chatGuid,
+            chatIdentifier: extractChatIdentifierFromSessionKey(sessionKey) ?? findImessageHandle(friend),
+            isGroup: chatGuid.includes(";+;"),
+            sessionKey,
+            sendTarget: { kind: "chat_guid", value: chatGuid },
+            participantHandles: [],
+        };
+    }
+    const chatIdentifier = extractChatIdentifierFromSessionKey(sessionKey) ?? findImessageHandle(friend);
+    if (!chatIdentifier)
+        return null;
+    return {
+        chatIdentifier,
+        isGroup: false,
+        sessionKey,
+        sendTarget: { kind: "chat_identifier", value: chatIdentifier },
+        participantHandles: [],
+    };
+}
+async function sendProactiveBlueBubblesMessageToSession(params, deps = {}) {
+    const resolvedDeps = { ...defaultDeps, ...deps };
+    const client = resolvedDeps.createClient();
+    const store = resolvedDeps.createFriendStore();
+    let friend;
+    try {
+        friend = await store.get(params.friendId);
+    }
+    catch {
+        friend = null;
+    }
+    if (!friend) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.bluebubbles_proactive_no_friend",
+            message: "proactive send skipped: friend not found",
+            meta: { friendId: params.friendId, sessionKey: params.sessionKey },
+        });
+        return { delivered: false, reason: "friend_not_found" };
+    }
+    const explicitCrossChatAuthorized = params.intent === "explicit_cross_chat"
+        && types_1.TRUSTED_LEVELS.has(params.authorizingSession?.trustLevel ?? "stranger");
+    if (!explicitCrossChatAuthorized && !types_1.TRUSTED_LEVELS.has(friend.trustLevel ?? "stranger")) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.bluebubbles_proactive_trust_skip",
+            message: "proactive send skipped: trust level not allowed",
+            meta: {
+                friendId: params.friendId,
+                sessionKey: params.sessionKey,
+                trustLevel: friend.trustLevel ?? "unknown",
+                intent: params.intent ?? "generic_outreach",
+                authorizingTrustLevel: params.authorizingSession?.trustLevel ?? null,
+            },
+        });
+        return { delivered: false, reason: "trust_skip" };
+    }
+    const chat = buildChatRefForSessionKey(friend, params.sessionKey);
+    if (!chat) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.bluebubbles_proactive_no_handle",
+            message: "proactive send skipped: no iMessage handle found",
+            meta: { friendId: params.friendId, sessionKey: params.sessionKey },
+        });
+        return { delivered: false, reason: "missing_target" };
+    }
+    try {
+        await client.sendText({ chat, text: params.text });
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.bluebubbles_proactive_sent",
+            message: "proactive bluebubbles message sent",
+            meta: {
+                friendId: params.friendId,
+                sessionKey: params.sessionKey,
+                chatGuid: chat.chatGuid ?? null,
+                chatIdentifier: chat.chatIdentifier ?? null,
+            },
+        });
+        return { delivered: true };
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "error",
+            component: "senses",
+            event: "senses.bluebubbles_proactive_send_error",
+            message: "proactive bluebubbles send failed",
+            meta: {
+                friendId: params.friendId,
+                sessionKey: params.sessionKey,
+                reason: error instanceof Error ? error.message : String(error),
+            },
+        });
+        return { delivered: false, reason: "send_error" };
+    }
+}
+function scanPendingBlueBubblesFiles(pendingRoot) {
+    const results = [];
+    let friendIds;
+    try {
+        friendIds = fs.readdirSync(pendingRoot);
+    }
+    catch {
+        return results;
+    }
+    for (const friendId of friendIds) {
+        const bbDir = path.join(pendingRoot, friendId, "bluebubbles");
+        let keys;
+        try {
+            keys = fs.readdirSync(bbDir);
+        }
+        catch {
+            continue;
+        }
+        for (const key of keys) {
+            const keyDir = path.join(bbDir, key);
+            let files;
+            try {
+                files = fs.readdirSync(keyDir);
+            }
+            catch {
+                continue;
+            }
+            for (const file of files.filter((f) => f.endsWith(".json")).sort()) {
+                const filePath = path.join(keyDir, file);
+                try {
+                    const content = fs.readFileSync(filePath, "utf-8");
+                    results.push({ friendId, key, filePath, content });
+                }
+                catch {
+                    // skip unreadable files
+                }
+            }
+        }
+    }
+    return results;
+}
+async function drainAndSendPendingBlueBubbles(deps = {}, pendingRoot) {
+    const resolvedDeps = { ...defaultDeps, ...deps };
+    const root = pendingRoot ?? path.join((0, identity_1.getAgentRoot)(), "state", "pending");
+    const client = resolvedDeps.createClient();
+    const store = resolvedDeps.createFriendStore();
+    const pendingFiles = scanPendingBlueBubblesFiles(root);
+    const result = { sent: 0, skipped: 0, failed: 0 };
+    for (const { friendId, filePath, content } of pendingFiles) {
+        let parsed;
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch {
+            result.failed++;
+            try {
+                fs.unlinkSync(filePath);
+            }
+            catch { /* ignore */ }
+            continue;
+        }
+        const messageText = typeof parsed.content === "string" ? parsed.content : "";
+        if (!messageText.trim()) {
+            result.skipped++;
+            try {
+                fs.unlinkSync(filePath);
+            }
+            catch { /* ignore */ }
+            continue;
+        }
+        let friend;
+        try {
+            friend = await store.get(friendId);
+        }
+        catch {
+            friend = null;
+        }
+        if (!friend) {
+            result.skipped++;
+            try {
+                fs.unlinkSync(filePath);
+            }
+            catch { /* ignore */ }
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "senses",
+                event: "senses.bluebubbles_proactive_no_friend",
+                message: "proactive send skipped: friend not found",
+                meta: { friendId },
+            });
+            continue;
+        }
+        if (!types_1.TRUSTED_LEVELS.has(friend.trustLevel ?? "stranger")) {
+            result.skipped++;
+            try {
+                fs.unlinkSync(filePath);
+            }
+            catch { /* ignore */ }
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "senses.bluebubbles_proactive_trust_skip",
+                message: "proactive send skipped: trust level not allowed",
+                meta: { friendId, trustLevel: friend.trustLevel ?? "unknown" },
+            });
+            continue;
+        }
+        const handle = findImessageHandle(friend);
+        if (!handle) {
+            result.skipped++;
+            try {
+                fs.unlinkSync(filePath);
+            }
+            catch { /* ignore */ }
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "senses",
+                event: "senses.bluebubbles_proactive_no_handle",
+                message: "proactive send skipped: no iMessage handle found",
+                meta: { friendId },
+            });
+            continue;
+        }
+        const chat = {
+            chatIdentifier: handle,
+            isGroup: false,
+            sessionKey: friendId,
+            sendTarget: { kind: "chat_identifier", value: handle },
+            participantHandles: [],
+        };
+        try {
+            await client.sendText({ chat, text: messageText });
+            result.sent++;
+            try {
+                fs.unlinkSync(filePath);
+            }
+            catch { /* ignore */ }
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "senses.bluebubbles_proactive_sent",
+                message: "proactive bluebubbles message sent",
+                meta: { friendId, handle },
+            });
+        }
+        catch (error) {
+            result.failed++;
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                component: "senses",
+                event: "senses.bluebubbles_proactive_send_error",
+                message: "proactive bluebubbles send failed",
+                meta: {
+                    friendId,
+                    handle,
+                    reason: error instanceof Error ? error.message : String(error),
+                },
+            });
+        }
+    }
+    if (result.sent > 0 || result.skipped > 0 || result.failed > 0) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.bluebubbles_proactive_drain_complete",
+            message: "bluebubbles proactive drain complete",
+            meta: { sent: result.sent, skipped: result.skipped, failed: result.failed },
+        });
+    }
+    return result;
+}
 function startBlueBubblesApp(deps = {}) {
     const resolvedDeps = { ...defaultDeps, ...deps };
     resolvedDeps.createClient();
     const channelConfig = (0, config_1.getBlueBubblesChannelConfig)();
     const server = resolvedDeps.createServer(createBlueBubblesWebhookHandler(deps));
+    const runtimeTimer = setInterval(() => {
+        void syncBlueBubblesRuntime(resolvedDeps);
+    }, BLUEBUBBLES_RUNTIME_SYNC_INTERVAL_MS);
+    server.on?.("close", () => {
+        clearInterval(runtimeTimer);
+    });
     server.listen(channelConfig.port, () => {
         (0, runtime_1.emitNervesEvent)({
             component: "channels",
@@ -328,5 +1197,6 @@ function startBlueBubblesApp(deps = {}) {
             meta: { port: channelConfig.port, webhookPath: channelConfig.webhookPath },
         });
     });
+    void syncBlueBubblesRuntime(resolvedDeps);
     return server;
 }