magus-cli 7.2.0 → 7.3.1

package/src/__tests__/upgrade-spawn.test.ts

@@ -0,0 +1,355 @@
+/**
+ * `magus upgrade`, end to end, with node:child_process replaced.
+ *
+ * The upgrade must install the npm PACKAGE (`package.json` `name`,
+ * `magus-cli`) at `latest`, with whichever package manager owns the active
+ * `magus` binary. The bare npm name is an unrelated package: installing it
+ * leaves magus where it was. The duplicate-install hint must name the real
+ * package too. The probes that look for the COMMAND (`which magus`,
+ * `bun pm -g bin`, `npm prefix -g`) stay as they are.
+ *
+ * SAFETY. This is the one test that could run a real global install, so three
+ * independent layers stand between it and one:
+ *   1. identity guard: before every call, the imported `spawn` and `execSync`
+ *      must BE the fakes, or the test throws without calling anything;
+ *   2. PATH is an empty temp directory for the duration of the call, so even a
+ *      real `spawn("bun", ...)` finds nothing (bun 1.4.0's child_process.spawn
+ *      honours a runtime PATH change; `Bun.which` does not, so it is not used);
+ *   3. the module mock is restored in afterAll, the way cli-router.test.ts
+ *      restores its own, so no later file in the same process inherits it.
+ * Every other process launcher on the module is replaced by a fake that
+ * records and throws.
+ *
+ * Written black-box from the API contract.
+ */
+
+import {
+	afterAll,
+	afterEach,
+	beforeAll,
+	beforeEach,
+	describe,
+	expect,
+	mock,
+	test,
+} from "bun:test";
+import * as childProcessNamespace from "node:child_process";
+import { EventEmitter } from "node:events";
+import {
+	mkdirSync,
+	mkdtempSync,
+	readFileSync,
+	realpathSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { stripVTControlCharacters } from "node:util";
+
+// Read at test time: the single source of truth the requirements name.
+const PKG = JSON.parse(
+	readFileSync(join(import.meta.dir, "..", "..", "package.json"), "utf8"),
+) as { name: string; version: string };
+
+const COMMAND = "magus";
+const PACKAGE = "magus-cli";
+const EXPECTED_ARGS = ["install", "-g", `${PACKAGE}@latest`];
+
+// Snapshot the real module BEFORE mocking. mock.module is process-global and
+// updates live namespaces, so the snapshot is what gets put back.
+const realChildProcess: Record<string, unknown> = { ...childProcessNamespace };
+const realDefault = (realChildProcess.default ?? {}) as Record<string, unknown>;
+
+// ---------------------------------------------------------------------------
+// Fakes
+// ---------------------------------------------------------------------------
+
+interface SpawnCall {
+	cmd: string;
+	args: string[];
+	options: Record<string, unknown>;
+}
+
+interface Scenario {
+	/** What `which magus` answers: the active binary. */
+	which: string;
+	/** What `bun pm -g bin` answers. */
+	bunBin: string;
+	/** What `npm prefix -g` answers. */
+	npmPrefix: string;
+	/** The exit code the fake child reports. */
+	exitCode: number;
+}
+
+let scenario: Scenario = { which: "", bunBin: "", npmPrefix: "", exitCode: 0 };
+let spawnCalls: SpawnCall[] = [];
+let execCalls: string[] = [];
+
+function fakeExecSync(command: string, options?: { encoding?: string }) {
+	const text = String(command);
+	execCalls.push(text);
+	let answer: string | undefined;
+	if (text.includes("which magus")) answer = scenario.which;
+	else if (text.includes("bun pm -g bin")) answer = scenario.bunBin;
+	else if (text.includes("npm prefix -g")) answer = scenario.npmPrefix;
+	if (!answer) {
+		throw new Error(`fake execSync has no answer for: ${text}`);
+	}
+	// Mirror Node: a string when an encoding is asked for, a Buffer otherwise.
+	const out = `${answer}\n`;
+	const encoding = options?.encoding;
+	return encoding && encoding !== "buffer" ? out : Buffer.from(out);
+}
+
+function fakeSpawn(
+	cmd: string,
+	args?: readonly string[],
+	options?: Record<string, unknown>,
+) {
+	spawnCalls.push({
+		cmd: String(cmd),
+		args: [...(args ?? [])],
+		options: options ?? {},
+	});
+	const child = Object.assign(new EventEmitter(), {
+		pid: 424242,
+		stdin: null,
+		stdout: null,
+		stderr: null,
+		kill: () => true,
+	});
+	const code = scenario.exitCode;
+	setTimeout(() => {
+		child.emit("exit", code, null);
+		child.emit("close", code, null);
+	}, 0);
+	return child;
+}
+
+function refuse(name: string) {
+	return (...a: unknown[]) => {
+		throw new Error(
+			`upgrade-spawn test refused child_process.${name}(${String(a[0])}): no real process may run here`,
+		);
+	};
+}
+
+const fakes = {
+	spawn: fakeSpawn,
+	execSync: fakeExecSync,
+	spawnSync: refuse("spawnSync"),
+	exec: refuse("exec"),
+	execFile: refuse("execFile"),
+	execFileSync: refuse("execFileSync"),
+	fork: refuse("fork"),
+};
+
+// ---------------------------------------------------------------------------
+// Lifecycle
+// ---------------------------------------------------------------------------
+
+let runUpgradeCommand: () => Promise<number>;
+
+beforeAll(async () => {
+	mock.module("node:child_process", () => ({
+		...realChildProcess,
+		...fakes,
+		default: { ...realDefault, ...fakes },
+	}));
+	// Imported only AFTER the mock, so the module binds to the fakes.
+	({ runUpgradeCommand } = await import("../cli/upgrade.js"));
+});
+
+afterAll(() => {
+	mock.module("node:child_process", () => realChildProcess);
+});
+
+/** Layer 1: refuse to proceed unless the fakes are what callers will get. */
+async function assertChildProcessIsFake(): Promise<void> {
+	const cp = (await import("node:child_process")) as unknown as Record<
+		string,
+		unknown
+	>;
+	if (cp.spawn !== fakeSpawn || cp.execSync !== fakeExecSync) {
+		throw new Error(
+			"SAFETY: node:child_process is not mocked. Refusing to call runUpgradeCommand, which would run a real global install.",
+		);
+	}
+}
+
+let root: string;
+let logs: string[];
+let otherOutput: string[];
+const realLog = console.log;
+const realError = console.error;
+const realWarn = console.warn;
+const realFetch = globalThis.fetch;
+
+beforeEach(() => {
+	// realpath: on macOS the temp dir sits behind a symlink.
+	root = realpathSync(mkdtempSync(join(tmpdir(), "magus-upgrade-spawn-")));
+	const bunBin = join(root, ".bun", "bin");
+	const npmPrefix = join(root, "npm");
+	mkdirSync(bunBin, { recursive: true });
+	mkdirSync(join(npmPrefix, "bin"), { recursive: true });
+	mkdirSync(join(root, "empty-path"));
+	// Two real installs of the command, one per manager (amendment M3).
+	writeFileSync(join(bunBin, COMMAND), "#!/bin/sh\nexit 0\n", { mode: 0o755 });
+	writeFileSync(join(npmPrefix, "bin", COMMAND), "#!/bin/sh\nexit 0\n", {
+		mode: 0o755,
+	});
+
+	scenario = { which: "", bunBin, npmPrefix, exitCode: 0 };
+	spawnCalls = [];
+	execCalls = [];
+	logs = [];
+	otherOutput = [];
+
+	console.log = (...a: unknown[]) => {
+		logs.push(a.map(String).join(" "));
+	};
+	console.error = (...a: unknown[]) => {
+		otherOutput.push(a.map(String).join(" "));
+	};
+	console.warn = (...a: unknown[]) => {
+		otherOutput.push(a.map(String).join(" "));
+	};
+	// No network, in case the upgrade consults the registry first.
+	globalThis.fetch = (async () =>
+		new Response(JSON.stringify({ version: "999.0.0" }), {
+			status: 200,
+			headers: { "content-type": "application/json" },
+		})) as unknown as typeof fetch;
+});
+
+afterEach(() => {
+	console.log = realLog;
+	console.error = realError;
+	console.warn = realWarn;
+	globalThis.fetch = realFetch;
+	rmSync(root, { recursive: true, force: true });
+});
+
+const bunWhich = () => join(scenario.bunBin, COMMAND);
+const npmWhich = () => join(scenario.npmPrefix, "bin", COMMAND);
+
+async function runUpgrade(which: string, exitCode = 0): Promise<number> {
+	scenario.which = which;
+	scenario.exitCode = exitCode;
+	await assertChildProcessIsFake();
+	// Layer 2: nothing is reachable by name while the upgrade runs (M2).
+	const savedPath = process.env.PATH;
+	process.env.PATH = join(root, "empty-path");
+	try {
+		return await runUpgradeCommand();
+	} finally {
+		if (savedPath === undefined) Reflect.deleteProperty(process.env, "PATH");
+		else process.env.PATH = savedPath;
+	}
+}
+
+/** Captured console.log output, one entry per physical line, ANSI removed. */
+function logLines(): string[] {
+	return logs.flatMap((l) => stripVTControlCharacters(l).split("\n"));
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("runUpgradeCommand installs the npm package with the owning manager", () => {
+	test("a bun-owned binary upgrades with `bun install -g <package>@latest`", async () => {
+		const code = await runUpgrade(bunWhich());
+
+		expect(code).toBe(0);
+		expect(spawnCalls).toHaveLength(1);
+		const call = spawnCalls[0]!;
+		expect(call.cmd).toBe("bun");
+		expect(call.args).toEqual(EXPECTED_ARGS);
+		expect(call.args).toEqual(["install", "-g", `${PKG.name}@latest`]);
+		expect(call.options).toMatchObject({ stdio: "inherit", shell: false });
+	});
+
+	test("an npm-owned binary upgrades with `npm install -g <package>@latest`", async () => {
+		// Precondition: nothing in this path may look bun-owned.
+		expect(npmWhich()).not.toContain(".bun");
+		expect(npmWhich()).not.toContain("bun/bin");
+
+		const code = await runUpgrade(npmWhich());
+
+		expect(code).toBe(0);
+		expect(spawnCalls).toHaveLength(1);
+		const call = spawnCalls[0]!;
+		expect(call.cmd).toBe("npm");
+		expect(call.args).toEqual(EXPECTED_ARGS);
+		expect(call.args).toEqual(["install", "-g", `${PKG.name}@latest`]);
+		expect(call.options).toMatchObject({ stdio: "inherit", shell: false });
+	});
+
+	test("a `bun/bin` path without `.bun` also counts as bun-owned", async () => {
+		const dir = join(root, "opt", "bun", "bin");
+		mkdirSync(dir, { recursive: true });
+		const which = join(dir, COMMAND);
+		writeFileSync(which, "#!/bin/sh\nexit 0\n", { mode: 0o755 });
+		expect(which).not.toContain(".bun");
+
+		await runUpgrade(which);
+
+		expect(spawnCalls).toHaveLength(1);
+		expect(spawnCalls[0]!.cmd).toBe("bun");
+		expect(spawnCalls[0]!.args).toEqual(EXPECTED_ARGS);
+	});
+
+	test("resolves with the child's exit code", async () => {
+		const code = await runUpgrade(npmWhich(), 3);
+
+		expect(spawnCalls).toHaveLength(1);
+		expect(code).toBe(3);
+	});
+});
+
+describe("the duplicate-install hint names the npm package", () => {
+	function expectBothHints() {
+		const out = logLines().join("\n");
+		expect(out).toContain(`bun uninstall -g ${PACKAGE}`);
+		expect(out).toContain(`npm uninstall -g ${PACKAGE}`);
+		// Every uninstall hint that was printed targets the package.
+		const hints = logLines().filter((l) => /\buninstall\b/.test(l));
+		expect(hints.length).toBeGreaterThanOrEqual(2);
+		for (const line of hints) {
+			const tokens = line.trim().split(/\s+/);
+			const i = tokens.indexOf("-g");
+			expect(i).toBeGreaterThanOrEqual(0);
+			expect(tokens[i + 1]).toBe(PKG.name);
+		}
+	}
+
+	test("both installs present, bun active: both hints name the package", async () => {
+		await runUpgrade(bunWhich());
+
+		expectBothHints();
+	});
+
+	test("both installs present, npm active: both hints name the package", async () => {
+		await runUpgrade(npmWhich());
+
+		expectBothHints();
+	});
+});
+
+describe("the probes still look for the command (R6)", () => {
+	test("`which magus`, `bun pm -g bin` and `npm prefix -g` are what gets asked", async () => {
+		await runUpgrade(bunWhich());
+
+		const probes = execCalls.join("\n");
+		expect(probes).toContain("bun pm -g bin");
+		expect(probes).toContain("npm prefix -g");
+		// `which` is asked about the COMMAND, not the package.
+		const whichProbe = execCalls
+			.map((c) => c.trim().split(/\s+/))
+			.find((tokens) => tokens.includes("which"));
+		expect(whichProbe).toBeDefined();
+		expect(whichProbe![whichProbe!.indexOf("which") + 1]).toBe(COMMAND);
+	});
+});

package/src/__tests__/useStaleLoadModal.test.ts

@@ -0,0 +1,177 @@
+import { describe, expect, it } from "bun:test";
+import {
+	buildStaleLoadModal,
+	staleLoadRepairSummary,
+} from "../ui/hooks/useStaleLoadModal";
+
+/**
+ * The startup popup for a broken plugin.
+ *
+ * Same shape as buildGitignoreModal beside it, with one difference that is the
+ * whole point of the popup: FIXING is the default. A plugin the loader resolves
+ * at the wrong version means every session in this directory runs code nobody
+ * installed, so Enter must repair it rather than dismiss.
+ */
+describe("buildStaleLoadModal", () => {
+	const args = (
+		over: Partial<Parameters<typeof buildStaleLoadModal>[0]> = {},
+	) => ({
+		brokenCount: 2,
+		onFix: () => {},
+		onOpenTab: () => {},
+		onDismiss: () => {},
+		...over,
+	});
+
+	it("offers fix, review and dismiss, with FIX first", () => {
+		const modal = buildStaleLoadModal(args());
+		if (modal.type !== "select") throw new Error("type guard");
+
+		expect(modal.options.map((o) => o.value)).toEqual([
+			"fix",
+			"open-tab",
+			"dismiss",
+		]);
+	});
+
+	it("defaults to FIX explicitly, not by accident of ordering", () => {
+		// Stated in the data so a future reordering cannot quietly make "leave it
+		// broken" the thing Enter does.
+		const modal = buildStaleLoadModal(args());
+		if (modal.type !== "select") throw new Error("type guard");
+
+		expect(modal.defaultIndex).toBe(0);
+		expect(modal.options[modal.defaultIndex ?? -1]?.value).toBe("fix");
+	});
+
+	it("blames the Claude Code bug, not magus's own state", () => {
+		// The title is the whole message for anyone who reads one line. It has to
+		// say what is wrong — a defect in Claude Code's loader — rather than
+		// report that two of magus's stores disagree, which is not actionable and
+		// reads as though the user misconfigured something.
+		const modal = buildStaleLoadModal(args({ brokenCount: 3 }));
+		if (modal.type !== "select") throw new Error("type guard");
+
+		expect(modal.title).toContain("Claude Code");
+		expect(modal.message).toContain("stale cached version");
+		expect(modal.options[0].label).toBe("Fix it (3 plugins)");
+		expect(modal.message).toContain("3 plugins are on an older version");
+	});
+
+	it("says the reach is every worktree, not just this directory", () => {
+		// Relevance is decided by repository root, so every worktree and the main
+		// checkout resolve identically and break together. A reader told only
+		// about "this directory" would fix one worktree and expect the others to
+		// differ — they cannot.
+		const modal = buildStaleLoadModal(args({ brokenCount: 3 }));
+		if (modal.type !== "select") throw new Error("type guard");
+
+		expect(modal.message).toContain("every worktree");
+		expect(modal.message).toContain("main checkout");
+	});
+
+	it("states the effect plainly, without overstating it", () => {
+		// A draft claimed "your sessions run code you did not install". Nothing
+		// happens to the user's code; an old cached plugin version is used. The
+		// overstatement is pinned here so it cannot come back on the next edit.
+		const modal = buildStaleLoadModal(args({ brokenCount: 3 }));
+		if (modal.type !== "select") throw new Error("type guard");
+
+		expect(modal.message).not.toContain("run code");
+		expect(modal.message).not.toContain("did not install");
+	});
+
+	it("reads correctly for a single plugin", () => {
+		const modal = buildStaleLoadModal(args({ brokenCount: 1 }));
+		if (modal.type !== "select") throw new Error("type guard");
+
+		expect(modal.options[0].label).toBe("Fix it (1 plugin)");
+		expect(modal.message).toContain("1 plugin is on an older version");
+	});
+
+	it("promises the backup and promises not to delete or downgrade", () => {
+		// The popup is asking permission to edit Claude Code-owned state. What it
+		// will and will not do has to be on the screen, not only in a code comment.
+		const modal = buildStaleLoadModal(args());
+		if (modal.type !== "select") throw new Error("type guard");
+
+		expect(modal.message).toContain(
+			"installed_plugins.json is backed up first",
+		);
+		// Case-insensitive: the promise has to be on screen, but whether it opens a
+		// sentence or trails one is a wording choice, and pinning the capital made
+		// an ordinary copy edit fail for nothing.
+		expect(modal.message.toLowerCase()).toContain(
+			"nothing is deleted or downgraded",
+		);
+	});
+
+	it("routes each choice to its callback, and cancel to dismiss", () => {
+		let fixed = 0;
+		let opened = 0;
+		let dismissed = 0;
+		const modal = buildStaleLoadModal(
+			args({
+				onFix: () => {
+					fixed++;
+				},
+				onOpenTab: () => {
+					opened++;
+				},
+				onDismiss: () => {
+					dismissed++;
+				},
+			}),
+		);
+		if (modal.type !== "select") throw new Error("type guard");
+
+		modal.onSelect("fix");
+		modal.onSelect("open-tab");
+		modal.onSelect("dismiss");
+		modal.onCancel();
+
+		expect({ fixed, opened, dismissed }).toEqual({
+			fixed: 1,
+			opened: 1,
+			dismissed: 2,
+		});
+	});
+});
+
+describe("staleLoadRepairSummary", () => {
+	it("says what loads NOW for each repaired plugin", () => {
+		expect(
+			staleLoadRepairSummary([
+				{ pluginId: "madbench@magus", target: "0.5.0", ok: true },
+				{ pluginId: "dev@magus", target: "7.4.0", ok: true },
+			]),
+		).toBe("✓ madbench@magus now loads v0.5.0\n✓ dev@magus now loads v7.4.0");
+	});
+
+	it("reports a failed repair with its own reason, never as a success", () => {
+		expect(
+			staleLoadRepairSummary([
+				{
+					pluginId: "madbench@magus",
+					target: "0.5.0",
+					ok: false,
+					error: "the loader still resolves v0.3.0 here, not v0.5.0",
+				},
+			]),
+		).toBe(
+			"✗ madbench@magus — the loader still resolves v0.3.0 here, not v0.5.0",
+		);
+	});
+
+	it("falls back to a plain reason rather than an empty line", () => {
+		expect(
+			staleLoadRepairSummary([
+				{ pluginId: "a@magus", target: "1.0.0", ok: false },
+			]),
+		).toBe("✗ a@magus — repair did not take effect");
+	});
+
+	it("says so when there was nothing to repair", () => {
+		expect(staleLoadRepairSummary([])).toBe("Nothing to repair.");
+	});
+});

package/src/cli/doctor.ts

@@ -7,10 +7,16 @@
  *   2. Profile symlink integrity — the active profile's links resolve.
  *   3. Convention compliance — .gitignore + CLAUDE.md blocks (ported engine).
  *   4. Model routing — config validity, hook registration, and drift.
+ *   5. Plugin loads — what Claude Code will load here vs what is installed.
  */
 
 import path from "node:path";
 import fs from "fs-extra";
+import {
+	getProjectInstalledPluginVersions,
+	readInstalledPluginsRegistry,
+	readSettings,
+} from "../services/claude-settings.js";
 import { checkBinaries, missingBinaries } from "../services/doctor-bins.js";
 import { checkProject, fixDoctorIssues } from "../services/doctor.js";
 import {
@@ -22,6 +28,11 @@ import {
 	readModelsConfig,
 	readModelsStatus,
 } from "../services/models-manager.js";
+import { isBehind } from "../services/plugin-manager.js";
+import {
+	type RepoRootCache,
+	pickLoadedEntry,
+} from "../services/plugin-resolution.js";
 import { resolveAllProfiles } from "../services/resolver.js";
 import { activeProfile, profileDir } from "../services/symlink-manager.js";
 import { resolveExecutable } from "../utils/command-utils.js";
@@ -111,8 +122,123 @@ export async function runDoctorCommand(args: string[]): Promise<number> {
 	// 4. Model routing.
 	problems += await checkModels(projectPath, fix);
 
-	if (problems === 0) console.log("\n✓ No problems found.");
-	return problems > 0 && !fix ? 1 : 0;
+	// 5. Stale plugin loads. Counted SEPARATELY, because `--fix` does not repair
+	// them — see doctorExitCode.
+	const staleLoads = await checkPluginLoads(projectPath);
+
+	if (problems === 0 && staleLoads === 0) console.log("\n✓ No problems found.");
+	return doctorExitCode({ fixable: problems, unfixable: staleLoads, fix });
+}
+
+/**
+ * Doctor's exit code.
+ *
+ * `--fix` suppresses the exit code for what it repaired — that is the point of
+ * the flag, and a caller that asked for repairs does not want a red exit over
+ * problems that are now gone. It must NOT suppress a class it never touches.
+ *
+ * Stale plugin loads are exactly that class: `checkPluginLoads` prints them and
+ * says so, and the repair lives in `repairStaleLoad`, reached by `magus update`
+ * and the Plugins screen. Folding them into the same counter meant `magus doctor
+ * --fix` printed red lines and exited 0 — so a CI or pre-flight step went green
+ * over a plugin whose sessions run a version nobody installed, which is the same
+ * deception the stale-load work exists to end.
+ *
+ * Pure and exported so the decision is pinned by a test rather than inferred from
+ * a command that needs a real `~/.claude` to run.
+ */
+export function doctorExitCode(args: {
+	/** Problems `--fix` can act on. */
+	fixable: number;
+	/** Problems it cannot — reported either way, and never silenced by `--fix`. */
+	unfixable: number;
+	fix: boolean;
+}): number {
+	if (args.unfixable > 0) return 1;
+	return args.fixable > 0 && !args.fix ? 1 : 0;
+}
+
+/**
+ * Plugins whose installed version is NOT the version that will load here.
+ *
+ * Reported, never repaired — `--fix` deliberately does nothing about it, and
+ * that is a division of labour rather than a dead end. A reinstall does not
+ * clear this (measured): it writes another `installed_plugins.json` row for THIS
+ * project, while the row the loader picks belongs to a different one — usually a
+ * worktree that has since been deleted, whose entry nothing prunes. Moving those
+ * rows forward is what fixes it, and that lives in `repairStaleLoad`, reached by
+ * `magus update` and by the Plugins screen's `a` key. Doctor's job is to name
+ * the winner, which is the one thing neither of those prints.
+ *
+ * Both halves come from the registry rather than the catalog, so this section
+ * makes no network call and holds even when GitHub is unreachable:
+ *   installed — magus's own resolution, `pickRegistryEntry` via settings overlay
+ *   loads     — the loader's, `pickLoadedEntry`
+ */
+async function checkPluginLoads(projectPath: string): Promise<number> {
+	const registry = await readInstalledPluginsRegistry();
+	const settings = await readSettings(projectPath);
+	const installed = await getProjectInstalledPluginVersions(
+		settings.installedPluginVersions || {},
+		projectPath,
+	);
+	const ids = Object.keys(installed);
+	if (ids.length === 0) return 0;
+
+	// One cache across every plugin: the same handful of project paths repeat in
+	// hundreds of rows, and each miss walks the tree to the filesystem root.
+	const cache: RepoRootCache = new Map();
+	const stale: Array<{
+		pluginId: string;
+		loaded: string;
+		recorded: string;
+		winner: string;
+	}> = [];
+
+	for (const pluginId of ids.sort()) {
+		const recorded = installed[pluginId];
+		if (!recorded) continue;
+		const pick = pickLoadedEntry(
+			registry.plugins?.[pluginId],
+			projectPath,
+			cache,
+		);
+		if (!pick?.version) continue;
+		// The same predicate the classifier uses, so doctor and the plugin screen
+		// cannot disagree about which pairs count. Unorderable pairs answer null
+		// and are left alone — "cannot tell" is not a finding.
+		if (isBehind(recorded, pick.version) !== true) continue;
+		stale.push({
+			pluginId,
+			loaded: pick.version,
+			recorded,
+			winner:
+				pick.projectPath ??
+				(pick.scope === "user" ? "user scope (no project)" : "unknown project"),
+		});
+	}
+
+	console.log("\nPlugin loads:");
+	if (stale.length === 0) {
+		console.log(
+			`  ✓ All ${ids.length} installed plugins load at their installed version.`,
+		);
+		return 0;
+	}
+
+	for (const row of stale) {
+		console.log(
+			`  ✗ ${row.pluginId} — loads v${row.loaded}, installed v${row.recorded}`,
+		);
+		console.log(`      the entry that wins belongs to ${row.winner}`);
+	}
+	console.log(
+		"    Reinstalling does not fix this. Run `magus update` — it moves those",
+	);
+	console.log(
+		"    install records forward, backing up installed_plugins.json first.",
+	);
+	return stale.length;
 }
 
 /**