@ouro.bot/cli 0.1.0-alpha.53 → 0.1.0-alpha.530

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

@@ -39,14 +39,27 @@ const path = __importStar(require("path"));
 const process_manager_1 = require("./process-manager");
 const daemon_1 = require("./daemon");
 const runtime_1 = require("../../nerves/runtime");
+const index_1 = require("../../nerves/index");
 const message_router_1 = require("./message-router");
 const health_monitor_1 = require("./health-monitor");
+const daemon_health_1 = require("./daemon-health");
+const daemon_rollup_1 = require("./daemon-rollup");
 const task_scheduler_1 = require("./task-scheduler");
 const runtime_logging_1 = require("./runtime-logging");
 const sense_manager_1 = require("./sense-manager");
 const agent_discovery_1 = require("./agent-discovery");
 const identity_1 = require("../identity");
 const runtime_mode_1 = require("./runtime-mode");
+const habit_scheduler_1 = require("../habits/habit-scheduler");
+const habit_migration_1 = require("../habits/habit-migration");
+const os_cron_deps_1 = require("./os-cron-deps");
+const os_cron_1 = require("./os-cron");
+const daemon_tombstone_1 = require("./daemon-tombstone");
+const agent_config_check_1 = require("./agent-config-check");
+const drift_detection_1 = require("./drift-detection");
+const pulse_1 = require("./pulse");
+const socket_client_1 = require("./socket-client");
+const bundle_manifest_1 = require("../../mind/bundle-manifest");
 function parseSocketPath(argv) {
     const socketIndex = argv.indexOf("--socket");
     if (socketIndex >= 0) {
@@ -66,6 +79,16 @@ const mode = (0, runtime_mode_1.detectRuntimeMode)((0, identity_1.getRepoRoot)()
     message: "starting daemon entrypoint",
     meta: { socketPath, entryPath, mode },
 });
+/* v8 ignore next -- dev-mode indicator: false branch (production) tested in daemon-boot-updates.test.ts @preserve */
+if (mode === "dev") {
+    const repoRoot = (0, identity_1.getRepoRoot)();
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.dev_mode_indicator",
+        message: `[dev] running from ${repoRoot}`,
+        meta: { repoRoot },
+    });
+}
 const managedAgents = (0, agent_discovery_1.listEnabledBundleAgents)();
 const processManager = new process_manager_1.DaemonProcessManager({
     agents: managedAgents.map((agent) => ({
@@ -75,6 +98,28 @@ const processManager = new process_manager_1.DaemonProcessManager({
         autoStart: true,
     })),
     existsSync: fs.existsSync,
+    /* v8 ignore next 4 -- wiring: delegates to checkAgentConfigWithProviderHealth which has full unit tests @preserve */
+    configCheck: async (agent) => {
+        const bundlesRoot = (0, identity_1.getAgentBundlesRoot)();
+        return (0, agent_config_check_1.checkAgentConfigWithProviderHealth)(agent, bundlesRoot);
+    },
+    /* v8 ignore start -- pulse flush wiring: integration code; flushPulse itself has full unit tests @preserve */
+    onSnapshotChange: () => {
+        (0, pulse_1.flushPulse)({
+            snapshots: processManager.listAgentSnapshots(),
+            bundlesRoot: (0, identity_1.getAgentBundlesRoot)(),
+            daemonVersion: (0, bundle_manifest_1.getPackageVersion)(),
+            now: new Date(),
+            // Default I/O wired into pulse.ts (writePulse, readPulse, etc.)
+            // Wake recipient: send inner.wake over the daemon's own socket so
+            // the recipient agent runs an inner-dialog turn that picks up the
+            // pulse alert. Catch errors silently — pulse is best-effort.
+            fireInnerWake: (agent) => {
+                (0, socket_client_1.sendDaemonCommand)(socketPath, { kind: "inner.wake", agent }).catch(() => { });
+            },
+        });
+    },
+    /* v8 ignore stop */
 });
 const scheduler = new task_scheduler_1.TaskDrivenScheduler({
     agents: [...managedAgents],
@@ -86,6 +131,7 @@ const senseManager = new sense_manager_1.DaemonSenseManager({
 const healthMonitor = new health_monitor_1.HealthMonitor({
     processManager,
     scheduler,
+    senseProbeProvider: () => senseManager.listHealthProbes(),
     alertSink: (message) => {
         (0, runtime_1.emitNervesEvent)({
             level: "error",
@@ -95,7 +141,40 @@ const healthMonitor = new health_monitor_1.HealthMonitor({
             meta: { message },
         });
     },
+    /* v8 ignore next 3 -- wiring: delegates to processManager.restartAgent which has full unit tests @preserve */
+    onCriticalAgent: (agentName) => {
+        try {
+            processManager.restartAgent(agentName);
+        }
+        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;
+let stopCommandExitScheduled = false;
+function stopEntryRuntime() {
+    if (entryRuntimeStopping)
+        return;
+    entryRuntimeStopping = true;
+    for (const s of habitSchedulers) {
+        s.stopWatching();
+        s.stop();
+    }
+    healthMonitor.stopPeriodicChecks();
+}
+function scheduleCleanProcessExitAfterStopCommand() {
+    if (stopCommandExitScheduled)
+        return;
+    stopCommandExitScheduled = true;
+    setTimeout(() => process.exit(0), 100);
+}
 const daemon = new daemon_1.OuroDaemon({
     socketPath,
     processManager,
@@ -103,21 +182,324 @@ const daemon = new daemon_1.OuroDaemon({
     scheduler,
     healthMonitor,
     router,
+    mode,
+    onStopCommandComplete: () => {
+        stopEntryRuntime();
+        scheduleCleanProcessExitAfterStopCommand();
+    },
 });
-void daemon.start().catch(async () => {
+const daemonStartedAt = new Date().toISOString();
+const degradedComponents = [];
+function buildDaemonHealthState() {
+    const snapshots = processManager.listAgentSnapshots();
+    const agentDegradedComponents = snapshots
+        .filter((snapshot) => snapshot.status !== "running")
+        .map((snapshot) => {
+        const reasonParts = [
+            snapshot.errorReason ?? `${snapshot.channel} is ${snapshot.status}`,
+            snapshot.fixHint ? `Fix: ${snapshot.fixHint}` : null,
+        ].filter((part) => part !== null);
+        return {
+            component: `agent:${snapshot.name}`,
+            reason: reasonParts.join(" "),
+            since: snapshot.lastCrashAt ?? daemonStartedAt,
+        };
+    });
+    // Preserved for backwards-compatible inspection: callers (status
+    // command, mailbox surface, etc.) may still read this combined list
+    // for per-component reasons. The rollup status field above is what
+    // changed meaning — the array is still the union of bootstrap +
+    // agent-derived degradation entries.
+    const degraded = [
+        ...degradedComponents.map((entry) => ({ ...entry })),
+        ...agentDegradedComponents,
+    ];
+    // Layer 4: probe each enabled agent for drift between agent.json
+    // (intent) and state/providers.json (observed binding). The result is
+    // a single boolean — driftDetected — that downgrades the rollup from
+    // healthy to partial when true. Per-finding detail is consumed by
+    // render-side surfaces (inner-status, --no-repair summary) and by
+    // Layer 3 RepairGuide; the rollup itself only cares about presence.
+    // Best-effort: a single agent's read failure is not blocking — the
+    // function returns "no drift detected for that agent" and continues.
+    const bundlesRoot = (0, identity_1.getAgentBundlesRoot)();
+    const drift = [];
+    for (const snapshot of snapshots) {
+        try {
+            const inputs = (0, drift_detection_1.loadDriftInputsForAgent)(bundlesRoot, snapshot.name);
+            const findings = (0, drift_detection_1.detectProviderBindingDrift)({
+                agentName: snapshot.name,
+                agentJson: inputs.agentJson,
+                providerState: inputs.providerState,
+            });
+            if (findings.length > 0) {
+                drift.push(...findings);
+            }
+        }
+        catch {
+            // best-effort: continue scanning
+        }
+    }
+    const driftDetected = drift.length > 0;
+    // Layer 1 rollup: project per-agent snapshots into the minimal
+    // AgentRollupInput shape and let computeDaemonRollup decide. The
+    // input is "every enabled agent" — managedAgents was filtered via
+    // listEnabledBundleAgents at module init, and snapshots only covers
+    // agents the process manager was told to manage, so by construction
+    // these entries are all enabled. The rollup function is a pure
+    // declarative function on the data we hand it.
+    //
+    // Note: safe-mode is wired as `false` here. Existing crash-loop
+    // detection (safe-mode.ts) already runs at the daemon-up boot path
+    // (cli-exec.ts), not from inside the daemon process itself. Once
+    // the daemon is up and reaching this rollup, safe mode no longer
+    // applies — the daemon is by definition past the crash-loop gate.
+    // If a future PR moves safe-mode signal into the running daemon,
+    // wire it through this third argument.
+    const rollupStatus = (0, daemon_rollup_1.computeDaemonRollup)({
+        enabledAgents: snapshots.map((snapshot) => ({
+            name: snapshot.name,
+            status: snapshot.status,
+        })),
+        bootstrapDegraded: degradedComponents,
+        safeMode: false,
+        driftDetected,
+    });
+    return {
+        status: rollupStatus,
+        mode,
+        pid: process.pid,
+        startedAt: daemonStartedAt,
+        uptimeSeconds: Math.floor(process.uptime()),
+        safeMode: null,
+        degraded,
+        drift,
+        agents: Object.fromEntries(snapshots.map((snapshot) => [
+            snapshot.name,
+            {
+                status: snapshot.status,
+                pid: snapshot.pid,
+                crashes: snapshot.restartCount,
+            },
+        ])),
+        habits: {},
+    };
+}
+function recordRecoverableBootstrapFailure(options) {
+    const errorMessage = options.error instanceof Error ? options.error.message : String(options.error);
+    const existing = degradedComponents.find((entry) => entry.component === options.component);
+    const reason = `${errorMessage}. ${options.guidance}`;
+    if (existing) {
+        existing.reason = reason;
+    }
+    else {
+        degradedComponents.push({
+            component: options.component,
+            reason,
+            since: new Date().toISOString(),
+        });
+    }
+    (0, runtime_1.emitNervesEvent)({
+        level: "warn",
+        component: "daemon",
+        event: "daemon.bootstrap_degraded",
+        message: "recoverable daemon bootstrap failure; daemon remains available in degraded mode",
+        meta: {
+            agent: options.agent,
+            component: options.component,
+            habitsDir: options.habitsDir,
+            error: errorMessage,
+            guidance: options.guidance,
+        },
+    });
+}
+function emitHabitSetupError(agent, error) {
+    const normalized = error instanceof Error ? error : new Error(String(error));
+    (0, runtime_1.emitNervesEvent)({
+        level: "error",
+        component: "daemon",
+        event: "daemon.habit_setup_error",
+        message: `habit setup failed for agent ${agent}`,
+        meta: { agent, error: normalized.message },
+    });
+}
+/* v8 ignore start — daemon health writer wiring, tested via daemon-health.test.ts @preserve */
+const healthWriter = new daemon_health_1.DaemonHealthWriter((0, daemon_health_1.getDefaultHealthPath)());
+const healthSink = (0, daemon_health_1.createHealthNervesSink)(healthWriter, buildDaemonHealthState);
+(0, index_1.registerGlobalLogSink)(healthSink);
+/* v8 ignore stop */
+/* v8 ignore start -- habit wiring: lambdas delegate to processManager/fs; tested via HabitScheduler unit tests @preserve */
+void daemon.start().then(() => {
+    const bundlesRoot = (0, identity_1.getAgentBundlesRoot)();
+    const ouroPath = (0, os_cron_deps_1.resolveOuroBinaryPath)();
+    const osCronDeps = (0, os_cron_deps_1.createRealOsCronDeps)();
+    for (const agent of managedAgents) {
+        const bundleRoot = path.join(bundlesRoot, `${agent}.ouro`);
+        const habitsDir = path.join(bundleRoot, "habits");
+        const degradedComponent = `habits:${agent}`;
+        try {
+            // Migrate old tasks/habits/ to habits/ at bundle root
+            (0, habit_migration_1.migrateHabitsFromTaskSystem)(bundleRoot);
+            const osCronManager = new os_cron_1.LaunchdCronManager(osCronDeps);
+            const scheduler = new habit_scheduler_1.HabitScheduler({
+                agent,
+                habitsDir,
+                osCronManager,
+                onHabitFire: (habitName) => {
+                    processManager.sendToAgent(agent, { type: "habit", habitName });
+                },
+                deps: {
+                    readdir: (dir) => fs.readdirSync(dir),
+                    readFile: (p, enc) => fs.readFileSync(p, enc),
+                    writeFile: (p, c, enc) => fs.writeFileSync(p, c, enc),
+                    existsSync: (p) => fs.existsSync(p),
+                    now: () => Date.now(),
+                    ouroPath,
+                    watch: (dir, cb) => fs.watch(dir, cb),
+                },
+            });
+            try {
+                scheduler.start();
+                scheduler.startPeriodicReconciliation();
+                scheduler.watchForChanges();
+                habitSchedulers.push(scheduler);
+            }
+            catch (error) {
+                try {
+                    scheduler.stopWatching();
+                    scheduler.stop();
+                }
+                catch {
+                    // Cleanup is best-effort for partially initialized schedulers.
+                }
+                emitHabitSetupError(agent, error);
+                recordRecoverableBootstrapFailure({
+                    agent,
+                    component: degradedComponent,
+                    habitsDir,
+                    error,
+                    guidance: `fix ${agent} habits or cron setup and rerun ouro up to restore habit automation`,
+                });
+            }
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            emitHabitSetupError(agent, error);
+            recordRecoverableBootstrapFailure({
+                agent,
+                component: degradedComponent,
+                habitsDir,
+                error,
+                guidance: `fix ${agent} habits or cron setup and rerun ouro up to restore habit automation`,
+            });
+        }
+    }
+    healthMonitor.startPeriodicChecks(60_000);
+    /* v8 ignore start -- startup failure + signal handlers: call process.exit, untestable in vitest @preserve */
+}).catch(async (err) => {
+    const error = err instanceof Error ? err : new Error(String(err));
+    _tombstoneWritten = true;
+    (0, daemon_tombstone_1.writeDaemonTombstone)("startupFailure", error);
     (0, runtime_1.emitNervesEvent)({
         level: "error",
         component: "daemon",
         event: "daemon.entry_error",
         message: "daemon entrypoint failed",
-        meta: {},
+        meta: { error: error.message },
     });
+    setTimeout(() => process.exit(1), 5_000).unref();
     await daemon.stop();
     process.exit(1);
 });
 process.on("SIGINT", () => {
+    // ALWAYS write a tombstone, even on signal-driven shutdown. The previous
+    // behavior was to set _gracefulShutdown=true and skip the tombstone, which
+    // meant ANY external SIGINT/SIGTERM (launchd policy, OOM killer, manual
+    // kill, killOrphanProcesses from a sibling daemon) silently disappeared
+    // from the death log. The user lost weeks of visibility into why their
+    // daemon kept dying. Tombstones are informational — having a "sigint"
+    // tombstone is strictly better than silence.
+    _tombstoneWritten = true;
+    (0, daemon_tombstone_1.writeDaemonTombstone)("sigint", new Error("daemon received SIGINT"));
+    stopEntryRuntime();
+    setTimeout(() => process.exit(1), 5_000).unref();
     void daemon.stop().then(() => process.exit(0));
 });
 process.on("SIGTERM", () => {
+    _tombstoneWritten = true;
+    (0, daemon_tombstone_1.writeDaemonTombstone)("sigterm", new Error("daemon received SIGTERM"));
+    stopEntryRuntime();
+    setTimeout(() => process.exit(1), 5_000).unref();
     void daemon.stop().then(() => process.exit(0));
 });
+/* v8 ignore stop */
+// Suppress EPIPE on stdout/stderr — normal when detached daemon's parent exits
+/* v8 ignore start -- EPIPE suppression: only fires when parent process exits @preserve */
+process.stdout?.on?.("error", () => { });
+process.stderr?.on?.("error", () => { });
+/* v8 ignore stop */
+/* v8 ignore start -- global exception handlers: genuinely untestable in vitest; exercised by real daemon crashes @preserve */
+let _uncaughtCount = 0;
+let _tombstoneWritten = false;
+let _lastKnownCause = null;
+const CIRCUIT_BREAKER_WINDOW_MS = 60_000;
+const CIRCUIT_BREAKER_MAX = 10;
+process.on("uncaughtException", (error) => {
+    // EPIPE is normal for detached daemon processes — parent closed the pipe
+    if (error.code === "EPIPE")
+        return;
+    _uncaughtCount++;
+    _lastKnownCause = error;
+    setTimeout(() => { _uncaughtCount--; }, CIRCUIT_BREAKER_WINDOW_MS).unref();
+    _tombstoneWritten = true;
+    (0, daemon_tombstone_1.writeDaemonTombstone)("uncaughtException", error);
+    (0, runtime_1.emitNervesEvent)({
+        level: "error",
+        component: "daemon",
+        event: "daemon.uncaught_exception",
+        message: "uncaught exception in daemon process (continuing)",
+        meta: { error: error.message, stack: error.stack ?? null, uncaughtCount: _uncaughtCount },
+    });
+    // Circuit breaker: if too many exceptions in a short window, the process
+    // is in a bad state — exit so launchd/self-spawn can restart fresh.
+    if (_uncaughtCount >= CIRCUIT_BREAKER_MAX) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "error",
+            component: "daemon",
+            event: "daemon.circuit_breaker_exit",
+            message: `daemon exiting: ${_uncaughtCount} uncaught exceptions in ${CIRCUIT_BREAKER_WINDOW_MS / 1000}s`,
+            meta: { uncaughtCount: _uncaughtCount },
+        });
+        setTimeout(() => process.exit(1), 5_000).unref();
+        void daemon.stop().then(() => process.exit(1));
+    }
+});
+process.on("unhandledRejection", (reason) => {
+    const error = reason instanceof Error ? reason : new Error(String(reason));
+    _lastKnownCause = error;
+    _tombstoneWritten = true;
+    (0, daemon_tombstone_1.writeDaemonTombstone)("unhandledRejection", error);
+    (0, runtime_1.emitNervesEvent)({
+        level: "error",
+        component: "daemon",
+        event: "daemon.unhandled_rejection",
+        message: "unhandled promise rejection in daemon process",
+        meta: { reason: error.message, stack: error.stack ?? null },
+    });
+});
+// Catch-all: write tombstone on any exit where we didn't already record the cause.
+// process.on('exit') is synchronous-only — writeDaemonTombstone uses writeFileSync, so it works.
+//
+// Previously this skipped writing if `_gracefulShutdown` was true, which made
+// SIGINT/SIGTERM-driven exits invisible in the death log. The signal handlers
+// above now always write their own tombstone before exiting, so this catch-all
+// only runs for exits the signal handlers didn't reach (e.g. process.exit
+// called from somewhere unexpected).
+process.on("exit", (code) => {
+    if (_tombstoneWritten)
+        return;
+    const reason = code === 0 ? "unexpectedCleanExit" : "unexpectedExit";
+    const error = _lastKnownCause ?? new Error(`daemon exited with code ${code} (no specific cause captured)`);
+    (0, daemon_tombstone_1.writeDaemonTombstone)(reason, error);
+});
+/* v8 ignore stop */

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

@@ -0,0 +1,183 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HEALTH_TRACKED_EVENTS = exports.DaemonHealthWriter = void 0;
+exports.isRollupStatus = isRollupStatus;
+exports.isDaemonStatus = isDaemonStatus;
+exports.getDefaultHealthPath = getDefaultHealthPath;
+exports.createHealthNervesSink = createHealthNervesSink;
+exports.readHealth = readHealth;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const runtime_1 = require("../../nerves/runtime");
+/**
+ * Daemon-wide rollup vocabulary — locked layer-1 contract.
+ *
+ * - `RollupStatus` is what `computeDaemonRollup` returns (post-inventory,
+ *   four-state). The function never returns `"down"` because by the time
+ *   the rollup is reachable the daemon has already started, opened its
+ *   socket, and read its agent inventory — pre-inventory failure is the
+ *   caller's domain.
+ * - `DaemonStatus` is what `DaemonHealthState.status` accepts. The caller
+ *   widens the rollup result with `"down"` along the daemon-entry failure
+ *   path (e.g. when the daemon process can't read inventory at all).
+ *
+ * `isRollupStatus` and `isDaemonStatus` are runtime guards used both by
+ * `readHealth` (validating cached health files on disk) and by render-side
+ * consumers that want to narrow `unknown` JSON into the typed union before
+ * branching on it.
+ */
+// Single source of truth — the literal lists below are the runtime
+// projection of the type unions. A future literal added to RollupStatus
+// MUST also be added to ROLLUP_STATUS_LITERALS or `satisfies` blows up
+// at tsc. That tightens the Layer 1 contract: producer + consumer +
+// guard all stay in lockstep.
+const ROLLUP_STATUS_LITERALS = ["healthy", "partial", "degraded", "safe-mode"];
+const DAEMON_STATUS_LITERALS = [...ROLLUP_STATUS_LITERALS, "down"];
+const ROLLUP_STATUS_VALUES = new Set(ROLLUP_STATUS_LITERALS);
+const DAEMON_STATUS_VALUES = new Set(DAEMON_STATUS_LITERALS);
+function isRollupStatus(value) {
+    return typeof value === "string" && ROLLUP_STATUS_VALUES.has(value);
+}
+function isDaemonStatus(value) {
+    return typeof value === "string" && DAEMON_STATUS_VALUES.has(value);
+}
+class DaemonHealthWriter {
+    healthPath;
+    constructor(healthPath) {
+        this.healthPath = healthPath;
+    }
+    writeHealth(state) {
+        try {
+            const dir = path.dirname(this.healthPath);
+            fs.mkdirSync(dir, { recursive: true });
+            const tmpPath = `${this.healthPath}.tmp.${process.pid}`;
+            fs.writeFileSync(tmpPath, JSON.stringify(state, null, 2) + "\n", "utf-8");
+            fs.renameSync(tmpPath, this.healthPath);
+            (0, runtime_1.emitNervesEvent)({
+                component: "daemon",
+                event: "daemon.health_written",
+                message: "daemon health file written",
+                meta: { path: this.healthPath, status: state.status },
+            });
+        }
+        catch {
+            // Best-effort: if we can't write, don't crash the daemon.
+        }
+    }
+}
+exports.DaemonHealthWriter = DaemonHealthWriter;
+function getDefaultHealthPath() {
+    return path.join(os.homedir(), ".ouro-cli", "daemon-health.json");
+}
+/** Events that trigger a debounced health file write */
+exports.HEALTH_TRACKED_EVENTS = new Set([
+    "daemon.habit_cron_verification_failed",
+    "daemon.habit_fire",
+    "daemon.agent_exit",
+    "daemon.agent_started",
+    "daemon.agent_config_invalid",
+    "daemon.agent_config_failure",
+    "daemon.agent_entry_missing",
+    "daemon.agent_spawn_failed",
+    "daemon.agent_startup_stale_recovered",
+    "daemon.agent_restart_exhausted",
+    "daemon.agent_permanent_failure",
+    "daemon.agent_cooldown_recovery",
+    "daemon.bootstrap_degraded",
+    "daemon.safe_mode_entered",
+    "daemon.habit_scheduler_start",
+]);
+/**
+ * Creates a nerves LogSink that triggers debounced health writes on relevant events.
+ * Components don't know about the health writer — they just emit events.
+ */
+function createHealthNervesSink(writer, getState) {
+    let debounceTimer = null;
+    return (entry) => {
+        if (!exports.HEALTH_TRACKED_EVENTS.has(entry.event)) {
+            return;
+        }
+        // Debounce: max once per second
+        if (debounceTimer !== null) {
+            clearTimeout(debounceTimer);
+        }
+        debounceTimer = setTimeout(() => {
+            debounceTimer = null;
+            const state = getState();
+            writer.writeHealth(state);
+        }, 1000);
+    };
+}
+function readHealth(healthPath) {
+    try {
+        const raw = fs.readFileSync(healthPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!isDaemonStatus(parsed.status) ||
+            typeof parsed.mode !== "string" ||
+            typeof parsed.pid !== "number" ||
+            typeof parsed.startedAt !== "string" ||
+            typeof parsed.uptimeSeconds !== "number" ||
+            !Array.isArray(parsed.degraded) ||
+            typeof parsed.agents !== "object" ||
+            parsed.agents === null ||
+            typeof parsed.habits !== "object" ||
+            parsed.habits === null) {
+            return null;
+        }
+        // `drift` is required in DaemonHealthState but absent from cached
+        // health files written by pre-Layer-4 daemons. Tolerate that legacy
+        // shape by defaulting to []; the rest of the file is still valid.
+        const drift = Array.isArray(parsed.drift)
+            ? parsed.drift
+            : [];
+        return {
+            status: parsed.status,
+            mode: parsed.mode,
+            pid: parsed.pid,
+            startedAt: parsed.startedAt,
+            uptimeSeconds: parsed.uptimeSeconds,
+            safeMode: parsed.safeMode,
+            degraded: parsed.degraded,
+            drift,
+            agents: parsed.agents,
+            habits: parsed.habits,
+        };
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeDaemonRollup = computeDaemonRollup;
+/**
+ * Pure rollup decision function — given the post-inventory daemon
+ * surface, returns the daemon-wide rollup state per the locked Layer 1
+ * vocabulary table:
+ *
+ *   | rollup     | when                                                      |
+ *   | ---------- | --------------------------------------------------------- |
+ *   | healthy    | every enabled agent serving + no bootstrap-degraded + no safe-mode |
+ *   | partial    | (≥1 serving + ≥1 not serving) OR (all serving + ≥1 bootstrap-degraded) |
+ *   | degraded   | zero enabled agents serving (fresh install OR all unhealthy)        |
+ *   | safe-mode  | `safeMode === true` overrides everything else                       |
+ *
+ * The function NEVER returns `"down"`. By the time `computeDaemonRollup`
+ * is reachable, the daemon process has started, opened its socket, and
+ * read its agent inventory — pre-inventory failure is the caller's
+ * domain. `daemon-entry.ts`'s startup-failure path assigns `"down"` to
+ * `DaemonHealthState.status` directly without consulting this function.
+ */
+function computeDaemonRollup(input) {
+    // Safe mode wins, period. Crash-loop detection trumps everything —
+    // we want the human to see SAFE MODE, not a noisy partial/degraded.
+    if (input.safeMode) {
+        return "safe-mode";
+    }
+    // Count serving agents. "Serving" = "running" worker status.
+    // Anything else (crashed/stopped/starting/etc) is not serving.
+    let serving = 0;
+    let notServing = 0;
+    for (const agent of input.enabledAgents) {
+        if (agent.status === "running") {
+            serving++;
+        }
+        else {
+            notServing++;
+        }
+    }
+    // Zero-serving wins over bootstrap-degraded — we have no working
+    // agents to surface a "partially working" story about. This covers
+    // both fresh-install (`enabledAgents.length === 0`) and
+    // all-failed-live-check (`serving === 0` with `notServing > 0`).
+    // Render layer (cli-render.ts) splits the UX copy by inspecting the
+    // agents map; the rollup itself doesn't carry the distinction.
+    if (serving === 0) {
+        return "degraded";
+    }
+    // From here we have ≥1 serving agent. The remaining choice is
+    // healthy vs partial.
+    const hasUnhealthyAgent = notServing > 0;
+    const hasBootstrapDegraded = input.bootstrapDegraded.length > 0;
+    const hasDrift = input.driftDetected === true;
+    if (hasUnhealthyAgent || hasBootstrapDegraded || hasDrift) {
+        return "partial";
+    }
+    return "healthy";
+}