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

package/changelog.json

@@ -1,6 +1,18 @@
 {
   "_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": [

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

@@ -496,8 +496,32 @@ function renderRollupStatusLine(health) {
     switch (status) {
         case "healthy":
             return `Last known status: healthy ${tail}`;
-        case "partial":
-            return `Last known status: partial — some agents unhealthy ${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.

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

@@ -56,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");
@@ -183,6 +184,33 @@ function buildDaemonHealthState() {
         ...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
@@ -205,6 +233,7 @@ function buildDaemonHealthState() {
         })),
         bootstrapDegraded: degradedComponents,
         safeMode: false,
+        driftDetected,
     });
     return {
         status: rollupStatus,
@@ -214,6 +243,7 @@ function buildDaemonHealthState() {
         uptimeSeconds: Math.floor(process.uptime()),
         safeMode: null,
         degraded,
+        drift,
         agents: Object.fromEntries(snapshots.map((snapshot) => [
             snapshot.name,
             {

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

@@ -157,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,
@@ -165,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

@@ -50,7 +50,8 @@ function computeDaemonRollup(input) {
     // healthy vs partial.
     const hasUnhealthyAgent = notServing > 0;
     const hasBootstrapDegraded = input.bootstrapDegraded.length > 0;
-    if (hasUnhealthyAgent || hasBootstrapDegraded) {
+    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/nerves/coverage/file-completeness.js

@@ -93,6 +93,16 @@ const DISPATCH_EXEMPT_PATTERNS = [
     // 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.516",
+  "version": "0.1.0-alpha.517",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
     "cli": "dist/heart/daemon/ouro-bot-entry.js",