@ouro.bot/cli 0.1.0-alpha.515 → 0.1.0-alpha.516

package/changelog.json

@@ -1,6 +1,16 @@
 {
   "_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.516",
+      "changes": [
+        "Layer 1 of the harness-hardening sequence (1→4→2→3 from `docs/planning/2026-04-28-1900-planning-harness-hardening-and-repairguide.md`). Replaces the daemon-wide rollup at `daemon-entry.ts` (the binary `degraded.length > 0 ? \"degraded\" : \"ok\"` literal) with a five-state vocabulary: `healthy / partial / degraded / safe-mode / down`. A single sick agent no longer tips the whole daemon to `degraded`.",
+        "Type structure: `RollupStatus` (4-state, returned by the new pure `computeDaemonRollup` decision function in `daemon-rollup.ts`) and `DaemonStatus = RollupStatus | \"down\"` (full daemon-status; `down` is caller-owned because it represents pre-inventory failure, before the rollup is reachable). Both unions project from a single source-of-truth literal tuple so future widening touches one site.",
+        "`renderRollupStatusLine` in `cli-render.ts` uses a compiler-forced `never`-typed exhaustive switch — adding a future state compile-errors at every consumer using the pattern. The `degraded` literal carries three copy variants picked by inspecting cached agent statuses: empty map (fresh install, prompts `ouro hatch`), non-empty + any running agent (legacy stale cache from pre-Layer-1 daemons, prompts `ouro up` refresh), non-empty + zero running (all-failed live-check, prompts `ouro doctor`).",
+        "`runtime-readers.ts:readDaemonHealthDeep` parse tightened to use `isDaemonStatus`. `OutlookDaemonHealthDeep.status` widened to `DaemonStatus | \"unknown\"` so legacy serialized strings (`\"running\"`, `\"ok\"`) coerce defensively rather than failing the parse during rollout.",
+        "9759 tests pass (508 test files); coverage gate clean. The per-agent live-check loop in `cli-exec.ts` is intentionally untouched — it was already try/catch-isolated; the bug was in how its output rolled up. Subsequent PRs (layers 4, 2, 3) build on this PR's vocabulary."
+      ]
+    },
     {
       "version": "0.1.0-alpha.515",
       "changes": [

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

@@ -45,6 +45,7 @@ exports.formatTable = formatTable;
 exports.formatDaemonStatusOutput = formatDaemonStatusOutput;
 exports.formatVersionOutput = formatVersionOutput;
 exports.buildStoppedStatusPayload = buildStoppedStatusPayload;
+exports.renderRollupStatusLine = renderRollupStatusLine;
 exports.daemonUnavailableStatusOutput = daemonUnavailableStatusOutput;
 exports.isDaemonUnavailableError = isDaemonUnavailableError;
 exports.formatMcpResponse = formatMcpResponse;
@@ -472,6 +473,69 @@ function buildStoppedStatusPayload(socketPath, syncRows = [], agentRows = []) {
         providers: [],
     };
 }
+/**
+ * Render the cached daemon-rollup status as a one-line string for the
+ * "daemon not running" view. Each `DaemonStatus` literal maps to a
+ * label + a brief explanatory copy fragment. The default branch is
+ * `never`-typed so future widening of `DaemonStatus` compile-errors
+ * here — Layer 1's compiler-forced exhaustiveness contract.
+ *
+ * The `degraded` literal splits into two copy variants based on the
+ * cached health file's `agents` map:
+ * - empty map → "no agents configured" (fresh-install copy).
+ * - non-empty map → "none ready" (all-agents-failed-live-check copy).
+ *
+ * The split lives at the render layer (not in the rollup status itself)
+ * so the same status can carry distinct UX copy without inflating the
+ * type union.
+ */
+function renderRollupStatusLine(health) {
+    const status = health.status;
+    const tail = `(pid ${health.pid}, uptime ${health.uptimeSeconds}s)`;
+    /* v8 ignore next -- v8 instruments the switch statement itself as a branch; the never-typed default below is unreachable by construction so v8 cannot observe its branch firing @preserve */
+    switch (status) {
+        case "healthy":
+            return `Last known status: healthy ${tail}`;
+        case "partial":
+            return `Last known status: partial — some agents unhealthy ${tail}`;
+        case "degraded": {
+            // Three-way copy split based on the cached agents map:
+            // - empty map → fresh install / no agents configured.
+            // - non-empty + any agent reports "running" → legacy stale cache:
+            //   pre-Layer-1, status="degraded" meant "any sick component," so a
+            //   running agent could coexist with a degraded daemon. Post-Layer-1,
+            //   degraded means "zero serving" — mutually exclusive with a running
+            //   agent. A live disagreement therefore implies the cache pre-dates
+            //   the rollup-semantics fix; prompt for `ouro up` to refresh rather
+            //   than falsely claim "none ready."
+            // - non-empty + zero agents reporting "running" → all-failed copy.
+            const agentEntries = Object.values(health.agents);
+            if (agentEntries.length === 0) {
+                return `Last known status: degraded — no agents configured (run \`ouro hatch\` to add one) ${tail}`;
+            }
+            const anyRunning = agentEntries.some((agent) => agent.status === "running");
+            if (anyRunning) {
+                return `Last known status: degraded — stale cache, run \`ouro up\` to refresh ${tail}`;
+            }
+            return `Last known status: degraded — agents configured but none ready (run \`ouro doctor\`) ${tail}`;
+        }
+        case "safe-mode":
+            return `Last known status: safe-mode — crash loop tripped ${tail}`;
+        case "down":
+            return `Last known status: down ${tail}`;
+        /* v8 ignore start -- compiler-forced exhaustiveness: the never-typed default branch is unreachable by construction; if DaemonStatus widens, tsc errors at the assignment before the throw can run @preserve */
+        default: {
+            // Compiler-forced exhaustiveness. If DaemonStatus grows a new
+            // literal, this `never` cast errors at tsc, forcing every
+            // consumer to handle it explicitly. NEVER replace this with a
+            // permissive `default:` returning a fallback string — that's
+            // exactly how the old "ok | degraded" semantics leaked through.
+            const _exhaustive = status;
+            throw new Error(`unhandled daemon status: ${_exhaustive}`);
+        }
+        /* v8 ignore stop */
+    }
+}
 function daemonUnavailableStatusOutput(socketPath, healthFilePath) {
     // Read per-agent sync config and bundle list from disk so the user still
     // sees them when the daemon is down. Best-effort: any fs error returns []
@@ -515,7 +579,7 @@ function daemonUnavailableStatusOutput(socketPath, healthFilePath) {
     const resolvedHealthPath = healthFilePath ?? (0, daemon_health_1.getDefaultHealthPath)();
     const health = (0, daemon_health_1.readHealth)(resolvedHealthPath);
     if (health) {
-        lines.push(`Last known status: ${health.status} (pid ${health.pid}, uptime ${health.uptimeSeconds}s)`);
+        lines.push(renderRollupStatusLine(health));
         if (health.safeMode?.active) {
             lines.push(`SAFE MODE: ${health.safeMode.reason}`);
         }

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

@@ -43,6 +43,7 @@ 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");
@@ -173,12 +174,40 @@ function buildDaemonHealthState() {
             since: snapshot.lastCrashAt ?? daemonStartedAt,
         };
     });
+    // Preserved for backwards-compatible inspection: callers (status
+    // command, outlook 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 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,
+    });
     return {
-        status: degraded.length > 0 ? "degraded" : "ok",
+        status: rollupStatus,
         mode,
         pid: process.pid,
         startedAt: daemonStartedAt,

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

@@ -34,6 +34,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 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;
@@ -41,6 +43,38 @@ 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) {
@@ -111,7 +145,7 @@ function readHealth(healthPath) {
     try {
         const raw = fs.readFileSync(healthPath, "utf-8");
         const parsed = JSON.parse(raw);
-        if (typeof parsed.status !== "string" ||
+        if (!isDaemonStatus(parsed.status) ||
             typeof parsed.mode !== "string" ||
             typeof parsed.pid !== "number" ||
             typeof parsed.startedAt !== "string" ||

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

@@ -0,0 +1,57 @@
+"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;
+    if (hasUnhealthyAgent || hasBootstrapDegraded) {
+        return "partial";
+    }
+    return "healthy";
+}

package/dist/heart/outlook/readers/runtime-readers.js

@@ -49,6 +49,7 @@ const runtime_1 = require("../../../nerves/runtime");
 const habit_parser_1 = require("../../habits/habit-parser");
 const habit_runtime_state_1 = require("../../habits/habit-runtime-state");
 const identity_1 = require("../../identity");
+const daemon_health_1 = require("../../daemon/daemon-health");
 const shared_1 = require("./shared");
 const agent_machine_1 = require("./agent-machine");
 const sessions_1 = require("./sessions");
@@ -270,7 +271,12 @@ function readDaemonHealthDeep(healthPath) {
         const raw = fs.readFileSync(resolvedPath, "utf-8");
         const health = JSON.parse(raw);
         return {
-            status: typeof health.status === "string" ? health.status : "unknown",
+            // Layer 1: tighten the parse so only post-Layer-1 vocabulary
+            // carries through. Stale cached files that still hold legacy
+            // string values like "ok" or "running" — written by an older
+            // daemon binary — fall back to "unknown" so downstream Outlook
+            // consumers can detect the unparseable case explicitly.
+            status: (0, daemon_health_1.isDaemonStatus)(health.status) ? health.status : "unknown",
             mode: typeof health.mode === "string" ? health.mode : "unknown",
             pid: typeof health.pid === "number" ? health.pid : 0,
             startedAt: typeof health.startedAt === "string" ? health.startedAt : "",

package/dist/nerves/coverage/file-completeness.js

@@ -87,6 +87,12 @@ const DISPATCH_EXEMPT_PATTERNS = [
     // HTTP health probe: pure HTTP utility factory. The HealthMonitor caller
     // owns observability via daemon.health_result events.
     "daemon/http-health-probe",
+    // Rollup decision function: pure decision tree mapping per-agent
+    // snapshots + bootstrap-degraded entries + safe-mode flag to a
+    // RollupStatus. No side effects. The caller (daemon-entry.ts
+    // buildDaemonHealthState → DaemonHealthWriter) owns observability via
+    // daemon.health_written when the rolled-up state is persisted.
+    "daemon/daemon-rollup",
     // Attachment helper modules: generic file-path/extension utilities and the
     // source registry are pure support seams. The orchestrator/adapters that
     // call them own the observability.

package/package.json

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