magus-cli 7.2.0 → 7.3.1

package/src/__tests__/stale-load-repair.test.ts

@@ -0,0 +1,1076 @@
+import {
+	afterAll,
+	beforeAll,
+	beforeEach,
+	describe,
+	expect,
+	spyOn,
+	test,
+} from "bun:test";
+import { execFileSync } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+import fs from "fs-extra";
+import {
+	findStaleLoads,
+	repairAllStaleLoads,
+	repairStaleLoad,
+	writeInstalledPluginsRegistry,
+} from "../services/claude-settings.js";
+import type { PluginInfo } from "../services/plugin-manager.js";
+import {
+	isRelevantInstallation,
+	pickLoadedEntry,
+	repoRootForPath,
+	resolveLoadedVersions,
+} from "../services/plugin-resolution.js";
+import {
+	classifyPluginRows,
+	countPluginStates,
+} from "../services/update-plan.js";
+import type {
+	InstalledPluginEntry,
+	InstalledPluginsRegistry,
+} from "../types/index.js";
+
+/**
+ * `repairStaleLoad` — the one place magus writes `installed_plugins.json`
+ * deliberately.
+ *
+ * Exercised against REAL git repositories, for the same reason
+ * plugin-resolution.test.ts is: the whole difficulty is that rows belonging to
+ * other worktrees of the same repository — including deleted ones — take part in
+ * the loader's selection, and a hand-written `.git` file would only confirm
+ * whatever parse it was written from.
+ *
+ * Every case passes an explicit plugins ROOT under a temp directory. Nothing
+ * here may touch the operator's real `~/.claude` — this function rewrites the
+ * record of what every project on the machine has installed.
+ */
+
+// Isolate from the operator's git config, exactly as plugin-resolution.test.ts does.
+const GIT_CFG = [
+	"-c",
+	"user.name=test",
+	"-c",
+	"user.email=test@example.com",
+	"-c",
+	"commit.gpgsign=false",
+	"-c",
+	"init.defaultBranch=main",
+];
+const git = (cwd: string, ...args: string[]) =>
+	execFileSync("git", [...GIT_CFG, ...args], { cwd, encoding: "utf8" }).trim();
+
+const PLUGIN = "madbench@magus";
+
+let base: string;
+/** The repository under test, standing in for magus-src. */
+let mainTree: string;
+/** A live linked worktree of it — the directory every case runs "in". */
+let here: string;
+/** A worktree that was created, registered, then REMOVED. */
+let gone: string;
+/** The plugins root: registry file + cache, as `~/.claude/plugins`. */
+let root: string;
+let registryFile: string;
+
+const cacheFor = (version: string) =>
+	path.join(root, "cache", "magus", "madbench", version);
+
+const row = (
+	over: Partial<InstalledPluginEntry> & { version: string },
+): InstalledPluginEntry => ({
+	scope: "project",
+	installPath: cacheFor(over.version),
+	installedAt: "2026-01-01T00:00:00.000Z",
+	lastUpdated: "2026-01-01T00:00:00.000Z",
+	...over,
+});
+
+async function writeRegistry(rows: InstalledPluginEntry[]): Promise<void> {
+	const registry: InstalledPluginsRegistry = {
+		version: 2,
+		plugins: { [PLUGIN]: rows },
+	};
+	await fs.outputJson(registryFile, registry, { spaces: 2 });
+}
+
+const readRegistry = (): Promise<InstalledPluginsRegistry> =>
+	fs.readJson(registryFile);
+
+/** Every backup this suite's writes produced, newest last. */
+async function backups(): Promise<string[]> {
+	const names = await fs.readdir(path.dirname(registryFile));
+	return names
+		.filter((n) => n.startsWith("installed_plugins.json.backup."))
+		.sort();
+}
+
+beforeAll(async () => {
+	// realpath: on macOS os.tmpdir() is a symlink, and git reports real paths.
+	base = await fs.realpath(
+		await fs.mkdtemp(path.join(os.tmpdir(), "magus-repair-")),
+	);
+	mainTree = path.join(base, "magus-src");
+	here = path.join(mainTree, ".claude", "worktrees", "madbench");
+	gone = path.join(mainTree, ".claude", "worktrees", "gone");
+
+	await fs.ensureDir(mainTree);
+	git(mainTree, "init", "-q");
+	await fs.writeFile(path.join(mainTree, "README.md"), "hello\n");
+	git(mainTree, "add", "-A");
+	git(mainTree, "commit", "-qm", "initial");
+	git(mainTree, "worktree", "add", "-q", "-b", "madbench", here);
+
+	// Created, registered, then removed — its registry rows are what survive it,
+	// and on the reporting machine those were the rows that won.
+	git(mainTree, "worktree", "add", "-q", "-b", "gone", gone);
+	await fs.remove(gone);
+});
+
+afterAll(async () => {
+	if (base) await fs.remove(base);
+});
+
+beforeEach(async () => {
+	// A fresh plugins root per case, so a backup from one case cannot be counted
+	// by the next.
+	root = await fs.mkdtemp(path.join(base, "plugins-"));
+	registryFile = path.join(root, "installed_plugins.json");
+	for (const v of ["0.3.0", "0.4.0", "0.5.0", "0.9.0"]) {
+		await fs.ensureDir(cacheFor(v));
+	}
+});
+
+describe("repairStaleLoad — rows move FORWARD and none are removed", () => {
+	test("the deleted worktree's winning row is rewritten to the target", async () => {
+		// The measured defect: 0.3.0 registered against a worktree that no longer
+		// exists, written first, so it wins over this project's own 0.5.0.
+		await writeRegistry([
+			row({ version: "0.3.0", projectPath: gone }),
+			row({ version: "0.5.0", projectPath: here }),
+		]);
+		expect(
+			pickLoadedEntry((await readRegistry()).plugins[PLUGIN], here)?.version,
+		).toBe("0.3.0");
+
+		const result = await repairStaleLoad(PLUGIN, "0.5.0", here, root);
+
+		expect(result.ok).toBe(true);
+		expect(result.rewritten).toBe(1);
+		expect(result.loaded).toBe("0.5.0");
+
+		const after = (await readRegistry()).plugins[PLUGIN];
+		// NOTHING REMOVED — both rows survive, in their original order.
+		expect(after.length).toBe(2);
+		expect(after.map((e) => e.projectPath)).toEqual([gone, here]);
+		expect(after.map((e) => e.version)).toEqual(["0.5.0", "0.5.0"]);
+		expect(after[0].installPath).toBe(cacheFor("0.5.0"));
+	});
+
+	test("every relevant row behind the target moves, not just the winner", async () => {
+		await writeRegistry([
+			row({ version: "0.3.0", projectPath: gone }),
+			row({ version: "0.4.0", projectPath: mainTree }),
+			row({ version: "0.5.0", projectPath: here }),
+		]);
+
+		const result = await repairStaleLoad(PLUGIN, "0.5.0", here, root);
+
+		expect(result.ok).toBe(true);
+		expect(result.rewritten).toBe(2);
+		expect(
+			(await readRegistry()).plugins[PLUGIN].map((e) => e.version),
+		).toEqual(["0.5.0", "0.5.0", "0.5.0"]);
+	});
+
+	test("a row AHEAD of the target is left exactly as it was", async () => {
+		// Move forward only. A row at 0.9.0 is not something to "correct" down to
+		// the target, and rewriting it would be a downgrade this function promises
+		// never to perform.
+		await writeRegistry([
+			row({ version: "0.3.0", projectPath: gone }),
+			row({ version: "0.9.0", projectPath: mainTree }),
+			row({ version: "0.5.0", projectPath: here }),
+		]);
+
+		await repairStaleLoad(PLUGIN, "0.5.0", here, root);
+
+		const after = (await readRegistry()).plugins[PLUGIN];
+		expect(after[1].version).toBe("0.9.0");
+		expect(after[1].installPath).toBe(cacheFor("0.9.0"));
+	});
+
+	test("a row from an UNRELATED repository is never touched", async () => {
+		const other = path.join(base, "unrelated");
+		await fs.ensureDir(other);
+		git(other, "init", "-q");
+
+		await writeRegistry([
+			row({ version: "0.3.0", projectPath: other }),
+			row({ version: "0.5.0", projectPath: here }),
+		]);
+
+		const result = await repairStaleLoad(PLUGIN, "0.5.0", here, root);
+
+		expect(result.rewritten).toBe(0);
+		expect((await readRegistry()).plugins[PLUGIN][0].version).toBe("0.3.0");
+	});
+
+	test("the recorded commit is dropped on a rewritten row", async () => {
+		// It describes the version we just moved AWAY from; keeping it would have
+		// content-drift compare two different releases and report the repaired
+		// plugin as needing a reinstall.
+		await writeRegistry([
+			row({
+				version: "0.3.0",
+				projectPath: gone,
+				gitCommitSha: "a".repeat(40),
+			}),
+			row({ version: "0.5.0", projectPath: here }),
+		]);
+
+		await repairStaleLoad(PLUGIN, "0.5.0", here, root);
+
+		expect(
+			(await readRegistry()).plugins[PLUGIN][0].gitCommitSha,
+		).toBeUndefined();
+	});
+});
+
+describe("repairStaleLoad — the backup", () => {
+	test("a timestamped backup sits beside the registry after a write", async () => {
+		await writeRegistry([
+			row({ version: "0.3.0", projectPath: gone }),
+			row({ version: "0.5.0", projectPath: here }),
+		]);
+
+		const result = await repairStaleLoad(PLUGIN, "0.5.0", here, root);
+
+		expect(result.backup).not.toBeNull();
+		expect(await backups()).toEqual([path.basename(result.backup as string)]);
+		expect(path.dirname(result.backup as string)).toBe(root);
+	});
+
+	test("the backup holds the PRE-repair rows, so the edit can be undone", async () => {
+		await writeRegistry([
+			row({ version: "0.3.0", projectPath: gone }),
+			row({ version: "0.5.0", projectPath: here }),
+		]);
+
+		const result = await repairStaleLoad(PLUGIN, "0.5.0", here, root);
+		const saved: InstalledPluginsRegistry = await fs.readJson(
+			result.backup as string,
+		);
+
+		expect(saved.plugins[PLUGIN].map((e) => e.version)).toEqual([
+			"0.3.0",
+			"0.5.0",
+		]);
+	});
+
+	test("no rows to move means no write and no backup", async () => {
+		await writeRegistry([row({ version: "0.5.0", projectPath: here })]);
+
+		const result = await repairStaleLoad(PLUGIN, "0.5.0", here, root);
+
+		expect(result.ok).toBe(true);
+		expect(result.rewritten).toBe(0);
+		expect(result.backup).toBeNull();
+		expect(await backups()).toEqual([]);
+	});
+
+	test("an unbackupable registry is NOT written", async () => {
+		// The backup is the only undo for an edit to the record of every project's
+		// installs, so a repair that cannot take one must not proceed. Simulated by
+		// making the directory read-only: `fs.copy` cannot create the backup file,
+		// while the registry itself is still perfectly readable.
+		await writeRegistry([
+			row({ version: "0.3.0", projectPath: gone }),
+			row({ version: "0.5.0", projectPath: here }),
+		]);
+		const before = await fs.readFile(registryFile, "utf8");
+		await fs.chmod(root, 0o500);
+
+		try {
+			const result = await repairStaleLoad(PLUGIN, "0.5.0", here, root);
+
+			expect(result.ok).toBe(false);
+			expect(result.error).toContain("could not back up");
+			expect(result.rewritten).toBe(0);
+			expect(result.backup).toBeNull();
+			expect(await fs.readFile(registryFile, "utf8")).toBe(before);
+		} finally {
+			await fs.chmod(root, 0o700);
+		}
+	});
+});
+
+describe("repairStaleLoad — refusals", () => {
+	test("a target with no cache directory is refused before any write", async () => {
+		// Writing that row would leave the registry naming a directory that is not
+		// there: the loader would resolve it and load nothing at all, which is worse
+		// than the stale load it replaced.
+		await writeRegistry([
+			row({ version: "0.3.0", projectPath: gone }),
+			row({ version: "0.7.0", projectPath: here }),
+		]);
+		expect(await fs.pathExists(cacheFor("0.7.0"))).toBe(false);
+		const before = await fs.readFile(registryFile, "utf8");
+
+		const result = await repairStaleLoad(PLUGIN, "0.7.0", here, root);
+
+		expect(result.ok).toBe(false);
+		expect(result.error).toContain("no cache directory for v0.7.0");
+		expect(result.backup).toBeNull();
+		expect(await fs.readFile(registryFile, "utf8")).toBe(before);
+		expect(await backups()).toEqual([]);
+	});
+
+	test("a plugin with no registry rows is refused", async () => {
+		await fs.outputJson(registryFile, { version: 2, plugins: {} });
+
+		const result = await repairStaleLoad(PLUGIN, "0.5.0", here, root);
+
+		expect(result.ok).toBe(false);
+		expect(result.error).toContain("has no rows");
+	});
+
+	test("a string that is not a plugin id is refused", async () => {
+		const result = await repairStaleLoad("madbench", "0.5.0", here, root);
+		expect(result.ok).toBe(false);
+		expect(result.error).toContain("not a plugin id");
+	});
+
+	test("an unreadable registry is refused rather than replaced", async () => {
+		// `readInstalledPluginsRegistry` answers an EMPTY registry for a corrupt
+		// file, and writing that back would erase every project's installs on the
+		// machine. The repair reads and parses the same bytes it will check before
+		// writing, so a document it cannot parse stops it here.
+		await fs.outputFile(registryFile, "{ not json");
+
+		const result = await repairStaleLoad(PLUGIN, "0.5.0", here, root);
+
+		expect(result.ok).toBe(false);
+		expect(result.error).toContain("not a readable registry");
+		expect(await fs.readFile(registryFile, "utf8")).toBe("{ not json");
+	});
+});
+
+/**
+ * HOW FAR A REPAIR MAY REACH: this repository's own records, and nothing else.
+ *
+ * The loader's relevance filter counts `user` and `managed` rows for every
+ * project on the machine, and the repair used to rewrite through that same
+ * filter — so a fix offered as "this repo's install records" moved a machine-wide
+ * record, installed from an unrelated directory, forward on its own. The dialog
+ * is what the user consents on, so the repair is what had to change.
+ */
+describe("repairStaleLoad — scope reach", () => {
+	/** A machine-wide row: no projectPath, relevant to every directory. */
+	const machineWide = (scope: string, version: string): InstalledPluginEntry =>
+		({
+			scope,
+			installPath: cacheFor(version),
+			version,
+			installedAt: "2026-01-01T00:00:00.000Z",
+			lastUpdated: "2026-01-01T00:00:00.000Z",
+			// `managed` is a scope Claude Code writes and types/index.ts does not
+			// name — see LoaderScope in plugin-resolution.ts.
+		}) as unknown as InstalledPluginEntry;
+
+	test("a user-scope row is NOT moved forward, and this repo's rows are left alone too", async () => {
+		// It is the winner here, so no rewrite this function is willing to make can
+		// change the resolution. Refusing and naming the scope is the answer; the
+		// old behaviour moved the machine-wide row and reported success.
+		await writeRegistry([
+			machineWide("user", "0.3.0"),
+			row({ version: "0.5.0", projectPath: here }),
+		]);
+		const before = await fs.readFile(registryFile, "utf8");
+
+		const result = await repairStaleLoad(PLUGIN, "0.5.0", here, root);
+
+		expect(result.ok).toBe(false);
+		expect(result.error).toContain("machine-wide user-scope record at v0.3.0");
+		expect(result.error).toContain("--scope user");
+		expect(result.rewritten).toBe(0);
+		expect(await fs.readFile(registryFile, "utf8")).toBe(before);
+		expect(await backups()).toEqual([]);
+	});
+
+	test("an exact pin caps the survey, so a pinned plugin is never offered or moved", async () => {
+		// The measured shape: pin 0.3.0, this repository installed and loading 0.3.0,
+		// and a user-scope install at 0.5.0. The machine-wide row is relevant to every
+		// directory, so an uncapped survey took 0.5.0 as the target, offered the
+		// plugin in the startup popup, and the repair succeeded — moving a pinned
+		// plugin off its pin. Only the pin can say that move is unwanted.
+		//
+		// Array order puts this repository's row first so it is the loader's winner;
+		// otherwise the user row loads and there is no mismatch to survey at all.
+		await writeRegistry([
+			row({ version: "0.3.0", projectPath: here }),
+			machineWide("user", "0.5.0"),
+		]);
+		expect(
+			pickLoadedEntry((await readRegistry()).plugins[PLUGIN], here)?.version,
+		).toBe("0.3.0");
+
+		const pins = { [PLUGIN]: "0.3.0" };
+		expect(await findStaleLoads(here, root, pins)).toEqual([]);
+		expect(await repairAllStaleLoads(here, root, pins)).toEqual([]);
+		expect((await readRegistry()).plugins[PLUGIN][0].version).toBe("0.3.0");
+		expect(await backups()).toEqual([]);
+	});
+
+	test("the same rows on `latest` are surveyed and repaired to the user-scope version", async () => {
+		// The negative control for the cap: with nothing pinning the plugin down,
+		// 0.5.0 is the version this machine holds and loading 0.3.0 here is the
+		// defect the popup exists to report. The cap must not disable that.
+		await writeRegistry([
+			row({ version: "0.3.0", projectPath: here }),
+			machineWide("user", "0.5.0"),
+		]);
+
+		expect(await findStaleLoads(here, root)).toEqual([
+			{ pluginId: PLUGIN, loaded: "0.3.0", target: "0.5.0" },
+		]);
+		const [result] = await repairAllStaleLoads(here, root);
+		expect(result?.ok).toBe(true);
+		expect((await readRegistry()).plugins[PLUGIN][0].version).toBe("0.5.0");
+	});
+
+	test("a managed row is named as policy, not as something to update", async () => {
+		await writeRegistry([
+			machineWide("managed", "0.3.0"),
+			row({ version: "0.5.0", projectPath: here }),
+		]);
+
+		const result = await repairStaleLoad(PLUGIN, "0.5.0", here, root);
+
+		expect(result.ok).toBe(false);
+		expect(result.error).toContain("machine-wide managed-scope record");
+		expect(result.error).toContain("administrator policy");
+	});
+
+	test("a user-scope row that is not the winner stays where it is", async () => {
+		// The rows that decide the load here are this repository's, so the repair
+		// runs — and the machine-wide row at 0.4.0 must come out untouched. It was
+		// rewritten to 0.5.0 before this filter existed, changing what every other
+		// project on the machine resolves.
+		await writeRegistry([
+			row({ version: "0.3.0", projectPath: gone }),
+			machineWide("user", "0.4.0"),
+			row({ version: "0.5.0", projectPath: here }),
+		]);
+
+		const result = await repairStaleLoad(PLUGIN, "0.5.0", here, root);
+
+		expect(result.ok).toBe(true);
+		expect(result.rewritten).toBe(1);
+		const after = (await readRegistry()).plugins[PLUGIN];
+		expect(after.map((e) => [e.scope, e.version])).toEqual([
+			["project", "0.5.0"],
+			["user", "0.4.0"],
+			["project", "0.5.0"],
+		]);
+		expect(after[1].installPath).toBe(cacheFor("0.4.0"));
+	});
+
+	test("a rootless row from another directory is relevant but never rewritten", async () => {
+		// The loader's filter compares repository roots and two nulls are equal
+		// there, so this row genuinely competes — `isRelevantInstallation` says so
+		// and plugin-resolution.test.ts pins it. Writing it is a different question:
+		// "the same repository" cannot be true of two directories that are in no
+		// repository, so the repair reports that it could not fix this rather than
+		// editing a stranger's row.
+		const looseHere = path.join(base, "loose-here");
+		const looseOther = path.join(base, "loose-other");
+		await fs.ensureDir(looseHere);
+		await fs.ensureDir(looseOther);
+		expect(repoRootForPath(looseHere)).toBeNull();
+		await writeRegistry([
+			row({ version: "0.3.0", projectPath: looseOther }),
+			row({ version: "0.5.0", projectPath: looseHere }),
+		]);
+		expect(
+			isRelevantInstallation(
+				(await readRegistry()).plugins[PLUGIN][0],
+				looseHere,
+				repoRootForPath(looseHere),
+			),
+		).toBe(true);
+
+		const result = await repairStaleLoad(PLUGIN, "0.5.0", looseHere, root);
+
+		expect(result.rewritten).toBe(0);
+		expect(result.ok).toBe(false);
+		expect(result.error).toContain("still resolves v0.3.0");
+		expect((await readRegistry()).plugins[PLUGIN][0].version).toBe("0.3.0");
+	});
+});
+
+/**
+ * A LOST UPDATE is not prevented by an atomic write.
+ *
+ * The rename cannot be seen half-done, and that was the whole guarantee: the
+ * repair still rewrote the WHOLE file from a snapshot, so any other session's
+ * `claude plugin install` landing in between was discarded by a write that was
+ * perfectly atomic. This file is written constantly — dozens of live sessions on
+ * a working machine — and this repo's own resolution note measured it drifting
+ * inside minutes.
+ */
+describe("repairStaleLoad — a concurrent write is refused, not clobbered", () => {
+	test("another session's install survives, and the repair says why it stopped", async () => {
+		await writeRegistry([
+			row({ version: "0.3.0", projectPath: gone }),
+			row({ version: "0.5.0", projectPath: here }),
+		]);
+
+		// The interleave, forced at the one point the repair is guaranteed to await
+		// between reading the file and renaming over it: the backup copy. The
+		// concurrent writer adds a row for a DIFFERENT plugin, which is what a
+		// `claude plugin install` in another project looks like.
+		const realCopy: (src: string, dest: string) => Promise<void> =
+			fs.copy.bind(fs);
+		const spy = spyOn(fs, "copy").mockImplementation(
+			async (src: string, dest: string) => {
+				const current: InstalledPluginsRegistry =
+					await fs.readJson(registryFile);
+				current.plugins["other@magus"] = [
+					row({ version: "1.0.0", projectPath: here }),
+				];
+				await fs.outputJson(registryFile, current, { spaces: 2 });
+				return realCopy(src, dest);
+			},
+		);
+
+		try {
+			const result = await repairStaleLoad(PLUGIN, "0.5.0", here, root);
+
+			expect(result.ok).toBe(false);
+			expect(result.error).toContain("changed on disk after it was read");
+			expect(result.rewritten).toBe(0);
+		} finally {
+			spy.mockRestore();
+		}
+
+		const after = await readRegistry();
+		// The other session's row is still there — the whole point.
+		expect(after.plugins["other@magus"]?.[0]?.version).toBe("1.0.0");
+		// And nothing of ours was written from the stale snapshot.
+		expect(after.plugins[PLUGIN].map((e) => e.version)).toEqual([
+			"0.3.0",
+			"0.5.0",
+		]);
+		// A backup is an undo for a file that changed; nothing changed, so it goes.
+		expect(await backups()).toEqual([]);
+	});
+
+	test("the guarded write refuses directly when the bytes it was given are stale", async () => {
+		// The mechanism on its own, without the interleave: `expectBytes` is the
+		// precondition, and a write carrying yesterday's bytes must not land.
+		await writeRegistry([row({ version: "0.5.0", projectPath: here })]);
+		const stale = await fs.readFile(registryFile, "utf8");
+		await writeRegistry([row({ version: "0.9.0", projectPath: here })]);
+		const current = await fs.readFile(registryFile, "utf8");
+
+		await expect(
+			writeInstalledPluginsRegistry({ version: 2, plugins: {} }, root, stale),
+		).rejects.toThrow("changed on disk after it was read");
+		expect(await fs.readFile(registryFile, "utf8")).toBe(current);
+
+		// With the CURRENT bytes it lands, so the guard is not simply refusing
+		// everything.
+		await writeInstalledPluginsRegistry(
+			{ version: 2, plugins: {} },
+			root,
+			current,
+		);
+		expect((await readRegistry()).plugins).toEqual({});
+	});
+});
+
+describe("registry backups — one per repair, pruned", () => {
+	test("the filename names the plugin, so two repairs in one run are two files", async () => {
+		// Keyed on `Date.now()` alone, two repairs inside the same millisecond
+		// produced the SAME path and `fs.copy` overwrote — so in a multi-plugin
+		// repair the surviving file no longer held the first plugin's pre-repair
+		// state, and the only undo for it was gone.
+		await fs.ensureDir(path.join(root, "cache", "magus", "dev", "7.0.0"));
+		await fs.ensureDir(path.join(root, "cache", "magus", "dev", "7.4.0"));
+		const devRow = (version: string, projectPath: string) => ({
+			scope: "project" as const,
+			projectPath,
+			installPath: path.join(root, "cache", "magus", "dev", version),
+			version,
+			installedAt: "2026-01-01T00:00:00.000Z",
+			lastUpdated: "2026-01-01T00:00:00.000Z",
+		});
+		await fs.outputJson(
+			registryFile,
+			{
+				version: 2,
+				plugins: {
+					[PLUGIN]: [
+						row({ version: "0.3.0", projectPath: gone }),
+						row({ version: "0.5.0", projectPath: here }),
+					],
+					"dev@magus": [devRow("7.0.0", gone), devRow("7.4.0", here)],
+				},
+			},
+			{ spaces: 2 },
+		);
+
+		const results = await repairAllStaleLoads(here, root);
+		expect(results.every((r) => r.ok)).toBe(true);
+
+		const names = await backups();
+		expect(names.length).toBe(2);
+		expect(names.some((n) => n.endsWith("dev-magus"))).toBe(true);
+		expect(names.some((n) => n.endsWith("madbench-magus"))).toBe(true);
+		// Each holds the state before ITS OWN repair: dev's backup predates both.
+		const devBackup: InstalledPluginsRegistry = await fs.readJson(
+			path.join(root, names.find((n) => n.endsWith("dev-magus")) as string),
+		);
+		expect(devBackup.plugins["dev@magus"].map((e) => e.version)).toEqual([
+			"7.0.0",
+			"7.4.0",
+		]);
+	});
+
+	test("old backups are pruned to the newest ten", async () => {
+		// The backup is the only undo for a write to Claude Code-owned state, so
+		// they are kept — but nothing pruned them, and every repair left another
+		// copy of a multi-hundred-KB file in a directory magus does not own.
+		await writeRegistry([
+			row({ version: "0.3.0", projectPath: gone }),
+			row({ version: "0.5.0", projectPath: here }),
+		]);
+		// Timestamps well below `Date.now()`, same width so a name sort orders them,
+		// so the real backup sorts newest and the dummies sort oldest-first.
+		for (let i = 0; i < 12; i++) {
+			const stamp = `1000000000${String(i).padStart(3, "0")}`;
+			await fs.outputFile(`${registryFile}.backup.${stamp}.0.older`, "{}");
+		}
+
+		const result = await repairStaleLoad(PLUGIN, "0.5.0", here, root);
+		expect(result.ok).toBe(true);
+
+		const names = await backups();
+		expect(names.length).toBe(10);
+		expect(names.at(-1)).toBe(path.basename(result.backup as string));
+		// The oldest three went; the newest of the dummies stayed.
+		expect(names.some((n) => n.includes("1000000000000.0.older"))).toBe(false);
+		expect(names.some((n) => n.includes("1000000000002.0.older"))).toBe(false);
+		expect(names.some((n) => n.includes("1000000000003.0.older"))).toBe(true);
+		expect(names.some((n) => n.includes("1000000000011.0.older"))).toBe(true);
+	});
+});
+
+describe("repairStaleLoad — the post-write assertion", () => {
+	test("a write that does NOT change the resolution reports FAILURE", async () => {
+		// Every relevant row behind 0.5.0 is moved forward, and the loader still
+		// resolves something else: mainTree's row is ahead of the target, exists on
+		// disk, and comes first, so it keeps winning. The repair genuinely did not
+		// achieve what it was asked for, and saying "ok" here would be exactly the
+		// deception this whole state exists to end.
+		await writeRegistry([
+			row({ version: "0.9.0", projectPath: mainTree }),
+			row({ version: "0.3.0", projectPath: gone }),
+			row({ version: "0.5.0", projectPath: here }),
+		]);
+
+		const result = await repairStaleLoad(PLUGIN, "0.5.0", here, root);
+
+		expect(result.rewritten).toBe(1);
+		expect(result.loaded).toBe("0.9.0");
+		expect(result.ok).toBe(false);
+		expect(result.error).toContain("still resolves v0.9.0");
+	});
+
+	test("the assertion reads the file from DISK, not the object it mutated", async () => {
+		await writeRegistry([
+			row({ version: "0.3.0", projectPath: gone }),
+			row({ version: "0.5.0", projectPath: here }),
+		]);
+
+		const result = await repairStaleLoad(PLUGIN, "0.5.0", here, root);
+
+		// Proving the claim means re-resolving the persisted file independently and
+		// getting the same answer the repair reported.
+		expect(
+			pickLoadedEntry((await readRegistry()).plugins[PLUGIN], here)?.version,
+		).toBe(result.loaded);
+		expect(result.loaded).toBe("0.5.0");
+	});
+
+	test("a repair reporting ok means the loader really resolves the target", async () => {
+		await writeRegistry([
+			row({ version: "0.3.0", projectPath: gone }),
+			row({ version: "0.4.0", projectPath: here }),
+		]);
+
+		const result = await repairStaleLoad(PLUGIN, "0.4.0", here, root);
+
+		expect(result.ok).toBe(true);
+		expect(
+			pickLoadedEntry((await readRegistry()).plugins[PLUGIN], here)?.version,
+		).toBe("0.4.0");
+	});
+});
+
+describe("findStaleLoads", () => {
+	test("names the broken plugin and the version to repair it to", async () => {
+		await writeRegistry([
+			row({ version: "0.3.0", projectPath: gone }),
+			row({ version: "0.5.0", projectPath: here }),
+		]);
+
+		expect(await findStaleLoads(here, root)).toEqual([
+			{ pluginId: PLUGIN, loaded: "0.3.0", target: "0.5.0" },
+		]);
+	});
+
+	test("a plugin loading its newest relevant row is not reported", async () => {
+		await writeRegistry([
+			row({ version: "0.5.0", projectPath: here }),
+			row({ version: "0.3.0", projectPath: gone }),
+		]);
+
+		expect(await findStaleLoads(here, root)).toEqual([]);
+	});
+
+	test("rows from other repositories cannot make a plugin look broken", async () => {
+		const other = path.join(base, "unrelated-find");
+		await fs.ensureDir(other);
+		git(other, "init", "-q");
+
+		await writeRegistry([
+			row({ version: "0.3.0", projectPath: here }),
+			row({ version: "0.9.0", projectPath: other }),
+		]);
+
+		expect(await findStaleLoads(here, root)).toEqual([]);
+	});
+
+	test("an empty registry reports nothing", async () => {
+		await fs.outputJson(registryFile, { version: 2, plugins: {} });
+		expect(await findStaleLoads(here, root)).toEqual([]);
+	});
+
+	test("a target with no cache directory is not offered as a finding", async () => {
+		// `repairStaleLoad` refuses this target outright, so reporting it would put
+		// a plugin in the popup's count that pressing FIX could not repair. Asking
+		// the refusal in advance is the fix.
+		await writeRegistry([
+			row({ version: "0.3.0", projectPath: gone }),
+			row({ version: "0.7.0", projectPath: here }),
+		]);
+		expect(await fs.pathExists(cacheFor("0.7.0"))).toBe(false);
+
+		expect(await findStaleLoads(here, root)).toEqual([]);
+	});
+
+	test("an 'unknown' version is never a target", async () => {
+		// MEASURED: plugin-dev@claude-plugins-official recorded the literal string
+		// "unknown". There is no version to move rows to and no cache directory
+		// named `unknown`, so the popup was offering a fix that could not run.
+		await writeRegistry([
+			row({ version: "76c85b7366c8", projectPath: gone }),
+			row({ version: "unknown", projectPath: here }),
+		]);
+
+		expect(await findStaleLoads(here, root)).toEqual([]);
+	});
+
+	test("two differing commit shas are not a repair", async () => {
+		// MEASURED: skill-creator@claude-plugins-official. `isBehind` answers true
+		// for two differing opaque ids — correct for "is this what is published
+		// now", wrong here. Nothing orders two shas, so "move forward" would pick
+		// one at random and call it a repair.
+		const shaHere = "517b2fcd1b60";
+		const shaGone = "76c85b7366c8";
+		await fs.ensureDir(path.join(root, "cache", "magus", "madbench", shaHere));
+		await writeRegistry([
+			row({
+				version: shaGone,
+				projectPath: gone,
+				installPath: path.join(root, "cache", "magus", "madbench", shaGone),
+			}),
+			row({
+				version: shaHere,
+				projectPath: here,
+				installPath: path.join(root, "cache", "magus", "madbench", shaHere),
+			}),
+		]);
+
+		expect(await findStaleLoads(here, root)).toEqual([]);
+	});
+});
+
+/**
+ * THE invariant: the startup popup and the Plugins header count the same plugins.
+ *
+ * They did not. Measured in this worktree on the reporting machine, the header
+ * said `6 broken` and the popup said `8 broken plugins` — the popup was asking
+ * `isBehind` where the classifier asks the narrower "is this an ordered move
+ * forward", so it counted two plugins nothing could repair and offered to fix
+ * them. This repo's own note in PluginsScreen.tsx says a header must never count
+ * a row the list beside it does not show; the same rule across two surfaces is
+ * what this describes.
+ *
+ * Both sides are derived from ONE registry fixture here, the panel's through
+ * `resolveLoadedVersions` exactly as plugin-manager does it, so the test cannot
+ * pass by two hand-written numbers agreeing.
+ */
+describe("the popup count equals the Plugins header count", () => {
+	/**
+	 * The panel's side: classify rows whose loadedVersion comes off the registry.
+	 *
+	 * @param published what the MARKETPLACE offers for every plugin, relative to
+	 *   what this project holds. The fixture used to hardcode "the same version",
+	 *   and that is the one configuration where the classifier's two candidate
+	 *   formulas — catalog-versus-loaded and installed-versus-loaded — cannot
+	 *   disagree. 220 tests passed over a `stale-load` branch that asked the
+	 *   catalog question, which turned every pending release into a BROKEN row
+	 *   that no installer ever fixed. So the pending case is a parameter now, and
+	 *   `"ahead"` is the input that separates the two. `"none"` is the mirror
+	 *   failure: a marketplace that publishes no version at all (278 of the 292
+	 *   official plugins), where the catalog formula answered false and a real
+	 *   stale load read as `current`.
+	 */
+	async function headerBrokenCount(
+		published: "same" | "ahead" | "none" = "same",
+	): Promise<number> {
+		const registry: InstalledPluginsRegistry = await readRegistry();
+		const loaded = resolveLoadedVersions(registry, here);
+		const plugins: PluginInfo[] = Object.entries(registry.plugins).map(
+			([id, rows]) => {
+				// The version this project holds, as the Plugins screen sees it: the
+				// newest row relevant to this directory.
+				const mine =
+					rows.find((r) => r.projectPath === here)?.version ??
+					(rows[0]?.version as string);
+				return {
+					id,
+					name: id.split("@")[0] as string,
+					// What the catalog offers. `ahead` stands for the ordinary state of
+					// this marketplace: a release is published and not installed yet.
+					version:
+						published === "ahead"
+							? bumped(mine)
+							: published === "none"
+								? null
+								: mine,
+					description: "",
+					marketplace: id.split("@")[1] ?? "magus",
+					marketplaceDisplay: "",
+					enabled: true,
+					installedVersion: mine,
+					loadedVersion: loaded[id] ?? null,
+					projectScope: { enabled: true, version: mine },
+				} as PluginInfo;
+			},
+		);
+		return countPluginStates(classifyPluginRows(plugins, {}).values())[
+			"stale-load"
+		];
+	}
+
+	/**
+	 * One minor version up, or the string unchanged when it carries no ordering
+	 * (a commit sha, the literal "unknown"). Those plugins are excluded by both
+	 * surfaces for other reasons and must stay excluded, so leaving them alone
+	 * keeps this helper from being the thing that changes their answer.
+	 */
+	function bumped(version: string): string {
+		const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
+		if (!m) return version;
+		return `${m[1]}.${Number(m[2]) + 1}.0`;
+	}
+
+	/**
+	 * Two genuinely broken plugins, plus the two shapes that used to inflate the
+	 * popup, plus one healthy plugin.
+	 */
+	beforeEach(async () => {
+		const at = (name: string, version: string) =>
+			path.join(root, "cache", "magus", name, version);
+		for (const [name, version] of [
+			["madbench", "0.3.0"],
+			["madbench", "0.5.0"],
+			["dev", "7.0.0"],
+			["dev", "8.0.0"],
+			["healthy", "1.0.0"],
+			["shaish", "517b2fcd1b60"],
+			["shaish", "76c85b7366c8"],
+			["unversioned", "76c85b7366c8"],
+		] as const) {
+			await fs.ensureDir(at(name, version));
+		}
+
+		const pair = (
+			name: string,
+			oldVersion: string,
+			newVersion: string,
+		): InstalledPluginEntry[] => [
+			{
+				scope: "project",
+				projectPath: gone,
+				installPath: at(name, oldVersion),
+				version: oldVersion,
+				installedAt: "2026-01-01T00:00:00.000Z",
+				lastUpdated: "2026-01-01T00:00:00.000Z",
+			},
+			{
+				scope: "project",
+				projectPath: here,
+				installPath: at(name, newVersion),
+				version: newVersion,
+				installedAt: "2026-01-01T00:00:00.000Z",
+				lastUpdated: "2026-01-01T00:00:00.000Z",
+			},
+		];
+
+		await fs.outputJson(
+			registryFile,
+			{
+				version: 2,
+				plugins: {
+					// Broken and repairable.
+					"madbench@magus": pair("madbench", "0.3.0", "0.5.0"),
+					"dev@magus": pair("dev", "7.0.0", "8.0.0"),
+					// Sha-versioned: unorderable, so not a repair either way.
+					"shaish@magus": pair("shaish", "76c85b7366c8", "517b2fcd1b60"),
+					// Target is the literal string "unknown".
+					"unversioned@magus": pair("unversioned", "76c85b7366c8", "unknown"),
+					// Healthy: one row, loading what it holds.
+					"healthy@magus": [
+						{
+							scope: "project",
+							projectPath: here,
+							installPath: at("healthy", "1.0.0"),
+							version: "1.0.0",
+							installedAt: "2026-01-01T00:00:00.000Z",
+							lastUpdated: "2026-01-01T00:00:00.000Z",
+						},
+					],
+				},
+			},
+			{ spaces: 2 },
+		);
+	});
+
+	test("both surfaces count exactly the two repairable plugins", async () => {
+		const popup = await findStaleLoads(here, root);
+
+		expect(popup.map((p) => p.pluginId)).toEqual([
+			"dev@magus",
+			"madbench@magus",
+		]);
+		expect(popup.length).toBe(await headerBrokenCount());
+		expect(popup.length).toBe(2);
+	});
+
+	test("the sha-versioned and 'unknown' plugins are excluded by BOTH", async () => {
+		// Named individually so a regression says which shape came back rather than
+		// only that a count moved.
+		const reported = (await findStaleLoads(here, root)).map((p) => p.pluginId);
+
+		expect(reported).not.toContain("shaish@magus");
+		expect(reported).not.toContain("unversioned@magus");
+		expect(reported).not.toContain("healthy@magus");
+		expect(await headerBrokenCount()).toBe(2);
+	});
+
+	test("a PENDING RELEASE on every plugin changes neither count", async () => {
+		// The configuration the fixture could not previously express, and the one
+		// that matters most: the marketplace is one minor version ahead of what is
+		// installed, which is the normal state of this repo's own marketplace.
+		//
+		// `healthy@magus` loads exactly what it holds and is merely behind the
+		// catalog — an `update`, not a broken load. Before the classifier compared
+		// the INSTALLED version against the loaded one, it counted here as
+		// `stale-load` with no scopes: red in the header, offered as "press a to
+		// fix", and fixed by nothing, because no installer runs for that state.
+		expect(await headerBrokenCount("ahead")).toBe(2);
+		expect((await findStaleLoads(here, root)).length).toBe(2);
+	});
+
+	test("an UNVERSIONED catalog hides neither of them", async () => {
+		// The mirror: with no published version to compare, the catalog formula
+		// answered false for every plugin and both genuinely broken ones read as
+		// `current` — a clean bill of health over two sessions running old code.
+		expect(await headerBrokenCount("none")).toBe(2);
+		expect((await findStaleLoads(here, root)).length).toBe(2);
+	});
+
+	test("every plugin the popup names is one repairAllStaleLoads actually fixes", async () => {
+		// The count agreeing is not enough: the popup's promise is that pressing FIX
+		// repairs what it counted. Each result must be `ok`, which is the repair's
+		// own post-write assertion that the loader now resolves the target.
+		const results = await repairAllStaleLoads(here, root);
+
+		expect(results.map((r) => [r.pluginId, r.ok])).toEqual([
+			["dev@magus", true],
+			["madbench@magus", true],
+		]);
+		expect(await findStaleLoads(here, root)).toEqual([]);
+		expect(await headerBrokenCount()).toBe(0);
+	});
+});
+
+describe("repairAllStaleLoads", () => {
+	test("repairs every plugin findStaleLoads names, and clears the survey", async () => {
+		await fs.ensureDir(path.join(root, "cache", "magus", "dev", "7.4.0"));
+		await fs.ensureDir(path.join(root, "cache", "magus", "dev", "7.0.0"));
+		await fs.outputJson(
+			registryFile,
+			{
+				version: 2,
+				plugins: {
+					[PLUGIN]: [
+						row({ version: "0.3.0", projectPath: gone }),
+						row({ version: "0.5.0", projectPath: here }),
+					],
+					"dev@magus": [
+						{
+							scope: "project",
+							projectPath: gone,
+							installPath: path.join(root, "cache", "magus", "dev", "7.0.0"),
+							version: "7.0.0",
+							installedAt: "2026-01-01T00:00:00.000Z",
+							lastUpdated: "2026-01-01T00:00:00.000Z",
+						},
+						{
+							scope: "project",
+							projectPath: here,
+							installPath: path.join(root, "cache", "magus", "dev", "7.4.0"),
+							version: "7.4.0",
+							installedAt: "2026-01-01T00:00:00.000Z",
+							lastUpdated: "2026-01-01T00:00:00.000Z",
+						},
+					],
+				},
+			},
+			{ spaces: 2 },
+		);
+
+		const results = await repairAllStaleLoads(here, root);
+
+		expect(results.map((r) => [r.pluginId, r.ok, r.loaded])).toEqual([
+			["dev@magus", true, "7.4.0"],
+			[PLUGIN, true, "0.5.0"],
+		]);
+		expect(await findStaleLoads(here, root)).toEqual([]);
+	});
+
+	test("a healthy machine repairs nothing and writes no backup", async () => {
+		await writeRegistry([row({ version: "0.5.0", projectPath: here })]);
+
+		expect(await repairAllStaleLoads(here, root)).toEqual([]);
+		expect(await backups()).toEqual([]);
+	});
+});