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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arye Mendelow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/changelog.json

@@ -1,6 +1,18 @@
 {
   "_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.722",
+      "changes": [
+        "ouro doctor now asserts pipeline liveness (mail ingest age, sense inbound-delivery age) so a configured-but-dead pipe fails loudly instead of reporting healthy."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.721",
+      "changes": [
+        "Make Slugger context hydration and native habit traces inspectable and coverage-gated."
+      ]
+    },
     {
       "version": "0.1.0-alpha.720",
       "changes": [

package/dist/arc/flight-recorder.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isHabitRunTrigger = isHabitRunTrigger;
 exports.flightRecorderLatestPath = flightRecorderLatestPath;
+exports.decisionsFromHabitRunTraceSteps = decisionsFromHabitRunTraceSteps;
 exports.isFlightRecorderResume = isFlightRecorderResume;
 exports.readFlightRecorderResume = readFlightRecorderResume;
 exports.writeFlightRecorderResume = writeFlightRecorderResume;
@@ -86,6 +87,17 @@ function atomicWriteJson(filePath, value) {
 function cappedArray(values) {
     return values.map((value) => (0, session_events_1.capStructuredRecordString)(value));
 }
+function decisionsFromHabitRunTraceSteps(traceSteps = []) {
+    const decisions = [];
+    for (const step of traceSteps) {
+        for (const decision of step.decisions ?? []) {
+            const trimmed = decision.trim();
+            if (trimmed.length > 0)
+                decisions.push((0, session_events_1.capStructuredRecordString)(trimmed));
+        }
+    }
+    return uniqueStrings(decisions);
+}
 function normalizeEvent(input) {
     const recordedAt = input.recordedAt ?? new Date().toISOString();
     return {
@@ -604,6 +616,55 @@ function isHabitSurfaceAttemptArray(value) {
             && (entry.rawStatus === undefined || typeof entry.rawStatus === "string")
             && (entry.error === undefined || typeof entry.error === "string"));
 }
+function isHabitRunTraceStepKind(value) {
+    return value === "trigger"
+        || value === "habit_definition"
+        || value === "fetch"
+        || value === "snapshot"
+        || value === "render"
+        || value === "decision"
+        || value === "produced_ref"
+        || value === "surface_attempt"
+        || value === "send"
+        || value === "ledger"
+        || value === "error"
+        || value === "complete";
+}
+function isHabitRunTraceStepStatus(value) {
+    return value === "started"
+        || value === "succeeded"
+        || value === "skipped"
+        || value === "blocked"
+        || value === "failed";
+}
+function isHabitRunTraceRefArray(value) {
+    return Array.isArray(value)
+        && value.every((entry) => isPlainRecord(entry)
+            && typeof entry.kind === "string"
+            && entry.kind.trim().length > 0
+            && typeof entry.locator === "string"
+            && entry.locator.trim().length > 0
+            && (entry.label === undefined || typeof entry.label === "string"));
+}
+function isHabitRunTraceStepArray(value) {
+    return Array.isArray(value)
+        && value.every((entry) => isPlainRecord(entry)
+            && entry.schemaVersion === 1
+            && typeof entry.stepId === "string"
+            && entry.stepId.trim().length > 0
+            && isHabitRunTraceStepKind(entry.kind)
+            && isHabitRunTraceStepStatus(entry.status)
+            && typeof entry.at === "string"
+            && entry.at.trim().length > 0
+            && typeof entry.summary === "string"
+            && entry.summary.trim().length > 0
+            && (entry.refs === undefined || isHabitRunTraceRefArray(entry.refs))
+            && (entry.producedRefs === undefined || isProducedRefArray(entry.producedRefs))
+            && (entry.decisions === undefined || isStringArray(entry.decisions))
+            && (entry.surfaceAttempt === undefined || isHabitSurfaceAttemptArray([entry.surfaceAttempt]))
+            && (entry.error === undefined || typeof entry.error === "string")
+            && (entry.meta === undefined || isPlainRecord(entry.meta)));
+}
 function isHabitReturnRouteArray(value) {
     return Array.isArray(value)
         && value.every((entry) => isPlainRecord(entry)
@@ -633,10 +694,11 @@ function isHabitToolPolicy(value) {
         && typeof value.outwardMessagingAllowed === "boolean";
 }
 function defaultHabitRunSummarySnapshot(receipt) {
+    const decisions = decisionsFromHabitRunTraceSteps(receipt.traceSteps);
     if (receipt.errors.length > 0) {
         return {
             summary: `Habit ${receipt.habitName} finished with errors: ${receipt.errors.join("; ")}`,
-            decisions: [],
+            decisions,
             nextLikelyStep: null,
         };
     }
@@ -644,7 +706,7 @@ function defaultHabitRunSummarySnapshot(receipt) {
     if (surface) {
         return {
             summary: `Habit ${receipt.habitName} surfaced via ${surface.recipient}/${surface.channel}.`,
-            decisions: [],
+            decisions,
             nextLikelyStep: null,
         };
     }
@@ -652,13 +714,13 @@ function defaultHabitRunSummarySnapshot(receipt) {
     if (produced) {
         return {
             summary: `Habit ${receipt.habitName} produced ${produced.kind}: ${produced.locator}.`,
-            decisions: [],
+            decisions,
             nextLikelyStep: null,
         };
     }
     return {
         summary: `Habit ${receipt.habitName} finished with ${receipt.outcome}.`,
-        decisions: [],
+        decisions,
         nextLikelyStep: null,
     };
 }
@@ -674,7 +736,7 @@ function normalizeHabitRunSummarySnapshot(value, fallback) {
             : fallback.nextLikelyStep;
     return {
         summary: (0, session_events_1.capStructuredRecordString)(summary),
-        decisions: cappedArray(isStringArray(snapshot.decisions) ? snapshot.decisions : fallback.decisions),
+        decisions: cappedArray(isStringArray(snapshot.decisions) && snapshot.decisions.length > 0 ? snapshot.decisions : fallback.decisions),
         nextLikelyStep: nextLikelyStep === null ? null : (0, session_events_1.capStructuredRecordString)(nextLikelyStep),
     };
 }
@@ -711,6 +773,7 @@ function isHabitRunReceipt(value) {
         && (value.summarySnapshot === undefined || isPlainRecord(value.summarySnapshot))
         && isProducedRefArray(value.producedRefs)
         && isHabitSurfaceAttemptArray(value.surfaceAttempts)
+        && (value.traceSteps === undefined || isHabitRunTraceStepArray(value.traceSteps))
         && isStringArray(value.errors);
 }
 function isLegacyHabitRunReceipt(value) {
@@ -780,11 +843,53 @@ function normalizeLegacyHabitRunReceipt(receipt) {
         summarySnapshot: defaultHabitRunSummarySnapshot(receipt),
         producedRefs: receipt.producedRefs,
         surfaceAttempts: receipt.surfaceAttempts,
+        traceSteps: [],
         errors: receipt.errors,
     };
 }
+function capHabitRunTraceRefs(refs) {
+    if (!refs || refs.length === 0)
+        return undefined;
+    return refs.map((ref) => ({
+        kind: (0, session_events_1.capStructuredRecordString)(ref.kind),
+        locator: (0, session_events_1.capStructuredRecordString)(ref.locator),
+        ...(ref.label ? { label: (0, session_events_1.capStructuredRecordString)(ref.label) } : {}),
+    }));
+}
+function capHabitRunTraceStep(step) {
+    const refs = capHabitRunTraceRefs(step.refs);
+    const producedRefs = step.producedRefs?.map((ref) => ({ ...ref, locator: (0, session_events_1.capStructuredRecordString)(ref.locator) }));
+    const decisions = step.decisions ? cappedArray(step.decisions) : undefined;
+    const surfaceAttempt = step.surfaceAttempt
+        ? {
+            ...step.surfaceAttempt,
+            recipient: (0, session_events_1.capStructuredRecordString)(step.surfaceAttempt.recipient),
+            channel: (0, session_events_1.capStructuredRecordString)(step.surfaceAttempt.channel),
+            ...(step.surfaceAttempt.rawStatus ? { rawStatus: (0, session_events_1.capStructuredRecordString)(step.surfaceAttempt.rawStatus) } : {}),
+            ...(step.surfaceAttempt.error ? { error: (0, session_events_1.capStructuredRecordString)(step.surfaceAttempt.error) } : {}),
+        }
+        : undefined;
+    return {
+        schemaVersion: 1,
+        stepId: (0, session_events_1.capStructuredRecordString)(step.stepId),
+        kind: step.kind,
+        status: step.status,
+        at: (0, session_events_1.capStructuredRecordString)(step.at),
+        summary: (0, session_events_1.capStructuredRecordString)(step.summary),
+        ...(refs ? { refs } : {}),
+        ...(producedRefs && producedRefs.length > 0 ? { producedRefs } : {}),
+        ...(decisions && decisions.length > 0 ? { decisions } : {}),
+        ...(surfaceAttempt ? { surfaceAttempt } : {}),
+        ...(step.error ? { error: (0, session_events_1.capStructuredRecordString)(step.error) } : {}),
+        ...(step.meta ? { meta: (0, session_events_1.capStructuredRecordStringLeaves)(step.meta) } : {}),
+    };
+}
+function normalizeHabitRunTraceSteps(traceSteps) {
+    return (traceSteps ?? []).map((step) => capHabitRunTraceStep(step));
+}
 function capHabitRunReceipt(receipt) {
-    const fallbackSnapshot = defaultHabitRunSummarySnapshot(receipt);
+    const traceSteps = normalizeHabitRunTraceSteps(receipt.traceSteps);
+    const fallbackSnapshot = defaultHabitRunSummarySnapshot({ ...receipt, traceSteps });
     return {
         ...receipt,
         habitName: (0, session_events_1.capStructuredRecordString)(receipt.habitName),
@@ -822,6 +927,7 @@ function capHabitRunReceipt(receipt) {
             ...(attempt.rawStatus ? { rawStatus: (0, session_events_1.capStructuredRecordString)(attempt.rawStatus) } : {}),
             ...(attempt.error ? { error: (0, session_events_1.capStructuredRecordString)(attempt.error) } : {}),
         })),
+        traceSteps,
         errors: receipt.errors.map((error) => (0, session_events_1.capStructuredRecordString)(error)),
     };
 }

package/dist/heart/daemon/doctor.js

@@ -7,9 +7,10 @@
  * "fail" check and the remaining categories still run.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KNOWN_DOCTOR_CATEGORIES = void 0;
+exports.KNOWN_DOCTOR_CATEGORIES = exports.DEFAULT_SENSE_DELIVERY_THRESHOLDS = exports.DEFAULT_MAIL_INGEST_THRESHOLDS = void 0;
 exports.checkCliPath = checkCliPath;
 exports.checkDaemon = checkDaemon;
+exports.senseInboundDeliveryCheck = senseInboundDeliveryCheck;
 exports.checkAgents = checkAgents;
 exports.checkSenses = checkSenses;
 exports.checkHabits = checkHabits;
@@ -23,6 +24,7 @@ exports.checkLifecycle = checkLifecycle;
 exports.runDoctorChecks = runDoctorChecks;
 const runtime_1 = require("../../nerves/runtime");
 const bluebubbles_health_diagnostics_1 = require("./bluebubbles-health-diagnostics");
+const freshness_1 = require("./freshness");
 const ouro_path_installer_1 = require("../versioning/ouro-path-installer");
 const runtime_credentials_1 = require("../runtime-credentials");
 const machine_identity_1 = require("../machine-identity");
@@ -115,6 +117,102 @@ const SENSITIVE_CONFIG_KEYS = ["apiKey", "token", "secret", "password"];
 function credentialKeyLeaks(raw) {
     return SENSITIVE_CONFIG_KEYS.filter((key) => raw.includes(`"${key}"`));
 }
+// ── Pipeline liveness (dead-pipe detection) ──
+//
+// Configuration checks answer "is this wired up?". These answer "is anything
+// actually flowing?". Both are needed: the 77-day mail outage and the
+// multi-day BlueBubbles inbound outage were both invisible to configuration
+// and connection checks that stayed green throughout.
+/**
+ * Mail ingest thresholds.
+ *
+ * A delegated mailbox forwards a human's real inbox, so a full calendar day
+ * with zero inbound mail is already anomalous — that is the warn line. Fail
+ * waits until 72h so a genuinely quiet weekend on a low-traffic mailbox does
+ * not hard-fail doctor; the 2026-05-10 outage would have failed on day four
+ * instead of going unnoticed for seventy-seven. Override per agent with
+ * `senses.mail.freshness.{warnAfterHours,failAfterHours}` in `agent.json`.
+ */
+exports.DEFAULT_MAIL_INGEST_THRESHOLDS = {
+    warnAfterMs: 24 * freshness_1.FRESHNESS_HOUR_MS,
+    failAfterMs: 72 * freshness_1.FRESHNESS_HOUR_MS,
+};
+/**
+ * Inbound sense-delivery thresholds.
+ *
+ * Human-driven chat surfaces are bursty — nobody texts an agent every day —
+ * so the warn line sits at 72h and failure waits a full week. Seven days
+ * without a single inbound message on an attached chat sense is not plausible
+ * quiet; it is a dead pipe. Override per agent with
+ * `senses.<sense>.freshness.{warnAfterHours,failAfterHours}` in `agent.json`.
+ */
+exports.DEFAULT_SENSE_DELIVERY_THRESHOLDS = {
+    warnAfterMs: 72 * freshness_1.FRESHNESS_HOUR_MS,
+    failAfterMs: 7 * freshness_1.FRESHNESS_DAY_MS,
+};
+/** Hard bound on how many per-conversation inbound logs a sense probe stats. */
+const SENSE_DELIVERY_MAX_LOG_SCAN = 500;
+function pipelineLivenessCheck(input) {
+    const result = (0, freshness_1.evaluateFreshness)({
+        activity: input.activity,
+        unit: input.unit,
+        observation: input.probe.observation,
+        provenance: input.probe.provenance,
+        nowMs: input.nowMs,
+        thresholds: input.thresholds,
+        remediation: input.remediation,
+        configuredSinceMs: input.configuredSinceMs,
+        context: input.context,
+    });
+    return { id: input.id, label: input.label, status: result.status, detail: result.detail };
+}
+/** Best-effort mtime used as a "this pipe has been wired up since" floor. */
+function pathMtimeMs(deps, filePath) {
+    if (!deps.existsSync(filePath))
+        return null;
+    try {
+        return deps.statSync(filePath).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read `senses.<sense>.freshness` from `agent.json`, if present. */
+function senseFreshnessOverride(deps, agentDir, sense) {
+    const configPath = `${deps.bundlesRoot}/${agentDir}/agent.json`;
+    if (!deps.existsSync(configPath))
+        return null;
+    try {
+        const config = JSON.parse(deps.readFileSync(configPath));
+        return asRecord(asRecord(config.senses)?.[sense])?.freshness ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Inbound-delivery liveness for a sense that records what it received.
+ *
+ * This asserts on the *inbound* log, deliberately not on the upstream health
+ * probe: BlueBubbles reported `upstreamStatus: ok` for days while inbound
+ * delivery was dead because the server was POSTing to a stale webhook port.
+ * A sense opts in by calling this with its inbound log directory.
+ */
+function senseInboundDeliveryCheck(input) {
+    const suffix = input.logSuffix ?? ".ndjson";
+    return pipelineLivenessCheck({
+        id: `senses.${input.sense}.inbound_liveness`,
+        label: `${input.agentDir} ${input.sense} inbound delivery`,
+        activity: `${input.sense} inbound delivery`,
+        unit: "inbound message",
+        probe: (0, freshness_1.observeAppendPerEventStore)(input.inboundDir, input.deps, { suffix, maxEntries: SENSE_DELIVERY_MAX_LOG_SCAN }),
+        thresholds: (0, freshness_1.resolveFreshnessThresholds)(exports.DEFAULT_SENSE_DELIVERY_THRESHOLDS, senseFreshnessOverride(input.deps, input.agentDir, input.sense)),
+        remediation: input.remediation,
+        configuredSinceMs: input.configuredSincePath ? pathMtimeMs(input.deps, input.configuredSincePath) : null,
+        context: input.context,
+        nowMs: input.nowMs,
+    });
+}
 function checkAgents(deps) {
     const checks = [];
     if (!deps.existsSync(deps.bundlesRoot)) {
@@ -255,6 +353,7 @@ async function checkSenses(deps) {
                     status: "pass",
                     detail: serverUrl,
                 });
+                let upstreamContext = "upstream probe not run in this pass";
                 if (deps.fetchImpl) {
                     const probe = await (0, bluebubbles_health_diagnostics_1.probeBlueBubblesHealth)({
                         serverUrl,
@@ -267,7 +366,21 @@ async function checkSenses(deps) {
                         status: probe.ok ? "pass" : "fail",
                         detail: probe.detail,
                     });
+                    upstreamContext = probe.ok
+                        ? "upstream probe reachable — which does not prove inbound delivery"
+                        : "upstream probe failing";
                 }
+                const bluebubblesStateRoot = `${deps.bundlesRoot}/${agentDir}/state/senses/bluebubbles`;
+                checks.push(senseInboundDeliveryCheck({
+                    deps,
+                    agentDir,
+                    sense: "bluebubbles",
+                    inboundDir: `${bluebubblesStateRoot}/inbound`,
+                    configuredSincePath: bluebubblesStateRoot,
+                    context: upstreamContext,
+                    remediation: "no iMessage is reaching this agent — confirm the BlueBubbles server's configured webhook URL/port matches the port this daemon is listening on (a stale webhook port is the known cause), then re-attach with `ouro connect bluebubbles --agent <agent>`",
+                    nowMs: Date.now(),
+                }));
             }
             if (sense === "mail" && senseObj.enabled === true) {
                 const runtimeConfig = await (0, runtime_credentials_1.refreshRuntimeCredentialConfig)(agentName, { preserveCachedOnFailure: true });
@@ -739,26 +852,64 @@ function checkMailroom(deps) {
             checks.push({ label: `${agentDir} mailroom`, status: "warn", detail: "registry.json has no mailboxes — provision via `ouro connect mail`" });
             continue;
         }
-        let messagesCount = 0;
         const messagesDir = `${mailroomRoot}/messages`;
-        /* v8 ignore start -- defensive: messages-dir presence + readdir error + pluralization branches depend on filesystem-state fixtures not exhaustively covered @preserve */
-        if (deps.existsSync(messagesDir)) {
-            try {
-                messagesCount = deps.readdirSync(messagesDir).filter((name) => name.endsWith(".json")).length;
-            }
-            catch {
-                // ignore — pass detail just won't include the message count
-            }
-        }
+        const listing = listStoredMailMessages(deps, messagesDir);
+        /* v8 ignore start -- defensive: pluralization branches depend on filesystem-state fixtures not exhaustively covered @preserve */
         checks.push({
             label: `${agentDir} mailroom`,
             status: "pass",
-            detail: `${mailboxes.length} mailbox${mailboxes.length === 1 ? "" : "es"}, ${sourceGrants.length} source grant${sourceGrants.length === 1 ? "" : "s"}, ${messagesCount} message${messagesCount === 1 ? "" : "s"}`,
+            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));
     }
     return { name: "Mailroom", checks };
 }
+function listStoredMailMessages(deps, messagesDir) {
+    if (!deps.existsSync(messagesDir))
+        return { count: 0, readable: true };
+    try {
+        return { count: deps.readdirSync(messagesDir).filter((name) => name.endsWith(".json")).length, readable: true };
+    }
+    catch {
+        return { count: 0, readable: false };
+    }
+}
+/**
+ * Mail-ingest liveness — "is mail still arriving?", as opposed to the check
+ * above, which only says "is a mailbox configured?".
+ *
+ * This is the check that would have caught the 2026-05-10 outage: the mailbox,
+ * 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?".
+ */
+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}`,
+        };
+    return pipelineLivenessCheck({
+        id: "mail.ingest_liveness",
+        label: `${agentDir} mail ingest liveness`,
+        activity: "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",
+        configuredSinceMs: pathMtimeMs(deps, `${mailroomRoot}/registry.json`),
+        context: "mailbox configured",
+        nowMs: Date.now(),
+    });
+}
 function checkFriends(deps) {
     const checks = [];
     const agents = discoverAgents(deps);