@kal-elsam/kairo-runtime 0.4.2 → 0.5.0

package/global-template/components/sdd-core/skills/sdd-tasks/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: sdd-tasks
+description: "Break an accepted design into ordered, reviewable tasks."
+---
+
+# SDD Tasks
+
+Use this skill after design to produce a task list that one reviewer can follow without reopening scope.
+
+## References
+- [Phase contract](references/contract.md)
+## Source of truth
+
+- `AGENTS.md`
+- `docs/ai/harness.md`
+- `docs/ai/spec-driven-development.md`
+- `docs/ai/testing.md`
+
+## Workflow
+
+1. Split the design into independent, reviewable units.
+2. Order tasks by dependency and risk.
+3. Attach acceptance and validation to each task.
+4. Keep persona and SDD contracts out of the task bodies.
+
+## Output
+
+```txt
+Task order:
+Dependencies:
+Acceptance per task:
+Validation per task:
+Next skill:
+```

package/global-template/components/sdd-core/skills/sdd-tasks/references/contract.md

@@ -0,0 +1,4 @@
+# sdd-tasks contract
+Activation: After design is stable enough to decompose. Hard rules: Independent reviewable units with acceptance+validation; no persona in bodies.
+Gates: Ordered list ready → sdd-apply · design hole → return to sdd-design Steps: Split units → order by dependency/risk → attach acceptance/validation → stop.
+Output: Task order | Dependencies | Acceptance per task | Validation per task | Next skill

package/global-template/components/sdd-core/skills/sdd-verify/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: sdd-verify
+description: "Validate applied work against acceptance and pipeline gates."
+---
+
+# SDD Verify
+
+Use this skill after implementation to prove the task is done with evidence, not claims.
+
+## References
+- [Phase contract](references/contract.md)
+## Source of truth
+
+- `AGENTS.md`
+- `docs/ai/harness.md`
+- `docs/ai/quality-gates.md`
+- `docs/ai/testing.md`
+
+## Workflow
+
+1. Re-read acceptance criteria for the completed task.
+2. Run the relevant lint, type, test, and smoke checks.
+3. Record failures, skips, and residual risk honestly.
+4. Hand off to archive only when the evidence is complete.
+
+## Output
+
+```txt
+Acceptance checked:
+Commands run:
+Results:
+Residual risk:
+Next skill:
+```

package/global-template/components/sdd-core/skills/sdd-verify/references/contract.md

@@ -0,0 +1,4 @@
+# sdd-verify contract
+Activation: After apply, before archive — prove done with evidence. Hard rules: Evidence over claims; record skips/failures/residual risk honestly.
+Gates: Evidence complete → sdd-archive · acceptance fails → return to sdd-apply Steps: Re-read acceptance → run lint/type/test/smoke → record results → handoff.
+Output: Acceptance checked | Commands run | Results | Residual risk | Next skill

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Kairo Runtime — local agent operating system for Codex, Cursor, Claude, Gemini, Copilot, Engram, and Graphify.",
   "type": "module",
   "homepage": "https://github.com/Kal-elSam/harness#readme",

package/scripts/cockpit-smoke.mjs

@@ -19,13 +19,14 @@ import {
   reduceCockpitUi,
   routeCockpitKey
 } from "../src/global/ink/cockpit-controller.js";
+import { formatProposalLines } from "../src/global/ink/cockpit-proposals.js";
 import { ORCHESTRATOR_VIEWS } from "../src/global/ink/orchestrator-state.js";
 
 const root = join(dirname(fileURLToPath(import.meta.url)), "..");
 const require = createRequire(import.meta.url);
 const pkg = require(join(root, "package.json"));
 
-assert.equal(pkg.version, "0.4.2");
+assert.equal(pkg.version, "0.5.0");
 assert.ok(pkg.dependencies["ansi-escapes"]);
 
 assert.equal(resolveLayoutMode({ columns: 120, rows: 40 }), LAYOUT_MODES.WIDE);
@@ -68,7 +69,7 @@ const mission = buildHomeMissionModel({
   },
   layoutMode: LAYOUT_MODES.MINIMAL
 });
-assert.match(mission.title, /HOME — smoke/);
+assert.match(mission.title, /HOME — smoke|CONTROL CENTER/i);
 assert.match(mission.readiness.headline, /LIMITED|READY|NEEDS/i);
 assert.equal(mission.next.targetAction, "launch");
 assert.match(mission.recent.headline, /Codex · Failed/);
@@ -84,7 +85,7 @@ const asciiNav = buildNavModel({
 assert.equal(asciiNav.items[1].marker, ">");
 assert.equal(asciiNav.items[0].current, true);
 assert.equal(asciiNav.items[1].selected, true);
-assert.match(asciiNav.explanation, /Supervised runs|Running/i);
+assert.match(asciiNav.explanation, /Detected agents|IDEs|models|Harness|modules/i);
 
 function applyKey(state, keyAction) {
   const routed = routeCockpitKey(state, keyAction);
@@ -97,21 +98,21 @@ function smokeNavigation(layoutMode) {
     layoutMode,
     region: layoutMode === LAYOUT_MODES.MINIMAL ? COCKPIT_REGIONS.CONTENT : COCKPIT_REGIONS.NAV
   });
-  const diagnosticsIndex = COCKPIT_NAV.findIndex((item) => item.id === "diagnostics");
+  const diagnosticsIndex = COCKPIT_NAV.findIndex((item) => item.id === "changes");
   while (state.navIndex < diagnosticsIndex) {
     state = applyKey(state, { type: "arrow", direction: "down" });
   }
   state = applyKey(state, { type: "enter" });
-  assert.equal(state.view, ORCHESTRATOR_VIEWS.DIAGNOSTICS);
+  assert.equal(state.view, ORCHESTRATOR_VIEWS.CHANGES);
   assert.equal(state.region, COCKPIT_REGIONS.NAV);
 
   state = applyKey(state, { type: "arrow", direction: "up" });
   state = applyKey(state, { type: "enter" });
-  assert.equal(state.view, ORCHESTRATOR_VIEWS.LAUNCH);
-  assert.equal(state.region, COCKPIT_REGIONS.CONTENT);
+  assert.equal(state.view, ORCHESTRATOR_VIEWS.MODULES);
+  assert.equal(state.region, COCKPIT_REGIONS.NAV);
 
   const footer = buildFooterModel({
-    view: ORCHESTRATOR_VIEWS.DIAGNOSTICS,
+    view: ORCHESTRATOR_VIEWS.CHANGES,
     region: COCKPIT_REGIONS.NAV,
     unicode: false
   });
@@ -126,4 +127,24 @@ function smokeNavigation(layoutMode) {
 smokeNavigation(LAYOUT_MODES.WIDE);
 smokeNavigation(LAYOUT_MODES.COMPACT);
 
+const proposalLines = formatProposalLines([
+  {
+    id: "setup-local",
+    severity: "high",
+    title: "Finish local setup",
+    destination: "changes",
+    evidence: [{ type: "status", source: "status.overall", ref: "missing" }]
+  }
+], {
+  budgets: {
+    stableUsedTokens: 1,
+    stableBudgetTokens: 10,
+    requestUsedTokens: 0,
+    requestBudgetTokens: 10
+  }
+});
+assert.match(proposalLines.join("\n"), /\[HIGH\] Finish local setup → changes/);
+assert.match(proposalLines.join("\n"), /Budget · stable 1\/10/);
+assert.match(proposalLines.join("\n"), /evidence: status\.overall/);
+
 console.log("cockpit smoke OK");

package/scripts/smoke-test.sh

@@ -78,6 +78,15 @@ echo
 echo "== kairo status (after install) =="
 npx --no-install kairo status
 
+echo
+echo "== kairo components configure/verify sdd-core =="
+npx --no-install kairo components configure sdd-core --agents codex,cursor --persona off --dry-run --json \
+  | node -e 'let s="";process.stdin.on("data",d=>s+=d);process.stdin.on("end",()=>{const p=JSON.parse(s);if(p.writes!==false||p.applied!==false)process.exit(1)})'
+npx --no-install kairo components configure sdd-core --agents codex,cursor --persona off --yes --json \
+  | node -e 'let s="";process.stdin.on("data",d=>s+=d);process.stdin.on("end",()=>{const p=JSON.parse(s);const fs=require("fs");const path=require("path");if(p.writes!==false||(p.summary?.create??0)!==0||!p.receipt?.id)process.exit(1);if(!fs.existsSync(path.join(process.env.HARNESS_HOME,".agents","skills","sdd-init","SKILL.md")))process.exit(1)})'
+npx --no-install kairo components verify sdd-core --agents codex,cursor --json \
+  | node -e 'let s="";process.stdin.on("data",d=>s+=d);process.stdin.on("end",()=>{const p=JSON.parse(s);if(p.status!=="configured"||p.ok!==true)process.exit(1)})'
+
 SNAPSHOT="$(ls -A "$FAKE_HOME/.harness/backups" | head -1)"
 BACKUP_FILE="$(ls -A "$FAKE_HOME/.harness/backups/$SNAPSHOT" | head -1)"
 

package/src/cli.js

@@ -4,6 +4,11 @@ import { basename, dirname, resolve } from "node:path";
 import { ADAPTERS } from "./harness-files.js";
 import { GLOBAL_AGENT_IDS } from "./global/registry.js";
 import { COMPONENT_IDS, DEFAULT_COMPONENT_IDS } from "./global/component-registry.js";
+import {
+  runComponentsConfigure,
+  runComponentsRollback,
+  runComponentsVerify
+} from "./global/component-integration-cli.js";
 import {
   printGlobalComponents,
   printGlobalDetect,
@@ -237,6 +242,15 @@ async function dispatchComponentsCommand(options, invoke) {
     case "import":
       await runComponentsImport(options);
       return;
+    case "configure":
+      await runComponentsConfigure({ ...options, packageRoot });
+      return;
+    case "verify":
+      await runComponentsVerify({ ...options, packageRoot });
+      return;
+    case "rollback":
+      await runComponentsRollback(options);
+      return;
     default:
       throw new Error(
         `Unknown components action "${options.componentsAction}". Run "${invoke} help".`
@@ -321,6 +335,8 @@ export function parseArgs(argv) {
     components: null,
     componentsAction: null,
     componentId: null,
+    receiptId: null,
+    persona: null,
     label: null,
     outPath: null,
     bundlePath: null,
@@ -358,6 +374,7 @@ export function parseArgs(argv) {
     agent: null,
     task: null,
     model: null,
+    intelligenceBackend: null,
     permissions: null,
     captureTranscript: false,
     follow: false,
@@ -438,6 +455,10 @@ export function parseArgs(argv) {
     } else if (arg === "--apply") options.apply = true;
     else if (arg === "--to") options.snapshot = args[++index];
     else if (arg.startsWith("--to=")) options.snapshot = arg.slice("--to=".length);
+    else if (arg === "--receipt") options.receiptId = args[++index];
+    else if (arg.startsWith("--receipt=")) options.receiptId = arg.slice("--receipt=".length);
+    else if (arg === "--persona") options.persona = parsePersona(args[++index]);
+    else if (arg.startsWith("--persona=")) options.persona = parsePersona(arg.slice("--persona=".length));
     else if (arg === "--limit") options.limit = parsePositiveInt(args[++index], "limit");
     else if (arg.startsWith("--limit=")) options.limit = parsePositiveInt(arg.slice("--limit=".length), "limit");
     else if (arg === "--command") options.historyCommand = args[++index];
@@ -462,6 +483,8 @@ export function parseArgs(argv) {
     else if (arg.startsWith("--agent=")) options.agent = arg.slice("--agent=".length);
     else if (arg === "--model") options.model = args[++index];
     else if (arg.startsWith("--model=")) options.model = arg.slice("--model=".length);
+    else if (arg === "--backend") options.intelligenceBackend = args[++index] ?? "";
+    else if (arg.startsWith("--backend=")) options.intelligenceBackend = arg.slice("--backend=".length);
     else if (arg === "--permissions") options.permissions = parsePathList(args[++index]);
     else if (arg.startsWith("--permissions=")) options.permissions = parsePathList(arg.slice("--permissions=".length));
     else if (arg === "--capture-transcript") options.captureTranscript = true;
@@ -514,7 +537,18 @@ function parseComponentsAction(args, options) {
 
   if (action === "validate") return;
 
-  throw new Error(`Unknown components action "${action}". Use validate, init, pack, or import.`);
+  if (action === "configure" || action === "verify" || action === "rollback") {
+    const componentId = args[0];
+    if (!componentId || componentId.startsWith("-")) {
+      throw new Error(
+        `Missing component id. Use: ${formatCliCommand(`components ${action} <component-id>`)}`
+      );
+    }
+    options.componentId = args.shift();
+    return;
+  }
+
+  throw new Error(`Unknown components action "${action}". Use validate, init, pack, import, configure, verify, or rollback.`);
 }
 
 function parsePolicyAction(args, options) {
@@ -685,6 +719,14 @@ function parseAdapters(value) {
   return items;
 }
 
+function parsePersona(value) {
+  const persona = String(value ?? "").trim().toLowerCase();
+  if (persona !== "off" && persona !== "teaching") {
+    throw new Error('Invalid --persona. Use "off" or "teaching".');
+  }
+  return persona;
+}
+
 function printHelp() {
   const cli = PREFERRED_CLI;
   console.log(`${BRAND.displayName} (${PACKAGE_NAME})
@@ -707,7 +749,9 @@ Usage:
   ${cli} runs stop <runId> [--json]
   ${cli} orchestrator [--json]          Read-only agent capability diagnostics
   ${cli} intelligence [status|models|context|route|ask] [--json]
-  ${cli} intelligence ask --prompt "..." [--cloud-consent] [--yes] [--paths a,b]
+  ${cli} intelligence models --backend opencode-go|opencode-zen|opencode
+  ${cli} intelligence route --backend opencode-go --model <id> [--cloud-consent]
+  ${cli} intelligence ask --prompt "..." [--backend <id>] [--model <id>] [--cloud-consent] [--yes] [--paths a,b]
   ${cli} setup [--dry-run] [--yes] [--confirm] [--simple] [--no-preflight] [--agents <list|all>] [--components <list>]
   ${cli} status [--json]
   ${cli} sync [--dry-run] [--yes] [--confirm] [--json] [--no-preflight]
@@ -732,6 +776,10 @@ Usage:
   ${cli} report [--json] [--out <file>] [--limit <n>]
   ${cli} components
   ${cli} components validate|init|pack|import ...
+  ${cli} components configure engram-memory [--agents <list>] [--dry-run|--yes] [--json]
+  ${cli} components configure sdd-core [--agents <list>] [--persona off|teaching] [--dry-run|--yes] [--json]
+  ${cli} components verify sdd-core [--agents <list>] [--json]
+  ${cli} components rollback engram-memory|sdd-core --receipt <id> [--dry-run|--yes] [--json]
   ${cli} uninstall [--dry-run]
 
 Scopes:
@@ -749,8 +797,9 @@ Commands:
   runs       List, inspect, or cancel agent runs under ~/.harness/runs/.
   orchestrator  Read-only capability registry diagnostics (--json supported).
   intelligence  Harness Engineering layer: backends, context packs, routing, budgets.
-             Local-first (Ollama). Cloud (OpenRouter/free) only with --cloud-consent.
-             Credentials via env only (OPENROUTER_API_KEY, OLLAMA_HOST). Never stored.
+             Local-first (Ollama). Cloud only with --cloud-consent.
+             Ephemeral --backend/--model override preferredBackend/preferredModel.
+             Credentials via env only (OPENROUTER_API_KEY, OPENCODE_API_KEY, OLLAMA_HOST). Never stored.
   setup      Managed ecosystem setup. Interactive Ink UI (TTY). Use --simple for Clack prompts.
   status     Control panel: agents, components, drift, backups, next action.
   sync       Converge managed content (repair drift), then show status.
@@ -768,7 +817,7 @@ Commands:
   rollback   Preview or restore a prior config snapshot (--apply to write).
   policy     View or edit local operation preferences under ~/.harness/policy.json.
   report     Read-only diagnostics bundle: status, policy, adapters, diff, history.
-  components List, validate, scaffold, pack, or import workspace components.
+  components List, validate, scaffold, pack, import, or configure integrations (Engram, SDD).
   uninstall  Remove managed sections and global state. Backups are preserved.
   init       Alias for install --scope=workspace (legacy).
 

package/src/global/action-planner.js

@@ -180,7 +180,7 @@ function summarizeDiagnostics(capabilities) {
   };
 }
 
-function buildDiagnosticRecommendations({
+export function buildDiagnosticRecommendations({
   capabilities,
   profile,
   diagnostics,
@@ -206,13 +206,26 @@ function buildDiagnosticRecommendations({
     }
   }
 
-  if (!intelligenceSummary?.localAvailable && !intelligenceSummary?.cloudAuthenticated) {
+  if (!intelligenceSummary?.localAvailable && !intelligenceSummary?.cloudConfigured) {
     recommendations.push(
-      "No intelligence backend available. Start Ollama or set OPENROUTER_API_KEY (env only). Diagnostics mode remains available."
+      "No intelligence backend available. Start Ollama, install the OpenCode CLI, or set OPENCODE_API_KEY / OPENROUTER_API_KEY (env only). Diagnostics mode remains available."
+    );
+  } else if (
+    !intelligenceSummary?.localAvailable
+    && intelligenceSummary?.cloudConfigured
+    && !intelligenceSummary?.cloudAuthenticated
+  ) {
+    recommendations.push(
+      `Cloud intelligence is configured but not authenticated. Run ${formatCliCommand("intelligence status")} to inspect evidence before invoke.`
     );
   } else if (!intelligenceSummary?.localAvailable && intelligenceSummary?.cloudAuthenticated) {
+    const provider = intelligenceSummary.opencodeGoAuthenticated
+      ? "OpenCode Go"
+      : intelligenceSummary.opencodeZenAuthenticated
+        ? "OpenCode Zen"
+        : "OpenRouter";
     recommendations.push(
-      `OpenRouter is authenticated. Cloud invoke still requires session flags: ${formatCliCommand("intelligence ask --cloud-consent --yes")}.`
+      `${provider} is authenticated. Cloud invoke requires: ${formatCliCommand("intelligence ask --cloud-consent --yes")}.`
     );
   }
 

package/src/global/component-authoring.js

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
+import { COMPONENT_ID_PATTERN } from "./component-manifest.js";
 import { COMPONENT_IDS } from "./component-registry.js";
 import {
   hasWorkspaceCatalog,
@@ -9,8 +10,6 @@ import {
   workspaceCatalogPath
 } from "./load-workspace-component-catalog.js";
 import { formatCliCommand } from "./brand/cli.js";
-
-const COMPONENT_ID_PATTERN = /^[a-z][a-z0-9-]*$/;
 const DEFAULT_VERSION = "0.1.0";
 const DEFAULT_ASSET = "README.md";
 

package/src/global/component-ecosystem-checks.js

@@ -1,17 +1,34 @@
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { formatCliCommand } from "./brand/cli.js";
-
+import { ensureIntegrationProvidersRegistered } from "./integrations/index.js";
+import { requireIntegrationProvider } from "./integrations/provider-registry.js";
+import { buildEngramIntegrationChecks, buildSddIntegrationChecks } from "./component-integration-cli.js";
+import { KAIRO_ENGRAM_AGENT_IDS } from "./integrations/engram-evidence.js";
+import { SDD_MANAGED_AGENT_IDS } from "./integrations/sdd-destinations.js";
+import { harnessHomePaths } from "./paths.js";
+import { readGlobalState } from "./state.js";
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
 const GRAPH_REPORT_COMMIT_PATTERN = /Built from commit:\s*`([0-9a-f]+)`/i;
 
-export async function runComponentEcosystemChecks({ installedComponents, workspaceRoot = null } = {}) {
+export async function runComponentEcosystemChecks({
+  installedComponents,
+  workspaceRoot = null,
+  homeDir = null
+} = {}) {
   const installedIds = new Set(installedComponents.map((component) => component.id));
   const checks = [];
 
   if (installedIds.has("engram-memory")) {
-    checks.push(buildEngramMcpCheck());
+    checks.push(...await buildEngramChecks({ homeDir }));
+  }
+
+  if (installedIds.has("sdd-core")) {
+    checks.push(...await buildSddChecks({ homeDir }));
   }
 
   if (installedIds.has("graphify-context")) {
@@ -21,14 +38,59 @@ export async function runComponentEcosystemChecks({ installedComponents, workspa
   return checks;
 }
 
-function buildEngramMcpCheck() {
-  return {
-    name: "engram:mcp-tools",
-    status: "warning",
-    category: "integration",
-    componentId: "engram-memory",
-    detail: "Engram MCP is not bundled. Configure mem_* tools in your agent (user-engram or plugin-engram-engram) when ready."
-  };
+async function buildEngramChecks({ homeDir }) {
+  ensureIntegrationProvidersRegistered();
+  try {
+    const provider = requireIntegrationProvider("engram");
+    const inspection = await provider.inspect({
+      homeDir: homeDir ?? undefined,
+      agentIds: KAIRO_ENGRAM_AGENT_IDS
+    });
+    return buildEngramIntegrationChecks(inspection);
+  } catch (error) {
+    return [{
+      name: "engram:binary",
+      status: "warning",
+      category: "integration",
+      componentId: "engram-memory",
+      detail: error instanceof Error ? error.message : "Engram inspection failed."
+    }];
+  }
+}
+
+async function buildSddChecks({ homeDir }) {
+  ensureIntegrationProvidersRegistered();
+  try {
+    const provider = requireIntegrationProvider("sdd-core");
+    const resolvedHome = homeDir ?? undefined;
+    const state = resolvedHome
+      ? await readGlobalState(harnessHomePaths(resolvedHome).statePath)
+      : null;
+    const managed = new Set(SDD_MANAGED_AGENT_IDS);
+    const installedAgents = (state?.adapters ?? [])
+      .map((entry) => entry.id)
+      .filter((id) => managed.has(id));
+    const trackedFiles = Object.fromEntries(
+      (state?.sdd?.files ?? []).map((file) => [file.destinationPath, file.hash])
+    );
+    const verification = await provider.verify({
+      homeDir: resolvedHome,
+      requestedAgentIds: installedAgents.length ? installedAgents : [],
+      detectedAgentIds: installedAgents,
+      trackedFiles,
+      personaAgentIds: state?.sdd?.personaAgentIds ?? [],
+      packageRoot: PACKAGE_ROOT
+    });
+    return buildSddIntegrationChecks(verification);
+  } catch (error) {
+    return [{
+      name: "sdd-core:skills",
+      status: "warning",
+      category: "integration",
+      componentId: "sdd-core",
+      detail: error instanceof Error ? error.message : "SDD verification failed."
+    }];
+  }
 }
 
 async function buildGraphifyChecks(workspaceRoot) {
@@ -115,7 +177,6 @@ async function readGraphFreshness(workspaceRoot, reportPath) {
   }
 
   const isFresh = headCommit.startsWith(graphCommit) || graphCommit.startsWith(headCommit);
-
   if (isFresh) {
     return {
       status: "ok",
@@ -134,9 +195,7 @@ function resolveGitHead(workspaceRoot) {
     cwd: workspaceRoot,
     encoding: "utf8"
   });
-
   if (result.status !== 0) return null;
-
   const head = result.stdout.trim();
   return head.length > 0 ? head : null;
 }

package/src/global/component-health.js

@@ -0,0 +1,56 @@
+/** Public component health states derived from doctor checks. */
+
+export const COMPONENT_HEALTH = Object.freeze({
+  HEALTHY: "healthy",
+  DEGRADED: "degraded",
+  DRIFTED: "drifted",
+  MISSING: "missing"
+});
+
+const CHECK_TO_HEALTH = Object.freeze({
+  missing: COMPONENT_HEALTH.MISSING,
+  stale: COMPONENT_HEALTH.DRIFTED,
+  warning: COMPONENT_HEALTH.DEGRADED,
+  ok: COMPONENT_HEALTH.HEALTHY
+});
+
+const HEALTH_RANK = Object.freeze({
+  [COMPONENT_HEALTH.MISSING]: 3,
+  [COMPONENT_HEALTH.DRIFTED]: 2,
+  [COMPONENT_HEALTH.DEGRADED]: 1,
+  [COMPONENT_HEALTH.HEALTHY]: 0
+});
+
+export function summarizeComponentHealth(checks = []) {
+  if (!Array.isArray(checks) || checks.length === 0) {
+    return COMPONENT_HEALTH.HEALTHY;
+  }
+
+  let worst = COMPONENT_HEALTH.HEALTHY;
+  for (const check of checks) {
+    const mapped = CHECK_TO_HEALTH[check.status] ?? COMPONENT_HEALTH.DEGRADED;
+    if (HEALTH_RANK[mapped] > HEALTH_RANK[worst]) worst = mapped;
+  }
+  return worst;
+}
+
+export function buildComponentHealthEntries(components, checks) {
+  return components.map((component) => {
+    const related = checks.filter((check) => check.componentId === component.id);
+    return {
+      id: component.id,
+      version: component.version,
+      source: component.source ?? "bundled",
+      status: summarizeComponentHealth(related),
+      checks: related.map((check) => ({
+        name: check.name,
+        status: check.status,
+        type: check.category ?? null
+      }))
+    };
+  });
+}
+
+export function doctorAffectedByComponentHealth(health) {
+  return health === COMPONENT_HEALTH.MISSING || health === COMPONENT_HEALTH.DRIFTED;
+}