@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/capabilities/doctor/checks/checkPackageRefs.ts

@@ -0,0 +1,73 @@
+/**
+ * Doctor check: report how each configured semantic package resolves.
+ *
+ * ADAPTED for v2: the old local>git>bundled loader chain is retired — resolution
+ * now flows through `sources update` into `pragma.lock.json` + the cached pack.
+ * This check reads the lock (which packages resolved) and the storeless pack
+ * index (the entity total), never booting the store. An absent lock with
+ * configured packages is the "run `sources update`" case.
+ */
+
+import {
+  entityTotal,
+  readPackIndex,
+} from "../../../kernel/completion/entitySource.js";
+import type { PackageEntry } from "../../../kernel/config/types.js";
+import { readLock } from "../../../kernel/runtime/lock.js";
+import type { PragmaRuntime } from "../../../kernel/runtime/types.js";
+import type { CheckItem, CheckResult } from "../types.js";
+
+const entryName = (entry: PackageEntry): string =>
+  typeof entry === "string" ? entry : entry.name;
+
+/**
+ * Report package resolution status against the lock and the entity total.
+ *
+ * @param rt - The per-invocation runtime.
+ * @returns A CheckResult with a per-package breakdown.
+ * @note Impure — reads config, the lock, and the pack index from disk.
+ */
+export async function checkPackageRefs(
+  rt: PragmaRuntime,
+): Promise<CheckResult> {
+  const entries = (await rt.loadConfig()).config.packages ?? [];
+  const lock = readLock(rt.cwd);
+  const index = readPackIndex(rt.cwd);
+  const totalEntities = index ? entityTotal(index) : 0;
+
+  if (entries.length === 0) {
+    return {
+      name: "package refs",
+      status: "pass",
+      detail: `no packages configured — the embedded pack answers reads (${totalEntities.toLocaleString()} entities)`,
+    };
+  }
+
+  const items: CheckItem[] = [];
+  let unresolved = 0;
+  for (const entry of entries) {
+    const name = entryName(entry);
+    const packEntry = lock?.packs.find((pack) => pack.name === name);
+    if (packEntry) {
+      items.push({
+        label: name,
+        status: "pass",
+        detail: `resolved ${packEntry.resolved}`,
+      });
+    } else {
+      items.push({ label: name, status: "fail", detail: "not in the lock" });
+      unresolved += 1;
+    }
+  }
+
+  const ok = lock !== undefined && unresolved === 0;
+  return {
+    name: "package refs",
+    status: ok ? "pass" : "fail",
+    detail: ok
+      ? `${entries.length} package(s) resolved · ${totalEntities.toLocaleString()} entities`
+      : `${unresolved} of ${entries.length} package(s) not resolved`,
+    items,
+    ...(ok ? {} : { remedy: "pragma sources update" }),
+  };
+}

package/src/capabilities/doctor/checks/checkPragmaVersion.ts

@@ -0,0 +1,22 @@
+import type { PragmaRuntime } from "../../../kernel/runtime/types.js";
+import { detectInstallSource } from "../../shared/packageManager.js";
+import type { CheckResult } from "../types.js";
+
+/**
+ * Report the pragma version and how it was installed. Always passes — purely
+ * informational.
+ *
+ * @param rt - The per-invocation runtime (for `version`).
+ * @returns A CheckResult with version and install details.
+ * @note Impure — reads the process for the install heuristic.
+ */
+export async function checkPragmaVersion(
+  rt: PragmaRuntime,
+): Promise<CheckResult> {
+  const install = detectInstallSource();
+  return {
+    name: "pragma version",
+    status: "pass",
+    detail: `v${rt.version} (installed via ${install.label})`,
+  };
+}

package/src/capabilities/doctor/checks/checkShellCompletions.test.ts

@@ -0,0 +1,111 @@
+/**
+ * `checkShellCompletions` — the doctor check that verifies completions are
+ * installed AND functional.
+ *
+ * Runs against an isolated HOME and a controlled `$SHELL` so the three gates —
+ * the resolver effect test, the real install-path probe, and the zsh fpath
+ * activation gate — are deterministic. The effect test (gate 1) drives the real
+ * `runComplete` resolver; the install/fpath gates write real files under the
+ * temp HOME rather than mocking the fs.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { completionScriptPath } from "../../setup/shell.js";
+import { checkShellCompletions } from "./checkShellCompletions.js";
+
+const roots: string[] = [];
+const tmp = (): string => {
+  const dir = mkdtempSync(join(tmpdir(), "pragma-completions-"));
+  roots.push(dir);
+  return dir;
+};
+
+let prevHome: string | undefined;
+let prevShell: string | undefined;
+beforeEach(() => {
+  prevHome = process.env.HOME;
+  prevShell = process.env.SHELL;
+  process.env.HOME = tmp();
+});
+afterEach(() => {
+  process.env.HOME = prevHome;
+  if (prevShell === undefined) delete process.env.SHELL;
+  else process.env.SHELL = prevShell;
+  for (const dir of roots) rmSync(dir, { recursive: true, force: true });
+  roots.length = 0;
+});
+
+/** Write the (empty) completion script to the shell's real install path. */
+function installScript(shell: "zsh" | "bash" | "fish"): void {
+  const path = completionScriptPath(shell);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, "# stub\n");
+}
+
+/** Write a `.zshrc` that puts ~/.zfunc on fpath. */
+function wireZfunc(): void {
+  writeFileSync(
+    join(process.env.HOME as string, ".zshrc"),
+    "fpath=(~/.zfunc $fpath)\nautoload -Uz compinit && compinit\n",
+  );
+}
+
+describe("checkShellCompletions — effect test (gate 1)", () => {
+  it("passes the resolver gate: `pragma <TAB>` resolves nouns", async () => {
+    // No shell → skip, but only AFTER the resolver answered — the detail proves
+    // the effect test ran and succeeded.
+    delete process.env.SHELL;
+    const result = await checkShellCompletions(tmp());
+    expect(result.status).toBe("skip");
+    expect(result.detail).toMatch(/resolver OK/);
+  });
+});
+
+describe("checkShellCompletions — install probe (gate 2)", () => {
+  it("fails when $SHELL is set but no script is installed", async () => {
+    process.env.SHELL = "/usr/bin/bash";
+    const result = await checkShellCompletions(tmp());
+    expect(result.status).toBe("fail");
+    expect(result.detail).toMatch(/not installed/);
+    expect(result.remedy).toBe("pragma setup completions");
+  });
+
+  it("passes for bash once the script exists at its real path", async () => {
+    process.env.SHELL = "/usr/bin/bash";
+    installScript("bash");
+    const result = await checkShellCompletions(tmp());
+    expect(result.status).toBe("pass");
+    expect(result.detail).toMatch(/bash installed and resolving/);
+  });
+
+  it("passes for fish once the script exists at its real path", async () => {
+    process.env.SHELL = "/usr/bin/fish";
+    installScript("fish");
+    const result = await checkShellCompletions(tmp());
+    expect(result.status).toBe("pass");
+  });
+});
+
+describe("checkShellCompletions — zsh fpath activation (gate 3)", () => {
+  it("fails when the zsh script is installed but ~/.zfunc is not on fpath", async () => {
+    process.env.SHELL = "/usr/bin/zsh";
+    installScript("zsh");
+    const result = await checkShellCompletions(tmp());
+    expect(result.status).toBe("fail");
+    expect(result.detail).toMatch(/not on your fpath/);
+    // The remedy IS the activation hint — the exact ~/.zshrc lines.
+    expect(result.remedy).toMatch(/fpath=\(~\/\.zfunc/);
+  });
+
+  it("passes once the zsh script is installed AND ~/.zfunc is on fpath", async () => {
+    process.env.SHELL = "/usr/bin/zsh";
+    installScript("zsh");
+    wireZfunc();
+    const result = await checkShellCompletions(tmp());
+    expect(result.status).toBe("pass");
+    expect(result.detail).toMatch(/zsh installed and resolving/);
+  });
+});

package/src/capabilities/doctor/checks/checkShellCompletions.ts

@@ -0,0 +1,131 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  indexCompletionEnv,
+  runComplete,
+} from "../../../kernel/completion/index.js";
+import { capabilities } from "../../index.js";
+import {
+  activationHint,
+  completionScriptPath,
+  detectShell,
+} from "../../setup/shell.js";
+import type { CheckResult } from "../types.js";
+
+const NAME = "Shell completions";
+
+/**
+ * Whether the user's `.zshrc` puts `~/.zfunc` on `$fpath` — the activation step
+ * `setup completions` cannot perform for the user. zsh loads nothing from
+ * `~/.zfunc` unless it is on `fpath` before `compinit`, so an installed script
+ * with no fpath wiring is silently dead. A permissive check: any `fpath` line
+ * mentioning `.zfunc` counts (we can't parse ordering statically).
+ */
+function zfuncOnFpath(): boolean {
+  try {
+    const rc = readFileSync(join(homedir(), ".zshrc"), "utf-8");
+    return rc
+      .split("\n")
+      .some((line) => line.includes("fpath") && line.includes(".zfunc"));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Drive the storeless `__complete` resolver and observe that it answers — the
+ * completion effect the installed script delegates every name context to. Uses
+ * the noun context (`pragma <TAB>`), which is grammar-derived and never empty,
+ * so a zero here means the resolver itself is broken, independent of any pack.
+ *
+ * @param cwd - The project directory (wires the entity seam, though the noun
+ *   context does not read it).
+ * @returns The number of candidates the resolver returned for a bare `pragma `.
+ */
+async function completeProbe(cwd: string): Promise<number> {
+  const matches = await runComplete(
+    [""],
+    capabilities,
+    indexCompletionEnv(cwd),
+  );
+  return matches.length;
+}
+
+/**
+ * Check that shell completions are installed AND functional.
+ *
+ * Three gates, in order:
+ * 1. The resolver answers (`completeProbe` drives `runComplete` end to end) —
+ *    the effect every installed script depends on. A failure here is a real
+ *    regression, so it fails even when nothing is installed.
+ * 2. The script file exists at the shell's real install path (`shell.ts`) —
+ *    NOT a `"pragma"` substring in an RC file, which `setup completions` never
+ *    writes.
+ * 3. For zsh, `~/.zfunc` is on `$fpath` — the activation step setup can only
+ *    hint. Installed-but-unwired reports a distinct remedy.
+ *
+ * @param cwd - The project directory (for the resolver's entity seam).
+ * @returns A CheckResult: pass (installed + wired + answering), fail (with the
+ *   attributable remedy), or skip (shell undetected).
+ * @note Impure — reads `$SHELL`, the install path, `.zshrc`, and drives the
+ *   storeless resolver.
+ */
+export async function checkShellCompletions(cwd: string): Promise<CheckResult> {
+  // 1. Effect test: the resolver the scripts delegate to must actually answer.
+  let candidates: number;
+  try {
+    candidates = await completeProbe(cwd);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return {
+      name: NAME,
+      status: "fail",
+      detail: `completion resolver failed: ${reason}`,
+      remedy: "Report this as a bug — `pragma __complete` should never throw.",
+    };
+  }
+  if (candidates === 0) {
+    return {
+      name: NAME,
+      status: "fail",
+      detail: "completion resolver returned no candidates for `pragma <TAB>`",
+      remedy: "Report this as a bug — the noun context is always non-empty.",
+    };
+  }
+
+  // 2. The script file exists at the shell's real install path.
+  const shell = detectShell();
+  if (!shell) {
+    return {
+      name: NAME,
+      status: "skip",
+      detail: "resolver OK; shell not detected ($SHELL unset)",
+    };
+  }
+  const path = completionScriptPath(shell);
+  if (!existsSync(path)) {
+    return {
+      name: NAME,
+      status: "fail",
+      detail: `resolver OK; ${shell} script not installed`,
+      remedy: "pragma setup completions",
+    };
+  }
+
+  // 3. zsh only: the script is dead unless ~/.zfunc is on $fpath.
+  if (shell === "zsh" && !zfuncOnFpath()) {
+    return {
+      name: NAME,
+      status: "fail",
+      detail: `installed at ${path}, but ~/.zfunc is not on your fpath`,
+      remedy: activationHint("zsh"),
+    };
+  }
+
+  return {
+    name: NAME,
+    status: "pass",
+    detail: `${shell} installed and resolving (${candidates} nouns)`,
+  };
+}

package/src/capabilities/doctor/checks/checkSkillsSymlinked.ts

@@ -0,0 +1,60 @@
+import { existsSync } from "node:fs";
+import type { DetectedHarness } from "@canonical/harnesses";
+import { detectHarnesses } from "@canonical/harnesses";
+import { runTask } from "@canonical/task/node";
+import type { CheckResult } from "../types.js";
+
+/**
+ * Check that a skills directory exists for each detected AI harness. Skipped
+ * when no harnesses are detected.
+ *
+ * @param cwd - The project root to detect harnesses against.
+ * @returns A CheckResult indicating pass, fail (with a remedy), or skip.
+ * @note Impure — detects harnesses and probes the filesystem.
+ */
+export async function checkSkillsSymlinked(cwd: string): Promise<CheckResult> {
+  let detected: DetectedHarness[];
+  try {
+    detected = await runTask(detectHarnesses(cwd));
+  } catch {
+    return {
+      name: "Skills symlinked",
+      status: "fail",
+      detail: "harness detection failed",
+      remedy: "pragma setup skills",
+    };
+  }
+
+  if (detected.length === 0) {
+    return {
+      name: "Skills symlinked",
+      status: "skip",
+      detail: "no AI harnesses detected",
+    };
+  }
+
+  const linked: string[] = [];
+  const missing: string[] = [];
+  for (const d of detected) {
+    if (existsSync(d.harness.skillsPath(cwd))) {
+      linked.push(d.harness.name);
+    } else {
+      missing.push(d.harness.name);
+    }
+  }
+
+  if (missing.length === 0) {
+    return {
+      name: "Skills symlinked",
+      status: "pass",
+      detail: linked.join(", "),
+    };
+  }
+
+  return {
+    name: "Skills symlinked",
+    status: "fail",
+    detail: `missing for ${missing.join(", ")}`,
+    remedy: "pragma setup skills",
+  };
+}

package/src/capabilities/doctor/doctor.render.ts

@@ -0,0 +1,116 @@
+/**
+ * Formatters for `pragma doctor` — plain (chalk), llm (Markdown), json.
+ *
+ * Ported from the old shell's `doctor/formatters/doctor.ts`, retargeted at the
+ * kernel `Formatters` contract.
+ */
+
+import chalk from "chalk";
+import type { Formatters } from "../../kernel/spec/types.js";
+import type { CheckResult, CheckStatus, DoctorData } from "./types.js";
+
+/** Status icons for pass/fail/skip results (checks and sub-items). */
+const STATUS_ICONS: Record<CheckStatus, string> = {
+  pass: chalk.green("✓"),
+  fail: chalk.red("✗"),
+  skip: chalk.yellow("○"),
+};
+
+const SUB_BULLET = chalk.dim("·");
+const FIX_ARROW = chalk.cyan("↳");
+const INDENT = "     "; // aligns sub-lines under the check name
+
+/**
+ * Render one check as terminal lines: a headline row (icon, aligned name,
+ * detail), an optional indented breakdown of sub-items, and — for failures — an
+ * inline remedial instruction.
+ */
+function formatCheckPlain(check: CheckResult, nameWidth: number): string[] {
+  const name = check.name.padEnd(nameWidth);
+  const label = check.status === "fail" ? chalk.red(name) : chalk.bold(name);
+  const lines = [
+    `  ${STATUS_ICONS[check.status]}  ${label}  ${chalk.dim(check.detail)}`,
+  ];
+
+  if (check.items && check.items.length > 0) {
+    const itemWidth = Math.max(...check.items.map((i) => i.label.length));
+    const anyStatus = check.items.some((i) => i.status !== undefined);
+    for (const item of check.items) {
+      const icon = anyStatus
+        ? item.status
+          ? `${STATUS_ICONS[item.status]} `
+          : "  "
+        : "";
+      const itemLabel = item.detail ? item.label.padEnd(itemWidth) : item.label;
+      const detail = item.detail ? `  ${chalk.dim(item.detail)}` : "";
+      lines.push(`${INDENT}${SUB_BULLET} ${icon}${itemLabel}${detail}`);
+    }
+  }
+
+  if (check.status === "fail" && check.remedy) {
+    lines.push(`${INDENT}${FIX_ARROW} ${chalk.cyan("fix:")} ${check.remedy}`);
+  }
+
+  return lines;
+}
+
+/** Render the pass/fail/skip tally, coloring non-zero fail/skip. */
+function formatSummary(data: DoctorData): string {
+  const parts = [chalk.green(`${data.passed} passed`)];
+  parts.push(
+    data.failed > 0
+      ? chalk.red(`${data.failed} failed`)
+      : chalk.dim(`${data.failed} failed`),
+  );
+  parts.push(
+    data.skipped > 0
+      ? chalk.yellow(`${data.skipped} skipped`)
+      : chalk.dim(`${data.skipped} skipped`),
+  );
+  return `  ${parts.join(chalk.dim(" · "))}`;
+}
+
+export const doctorFormatters: Formatters<DoctorData> = {
+  plain(data) {
+    const nameWidth = Math.max(...data.checks.map((c) => c.name.length), 0);
+    const lines: string[] = [chalk.bold("pragma doctor"), ""];
+    for (const check of data.checks) {
+      lines.push(...formatCheckPlain(check, nameWidth));
+    }
+    lines.push("", formatSummary(data));
+    return lines.join("\n");
+  },
+
+  llm(data) {
+    const lines: string[] = ["## Doctor", ""];
+    for (const check of data.checks) {
+      const icon =
+        check.status === "pass" ? "✓" : check.status === "fail" ? "✗" : "○";
+      lines.push(`- ${icon} **${check.name}**: ${check.detail}`);
+      for (const item of check.items ?? []) {
+        const itemIcon =
+          item.status === "pass"
+            ? "✓ "
+            : item.status === "fail"
+              ? "✗ "
+              : item.status === "skip"
+                ? "○ "
+                : "";
+        const detail = item.detail ? `: ${item.detail}` : "";
+        lines.push(`  - ${itemIcon}${item.label}${detail}`);
+      }
+      if (check.status === "fail" && check.remedy) {
+        lines.push(`  - _fix:_ \`${check.remedy}\``);
+      }
+    }
+    lines.push(
+      "",
+      `_${data.passed} passed, ${data.failed} failed, ${data.skipped} skipped_`,
+    );
+    return lines.join("\n");
+  },
+
+  json(data) {
+    return JSON.stringify(data);
+  },
+};

package/src/capabilities/doctor/doctor.test.ts

@@ -0,0 +1,179 @@
+/**
+ * `pragma doctor` — the nine environment health checks.
+ *
+ * Runs against isolated HOME/cwd/XDG so the harness/config/completion checks are
+ * deterministic (no harnesses, no config, no rc files). Covers the shape, a
+ * representative pass/fail/skip spread, the store check (down via an injected
+ * throwing store; up via the canonical fixture), exit 0 despite failures, and
+ * the MCP read-only envelope.
+ */
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type { ConfigLayers } from "../../kernel/config/types.js";
+import { executeVerb } from "../../kernel/project/cli/dispatch.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import { createQueryFacade } from "../../kernel/runtime/facade.js";
+import type {
+  GlobalFlags,
+  LazyStore,
+  PragmaRuntime,
+} from "../../kernel/runtime/types.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import {
+  ALL_VISIBLE_CONFIG,
+  CANONICAL_TTL,
+} from "../../testing/fixtures/graph/canonical.js";
+import { bootFixtureRuntime } from "../../testing/helpers/fixtureGraph.js";
+import { projectMcp } from "../../testing/helpers/projectMcp.js";
+import { doctorModule } from "./index.js";
+import { runChecks } from "./runChecks.js";
+import type { DoctorData } from "./types.js";
+
+const FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+const NO_MUT = { dryRun: false, undo: false, yes: false };
+const doctorVerb = doctorModule.verbs[0] as VerbSpec;
+
+const roots: string[] = [];
+const tmp = (prefix: string): string => {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+  roots.push(dir);
+  return dir;
+};
+
+let prevHome: string | undefined;
+let prevXdg: string | undefined;
+beforeEach(() => {
+  prevHome = process.env.HOME;
+  prevXdg = process.env.XDG_CONFIG_HOME;
+  // Empty HOME/XDG so `~`-based harness signals, rc files, and the global config
+  // are all absent — the harness/config/completion checks become deterministic.
+  process.env.HOME = tmp("pragma-doctor-home-");
+  process.env.XDG_CONFIG_HOME = tmp("pragma-doctor-xdg-");
+});
+afterEach(() => {
+  process.env.HOME = prevHome;
+  process.env.XDG_CONFIG_HOME = prevXdg;
+  for (const dir of roots) rmSync(dir, { recursive: true, force: true });
+  roots.length = 0;
+});
+
+const defaultLayers: ConfigLayers = {
+  config: { channel: "normal" },
+  origins: {
+    tier: "default",
+    channel: "default",
+    detail: "default",
+    packages: "default",
+    stories: "default",
+    prefixes: "default",
+    prompts: "default",
+  },
+  global: { path: "", exists: false },
+  project: { exists: false },
+};
+
+/** A runtime whose store fails to boot — for the store-down check path. */
+function throwingStoreRuntime(cwd: string): PragmaRuntime {
+  const store: LazyStore = {
+    get booted() {
+      return false;
+    },
+    async get() {
+      throw new Error("store down");
+    },
+    invalidate() {},
+  };
+  return {
+    cwd,
+    version: "9.9.9",
+    globalFlags: FLAGS,
+    loadConfig: async () => defaultLayers,
+    store,
+    query: createQueryFacade(store),
+  };
+}
+
+const byName = (data: DoctorData, name: string) =>
+  data.checks.find((c) => c.name === name);
+
+describe("doctor — shape & spread", () => {
+  it("returns 9 checks whose tallies sum, each with a valid status", async () => {
+    const data = await runChecks(bootRuntime(FLAGS, tmp("pragma-proj-")));
+    expect(data.checks).toHaveLength(9);
+    expect(data.passed + data.failed + data.skipped).toBe(9);
+    for (const check of data.checks) {
+      expect(["pass", "fail", "skip"]).toContain(check.status);
+    }
+    // Deterministic under the isolated env.
+    expect(byName(data, "Node version")?.status).toBe("pass");
+    // The 3 default-config packages are configured but not locked here → an
+    // attributable fail listing them, with the sources-update remedy.
+    const pkgRefs = byName(data, "package refs");
+    expect(pkgRefs?.status).toBe("fail");
+    expect(pkgRefs?.remedy).toBe("pragma sources update");
+    expect(pkgRefs?.items?.length).toBe(3);
+    // No harnesses in an empty HOME/cwd — attributable fail + skips.
+    expect(byName(data, "MCP configured")?.status).toBe("fail");
+    expect(byName(data, "Skills symlinked")?.status).toBe("skip");
+    expect(byName(data, "MCP commands")?.status).toBe("skip");
+    // No project/global config in the isolated XDG.
+    expect(byName(data, "pragma config")?.status).toBe("fail");
+  });
+});
+
+describe("doctor — the store check", () => {
+  it("a store that fails to boot is an attributable fail, not a crash", async () => {
+    const data = await runChecks(throwingStoreRuntime(tmp("pragma-proj-")));
+    expect(data.checks).toHaveLength(9);
+    const keStore = byName(data, "ke store");
+    expect(keStore?.status).toBe("fail");
+    expect(keStore?.remedy).toBeTruthy();
+  });
+
+  it("a booted store passes with an entity total", async () => {
+    const fixture = await bootFixtureRuntime({
+      ttl: CANONICAL_TTL,
+      config: ALL_VISIBLE_CONFIG,
+    });
+    const data = await runChecks(fixture.runtime);
+    const keStore = byName(data, "ke store");
+    expect(keStore?.status).toBe("pass");
+    expect(keStore?.detail).toMatch(/entities/);
+    await fixture.dispose();
+  });
+});
+
+describe("doctor — dispatch & MCP", () => {
+  it("exits 0 even when checks fail (failures live in the envelope)", async () => {
+    const outcome = await executeVerb(
+      doctorVerb,
+      {},
+      NO_MUT,
+      bootRuntime(FLAGS, tmp("pragma-proj-")),
+    );
+    expect(outcome.exitCode).toBe(0);
+  });
+
+  it("MCP doctor is read-only and returns the checks envelope", async () => {
+    const mcp = await projectMcp([doctorModule], tmp("pragma-proj-"));
+    const tools = await mcp.listTools();
+    const doctorTool = tools.find((t) => t.name === "doctor");
+    expect(
+      (doctorTool?.annotations as { readOnlyHint?: boolean } | undefined)
+        ?.readOnlyHint,
+    ).toBe(true);
+
+    const envelope = await mcp.callTool("doctor");
+    await mcp.cleanup();
+    expect(envelope.ok).toBe(true);
+    expect((envelope.data as DoctorData).checks).toHaveLength(9);
+  });
+});