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

package/changelog.json

@@ -1,6 +1,28 @@
 {
   "_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.517",
+      "changes": [
+        "Layer 4 of the harness-hardening sequence (PR 2 of 4 in 1→4→2→3 from `docs/planning/2026-04-28-1900-planning-harness-hardening-and-repairguide.md`). Detects per-lane drift between each agent's intent (committed `agent.json`) and the observed binding on this machine (`state/providers.json`), surfaces the drift through the existing `EffectiveProviderReadiness.reason: \"provider-model-changed\"` vocabulary, and emits a copy-pasteable `ouro use` repair proposal. Read-only: the PR never mutates `state/providers.json` and never invokes the `ouro use` CLI surface.",
+        "New module `src/heart/daemon/drift-detection.ts`. `detectProviderBindingDrift(input)` is a pure intent-vs-observed comparator — it tolerates legacy `humanFacing`/`agentFacing` AND new `outward`/`inner` keys in `agent.json` with a 'new key wins, fall back to legacy' precedence rule (the rename is in flight; mixed `agent.json` files must work). `loadDriftInputsForAgent(bundlesRoot, agentName)` is the I/O wrapper that reads both files off disk, mapping missing/invalid `state/providers.json` to a `null` providerState (the comparator interprets `null` as 'no observation, nothing to drift against' — fresh-install case).",
+        "`checkAgentConfigWithProviderHealth` gains an additive optional `driftFindings: DriftFinding[]` field on `ConfigCheckResult`. Drift detection runs once after state setup so findings ride along with both success and failure return paths. Drift is advisory and never flips `ok` to false. Non-breaking: 7 existing tests using strict `toEqual({ok:true})` were loosened to `toMatchObject({ok:true})` to accept the additive field — no behavior change.",
+        "`computeDaemonRollup` (Layer 1) gains an optional `driftDetected: boolean`. When true, `healthy` → `partial` (same downgrade rule as `bootstrapDegraded`). `degraded` and `safe-mode` rollups are unaffected — drift never escalates past `partial` and never un-downgrades. `daemon-entry.ts` probes each enabled agent for drift before computing the rollup; a single agent's read failure is best-effort and does not block the scan.",
+        "`buildInnerStatusOutput` gains an optional `driftFindings` field and renders a `drift advisory` section per finding (lane, intent vs observed, copy-pasteable `ouro use`). `cli-exec.ts` adds `collectAgentDriftAdvisories` + `writeDriftAdvisorySummary` helpers; wired into the `--no-repair` boot path (preflight provider-degraded, post-startup degraded, AND the all-clear path) and the `inner.status` command. Operators see drift advisories without running `ouro inner status` per agent.",
+        "Daemon-wide drift visibility (post-review fix from ouroboros): `DaemonHealthState` gains a required `drift: DriftFinding[]` field, populated by `buildDaemonHealthState` from the per-agent drift probe. `renderRollupStatusLine`'s `partial` branch now distinguishes three sub-cases — agents-unhealthy-only, drift-only, and both — so a drift-induced `partial` rollup carries a clear cause rather than the misleading 'some agents unhealthy' copy. `readHealth` tolerates legacy cached health files missing the field (defaults to `[]`).",
+        "9874 tests pass. 100% coverage on all new and changed source files. Typecheck clean. Lint clean. Layer 3 (RepairGuide) consumes the `driftFindings` array surfaced here — Layer 3 is where drift findings cease to be advisory and become actionable. Layer 2 (sync probe) is independent of this PR."
+      ]
+    },
+    {
+      "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/agent-config-check.js

@@ -47,6 +47,7 @@ const provider_credentials_1 = require("../provider-credentials");
 const vault_unlock_1 = require("../../repertoire/vault-unlock");
 const readiness_repair_1 = require("./readiness-repair");
 const provider_ping_progress_1 = require("./provider-ping-progress");
+const drift_detection_1 = require("./drift-detection");
 function isAgentProvider(value) {
     return Object.prototype.hasOwnProperty.call(identity_1.PROVIDER_CREDENTIALS, value);
 }
@@ -387,6 +388,26 @@ async function checkAgentConfigWithProviderHealth(agentName, bundlesRoot, deps =
         return stateResult.result;
     if (stateResult.disabled)
         return { ok: true };
+    // Layer 4 drift detection. Runs once per call after state setup so that
+    // drift findings ride along regardless of ping outcome — consumers
+    // (Layer 4 rollup, Layer 3 RepairGuide) want to see drift even when a
+    // live-check is failing for unrelated reasons. Drift detection is pure
+    // and never throws on a malformed agent.json: any read error here would
+    // indicate the bundle disappeared between state setup and now (a
+    // race), which we surface as `[]` rather than a hard failure.
+    let driftFindings = [];
+    try {
+        const inputs = (0, drift_detection_1.loadDriftInputsForAgent)(bundlesRoot, agentName);
+        driftFindings = (0, drift_detection_1.detectProviderBindingDrift)({
+            agentName,
+            agentJson: inputs.agentJson,
+            providerState: inputs.providerState,
+        });
+    }
+    catch {
+        /* v8 ignore next 1 -- defensive race-window guard: agent.json went away after state setup. Tested via Unit 5 integration when at all. @preserve */
+        driftFindings = [];
+    }
     deps.onProgress?.(selectedProviderPlan(agentName, stateResult.state));
     const ping = deps.pingProvider ?? (await Promise.resolve().then(() => __importStar(require("../provider-ping")))).pingProvider;
     const shouldRecordReadiness = deps.recordReadiness ?? true;
@@ -402,16 +423,16 @@ async function checkAgentConfigWithProviderHealth(agentName, bundlesRoot, deps =
         const binding = stateResult.state.lanes[lane];
         if (!poolResult.ok) {
             if (poolResult.reason === "missing") {
-                return missingCredentialResult(agentName, lane, binding.provider, binding.model, poolResult.poolPath);
+                return { ...missingCredentialResult(agentName, lane, binding.provider, binding.model, poolResult.poolPath), driftFindings };
             }
-            return invalidPoolResult(agentName, lane, binding.provider, binding.model, {
-                ...poolResult,
-                reason: poolResult.reason,
-            });
+            return { ...invalidPoolResult(agentName, lane, binding.provider, binding.model, {
+                    ...poolResult,
+                    reason: poolResult.reason,
+                }), driftFindings };
         }
         const record = credentialRecordForLane(poolResult.pool, binding.provider);
         if (!record) {
-            return missingCredentialResult(agentName, lane, binding.provider, binding.model, poolResult.poolPath);
+            return { ...missingCredentialResult(agentName, lane, binding.provider, binding.model, poolResult.poolPath), driftFindings };
         }
         const key = `${binding.provider}\0${binding.model}\0${record.revision}`;
         const group = pingGroups.get(key);
@@ -475,7 +496,7 @@ async function checkAgentConfigWithProviderHealth(agentName, bundlesRoot, deps =
         }
     }
     if (firstFailure)
-        return firstFailure;
+        return { ...firstFailure, driftFindings };
     (0, runtime_1.emitNervesEvent)({
         component: "daemon",
         event: "daemon.agent_config_valid",
@@ -484,7 +505,8 @@ async function checkAgentConfigWithProviderHealth(agentName, bundlesRoot, deps =
             agent: agentName,
             providers: [...new Set([...pingGroups.values()].map((group) => group.provider))],
             liveProviderCheck: true,
+            driftCount: driftFindings.length,
         },
     });
-    return { ok: true };
+    return { ok: true, driftFindings };
 }

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

@@ -40,6 +40,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.summarizeDaemonStartupFailure = summarizeDaemonStartupFailure;
+exports.writeDriftAdvisorySummary = writeDriftAdvisorySummary;
+exports.collectAgentDriftAdvisories = collectAgentDriftAdvisories;
 exports.mergeStartupStability = mergeStartupStability;
 exports.ensureDaemonRunning = ensureDaemonRunning;
 exports.listGithubCopilotModels = listGithubCopilotModels;
@@ -94,6 +96,7 @@ const cli_help_1 = require("./cli-help");
 const cli_render_1 = require("./cli-render");
 const cli_defaults_1 = require("./cli-defaults");
 const agent_config_check_1 = require("./agent-config-check");
+const drift_detection_1 = require("./drift-detection");
 const doctor_1 = require("./doctor");
 const cli_render_doctor_1 = require("./cli-render-doctor");
 const interactive_repair_1 = require("./interactive-repair");
@@ -408,6 +411,61 @@ function writeProviderRepairSummary(deps, title, degraded) {
     const blocks = degraded.map((entry) => (0, readiness_repair_1.renderReadinessIssueNextSteps)(readinessIssueFromDegraded(entry)).join("\n"));
     deps.writeStdout([title, ...blocks].join("\n\n"));
 }
+/**
+ * Layer 4: render a per-agent drift advisory block to stdout. Called from
+ * the `--no-repair` summary path when one or more enabled agents have a
+ * mismatch between `agent.json` (intent) and `state/providers.json`
+ * (observation). The block surfaces the lane, intent vs observed
+ * binding, and the copy-pasteable `ouro use` repair command per finding.
+ *
+ * Drift is advisory: this helper only PRINTS the advisory; running the
+ * repair command is the operator's call (and is Layer 3 RepairGuide's
+ * domain when the daemon does it automatically).
+ *
+ * Exported for direct unit-testing; the production callers are
+ * inside this module.
+ */
+function writeDriftAdvisorySummary(deps, advisories) {
+    if (advisories.length === 0)
+        return;
+    const lines = ["Drift advisory: agent intent does not match this machine's observed binding"];
+    for (const advisory of advisories) {
+        lines.push("");
+        lines.push(`  ${advisory.agent} (${advisory.lane}):`);
+        lines.push(`    intent:   ${advisory.intentProvider}/${advisory.intentModel}`);
+        lines.push(`    observed: ${advisory.observedProvider}/${advisory.observedModel}`);
+        lines.push(`    repair:   ${advisory.repairCommand}`);
+    }
+    deps.writeStdout(lines.join("\n"));
+}
+/**
+ * Collect drift findings across every enabled agent in the bundles
+ * directory. Used by the `--no-repair` summary path so that drift
+ * advisories ride along with (or stand alone in place of) the existing
+ * provider-repair summary. Errors during a single agent's load (e.g.
+ * malformed `agent.json`) are swallowed: drift detection is advisory
+ * and must not block the rest of the boot path.
+ */
+async function collectAgentDriftAdvisories(deps) {
+    const agents = await listCliAgents(deps);
+    const bundlesRoot = deps.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)();
+    const findings = [];
+    for (const agent of [...new Set(agents)]) {
+        try {
+            const inputs = (0, drift_detection_1.loadDriftInputsForAgent)(bundlesRoot, agent);
+            const agentFindings = (0, drift_detection_1.detectProviderBindingDrift)({
+                agentName: agent,
+                agentJson: inputs.agentJson,
+                providerState: inputs.providerState,
+            });
+            findings.push(...agentFindings);
+        }
+        catch {
+            // Best-effort: a per-agent read failure is not blocking.
+        }
+    }
+    return findings;
+}
 function providerRepairCountSummary(count) {
     if (count === 0)
         return "selected providers answered live checks";
@@ -5661,6 +5719,13 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
                 progress.end();
                 if (command.noRepair) {
                     writeProviderRepairSummary(deps, "Provider checks need attention", preflightProviderDegraded);
+                    // Layer 4: drift advisories ride along with the provider-repair
+                    // summary under --no-repair. Non-blocking; failure to collect
+                    // findings (e.g. malformed agent.json on one bundle) is swallowed
+                    // by `collectAgentDriftAdvisories` so the rest of the boot path
+                    // is unaffected.
+                    const driftAdvisories = await collectAgentDriftAdvisories(deps);
+                    writeDriftAdvisorySummary(deps, driftAdvisories);
                     const message = "daemon not started: provider checks need repair. Run `ouro repair` or rerun `ouro up` to choose a repair path.";
                     return returnCliFailure(deps, message);
                 }
@@ -5716,12 +5781,19 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
             if (command.noRepair) {
                 // --no-repair: write degraded summary and skip interactive repair
                 writeProviderRepairSummary(deps, "Provider checks need attention", daemonResult.stability.degraded);
+                // Layer 4: drift advisories ride along with the post-startup
+                // degraded summary too — same rationale as the preflight path.
+                const driftAdvisories = await collectAgentDriftAdvisories(deps);
+                writeDriftAdvisorySummary(deps, driftAdvisories);
                 (0, runtime_1.emitNervesEvent)({
                     level: "warn",
                     component: "daemon",
                     event: "daemon.no_repair_degraded_summary",
                     message: "degraded agents detected with --no-repair, skipping interactive repair",
-                    meta: { degradedCount: daemonResult.stability.degraded.length },
+                    meta: {
+                        degradedCount: daemonResult.stability.degraded.length,
+                        driftCount: driftAdvisories.length,
+                    },
                 });
             }
             else {
@@ -5796,6 +5868,13 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
                 }
             }
         }
+        else if (command.noRepair) {
+            // Layer 4: no degraded agents to summarize, but --no-repair still
+            // surfaces drift advisories so the operator sees them without
+            // having to run `ouro inner status` per agent.
+            const driftAdvisories = await collectAgentDriftAdvisories(deps);
+            writeDriftAdvisorySummary(deps, driftAdvisories);
+        }
         // Persist boot startup AFTER daemon is running — bootstrap is safe now
         // because the daemon socket exists, so launchd's KeepAlive registers
         // for crash recovery without starting a competing process.
@@ -6903,6 +6982,22 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
             catch { /* no habits — heartbeat unknown */ }
             // Attention count
             const activeObligations = listActiveReturnObligations(command.agent);
+            // Layer 4 drift findings for this agent. Best-effort: if agent.json
+            // is unreadable mid-call we just suppress the advisory rather than
+            // failing the inner-status render.
+            let driftFindings = [];
+            try {
+                const bundlesRoot = deps.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)();
+                const inputs = (0, drift_detection_1.loadDriftInputsForAgent)(bundlesRoot, command.agent);
+                driftFindings = (0, drift_detection_1.detectProviderBindingDrift)({
+                    agentName: command.agent,
+                    agentJson: inputs.agentJson,
+                    providerState: inputs.providerState,
+                });
+            }
+            catch {
+                driftFindings = [];
+            }
             const message = buildInnerStatusOutput({
                 agentName: command.agent,
                 runtimeState,
@@ -6910,6 +7005,7 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
                 heartbeat,
                 attentionCount: activeObligations.length,
                 now: Date.now(),
+                driftFindings,
             });
             deps.writeStdout(message);
             return message;

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,93 @@ 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": {
+            // `partial` arises from two independent sources:
+            //   (a) some enabled agents not in `running` state, or
+            //   (b) Layer-4 drift between agent.json (intent) and state/providers.json (observed).
+            // Either or both can be true. Render mentions both when applicable so
+            // the operator isn't misled into thinking agents are unhealthy when the
+            // only anomaly is configuration drift.
+            const unhealthyCount = Object.values(health.agents).filter((agent) => agent.status !== "running").length;
+            const driftCount = (health.drift ?? []).length;
+            const parts = [];
+            if (unhealthyCount > 0) {
+                parts.push(`${unhealthyCount} agent${unhealthyCount === 1 ? "" : "s"} unhealthy`);
+            }
+            if (driftCount > 0) {
+                parts.push(`drift on ${driftCount} agent${driftCount === 1 ? "" : "s"}`);
+            }
+            // Fallback for legacy cached files: status="partial" with no
+            // visible cause (no unhealthy agents AND no drift array). This
+            // happens when the file pre-dates Layer 4 and the daemon flagged
+            // partial via some signal that's no longer expressible. Prompt
+            // refresh via `ouro up` rather than asserting a specific cause.
+            const detail = parts.length > 0
+                ? ` — ${parts.join("; ")}`
+                : " — stale cache, run `ouro up` to refresh";
+            return `Last known status: partial${detail} ${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 +603,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");
@@ -55,6 +56,7 @@ 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");
@@ -173,18 +175,75 @@ 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 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: degraded.length > 0 ? "degraded" : "ok",
+        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,
             {

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" ||
@@ -123,6 +157,12 @@ function readHealth(healthPath) {
             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,
@@ -131,6 +171,7 @@ function readHealth(healthPath) {
             uptimeSeconds: parsed.uptimeSeconds,
             safeMode: parsed.safeMode,
             degraded: parsed.degraded,
+            drift,
             agents: parsed.agents,
             habits: parsed.habits,
         };

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";
+}

package/dist/heart/daemon/drift-detection.js

@@ -0,0 +1,146 @@
+"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.detectProviderBindingDrift = detectProviderBindingDrift;
+exports.loadDriftInputsForAgent = loadDriftInputsForAgent;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const provider_state_1 = require("../provider-state");
+/**
+ * Pull the per-lane intent out of an agent.json view, preferring the new
+ * `outward`/`inner` keys over the legacy `humanFacing`/`agentFacing` keys
+ * when both are present. Returns `null` if neither set carries a usable
+ * binding for this lane (the comparator treats that as "no intent to
+ * compare against" and emits no drift for that lane).
+ */
+function resolveLaneIntent(agentJson, lane) {
+    const newKey = lane === "outward" ? agentJson.outward : agentJson.inner;
+    if (newKey && typeof newKey.provider === "string" && typeof newKey.model === "string") {
+        return { provider: newKey.provider, model: newKey.model };
+    }
+    const legacy = lane === "outward" ? agentJson.humanFacing : agentJson.agentFacing;
+    if (legacy && typeof legacy.provider === "string" && typeof legacy.model === "string") {
+        return { provider: legacy.provider, model: legacy.model };
+    }
+    return null;
+}
+function buildRepairCommand(agentName, lane, provider, model) {
+    return `ouro use --agent ${agentName} --lane ${lane} --provider ${provider} --model ${model}`;
+}
+/**
+ * Pure intent-vs-observed comparator. Emits one `DriftFinding` per lane
+ * whose intent (agent.json) does not match its observation
+ * (state/providers.json).
+ *
+ * Returns `[]` when:
+ * - `providerState === null` (fresh install, nothing to drift against), OR
+ * - both lanes match, OR
+ * - a lane has no intent in agent.json AND no observation in providerState
+ *   (deferred to other layers — drift detection is silent on that lane).
+ */
+function detectProviderBindingDrift(input) {
+    if (input.providerState === null) {
+        return [];
+    }
+    const findings = [];
+    const lanes = ["outward", "inner"];
+    for (const lane of lanes) {
+        const intent = resolveLaneIntent(input.agentJson, lane);
+        if (!intent)
+            continue;
+        const observed = input.providerState.lanes[lane];
+        if (intent.provider === observed.provider && intent.model === observed.model) {
+            continue;
+        }
+        findings.push({
+            agent: input.agentName,
+            lane,
+            intentProvider: intent.provider,
+            intentModel: intent.model,
+            observedProvider: observed.provider,
+            observedModel: observed.model,
+            reason: "provider-model-changed",
+            repairCommand: buildRepairCommand(input.agentName, lane, intent.provider, intent.model),
+        });
+    }
+    return findings;
+}
+function agentRootFor(bundlesRoot, agentName) {
+    return path.join(bundlesRoot, `${agentName}.ouro`);
+}
+function readAgentJson(agentJsonPath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(agentJsonPath, "utf-8");
+    }
+    catch {
+        throw new Error(`agent.json not found at ${agentJsonPath}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`agent.json at ${agentJsonPath} contains invalid JSON: ${String(error)}`);
+    }
+    // The drift loader is intentionally permissive: it parses the file as a
+    // typed `AgentConfig` view but does not validate every field. The
+    // comparator (Unit 1) is the one that decides which intent fields are
+    // usable; non-conforming bindings just silently skip drift detection
+    // on that lane. Stricter validation belongs to `loadAgentConfig` in
+    // identity.ts (which also has side effects we don't want here).
+    return parsed;
+}
+/**
+ * Loader for the drift comparator. Reads the per-agent `agent.json` and
+ * `state/providers.json` off disk, returning typed inputs ready to feed
+ * into `detectProviderBindingDrift`.
+ *
+ * - Throws when `agent.json` is missing or unparseable. The caller decides
+ *   whether to swallow (drift detection has no opinion on a broken
+ *   `agent.json` — that's the existing `agent-config-check` flow's job).
+ * - Returns `providerState: null` when `state/providers.json` is missing
+ *   (fresh install) or invalid (the comparator interprets `null` as "no
+ *   observation, nothing to drift against").
+ * - Never writes to disk.
+ */
+function loadDriftInputsForAgent(bundlesRoot, agentName) {
+    const agentRoot = agentRootFor(bundlesRoot, agentName);
+    const agentJsonPath = path.join(agentRoot, "agent.json");
+    const agentJson = readAgentJson(agentJsonPath);
+    const stateResult = (0, provider_state_1.readProviderState)(agentRoot);
+    const providerState = stateResult.ok ? stateResult.state : null;
+    return { agentJson, providerState };
+}

package/dist/heart/daemon/inner-status.js

@@ -74,6 +74,18 @@ function buildInnerStatusOutput(input) {
     // Attention
     const thoughtWord = attentionCount === 1 ? "thought" : "thoughts";
     lines.push(`  attention: ${attentionCount} held ${thoughtWord}`);
+    // Layer 4 drift advisory. Renders one line per finding with the
+    // lane, intent vs observed binding, and the copy-pasteable repair
+    // command. Suppressed entirely when no findings exist (or the field
+    // is absent — pre-Layer-4 callers).
+    const driftFindings = input.driftFindings ?? [];
+    if (driftFindings.length > 0) {
+        lines.push("  drift advisory:");
+        for (const finding of driftFindings) {
+            lines.push(`    - ${finding.lane}: intent ${finding.intentProvider}/${finding.intentModel} vs observed ${finding.observedProvider}/${finding.observedModel}`);
+            lines.push(`      repair: ${finding.repairCommand}`);
+        }
+    }
     (0, runtime_1.emitNervesEvent)({
         component: "daemon",
         event: "daemon.inner_status_read",
@@ -83,6 +95,7 @@ function buildInnerStatusOutput(input) {
             status: runtimeState?.status ?? "unknown",
             journalCount: journalFiles.length,
             attentionCount,
+            driftCount: driftFindings.length,
         },
     });
     return lines.join("\n");

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,22 @@ 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",
+    // Drift comparator + thin I/O loader: `detectProviderBindingDrift`
+    // is a pure intent-vs-observed comparator with no side effects;
+    // `loadDriftInputsForAgent` is a small fs-read wrapper that returns
+    // `null` on missing/invalid state rather than emitting. The caller
+    // (daemon-entry.ts buildDaemonHealthState's per-agent drift probe)
+    // owns observability — drift findings ride along through
+    // `daemon.health_written` as part of the rolled-up state, and
+    // `agent-config-check.ts` carries `driftFindings` through its
+    // existing instrumentation. Same pattern as `daemon-rollup`.
+    "daemon/drift-detection",
     // 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.517",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
     "cli": "dist/heart/daemon/ouro-bot-entry.js",