@ouro.bot/cli 0.1.0-alpha.527 → 0.1.0-alpha.529

package/changelog.json

@@ -1,6 +1,23 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.529",
+      "changes": [
+        "MCP agent status now asks the daemon for proof-bearing runtime health, including per-agent worker rows and enabled sense rows with proof method, proof age, failure layer, and recovery counters.",
+        "MCP status reports daemon/socket unreachability as an explicit status line instead of hiding it behind otherwise successful diary/session facts.",
+        "MCP status now includes its own package version and flags MCP-vs-daemon version mismatches so stale long-lived MCP servers are visible during reliability checks."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.528",
+      "changes": [
+        "Daemon overview health now degrades whenever an enabled sense is configured but not externally proven healthy, and `ouro up` refuses a healthy handoff when runtime senses are degraded instead of treating unreachable iMessage as green.",
+        "Managed sense health probes now carry restart ownership, so failed BlueBubbles/iMessage probes trigger daemon-managed recovery while preserving proof method, proof age, failure layer, recovery action, and pending recovery age in status surfaces.",
+        "BlueBubbles webhooks now durably capture inbound and mutation sidecars before acknowledging the HTTP request, then process the slower agent turn asynchronously so live iMessage delivery is not blocked by model/runtime latency.",
+        "MCP agent status now returns concrete runtime facts instead of terse placeholder text, giving external tools a proof-bearing status surface for Slugger and other agents."
+      ]
+    },
     {
       "version": "0.1.0-alpha.527",
       "changes": [

package/dist/heart/daemon/agent-service.js

@@ -58,6 +58,7 @@ const path = __importStar(require("path"));
 const identity_1 = require("../identity");
 const diary_1 = require("../../mind/diary");
 const runtime_1 = require("../../nerves/runtime");
+const socket_client_1 = require("./socket-client");
 /** Format diary hits the same way the search_notes tool does. */
 function formatDiaryHits(hits) {
     return hits.map((f) => `[diary] ${f.text} (source=${f.source}, createdAt=${f.createdAt})`);
@@ -149,6 +150,152 @@ function listTaskFiles(agent) {
 function emit(event, message, meta) {
     (0, runtime_1.emitNervesEvent)({ component: "daemon", event, message, meta });
 }
+function objectRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function stringValue(value) {
+    return typeof value === "string" ? value : null;
+}
+function booleanValue(value) {
+    return typeof value === "boolean" ? value : null;
+}
+function numberValue(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function readMcpRuntimeVersion() {
+    const packagePath = path.resolve(__dirname, "..", "..", "..", "package.json");
+    try {
+        const parsed = JSON.parse(fs.readFileSync(packagePath, "utf-8"));
+        return stringValue(parsed.version);
+    }
+    catch {
+        return null;
+    }
+}
+function summarizeRuntimeStatus(data, agent) {
+    const payload = objectRecord(data);
+    if (!payload)
+        return null;
+    const overview = objectRecord(payload.overview);
+    const workers = Array.isArray(payload.workers) ? payload.workers : [];
+    const senses = Array.isArray(payload.senses) ? payload.senses : [];
+    return {
+        daemonReachable: true,
+        overview: overview
+            ? {
+                daemon: stringValue(overview.daemon) ?? "unknown",
+                health: stringValue(overview.health) ?? "unknown",
+                version: stringValue(overview.version),
+                mode: stringValue(overview.mode),
+            }
+            : undefined,
+        workers: workers.flatMap((row) => {
+            const record = objectRecord(row);
+            if (!record || stringValue(record.agent) !== agent)
+                return [];
+            const worker = stringValue(record.worker);
+            const status = stringValue(record.status);
+            return worker && status ? [{ worker, status }] : [];
+        }),
+        senses: senses.flatMap((row) => {
+            const record = objectRecord(row);
+            if (!record || stringValue(record.agent) !== agent)
+                return [];
+            const sense = stringValue(record.sense);
+            const status = stringValue(record.status);
+            const enabled = booleanValue(record.enabled);
+            if (!sense || !status || enabled === null)
+                return [];
+            return [{
+                    sense,
+                    status,
+                    enabled,
+                    detail: stringValue(record.detail),
+                    proofMethod: stringValue(record.proofMethod),
+                    lastProofAt: stringValue(record.lastProofAt),
+                    proofAgeMs: numberValue(record.proofAgeMs),
+                    pendingRecoveryCount: numberValue(record.pendingRecoveryCount),
+                    failedRecoveryCount: numberValue(record.failedRecoveryCount),
+                    failureLayer: stringValue(record.failureLayer),
+                    lastFailure: stringValue(record.lastFailure),
+                    recoveryAction: stringValue(record.recoveryAction),
+                }];
+        }),
+    };
+}
+async function readRuntimeStatus(socketPath, agent) {
+    if (!socketPath)
+        return null;
+    try {
+        const response = await (0, socket_client_1.sendDaemonCommand)(socketPath, { kind: "daemon.status" });
+        if (!response.ok) {
+            return {
+                daemonReachable: false,
+                workers: [],
+                senses: [],
+                error: response.error ?? response.message ?? "daemon status did not answer cleanly",
+            };
+        }
+        return summarizeRuntimeStatus(response.data, agent);
+    }
+    catch (error) {
+        return {
+            daemonReachable: false,
+            workers: [],
+            senses: [],
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+function formatRuntimeStatusLines(runtime, mcpVersion) {
+    if (!runtime)
+        return mcpVersion ? [`mcpVersion=${mcpVersion}`] : [];
+    if (!runtime.daemonReachable) {
+        return [
+            `daemon=unreachable${runtime.error ? `\terror=${runtime.error}` : ""}`,
+            ...(mcpVersion ? [`mcpVersion=${mcpVersion}`] : []),
+        ];
+    }
+    const lines = [];
+    if (runtime.overview) {
+        const versionPart = runtime.overview.version ? `\tdaemonVersion=${runtime.overview.version}` : "";
+        const modePart = runtime.overview.mode ? `\tmode=${runtime.overview.mode}` : "";
+        const mcpVersionPart = mcpVersion ? `\tmcpVersion=${mcpVersion}` : "";
+        const mismatchPart = mcpVersion && runtime.overview.version && mcpVersion !== runtime.overview.version
+            ? `\tversionMismatch=mcp:${mcpVersion},daemon:${runtime.overview.version}`
+            : "";
+        lines.push(`daemon=${runtime.overview.daemon}\thealth=${runtime.overview.health}${versionPart}${modePart}${mcpVersionPart}${mismatchPart}`);
+    }
+    for (const worker of runtime.workers) {
+        lines.push(`worker=${worker.worker}:${worker.status}`);
+    }
+    for (const sense of runtime.senses) {
+        const detailPart = sense.detail ? `\tdetail=${sense.detail}` : "";
+        const proofPart = sense.proofMethod ? `\tproof=${sense.proofMethod}` : "";
+        const lastProofPart = sense.lastProofAt ? `\tlastProofAt=${sense.lastProofAt}` : "";
+        const proofAgePart = sense.proofAgeMs !== null ? `\tproofAgeMs=${sense.proofAgeMs}` : "";
+        const pendingPart = sense.pendingRecoveryCount !== null ? `\tpendingRecovery=${sense.pendingRecoveryCount}` : "";
+        const failedPart = sense.failedRecoveryCount !== null ? `\tfailedRecovery=${sense.failedRecoveryCount}` : "";
+        const failureLayerPart = sense.failureLayer ? `\tfailureLayer=${sense.failureLayer}` : "";
+        const failurePart = sense.lastFailure ? `\tlastFailure=${sense.lastFailure}` : "";
+        const recoveryPart = sense.recoveryAction ? `\trecovery=${sense.recoveryAction}` : "";
+        lines.push(`sense=${sense.sense}:${sense.enabled ? sense.status : "disabled"}`
+            + detailPart
+            + proofPart
+            + lastProofPart
+            + proofAgePart
+            + pendingPart
+            + failedPart
+            + failureLayerPart
+            + failurePart
+            + recoveryPart);
+    }
+    if (lines.length === 0 && mcpVersion)
+        lines.push(`mcpVersion=${mcpVersion}`);
+    return lines;
+}
 // ─── Handlers ────────────────────────────────────────────────────────────────
 async function handleAgentStatus(params) {
     (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.agent_service_start", message: "handling agent.status", meta: { agent: params.agent } });
@@ -156,17 +303,32 @@ async function handleAgentStatus(params) {
     const facts = (0, diary_1.readDiaryEntries)(diaryRoot);
     const innerStatus = readInnerDialogStatus(params.agent);
     const sessions = enumerateSessions(params.agent);
+    const mcpVersion = readMcpRuntimeVersion();
+    const runtime = await readRuntimeStatus(params.socketPath ?? socket_client_1.DEFAULT_DAEMON_SOCKET_PATH, params.agent);
     emit("daemon.agent_service_end", "completed agent.status", { agent: params.agent });
+    const innerStatusValue = innerStatus?.status ?? "unknown";
+    const lastThoughtAt = innerStatus?.lastCompletedAt ?? null;
+    const agentLine = [
+        `agent=${params.agent}`,
+        `innerStatus=${innerStatusValue}`,
+        `lastThoughtAt=${lastThoughtAt ?? "never"}`,
+        `sessionCount=${sessions.length}`,
+        `diaryEntries=${facts.length}`,
+    ].join("\t");
+    const runtimeLines = formatRuntimeStatusLines(runtime, mcpVersion);
+    const message = [agentLine, ...runtimeLines].join("\n");
     return {
         ok: true,
-        message: `Agent ${params.agent} status`,
+        message,
         data: {
             agent: params.agent,
-            innerStatus: innerStatus?.status ?? "unknown",
-            lastThoughtAt: innerStatus?.lastCompletedAt ?? null,
+            innerStatus: innerStatusValue,
+            lastThoughtAt,
             sessionCount: sessions.length,
             hasDiaryEntries: facts.length > 0,
             factCount: facts.length,
+            runtime,
+            mcpVersion,
         },
     };
 }

package/dist/heart/daemon/cli-exec.js

@@ -621,7 +621,7 @@ function finalDaemonFailureMessage(deps, reason) {
     lines.push("Run `ouro up` again or `ouro doctor` for a deeper diagnosis.");
     return lines.join("\n");
 }
-async function verifyDaemonReadyForHandoff(deps) {
+async function verifyDaemonReadyForHandoff(deps, options = {}) {
     const socketAlive = await deps.checkSocketAlive(deps.socketPath);
     if (!socketAlive) {
         return {
@@ -654,6 +654,23 @@ async function verifyDaemonReadyForHandoff(deps) {
                 message: finalDaemonFailureMessage(deps, `the daemon reported state ${payload.overview.daemon}`),
             };
         }
+        if (payload.overview.health !== "ok") {
+            const degradedSenses = payload.senses
+                .filter((sense) => sense.enabled && !["running", "interactive", "disabled", "not_attached"].includes(sense.status))
+                .map((sense) => `${sense.agent}/${sense.sense}: ${sense.status} - ${sense.detail}`);
+            const detail = degradedSenses.length > 0 ? `; ${degradedSenses.join("; ")}` : "";
+            if (options.allowDegradedHealth) {
+                return {
+                    ok: true,
+                    summary: `runtime health ${payload.overview.health}`,
+                };
+            }
+            return {
+                ok: false,
+                summary: `daemon health ${payload.overview.health}`,
+                message: finalDaemonFailureMessage(deps, `runtime health is ${payload.overview.health}${detail}`),
+            };
+        }
         const workerCount = payload.workers.length;
         return {
             ok: true,
@@ -5863,7 +5880,10 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
         daemonResult.stability = mergeStartupStability(daemonResult.stability, providerDegraded);
         progress.completePhase("provider checks", providerRepairCountSummary(providerDegraded.length));
         progress.startPhase("final daemon check");
-        const finalDaemonCheck = await verifyDaemonReadyForHandoff(deps);
+        const finalDaemonCheck = await verifyDaemonReadyForHandoff(deps, {
+            allowDegradedHealth: Boolean(command.noRepair
+                && ((daemonResult.stability?.degraded.length ?? 0) > 0 || providerDegraded.length > 0)),
+        });
         if (!finalDaemonCheck.ok) {
             ;
             progress.failPhase?.("final daemon check", finalDaemonCheck.summary);

package/dist/heart/daemon/cli-render.js

@@ -66,6 +66,50 @@ function numberField(value) {
 function booleanField(value) {
     return typeof value === "boolean" ? value : null;
 }
+function formatDurationMs(ms) {
+    if (ms < 1_000)
+        return `${Math.round(ms)}ms`;
+    if (ms < 60_000)
+        return `${Math.round(ms / 1_000)}s`;
+    if (ms < 3_600_000)
+        return `${Math.round(ms / 60_000)}m`;
+    if (ms < 86_400_000)
+        return `${Math.round(ms / 3_600_000)}h`;
+    return `${Math.round(ms / 86_400_000)}d`;
+}
+function formatSenseDetail(row) {
+    const details = [row.detail];
+    const proofParts = [];
+    if (row.proofMethod)
+        proofParts.push(`proof=${row.proofMethod}`);
+    if (row.lastProofAt)
+        proofParts.push(`lastProof=${row.lastProofAt}`);
+    if (row.proofAgeMs !== undefined)
+        proofParts.push(`proofAge=${formatDurationMs(row.proofAgeMs)}`);
+    if (proofParts.length > 0)
+        details.push(proofParts.join(" "));
+    const recoveryParts = [];
+    if (row.pendingRecoveryCount !== undefined)
+        recoveryParts.push(`pendingRecovery=${row.pendingRecoveryCount}`);
+    if (row.failedRecoveryCount !== undefined)
+        recoveryParts.push(`failedRecovery=${row.failedRecoveryCount}`);
+    if (row.oldestPendingRecoveryAt)
+        recoveryParts.push(`oldestPending=${row.oldestPendingRecoveryAt}`);
+    if (row.oldestPendingRecoveryAgeMs !== undefined)
+        recoveryParts.push(`oldestPendingAge=${formatDurationMs(row.oldestPendingRecoveryAgeMs)}`);
+    if (recoveryParts.length > 0)
+        details.push(recoveryParts.join(" "));
+    const failureParts = [];
+    if (row.failureLayer)
+        failureParts.push(`failureLayer=${row.failureLayer}`);
+    if (row.lastFailure)
+        failureParts.push(`lastFailure=${row.lastFailure}`);
+    if (row.recoveryAction)
+        failureParts.push(`recovery=${row.recoveryAction}`);
+    if (failureParts.length > 0)
+        details.push(failureParts.join(" "));
+    return details.filter(Boolean).join("; ");
+}
 // ── Parsers ──
 function parseStatusPayload(data) {
     if (!data || typeof data !== "object" || Array.isArray(data))
@@ -116,7 +160,7 @@ function parseStatusPayload(data) {
         const enabled = booleanField(row.enabled);
         if (!agent || !sense || !status || detail === null || enabled === null)
             return null;
-        return {
+        const parsed = {
             agent,
             sense,
             label: stringField(row.label) ?? undefined,
@@ -124,6 +168,37 @@ function parseStatusPayload(data) {
             status,
             detail,
         };
+        const proofMethod = stringField(row.proofMethod);
+        const lastProofAt = stringField(row.lastProofAt);
+        const proofAgeMs = numberField(row.proofAgeMs);
+        const lastFailure = stringField(row.lastFailure);
+        const failureLayer = stringField(row.failureLayer);
+        const recoveryAction = stringField(row.recoveryAction);
+        const pendingRecoveryCount = numberField(row.pendingRecoveryCount);
+        const failedRecoveryCount = numberField(row.failedRecoveryCount);
+        const oldestPendingRecoveryAt = stringField(row.oldestPendingRecoveryAt);
+        const oldestPendingRecoveryAgeMs = numberField(row.oldestPendingRecoveryAgeMs);
+        if (proofMethod !== null)
+            parsed.proofMethod = proofMethod;
+        if (lastProofAt !== null)
+            parsed.lastProofAt = lastProofAt;
+        if (proofAgeMs !== null)
+            parsed.proofAgeMs = proofAgeMs;
+        if (lastFailure !== null)
+            parsed.lastFailure = lastFailure;
+        if (failureLayer !== null)
+            parsed.failureLayer = failureLayer;
+        if (recoveryAction !== null)
+            parsed.recoveryAction = recoveryAction;
+        if (pendingRecoveryCount !== null)
+            parsed.pendingRecoveryCount = pendingRecoveryCount;
+        if (failedRecoveryCount !== null)
+            parsed.failedRecoveryCount = failedRecoveryCount;
+        if (oldestPendingRecoveryAt !== null)
+            parsed.oldestPendingRecoveryAt = oldestPendingRecoveryAt;
+        if (oldestPendingRecoveryAgeMs !== null)
+            parsed.oldestPendingRecoveryAgeMs = oldestPendingRecoveryAgeMs;
+        return parsed;
     });
     const parsedWorkers = workers.map((entry) => {
         if (!entry || typeof entry !== "object" || Array.isArray(entry))
@@ -364,7 +439,7 @@ function formatDaemonStatusOutput(response, fallback) {
                 const name = humanizeSenseName(row.sense, row.label).padEnd(nameWidth);
                 const dot = row.enabled ? statusDot(row.status) : dim("○");
                 const statusText = (row.enabled ? row.status : "disabled").padEnd(statusWidth);
-                lines.push(`    ${name} ${dot} ${statusText}  ${dim(row.detail)}`);
+                lines.push(`    ${name} ${dot} ${statusText}  ${dim(formatSenseDetail(row))}`);
             }
         }
         lines.push("");

package/dist/heart/daemon/daemon-entry.js

@@ -148,6 +148,13 @@ const healthMonitor = new health_monitor_1.HealthMonitor({
         }
         catch { /* recovery is best-effort */ }
     },
+    /* v8 ignore next 3 -- wiring: delegates to senseManager.restartSense which has focused tests @preserve */
+    onCriticalSense: (managedName) => {
+        try {
+            void senseManager.restartSense(managedName);
+        }
+        catch { /* recovery is best-effort */ }
+    },
 });
 const habitSchedulers = [];
 let entryRuntimeStopping = false;

package/dist/heart/daemon/daemon.js

@@ -345,17 +345,46 @@ function buildWorkerRows(snapshots) {
         fixHint: snapshot.fixHint ?? null,
     }));
 }
+function unhealthySenseRows(senses) {
+    return senses.filter((row) => {
+        if (!row.enabled)
+            return false;
+        if (row.status === "disabled" || row.status === "not_attached")
+            return false;
+        if (row.status === "interactive" || row.status === "running")
+            return false;
+        return true;
+    });
+}
+function overviewHealth(workers, senses) {
+    if (!workers.every((worker) => worker.status === "running"))
+        return "warn";
+    if (unhealthySenseRows(senses).length > 0)
+        return "warn";
+    return "ok";
+}
 function formatStatusSummary(payload) {
     if (payload.overview.workerCount === 0 && payload.overview.senseCount === 0) {
         return "no managed agents";
     }
-    const rows = [
-        ...payload.workers.map((row) => `${row.agent}/${row.worker}:${row.status}`),
-        ...payload.senses
-            .filter((row) => row.enabled)
-            .map((row) => `${row.agent}/${row.sense}:${row.status}`),
+    const degraded = [
+        ...payload.workers
+            .filter((row) => row.status !== "running")
+            .map((row) => `worker:${row.agent}/${row.worker}:${row.status}`),
+        ...unhealthySenseRows(payload.senses)
+            .map((row) => `sense:${row.agent}/${row.sense}:${row.status}`),
     ];
-    const detail = rows.length > 0 ? `\titems=${rows.join(",")}` : "";
+    const detail = degraded.length > 0 ? `\tdegraded=${degraded.join(",")}` : "";
+    if (!detail) {
+        const rows = [
+            ...payload.workers.map((row) => `${row.agent}/${row.worker}:${row.status}`),
+            ...payload.senses
+                .filter((row) => row.enabled)
+                .map((row) => `${row.agent}/${row.sense}:${row.status}`),
+        ];
+        const items = rows.length > 0 ? `\titems=${rows.join(",")}` : "";
+        return `daemon=${payload.overview.daemon}\tworkers=${payload.overview.workerCount}\tsenses=${payload.overview.senseCount}\thealth=${payload.overview.health}${items}`;
+    }
     return `daemon=${payload.overview.daemon}\tworkers=${payload.overview.workerCount}\tsenses=${payload.overview.senseCount}\thealth=${payload.overview.health}${detail}`;
 }
 function parseIncomingCommand(raw) {
@@ -480,7 +509,7 @@ class OuroDaemon {
         return {
             overview: {
                 daemon: "running",
-                health: workers.every((worker) => worker.status === "running") ? "ok" : "warn",
+                health: overviewHealth(workers, senses),
                 socketPath: this.socketPath,
                 mailboxUrl,
                 outlookUrl: mailboxUrl,

package/dist/heart/daemon/health-monitor.js

@@ -8,6 +8,7 @@ class HealthMonitor {
     alertSink;
     diskUsagePercent;
     onCriticalAgent;
+    onCriticalSense;
     senseProbes;
     senseProbeProvider;
     intervalHandle = null;
@@ -17,9 +18,31 @@ class HealthMonitor {
         this.alertSink = options.alertSink ?? (() => undefined);
         this.diskUsagePercent = options.diskUsagePercent ?? (() => 0);
         this.onCriticalAgent = options.onCriticalAgent ?? (() => undefined);
+        this.onCriticalSense = options.onCriticalSense ?? (() => undefined);
         this.senseProbes = options.senseProbes ?? [];
         this.senseProbeProvider = options.senseProbeProvider ?? (() => []);
     }
+    triggerSenseRecovery(probe, detail) {
+        if (!probe.managedName)
+            return;
+        try {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "daemon",
+                event: "daemon.health_check_sense_recovery_attempted",
+                message: "triggering recovery restart for failed sense probe",
+                meta: {
+                    probeName: probe.name,
+                    managedName: probe.managedName,
+                    detail,
+                },
+            });
+            this.onCriticalSense(probe.managedName, probe.name);
+        }
+        catch {
+            // Recovery is best-effort -- callback errors must not crash runChecks
+        }
+    }
     startPeriodicChecks(intervalMs) {
         if (this.intervalHandle !== null)
             return;
@@ -137,6 +160,7 @@ class HealthMonitor {
                     });
                 }
                 else {
+                    this.triggerSenseRecovery(probe, outcome.detail ?? "unknown");
                     results.push({
                         name: `sense-probe:${probe.name}`,
                         status: "critical",
@@ -145,6 +169,7 @@ class HealthMonitor {
                 }
             }
             catch (error) {
+                this.triggerSenseRecovery(probe, error instanceof Error ? error.message : String(error));
                 results.push({
                     name: `sense-probe:${probe.name}`,
                     status: "critical",

package/dist/heart/daemon/sense-manager.js

@@ -266,12 +266,19 @@ function readBlueBubblesRuntimeJson(runtimePath) {
                 ? parsed.detail
                 : "startup health probe pending",
             lastCheckedAt: typeof parsed.lastCheckedAt === "string" ? parsed.lastCheckedAt : undefined,
+            proofMethod: typeof parsed.proofMethod === "string" && parsed.proofMethod.trim()
+                ? parsed.proofMethod
+                : undefined,
             pendingRecoveryCount: typeof parsed.pendingRecoveryCount === "number" && Number.isFinite(parsed.pendingRecoveryCount)
                 ? parsed.pendingRecoveryCount
                 : 0,
             failedRecoveryCount: typeof parsed.failedRecoveryCount === "number" && Number.isFinite(parsed.failedRecoveryCount)
                 ? parsed.failedRecoveryCount
                 : 0,
+            oldestPendingRecoveryAt: typeof parsed.oldestPendingRecoveryAt === "string" ? parsed.oldestPendingRecoveryAt : undefined,
+            oldestPendingRecoveryAgeMs: typeof parsed.oldestPendingRecoveryAgeMs === "number" && Number.isFinite(parsed.oldestPendingRecoveryAgeMs)
+                ? parsed.oldestPendingRecoveryAgeMs
+                : undefined,
         };
         /* v8 ignore stop */
         /* v8 ignore start -- defensive: catch for missing/corrupt BB runtime state file @preserve */
@@ -288,34 +295,66 @@ function readBlueBubblesRuntimeFacts(agent, bundlesRoot, snapshot) {
         return { runtime: snapshot?.runtime };
     }
     const state = readBlueBubblesRuntimeJson(runtimePath);
+    const checkedAtMs = state.lastCheckedAt ? Date.parse(state.lastCheckedAt) : Number.NaN;
+    const proofFacts = {
+        proofMethod: state.proofMethod ?? "bluebubbles.checkHealth",
+        lastProofAt: state.lastCheckedAt,
+        proofAgeMs: Number.isFinite(checkedAtMs) ? Math.max(0, Date.now() - checkedAtMs) : undefined,
+        pendingRecoveryCount: state.pendingRecoveryCount,
+        failedRecoveryCount: state.failedRecoveryCount,
+        oldestPendingRecoveryAt: state.oldestPendingRecoveryAt,
+        oldestPendingRecoveryAgeMs: state.oldestPendingRecoveryAgeMs,
+    };
     if (!blueBubblesRuntimeStateIsFresh(state.lastCheckedAt)) {
-        return { runtime: snapshot?.runtime };
+        return {
+            runtime: snapshot?.runtime,
+            lastFailure: state.lastCheckedAt ? "BlueBubbles proof is stale" : undefined,
+            failureLayer: state.lastCheckedAt ? "proof_freshness" : undefined,
+        };
     }
     if (snapshot?.runtime !== "running") {
         return {
             runtime: "error",
             detail: "BlueBubbles listener is not running",
+            ...proofFacts,
+            lastFailure: "listener process is not running",
+            failureLayer: "listener",
+            recoveryAction: "daemon health monitor will restart the BlueBubbles listener when its probe fails",
         };
     }
     if (state.upstreamStatus === "error") {
         return {
             runtime: "error",
             detail: state.detail,
+            ...proofFacts,
+            lastFailure: state.detail,
+            failureLayer: "upstream",
+            recoveryAction: "verify BlueBubbles server/app auth and local machine attachment, then retry the listener",
         };
     }
     if (state.pendingRecoveryCount > 0) {
         return {
             runtime: "error",
             detail: state.detail,
+            ...proofFacts,
+            lastFailure: state.detail,
+            failureLayer: "recovery_queue",
+            recoveryAction: "queued recovery will retry; inspect BlueBubbles inbound/recovery sidecar logs if age keeps growing",
         };
     }
     if (state.upstreamStatus === "ok") {
         return {
             runtime: "running",
+            ...proofFacts,
             ...(state.failedRecoveryCount > 0 ? { detail: state.detail } : {}),
+            ...(state.failedRecoveryCount > 0 ? {
+                lastFailure: state.detail,
+                failureLayer: "recovery_quarantine",
+                recoveryAction: "inspect quarantined BlueBubbles recovery failures; live transport remains reachable",
+            } : {}),
         };
     }
-    return { runtime: snapshot?.runtime };
+    return { runtime: snapshot?.runtime, ...proofFacts };
 }
 class DaemonSenseManager {
     processManager;
@@ -467,10 +506,20 @@ class DaemonSenseManager {
             const machinePayload = machineRuntimeConfig.config;
             const bluebubblesChannel = machinePayload.bluebubblesChannel;
             const port = numberField(bluebubblesChannel, "port", DEFAULT_BLUEBUBBLES_PORT);
-            probes.push((0, http_health_probe_1.createHttpHealthProbe)(`bluebubbles:${agent}`, port));
+            probes.push({
+                ...(0, http_health_probe_1.createHttpHealthProbe)(`bluebubbles:${agent}`, port),
+                managedName: `${agent}:bluebubbles`,
+            });
         }
         return probes;
     }
+    async restartSense(managedName) {
+        if (this.processManager.restartAgent) {
+            await this.processManager.restartAgent(managedName);
+            return;
+        }
+        await this.processManager.startAgent?.(managedName);
+    }
     listSenseRows() {
         const runtime = new Map();
         for (const snapshot of this.processManager.listAgentSnapshots()) {
@@ -513,6 +562,18 @@ class DaemonSenseManager {
                             ?? context.facts[entry.sense].detail
                         : context.facts[entry.sense].detail
                     : "not enabled in agent.json",
+                ...(entry.sense === "bluebubbles" ? {
+                    proofMethod: blueBubblesRuntimeFacts.proofMethod,
+                    lastProofAt: blueBubblesRuntimeFacts.lastProofAt,
+                    proofAgeMs: blueBubblesRuntimeFacts.proofAgeMs,
+                    lastFailure: blueBubblesRuntimeFacts.lastFailure,
+                    failureLayer: blueBubblesRuntimeFacts.failureLayer,
+                    recoveryAction: blueBubblesRuntimeFacts.recoveryAction,
+                    pendingRecoveryCount: blueBubblesRuntimeFacts.pendingRecoveryCount,
+                    failedRecoveryCount: blueBubblesRuntimeFacts.failedRecoveryCount,
+                    oldestPendingRecoveryAt: blueBubblesRuntimeFacts.oldestPendingRecoveryAt,
+                    oldestPendingRecoveryAgeMs: blueBubblesRuntimeFacts.oldestPendingRecoveryAgeMs,
+                } : {}),
             }));
         });
         (0, runtime_1.emitNervesEvent)({

package/dist/heart/mcp/mcp-server.js

@@ -425,7 +425,7 @@ function createMcpServer(options) {
         if (serviceHandler && typeof agentService[serviceHandler] === "function") {
             const handlerFn = agentService[serviceHandler];
             try {
-                response = await handlerFn({ agent, friendId, ...toolArgs });
+                response = await handlerFn({ agent, friendId, socketPath, ...toolArgs });
             }
             catch (error) {
                 const errorMessage = error instanceof Error ? error.message : String(error);

package/dist/senses/bluebubbles/index.js

@@ -1239,6 +1239,9 @@ function countPendingRecoveryCandidates(agentName) {
         .length;
 }
 function countPendingCapturedInboundMessages(agentName) {
+    return listPendingCapturedInboundMessages(agentName).length;
+}
+function listPendingCapturedInboundMessages(agentName) {
     const seenMessageGuids = new Set();
     return (0, inbound_log_1.listRecordedBlueBubblesInbound)(agentName)
         .filter((entry) => {
@@ -1247,8 +1250,7 @@ function countPendingCapturedInboundMessages(agentName) {
         seenMessageGuids.add(entry.messageGuid);
         return true;
     })
-        .filter((entry) => !(0, processed_log_1.hasProcessedBlueBubblesMessage)(agentName, entry.sessionKey, entry.messageGuid))
-        .length;
+        .filter((entry) => !(0, processed_log_1.hasProcessedBlueBubblesMessage)(agentName, entry.sessionKey, entry.messageGuid));
 }
 function parseTimestampMs(value) {
     if (!value)
@@ -1273,6 +1275,23 @@ function formatBlueBubblesRuntimeDetail(queued, failed) {
         return `${failed} message(s) unrecoverable this cycle; upstream ok`;
     return "upstream reachable";
 }
+function blueBubblesPendingRecoverySnapshot(agentName, nowMs = Date.now()) {
+    const pendingRecordedAt = [
+        ...listPendingCapturedInboundMessages(agentName).map((entry) => entry.recordedAt),
+        ...(0, mutation_log_1.listBlueBubblesRecoveryCandidates)(agentName)
+            .filter((entry) => !(0, processed_log_1.hasProcessedBlueBubblesMessage)(agentName, entry.sessionKey, entry.messageGuid))
+            .map((entry) => entry.recordedAt),
+    ]
+        .map((value) => ({ value, ms: Date.parse(value) }))
+        .filter((entry) => Number.isFinite(entry.ms))
+        .sort((left, right) => left.ms - right.ms);
+    const oldest = pendingRecordedAt[0];
+    return {
+        pendingRecoveryCount: countPendingCapturedInboundMessages(agentName) + countPendingRecoveryCandidates(agentName),
+        oldestPendingRecoveryAt: oldest?.value,
+        oldestPendingRecoveryAgeMs: oldest ? Math.max(0, nowMs - oldest.ms) : undefined,
+    };
+}
 async function syncBlueBubblesRuntime(deps = {}) {
     const resolvedDeps = { ...defaultDeps, ...deps };
     const agentName = resolvedDeps.getAgentName();
@@ -1281,13 +1300,13 @@ async function syncBlueBubblesRuntime(deps = {}) {
     const previousState = (0, runtime_state_1.readBlueBubblesRuntimeState)(agentName);
     try {
         await client.checkHealth();
-        const capturedPending = countPendingCapturedInboundMessages(agentName);
-        const recoveryPending = countPendingRecoveryCandidates(agentName);
+        const pendingBeforeCatchup = blueBubblesPendingRecoverySnapshot(agentName);
         (0, runtime_state_1.writeBlueBubblesRuntimeState)(agentName, {
             upstreamStatus: "ok",
             detail: "upstream reachable; recovery pass running",
             lastCheckedAt: checkedAt,
-            pendingRecoveryCount: capturedPending + recoveryPending,
+            proofMethod: "bluebubbles.checkHealth",
+            ...pendingBeforeCatchup,
             lastRecoveredAt: previousState.lastRecoveredAt,
             lastRecoveredMessageGuid: previousState.lastRecoveredMessageGuid,
         });
@@ -1295,7 +1314,8 @@ async function syncBlueBubblesRuntime(deps = {}) {
             processTurns: false,
         });
         const failed = catchUp.failed;
-        const queued = capturedPending + recoveryPending + (catchUp.queued ?? 0);
+        const pendingAfterCatchup = blueBubblesPendingRecoverySnapshot(agentName);
+        const queued = pendingAfterCatchup.pendingRecoveryCount;
         // upstreamStatus reflects whether BlueBubbles itself and the local bridge
         // can answer webhook traffic. The daemon status layer treats
         // pendingRecoveryCount as unhealthy for user-facing iMessage reachability,
@@ -1304,6 +1324,8 @@ async function syncBlueBubblesRuntime(deps = {}) {
             upstreamStatus: "ok",
             detail: formatBlueBubblesRuntimeDetail(queued, failed),
             lastCheckedAt: checkedAt,
+            proofMethod: "bluebubbles.checkHealth",
+            ...pendingAfterCatchup,
             pendingRecoveryCount: queued,
             failedRecoveryCount: failed,
             lastRecoveredAt: previousState.lastRecoveredAt,
@@ -1315,7 +1337,8 @@ async function syncBlueBubblesRuntime(deps = {}) {
             upstreamStatus: "error",
             detail: error instanceof Error ? error.message : String(error),
             lastCheckedAt: checkedAt,
-            pendingRecoveryCount: countPendingCapturedInboundMessages(agentName) + countPendingRecoveryCandidates(agentName),
+            proofMethod: "bluebubbles.checkHealth",
+            ...blueBubblesPendingRecoverySnapshot(agentName),
             failedRecoveryCount: 0,
         });
     }
@@ -1324,13 +1347,14 @@ async function recoverQueuedBlueBubblesMessages(deps = {}) {
     const resolvedDeps = { ...defaultDeps, ...deps };
     const agentName = resolvedDeps.getAgentName();
     const previousState = (0, runtime_state_1.readBlueBubblesRuntimeState)(agentName);
-    const initialPending = countPendingCapturedInboundMessages(agentName) + countPendingRecoveryCandidates(agentName);
+    const initialPending = blueBubblesPendingRecoverySnapshot(agentName).pendingRecoveryCount;
     if (initialPending === 0) {
         return { recovered: 0, skipped: 0, failed: 0, pendingRecoveryCount: 0 };
     }
     const captured = await recoverCapturedBlueBubblesInboundMessages(resolvedDeps);
     const recovery = await recoverMissedBlueBubblesMessages(resolvedDeps);
-    const pendingRecoveryCount = countPendingCapturedInboundMessages(agentName) + countPendingRecoveryCandidates(agentName);
+    const pendingSnapshot = blueBubblesPendingRecoverySnapshot(agentName);
+    const pendingRecoveryCount = pendingSnapshot.pendingRecoveryCount;
     const failed = captured.failed + recovery.failed;
     const recovered = captured.recovered + recovery.recovered;
     const skipped = captured.skipped + recovery.skipped;
@@ -1341,7 +1365,8 @@ async function recoverQueuedBlueBubblesMessages(deps = {}) {
             upstreamStatus: "ok",
             detail: formatBlueBubblesRuntimeDetail(pendingRecoveryCount, failed),
             lastCheckedAt: checkedAt,
-            pendingRecoveryCount,
+            proofMethod: "bluebubbles.checkHealth",
+            ...pendingSnapshot,
             failedRecoveryCount: failed,
             lastRecoveredAt: recovered > 0 ? checkedAt : previousState.lastRecoveredAt,
             lastRecoveredMessageGuid: previousState.lastRecoveredMessageGuid,
@@ -1352,7 +1377,8 @@ async function recoverQueuedBlueBubblesMessages(deps = {}) {
             upstreamStatus: "error",
             detail: error instanceof Error ? error.message : String(error),
             lastCheckedAt: checkedAt,
-            pendingRecoveryCount,
+            proofMethod: "bluebubbles.checkHealth",
+            ...pendingSnapshot,
             failedRecoveryCount: failed,
             lastRecoveredAt: recovered > 0 ? checkedAt : previousState.lastRecoveredAt,
             lastRecoveredMessageGuid: previousState.lastRecoveredMessageGuid,
@@ -1691,24 +1717,85 @@ function createBlueBubblesWebhookHandler(deps = {}) {
             writeJson(res, 400, { error: "Invalid JSON body" });
             return;
         }
+        let normalized;
         try {
-            const result = await handleBlueBubblesEvent(payload, deps);
-            writeJson(res, 200, result);
+            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,
+                    },
+                });
+                writeJson(res, 200, {
+                    handled: true,
+                    notifiedAgent: false,
+                    reason: "ignored",
+                });
+                return;
+            }
             (0, runtime_1.emitNervesEvent)({
                 level: "error",
                 component: "senses",
                 event: "senses.bluebubbles_webhook_error",
                 message: "bluebubbles webhook handling failed",
                 meta: {
+                    /* v8 ignore next -- normalizeBlueBubblesEvent throws Error subclasses; String fallback is defensive @preserve */
                     reason: error instanceof Error ? error.message : String(error),
                 },
             });
             writeJson(res, 500, {
+                /* v8 ignore next -- normalizeBlueBubblesEvent throws Error subclasses; String fallback is defensive @preserve */
                 error: error instanceof Error ? error.message : String(error),
             });
+            return;
+        }
+        const resolvedDeps = { ...defaultDeps, ...deps };
+        if (normalized.kind === "message" && !normalized.fromMe) {
+            (0, inbound_log_1.recordBlueBubblesInbound)(resolvedDeps.getAgentName(), normalized, "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),
+                    },
+                });
+            }
+        }
+        writeJson(res, 200, {
+            handled: true,
+            notifiedAgent: false,
+            kind: normalized.kind,
+            queued: true,
+            reason: "queued",
+        });
+        setTimeout(() => {
+            void handleBlueBubblesEvent(payload, deps).catch((error) => {
+                (0, runtime_1.emitNervesEvent)({
+                    level: "error",
+                    component: "senses",
+                    event: "senses.bluebubbles_webhook_async_error",
+                    message: "bluebubbles webhook async handling failed after durable capture",
+                    meta: {
+                        reason: error instanceof Error ? error.message : String(error),
+                    },
+                });
+            });
+        }, 0);
     };
 }
 function findImessageHandle(friend) {

package/dist/senses/bluebubbles/runtime-state.js

@@ -64,10 +64,19 @@ function readBlueBubblesRuntimeState(agentName, agentRoot) {
                 ? parsed.detail
                 : DEFAULT_RUNTIME_STATE.detail,
             lastCheckedAt: typeof parsed.lastCheckedAt === "string" ? parsed.lastCheckedAt : undefined,
+            proofMethod: typeof parsed.proofMethod === "string" && parsed.proofMethod.trim()
+                ? parsed.proofMethod
+                : undefined,
             pendingRecoveryCount: typeof parsed.pendingRecoveryCount === "number" && Number.isFinite(parsed.pendingRecoveryCount)
                 ? parsed.pendingRecoveryCount
                 : 0,
             ...(typeof failedRecoveryCount === "number" ? { failedRecoveryCount } : {}),
+            oldestPendingRecoveryAt: typeof parsed.oldestPendingRecoveryAt === "string"
+                ? parsed.oldestPendingRecoveryAt
+                : undefined,
+            oldestPendingRecoveryAgeMs: typeof parsed.oldestPendingRecoveryAgeMs === "number" && Number.isFinite(parsed.oldestPendingRecoveryAgeMs)
+                ? parsed.oldestPendingRecoveryAgeMs
+                : undefined,
             lastRecoveredAt: typeof parsed.lastRecoveredAt === "string" ? parsed.lastRecoveredAt : undefined,
             lastRecoveredMessageGuid: typeof parsed.lastRecoveredMessageGuid === "string"
                 ? parsed.lastRecoveredMessageGuid

package/package.json

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