getculpa 1.0.9 → 1.1.0

package/lib/doctor.mjs

@@ -1,420 +1,454 @@
-// CF20-T5 — `getculpa doctor`. Support-paste-friendly, plain text (no ANSI,
-// ever — that trivially satisfies "no ANSI when not TTY" without a second
-// TTY-conditional code path to test), sectioned diagnostics.
-//
-// Exit-code contract (spec sec 31, "doctor-on-dormant"): only STRUCTURAL
-// integrity problems (a missing parity file, an unreadable install-state.json,
-// a missing vendored launcher, or an actively-running-but-unreachable
-// database) are FAILures. Everything Docker/network/health-related degrades
-// to a WARNing — a fully-provisioned but not-yet-started ("dormant") install
-// must report ok:true. This mirrors status.mjs's own "never throws, always
-// degrades honestly" contract, extended with a pass/fail verdict.
-//
-// Every docker/http call is injectable (spawnSync/fetchFn), same pattern as
-// lib/docker.mjs, lib/start.mjs and lib/status.mjs — no PATH shim, no real
-// network, no real container.
-
-import { spawnSync as realSpawnSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { findPortOwner, probeHealth, PROBE_TIMEOUT_MS } from "./docker.mjs";
-import { checkDockerPresent, checkDockerEngineReachable, classifyUpgrade, parsePinnedServerVersion } from "./preflight.mjs";
-import { parityAssetsFor } from "./provision.mjs";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const packageRoot = path.join(__dirname, "..");
-
-const PORTS_TO_CHECK = [3000, 4545];
-const DASHBOARD_URL = "http://127.0.0.1:3000";
-const API_HEALTH_URL = "http://127.0.0.1:4545/health";
-const ENTITLEMENT_URL = "http://127.0.0.1:4545/internal/entitlement";
-
-function check(section, label, status, detail) {
-  return { section, label, status, detail };
-}
-
-function readJsonSafe(filePath) {
-  try {
-    return JSON.parse(readFileSync(filePath, "utf8"));
-  } catch {
-    return null;
-  }
-}
-
-function readTextSafe(filePath) {
-  try {
-    return readFileSync(filePath, "utf8");
-  } catch {
-    return "";
-  }
-}
-
-// `docker ps -a --filter label=com.docker.compose.project=culpa` with a
-// tab-separated format — one call serves the "runtime/service state"
-// section AND tells the rest of doctor whether the project (and its db
-// container specifically) is running, without three separate `docker ps`
-// invocations.
-function listProjectContainers(spawnSync) {
-  const r = spawnSync(
-    "docker",
-    ["ps", "-a", "--filter", "label=com.docker.compose.project=culpa", "--format", "{{.Names}}\t{{.State}}\t{{.Status}}"],
-    { encoding: "utf8", timeout: PROBE_TIMEOUT_MS },
-  );
-  if (r.status !== 0) return [];
-  return (r.stdout ?? "")
-    .split("\n")
-    .map((l) => l.trim())
-    .filter(Boolean)
-    .map((line) => {
-      const [name, state, ...statusParts] = line.split("\t");
-      return { name: name ?? "", state: state ?? "", status: statusParts.join("\t") };
-    });
-}
-
-function getDockerServerVersion(spawnSync) {
-  const r = spawnSync("docker", ["version", "--format", "{{.Server.Version}}"], {
-    encoding: "utf8",
-    timeout: PROBE_TIMEOUT_MS,
-  });
-  if (r.status !== 0) return null;
-  return (r.stdout ?? "").trim() || null;
-}
-
-function checkVersionPlatform(currentVersion, platform, arch) {
-  return [
-    check("Version / platform", "getculpa package version", "info", currentVersion),
-    check("Version / platform", "Platform", "info", platform),
-    check("Version / platform", "Architecture", "info", arch),
-  ];
-}
-
-function checkVendoredLauncher(vendorDir, platform) {
-  const exe = platform === "win32" ? ".exe" : "";
-  const launcherPath = path.join(vendorDir, `culpa-launcher${exe}`);
-  const present = existsSync(launcherPath);
-  return check(
-    "Installation integrity",
-    "Vendored launcher",
-    present ? "ok" : "fail",
-    present ? launcherPath : `missing: ${launcherPath} (run \`npm rebuild getculpa\`, or reinstall)`,
-  );
-}
-
-function checkInstallationIntegrity(appDir, platform) {
-  const checks = [];
-  const liveComposePath = path.join(appDir, "docker-compose.yml");
-  const installed = existsSync(liveComposePath);
-
-  checks.push(check("Installation integrity", "App directory", installed ? "ok" : "info", appDir));
-
-  if (!installed) {
-    checks.push(check("Installation integrity", "Live compose", "info", "not installed - nothing to verify"));
-    return { checks, installed, state: null };
-  }
-
-  checks.push(check("Installation integrity", "Live compose", "ok", liveComposePath));
-
-  // T-CF28-6: grade only the files this platform is supposed to have. On
-  // darwin/linux the four Windows .ps1 scripts are correctly absent — listing
-  // them at all (as [OK] before, as a failure after the staging fix) reports
-  // on an install that does not exist.
-  for (const name of parityAssetsFor(platform)) {
-    const assetPath = path.join(appDir, name);
-    const present = existsSync(assetPath);
-    checks.push(
-      check(
-        "Installation integrity",
-        `Parity file: ${name}`,
-        present ? "ok" : "fail",
-        present ? assetPath : `missing: ${assetPath} (run \`getculpa repair\`)`,
-      ),
-    );
-  }
-
-  const state = readJsonSafe(path.join(appDir, "install-state.json"));
-  checks.push(
-    check(
-      "Installation integrity",
-      "install-state.json",
-      state ? "ok" : "fail",
-      state ? "readable" : "missing or unreadable (run `getculpa repair`)",
-    ),
-  );
-
-  checks.push(
-    check(
-      "Installation integrity",
-      "Capture collector",
-      state?.collectorStaged ? "ok" : "warn",
-      state?.collectorStaged ? "staged" : "not staged (capture is off on this install)",
-    ),
-  );
-
-  return { checks, installed, state };
-}
-
-function checkDocker(spawnSync) {
-  const checks = [];
-  const present = checkDockerPresent(spawnSync);
-  checks.push(
-    check("Docker", "Docker CLI", present ? "ok" : "warn", present ? "found" : "not found - install from https://docs.docker.com/get-docker/"),
-  );
-
-  const reachable = present && checkDockerEngineReachable(spawnSync);
-  checks.push(
-    check(
-      "Docker",
-      "Docker engine",
-      reachable ? "ok" : "warn",
-      reachable ? "running" : present ? "installed, but the engine is not running" : "unavailable (Docker not installed)",
-    ),
-  );
-
-  if (reachable) {
-    const version = getDockerServerVersion(spawnSync);
-    checks.push(check("Docker", "Docker version", version ? "ok" : "warn", version ?? "could not be determined"));
-  }
-
-  return { checks, reachable };
-}
-
-function checkRuntimeState(containers) {
-  if (containers.length === 0) {
-    return [check("Runtime / service state", "Containers", "info", "no containers for the culpa compose project (never started, or fully removed)")];
-  }
-  return containers.map((c) =>
-    check("Runtime / service state", c.name, c.state === "running" ? "ok" : "info", `${c.state} - ${c.status}`),
-  );
-}
-
-function checkExpectedDirectories(appDir, vendorDir) {
-  const dirs = [
-    ["App directory", appDir],
-    ["Backups directory", path.join(appDir, "backups")],
-    ["Vendor directory", vendorDir],
-  ];
-  return dirs.map(([label, dir]) => check("Expected directories", label, "info", `${existsSync(dir) ? "exists" : "missing"}: ${dir}`));
-}
-
-function checkDatabase(spawnSync, containers) {
-  const dbContainer = containers.find((c) => /culpa-db/.test(c.name));
-  if (!dbContainer || dbContainer.state !== "running") {
-    return [check("Database", "Postgres (culpa-db)", "info", "skipped - db container not running")];
-  }
-  const r = spawnSync("docker", ["exec", "culpa-db", "pg_isready", "-U", "culpa"], {
-    encoding: "utf8",
-    timeout: PROBE_TIMEOUT_MS,
-  });
-  const ready = r.status === 0;
-  return [check("Database", "Postgres (culpa-db)", ready ? "ok" : "fail", ready ? "accepting connections" : "container is running but not accepting connections")];
-}
-
-function checkMigrations(appDir) {
-  const lastBoot = readTextSafe(path.join(appDir, "last-boot-version.txt")).trim();
-  const pinned = parsePinnedServerVersion(readTextSafe(path.join(appDir, "docker-compose.yml")));
-  return [
-    check("Migrations", "Last booted server version", "info", lastBoot || "unknown (never recorded)"),
-    check("Migrations", "Live compose pinned server tag", "info", pinned ?? "unknown"),
-  ];
-}
-
-function checkPorts(spawnSync, platform, running) {
-  return PORTS_TO_CHECK.map((port) => {
-    const owner = findPortOwner(port, { platform, spawnSync });
-    if (!owner) return check("Ports", `:${port}`, "ok", "free");
-    if (running) return check("Ports", `:${port}`, "ok", `culpa-owned (${owner.name}, pid ${owner.pid})`);
-    return check("Ports", `:${port}`, "warn", `in use by ${owner.name} (pid ${owner.pid})`);
-  });
-}
-
-async function checkHealth(fetchFn, running) {
-  if (!running) {
-    return [
-      check("Culpa health", "Dashboard (:3000)", "info", "not running"),
-      check("Culpa health", "API (:4545)", "info", "not running"),
-    ];
-  }
-  const dashboardHealthy = await probeHealth(DASHBOARD_URL, { fetchFn });
-  const apiHealthy = await probeHealth(API_HEALTH_URL, { fetchFn });
-  return [
-    check("Culpa health", "Dashboard (:3000)", dashboardHealthy ? "ok" : "warn", dashboardHealthy ? "healthy" : "not responding"),
-    check("Culpa health", "API (:4545)", apiHealthy ? "ok" : "warn", apiHealthy ? "healthy" : "not responding"),
-  ];
-}
-
-function scanLicenseKeyPresence(env, appDir) {
-  // CodeRabbit PR#19 [6]: "   " is truthy — trim before believing the env
-  if ((env.CULPA_LICENSE_KEY ?? "").trim() !== "") return true;
-  const compose = readTextSafe(path.join(appDir, "docker-compose.yml"));
-  // V102 T-V102-15 (M6/W3, D-113): the old bare /CULPA_LICENSE_KEY/ regex
-  // matched a COMMENT line in the shipped compose, so doctor reported
-  // "[OK] present (redacted)" with no key set — on real hardware, both
-  // platforms, while `status` said "License: unknown" beside it. Only an
-  // uncommented env ENTRY carrying a non-empty value counts.
-  return compose.split(/\r?\n/).some((line) => {
-    const t = line.trim();
-    if (t.startsWith("#")) return false;
-    const m = /^-?\s*["']?CULPA_LICENSE_KEY["']?\s*[:=]\s*(.+)$/.exec(t);
-    if (m === null) return false;
-    // PR#19 [6]: "KEY: # configured elsewhere" is YAML for an EMPTY value
-    // plus a trailing comment — never a configured key
-    const value = m[1].trim().replace(/^["']|["']$/g, "").trim();
-    return value.length > 0 && !value.startsWith("#");
-  });
-}
-
-// Extracts ONLY configured/state/plan — even if the (possibly stubbed, in
-// tests) response carries other fields, they are never read into the
-// report. This is the redaction boundary the F1 fact tests.
-async function checkLicense(fetchFn, running, env, appDir) {
-  const checks = [];
-  const keyPresent = scanLicenseKeyPresence(env, appDir);
-  checks.push(check("License", "CULPA_LICENSE_KEY", keyPresent ? "ok" : "info", keyPresent ? "present (redacted)" : "not set"));
-
-  if (!running) {
-    checks.push(check("License", "Entitlement", "info", "unknown (server not running)"));
-    return checks;
-  }
-  try {
-    const res = await fetchFn(ENTITLEMENT_URL, { signal: AbortSignal.timeout(3_000) });
-    if (res.status !== 200) {
-      checks.push(check("License", "Entitlement", "warn", `server did not answer (status ${res.status})`));
-      return checks;
-    }
-    const body = await res.json();
-    const configured = typeof body?.configured === "boolean" ? body.configured : null;
-    const state = typeof body?.state === "string" ? body.state : null;
-    const plan = typeof body?.plan === "string" ? body.plan : null;
-    checks.push(
-      check(
-        "License",
-        "Entitlement",
-        "ok",
-        `configured=${configured ?? "unknown"}, state=${state ?? "n/a"}, plan=${plan ?? "n/a"}`,
-      ),
-    );
-  } catch {
-    checks.push(check("License", "Entitlement", "warn", "could not reach the server"));
-  }
-  return checks;
-}
-
-// CF20-R: classifyInstall alone cannot distinguish a package DOWNGRADE
-// (this package is older than what is already staged/live) from a
-// genuinely unclear install state — both collapsed into "repair" with the
-// same "run `getculpa repair`" message, which is misleading for a
-// downgrade (it is not unclear, it was a deliberate, correct refusal).
-// classifyUpgrade already makes that distinction (provision.mjs's own
-// caller uses it) — currentVersion was already threaded all the way from
-// bin/getculpa.js into this function; the gap was this function reading it
-// through the coarser classifier.
-function checkUpdateState(appDir, currentVersion, installed) {
-  const checks = [];
-  if (!installed) {
-    checks.push(check("Update state", "Install vs shipped version", "info", "not installed - nothing to compare"));
-    return checks;
-  }
-  const { classification: kind, previousVersion } = classifyUpgrade({ appDir, currentVersion });
-  const label = {
-    "same-version": ["ok", `up to date (v${currentVersion})`],
-    upgrade: ["warn", `an update is staged - run \`getculpa\` to apply it`],
-    repair: ["warn", "install state is unclear - run `getculpa repair`"],
-    fresh: ["info", "not installed"],
-    "downgrade-package": [
-      "warn",
-      `this package (v${currentVersion}) is OLDER than the installed Culpa v${previousVersion ?? "?"} - refusing to downgrade (set CULPA_ALLOW_DOWNGRADE=1 to override)`,
-    ],
-  }[kind] ?? ["info", kind];
-  checks.push(check("Update state", "Install vs shipped version", label[0], label[1]));
-
-  const updateStatePath = path.join(appDir, "updates", "state.json");
-  const launcherState = readJsonSafe(updateStatePath);
-  // Audit (flows) finding 2: this reported "ok" whenever the JSON merely
-  // PARSED, never looking at current. So on the exact stranded install
-  // T-CF28-4b exists to prevent - no payload ever staged - doctor printed
-  // "Overall: OK" while the very next getculpa dead-ended with "no installed
-  // version found". Diagnostics that reassure you about the broken thing are
-  // worse than none.
-  const noPayload = launcherState !== null && (launcherState.current ?? null) === null;
-  checks.push(
-    check(
-      "Update state",
-      "Launcher self-update state",
-      launcherState === null ? "info" : noPayload ? "fail" : "ok",
-      launcherState === null
-        ? "unknown (no update state recorded yet)"
-        : noPayload
-          ? "no CLI payload is staged (current=null) - run `getculpa update`, then `getculpa`"
-          : `current=${launcherState.current}, pending=${launcherState.pending ?? "none"}, mode=${launcherState.mode ?? "n/a"}`,
-    ),
-  );
-  return checks;
-}
-
-export async function doctor(opts) {
-  const {
-    appDir,
-    currentVersion,
-    platform = process.platform,
-    arch = process.arch,
-    spawnSync = realSpawnSync,
-    fetchFn = fetch,
-    env = process.env,
-    vendorDir = path.join(packageRoot, "vendor"),
-  } = opts;
-
-  const checks = [];
-  checks.push(...checkVersionPlatform(currentVersion, platform, arch));
-
-  const integrity = checkInstallationIntegrity(appDir, platform);
-  checks.push(...integrity.checks);
-  checks.push(checkVendoredLauncher(vendorDir, platform));
-
-  const docker = checkDocker(spawnSync);
-  checks.push(...docker.checks);
-
-  const containers = docker.reachable ? listProjectContainers(spawnSync) : [];
-  checks.push(...checkRuntimeState(containers));
-  checks.push(...checkExpectedDirectories(appDir, vendorDir));
-  checks.push(...checkDatabase(spawnSync, containers));
-  checks.push(...checkMigrations(appDir));
-
-  const running = containers.some((c) => c.state === "running");
-  checks.push(...checkPorts(spawnSync, platform, running));
-  checks.push(...(await checkHealth(fetchFn, running)));
-  checks.push(...(await checkLicense(fetchFn, running, env, appDir)));
-  checks.push(...checkUpdateState(appDir, currentVersion, integrity.installed));
-
-  const ok = !checks.some((c) => c.status === "fail");
-  return { ok, checks };
-}
-
-export function formatDoctorReport(result) {
-  const lines = [];
-  lines.push("Culpa doctor report");
-  lines.push("====================");
-  lines.push("");
-
-  const sections = [];
-  for (const c of result.checks) {
-    let section = sections.find((s) => s.name === c.section);
-    if (!section) {
-      section = { name: c.section, items: [] };
-      sections.push(section);
-    }
-    section.items.push(c);
-  }
-
-  for (const section of sections) {
-    lines.push(`-- ${section.name} --`);
-    for (const item of section.items) {
-      lines.push(`[${item.status.toUpperCase()}] ${item.label}: ${item.detail}`);
-    }
-    lines.push("");
-  }
-
-  const failureCount = result.checks.filter((c) => c.status === "fail").length;
-  lines.push(result.ok ? "Overall: OK" : `Overall: ${failureCount} failure(s) - see above ([FAIL] lines).`);
-  return lines.join("\n");
-}
+// CF20-T5 — `getculpa doctor`. Support-paste-friendly, plain text (no ANSI,
+// ever — that trivially satisfies "no ANSI when not TTY" without a second
+// TTY-conditional code path to test), sectioned diagnostics.
+//
+// Exit-code contract (spec sec 31, "doctor-on-dormant"): only STRUCTURAL
+// integrity problems (a missing parity file, an unreadable install-state.json,
+// a missing vendored launcher, or an actively-running-but-unreachable
+// database) are FAILures. Everything Docker/network/health-related degrades
+// to a WARNing — a fully-provisioned but not-yet-started ("dormant") install
+// must report ok:true. This mirrors status.mjs's own "never throws, always
+// degrades honestly" contract, extended with a pass/fail verdict.
+//
+// Every docker/http call is injectable (spawnSync/fetchFn), same pattern as
+// lib/docker.mjs, lib/start.mjs and lib/status.mjs — no PATH shim, no real
+// network, no real container.
+
+import { spawnSync as realSpawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { findPortOwner, probeHealth, PROBE_TIMEOUT_MS, runningImageVersions } from "./docker.mjs";
+import {
+  checkDockerPresent,
+  checkDockerEngineReachable,
+  classifyUpgrade,
+  parsePinnedServerVersion,
+  unprovisionedDiagnosis,
+  versionSkew,
+} from "./preflight.mjs";
+import { parityAssetsFor } from "./provision.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.join(__dirname, "..");
+
+const PORTS_TO_CHECK = [3000, 4545];
+const DASHBOARD_URL = "http://127.0.0.1:3000";
+const API_HEALTH_URL = "http://127.0.0.1:4545/health";
+const ENTITLEMENT_URL = "http://127.0.0.1:4545/internal/entitlement";
+
+function check(section, label, status, detail) {
+  return { section, label, status, detail };
+}
+
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function readTextSafe(filePath) {
+  try {
+    return readFileSync(filePath, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+// `docker ps -a --filter label=com.docker.compose.project=culpa` with a
+// tab-separated format — one call serves the "runtime/service state"
+// section AND tells the rest of doctor whether the project (and its db
+// container specifically) is running, without three separate `docker ps`
+// invocations.
+function listProjectContainers(spawnSync) {
+  const r = spawnSync(
+    "docker",
+    ["ps", "-a", "--filter", "label=com.docker.compose.project=culpa", "--format", "{{.Names}}\t{{.State}}\t{{.Status}}"],
+    { encoding: "utf8", timeout: PROBE_TIMEOUT_MS },
+  );
+  if (r.status !== 0) return [];
+  return (r.stdout ?? "")
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const [name, state, ...statusParts] = line.split("\t");
+      return { name: name ?? "", state: state ?? "", status: statusParts.join("\t") };
+    });
+}
+
+function getDockerServerVersion(spawnSync) {
+  const r = spawnSync("docker", ["version", "--format", "{{.Server.Version}}"], {
+    encoding: "utf8",
+    timeout: PROBE_TIMEOUT_MS,
+  });
+  if (r.status !== 0) return null;
+  return (r.stdout ?? "").trim() || null;
+}
+
+function checkVersionPlatform(currentVersion, platform, arch) {
+  return [
+    check("Version / platform", "getculpa package version", "info", currentVersion),
+    check("Version / platform", "Platform", "info", platform),
+    check("Version / platform", "Architecture", "info", arch),
+  ];
+}
+
+function checkVendoredLauncher(vendorDir, platform) {
+  const exe = platform === "win32" ? ".exe" : "";
+  const launcherPath = path.join(vendorDir, `culpa-launcher${exe}`);
+  const present = existsSync(launcherPath);
+  return check(
+    "Installation integrity",
+    "Vendored launcher",
+    present ? "ok" : "fail",
+    present ? launcherPath : `missing: ${launcherPath} (run \`npm rebuild getculpa\`, or reinstall)`,
+  );
+}
+
+function checkInstallationIntegrity(appDir, platform) {
+  const checks = [];
+  const liveComposePath = path.join(appDir, "docker-compose.yml");
+  const installed = existsSync(liveComposePath);
+
+  checks.push(check("Installation integrity", "App directory", installed ? "ok" : "info", appDir));
+
+  if (!installed) {
+    // T-179 (ISS-MAC-8): a package that runs but was never provisioned is
+    // not "nothing to verify" — it is the failure the customer is trying to
+    // diagnose. `info` here let the report end "Overall: OK".
+    const diagnosis = unprovisionedDiagnosis();
+    checks.push(check("Installation integrity", "Provisioning", "fail", `${diagnosis.message} ${diagnosis.recovery}`));
+    return { checks, installed, state: null };
+  }
+
+  checks.push(check("Installation integrity", "Live compose", "ok", liveComposePath));
+
+  // T-CF28-6: grade only the files this platform is supposed to have. On
+  // darwin/linux the four Windows .ps1 scripts are correctly absent — listing
+  // them at all (as [OK] before, as a failure after the staging fix) reports
+  // on an install that does not exist.
+  for (const name of parityAssetsFor(platform)) {
+    const assetPath = path.join(appDir, name);
+    const present = existsSync(assetPath);
+    checks.push(
+      check(
+        "Installation integrity",
+        `Parity file: ${name}`,
+        present ? "ok" : "fail",
+        present ? assetPath : `missing: ${assetPath} (run \`getculpa repair\`)`,
+      ),
+    );
+  }
+
+  const state = readJsonSafe(path.join(appDir, "install-state.json"));
+  checks.push(
+    check(
+      "Installation integrity",
+      "install-state.json",
+      state ? "ok" : "fail",
+      state ? "readable" : "missing or unreadable (run `getculpa repair`)",
+    ),
+  );
+
+  checks.push(
+    check(
+      "Installation integrity",
+      "Capture collector",
+      state?.collectorStaged ? "ok" : "warn",
+      state?.collectorStaged ? "staged" : "not staged (capture is off on this install)",
+    ),
+  );
+
+  return { checks, installed, state };
+}
+
+function checkDocker(spawnSync) {
+  const checks = [];
+  const present = checkDockerPresent(spawnSync);
+  checks.push(
+    check("Docker", "Docker CLI", present ? "ok" : "warn", present ? "found" : "not found - install from https://docs.docker.com/get-docker/"),
+  );
+
+  const reachable = present && checkDockerEngineReachable(spawnSync);
+  checks.push(
+    check(
+      "Docker",
+      "Docker engine",
+      reachable ? "ok" : "warn",
+      reachable ? "running" : present ? "installed, but the engine is not running" : "unavailable (Docker not installed)",
+    ),
+  );
+
+  if (reachable) {
+    const version = getDockerServerVersion(spawnSync);
+    checks.push(check("Docker", "Docker version", version ? "ok" : "warn", version ?? "could not be determined"));
+  }
+
+  return { checks, reachable };
+}
+
+function checkRuntimeState(containers) {
+  if (containers.length === 0) {
+    return [check("Runtime / service state", "Containers", "info", "no containers for the culpa compose project (never started, or fully removed)")];
+  }
+  return containers.map((c) =>
+    check("Runtime / service state", c.name, c.state === "running" ? "ok" : "info", `${c.state} - ${c.status}`),
+  );
+}
+
+function checkExpectedDirectories(appDir, vendorDir) {
+  const dirs = [
+    ["App directory", appDir],
+    ["Backups directory", path.join(appDir, "backups")],
+    ["Vendor directory", vendorDir],
+  ];
+  return dirs.map(([label, dir]) => check("Expected directories", label, "info", `${existsSync(dir) ? "exists" : "missing"}: ${dir}`));
+}
+
+function checkDatabase(spawnSync, containers) {
+  const dbContainer = containers.find((c) => /culpa-db/.test(c.name));
+  if (!dbContainer || dbContainer.state !== "running") {
+    return [check("Database", "Postgres (culpa-db)", "info", "skipped - db container not running")];
+  }
+  const r = spawnSync("docker", ["exec", "culpa-db", "pg_isready", "-U", "culpa"], {
+    encoding: "utf8",
+    timeout: PROBE_TIMEOUT_MS,
+  });
+  const ready = r.status === 0;
+  return [check("Database", "Postgres (culpa-db)", ready ? "ok" : "fail", ready ? "accepting connections" : "container is running but not accepting connections")];
+}
+
+function checkMigrations(appDir) {
+  const lastBoot = readTextSafe(path.join(appDir, "last-boot-version.txt")).trim();
+  const pinned = parsePinnedServerVersion(readTextSafe(path.join(appDir, "docker-compose.yml")));
+  return [
+    check("Migrations", "Last booted server version", "info", lastBoot || "unknown (never recorded)"),
+    check("Migrations", "Live compose pinned server tag", "info", pinned ?? "unknown"),
+  ];
+}
+
+// T-178 (ISS-MAC-7): a stack whose containers are behind the live pin, or a
+// live compose behind the shipped one, is a FINDING — doctor used to print
+// "Overall: OK" beside exactly that skew because nothing compared the three.
+function checkVersionSkew(appDir, spawnSync, running) {
+  const shippedText = readTextSafe(path.join(appDir, "culpa-compose.yml"));
+  const liveText = readTextSafe(path.join(appDir, "docker-compose.yml"));
+  const runningVersions = running ? runningImageVersions(spawnSync) : {};
+  const skew = versionSkew({ shippedText, liveText, running: runningVersions });
+  if (skew !== null) {
+    const detail =
+      skew.kind === "running-behind"
+        ? `${skew.component} is running ${skew.from} but the compose pins ${skew.to} - run \`getculpa\` to apply it`
+        : `live compose pins ${skew.from}, this package ships ${skew.to} - run \`getculpa\` to apply the update`;
+    return [check("Version skew", "Containers vs compose vs package", "fail", detail)];
+  }
+  if (!running || Object.keys(runningVersions).length === 0) {
+    return [check("Version skew", "Containers vs compose vs package", "info", running ? "running images could not be read" : "not running - nothing to compare")];
+  }
+  const server = runningVersions["culpa-server"] ?? Object.values(runningVersions)[0];
+  return [check("Version skew", "Containers vs compose vs package", "ok", `containers match the compose pins (${server})`)];
+}
+
+function checkPorts(spawnSync, platform, running) {
+  return PORTS_TO_CHECK.map((port) => {
+    const owner = findPortOwner(port, { platform, spawnSync });
+    if (!owner) return check("Ports", `:${port}`, "ok", "free");
+    if (running) return check("Ports", `:${port}`, "ok", `culpa-owned (${owner.name}, pid ${owner.pid})`);
+    return check("Ports", `:${port}`, "warn", `in use by ${owner.name} (pid ${owner.pid})`);
+  });
+}
+
+async function checkHealth(fetchFn, running) {
+  if (!running) {
+    return [
+      check("Culpa health", "Dashboard (:3000)", "info", "not running"),
+      check("Culpa health", "API (:4545)", "info", "not running"),
+    ];
+  }
+  const dashboardHealthy = await probeHealth(DASHBOARD_URL, { fetchFn });
+  const apiHealthy = await probeHealth(API_HEALTH_URL, { fetchFn });
+  return [
+    check("Culpa health", "Dashboard (:3000)", dashboardHealthy ? "ok" : "warn", dashboardHealthy ? "healthy" : "not responding"),
+    check("Culpa health", "API (:4545)", apiHealthy ? "ok" : "warn", apiHealthy ? "healthy" : "not responding"),
+  ];
+}
+
+function scanLicenseKeyPresence(env, appDir) {
+  // CodeRabbit PR#19 [6]: "   " is truthy — trim before believing the env
+  if ((env.CULPA_LICENSE_KEY ?? "").trim() !== "") return true;
+  const compose = readTextSafe(path.join(appDir, "docker-compose.yml"));
+  // V102 T-V102-15 (M6/W3, D-113): the old bare /CULPA_LICENSE_KEY/ regex
+  // matched a COMMENT line in the shipped compose, so doctor reported
+  // "[OK] present (redacted)" with no key set — on real hardware, both
+  // platforms, while `status` said "License: unknown" beside it. Only an
+  // uncommented env ENTRY carrying a non-empty value counts.
+  return compose.split(/\r?\n/).some((line) => {
+    const t = line.trim();
+    if (t.startsWith("#")) return false;
+    const m = /^-?\s*["']?CULPA_LICENSE_KEY["']?\s*[:=]\s*(.+)$/.exec(t);
+    if (m === null) return false;
+    // PR#19 [6]: "KEY: # configured elsewhere" is YAML for an EMPTY value
+    // plus a trailing comment — never a configured key
+    const value = m[1].trim().replace(/^["']|["']$/g, "").trim();
+    return value.length > 0 && !value.startsWith("#");
+  });
+}
+
+// Extracts ONLY configured/state/plan — even if the (possibly stubbed, in
+// tests) response carries other fields, they are never read into the
+// report. This is the redaction boundary the F1 fact tests.
+async function checkLicense(fetchFn, running, env, appDir) {
+  const checks = [];
+  const keyPresent = scanLicenseKeyPresence(env, appDir);
+  checks.push(check("License", "CULPA_LICENSE_KEY", keyPresent ? "ok" : "info", keyPresent ? "present (redacted)" : "not set"));
+
+  if (!running) {
+    checks.push(check("License", "Entitlement", "info", "unknown (server not running)"));
+    return checks;
+  }
+  try {
+    const res = await fetchFn(ENTITLEMENT_URL, { signal: AbortSignal.timeout(3_000) });
+    if (res.status !== 200) {
+      checks.push(check("License", "Entitlement", "warn", `server did not answer (status ${res.status})`));
+      return checks;
+    }
+    const body = await res.json();
+    const configured = typeof body?.configured === "boolean" ? body.configured : null;
+    const state = typeof body?.state === "string" ? body.state : null;
+    const plan = typeof body?.plan === "string" ? body.plan : null;
+    checks.push(
+      check(
+        "License",
+        "Entitlement",
+        "ok",
+        `configured=${configured ?? "unknown"}, state=${state ?? "n/a"}, plan=${plan ?? "n/a"}`,
+      ),
+    );
+  } catch {
+    checks.push(check("License", "Entitlement", "warn", "could not reach the server"));
+  }
+  return checks;
+}
+
+// CF20-R: classifyInstall alone cannot distinguish a package DOWNGRADE
+// (this package is older than what is already staged/live) from a
+// genuinely unclear install state — both collapsed into "repair" with the
+// same "run `getculpa repair`" message, which is misleading for a
+// downgrade (it is not unclear, it was a deliberate, correct refusal).
+// classifyUpgrade already makes that distinction (provision.mjs's own
+// caller uses it) — currentVersion was already threaded all the way from
+// bin/getculpa.js into this function; the gap was this function reading it
+// through the coarser classifier.
+function checkUpdateState(appDir, currentVersion, installed) {
+  const checks = [];
+  if (!installed) {
+    checks.push(check("Update state", "Install vs shipped version", "info", "not installed - nothing to compare"));
+    return checks;
+  }
+  const { classification: kind, previousVersion } = classifyUpgrade({ appDir, currentVersion });
+  const label = {
+    "same-version": ["ok", `up to date (v${currentVersion})`],
+    upgrade: ["warn", `an update is staged - run \`getculpa\` to apply it`],
+    repair: ["warn", "install state is unclear - run `getculpa repair`"],
+    fresh: ["info", "not installed"],
+    "downgrade-package": [
+      "warn",
+      `this package (v${currentVersion}) is OLDER than the installed Culpa v${previousVersion ?? "?"} - refusing to downgrade (set CULPA_ALLOW_DOWNGRADE=1 to override)`,
+    ],
+  }[kind] ?? ["info", kind];
+  checks.push(check("Update state", "Install vs shipped version", label[0], label[1]));
+
+  const updateStatePath = path.join(appDir, "updates", "state.json");
+  const launcherState = readJsonSafe(updateStatePath);
+  // Audit (flows) finding 2: this reported "ok" whenever the JSON merely
+  // PARSED, never looking at current. So on the exact stranded install
+  // T-CF28-4b exists to prevent - no payload ever staged - doctor printed
+  // "Overall: OK" while the very next getculpa dead-ended with "no installed
+  // version found". Diagnostics that reassure you about the broken thing are
+  // worse than none.
+  const noPayload = launcherState !== null && (launcherState.current ?? null) === null;
+  checks.push(
+    check(
+      "Update state",
+      "Launcher self-update state",
+      launcherState === null ? "info" : noPayload ? "fail" : "ok",
+      launcherState === null
+        ? "unknown (no update state recorded yet)"
+        : noPayload
+          ? "no CLI payload is staged (current=null) - run `getculpa update`, then `getculpa`"
+          : `current=${launcherState.current}, pending=${launcherState.pending ?? "none"}, mode=${launcherState.mode ?? "n/a"}`,
+    ),
+  );
+  return checks;
+}
+
+export async function doctor(opts) {
+  const {
+    appDir,
+    currentVersion,
+    platform = process.platform,
+    arch = process.arch,
+    spawnSync = realSpawnSync,
+    fetchFn = fetch,
+    env = process.env,
+    vendorDir = path.join(packageRoot, "vendor"),
+  } = opts;
+
+  const checks = [];
+  checks.push(...checkVersionPlatform(currentVersion, platform, arch));
+
+  const integrity = checkInstallationIntegrity(appDir, platform);
+  checks.push(...integrity.checks);
+  checks.push(checkVendoredLauncher(vendorDir, platform));
+
+  const docker = checkDocker(spawnSync);
+  checks.push(...docker.checks);
+
+  const containers = docker.reachable ? listProjectContainers(spawnSync) : [];
+  checks.push(...checkRuntimeState(containers));
+  checks.push(...checkExpectedDirectories(appDir, vendorDir));
+  checks.push(...checkDatabase(spawnSync, containers));
+  checks.push(...checkMigrations(appDir));
+
+  const running = containers.some((c) => c.state === "running");
+  checks.push(...checkVersionSkew(appDir, spawnSync, running));
+  checks.push(...checkPorts(spawnSync, platform, running));
+  checks.push(...(await checkHealth(fetchFn, running)));
+  checks.push(...(await checkLicense(fetchFn, running, env, appDir)));
+  checks.push(...checkUpdateState(appDir, currentVersion, integrity.installed));
+
+  const ok = !checks.some((c) => c.status === "fail");
+  return { ok, checks };
+}
+
+export function formatDoctorReport(result) {
+  const lines = [];
+  lines.push("Culpa doctor report");
+  lines.push("====================");
+  lines.push("");
+
+  const sections = [];
+  for (const c of result.checks) {
+    let section = sections.find((s) => s.name === c.section);
+    if (!section) {
+      section = { name: c.section, items: [] };
+      sections.push(section);
+    }
+    section.items.push(c);
+  }
+
+  for (const section of sections) {
+    lines.push(`-- ${section.name} --`);
+    for (const item of section.items) {
+      lines.push(`[${item.status.toUpperCase()}] ${item.label}: ${item.detail}`);
+    }
+    lines.push("");
+  }
+
+  const failureCount = result.checks.filter((c) => c.status === "fail").length;
+  lines.push(result.ok ? "Overall: OK" : `Overall: ${failureCount} failure(s) - see above ([FAIL] lines).`);
+  return lines.join("\n");
+}