@canonical/pragma-cli 0.35.0 → 0.37.0

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

@@ -1,7 +1,7 @@
 /**
- * The banded doctor rows, derived from the setup target table.
+ * The scoped doctor rows, derived from the setup target table.
  *
- * `doctor` and `setup` are the SAME LIST. Every banded row here carries a
+ * `doctor` and `setup` are the SAME LIST. Every scoped row here carries a
  * target id verbatim — `completions`, not "Shell completions"; `mcp`, not "MCP
  * configured" — because the row name IS the fix command's argument, and a user
  * who reads `✗ mcp` beside `fix: pragma setup mcp` can see that they are the
@@ -11,11 +11,18 @@
  *
  * Every row's detection comes from the target table's own `detect`, so the two
  * surfaces cannot disagree about what they looked at, and every `fix:` is
- * derived from the row's id and band rather than authored per check.
+ * derived from the row's id and scope rather than authored per check.
  *
- * Doctor's UNBANDED environment checks (Node version, the CLI's own version,
+ * Doctor's UNSCOPED environment checks (Node version, the CLI's own version,
  * pack refs, the store) diagnose things setup cannot install and stay outside
  * this list.
+ *
+ * ONE scoped row is not a target: `harnesses`, the per-scope inventory. It is an
+ * inventory of the machine the targets are measured against, not a target that
+ * can be set up, so it deliberately carries no `fix:` and can never be `fail`
+ * or `available` — see {@link inventoryChecks}. The bijection between the other
+ * rows and the setup table is untouched: `harnesses` is not a `TargetId`, and
+ * nothing derives a command from it.
  */
 
 import { MCP_SERVER_NAME } from "../../../constants.js";
@@ -36,15 +43,24 @@ import {
   lspSkipReason,
   type McpDetection,
   mcpGroupState,
+  mcpWriteState,
   type SkillsDetection,
   skillsSkipReason,
+  skillsSkipRemedy,
 } from "../../setup/operations/index.js";
 import { shortenPath, TARGET_IDS } from "../../setup/plan.js";
-import type { CheckItem, CheckResult, ScopeBand } from "../types.js";
+import { MCP_NO_LOCATION } from "../../setup/targets.js";
+import type { CheckItem, CheckResult, Scope } from "../types.js";
 import { checkShellCompletions } from "./checkShellCompletions.js";
+import {
+  harnessInventory,
+  type InventoryGroup,
+  type InventoryHarness,
+  inventoryHealth,
+} from "./harnessInventory.js";
 import { commandResolves } from "./mcpCommand.js";
 
-/** What a row reports before its name, band and `fix:` line are attached. */
+/** What a row reports before its name, scope and `fix:` line are attached. */
 interface Health {
   readonly status: CheckResult["status"];
   readonly detail: string;
@@ -64,7 +80,8 @@ const configHealth = (
   roots: { global: string; project: string },
 ): Health => {
   const path = shortenPath(d.path, roots);
-  if (!d.exists) return { status: "available", detail: `${path} not created` };
+  if (!d.exists)
+    return { status: "available", detail: `${path} does not exist yet` };
   if (!d.parses) {
     return { status: "fail", detail: `${path} cannot be parsed as JSON` };
   }
@@ -78,8 +95,8 @@ const lspHealth = (d: LspDetection): Health => {
   }
   const editors = lspEditorNames(d).join(", ");
   return d.state === "installed"
-    ? { status: "pass", detail: `installed (${editors})` }
-    : { status: "available", detail: `not installed (${editors})` };
+    ? { status: "pass", detail: `installed in ${editors}` }
+    : { status: "available", detail: `not installed in ${editors}` };
 };
 
 /**
@@ -90,22 +107,19 @@ const lspHealth = (d: LspDetection): Health => {
  */
 async function mcpHealth(
   d: McpDetection,
-  band: ScopeBand,
+  scope: Scope,
   cwd: string,
   roots: { global: string; project: string },
 ): Promise<Health> {
   if (d.groups.length === 0) {
-    return {
-      status: "skip",
-      detail: "no harness config location in this band",
-    };
+    return { status: "skip", detail: MCP_NO_LOCATION[scope] };
   }
   const resolves = await commandResolves(MCP_SERVER_NAME, cwd);
   const items: CheckItem[] = d.groups.map((group) => {
     const state = mcpGroupState(d, group.path);
     const label = shortenPath(group.path, roots);
     if (state === "absent") {
-      return { label, status: "available", detail: "not configured" };
+      return { label, status: "available", detail: "not registered" };
     }
     if (state === "drifted") {
       return { label, status: "fail", detail: "entry differs from current" };
@@ -114,8 +128,8 @@ async function mcpHealth(
       label,
       status: resolves ? "pass" : "fail",
       detail: resolves
-        ? `entry current, \`${MCP_SERVER_NAME}\` resolves`
-        : `entry current, \`${MCP_SERVER_NAME}\` is not on PATH`,
+        ? `registered, and \`${MCP_SERVER_NAME}\` is on PATH`
+        : `registered, but \`${MCP_SERVER_NAME}\` is not on PATH`,
     };
   });
   const configured = items.filter((item) => item.status === "pass").length;
@@ -123,24 +137,29 @@ async function mcpHealth(
   if (failing > 0) {
     return {
       status: "fail",
-      detail: `${failing} of ${items.length} need attention`,
+      detail: `${failing} of ${items.length} config files need attention`,
       items,
     };
   }
   if (configured === 0) {
-    // Project-band absence is not a failure: the band is opt-in, so a
-    // repository with no checked-in MCP config is a healthy repository.
-    return band === "project"
-      ? { status: "skip", detail: "not configured for this project (opt-in)" }
+    // Absence in the LOCAL PROJECT is not a failure: registering there is
+    // opt-in, so a repository with no checked-in MCP config is healthy. The
+    // line says so rather than leaving "(opt-in)" to be decoded.
+    return scope === "project"
+      ? {
+          status: "skip",
+          detail:
+            "not registered for this project — per-project registration is opt-in",
+        }
       : {
           status: "available",
-          detail: `${items.length} not configured`,
+          detail: `not registered in any of ${items.length} config files`,
           items,
         };
   }
   return {
     status: configured === items.length ? "pass" : "available",
-    detail: `${configured} of ${items.length} current`,
+    detail: `registered in ${configured} of ${items.length} config files`,
     items,
   };
 }
@@ -148,13 +167,27 @@ async function mcpHealth(
 /** The `skills` row: every expected link present, lstat-verified, none stale. */
 function skillsHealth(
   d: SkillsDetection,
-  band: ScopeBand,
+  scope: Scope,
   roots: { global: string; project: string },
 ): Health {
-  if (!d.available) {
+  const short = shortenPath(d.sourceRoot, roots);
+  // Stale links this scope owns are work even when the root holds no skill, so
+  // the row is only a skip once there is nothing left to reconcile either.
+  const orphans = d.rootExists ? d.orphans.length : 0;
+  if (!d.available && orphans === 0) {
+    // The skip carries a remedy — `setup`'s row and this row are the same
+    // finding, and the dead-end version of it ("no skills installed", no next
+    // step) was reported identically by both surfaces.
     return {
       status: "skip",
-      detail: skillsSkipReason(shortenPath(d.sourceRoot, roots), band),
+      detail: skillsSkipReason(short, scope, d.rootExists),
+      remedy: skillsSkipRemedy(short, scope),
+    };
+  }
+  if (orphans > 0) {
+    return {
+      status: "available",
+      detail: `${orphans} link${orphans === 1 ? "" : "s"} point at a skill that is gone`,
     };
   }
   const stale = d.actions.filter((a) => a.action === "replaced").length;
@@ -169,6 +202,22 @@ function skillsHealth(
   // and reporting the two the same way made this row say "links current" where
   // no link exists at all. Setup will never clear such a path — it is not this
   // command's to delete — so the row carries the only remedy that settles it.
+  // A symlink pointing outside every root pragma owns is `skipped` so setup
+  // will never delete it — which would make this row claim "links current" over
+  // a path where the user's own link shadows a shipped skill. `skipped` also
+  // covers an already-correct link (owned) and a real directory (blocked), so
+  // the foreign case is what is left.
+  const foreign = d.actions.filter(
+    (a) => a.action === "skipped" && !a.owned && !a.blocked,
+  ).length;
+  if (foreign > 0) {
+    return {
+      status: "available",
+      detail: `${foreign} of ${d.actions.length} link paths hold a symlink pragma does not own`,
+      remedy:
+        "Move or delete the symlink at that path, then link the skills again.",
+    };
+  }
   const blocked = d.actions.filter((a) => a.blocked).length;
   if (blocked > 0) {
     return {
@@ -198,7 +247,7 @@ async function healthOf(
   roots: { global: string; project: string },
 ): Promise<Health> {
   // A detection that threw is reported as ITS OWN failing row. Letting the
-  // rejection escape took the whole banded section of the report with it, so a
+  // rejection escape took the whole scoped section of the report with it, so a
   // single unreadable config file left the user with no rows at all — the one
   // moment the report is most worth having.
   const failure = detectionFailure(row);
@@ -220,55 +269,176 @@ async function healthOf(
     case "lsp":
       return lspHealth(row.detection as LspDetection);
     case "mcp":
-      return mcpHealth(row.detection as McpDetection, row.band, rt.cwd, roots);
+      return mcpHealth(row.detection as McpDetection, row.scope, rt.cwd, roots);
     default:
-      return skillsHealth(row.detection as SkillsDetection, row.band, roots);
+      return skillsHealth(row.detection as SkillsDetection, row.scope, roots);
   }
 }
 
+/** The scoped inventory row's name — a LISTING, not a setup target id. */
+export const INVENTORY_CHECK = "harnesses";
+
+/**
+ * The `harnesses` row for one scope: what this machine has, and where pragma
+ * stands in each.
+ *
+ * It is the one scoped row that is NOT a target, and it earns that by never
+ * competing with the ones that are. Its status is only `pass` or `skip`, so it
+ * adds no failure and no `available` to the tally, and it derives no `fix:` —
+ * the `mcp` and `skills` rows beside it already name every command a harness
+ * needs, and repeating them here would be the same finding seen twice.
+ *
+ * The registry is the only thing detection could not supply: `detectHarnesses`
+ * filters to hits, so "Windsurf is not on this machine" was unrepresentable
+ * until the universe came from somewhere. Everything else — which harnesses
+ * share which file, and whether each one's own entry in it is current — is read
+ * straight off the `mcp` detection this report already ran. The projection to
+ * {@link InventoryGroup} is deliberate: `McpDetection` holds
+ * `writeMcpConfigTargets`/`removeMcpConfigFrom` as live functions, and a
+ * `mutates: false` command should be unable to reach a writer, not merely
+ * trusted not to.
+ *
+ * This is also where the harness↔`mcpKey` association is REJOINED, because it
+ * is the one place that holds both halves: `TargetGroup` records the names
+ * sharing a file and, separately, one write per distinct `mcpKey`, and the
+ * registry is what says which key a given harness writes. Without that join the
+ * only state available per harness is the file's aggregate — and a
+ * `.vscode/mcp.json` where VS Code's `servers` entry is current while Cline's
+ * `mcpServers` is absent aggregates to `drifted`, which would report BOTH
+ * harnesses as drifted when neither one is.
+ *
+ * @param rt - The per-invocation runtime (read for `--verbose`).
+ * @param rows - Every detected row, both scopes, as `scopedChecks` has them.
+ * @param roots - The roots every path renders relative to.
+ * @returns One inventory {@link CheckResult} per scope, global then project.
+ * @note Impure — dynamically imports the harness registry.
+ */
+async function inventoryChecks(
+  rt: PragmaRuntime,
+  rows: readonly DetectedRow[],
+  roots: { global: string; project: string },
+): Promise<CheckResult[]> {
+  const { harnesses, isHarnessInBand } = await import("@canonical/harnesses");
+  const verbose = rt.globalFlags.verbose;
+  const scopes: readonly Scope[] = ["global", "project"];
+  // The key each harness NAME writes under — the half of the association
+  // `groupConfigTargets` consumed and did not record. Names are the only
+  // identity a group carries, and the registry's are unique.
+  const keyByName = new Map(harnesses.map((h) => [h.name, h.mcpKey]));
+
+  return scopes.map((scope): CheckResult => {
+    // `isHarnessInBand(harness.scope, scope, scope)` — the scope asked for as
+    // its OWN selection ("band" is the harnesses package's name for it) — is
+    // exactly "does this harness have a config location here", which is the
+    // question `detectMcp` already answers for that scope. Asking it under the
+    // `both` selection would instead answer "who writes here when both scopes
+    // run", and report every dual-scope harness as having no global location.
+    const registry: InventoryHarness[] = harnesses.map((harness) => ({
+      id: harness.id,
+      name: harness.name,
+      inScope: isHarnessInBand(harness.scope, scope, scope),
+    }));
+
+    const mcpRow = rows.find(
+      (row) => row.target.id === "mcp" && row.scope === scope,
+    );
+    if (mcpRow === undefined || detectionFailure(mcpRow) !== undefined) {
+      return {
+        name: INVENTORY_CHECK,
+        status: "skip",
+        detail: "harness detection did not settle — see the `mcp` row",
+        scope,
+      };
+    }
+
+    const detection = mcpRow.detection as McpDetection;
+    const groups: InventoryGroup[] = detection.groups.map((group) => ({
+      path: shortenPath(group.path, roots),
+      harnesses: group.harnessNames.map((name) => {
+        // The harness's OWN write in this file. A name the registry does not
+        // know (or a key no write carries — impossible while the group was
+        // built from the same registry) falls back to the file's aggregate:
+        // strictly no worse than the state before this join existed.
+        const write = group.writes.find(
+          (w) => w.mcpKey === keyByName.get(name),
+        );
+        return {
+          name,
+          state:
+            write === undefined
+              ? mcpGroupState(detection, group.path)
+              : mcpWriteState(detection, write),
+        };
+      }),
+    }));
+
+    const health = inventoryHealth(
+      harnessInventory(registry, groups, scope),
+      verbose,
+    );
+    return {
+      name: INVENTORY_CHECK,
+      status: health.status,
+      detail: health.detail,
+      scope,
+      ...(health.items.length === 0 ? {} : { items: health.items }),
+    };
+  });
+}
+
 /**
- * The command that repairs a row — derived from its id and band, never
+ * The command that repairs a row — derived from its id and scope, never
  * authored. This is the bijection made mechanical: a row exists because a
  * target exists, and its fix is that target's own invocation.
  */
-export const fixCommandFor = (
-  id: string,
-  band: ScopeBand,
-  bin: string,
-): string => `${bin} setup ${id}${band === "project" ? " --local" : ""}`;
+export const fixCommandFor = (id: string, scope: Scope, bin: string): string =>
+  `${bin} setup ${id}${scope === "project" ? " --local" : ""}`;
 
 /**
- * Run every banded check: the target table, both bands, in table order.
+ * Run every scoped check: the target table, both scopes, in table order, then
+ * each scope's harness inventory.
+ *
+ * The inventory rows come LAST within the array, and the renderer partitions by
+ * scope while preserving order, so each scope's section ends with the listing of
+ * what that scope actually holds — the targets first, then the machine they were
+ * measured against. They ride on the SAME detection pass: no target is probed a
+ * second time to produce them.
  *
  * @param rt - The per-invocation runtime.
  * @param bin - The binary name the `fix:` lines are derived from.
- * @returns One {@link CheckResult} per (target, band) the machine can hold.
+ * @returns One {@link CheckResult} per (target, scope), plus one per scope.
  * @note Impure — every target's detection reads the real filesystem.
  */
-export async function bandedChecks(
+export async function scopedChecks(
   rt: PragmaRuntime,
   bin: string,
 ): Promise<CheckResult[]> {
   const roots = await resolveRoots(rt);
   const detected = await detectTargets(rt, [...TARGET_IDS], "both");
-  return Promise.all(
-    detected.map(async (row): Promise<CheckResult> => {
-      const health = await healthOf(row, rt, roots);
-      const needsFix =
-        health.status === "fail" || health.status === "available";
-      return {
-        name: row.target.id,
-        status: health.status,
-        detail: health.detail,
-        band: row.band,
-        ...(health.items === undefined ? {} : { items: health.items }),
-        ...(needsFix
-          ? {
-              remedy:
-                health.remedy ?? fixCommandFor(row.target.id, row.band, bin),
-            }
-          : {}),
-      };
-    }),
-  );
+  const [targetRows, inventoryRows] = await Promise.all([
+    Promise.all(
+      detected.map(async (row): Promise<CheckResult> => {
+        const health = await healthOf(row, rt, roots);
+        const needsFix =
+          health.status === "fail" || health.status === "available";
+        // A `skip` gets no DERIVED fix — re-running the target's own setup command
+        // would reproduce the skip. But a skip that AUTHORED a remedy has found a
+        // real next step on this machine (fill the scope's skill root, say), and
+        // dropping it is what made the skip a dead end on both surfaces.
+        const remedy = needsFix
+          ? (health.remedy ?? fixCommandFor(row.target.id, row.scope, bin))
+          : health.remedy;
+        return {
+          name: row.target.id,
+          status: health.status,
+          detail: health.detail,
+          scope: row.scope,
+          ...(health.items === undefined ? {} : { items: health.items }),
+          ...(remedy === undefined ? {} : { remedy }),
+        };
+      }),
+    ),
+    inventoryChecks(rt, detected, roots),
+  ]);
+  return [...targetRows, ...inventoryRows];
 }

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

@@ -1,14 +1,16 @@
 /**
- * Render goldens for `pragma doctor` — the band-grouped report AND the plain-path
- * color gate (F1).
+ * Render goldens for `pragma doctor` — the scope-grouped report AND the
+ * plain-path color gate (F1).
  *
- * The banded Global/Project grouping (`partitionByBand` → sections) is pinned for
- * both the plain and llm formatters, locking the unified Global/Project
- * vocabulary (the report no longer says MACHINE/PROJECT). Separately, the plain
+ * The Global / Local project grouping (`partitionByScope` → sections) is pinned
+ * for both the plain and llm formatters, locking the vocabulary the flags
+ * already use — `--global` and `--local`. It is neither MACHINE/PROJECT (the
+ * first spelling) nor "band" (the second): "band" was this repository's word for
+ * the partition and nobody else's. Separately, the plain
  * formatter tints ONLY on a color-capable TTY: `supports-color` reports a
  * non-zero `chalk.level` off a TTY under `GITHUB_ACTIONS` / `FORCE_COLOR`, so the
  * `isTTY` gate (via the shared style seam) keeps ANSI out of
- * `doctor --format plain | tee`. `beforeEach` forces color OFF so the banded
+ * `doctor --format plain | tee`. `beforeEach` forces color OFF so the section
  * goldens stay deterministic; the color tests opt a level back in explicitly.
  */
 
@@ -17,28 +19,28 @@ import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
 import { doctorFormatters } from "./doctor.render.js";
 import type { DoctorData } from "./types.js";
 
-/** A fixture spanning all three groups: environment (no band), global, project. */
-const BANDED_DATA: DoctorData = {
+/** A fixture spanning all three groups: environment (no scope), global, project. */
+const SCOPED_DATA: DoctorData = {
   checks: [
     { name: "Node version", status: "pass", detail: "v20 detected" },
     {
       name: "Shell completions",
       status: "pass",
       detail: "zsh up to date and resolving",
-      band: "global",
+      scope: "global",
     },
     {
       name: "MCP configured",
       status: "available",
       detail: "not set up for Windsurf",
       remedy: "pragma setup mcp",
-      band: "global",
+      scope: "global",
     },
     {
       name: "Skills symlinked",
       status: "skip",
       detail: "no AI harnesses detected",
-      band: "project",
+      scope: "project",
     },
   ],
   passed: 2,
@@ -98,54 +100,59 @@ afterAll(() => {
   chalk.level = prevLevel;
 });
 
-describe("doctor render — banded plain report", () => {
-  it("groups checks under Global then Project headers (unified labels)", () => {
-    const out = doctorFormatters.plain(BANDED_DATA);
+describe("doctor render — scoped plain report", () => {
+  it("groups checks under Global then Local project headers", () => {
+    const out = doctorFormatters.plain(SCOPED_DATA);
     const lines = out.split("\n");
-    // The two banded section headers use the unified Global/Project vocabulary.
+    // The two section headers use the words the flags use.
     expect(lines).toContain("Global");
-    expect(lines).toContain("Project");
-    // The superseded MACHINE/PROJECT labels are gone.
+    expect(lines).toContain("Local project");
+    // The superseded MACHINE/PROJECT labels are gone — and so is "band", which
+    // no user-facing string in this report may say.
     expect(out).not.toContain("MACHINE");
     expect(out).not.toMatch(/^PROJECT$/m);
+    expect(out).not.toMatch(/\bbands?\b/);
   });
 
-  it("orders environment → Global → Project, banding each check correctly", () => {
-    const out = doctorFormatters.plain(BANDED_DATA);
-    // Environment check leads with no header; the two global-band checks sit
-    // under Global; the project-band check sits under Project.
+  it("orders environment → Global → Local project, placing each check correctly", () => {
+    const out = doctorFormatters.plain(SCOPED_DATA);
+    // Environment check leads with no header; the two global checks sit under
+    // Global; the per-project check sits under Local project.
     const at = (needle: string): number => out.indexOf(needle);
     expect(at("Node version")).toBeGreaterThanOrEqual(0);
     expect(at("Node version")).toBeLessThan(at("Global"));
     expect(at("Global")).toBeLessThan(at("Shell completions"));
-    expect(at("MCP configured")).toBeLessThan(at("Project"));
-    expect(at("Project")).toBeLessThan(at("Skills symlinked"));
-    // An available banded check keeps its inline setup command under its band.
+    expect(at("MCP configured")).toBeLessThan(at("Local project"));
+    expect(at("Local project")).toBeLessThan(at("Skills symlinked"));
+    // An available scoped check keeps its inline setup command under its scope.
     expect(out).toContain("fix: pragma setup mcp");
     // The tally closes the report.
     expect(out).toContain("2 passed");
   });
 });
 
-describe("doctor render — banded llm report", () => {
-  it("groups checks under ### Global then ### Project headers", () => {
-    const out = doctorFormatters.llm(BANDED_DATA);
+describe("doctor render — scoped llm report", () => {
+  it("groups checks under ### Global then ### Local project headers", () => {
+    const out = doctorFormatters.llm(SCOPED_DATA);
     expect(out).toContain("### Global");
-    expect(out).toContain("### Project");
+    expect(out).toContain("### Local project");
     expect(out).not.toContain("### Machine");
     const at = (needle: string): number => out.indexOf(needle);
-    // Environment leads (no section header), then the two banded sections.
+    // Environment leads (no section header), then the two scoped sections.
     expect(at("Node version")).toBeLessThan(at("### Global"));
     expect(at("### Global")).toBeLessThan(at("Shell completions"));
-    expect(at("Shell completions")).toBeLessThan(at("### Project"));
-    expect(at("### Project")).toBeLessThan(at("Skills symlinked"));
+    expect(at("Shell completions")).toBeLessThan(at("### Local project"));
+    expect(at("### Local project")).toBeLessThan(at("Skills symlinked"));
     expect(out).toContain("_2 passed, 0 failed, 1 available, 1 skipped_");
   });
 });
 
 describe("doctor render — json", () => {
   it("is the exact DoctorData round-trip", () => {
-    expect(JSON.parse(doctorFormatters.json(BANDED_DATA))).toEqual(BANDED_DATA);
+    expect(JSON.parse(doctorFormatters.json(SCOPED_DATA))).toEqual(SCOPED_DATA);
+    // The machine surface uses the scope vocabulary too — the retired word
+    // cannot survive as a JSON key.
+    expect(doctorFormatters.json(SCOPED_DATA)).not.toMatch(/\bbands?\b/);
   });
 });
 
@@ -179,3 +186,72 @@ describe("doctor render — color ON (attended TTY)", () => {
     });
   });
 });
+
+/**
+ * The harness inventory renders through the EXISTING check-with-items
+ * primitive — a listing needs no new machinery, only a check whose `items` are
+ * harnesses. This pins that it reads as an inventory in both formats: named
+ * harnesses under their scope, mixed per-item glyphs, and NO `fix:` line (the
+ * `mcp`/`skills` rows own every action a harness can need).
+ */
+const INVENTORY_DATA: DoctorData = {
+  checks: [
+    {
+      name: "harnesses",
+      status: "pass",
+      detail: "1 detected · 1 registered · 3 known",
+      scope: "global",
+      items: [
+        {
+          label: "Claude Code",
+          status: "pass",
+          detail: "registered — ~/.claude.json",
+        },
+        { label: "Cursor", status: "skip", detail: "not detected" },
+        {
+          label: "VS Code",
+          status: "skip",
+          detail: "keeps no global config",
+        },
+      ],
+    },
+  ],
+  passed: 1,
+  failed: 0,
+  available: 0,
+  skipped: 0,
+};
+
+describe("doctor render — the harness inventory", () => {
+  it("renders one aligned sub-item per harness, with no fix line", () => {
+    const out = doctorFormatters.plain(INVENTORY_DATA);
+    expect(out).toContain("Global");
+    expect(out).toContain("harnesses");
+    expect(out).toContain("1 detected · 1 registered · 3 known");
+    expect(out).toContain("· ✓ Claude Code  registered — ~/.claude.json");
+    expect(out).toContain("· ○ Cursor       not detected");
+    expect(out).toContain("· ○ VS Code      keeps no global config");
+    // A listing proposes nothing — and never renders a failure glyph.
+    expect(out).not.toContain("fix:");
+    expect(out).not.toContain("✗");
+  });
+
+  it("nests the harnesses under the check in the llm format", () => {
+    const out = doctorFormatters.llm(INVENTORY_DATA);
+    expect(out).toContain("### Global");
+    expect(out).toContain(
+      "- ✓ **harnesses**: 1 detected · 1 registered · 3 known",
+    );
+    expect(out).toContain("  - ✓ Claude Code: registered — ~/.claude.json");
+    expect(out).toContain("  - ○ VS Code: keeps no global config");
+    expect(out).not.toContain("_fix:_");
+  });
+
+  it("round-trips through json with every row intact", () => {
+    const parsed = JSON.parse(
+      doctorFormatters.json(INVENTORY_DATA),
+    ) as DoctorData;
+    expect(parsed).toEqual(INVENTORY_DATA);
+    expect(parsed.checks[0]?.items).toHaveLength(3);
+  });
+});