@ouro.bot/cli 0.1.0-alpha.721 → 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,12 @@
 {
   "_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": [

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);

package/dist/heart/daemon/freshness.js

@@ -0,0 +1,302 @@
+"use strict";
+/**
+ * Pipeline freshness — "is this pipe still moving?"
+ *
+ * Every outage this module exists to prevent had the same shape: a health
+ * check verified that something was *configured* or *connected*, and reported
+ * a green tick next to a pipe that had been dead for weeks.
+ *
+ *   - mail: `mail enabled` / `mail config ok` / `45479 messages` all passed
+ *     while zero mail had been ingested for 77 days after a vault key rotation
+ *     changed the mailbox keyIds. The message count is cumulative, so it can
+ *     only ever go up — it is not a liveness signal.
+ *   - bluebubbles: the upstream HTTP probe stayed `ok` for days while inbound
+ *     delivery was dead, because the server was POSTing its webhook to a
+ *     stale port. A reachable upstream does not prove inbound delivery.
+ *   - launchd: checks asserted a plist *file* existed rather than that the
+ *     job was loaded.
+ *
+ * The fix is to assert on *observed data flow*, with three rules baked into
+ * this primitive:
+ *
+ *   1. Age is always stated in the message, in human units, with the
+ *      timestamp it was derived from.
+ *   2. "Never observed any activity" and "could not observe" are distinct
+ *      states from "activity, but stale" — and none of them can read as
+ *      `pass`. An unobservable pipe is unverified, not healthy.
+ *   3. Every non-`pass` result carries a concrete remediation hint.
+ *
+ * Thresholds are always supplied by the caller so freshness policy lives with
+ * the pipe it describes, not in this file.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CLOCK_SKEW_TOLERANCE_MS = exports.FRESHNESS_DAY_MS = exports.FRESHNESS_HOUR_MS = exports.FRESHNESS_MINUTE_MS = void 0;
+exports.formatFreshnessAge = formatFreshnessAge;
+exports.formatFreshnessTimestamp = formatFreshnessTimestamp;
+exports.evaluateFreshness = evaluateFreshness;
+exports.observeCreatePerEventStore = observeCreatePerEventStore;
+exports.observeAppendPerEventStore = observeAppendPerEventStore;
+exports.resolveFreshnessThresholds = resolveFreshnessThresholds;
+const runtime_1 = require("../../nerves/runtime");
+exports.FRESHNESS_MINUTE_MS = 60 * 1000;
+exports.FRESHNESS_HOUR_MS = 60 * exports.FRESHNESS_MINUTE_MS;
+exports.FRESHNESS_DAY_MS = 24 * exports.FRESHNESS_HOUR_MS;
+/** Small tolerance before a future timestamp is treated as clock skew. */
+exports.DEFAULT_CLOCK_SKEW_TOLERANCE_MS = exports.FRESHNESS_MINUTE_MS;
+/**
+ * Human-readable duration. Always rounds down so the age is never overstated:
+ * "77 days" means at least 77 days have elapsed.
+ */
+function formatFreshnessAge(ms) {
+    const clamped = Math.max(0, ms);
+    const seconds = Math.floor(clamped / 1000);
+    if (seconds < 60)
+        return `${seconds} second${seconds === 1 ? "" : "s"}`;
+    const minutes = Math.floor(clamped / exports.FRESHNESS_MINUTE_MS);
+    if (minutes < 60)
+        return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+    const hours = Math.floor(clamped / exports.FRESHNESS_HOUR_MS);
+    if (hours < 48)
+        return `${hours} hour${hours === 1 ? "" : "s"}`;
+    // The day bucket only starts at 48h, so it is always plural.
+    return `${Math.floor(clamped / exports.FRESHNESS_DAY_MS)} days`;
+}
+/** Minute-precision ISO instant — keeps the incident date visible and unambiguous. */
+function formatFreshnessTimestamp(ms) {
+    return new Date(ms).toISOString().replace(/:\d{2}\.\d{3}Z$/, "Z");
+}
+function joinDetail(parts) {
+    return parts.filter((part) => !!part && part.trim().length > 0).join("; ");
+}
+function statusForAge(ageMs, thresholds) {
+    if (ageMs >= thresholds.failAfterMs)
+        return "fail";
+    if (ageMs >= thresholds.warnAfterMs)
+        return "warn";
+    return "pass";
+}
+/**
+ * Severity for "readable store, nothing ever recorded".
+ *
+ * Floors at `warn` on purpose: a configured-but-never-delivered pipe is never
+ * healthy, but a pipe wired up minutes ago does not deserve a hard failure.
+ */
+function statusForNever(input) {
+    const since = input.configuredSinceMs;
+    if (typeof since !== "number" || !Number.isFinite(since)) {
+        return { status: "fail", configuredForMs: null };
+    }
+    const configuredForMs = Math.max(0, input.nowMs - since);
+    const escalated = statusForAge(configuredForMs, input.thresholds);
+    return { status: escalated === "pass" ? "warn" : escalated, configuredForMs };
+}
+function evaluateActivity(input, atMs) {
+    const tolerance = input.clockSkewToleranceMs ?? exports.DEFAULT_CLOCK_SKEW_TOLERANCE_MS;
+    const skewMs = atMs - input.nowMs;
+    const timestamp = formatFreshnessTimestamp(atMs);
+    if (skewMs > tolerance) {
+        return {
+            status: "warn",
+            state: "future",
+            ageMs: 0,
+            detail: joinDetail([
+                input.context,
+                `last ${input.unit} is timestamped ${timestamp}, ${formatFreshnessAge(skewMs)} in the future — clock skew means freshness cannot be trusted`,
+                input.provenance,
+                `fix: ${input.remediation}`,
+            ]),
+        };
+    }
+    const ageMs = Math.max(0, -skewMs);
+    const status = statusForAge(ageMs, input.thresholds);
+    if (status === "pass") {
+        return {
+            status,
+            state: "fresh",
+            ageMs,
+            detail: joinDetail([
+                input.context,
+                `${input.activity} ${formatFreshnessAge(ageMs)} ago (last ${input.unit} ${timestamp})`,
+                input.provenance,
+            ]),
+        };
+    }
+    return {
+        status,
+        state: "stale",
+        ageMs,
+        detail: joinDetail([
+            input.context,
+            `no ${input.activity} in ${formatFreshnessAge(ageMs)} — last ${input.unit} ${timestamp}`,
+            input.provenance,
+            `fix: ${input.remediation}`,
+        ]),
+    };
+}
+/**
+ * Turn a single observation into a status + actionable detail.
+ *
+ * The only path that can return `pass` is an observed activity timestamp
+ * inside the warn threshold. Everything else — no activity, unreadable store,
+ * skewed clock — is surfaced, never swallowed.
+ */
+function evaluateFreshness(input) {
+    const observation = input.observation;
+    if (observation.kind === "unknown") {
+        return {
+            status: "fail",
+            state: "unknown",
+            ageMs: null,
+            detail: joinDetail([
+                input.context,
+                `${input.activity}: last-activity time could not be determined — ${observation.reason}; unverified, not healthy`,
+                input.provenance,
+                `fix: ${input.remediation}`,
+            ]),
+        };
+    }
+    if (observation.kind === "none") {
+        const { status, configuredForMs } = statusForNever(input);
+        return {
+            status,
+            state: "never",
+            ageMs: null,
+            detail: joinDetail([
+                input.context,
+                configuredForMs === null
+                    ? `no ${input.activity} ever — the store is readable and empty`
+                    : `no ${input.activity} ever — the store is readable and empty, and this pipe has been configured for ${formatFreshnessAge(configuredForMs)}`,
+                input.provenance,
+                `fix: ${input.remediation}`,
+            ]),
+        };
+    }
+    if (!Number.isFinite(observation.atMs)) {
+        return evaluateFreshness({
+            ...input,
+            observation: { kind: "unknown", reason: `observed timestamp is not a finite epoch-ms value (${String(observation.atMs)})` },
+        });
+    }
+    return evaluateActivity(input, observation.atMs);
+}
+/**
+ * Last-write probe for **create-per-event** stores — one new file per event,
+ * such as the mailroom's `messages/<id>.json`.
+ *
+ * A directory's mtime advances whenever an entry is created or removed, so it
+ * is an exact answer to "when was a file last added here" for O(1) cost, with
+ * no per-entry stat. That matters: the production mailroom holds ~45k message
+ * files and must never be stat-walked by a health check.
+ *
+ * It is also the semantically *correct* signal here. A message's `receivedAt`
+ * is when the mail was sent, not when this machine ingested it — an mbox
+ * backfill writes month-old `receivedAt` values today — so parsing message
+ * bodies would answer a different question than "is the pipe moving?".
+ *
+ * `hasEntries` is supplied by the caller (which typically already lists the
+ * directory for a count) so an empty directory reports `none` rather than
+ * reporting its own creation time as activity.
+ */
+function observeCreatePerEventStore(dir, deps, options) {
+    const provenance = `derived from ${dir} directory mtime (O(1), no per-entry scan)`;
+    if (!deps.existsSync(dir)) {
+        return { observation: { kind: "none" }, provenance: `${dir} does not exist` };
+    }
+    if (!options.hasEntries) {
+        return { observation: { kind: "none" }, provenance: `${dir} is empty` };
+    }
+    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
+ * chat).
+ *
+ * Directory mtime is the wrong signal here: appending to an existing file does
+ * not touch its parent directory, so a busy-but-not-growing log set would look
+ * frozen. This stats each matching entry and takes the newest.
+ *
+ * The scan is bounded by `maxEntries`. When the bound is hit the provenance
+ * says so explicitly — a bounded scan must never masquerade as exhaustive.
+ */
+function observeAppendPerEventStore(dir, deps, options) {
+    if (!deps.existsSync(dir)) {
+        return { observation: { kind: "none" }, provenance: `${dir} does not exist` };
+    }
+    let entries;
+    try {
+        entries = deps.readdirSync(dir).filter((name) => name.endsWith(options.suffix));
+    }
+    catch (error) {
+        return {
+            observation: { kind: "unknown", reason: `${dir} could not be listed: ${error instanceof Error ? error.message : String(error)}` },
+            provenance: `attempted directory listing of ${dir}`,
+        };
+    }
+    if (entries.length === 0) {
+        return { observation: { kind: "none" }, provenance: `${dir} holds no ${options.suffix} logs` };
+    }
+    const scanned = entries.slice(0, options.maxEntries);
+    const truncated = entries.length > scanned.length;
+    const provenance = truncated
+        ? `newest mtime across the first ${scanned.length} of ${entries.length} ${options.suffix} logs in ${dir} — scan bounded, newer activity may exist in the unscanned ${entries.length - scanned.length}`
+        : `newest mtime across ${scanned.length} ${options.suffix} log${scanned.length === 1 ? "" : "s"} in ${dir}`;
+    let newest = Number.NEGATIVE_INFINITY;
+    const failures = [];
+    for (const name of scanned) {
+        try {
+            const mtimeMs = deps.statSync(`${dir}/${name}`).mtimeMs;
+            if (mtimeMs > newest)
+                newest = mtimeMs;
+        }
+        catch (error) {
+            failures.push(`${name}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (newest === Number.NEGATIVE_INFINITY) {
+        return {
+            observation: { kind: "unknown", reason: `none of the ${scanned.length} log(s) in ${dir} could be stat'd: ${failures.slice(0, 3).join("; ")}` },
+            provenance,
+        };
+    }
+    return {
+        observation: { kind: "activity", atMs: newest },
+        provenance: failures.length > 0 ? `${provenance} (${failures.length} unreadable and skipped)` : provenance,
+    };
+}
+/**
+ * Merge an `agent.json` override onto in-repo defaults.
+ *
+ * Configuration lives in a committed config file rather than an environment
+ * variable, per the repo configuration policy. Non-positive and non-finite
+ * values are ignored so a malformed override can never disable the check.
+ */
+function resolveFreshnessThresholds(defaults, override) {
+    const record = override && typeof override === "object" && !Array.isArray(override)
+        ? override
+        : null;
+    const hours = (key) => {
+        const value = record?.[key];
+        return typeof value === "number" && Number.isFinite(value) && value > 0 ? value * exports.FRESHNESS_HOUR_MS : null;
+    };
+    return {
+        warnAfterMs: hours("warnAfterHours") ?? defaults.warnAfterMs,
+        failAfterMs: hours("failAfterHours") ?? defaults.failAfterMs,
+    };
+}
+/* v8 ignore start -- module load observability event */
+(0, runtime_1.emitNervesEvent)({
+    component: "daemon",
+    event: "daemon.pipeline_freshness_loaded",
+    message: "pipeline freshness primitive loaded",
+    meta: {},
+});
+/* v8 ignore stop */

package/package.json

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