nemoris 0.1.0 → 0.1.2

package/src/onboarding/doctor.js

@@ -1,530 +1,530 @@
-/**
- * Nemoris Doctor — standalone health report command.
- *
- * Pure functions (checkPlatform, formatDoctorReport) are unit-tested.
- * runDoctor orchestrates all checks and is tested in integration.
- */
-
-import fs from "node:fs";
-import os from "node:os";
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-import { getDaemonPaths, listServeDaemonPids } from "../cli/runtime-control.js";
-
-const execFileAsync = promisify(execFile);
-
-// ── Minimum supported Node.js major version ─────────────────────────
-const MIN_NODE_MAJOR = 22;
-
-// ── Platform check ───────────────────────────────────────────────────
-
-/**
- * Returns basic platform information.
- * @returns {{ os: string, arch: string, nodeVersion: string, nodeOk: boolean }}
- */
-export function checkPlatform() {
-  const platform = os.platform();
-  const arch = os.arch();
-  const nodeVersion = process.version;
-  const major = parseInt(nodeVersion.replace(/^v/, "").split(".")[0], 10);
-  const nodeOk = major >= MIN_NODE_MAJOR;
-
-  // Map os.platform() to a human-readable OS name
-  const osNames = {
-    darwin: "macOS",
-    linux: "Linux",
-    win32: "Windows",
-  };
-  const osDisplay = osNames[platform] || platform;
-
-  return {
-    os: osDisplay,
-    arch,
-    nodeVersion,
-    nodeOk,
-  };
-}
-
-// ── Dependency checks ────────────────────────────────────────────────
-
-/**
- * Checks for required and optional CLI dependencies.
- * @returns {Promise<Array<{ name: string, found: boolean, required: boolean, installHint: string }>>}
- */
-export async function checkDependencies() {
-  const platform = os.platform();
-  const whichCmd = platform === "win32" ? "where" : "which";
-  const deps = [];
-
-  async function check(name, required, hint) {
-    try {
-      await execFileAsync(whichCmd, [name], { timeout: 3000 });
-      deps.push({ name, found: true, required, installHint: hint });
-    } catch {
-      deps.push({ name, found: false, required, installHint: hint });
-    }
-  }
-
-  await check("git", true, "https://git-scm.com");
-  await check("ollama", false, "https://ollama.ai");
-  await check("gh", false, "https://cli.github.com (optional)");
-
-  if (platform === "win32") {
-    await check("pm2", false, "npm install -g pm2 (https://pm2.io)");
-  }
-
-  return deps;
-}
-
-// ── Format helpers ───────────────────────────────────────────────────
-
-function _stripAnsi(str) {
-  // Strip ANSI escape codes for length calculations
-  // eslint-disable-next-line no-control-regex
-  return str.replace(/\x1b\[[0-9;]*m/g, "");
-}
-
-function checkIcon(ok) {
-  return ok ? "\x1b[32m✓\x1b[0m" : "\x1b[31m✗\x1b[0m";
-}
-
-function warnIcon() {
-  return "\x1b[33m!\x1b[0m";
-}
-
-function bold(text) {
-  return `\x1b[1m${text}\x1b[0m`;
-}
-
-function dim(text) {
-  return `\x1b[2m${text}\x1b[0m`;
-}
-
-function formatProviderReason(status) {
-  if (status === null || status === undefined || status === "") {
-    return "";
-  }
-
-  if (typeof status === "number") {
-    return `HTTP ${status}`;
-  }
-
-  const text = String(status).trim();
-  const missingToken = text.match(/\(env:([A-Z0-9_]+)\)/);
-  if (missingToken) {
-    return `missing ${missingToken[1]}`;
-  }
-
-  return text;
-}
-
-function row(label, value, ok) {
-  const icon = ok === null ? warnIcon() : checkIcon(ok);
-  const labelPad = label.padEnd(16);
-  const valuePad = (value || "").toString().padEnd(22);
-  return `  ${labelPad}${valuePad}${icon}`;
-}
-
-// ── formatDoctorReport ───────────────────────────────────────────────
-
-/**
- * Renders a human-readable doctor report string.
- *
- * @param {{
- *   platform: { os: string, arch: string, nodeVersion: string, nodeOk: boolean },
- *   installDir: string,
- *   configValid: boolean,
- *   configErrors: string[],
- *   providers: Array<{ id: string, healthy: boolean, status?: string }>,
- *   lanes: Array<{ id: string, ready: boolean }>,
- *   jobs: Array<{ id: string, healthy: boolean }>,
- *   delivery: Array<{ id: string, ready: boolean }>,
- *   daemon?: { pids?: number[], stalePidFile?: boolean },
- *   suggestions: string[],
- *   exitCode?: number,
- * }} results
- * @returns {string}
- */
-export function formatDoctorReport(results) {
-  const {
-    platform,
-    installDir,
-    configValid,
-    configErrors = [],
-    dependencies = [],
-    providers = [],
-    lanes = [],
-    jobs = [],
-    delivery = [],
-    mcpServers = [],
-    daemon = {},
-    suggestions = [],
-  } = results;
-
-  const lines = [];
-
-  // Header
-  const headerLine = "─".repeat(40);
-  lines.push(`\n${bold(`── Nemoris Doctor `)}${bold(headerLine.slice(19))}\n`);
-
-  // Platform section
-  const osLabel = `${platform.os} (${platform.arch})`;
-  lines.push(row("Platform", osLabel, true));
-  lines.push(row("Node.js", platform.nodeVersion, platform.nodeOk));
-
-  // Install dir — shorten to ~ if in home
-  const homeDir = os.homedir();
-  const displayDir = installDir
-    ? installDir.startsWith(homeDir)
-      ? installDir.replace(homeDir, "~")
-      : installDir
-    : "(unknown)";
-  lines.push(row("Install", displayDir, true));
-
-  const allLanesReady = lanes.every((lane) => lane.ready);
-
-  // Dependencies section
-  if (dependencies.length > 0) {
-    lines.push(`\n${bold("  Dependencies")}`);
-    for (let i = 0; i < dependencies.length; i++) {
-      const d = dependencies[i];
-      const prefix = i === dependencies.length - 1 ? "  └─" : "  ├─";
-      if (d.found) {
-        lines.push(`${prefix} ${d.name.padEnd(14)} ${dim("found")}  ${checkIcon(true)}`);
-      } else if (d.required) {
-        lines.push(`${prefix} ${d.name.padEnd(14)} \x1b[31mmissing\x1b[0m  ${checkIcon(false)}  ${dim(d.installHint)}`);
-      } else {
-        lines.push(`${prefix} ${d.name.padEnd(14)} ${dim("missing")}  \x1b[33m!\x1b[0m  ${dim(d.installHint)}`);
-      }
-    }
-  }
-
-  // Providers section
-  if (providers.length > 0) {
-    lines.push(`\n${bold("  Providers")}`);
-    for (let i = 0; i < providers.length; i++) {
-      const p = providers[i];
-      const prefix = i === providers.length - 1 ? "  └─" : "  ├─";
-      if (p.healthy) {
-        lines.push(`${prefix} ${p.id.padEnd(14)} ${dim("healthy")}  ${checkIcon(true)}`);
-      } else if (allLanesReady) {
-        const reasonText = formatProviderReason(p.status);
-        const reason = reasonText ? `  ${dim(`(${reasonText})`)}` : "";
-        lines.push(`${prefix} ${p.id.padEnd(14)} ${dim("not configured")}  —${reason}`);
-      } else {
-        const reasonText = formatProviderReason(p.status);
-        const reason = reasonText ? dim(`(${reasonText})`) : "";
-        lines.push(`${prefix} ${p.id.padEnd(14)} \x1b[31munhealthy\x1b[0m  ${checkIcon(false)}  ${reason}`);
-      }
-    }
-  }
-
-  // Config section
-  const configNote = configValid
-    ? `${configErrors.length === 0 ? "all manifests valid" : `${configErrors.length} error(s)`}`
-    : `${configErrors.length} error(s)`;
-  lines.push(`\n${row("Config", configNote, configValid)}`);
-
-  if (configErrors.length > 0) {
-    for (const err of configErrors) {
-      lines.push(`    ${dim("• " + err)}`);
-    }
-  }
-
-  // Lanes section
-  if (lanes.length > 0) {
-    lines.push(`\n${bold("  Lanes")}`);
-    for (let i = 0; i < lanes.length; i++) {
-      const l = lanes[i];
-      const prefix = i === lanes.length - 1 ? "  └─" : "  ├─";
-      lines.push(`${prefix} ${l.id.padEnd(30)} ${checkIcon(l.ready)}`);
-    }
-  }
-
-  // Jobs section
-  if (jobs.length > 0) {
-    lines.push(`\n${bold("  Jobs")}`);
-    for (let i = 0; i < jobs.length; i++) {
-      const j = jobs[i];
-      const prefix = i === jobs.length - 1 ? "  └─" : "  ├─";
-      lines.push(`${prefix} ${j.id.padEnd(30)} ${checkIcon(j.healthy)}`);
-    }
-  }
-
-  // Delivery section
-  if (delivery.length > 0) {
-    lines.push(`\n${bold("  Delivery")}`);
-    for (let i = 0; i < delivery.length; i++) {
-      const d = delivery[i];
-      const prefix = i === delivery.length - 1 ? "  └─" : "  ├─";
-      lines.push(`${prefix} ${d.id.padEnd(30)} ${checkIcon(d.ready)}`);
-    }
-  }
-
-  // MCP Servers section
-  if (mcpServers.length > 0) {
-    lines.push(`\n${bold("  MCP Servers")}`);
-    for (let i = 0; i < mcpServers.length; i++) {
-      const s = mcpServers[i];
-      const prefix = i === mcpServers.length - 1 ? "  └─" : "  ├─";
-      if (s.alive) {
-        lines.push(`${prefix} ${s.id.padEnd(14)} ${dim("running")}  ${checkIcon(true)}`);
-      } else {
-        lines.push(`${prefix} ${s.id.padEnd(14)} ${dim("stopped")}  ${checkIcon(false)}`);
-      }
-    }
-  }
-
-  if ((daemon.pids || []).length > 1 || daemon.stalePidFile) {
-    lines.push(`\n${bold("  Daemon")}`);
-    if ((daemon.pids || []).length > 1) {
-      lines.push(`  ⚠️  Multiple daemon processes detected (pids: ${daemon.pids.join(", ")}). Run nemoris stop && nemoris start to fix.`);
-    }
-    if (daemon.stalePidFile) {
-      lines.push("  ⚠️  Stale PID file found. Daemon is not running.");
-    }
-  }
-
-  // Overall status
-  // An unhealthy provider is only critical if lanes can't resolve without it.
-  // If all lanes are ready, unhealthy providers are warnings (unused/optional).
-  const allDeliveryReady = delivery.every((d) => d.ready);
-  const allJobsHealthy = jobs.every((j) => j.healthy);
-  const allProviderHealthy = providers.every((p) => p.healthy);
-  const overallHealthy = configValid && (allProviderHealthy || allLanesReady) && allDeliveryReady && allJobsHealthy;
-
-  const suggCount = suggestions.length;
-  const suggNote = suggCount > 0 ? ` (${suggCount} suggestion${suggCount === 1 ? "" : "s"})` : "";
-  const overallLabel = overallHealthy ? bold("healthy") : bold("degraded");
-  lines.push(`\n  Overall: ${overallLabel}${suggNote}\n`);
-
-  // Suggestions
-  if (suggestions.length > 0) {
-    for (const s of suggestions) {
-      lines.push(`  \x1b[33m💡\x1b[0m ${s}`);
-    }
-    lines.push("");
-  }
-
-  return lines.join("\n");
-}
-
-// ── runDoctor ────────────────────────────────────────────────────────
-
-/**
- * Orchestrates all health checks and returns a results object.
- *
- * @param {string} installDir  — path to the nemoris install root
- * @param {{
- *   execFileImpl?: Function,
- *   fsImpl?: typeof import("node:fs"),
- *   listServeDaemonPidsImpl?: Function,
- * }} options
- * @returns {Promise<object>}  — results suitable for formatDoctorReport + exitCode
- */
-export async function runDoctor(
-  installDir,
-  {
-    execFileImpl = execFileAsync,
-    fsImpl = fs,
-    listServeDaemonPidsImpl = listServeDaemonPids,
-  } = {},
-) {
-  const results = {
-    platform: checkPlatform(),
-    installDir,
-    configValid: true,
-    configErrors: [],
-    dependencies: [],
-    providers: [],
-    lanes: [],
-    jobs: [],
-    delivery: [],
-    mcpServers: [],
-    daemon: {
-      pids: [],
-      stalePidFile: false,
-    },
-    suggestions: [],
-    exitCode: 0,
-  };
-
-  // ── 0. Dependency checks ──────────────────────────────────────────
-  try {
-    results.dependencies = await checkDependencies();
-  } catch {
-    // Dependency check failure is non-fatal
-  }
-
-  // ── 1. Config validation ─────────────────────────────────────────
-  try {
-    const { ConfigLoader } = await import("../config/loader.js");
-    const { validateAllConfigs } = await import("../config/schema-validator.js");
-    const configDir = `${installDir}/config`;
-    const loader = new ConfigLoader({ rootDir: configDir });
-    const config = await loader.loadAll();
-    const validation = validateAllConfigs(config, configDir);
-    results.configValid = validation.ok;
-    results.configErrors = validation.errors || [];
-    results._config = config;
-  } catch (err) {
-    // Gracefully degrade — config may not exist yet
-    results.configValid = false;
-    results.configErrors = [err.message || "Failed to load config"];
-    results._config = null;
-  }
-
-  // ── 2. Provider health ───────────────────────────────────────────
-  try {
-    const { ProviderRegistry } = await import("../providers/registry.js");
-    const config = results._config;
-    if (config?.providers) {
-      const registry = new ProviderRegistry({ fetchImpl: fetch });
-      for (const [id, providerConfig] of Object.entries(config.providers)) {
-        try {
-          const adapter = registry.create(providerConfig);
-          let healthy = true;
-          let status = null;
-          if (typeof adapter.healthCheck === "function") {
-            const h = await adapter.healthCheck();
-            healthy = Boolean(h.ok);
-            status = h.status ?? null;
-          }
-          results.providers.push({ id, healthy, status });
-        } catch (err) {
-          results.providers.push({ id, healthy: false, status: err.message });
-        }
-      }
-    }
-  } catch {
-    // Provider module unavailable — skip
-  }
-
-  // ── 3. Lane readiness ────────────────────────────────────────────
-  try {
-    const { buildLaneReadiness } = await import("../runtime/lane-readiness.js");
-    const config = results._config;
-    if (config?.router) {
-      for (const [laneId] of Object.entries(config.router)) {
-        try {
-          const readiness = buildLaneReadiness({ jobId: laneId });
-          results.lanes.push({ id: laneId, ready: readiness.ready !== false });
-        } catch {
-          results.lanes.push({ id: laneId, ready: false });
-        }
-      }
-    }
-  } catch {
-    // Lane readiness module unavailable — skip
-  }
-
-  // ── 4. Job dependency health ─────────────────────────────────────
-  try {
-    const { DependencyHealth } = await import("../runtime/dependency-health.js");
-    const config = results._config;
-    if (config?.jobs) {
-      const dh = new DependencyHealth({
-        projectRoot: installDir,
-        liveRoot: installDir,
-        fetchImpl: fetch,
-        execFileImpl,
-      });
-      for (const [jobId] of Object.entries(config.jobs)) {
-        try {
-          let healthy = true;
-          if (typeof dh.forJob === "function") {
-            const jobHealth = await dh.forJob(jobId);
-            healthy = Boolean(jobHealth?.ok !== false);
-          }
-          results.jobs.push({ id: jobId, healthy });
-        } catch {
-          results.jobs.push({ id: jobId, healthy: false });
-        }
-      }
-    }
-  } catch {
-    // Dependency health module unavailable — skip
-  }
-
-  // ── 5. Delivery channel readiness ───────────────────────────────
-  try {
-    const config = results._config;
-    if (config?.delivery?.profiles) {
-      for (const [id, profile] of Object.entries(config.delivery.profiles)) {
-        // Basic check: profile exists and has an adapter
-        const ready = Boolean(profile?.adapter);
-        results.delivery.push({ id, ready });
-      }
-    }
-  } catch {
-    // Delivery config unavailable — skip
-  }
-
-  // ── 5b. MCP server health ────────────────────────────────────────────────────
-  try {
-    const config = results._config;
-    if (config?.mcp?.servers) {
-      for (const id of Object.keys(config.mcp.servers)) {
-        // MCP servers are lazy — at doctor time they're not running.
-        // Report them as configured but stopped (informational only).
-        results.mcpServers.push({ id, alive: false });
-      }
-    }
-  } catch {
-    // MCP config unavailable — skip
-  }
-
-  // ── 5c. Daemon process health ────────────────────────────────────────────────
-  try {
-    const { pidFile } = getDaemonPaths(installDir);
-    results.daemon.pids = await listServeDaemonPidsImpl({ execFileImpl });
-    results.daemon.stalePidFile = results.daemon.pids.length === 0 && fsImpl.existsSync(pidFile);
-  } catch {
-    // Daemon process checks are best-effort only.
-  }
-
-  // ── 6. Suggestions ───────────────────────────────────────────────
-  try {
-    const config = results._config;
-    // Suggest Telegram if no delivery configured
-    if (!config?.delivery?.profiles || Object.keys(config.delivery?.profiles || {}).length === 0) {
-      results.suggestions.push("Connect Telegram for delivery: nemoris channel add telegram");
-    }
-    // Suggest enabling embeddings if no embedding config
-    if (config && !config.runtime?.embeddings?.enabled) {
-      // Only suggest if runtime loaded but embeddings not explicitly enabled
-      if (config.runtime && config.runtime.embeddings === undefined) {
-        results.suggestions.push("Enable embeddings for semantic memory search: set runtime.embeddings.enabled = true");
-      }
-    }
-  } catch {
-    // Skip suggestions on error
-  }
-
-  // ── 7. Determine exit code ───────────────────────────────────────
-  // Unhealthy providers are only critical if lanes can't resolve without them.
-  const allLanesOk = results.lanes.every((l) => l.ready);
-  const providerIssuesCritical = results.providers.some((p) => !p.healthy) && !allLanesOk;
-  const hasCritical = !results.configValid ||
-    providerIssuesCritical ||
-    results.delivery.some((d) => !d.ready);
-  const hasWarning = results.suggestions.length > 0 ||
-    results.providers.some((p) => !p.healthy) ||
-    results.jobs.some((j) => !j.healthy) ||
-    results.lanes.some((l) => !l.ready) ||
-    results.daemon.pids.length > 1 ||
-    results.daemon.stalePidFile;
-
-  if (hasCritical) {
-    results.exitCode = 2;
-  } else if (hasWarning) {
-    results.exitCode = 1;
-  } else {
-    results.exitCode = 0;
-  }
-
-  // Clean up internal fields
-  delete results._config;
-
-  return results;
-}
+/**
+ * Nemoris Doctor — standalone health report command.
+ *
+ * Pure functions (checkPlatform, formatDoctorReport) are unit-tested.
+ * runDoctor orchestrates all checks and is tested in integration.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { getDaemonPaths, listServeDaemonPids } from "../cli/runtime-control.js";
+
+const execFileAsync = promisify(execFile);
+
+// ── Minimum supported Node.js major version ─────────────────────────
+const MIN_NODE_MAJOR = 22;
+
+// ── Platform check ───────────────────────────────────────────────────
+
+/**
+ * Returns basic platform information.
+ * @returns {{ os: string, arch: string, nodeVersion: string, nodeOk: boolean }}
+ */
+export function checkPlatform() {
+  const platform = os.platform();
+  const arch = os.arch();
+  const nodeVersion = process.version;
+  const major = parseInt(nodeVersion.replace(/^v/, "").split(".")[0], 10);
+  const nodeOk = major >= MIN_NODE_MAJOR;
+
+  // Map os.platform() to a human-readable OS name
+  const osNames = {
+    darwin: "macOS",
+    linux: "Linux",
+    win32: "Windows",
+  };
+  const osDisplay = osNames[platform] || platform;
+
+  return {
+    os: osDisplay,
+    arch,
+    nodeVersion,
+    nodeOk,
+  };
+}
+
+// ── Dependency checks ────────────────────────────────────────────────
+
+/**
+ * Checks for required and optional CLI dependencies.
+ * @returns {Promise<Array<{ name: string, found: boolean, required: boolean, installHint: string }>>}
+ */
+export async function checkDependencies() {
+  const platform = os.platform();
+  const whichCmd = platform === "win32" ? "where" : "which";
+  const deps = [];
+
+  async function check(name, required, hint) {
+    try {
+      await execFileAsync(whichCmd, [name], { timeout: 3000 });
+      deps.push({ name, found: true, required, installHint: hint });
+    } catch {
+      deps.push({ name, found: false, required, installHint: hint });
+    }
+  }
+
+  await check("git", true, "https://git-scm.com");
+  await check("ollama", false, "https://ollama.ai");
+  await check("gh", false, "https://cli.github.com (optional)");
+
+  if (platform === "win32") {
+    await check("pm2", false, "npm install -g pm2 (https://pm2.io)");
+  }
+
+  return deps;
+}
+
+// ── Format helpers ───────────────────────────────────────────────────
+
+function _stripAnsi(str) {
+  // Strip ANSI escape codes for length calculations
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+function checkIcon(ok) {
+  return ok ? "\x1b[32m✓\x1b[0m" : "\x1b[31m✗\x1b[0m";
+}
+
+function warnIcon() {
+  return "\x1b[33m!\x1b[0m";
+}
+
+function bold(text) {
+  return `\x1b[1m${text}\x1b[0m`;
+}
+
+function dim(text) {
+  return `\x1b[2m${text}\x1b[0m`;
+}
+
+function formatProviderReason(status) {
+  if (status === null || status === undefined || status === "") {
+    return "";
+  }
+
+  if (typeof status === "number") {
+    return `HTTP ${status}`;
+  }
+
+  const text = String(status).trim();
+  const missingToken = text.match(/\(env:([A-Z0-9_]+)\)/);
+  if (missingToken) {
+    return `missing ${missingToken[1]}`;
+  }
+
+  return text;
+}
+
+function row(label, value, ok) {
+  const icon = ok === null ? warnIcon() : checkIcon(ok);
+  const labelPad = label.padEnd(16);
+  const valuePad = (value || "").toString().padEnd(22);
+  return `  ${labelPad}${valuePad}${icon}`;
+}
+
+// ── formatDoctorReport ───────────────────────────────────────────────
+
+/**
+ * Renders a human-readable doctor report string.
+ *
+ * @param {{
+ *   platform: { os: string, arch: string, nodeVersion: string, nodeOk: boolean },
+ *   installDir: string,
+ *   configValid: boolean,
+ *   configErrors: string[],
+ *   providers: Array<{ id: string, healthy: boolean, status?: string }>,
+ *   lanes: Array<{ id: string, ready: boolean }>,
+ *   jobs: Array<{ id: string, healthy: boolean }>,
+ *   delivery: Array<{ id: string, ready: boolean }>,
+ *   daemon?: { pids?: number[], stalePidFile?: boolean },
+ *   suggestions: string[],
+ *   exitCode?: number,
+ * }} results
+ * @returns {string}
+ */
+export function formatDoctorReport(results) {
+  const {
+    platform,
+    installDir,
+    configValid,
+    configErrors = [],
+    dependencies = [],
+    providers = [],
+    lanes = [],
+    jobs = [],
+    delivery = [],
+    mcpServers = [],
+    daemon = {},
+    suggestions = [],
+  } = results;
+
+  const lines = [];
+
+  // Header
+  const headerLine = "─".repeat(40);
+  lines.push(`\n${bold(`── Nemoris Doctor `)}${bold(headerLine.slice(19))}\n`);
+
+  // Platform section
+  const osLabel = `${platform.os} (${platform.arch})`;
+  lines.push(row("Platform", osLabel, true));
+  lines.push(row("Node.js", platform.nodeVersion, platform.nodeOk));
+
+  // Install dir — shorten to ~ if in home
+  const homeDir = os.homedir();
+  const displayDir = installDir
+    ? installDir.startsWith(homeDir)
+      ? installDir.replace(homeDir, "~")
+      : installDir
+    : "(unknown)";
+  lines.push(row("Install", displayDir, true));
+
+  const allLanesReady = lanes.every((lane) => lane.ready);
+
+  // Dependencies section
+  if (dependencies.length > 0) {
+    lines.push(`\n${bold("  Dependencies")}`);
+    for (let i = 0; i < dependencies.length; i++) {
+      const d = dependencies[i];
+      const prefix = i === dependencies.length - 1 ? "  └─" : "  ├─";
+      if (d.found) {
+        lines.push(`${prefix} ${d.name.padEnd(14)} ${dim("found")}  ${checkIcon(true)}`);
+      } else if (d.required) {
+        lines.push(`${prefix} ${d.name.padEnd(14)} \x1b[31mmissing\x1b[0m  ${checkIcon(false)}  ${dim(d.installHint)}`);
+      } else {
+        lines.push(`${prefix} ${d.name.padEnd(14)} ${dim("missing")}  \x1b[33m!\x1b[0m  ${dim(d.installHint)}`);
+      }
+    }
+  }
+
+  // Providers section
+  if (providers.length > 0) {
+    lines.push(`\n${bold("  Providers")}`);
+    for (let i = 0; i < providers.length; i++) {
+      const p = providers[i];
+      const prefix = i === providers.length - 1 ? "  └─" : "  ├─";
+      if (p.healthy) {
+        lines.push(`${prefix} ${p.id.padEnd(14)} ${dim("healthy")}  ${checkIcon(true)}`);
+      } else if (allLanesReady) {
+        const reasonText = formatProviderReason(p.status);
+        const reason = reasonText ? `  ${dim(`(${reasonText})`)}` : "";
+        lines.push(`${prefix} ${p.id.padEnd(14)} ${dim("not configured")}  —${reason}`);
+      } else {
+        const reasonText = formatProviderReason(p.status);
+        const reason = reasonText ? dim(`(${reasonText})`) : "";
+        lines.push(`${prefix} ${p.id.padEnd(14)} \x1b[31munhealthy\x1b[0m  ${checkIcon(false)}  ${reason}`);
+      }
+    }
+  }
+
+  // Config section
+  const configNote = configValid
+    ? `${configErrors.length === 0 ? "all manifests valid" : `${configErrors.length} error(s)`}`
+    : `${configErrors.length} error(s)`;
+  lines.push(`\n${row("Config", configNote, configValid)}`);
+
+  if (configErrors.length > 0) {
+    for (const err of configErrors) {
+      lines.push(`    ${dim("• " + err)}`);
+    }
+  }
+
+  // Lanes section
+  if (lanes.length > 0) {
+    lines.push(`\n${bold("  Lanes")}`);
+    for (let i = 0; i < lanes.length; i++) {
+      const l = lanes[i];
+      const prefix = i === lanes.length - 1 ? "  └─" : "  ├─";
+      lines.push(`${prefix} ${l.id.padEnd(30)} ${checkIcon(l.ready)}`);
+    }
+  }
+
+  // Jobs section
+  if (jobs.length > 0) {
+    lines.push(`\n${bold("  Jobs")}`);
+    for (let i = 0; i < jobs.length; i++) {
+      const j = jobs[i];
+      const prefix = i === jobs.length - 1 ? "  └─" : "  ├─";
+      lines.push(`${prefix} ${j.id.padEnd(30)} ${checkIcon(j.healthy)}`);
+    }
+  }
+
+  // Delivery section
+  if (delivery.length > 0) {
+    lines.push(`\n${bold("  Delivery")}`);
+    for (let i = 0; i < delivery.length; i++) {
+      const d = delivery[i];
+      const prefix = i === delivery.length - 1 ? "  └─" : "  ├─";
+      lines.push(`${prefix} ${d.id.padEnd(30)} ${checkIcon(d.ready)}`);
+    }
+  }
+
+  // MCP Servers section
+  if (mcpServers.length > 0) {
+    lines.push(`\n${bold("  MCP Servers")}`);
+    for (let i = 0; i < mcpServers.length; i++) {
+      const s = mcpServers[i];
+      const prefix = i === mcpServers.length - 1 ? "  └─" : "  ├─";
+      if (s.alive) {
+        lines.push(`${prefix} ${s.id.padEnd(14)} ${dim("running")}  ${checkIcon(true)}`);
+      } else {
+        lines.push(`${prefix} ${s.id.padEnd(14)} ${dim("stopped")}  ${checkIcon(false)}`);
+      }
+    }
+  }
+
+  if ((daemon.pids || []).length > 1 || daemon.stalePidFile) {
+    lines.push(`\n${bold("  Daemon")}`);
+    if ((daemon.pids || []).length > 1) {
+      lines.push(`  ⚠️  Multiple daemon processes detected (pids: ${daemon.pids.join(", ")}). Run nemoris stop && nemoris start to fix.`);
+    }
+    if (daemon.stalePidFile) {
+      lines.push("  ⚠️  Stale PID file found. Daemon is not running.");
+    }
+  }
+
+  // Overall status
+  // An unhealthy provider is only critical if lanes can't resolve without it.
+  // If all lanes are ready, unhealthy providers are warnings (unused/optional).
+  const allDeliveryReady = delivery.every((d) => d.ready);
+  const allJobsHealthy = jobs.every((j) => j.healthy);
+  const allProviderHealthy = providers.every((p) => p.healthy);
+  const overallHealthy = configValid && (allProviderHealthy || allLanesReady) && allDeliveryReady && allJobsHealthy;
+
+  const suggCount = suggestions.length;
+  const suggNote = suggCount > 0 ? ` (${suggCount} suggestion${suggCount === 1 ? "" : "s"})` : "";
+  const overallLabel = overallHealthy ? bold("healthy") : bold("degraded");
+  lines.push(`\n  Overall: ${overallLabel}${suggNote}\n`);
+
+  // Suggestions
+  if (suggestions.length > 0) {
+    for (const s of suggestions) {
+      lines.push(`  \x1b[33m💡\x1b[0m ${s}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+// ── runDoctor ────────────────────────────────────────────────────────
+
+/**
+ * Orchestrates all health checks and returns a results object.
+ *
+ * @param {string} installDir  — path to the nemoris install root
+ * @param {{
+ *   execFileImpl?: Function,
+ *   fsImpl?: typeof import("node:fs"),
+ *   listServeDaemonPidsImpl?: Function,
+ * }} options
+ * @returns {Promise<object>}  — results suitable for formatDoctorReport + exitCode
+ */
+export async function runDoctor(
+  installDir,
+  {
+    execFileImpl = execFileAsync,
+    fsImpl = fs,
+    listServeDaemonPidsImpl = listServeDaemonPids,
+  } = {},
+) {
+  const results = {
+    platform: checkPlatform(),
+    installDir,
+    configValid: true,
+    configErrors: [],
+    dependencies: [],
+    providers: [],
+    lanes: [],
+    jobs: [],
+    delivery: [],
+    mcpServers: [],
+    daemon: {
+      pids: [],
+      stalePidFile: false,
+    },
+    suggestions: [],
+    exitCode: 0,
+  };
+
+  // ── 0. Dependency checks ──────────────────────────────────────────
+  try {
+    results.dependencies = await checkDependencies();
+  } catch {
+    // Dependency check failure is non-fatal
+  }
+
+  // ── 1. Config validation ─────────────────────────────────────────
+  try {
+    const { ConfigLoader } = await import("../config/loader.js");
+    const { validateAllConfigs } = await import("../config/schema-validator.js");
+    const configDir = `${installDir}/config`;
+    const loader = new ConfigLoader({ rootDir: configDir });
+    const config = await loader.loadAll();
+    const validation = validateAllConfigs(config, configDir);
+    results.configValid = validation.ok;
+    results.configErrors = validation.errors || [];
+    results._config = config;
+  } catch (err) {
+    // Gracefully degrade — config may not exist yet
+    results.configValid = false;
+    results.configErrors = [err.message || "Failed to load config"];
+    results._config = null;
+  }
+
+  // ── 2. Provider health ───────────────────────────────────────────
+  try {
+    const { ProviderRegistry } = await import("../providers/registry.js");
+    const config = results._config;
+    if (config?.providers) {
+      const registry = new ProviderRegistry({ fetchImpl: fetch });
+      for (const [id, providerConfig] of Object.entries(config.providers)) {
+        try {
+          const adapter = registry.create(providerConfig);
+          let healthy = true;
+          let status = null;
+          if (typeof adapter.healthCheck === "function") {
+            const h = await adapter.healthCheck();
+            healthy = Boolean(h.ok);
+            status = h.status ?? null;
+          }
+          results.providers.push({ id, healthy, status });
+        } catch (err) {
+          results.providers.push({ id, healthy: false, status: err.message });
+        }
+      }
+    }
+  } catch {
+    // Provider module unavailable — skip
+  }
+
+  // ── 3. Lane readiness ────────────────────────────────────────────
+  try {
+    const { buildLaneReadiness } = await import("../runtime/lane-readiness.js");
+    const config = results._config;
+    if (config?.router) {
+      for (const [laneId] of Object.entries(config.router)) {
+        try {
+          const readiness = buildLaneReadiness({ jobId: laneId });
+          results.lanes.push({ id: laneId, ready: readiness.ready !== false });
+        } catch {
+          results.lanes.push({ id: laneId, ready: false });
+        }
+      }
+    }
+  } catch {
+    // Lane readiness module unavailable — skip
+  }
+
+  // ── 4. Job dependency health ─────────────────────────────────────
+  try {
+    const { DependencyHealth } = await import("../runtime/dependency-health.js");
+    const config = results._config;
+    if (config?.jobs) {
+      const dh = new DependencyHealth({
+        projectRoot: installDir,
+        liveRoot: installDir,
+        fetchImpl: fetch,
+        execFileImpl,
+      });
+      for (const [jobId] of Object.entries(config.jobs)) {
+        try {
+          let healthy = true;
+          if (typeof dh.forJob === "function") {
+            const jobHealth = await dh.forJob(jobId);
+            healthy = Boolean(jobHealth?.ok !== false);
+          }
+          results.jobs.push({ id: jobId, healthy });
+        } catch {
+          results.jobs.push({ id: jobId, healthy: false });
+        }
+      }
+    }
+  } catch {
+    // Dependency health module unavailable — skip
+  }
+
+  // ── 5. Delivery channel readiness ───────────────────────────────
+  try {
+    const config = results._config;
+    if (config?.delivery?.profiles) {
+      for (const [id, profile] of Object.entries(config.delivery.profiles)) {
+        // Basic check: profile exists and has an adapter
+        const ready = Boolean(profile?.adapter);
+        results.delivery.push({ id, ready });
+      }
+    }
+  } catch {
+    // Delivery config unavailable — skip
+  }
+
+  // ── 5b. MCP server health ────────────────────────────────────────────────────
+  try {
+    const config = results._config;
+    if (config?.mcp?.servers) {
+      for (const id of Object.keys(config.mcp.servers)) {
+        // MCP servers are lazy — at doctor time they're not running.
+        // Report them as configured but stopped (informational only).
+        results.mcpServers.push({ id, alive: false });
+      }
+    }
+  } catch {
+    // MCP config unavailable — skip
+  }
+
+  // ── 5c. Daemon process health ────────────────────────────────────────────────
+  try {
+    const { pidFile } = getDaemonPaths(installDir);
+    results.daemon.pids = await listServeDaemonPidsImpl({ execFileImpl });
+    results.daemon.stalePidFile = results.daemon.pids.length === 0 && fsImpl.existsSync(pidFile);
+  } catch {
+    // Daemon process checks are best-effort only.
+  }
+
+  // ── 6. Suggestions ───────────────────────────────────────────────
+  try {
+    const config = results._config;
+    // Suggest Telegram if no delivery configured
+    if (!config?.delivery?.profiles || Object.keys(config.delivery?.profiles || {}).length === 0) {
+      results.suggestions.push("Connect Telegram for delivery: nemoris channel add telegram");
+    }
+    // Suggest enabling embeddings if no embedding config
+    if (config && !config.runtime?.embeddings?.enabled) {
+      // Only suggest if runtime loaded but embeddings not explicitly enabled
+      if (config.runtime && config.runtime.embeddings === undefined) {
+        results.suggestions.push("Enable embeddings for semantic memory search: set runtime.embeddings.enabled = true");
+      }
+    }
+  } catch {
+    // Skip suggestions on error
+  }
+
+  // ── 7. Determine exit code ───────────────────────────────────────
+  // Unhealthy providers are only critical if lanes can't resolve without them.
+  const allLanesOk = results.lanes.every((l) => l.ready);
+  const providerIssuesCritical = results.providers.some((p) => !p.healthy) && !allLanesOk;
+  const hasCritical = !results.configValid ||
+    providerIssuesCritical ||
+    results.delivery.some((d) => !d.ready);
+  const hasWarning = results.suggestions.length > 0 ||
+    results.providers.some((p) => !p.healthy) ||
+    results.jobs.some((j) => !j.healthy) ||
+    results.lanes.some((l) => !l.ready) ||
+    results.daemon.pids.length > 1 ||
+    results.daemon.stalePidFile;
+
+  if (hasCritical) {
+    results.exitCode = 2;
+  } else if (hasWarning) {
+    results.exitCode = 1;
+  } else {
+    results.exitCode = 0;
+  }
+
+  // Clean up internal fields
+  delete results._config;
+
+  return results;
+}