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

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

package/dist/heart/daemon/freshness.js

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