@kal-elsam/kairo-runtime 0.4.2 → 0.5.0

package/src/global/control-plane-proposals.js

@@ -0,0 +1,229 @@
+/**
+ * Deterministic evidence-backed control-plane proposals.
+ * Optional intelligence absence never yields a proposal.
+ * Health strings match CONTROL_PLANE_HEALTH in control-plane-snapshot.js.
+ */
+
+export const PROPOSAL_SEVERITY = Object.freeze({
+  HIGH: "high",
+  MEDIUM: "medium",
+  LOW: "low",
+  INFO: "info"
+});
+
+export const PROPOSAL_DESTINATION = Object.freeze({
+  CHANGES: "changes",
+  CONTROL_CENTER: "control-center",
+  IDES: "ides",
+  MODULES: "modules",
+  ACTIVITY: "activity",
+  PROFILE: "profile"
+});
+
+const SEVERITY_RANK = Object.freeze({
+  high: 0,
+  medium: 1,
+  low: 2,
+  info: 3
+});
+
+const ACTIONABLE = new Set(["missing", "stale", "warning", "failed"]);
+
+/**
+ * Derive proposals only from status, checks, diff, adapters, and policy.
+ * No proposal without evidence; deduped by id; severity then id order.
+ */
+export function buildControlPlaneProposals({
+  health = null,
+  status = null,
+  adapters = null,
+  policy = null,
+  diff = null
+} = {}) {
+  const out = [];
+
+  if (health === "NOT_CONFIGURED" || status?.overall === "missing") {
+    out.push(make(
+      "setup-local",
+      PROPOSAL_SEVERITY.HIGH,
+      "Finish local setup",
+      status?.nextAction ?? "Configure the local ecosystem before applying repairs.",
+      PROPOSAL_DESTINATION.CHANGES,
+      [
+        ev("status", "status.overall", status?.overall ?? "missing"),
+        ev("health", "control-plane.health", health ?? "NOT_CONFIGURED")
+      ]
+    ));
+  }
+
+  const hasDiff = Boolean(diff?.hasChanges);
+  const isDrift = status?.overall === "drift" || health === "ACTION_REQUIRED";
+  // Gate on health/overall drift only. diff.hasChanges can be true from
+  // needsManagedRepair SDD integration warnings while overall stays "ok".
+  if (isDrift) {
+    const evidence = [
+      ...(diff?.changes ?? []).slice(0, 8).map((change) =>
+        ev("diff", "diff.change", change.target ?? change.path ?? change.action ?? "managed-change")),
+      ...(status?.checks ?? [])
+        .filter((check) => (check.status === "stale" || check.status === "missing") && !isIntel(check))
+        .slice(0, 8)
+        .map((check) => ev("check", `status.checks.${check.name}`, check.status)),
+      ev("status", "status.overall", status?.overall ?? "drift")
+    ];
+    out.push(make(
+      "repair-drift",
+      PROPOSAL_SEVERITY.HIGH,
+      "Review and repair managed drift",
+      status?.nextAction
+        ?? (hasDiff
+          ? `${diff.changeCount ?? diff.changes?.length ?? 0} managed change(s) pending preview.`
+          : "Managed content has drifted from the expected inventory."),
+      PROPOSAL_DESTINATION.CHANGES,
+      evidence
+    ));
+  }
+
+  if (health === "CHECK_FAILED" || status?.overall === "failed") {
+    const failed = (status?.checks ?? [])
+      .filter((check) => (check.status === "failed" || check.status === "missing") && !isIntel(check));
+    if (failed.length === 0) {
+      out.push(make(
+        "verify-failed-overall",
+        PROPOSAL_SEVERITY.HIGH,
+        "Investigate failed governance checks",
+        status?.nextAction ?? "Doctor reported a failed overall status.",
+        PROPOSAL_DESTINATION.CONTROL_CENTER,
+        [ev("status", "status.overall", status?.overall ?? "failed")]
+      ));
+    } else {
+      for (const check of failed) {
+        out.push(make(
+          `verify-check-${slug(check.name)}`,
+          PROPOSAL_SEVERITY.HIGH,
+          `Investigate check: ${check.name}`,
+          check.detail ?? `Check status is ${check.status}.`,
+          PROPOSAL_DESTINATION.CONTROL_CENTER,
+          [
+            ev("check", `status.checks.${check.name}`, check.status),
+            ev("status", "status.overall", status?.overall ?? "failed")
+          ]
+        ));
+      }
+    }
+  }
+
+  const matrix = adapters?.adapters ?? status?.agents ?? [];
+  for (const entry of matrix) {
+    if (!entry?.detected || entry.managed) continue;
+    out.push(make(
+      `govern-adapter-${slug(entry.id)}`,
+      PROPOSAL_SEVERITY.MEDIUM,
+      `Govern detected agent: ${entry.id}`,
+      `${entry.id} is detected locally but not managed by Kairo.`,
+      PROPOSAL_DESTINATION.IDES,
+      [
+        ev("adapter", `adapters.${entry.id}.detected`, "true"),
+        ev("adapter", `adapters.${entry.id}.managed`, "false")
+      ]
+    ));
+  }
+
+  const effective = policy ?? status?.policy ?? null;
+  if (effective?.applyMode && effective.applyMode !== "confirm") {
+    out.push(make(
+      "review-policy-apply-mode",
+      PROPOSAL_SEVERITY.LOW,
+      "Review apply mode policy",
+      `Effective applyMode is "${effective.applyMode}". Confirm intentional deviation from confirm-gated applies.`,
+      PROPOSAL_DESTINATION.PROFILE,
+      [ev("policy", "policy.applyMode", String(effective.applyMode))]
+    ));
+  }
+
+  for (const check of status?.checks ?? []) {
+    if (isIntel(check) || !ACTIONABLE.has(check.status)) continue;
+
+    if (isExternal(check)) {
+      out.push(make(
+        `external-${slug(check.name)}`,
+        check.status === "missing" || check.status === "failed"
+          ? PROPOSAL_SEVERITY.MEDIUM
+          : PROPOSAL_SEVERITY.LOW,
+        `Review external integration: ${check.name}`,
+        externalDetail(check.detail ?? `Check status is ${check.status}.`),
+        PROPOSAL_DESTINATION.MODULES,
+        [
+          ev("check", `status.checks.${check.name}`, check.status),
+          ev("integration", "check.category", check.category ?? "integration")
+        ]
+      ));
+      continue;
+    }
+
+    if (check.status !== "warning" && check.status !== "stale") continue;
+    const isBackup = check.category === "backups";
+    out.push(make(
+      `warning-${slug(check.name)}`,
+      isBackup ? PROPOSAL_SEVERITY.INFO : PROPOSAL_SEVERITY.LOW,
+      isBackup ? `Note: ${check.name}` : `Review note: ${check.name}`,
+      check.detail ?? `Check status is ${check.status}.`,
+      isBackup ? PROPOSAL_DESTINATION.ACTIVITY : PROPOSAL_DESTINATION.CONTROL_CENTER,
+      [ev("check", `status.checks.${check.name}`, check.status)]
+    ));
+  }
+
+  return finalize(out);
+}
+
+function finalize(candidates) {
+  const byId = new Map();
+  for (const item of candidates) {
+    if (!item?.id || !item.evidence?.length) continue;
+    if (!byId.has(item.id)) byId.set(item.id, item);
+  }
+  return [...byId.values()].sort((left, right) => {
+    const rank = (SEVERITY_RANK[left.severity] ?? 99) - (SEVERITY_RANK[right.severity] ?? 99);
+    return rank !== 0 ? rank : left.id.localeCompare(right.id);
+  });
+}
+
+function make(id, severity, title, detail, destination, evidence) {
+  return {
+    id,
+    severity,
+    title,
+    detail,
+    destination,
+    evidence: evidence.map((entry) => ({
+      type: String(entry.type),
+      source: String(entry.source),
+      ref: String(entry.ref)
+    }))
+  };
+}
+
+function ev(type, source, ref) {
+  return { type, source, ref: String(ref) };
+}
+
+function isIntel(check) {
+  return check?.category === "intelligence" || check?.name === "intelligence providers";
+}
+
+function isExternal(check) {
+  const name = check?.name ?? "";
+  return name.startsWith("engram:") || name.startsWith("graphify:");
+}
+
+function externalDetail(detail) {
+  if (/runtime.?active|not runtime/i.test(detail)) return detail;
+  return `${detail} Configuration/version/freshness evidence only — not a claim of active runtime.`;
+}
+
+function slug(value) {
+  return String(value ?? "unknown")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    || "unknown";
+}

package/src/global/control-plane-snapshot.js

@@ -0,0 +1,212 @@
+import { buildAdapterMatrixReport } from "./adapter-matrix.js";
+import { listBackupSnapshots } from "./backups.js";
+import { buildDiffReport } from "./diff.js";
+import { buildExplainReport } from "./explain.js";
+import { getHistoryPath, readHistoryEvents } from "./history.js";
+import { harnessHomePaths } from "./paths.js";
+import { buildStatusReport } from "./status.js";
+import { buildControlPlaneJson } from "./json-output.js";
+import { formatCliCommand } from "./brand/cli.js";
+import { buildRuntimeDashboardData } from "./runtime/run-cli.js";
+import { describeBackupSnapshots } from "./rollback.js";
+import { buildControlPlaneProposals } from "./control-plane-proposals.js";
+
+/**
+ * Global control-plane health. Optional intelligence absence must never
+ * degrade these states by itself.
+ */
+export const CONTROL_PLANE_HEALTH = {
+  NOT_CONFIGURED: "NOT_CONFIGURED",
+  ACTION_REQUIRED: "ACTION_REQUIRED",
+  HEALTHY_WITH_NOTES: "HEALTHY_WITH_NOTES",
+  HEALTHY: "HEALTHY",
+  CHECK_FAILED: "CHECK_FAILED"
+};
+
+export const CONTROL_PLANE_CTA = {
+  SETUP: "setup",
+  REPAIR: "repair",
+  VERIFY: "verify",
+  REVIEW: "review",
+  IDLE: "idle"
+};
+
+/**
+ * Pure mapping from status.overall + warning counts to control-plane health.
+ * Does not inspect intelligence backends.
+ */
+export function resolveControlPlaneHealth(status) {
+  if (!status || status.state == null || status.overall === "missing") {
+    return CONTROL_PLANE_HEALTH.NOT_CONFIGURED;
+  }
+
+  if (status.overall === "failed") {
+    return CONTROL_PLANE_HEALTH.CHECK_FAILED;
+  }
+
+  if (status.overall === "drift") {
+    return CONTROL_PLANE_HEALTH.ACTION_REQUIRED;
+  }
+
+  if ((status.counts?.warning ?? 0) > 0) {
+    return CONTROL_PLANE_HEALTH.HEALTHY_WITH_NOTES;
+  }
+
+  return CONTROL_PLANE_HEALTH.HEALTHY;
+}
+
+/**
+ * Prefer setup / repairs / verification before launching runs.
+ */
+export function resolveControlPlaneCta({ health, status, diff } = {}) {
+  switch (health) {
+    case CONTROL_PLANE_HEALTH.NOT_CONFIGURED:
+      return {
+        kind: CONTROL_PLANE_CTA.SETUP,
+        title: "Finish local setup",
+        detail: status?.nextAction
+          ?? `Run ${formatCliCommand("setup")} to configure the local ecosystem.`,
+        destination: "changes"
+      };
+    case CONTROL_PLANE_HEALTH.ACTION_REQUIRED:
+      return {
+        kind: CONTROL_PLANE_CTA.REPAIR,
+        title: "Review and repair drift",
+        detail: status?.nextAction
+          ?? `Preview repairs with ${formatCliCommand("diff")}, then confirm sync.`,
+        destination: "changes"
+      };
+    case CONTROL_PLANE_HEALTH.CHECK_FAILED:
+      return {
+        kind: CONTROL_PLANE_CTA.VERIFY,
+        title: "Investigate failed checks",
+        detail: status?.nextAction
+          ?? `Run ${formatCliCommand("doctor")} for details.`,
+        destination: "control-center"
+      };
+    case CONTROL_PLANE_HEALTH.HEALTHY_WITH_NOTES:
+      return {
+        kind: CONTROL_PLANE_CTA.REVIEW,
+        title: "Review notes",
+        detail: diff?.hasChanges
+          ? "Some notes remain after a healthy scan. Open Changes to inspect."
+          : "Ecosystem is healthy with non-blocking notes.",
+        destination: "control-center"
+      };
+    case CONTROL_PLANE_HEALTH.HEALTHY:
+      return {
+        kind: CONTROL_PLANE_CTA.IDLE,
+        title: "Ecosystem healthy",
+        detail: status?.nextAction ?? "No governance action required.",
+        destination: "control-center"
+      };
+    default: {
+      const _exhaustive = health;
+      return {
+        kind: CONTROL_PLANE_CTA.VERIFY,
+        title: "Review control plane",
+        detail: String(_exhaustive),
+        destination: "control-center"
+      };
+    }
+  }
+}
+
+/**
+ * Read-only control-plane snapshot composed from existing engines.
+ * Never writes. Optional intelligence is intentionally omitted from health.
+ */
+export async function buildControlPlaneSnapshot({
+  homeDir,
+  workspaceRoot = null,
+  packageName,
+  packageRoot,
+  cliVersion,
+  includeDiff = true,
+  includeExplain = false,
+  includeRuntime = true,
+  historyLimit = 20
+} = {}) {
+  const status = await buildStatusReport(homeDir, { packageRoot, workspaceRoot });
+  const adapters = await buildAdapterMatrixReport(homeDir);
+  const history = await readHistoryEvents(homeDir, { limit: historyLimit });
+  const backupSnapshots = await describeBackupSnapshots(
+    harnessHomePaths(homeDir).backupsDir
+  ).catch(async () => {
+    const names = await listBackupSnapshots(harnessHomePaths(homeDir).backupsDir);
+    return names.map((name) => ({ name, fileCount: null }));
+  });
+
+  const diff = includeDiff
+    ? await buildDiffReport(homeDir, {
+      packageRoot,
+      packageName,
+      cliVersion,
+      workspaceRoot
+    })
+    : null;
+
+  const explain = includeExplain
+    ? await buildExplainReport(homeDir)
+    : null;
+
+  const runtime = includeRuntime
+    ? await buildRuntimeDashboardData({ homeDir, workspaceRoot, cliVersion })
+    : null;
+
+  const health = resolveControlPlaneHealth(status);
+  const cta = resolveControlPlaneCta({ health, status, diff });
+  const proposals = buildControlPlaneProposals({
+    health,
+    status,
+    adapters,
+    policy: status.policy,
+    diff
+  });
+
+  const governedAgents = (adapters.adapters ?? []).filter((entry) => entry.managed).length;
+  const detectedAgents = (adapters.adapters ?? []).filter((entry) => entry.detected).length;
+
+  return {
+    readOnly: true,
+    scannedAt: new Date().toISOString(),
+    cliVersion,
+    packageName,
+    homeDir,
+    workspaceRoot,
+    health,
+    cta,
+    proposals,
+    coverage: {
+      detectedAgents,
+      governedAgents,
+      components: status.components?.length ?? 0,
+      activeModules: (status.components ?? [])
+        .filter((entry) => entry.status === "ok")
+        .map((entry) => entry.id)
+    },
+    status,
+    adapters,
+    policy: status.policy,
+    backups: {
+      count: status.backups,
+      snapshots: backupSnapshots
+    },
+    history: {
+      path: getHistoryPath(homeDir),
+      limit: historyLimit,
+      events: history.events,
+      warnings: history.warnings
+    },
+    diff,
+    explain,
+    runtime: runtime
+      ? {
+        activeRuns: runtime.activeRuns?.length ?? 0,
+        recentRuns: runtime.recentRuns?.length ?? 0,
+        providers: runtime.providers ?? []
+      }
+      : null,
+    envelope: buildControlPlaneJson(status, { cliVersion })
+  };
+}

package/src/global/dashboard-guidance.js

@@ -42,7 +42,11 @@ export function countLaunchableAgents(dashboard = null) {
 
 export function hasIntelligenceConfigured(diagnostics = null) {
   const summary = diagnostics?.intelligence?.summary;
-  return Boolean(summary?.localAvailable || summary?.cloudAuthenticated);
+  return Boolean(
+    summary?.localAvailable
+    || summary?.cloudConfigured
+    || summary?.cloudAuthenticated
+  );
 }
 
 function hasBlockingDiagnostics(diagnostics = null) {
@@ -174,17 +178,37 @@ export function resolveDashboardRecommendation({
     };
   }
 
-  if (!intelligence?.localAvailable && !intelligence?.cloudAuthenticated) {
+  const intelConfigured = Boolean(
+    intelligence?.localAvailable
+    || intelligence?.cloudConfigured
+    || intelligence?.cloudAuthenticated
+  );
+  if (!intelConfigured) {
     return {
       kind: NEXT_STEP_KINDS.ENABLE_INTELLIGENCE,
       title: "Enable optional intelligence",
-      message: "Enable intelligence: start Ollama or set OPENROUTER_API_KEY, then retry.",
+      message: "Enable intelligence: start Ollama, install OpenCode CLI, or set OPENCODE_API_KEY / OPENROUTER_API_KEY, then retry.",
       detail: "Agents can still run without this optional capability.",
       targetView: RECOMMENDATION_TARGETS.DIAGNOSTICS,
       targetAction: null
     };
   }
 
+  if (
+    !intelligence?.localAvailable
+    && intelligence?.cloudConfigured
+    && !intelligence?.cloudAuthenticated
+  ) {
+    return {
+      kind: NEXT_STEP_KINDS.REVIEW,
+      title: "Inspect intelligence authentication",
+      message: `Cloud intelligence is configured but not authenticated. Run ${formatCliCommand("intelligence status")}.`,
+      detail: "Confirm API key or OpenCode auth evidence before cloud invoke.",
+      targetView: RECOMMENDATION_TARGETS.DIAGNOSTICS,
+      targetAction: null
+    };
+  }
+
   return {
     kind: NEXT_STEP_KINDS.REVIEW,
     title: "Review system health",

package/src/global/diff.js

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { updateGlobalHarness } from "./global-installer.js";
+import { needsManagedRepair } from "./governance-repair.js";
 import { harnessHomePaths } from "./paths.js";
 import { readGlobalState } from "./state.js";
 import { buildStatusReport } from "./status.js";
@@ -31,11 +32,7 @@ export async function buildDiffReport(homeDir, {
   }
 
   const statusReport = await buildStatusReport(homeDir, { packageRoot, workspaceRoot });
-  const needsRepair = statusReport.overall === "drift"
-    || statusReport.counts.missing > 0
-    || statusReport.counts.stale > 0;
-
-  if (!needsRepair) {
+  if (!needsManagedRepair(statusReport)) {
     return {
       homeDir,
       installed: true,

package/src/global/global-cli.js

@@ -404,7 +404,7 @@ export async function runGlobalDoctor(packageRoot, {
     return report;
   }
 
-  const { checks, ok, hasDrift } = await runGlobalDoctorChecks(homeDir, { packageRoot, workspaceRoot });
+  const { checks, ok, hasDrift, componentHealth } = await runGlobalDoctorChecks(homeDir, { packageRoot, workspaceRoot });
 
   console.log(`${BRAND.displayName} doctor (scope: agent-global)`);
   console.log(`Home: ${homeDir}`);
@@ -416,6 +416,14 @@ export async function runGlobalDoctor(packageRoot, {
     console.log(`[${label}] ${check.name}${detail}`);
   }
 
+  if (componentHealth.length > 0) {
+    console.log("");
+    console.log("Components:");
+    for (const entry of componentHealth) {
+      console.log(`  ${entry.id.padEnd(16)} ${entry.status}`);
+    }
+  }
+
   console.log("");
   if (ok) {
     console.log("Status: OK");
@@ -782,7 +790,14 @@ function printComponentEntry(component, { workspace = false } = {}) {
   console.log("");
   console.log(`${component.id} (${component.version}) [${defaultLabel}]`);
   console.log(`  Label: ${component.label}`);
+  console.log(`  Kind: ${component.kind ?? "component"}`);
   console.log(`  Assets: ${component.assetFiles.join(", ")}`);
+  if ((component.dependencies ?? []).length > 0) {
+    console.log(`  Dependencies: ${component.dependencies.join(", ")}`);
+  }
+  if ((component.healthChecks ?? []).length > 0) {
+    console.log(`  Health checks: ${component.healthChecks.map((check) => check.id).join(", ")}`);
+  }
 
   if (component.instructions) {
     console.log(`  Instructions: ${component.instructions}`);

package/src/global/global-doctor.js

@@ -1,13 +1,24 @@
 import { listBackupSnapshots } from "./backups.js";
 import { buildAdapterContext } from "./adapter-context.js";
+import { buildComponentHealthEntries } from "./component-health.js";
 import { runComponentEcosystemChecks } from "./component-ecosystem-checks.js";
 import { detectGlobalDrift, hasRepairableDrift } from "./drift.js";
 import { harnessHomePaths } from "./paths.js";
 import { resolveComponent } from "./component-registry.js";
 import { readGlobalState } from "./state.js";
 import { formatCliCommand } from "./brand/cli.js";
+import {
+  BACKEND_IDS,
+  inspectIntelligenceBackends
+} from "./intelligence/index.js";
 
-export async function runGlobalDoctorChecks(homeDir, { packageRoot, workspaceRoot = null } = {}) {
+export async function runGlobalDoctorChecks(homeDir, {
+  packageRoot,
+  workspaceRoot = null,
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+  inspectBackends = inspectIntelligenceBackends
+} = {}) {
   const paths = harnessHomePaths(homeDir);
   const state = await readGlobalState(paths.statePath);
   const installedComponents = (state?.components ?? []).map((entry) => resolveComponent(entry.id, { workspaceRoot }));
@@ -26,22 +37,84 @@ export async function runGlobalDoctorChecks(homeDir, { packageRoot, workspaceRoo
     checks.push(await backupsCheck(paths));
     checks.push(...await runComponentEcosystemChecks({
       installedComponents,
-      workspaceRoot
+      workspaceRoot,
+      homeDir
     }));
   }
 
+  checks.push(await intelligenceProvidersCheck({ env, fetchImpl, inspectBackends }));
+
   const hasMissing = checks.some((check) => check.status === "missing");
   const hasStale = checks.some((check) => check.status === "stale");
+  const componentHealth = buildComponentHealthEntries(state?.components ?? [], checks);
 
   return {
     checks,
     ok: !hasMissing && !hasStale,
     hasDrift: hasRepairableDrift(checks),
+    componentHealth,
     state,
     paths
   };
 }
 
+async function intelligenceProvidersCheck({ env, fetchImpl, inspectBackends }) {
+  try {
+    const backends = await inspectBackends({ env, fetchImpl });
+    const parts = [];
+
+    if (backends.some((entry) => entry.id === BACKEND_IDS.OLLAMA && entry.available)) {
+      parts.push("Ollama available");
+    }
+
+    const go = backends.find((entry) => entry.id === BACKEND_IDS.OPENCODE_GO);
+    const zen = backends.find((entry) => entry.id === BACKEND_IDS.OPENCODE_ZEN);
+    const runtime = backends.find((entry) => entry.id === BACKEND_IDS.OPENCODE);
+
+    if (go?.configured || go?.hasApiKey) {
+      parts.push(formatCloudProvider("OpenCode Go", go));
+    }
+    if (zen?.configured || zen?.hasApiKey) {
+      parts.push(formatCloudProvider("OpenCode Zen", zen));
+    }
+    if (runtime?.available || runtime?.detected) {
+      const providers = runtime.evidence?.authProviders?.length
+        ? runtime.evidence.authProviders.join(", ")
+        : "CLI installed";
+      parts.push(`OpenCode CLI runtime (${providers}; not authenticated by Kairo)`);
+    }
+    if (backends.some((entry) => entry.id === BACKEND_IDS.OPENROUTER && entry.hasApiKey)) {
+      parts.push("OpenRouter configured (env key; entitlement unverified)");
+    }
+
+    return {
+      name: "intelligence providers",
+      status: "ok",
+      category: "intelligence",
+      detail: parts.length > 0
+        ? `${parts.join("; ")}. Cloud invoke still needs --cloud-consent --yes. API keys never prove subscription or balance.`
+        : `Optional. Start Ollama, install OpenCode CLI, or set OPENCODE_API_KEY / OPENROUTER_API_KEY. See ${formatCliCommand("intelligence status")}.`
+    };
+  } catch (error) {
+    return {
+      name: "intelligence providers",
+      status: "warning",
+      category: "intelligence",
+      detail: `Intelligence provider inspection failed (${error?.message ?? error}). Overall doctor health is unchanged.`
+    };
+  }
+}
+
+function formatCloudProvider(label, entry) {
+  const identity = entry.authenticated
+    ? "authenticated"
+    : entry.configured || entry.hasApiKey
+      ? "configured"
+      : "detected";
+  const entitlement = entry.entitlement ?? "unknown";
+  return `${label} (${identity}; entitlement=${entitlement})`;
+}
+
 function stateOnlyCheck(state) {
   if (!state) {
     return {