@ouro.bot/cli 0.1.0-alpha.722 → 0.1.0-alpha.723

package/dist/heart/daemon/doctor.js

@@ -808,7 +808,7 @@ function tripStoresDiffer(deps, durableRoot, legacyRoot) {
     }
     return false;
 }
-function checkMailroom(deps) {
+async function checkMailroom(deps) {
     const checks = [];
     const agents = discoverAgents(deps);
     if (agents.length === 0) {
@@ -853,7 +853,7 @@ function checkMailroom(deps) {
             continue;
         }
         const messagesDir = `${mailroomRoot}/messages`;
-        const listing = listStoredMailMessages(deps, messagesDir);
+        const listing = listJsonDocuments(deps, messagesDir);
         /* v8 ignore start -- defensive: pluralization branches depend on filesystem-state fixtures not exhaustively covered @preserve */
         checks.push({
             label: `${agentDir} mailroom`,
@@ -861,20 +861,90 @@ function checkMailroom(deps) {
             detail: `${mailboxes.length} mailbox${mailboxes.length === 1 ? "" : "es"}, ${sourceGrants.length} source grant${sourceGrants.length === 1 ? "" : "s"}, ${listing.count} message${listing.count === 1 ? "" : "s"} stored (cumulative — not a liveness signal)`,
         });
         /* v8 ignore stop */
-        checks.push(mailIngestLivenessCheck(deps, agentDir, mailroomRoot, messagesDir, listing));
+        checks.push(mailIngestLivenessCheck(deps, agentDir, mailroomRoot, messagesDir, listing, await resolveMailStore(agentDir)));
     }
     return { name: "Mailroom", checks };
 }
-function listStoredMailMessages(deps, messagesDir) {
-    if (!deps.existsSync(messagesDir))
+function listJsonDocuments(deps, dir) {
+    if (!deps.existsSync(dir))
         return { count: 0, readable: true };
     try {
-        return { count: deps.readdirSync(messagesDir).filter((name) => name.endsWith(".json")).length, readable: true };
+        return { count: deps.readdirSync(dir).filter((name) => name.endsWith(".json")).length, readable: true };
     }
     catch {
         return { count: 0, readable: false };
     }
 }
+async function resolveMailStore(agentDir) {
+    const agentName = agentDir.replace(/\.ouro$/, "");
+    // An unreadable vault means the mode is unknown, so this falls back to the
+    // reader's own default — the local file store. `mail config` in checkSenses
+    // is where an unavailable runtime config is reported, and it fails hard.
+    const runtimeConfig = await (0, runtime_credentials_1.refreshRuntimeCredentialConfig)(agentName, { preserveCachedOnFailure: true });
+    if (!runtimeConfig.ok)
+        return { hosted: false };
+    const mailroom = asRecord(runtimeConfig.config.mailroom);
+    const azureAccountUrl = textField(mailroom, "azureAccountUrl");
+    if (!azureAccountUrl)
+        return { hosted: false };
+    const azureContainer = textField(mailroom, "azureContainer") || "mailroom";
+    return { hosted: true, label: `hosted azure-blob ${azureAccountUrl}/${azureContainer}` };
+}
+/**
+ * Local-file Mailroom liveness signal.
+ *
+ * The `messages/` directory mtime is both the cheapest and the most correct
+ * option. Cheapest: one stat regardless of store size, and the production store
+ * holds ~45k message files. Most correct: a message's `receivedAt` is when the
+ * mail was *sent* (an mbox backfill writes month-old values today), so parsing
+ * message bodies would answer a different question than "did this machine
+ * ingest anything recently?".
+ */
+function localMailStoreProbe(deps, messagesDir, listing) {
+    if (!listing.readable) {
+        return {
+            observation: { kind: "unknown", reason: `${messagesDir} exists but could not be listed` },
+            provenance: `attempted directory listing of ${messagesDir}`,
+        };
+    }
+    return (0, freshness_1.observeCreatePerEventStore)(messagesDir, deps, { hasEntries: listing.count > 0 });
+}
+/**
+ * Hosted Mailroom liveness signal.
+ *
+ * Once an agent is cut over to the hosted store, messages live in the Blob
+ * container and nothing writes to `state/mailroom/messages` any more, so its
+ * mtime freezes at the cutover. Reading it in hosted mode is how this check
+ * reported "no mail ingested in 77 days" on 2026-07-27 while the container was
+ * taking mail that same morning — a false failure, which trains operators to
+ * ignore the check and so undoes the reason it exists.
+ *
+ * The local artifact that does still move is the hosted reader's search cache:
+ * `AzureBlobMailroomStore` writes `state/mail-search/<messageId>.json` for
+ * every message it decrypts (see `mailroom/reader.ts`, which hands the hosted
+ * store that cache directory). Message ids are content hashes, so a *new* file
+ * appears exactly when this machine sees a message it has never seen before;
+ * re-reading old mail rewrites existing files and leaves the directory mtime
+ * untouched. Same create-per-event shape as the local store, same O(1) stat.
+ *
+ * It is deliberately one step downstream of ingest: it proves hosted mail
+ * reached this machine, which is the strongest claim available without network
+ * access or Azure credentials — a health check must need neither. The activity
+ * wording, provenance and remediation all say so rather than implying doctor
+ * measured the container itself, and an empty mirror reports `unknown` rather
+ * than the hosted store being empty.
+ */
+function hostedMailMirrorProbe(deps, agentDir, storeLabel) {
+    const mirrorDir = `${deps.bundlesRoot}/${agentDir}/state/mail-search`;
+    const listing = listJsonDocuments(deps, mirrorDir);
+    if (!listing.readable) {
+        return {
+            observation: { kind: "unknown", reason: `${mirrorDir} exists but could not be listed` },
+            provenance: `attempted directory listing of ${mirrorDir}`,
+        };
+    }
+    return (0, freshness_1.observeMirroredStore)(mirrorDir, deps, { hasEntries: listing.count > 0, remote: storeLabel });
+}
 /**
  * Mail-ingest liveness — "is mail still arriving?", as opposed to the check
  * above, which only says "is a mailbox configured?".
@@ -883,30 +953,27 @@ function listStoredMailMessages(deps, messagesDir) {
  * its config, and a cumulative count of 45,479 messages all reported ✔ for 77
  * days while zero mail was ingested.
  *
- * The signal is the `messages/` directory mtime, which is both the cheapest
- * and the most correct option. Cheapest: one stat regardless of store size,
- * and the production store holds ~45k message files. Most correct: a message's
- * `receivedAt` is when the mail was *sent* (an mbox backfill writes month-old
- * values today), so parsing message bodies would answer a different question
- * than "did this machine ingest anything recently?".
+ * Which signal is honest depends on where the store lives, so the probe, the
+ * activity wording and the remediation are all chosen per store kind. Reusing
+ * the local path in hosted mode measures a directory nothing writes to.
  */
-function mailIngestLivenessCheck(deps, agentDir, mailroomRoot, messagesDir, listing) {
-    const probe = listing.readable
-        ? (0, freshness_1.observeCreatePerEventStore)(messagesDir, deps, { hasEntries: listing.count > 0 })
-        : {
-            observation: { kind: "unknown", reason: `${messagesDir} exists but could not be listed` },
-            provenance: `attempted directory listing of ${messagesDir}`,
-        };
+function mailIngestLivenessCheck(deps, agentDir, mailroomRoot, messagesDir, listing, store) {
+    const hosted = store.hosted ? store : null;
+    const probe = hosted
+        ? hostedMailMirrorProbe(deps, agentDir, hosted.label)
+        : localMailStoreProbe(deps, messagesDir, listing);
     return pipelineLivenessCheck({
         id: "mail.ingest_liveness",
         label: `${agentDir} mail ingest liveness`,
-        activity: "mail ingested",
+        activity: hosted ? "hosted mail observed locally" : "mail ingested",
         unit: "message",
         probe,
         thresholds: (0, freshness_1.resolveFreshnessThresholds)(exports.DEFAULT_MAIL_INGEST_THRESHOLDS, senseFreshnessOverride(deps, agentDir, "mail")),
-        remediation: "mail is configured but nothing is arriving — re-check the mailbox grant and keyIds against the vault (a server-side key rotation silently orphans ingestion), run `ouro connect mail --agent <agent>`, and inspect the mailroom ingress logs",
+        remediation: hosted
+            ? `doctor measures hosted mail only through this machine's local mirror and makes no network calls — confirm the container itself by listing \`messages/\` blobs in ${hosted.label} by Last-Modified, or read the mailbox directly (\`ouro mailbox\`, or the agent's \`mail_recent\` tool); if the mirror is empty or stale while the container is current, the hosted reader on this machine is not running`
+            : "mail is configured but nothing is arriving — re-check the mailbox grant and keyIds against the vault (a server-side key rotation silently orphans ingestion), run `ouro connect mail --agent <agent>`, and inspect the mailroom ingress logs",
         configuredSinceMs: pathMtimeMs(deps, `${mailroomRoot}/registry.json`),
-        context: "mailbox configured",
+        context: hosted ? `mailbox configured; ${hosted.label}` : "mailbox configured",
         nowMs: Date.now(),
     });
 }

package/dist/heart/daemon/freshness.js

@@ -35,6 +35,7 @@ exports.formatFreshnessAge = formatFreshnessAge;
 exports.formatFreshnessTimestamp = formatFreshnessTimestamp;
 exports.evaluateFreshness = evaluateFreshness;
 exports.observeCreatePerEventStore = observeCreatePerEventStore;
+exports.observeMirroredStore = observeMirroredStore;
 exports.observeAppendPerEventStore = observeAppendPerEventStore;
 exports.resolveFreshnessThresholds = resolveFreshnessThresholds;
 const runtime_1 = require("../../nerves/runtime");
@@ -215,6 +216,46 @@ function observeCreatePerEventStore(dir, deps, options) {
         };
     }
 }
+/**
+ * Last-observation probe for a **local mirror of a remote store** — the cache
+ * this machine writes as it reads a store that lives somewhere else, such as
+ * the hosted Mailroom's `state/mail-search/<messageId>.json` documents.
+ *
+ * Mechanically this is `observeCreatePerEventStore`: one file per event, named
+ * by a content-addressed id, so the directory mtime answers "when did this
+ * machine last record something it had never seen before" for O(1) cost.
+ *
+ * One rule differs, and it is the entire reason this exists: an absent or empty
+ * mirror is `unknown`, never `none`. For a local store the directory *is* the
+ * store, so empty means "nothing was ever delivered". For a mirror the
+ * authoritative store is remote and deliberately not read here — a health check
+ * must not need network access or credentials — so empty means only "this
+ * machine holds no record". That is absence of evidence, and rendering it as a
+ * confident "never delivered" would be the same crying-wolf failure as reading
+ * a local directory that nothing writes to any more.
+ */
+function observeMirroredStore(dir, deps, options) {
+    const provenance = `derived from the local mirror at ${dir} (directory mtime, O(1), no per-entry scan); the authoritative store is ${options.remote}, which doctor does not read`;
+    const exists = deps.existsSync(dir);
+    if (!exists || !options.hasEntries) {
+        return {
+            observation: {
+                kind: "unknown",
+                reason: `the local mirror at ${dir} is ${exists ? "empty" : "absent"}, and ${options.remote} is not read by doctor (no network calls, no credentials), so recency cannot be measured on this machine`,
+            },
+            provenance,
+        };
+    }
+    try {
+        return { observation: { kind: "activity", atMs: deps.statSync(dir).mtimeMs }, provenance };
+    }
+    catch (error) {
+        return {
+            observation: { kind: "unknown", reason: `${dir} could not be stat'd: ${error instanceof Error ? error.message : String(error)}` },
+            provenance,
+        };
+    }
+}
 /**
  * Last-write probe for **append-per-event** stores — a small set of long-lived
  * logs appended in place, such as the BlueBubbles inbound ndjson (one file per

package/dist/heart/orientation-frame.js

@@ -72,9 +72,17 @@ function extractOrderedListReferents(text) {
     }
     return referents;
 }
-function hasCorrectionMarker(text) {
-    return /\b(hang on|wait|actually|not that|not this|wrong|misunderstood|you(?:'re| are) right|correct)\b/i.test(text)
-        || /^\s*no[\s,]/i.test(text);
+/**
+ * Returns the marker that fired, not just a boolean: when the hold blocks an action
+ * the agent has to be able to see *which* word triggered it. In the 2026-07-27
+ * incident it guessed wrong twice ("it's because of the word 'useful'") because the
+ * block message named no trigger.
+ */
+function correctionMarkerIn(text) {
+    const phrase = /\b(hang on|wait|actually|not that|not this|wrong|misunderstood|you(?:'re| are) right|correct)\b/i.exec(text);
+    if (phrase)
+        return phrase[0].toLowerCase();
+    return /^\s*no[\s,]/i.test(text) ? "no" : undefined;
 }
 function isTerseReferent(text) {
     const normalized = text.trim().toLowerCase().replace(/[.!?]+$/g, "");
@@ -93,12 +101,16 @@ function shouldAttachStructuredOutput(combinedSpeech, signals) {
         return true;
     return signals.some((signal) => signal === "terse_referent" || signal === "correction_marker");
 }
-function deriveSignals(currentUserSpeech, priorAssistantReferents, latestStructuredOutput) {
+function deriveSignals(currentUserSpeech, priorAssistantReferents, latestStructuredOutput, speechKind) {
     const combined = currentUserSpeech.join("\n").trim();
-    if (!combined)
+    // A reaction is an acknowledgement of an existing message, not new speech. Its
+    // text is synthesised by the sense from the message being reacted to, so scanning
+    // it would read the *quoted* message's words as the human's correction — and a
+    // positive tapback is approval, which must never gate outbound work.
+    if (!combined || speechKind === "reaction")
         return [];
     const signals = [];
-    if (hasCorrectionMarker(combined))
+    if (correctionMarkerIn(combined))
         signals.push("correction_marker");
     if (priorAssistantReferents.length > 0 && isTerseReferent(combined))
         signals.push("terse_referent");
@@ -106,15 +118,42 @@ function deriveSignals(currentUserSpeech, priorAssistantReferents, latestStructu
         signals.push("structured_referent");
     return [...new Set(signals)];
 }
-function deriveActionPolicy(signals) {
-    if (signals.length === 0)
+/**
+ * The hold exists for corrections that are terse or ambiguous ("no, not that one").
+ * A correction word buried in a long, self-contained instruction is neither: on
+ * 2026-07-27 the word "actually" — in "Do NOT claim a hotel has AC unless you
+ * actually saw evidence" — armed the hold inside a 195-word directive that had zero
+ * prior referents and no structured output, and blocked five consecutive
+ * `send_message` calls. The same directive was what authorised the send, and with
+ * nothing to disambiguate the remedy the block named could not be performed.
+ */
+const TERSE_CORRECTION_MAX_WORDS = 12;
+const CORRECTION_HOLD_CLEARED_BY = "Resolve the referent (orientation_get lists the candidates) or restate the request as a standalone, correction-free instruction. The policy is recomputed from each user turn, so it never carries past this turn.";
+function countWords(text) {
+    return text.trim().split(/\s+/).filter(Boolean).length;
+}
+function correctionMarkerArmsHold(combinedSpeech, priorAssistantReferents, latestStructuredOutput) {
+    if (countWords(combinedSpeech) <= TERSE_CORRECTION_MAX_WORDS)
+        return true;
+    // Long speech still holds when there is something concrete to disambiguate.
+    return priorAssistantReferents.length > 0 || Boolean(latestStructuredOutput);
+}
+function deriveActionPolicy(signals, combinedSpeech, priorAssistantReferents, latestStructuredOutput) {
+    const holdSignals = signals.filter((signal) => signal !== "correction_marker"
+        || correctionMarkerArmsHold(combinedSpeech, priorAssistantReferents, latestStructuredOutput));
+    if (holdSignals.length === 0)
         return { mode: "normal" };
+    const triggeredBy = holdSignals.includes("correction_marker")
+        ? correctionMarkerIn(combinedSpeech)
+        : undefined;
     return {
         mode: "correction_hold",
-        reason: signals.includes("terse_referent")
+        reason: holdSignals.includes("terse_referent")
             ? "Current user speech appears referent-dependent; inspect orientation before mutating durable state."
             : "Current user speech appears to correct or revise prior understanding; inspect orientation before mutating durable state.",
         blockedMutationKinds: ["durable_state_write", "external_side_effect"],
+        ...(triggeredBy ? { triggeredBy } : {}),
+        clearedBy: CORRECTION_HOLD_CLEARED_BY,
     };
 }
 function buildOrientationFrame(input) {
@@ -127,12 +166,13 @@ function buildOrientationFrame(input) {
     const previousAssistant = latestAssistantBefore(input.messages, derivedCurrent.firstIndex);
     const priorAssistantReferents = extractOrderedListReferents(extractMessageText(previousAssistant));
     const candidateStructuredOutput = latestStructuredOutputFrom(input.structuredOutputs);
-    const signals = deriveSignals(currentUserSpeech, priorAssistantReferents, candidateStructuredOutput);
+    const speechKind = input.speechKind ?? "utterance";
+    const signals = deriveSignals(currentUserSpeech, priorAssistantReferents, candidateStructuredOutput, speechKind);
     const combinedSpeech = currentUserSpeech.join("\n").trim();
     const latestStructuredOutput = candidateStructuredOutput && shouldAttachStructuredOutput(combinedSpeech, signals)
         ? candidateStructuredOutput
         : undefined;
-    const actionPolicy = deriveActionPolicy(signals);
+    const actionPolicy = deriveActionPolicy(signals, combinedSpeech, priorAssistantReferents, candidateStructuredOutput);
     const frame = {
         schemaVersion: 1,
         channel: input.channel,
@@ -142,6 +182,7 @@ function buildOrientationFrame(input) {
         signals,
         actionPolicy,
         ...(input.source ? { source: input.source } : {}),
+        ...(speechKind === "utterance" ? {} : { speechKind }),
     };
     (0, runtime_1.emitNervesEvent)({
         component: "engine",
@@ -155,6 +196,27 @@ function buildOrientationFrame(input) {
             policy: actionPolicy.mode,
         },
     });
+    if (actionPolicy.mode === "correction_hold") {
+        // Distinct + greppable: a hold that blocks an explicitly requested action must
+        // leave a trace naming what it blocks and what releases it.
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "engine",
+            event: "orientation.correction_hold_armed",
+            message: "orientation correction hold armed",
+            meta: {
+                channel: input.channel,
+                speechKind,
+                signals,
+                blockedMutationKinds: actionPolicy.blockedMutationKinds,
+                triggeredBy: actionPolicy.triggeredBy ?? null,
+                referentCount: priorAssistantReferents.length,
+                structuredOutput: candidateStructuredOutput?.id ?? null,
+                speechWordCount: countWords(combinedSpeech),
+                clearedBy: actionPolicy.clearedBy,
+            },
+        });
+    }
     return frame;
 }
 function renderOrientationFrame(frame) {
@@ -165,6 +227,15 @@ function renderOrientationFrame(frame) {
     ];
     if (frame.actionPolicy.mode === "correction_hold") {
         lines.push(`policy reason: ${frame.actionPolicy.reason}`);
+        lines.push(`policy blocks: ${frame.actionPolicy.blockedMutationKinds.join(", ")}`);
+        if (frame.actionPolicy.triggeredBy) {
+            lines.push(`policy trigger: correction marker "${frame.actionPolicy.triggeredBy}" in current user speech`);
+        }
+        if (frame.actionPolicy.clearedBy)
+            lines.push(`policy clears when: ${frame.actionPolicy.clearedBy}`);
+    }
+    if (frame.speechKind) {
+        lines.push(`speech kind: ${frame.speechKind}`);
     }
     if (frame.source) {
         lines.push("source:");

package/dist/senses/bluebubbles/client.js

@@ -687,5 +687,54 @@ function createBlueBubblesClient(config = (0, config_1.getBlueBubblesConfig)(),
                 return null;
             }
         },
+        async getMessageDetails(messageGuid) {
+            const url = buildRepairUrl(config.serverUrl, messageGuid, config.password);
+            try {
+                const response = await fetch(url, {
+                    method: "GET",
+                    signal: AbortSignal.timeout(channelConfig.requestTimeoutMs),
+                });
+                if (!response.ok) {
+                    (0, runtime_1.emitNervesEvent)({
+                        level: "warn",
+                        component: "senses",
+                        event: "senses.bluebubbles_get_message_details_error",
+                        message: "failed to fetch message details",
+                        meta: { messageGuid, status: response.status },
+                    });
+                    return null;
+                }
+                const data = extractRepairData(await parseJsonBody(response));
+                if (!data) {
+                    (0, runtime_1.emitNervesEvent)({
+                        level: "warn",
+                        component: "senses",
+                        event: "senses.bluebubbles_get_message_details_error",
+                        message: "message payload was not a record",
+                        meta: { messageGuid },
+                    });
+                    return null;
+                }
+                const text = typeof data.text === "string" ? data.text.trim() || null : null;
+                const fromMe = typeof data.isFromMe === "boolean" ? data.isFromMe : null;
+                (0, runtime_1.emitNervesEvent)({
+                    component: "senses",
+                    event: "senses.bluebubbles_get_message_details",
+                    message: "fetched message details by guid",
+                    meta: { messageGuid, hasText: text !== null, hasAuthorship: fromMe !== null },
+                });
+                return { text, fromMe };
+            }
+            catch (error) {
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    component: "senses",
+                    event: "senses.bluebubbles_get_message_details_error",
+                    message: "exception fetching message details",
+                    meta: { messageGuid, reason: error instanceof Error ? error.message : String(error) },
+                });
+                return null;
+            }
+        },
     };
 }

package/dist/senses/bluebubbles/index.js

@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BB_IN_FLIGHT_MAX_AGE_MS = void 0;
-exports.enrichReactionText = enrichReactionText;
+exports.resolveReactionTarget = resolveReactionTarget;
 exports.tokenizeForDedupe = tokenizeForDedupe;
 exports.jaccardSimilarity = jaccardSimilarity;
 exports.createStatusBatcher = createStatusBatcher;
@@ -116,16 +116,19 @@ const bbInFlightMessageClaims = new Map();
  * a leaked marker from blocking forward progress for hours.
  */
 exports.BB_IN_FLIGHT_MAX_AGE_MS = 15 * 60_000;
-// Enrich reaction text with the original message content for context.
-// If originalText is provided and non-empty, format as: baseText to: "truncated"
-// Otherwise return baseText unchanged.
-function enrichReactionText(baseText, originalText, maxLen) {
-    if (!originalText)
-        return baseText;
-    const truncated = originalText.length > maxLen
-        ? originalText.slice(0, maxLen - 3) + "..."
-        : originalText;
-    return `${baseText} to: "${truncated}"`;
+// Resolve the message a reaction points at, so the agent is told *what* was
+// reacted to and *whose* message it was rather than a bare "reacted with love".
+// Prefers the authorship-carrying lookup; falls back to text-only when the client
+// does not provide one. Every failure path returns an explicit "unknown" rather
+// than a value the caller could mistake for a resolved target.
+async function resolveReactionTarget(client, targetMessageGuid) {
+    const base = { guid: targetMessageGuid };
+    if (client.getMessageDetails) {
+        const details = await client.getMessageDetails(targetMessageGuid).catch(() => null);
+        return { ...base, text: details?.text ?? null, fromMe: details?.fromMe ?? null };
+    }
+    const text = await client.getMessageText(targetMessageGuid).catch(() => null);
+    return { ...base, text, fromMe: null };
 }
 // ── Near-duplicate outward-text detection ────────────────────────
 // Used by createBlueBubblesCallbacks to collapse mid-turn rephrasings of the
@@ -1390,13 +1393,14 @@ async function handleBlueBubblesNormalizedEvent(event, resolvedDeps, source, opt
                     meta: { threadGuid, hasText: !!repliedToText },
                 });
             }
-            // Enrich reaction mutations with the original message text for context
+            // 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.targetMessageGuid) {
-                /* v8 ignore start -- best-effort lookup; enrichReactionText covered by unit tests @preserve */
-                const originalText = await client.getMessageText(event.targetMessageGuid).catch(() => null);
-                if (originalText)
-                    event.textForAgent = enrichReactionText(event.textForAgent, originalText, 80);
+            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.
@@ -1411,6 +1415,7 @@ async function handleBlueBubblesNormalizedEvent(event, resolvedDeps, source, opt
                 currentUserMessages: [userMessage],
                 structuredOutputs: existing?.structuredOutputs ?? [],
                 source: buildBlueBubblesOrientationSource(event, priorMessages, repliedToText),
+                ...(isReaction ? { speechKind: "reaction" } : {}),
             });
             const visibleActivityTurnId = activeTurnId;
             const callbacks = createBlueBubblesCallbacks(client, event.chat, replyTarget, event.chat.isGroup, visibleActivityTurnId

package/dist/senses/bluebubbles/model.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BlueBubblesIgnoredEventError = void 0;
+exports.describeBlueBubblesReaction = describeBlueBubblesReaction;
+exports.renderBlueBubblesReactionText = renderBlueBubblesReactionText;
 exports.normalizeBlueBubblesEvent = normalizeBlueBubblesEvent;
 const runtime_1 = require("../../nerves/runtime");
 const render_1 = require("../../heart/attachments/render");
@@ -150,11 +152,70 @@ function formatMessageText(data, attachments) {
     return formatAttachmentText(attachments);
 }
 function normalizeReactionName(value) {
+    // chat.db stores associated_message_type as an integer; BlueBubbles forwards it
+    // as either the integer, its decimal string, or a name ("love", "-love").
+    if (typeof value === "number") {
+        return Number.isFinite(value) && value !== 0 ? String(value) : undefined;
+    }
     if (typeof value !== "string")
         return undefined;
     const trimmed = value.trim();
     return trimmed ? trimmed.toLowerCase() : undefined;
 }
+/**
+ * iMessage tapbacks: associated_message_type 2000-2005 add a tapback, 3000-3005
+ * remove the same tapback. BlueBubbles may send either the code or the name.
+ */
+const REACTION_VOCABULARY = [
+    { code: 2000, name: "love", verb: "loved", noun: "love" },
+    { code: 2001, name: "like", verb: "liked", noun: "like" },
+    { code: 2002, name: "dislike", verb: "disliked", noun: "dislike" },
+    { code: 2003, name: "laugh", verb: "laughed at", noun: "laugh" },
+    { code: 2004, name: "emphasize", verb: "emphasized", noun: "emphasis" },
+    { code: 2005, name: "question", verb: "questioned", noun: "question" },
+];
+const REACTION_EXCERPT_MAX_LENGTH = 80;
+function describeBlueBubblesReaction(raw) {
+    const stripped = raw.startsWith("-") ? raw.slice(1) : raw;
+    const code = /^\d+$/.test(stripped) ? Number(stripped) : undefined;
+    const removal = raw.startsWith("-") || (code !== undefined && code >= 3000 && code < 4000);
+    const action = removal ? "remove" : "add";
+    const entry = REACTION_VOCABULARY.find((candidate) => candidate.name === stripped || candidate.code === code || candidate.code + 1000 === code);
+    if (!entry)
+        return { raw, action };
+    return { raw, action, verb: entry.verb, noun: entry.noun };
+}
+function reactionExcerpt(text) {
+    return text.length > REACTION_EXCERPT_MAX_LENGTH
+        ? `${text.slice(0, REACTION_EXCERPT_MAX_LENGTH - 3)}...`
+        : text;
+}
+function reactionTargetPhrase(target) {
+    const text = target.text?.trim();
+    if (text) {
+        const owner = target.fromMe === true ? "your" : target.fromMe === false ? "their" : "a";
+        return `${owner} message: "${reactionExcerpt(text)}"`;
+    }
+    // Never hand the agent a bare "reacted with love" stub — say plainly that the
+    // referent is missing so it can ask instead of guessing what was approved.
+    return target.guid
+        ? `an unidentified message (target guid ${target.guid}; its text could not be resolved)`
+        : "an unidentified message (the reaction carried no target message reference)";
+}
+/**
+ * Render a reaction as speech the agent can act on: what the tapback was, whether
+ * it was added or removed, and which message it points at.
+ */
+function renderBlueBubblesReactionText(reaction, target) {
+    const phrase = reactionTargetPhrase(target);
+    if (reaction.action === "remove") {
+        const noun = reaction.noun ?? reaction.raw.replace(/^-/, "");
+        return `removed their ${noun} reaction from ${phrase}`;
+    }
+    return reaction.verb
+        ? `${reaction.verb} ${phrase}`
+        : `reacted with ${reaction.raw} to ${phrase}`;
+}
 function stripPartPrefix(guid) {
     if (!guid)
         return undefined;
@@ -162,10 +223,10 @@ function stripPartPrefix(guid) {
     const marker = trimmed.lastIndexOf("/");
     return marker >= 0 ? trimmed.slice(marker + 1) : trimmed;
 }
-function buildMutationText(mutationType, data, reactionName) {
-    if (mutationType === "reaction") {
-        return `reacted with ${reactionName}`;
-    }
+// Reactions never reach here: `detectMutationType` returns "reaction" only when a
+// reaction name was decoded, and that same name produces the descriptor the caller
+// renders with `renderBlueBubblesReactionText` instead.
+function buildMutationText(mutationType, data) {
     if (mutationType === "edit") {
         const editedText = readString(data, "text")?.trim() ?? "";
         return editedText ? `edited message: ${editedText}` : "edited a message";
@@ -228,6 +289,10 @@ function normalizeBlueBubblesEvent(payload) {
     const fromMe = readBoolean(data, "isFromMe") ?? false;
     const attachments = extractAttachments(data);
     const reactionName = normalizeReactionName(data.associatedMessageType);
+    const reaction = reactionName ? describeBlueBubblesReaction(reactionName) : undefined;
+    const targetMessageGuid = reaction
+        ? stripPartPrefix(readString(data, "associatedMessageGuid"))
+        : undefined;
     const mutationType = detectMutationType(eventType, data, reactionName);
     const requiresRepair = (readBoolean(data, "hasPayloadData") ?? false) ||
         attachments.length > 0 ||
@@ -238,16 +303,17 @@ function normalizeBlueBubblesEvent(payload) {
             eventType,
             mutationType,
             messageGuid,
-            targetMessageGuid: mutationType === "reaction"
-                ? stripPartPrefix(readString(data, "associatedMessageGuid"))
-                : undefined,
+            targetMessageGuid,
             timestamp,
             fromMe,
             sender,
             chat,
             shouldNotifyAgent: mutationType === "reaction" || mutationType === "edit" || mutationType === "unsend",
-            textForAgent: buildMutationText(mutationType, data, reactionName),
+            textForAgent: reaction
+                ? renderBlueBubblesReactionText(reaction, { guid: targetMessageGuid })
+                : buildMutationText(mutationType, data),
             requiresRepair,
+            ...(reaction ? { reaction } : {}),
         }
         : {
             kind: "message",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.722",
+  "version": "0.1.0-alpha.723",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
     "cli": "dist/heart/daemon/ouro-bot-entry.js",