magus-cli 0.0.0-placeholder → 7.1.0

package/src/__tests__/update-plan.test.ts

@@ -0,0 +1,1396 @@
+import { describe, expect, test } from "bun:test";
+import type { PluginInfo } from "../services/plugin-manager.js";
+import { type ToolFacts, classifyTool } from "../services/tool-probe.js";
+import {
+	applyBins,
+	binCommandFor,
+	planWorkItems,
+} from "../services/update-engine.js";
+import {
+	type BinUpdateAction,
+	type BinUpdateItem,
+	type PluginUpdateItem,
+	type UpdatePlan,
+	binNeedsWork,
+	classifyPlugin,
+	classifyPluginRows,
+	countPluginStates,
+	indexCatalog,
+	pinForRow,
+	planBinUpdates,
+	planHasWork,
+	planIsBehind,
+	planPluginUpdates,
+	planSkillUpdates,
+	scopeIsBehind,
+	scopesNeeding,
+	summarizePlan,
+} from "../services/update-plan.js";
+import type { ResolvedBin } from "../types/index.js";
+
+/** A PluginInfo with only the fields the planner reads. */
+function info(overrides: Partial<PluginInfo> & { id: string }): PluginInfo {
+	return {
+		name: overrides.id.split("@")[0]!,
+		version: null,
+		description: "",
+		marketplace: overrides.id.split("@")[1] ?? "magus",
+		marketplaceDisplay: "",
+		enabled: true,
+		...overrides,
+	} as PluginInfo;
+}
+
+function catalog(...infos: PluginInfo[]): Map<string, PluginInfo> {
+	return new Map(infos.map((i) => [i.id, i]));
+}
+
+/** Probe facts for a present, managed tool; override what the case is about. */
+function toolFacts(name: string, over: Partial<ToolFacts> = {}): ToolFacts {
+	return {
+		name,
+		present: true,
+		resolvedPath: `/bin/${name}`,
+		installed: "1.0.0",
+		latest: null,
+		behind: null,
+		managed: true,
+		sources: [],
+		...over,
+	};
+}
+
+function plan(overrides: Partial<UpdatePlan> = {}): UpdatePlan {
+	return {
+		profileId: "test",
+		plugins: [],
+		bins: [],
+		skills: [],
+		binSpecs: new Map(),
+		...overrides,
+	};
+}
+
+describe("planPluginUpdates — the profile declares it, the machine lacks it", () => {
+	test("a plugin absent from every scope is an install", () => {
+		const [item] = planPluginUpdates(
+			{ "dev@magus": "latest" },
+			catalog(info({ id: "dev@magus", version: "4.7.0" })),
+		);
+		expect(item).toMatchObject({
+			action: "install",
+			installed: null,
+			target: "4.7.0",
+			scopes: [],
+		});
+		expect(item.reason).toBe("absent");
+	});
+
+	test("a plugin missing from the catalog entirely is still an install", () => {
+		// The marketplace may not be registered yet — install registers it.
+		const [item] = planPluginUpdates({ "new@magus": "latest" }, catalog());
+		expect(item).toMatchObject({ action: "install", available: null });
+		expect(item.reason).toBe("absent");
+	});
+
+	test("an exact pin that is not installed installs that exact version", () => {
+		const [item] = planPluginUpdates(
+			{ "dev@magus": "4.6.1" },
+			catalog(info({ id: "dev@magus", version: "4.7.0" })),
+		);
+		expect(item.target).toBe("4.6.1");
+		expect(item.reason).toBe("absent");
+	});
+});
+
+describe("planPluginUpdates — advancing a 'latest' pin", () => {
+	test("a newer catalog version is an update, targeting it", () => {
+		const [item] = planPluginUpdates(
+			{ "dev@magus": "latest" },
+			catalog(
+				info({
+					id: "dev@magus",
+					version: "4.7.0",
+					projectScope: { enabled: true, version: "4.6.1" },
+				}),
+			),
+		);
+		expect(item).toMatchObject({
+			action: "update",
+			installed: "4.6.1",
+			target: "4.7.0",
+			scopes: ["project"],
+		});
+		expect(item.reason).toBe("behind");
+	});
+
+	test("the same version is current, with no scopes to touch", () => {
+		const [item] = planPluginUpdates(
+			{ "dev@magus": "latest" },
+			catalog(
+				info({
+					id: "dev@magus",
+					version: "4.7.0",
+					projectScope: { enabled: true, version: "4.7.0" },
+				}),
+			),
+		);
+		expect(item).toMatchObject({ action: "current", scopes: [] });
+		expect(item.reason).toBe("up-to-date");
+	});
+
+	test("an older catalog version does not downgrade a 'latest' pin", () => {
+		const [item] = planPluginUpdates(
+			{ "dev@magus": "latest" },
+			catalog(
+				info({
+					id: "dev@magus",
+					version: "4.5.0",
+					projectScope: { enabled: true, version: "4.7.0" },
+				}),
+			),
+		);
+		expect(item.action).toBe("current");
+		expect(item.reason).toBe("up-to-date");
+	});
+});
+
+describe("planPluginUpdates — a failed check is never 'up to date'", () => {
+	test("updateCheckFailed yields 'unknown', not 'current'", () => {
+		const [item] = planPluginUpdates(
+			{ "dev@magus": "latest" },
+			catalog(
+				info({
+					id: "dev@magus",
+					// The stale local clone reports the same version we have installed:
+					// without the flag this is indistinguishable from a clean check.
+					version: "4.6.1",
+					projectScope: { enabled: true, version: "4.6.1" },
+					updateCheckFailed: true,
+					updateCheckFailure: {
+						marketplace: "magus",
+						kind: "rate-limit",
+						detail: "GitHub rate limit",
+					},
+				}),
+			),
+		);
+		expect(item.action).toBe("unknown");
+		expect(item.note).toBe("GitHub rate limit");
+		expect(item.target).toBeNull();
+		expect(item.reason).toBe("catalog-unverified");
+	});
+
+	test("an unknown plugin is still work to look at, but does not fail --check", () => {
+		// The two predicates split here on purpose: the run has something to
+		// report (planHasWork), yet nothing is KNOWN to be behind, so the CI gate
+		// passes. Nothing is applied for an unknown either way.
+		const p = plan({
+			plugins: planPluginUpdates(
+				{ "dev@magus": "latest" },
+				catalog(
+					info({
+						id: "dev@magus",
+						version: "4.6.1",
+						projectScope: { enabled: true, version: "4.6.1" },
+						updateCheckFailed: true,
+					}),
+				),
+			),
+		});
+		expect(planHasWork(p)).toBe(true);
+		expect(planIsBehind(p)).toBe(false);
+	});
+});
+
+describe("planPluginUpdates — content drift", () => {
+	test("same version, changed files is a repair across every installed scope", () => {
+		const [item] = planPluginUpdates(
+			{ "dev@magus": "latest" },
+			catalog(
+				info({
+					id: "dev@magus",
+					version: "4.6.1",
+					contentStale: true,
+					userScope: { enabled: true, version: "4.6.1" },
+					projectScope: { enabled: true, version: "4.6.1" },
+				}),
+			),
+		);
+		expect(item.action).toBe("repair");
+		expect(item.scopes).toEqual(["user", "project"]);
+		expect(item.reason).toBe("content-stale");
+	});
+});
+
+describe("planPluginUpdates — an exact pin plans against what is deliverable", () => {
+	// This is dependency management, not a package manager: `claude plugin
+	// install` takes no version, so the only installable version is whatever the
+	// marketplace publishes now. A pin naming anything else cannot be satisfied,
+	// and planning toward it anyway never converges.
+
+	test("targets the marketplace version, not the unreachable pin", () => {
+		const [item] = planPluginUpdates(
+			{ "dev@magus": "4.6.1" },
+			catalog(
+				info({
+					id: "dev@magus",
+					version: "9.9.9",
+					projectScope: { enabled: true, version: "4.0.0" },
+				}),
+			),
+		);
+		expect(item).toMatchObject({ action: "update", target: "9.9.9" });
+		expect(item.reason).toBe("pin-undeliverable");
+	});
+
+	test("an unreachable pin is NOTED, never silently abandoned", () => {
+		const [item] = planPluginUpdates(
+			{ "dev@magus": "4.6.1" },
+			catalog(
+				info({
+					id: "dev@magus",
+					version: "9.9.9",
+					projectScope: { enabled: true, version: "9.9.9" },
+				}),
+			),
+		);
+		expect(item.note).toBe(
+			"manifest pins 4.6.1; the marketplace offers only 9.9.9",
+		);
+		expect(item.reason).toBe("pin-undeliverable");
+	});
+
+	test("already on the only installable version is CURRENT — no churn", () => {
+		// The bug this guards: planning 9.9.9 → 4.6.1 forever. Install returns
+		// 9.9.9, the next run replans the identical move, and --check fails in
+		// between every time.
+		const [item] = planPluginUpdates(
+			{ "dev@magus": "4.6.1" },
+			catalog(
+				info({
+					id: "dev@magus",
+					version: "9.9.9",
+					projectScope: { enabled: true, version: "9.9.9" },
+				}),
+			),
+		);
+		expect(item.action).toBe("current");
+		expect(item.scopes).toEqual([]);
+		expect(item.reason).toBe("pin-undeliverable");
+	});
+
+	test("an unsatisfiable pin does not fail --check forever", () => {
+		const p = plan({
+			plugins: planPluginUpdates(
+				{ "dev@magus": "4.6.1" },
+				catalog(
+					info({
+						id: "dev@magus",
+						version: "9.9.9",
+						projectScope: { enabled: true, version: "9.9.9" },
+					}),
+				),
+			),
+		});
+		expect(planIsBehind(p)).toBe(false);
+	});
+
+	test("a pin the marketplace DOES offer is honoured exactly", () => {
+		const [item] = planPluginUpdates(
+			{ "dev@magus": "4.6.1" },
+			catalog(
+				info({
+					id: "dev@magus",
+					version: "4.6.1",
+					projectScope: { enabled: true, version: "4.0.0" },
+				}),
+			),
+		);
+		expect(item).toMatchObject({ action: "update", target: "4.6.1" });
+		expect(item.note).toBeUndefined();
+		expect(item.reason).toBe("behind");
+	});
+
+	test("falls back to the pin when the catalog offers nothing", () => {
+		const [item] = planPluginUpdates(
+			{ "dev@magus": "4.6.1" },
+			catalog(
+				info({
+					id: "dev@magus",
+					version: null,
+					projectScope: { enabled: true, version: "4.0.0" },
+				}),
+			),
+		);
+		expect(item.target).toBe("4.6.1");
+		expect(item.reason).toBe("behind");
+	});
+});
+
+describe("per-scope decisions — a stale scope is never masked", () => {
+	test("project behind while user is current is an UPDATE, not 'current'", async () => {
+		// `installed` is the highest version across scopes. Deciding from it hid
+		// exactly this: project scope — the one that actually loads for the repo —
+		// sits behind while user scope drags the comparison up to "current".
+		const [item] = planPluginUpdates(
+			{ "dev@magus": "latest" },
+			catalog(
+				info({
+					id: "dev@magus",
+					version: "4.7.0",
+					userScope: { enabled: true, version: "4.7.0" },
+					projectScope: { enabled: true, version: "4.6.1" },
+				}),
+			),
+		);
+		expect(item.action).toBe("update");
+		expect(item.scopes).toEqual(["project"]);
+		expect(item.reason).toBe("behind");
+	});
+
+	test("the same masking under an EXACT pin is also caught", () => {
+		// The marketplace offers the pinned version here, so the target IS the pin
+		// and only the behind scope should move. (When the marketplace offers
+		// something else, every scope moves to that instead — see the
+		// "deliverable" suite.)
+		const [item] = planPluginUpdates(
+			{ "dev@magus": "4.6.1" },
+			catalog(
+				info({
+					id: "dev@magus",
+					version: "4.6.1",
+					userScope: { enabled: true, version: "4.6.1" },
+					projectScope: { enabled: true, version: "4.0.0" },
+				}),
+			),
+		);
+		expect(item.action).toBe("update");
+		expect(item.scopes).toEqual(["project"]);
+		expect(item.reason).toBe("behind");
+	});
+
+	test("an unreachable pin moves EVERY scope to the installable version", () => {
+		const [item] = planPluginUpdates(
+			{ "dev@magus": "4.6.1" },
+			catalog(
+				info({
+					id: "dev@magus",
+					version: "9.9.9",
+					userScope: { enabled: true, version: "4.6.1" },
+					projectScope: { enabled: true, version: "4.0.0" },
+				}),
+			),
+		);
+		expect(item.target).toBe("9.9.9");
+		expect(item.scopes).toEqual(["user", "project"]);
+		expect(item.reason).toBe("pin-undeliverable");
+	});
+
+	test("all scopes at the target is genuinely current", () => {
+		const [item] = planPluginUpdates(
+			{ "dev@magus": "latest" },
+			catalog(
+				info({
+					id: "dev@magus",
+					version: "4.7.0",
+					userScope: { enabled: true, version: "4.7.0" },
+					projectScope: { enabled: true, version: "4.7.0" },
+				}),
+			),
+		);
+		expect(item.action).toBe("current");
+		expect(item.reason).toBe("up-to-date");
+	});
+
+	// REVERSES an earlier decision, deliberately. This used to be `unknown` with
+	// a note reading "publishes no version", which put 278 of the 292 plugins in
+	// claude-plugins-official into a warning state that no action could ever
+	// clear: the marketplace does not publish versions, so re-running changes
+	// nothing and the row stays amber forever.
+	//
+	// The rule now is: if we cannot compare, assume what is installed is the
+	// latest. The machine code still says WHY (`no-published-version`), so the
+	// distinction is not lost — it just stops being reported as a problem. Do not
+	// "fix" this back without changing that rule first.
+	test("a catalog that declares no version leaves the install current", () => {
+		// dev@magus is IN the catalog with a null version — the declares-no-version
+		// case, not the withdrawn one.
+		const [item] = planPluginUpdates(
+			{ "dev@magus": "latest" },
+			catalog(
+				info({
+					id: "dev@magus",
+					version: null,
+					projectScope: { enabled: true, version: "4.6.1" },
+				}),
+			),
+		);
+		expect(item.action).toBe("current");
+		expect(item.reason).toBe("no-published-version");
+		// No note: there is nothing for the reader to do about it.
+		expect(item.note).toBeUndefined();
+		// And it is not confused with the withdrawn case, which is the next test.
+		expect(item.reason).not.toBe("not-offered");
+	});
+
+	test("an installed plugin ABSENT from every catalog is 'not offered'", () => {
+		// The genuinely withdrawn case: no catalog entry at all, the installed
+		// version known only from the registry.
+		const [item] = planPluginUpdates(
+			{ "withdrawn@magus": "latest" },
+			catalog(info({ id: "dev@magus", version: "4.6.1" })),
+		);
+		expect(item.action).toBe("unknown");
+		expect(item.note).toContain("not offered by any configured marketplace");
+		expect(item.reason).toBe("not-offered");
+	});
+});
+
+describe("planIsBehind — the --check gate", () => {
+	const skillRef = {
+		name: "release",
+		repo: "MadAppGang/magus",
+		path: "skills/release",
+	};
+
+	test("an already-installed skill does NOT fail the gate", () => {
+		// A skill ref carries no content hash, so it is re-fetched every run.
+		// Counting that as drift made --check exit 1 forever for any profile
+		// declaring a single skill — a gate that can never pass is no gate.
+		const p = plan({
+			skills: planSkillUpdates([skillRef], new Set(["release"])),
+		});
+		expect(planHasWork(p)).toBe(true);
+		expect(planIsBehind(p)).toBe(false);
+	});
+
+	test("a MISSING skill does fail the gate", () => {
+		const p = plan({ skills: planSkillUpdates([skillRef], new Set()) });
+		expect(planIsBehind(p)).toBe(true);
+	});
+
+	test("a present tool its installer calls current does NOT fail the gate, and is no work", () => {
+		const p = plan({
+			bins: planBinUpdates(
+				[{ name: "tmux", via: "brew", sources: [] }],
+				[toolFacts("tmux", { behind: false })],
+			),
+		});
+		expect(planHasWork(p)).toBe(false);
+		expect(planIsBehind(p)).toBe(false);
+	});
+
+	test("a tool its installer says is BEHIND does fail the gate", () => {
+		// Behaviour change, deliberate: "upgrade" used to mean "re-run the
+		// installer on a guess" and was excluded; it now means proven behind.
+		const p = plan({
+			bins: planBinUpdates(
+				[{ name: "claude-swap", via: "pip", sources: [] }],
+				[toolFacts("claude-swap", { behind: true, latest: "0.26.0" })],
+			),
+		});
+		expect(planIsBehind(p)).toBe(true);
+	});
+
+	test("an UNKNOWN tool does not fail the gate, and is no work", () => {
+		// Tool unknowns are often structural and permanent (another npm owns the
+		// file, go is absent) — counting them makes a gate that never passes.
+		const p = plan({
+			bins: planBinUpdates(
+				[{ name: "crush", via: "npm", sources: [] }],
+				[toolFacts("crush", { managed: false })],
+			),
+		});
+		expect(p.bins[0]!.action).toBe("unknown");
+		expect(planHasWork(p)).toBe(false);
+		expect(planIsBehind(p)).toBe(false);
+	});
+
+	test("a MISSING binary does fail the gate", () => {
+		const p = plan({
+			bins: planBinUpdates(
+				[{ name: "tmux-mcp", via: "bun", sources: [] }],
+				[toolFacts("tmux-mcp", { present: false, installed: null })],
+			),
+		});
+		expect(planIsBehind(p)).toBe(true);
+	});
+
+	test("an unverifiable plugin does NOT fail the gate, and is not applied", () => {
+		// Same rule as an unknown tool. The user's own profile declares 5 plugins
+		// whose marketplace publishes no version, so the old behaviour exited 1 on
+		// every run for ever — a gate that can never pass protects nothing. The
+		// count of unchecked items is printed beside the verdict instead.
+		const p = plan({
+			plugins: planPluginUpdates(
+				{ "dev@magus": "latest" },
+				catalog(
+					info({
+						id: "dev@magus",
+						version: "4.6.1",
+						projectScope: { enabled: true, version: "4.6.1" },
+						updateCheckFailed: true,
+					}),
+				),
+			),
+		});
+		expect(p.plugins[0]?.action).toBe("unknown");
+		expect(planIsBehind(p)).toBe(false);
+		expect(planWorkItems(p)).toEqual([]);
+	});
+
+	test("a plugin whose marketplace publishes no version does NOT fail the gate", () => {
+		// The real shape behind dry-run-1: listed, installed, no catalog version.
+		const p = plan({
+			plugins: planPluginUpdates(
+				{ "code-review@claude-plugins-official": "latest" },
+				catalog(
+					info({
+						id: "code-review@claude-plugins-official",
+						version: null,
+						projectScope: { enabled: true, version: "3ea32df27be7" },
+					}),
+				),
+			),
+		});
+		expect(p.plugins[0]?.reason).toBe("no-published-version");
+		expect(planIsBehind(p)).toBe(false);
+	});
+
+	test("a plugin that is behind, absent or content-stale still fails the gate", () => {
+		const behind = plan({
+			plugins: planPluginUpdates(
+				{ "dev@magus": "latest" },
+				catalog(
+					info({
+						id: "dev@magus",
+						version: "4.7.0",
+						projectScope: { enabled: true, version: "4.6.1" },
+					}),
+				),
+			),
+		});
+		expect(behind.plugins[0]?.action).toBe("update");
+		expect(planIsBehind(behind)).toBe(true);
+
+		const absent = plan({
+			plugins: planPluginUpdates(
+				{ "dev@magus": "latest" },
+				catalog(info({ id: "dev@magus", version: "4.7.0" })),
+			),
+		});
+		expect(absent.plugins[0]?.action).toBe("install");
+		expect(planIsBehind(absent)).toBe(true);
+
+		const stale = plan({
+			plugins: planPluginUpdates(
+				{ "dev@magus": "latest" },
+				catalog(
+					info({
+						id: "dev@magus",
+						version: "4.6.1",
+						projectScope: { enabled: true, version: "4.6.1" },
+						contentStale: true,
+					}),
+				),
+			),
+		});
+		expect(stale.plugins[0]?.action).toBe("repair");
+		expect(planIsBehind(stale)).toBe(true);
+	});
+
+	test("a fully current profile with skills and bins passes the gate", () => {
+		const p = plan({
+			plugins: planPluginUpdates(
+				{ "dev@magus": "latest" },
+				catalog(
+					info({
+						id: "dev@magus",
+						version: "4.7.0",
+						projectScope: { enabled: true, version: "4.7.0" },
+					}),
+				),
+			),
+			bins: planBinUpdates(
+				[{ name: "tmux-mcp", via: "bun", version: "1.0.0", sources: [] }],
+				[toolFacts("tmux-mcp", { installed: "1.0.0" })],
+			),
+			skills: planSkillUpdates([skillRef], new Set(["release"])),
+		});
+		expect(planIsBehind(p)).toBe(false);
+	});
+});
+
+describe("nothing ever plans a downgrade", () => {
+	// `claude plugin install` installs the newest published version and takes no
+	// version argument, so a downgrade is not a move this tool can perform.
+	// Planning one produces a step that runs, reports success, lands on the same
+	// version as before, and is replanned identically on the next run.
+
+	test("a scope AHEAD of the marketplace is left alone under an exact pin", () => {
+		const [item] = planPluginUpdates(
+			{ "dev@magus": "4.6.1" },
+			catalog(
+				info({
+					id: "dev@magus",
+					version: "9.9.9",
+					projectScope: { enabled: true, version: "10.0.0" },
+				}),
+			),
+		);
+		expect(item.action).toBe("current");
+		expect(item.scopes).toEqual([]);
+		expect(item.reason).toBe("pin-undeliverable");
+	});
+
+	test("an older pin with no catalog entry does not drag an install backwards", () => {
+		// available === null, so the pin is the only target on offer — and it is
+		// BELOW what is installed. Moving to it is neither possible nor wanted.
+		const [item] = planPluginUpdates(
+			{ "dev@magus": "4.6.1" },
+			catalog(
+				info({
+					id: "dev@magus",
+					version: null,
+					projectScope: { enabled: true, version: "5.0.0" },
+				}),
+			),
+		);
+		expect(item.action).toBe("current");
+		expect(item.scopes).toEqual([]);
+		expect(item.reason).toBe("up-to-date");
+	});
+
+	test("only the behind scope moves when one is ahead and one behind", () => {
+		const [item] = planPluginUpdates(
+			{ "dev@magus": "latest" },
+			catalog(
+				info({
+					id: "dev@magus",
+					version: "9.9.9",
+					userScope: { enabled: true, version: "10.0.0" },
+					projectScope: { enabled: true, version: "4.0.0" },
+				}),
+			),
+		);
+		expect(item.scopes).toEqual(["project"]);
+		expect(item.reason).toBe("behind");
+	});
+
+	test("scopesNeeding never returns a scope ahead of the target", () => {
+		const i = info({
+			id: "dev@magus",
+			userScope: { enabled: true, version: "10.0.0" },
+			projectScope: { enabled: true, version: "9.9.9" },
+			localScope: { enabled: true, version: "1.0.0" },
+		});
+		expect(scopesNeeding(i, "9.9.9")).toEqual(["local"]);
+	});
+});
+
+describe("scopesNeeding", () => {
+	test("returns every outdated scope, not just user", () => {
+		// Fixing only 'user' leaves the project row behind, so the same drift
+		// reappears on every run.
+		const i = info({
+			id: "dev@magus",
+			userScope: { enabled: true, version: "4.6.1" },
+			projectScope: { enabled: true, version: "4.6.1" },
+			localScope: { enabled: true, version: "4.7.0" },
+		});
+		expect(scopesNeeding(i, "4.7.0")).toEqual(["user", "project"]);
+	});
+
+	test("a scope already on the target is left alone", () => {
+		const i = info({
+			id: "dev@magus",
+			projectScope: { enabled: true, version: "4.7.0" },
+		});
+		expect(scopesNeeding(i, "4.7.0")).toEqual([]);
+	});
+});
+
+describe("planBinUpdates", () => {
+	const bin = (over: Partial<ResolvedBin>): ResolvedBin => ({
+		name: "tmux-mcp",
+		via: "bun",
+		sources: ["profile:test.cliTools"],
+		...over,
+	});
+
+	test("a missing binary is an install", () => {
+		const [item] = planBinUpdates(
+			[bin({})],
+			[toolFacts("tmux-mcp", { present: false, installed: null })],
+		);
+		expect(item).toMatchObject({ action: "install", reason: "absent" });
+	});
+
+	test("present, unpinned and CURRENT is current — the upgrade loop is gone", () => {
+		// This test used to read "present and unpinned is an upgrade — that is
+		// what 'update' means", and that was the defect: tmux, browser-use and
+		// mcp were current on the reporter's machine (brew / uv said so) and were
+		// "upgraded" on every run, forever.
+		const [item] = planBinUpdates(
+			[bin({ name: "tmux", via: "brew" })],
+			[toolFacts("tmux", { installed: "3.7c", behind: false })],
+		);
+		expect(item).toMatchObject({
+			action: "current",
+			reason: "up-to-date",
+			installed: "3.7c",
+			target: null,
+		});
+		expect(item.version).toBeUndefined();
+	});
+
+	test("present and unpinned is an upgrade ONLY when its installer says behind", () => {
+		const [item] = planBinUpdates(
+			[bin({ name: "claude-swap", via: "pip" })],
+			[toolFacts("claude-swap", { behind: true, latest: "0.26.0" })],
+		);
+		expect(item).toMatchObject({
+			action: "upgrade",
+			reason: "behind",
+			target: "0.26.0",
+		});
+	});
+
+	test("present and at its pin is current, keeping the pin", () => {
+		const [item] = planBinUpdates(
+			[bin({ version: "1.2.3" })],
+			[toolFacts("tmux-mcp", { installed: "1.2.3" })],
+		);
+		expect(item).toMatchObject({
+			action: "current",
+			reason: "at-pin",
+			version: "1.2.3",
+		});
+	});
+
+	test("a bin with no facts was never probed: unknown, with a note", () => {
+		const [item] = planBinUpdates([bin({})], []);
+		expect(item).toMatchObject({
+			action: "unknown",
+			reason: "not-probed",
+			note: "not probed",
+		});
+	});
+
+	test("the note is classifyTool's note, verbatim (the TUI shows the same string)", () => {
+		const f = toolFacts("crush", {
+			managed: false,
+			resolvedPath: "/n/crush.js",
+			owner: "npm (root /l)",
+		});
+		const [item] = planBinUpdates([bin({ name: "crush", via: "npm" })], [f]);
+		expect(item.note).toBe(
+			classifyTool(bin({ name: "crush", via: "npm" }), f).note,
+		);
+	});
+});
+
+describe("binNeedsWork — one predicate for apply, the meter and 'has work'", () => {
+	const actions: BinUpdateAction[] = [
+		"install",
+		"upgrade",
+		"current",
+		"unknown",
+	];
+	const itemFor = (action: BinUpdateAction): BinUpdateItem => ({
+		name: `t-${action}`,
+		action,
+		reason: "not-probed",
+		installed: null,
+		latest: null,
+		target: null,
+		sources: [],
+	});
+
+	test("install and upgrade are work; current and unknown are not", () => {
+		expect(actions.map((a) => binNeedsWork(itemFor(a)))).toEqual([
+			true,
+			true,
+			false,
+			false,
+		]);
+	});
+
+	test("applyBins, planWorkItems and planHasWork agree for every action", async () => {
+		for (const action of actions) {
+			const item = itemFor(action);
+			const p = plan({
+				bins: [item],
+				binSpecs: new Map([
+					[item.name, { name: item.name, via: "bun", sources: [] }],
+				]),
+			});
+			const ran: string[] = [];
+			await applyBins(
+				p,
+				undefined,
+				async (c) => {
+					ran.push(c.cmd);
+					return true;
+				},
+				// Read-back seam: never the real PATH in a unit test.
+				async (s) => toolFacts(s.name, { installed: "2.0.0" }),
+			);
+			const expected = binNeedsWork(item);
+			expect(ran.length > 0).toBe(expected);
+			expect(planWorkItems(p).includes(item.name)).toBe(expected);
+			expect(planHasWork(p)).toBe(expected);
+		}
+	});
+
+	test("an upgrade TO the pin runs the pin command, not the upgrade command", () => {
+		const spec: ResolvedBin = {
+			name: "mnemex",
+			via: "bun",
+			version: "1.0.0",
+			sources: [],
+		};
+		expect(
+			binCommandFor(
+				{ ...itemFor("upgrade"), name: "mnemex", target: "1.0.0" },
+				spec,
+			),
+		).toEqual({ cmd: "bun", args: ["install", "-g", "mnemex@1.0.0"] });
+		expect(
+			binCommandFor(
+				{ ...itemFor("upgrade"), target: "2.0.0" },
+				{
+					...spec,
+					version: undefined,
+				},
+			),
+		).toEqual({ cmd: "bun", args: ["install", "-g", "mnemex@latest"] });
+		expect(binCommandFor(itemFor("unknown"), spec)).toBeNull();
+	});
+});
+
+describe("planSkillUpdates", () => {
+	const ref = {
+		name: "release",
+		repo: "MadAppGang/magus",
+		path: "skills/release",
+	};
+
+	test("an uninstalled skill is an install", () => {
+		expect(planSkillUpdates([ref], new Set())[0]!.action).toBe("install");
+	});
+
+	test("an installed skill is refreshed, since refs carry no content hash", () => {
+		expect(planSkillUpdates([ref], new Set(["release"]))[0]!.action).toBe(
+			"refresh",
+		);
+	});
+});
+
+describe("planHasWork / summarizePlan", () => {
+	test("an all-current plan has no work", () => {
+		const p = plan({
+			plugins: planPluginUpdates(
+				{ "dev@magus": "latest" },
+				catalog(
+					info({
+						id: "dev@magus",
+						version: "4.7.0",
+						projectScope: { enabled: true, version: "4.7.0" },
+					}),
+				),
+			),
+		});
+		expect(planHasWork(p)).toBe(false);
+		expect(summarizePlan(p).current).toBe(1);
+	});
+
+	test("counts split installs from updates across plugins and bins", () => {
+		const p = plan({
+			plugins: planPluginUpdates(
+				{ "a@magus": "latest", "b@magus": "latest" },
+				catalog(
+					info({ id: "a@magus", version: "1.0.0" }),
+					info({
+						id: "b@magus",
+						version: "2.0.0",
+						projectScope: { enabled: true, version: "1.0.0" },
+					}),
+				),
+			),
+			bins: planBinUpdates(
+				[{ name: "tmux-mcp", via: "bun", sources: [] }],
+				[toolFacts("tmux-mcp", { installed: "1.0.0", latest: "1.1.0" })],
+			),
+		});
+		expect(summarizePlan(p)).toMatchObject({ installed: 1, updated: 2 });
+	});
+
+	test("unknown splits into plugins and tools, and the total is their sum", () => {
+		const p = plan({
+			plugins: planPluginUpdates(
+				// `a@magus` is an ORPHAN — no marketplace offers it — which is the
+				// one remaining way a plugin is genuinely `unknown`. A catalog that
+				// merely declares no version is `current` now, so using that here
+				// would leave `unknownPlugins` at 0 and the sum would hold
+				// trivially, testing nothing.
+				{ "a@magus": "latest" },
+				catalog(orphan("a@magus", "1.0.0")),
+			),
+			bins: planBinUpdates(
+				[
+					{ name: "crush", via: "npm", sources: [] },
+					{ name: "claude", via: "npm", sources: [] },
+					{ name: "tmux", via: "brew", sources: [] },
+				],
+				[
+					toolFacts("crush", { managed: false }),
+					toolFacts("claude", { managed: false }),
+					toolFacts("tmux", { behind: false }),
+				],
+			),
+		});
+		expect(summarizePlan(p)).toMatchObject({
+			unknownPlugins: 1,
+			unknownTools: 2,
+			unknown: 3,
+			current: 1,
+		});
+	});
+});
+
+// ── The classifier: rules the TUI and CLI now share ─────────────────────────
+
+/**
+ * An orphan as `getAvailablePlugins` builds one: installed, published by no
+ * marketplace we read, and — the trap — `version` filled in from its own
+ * installed version, so a naive compare finds them equal.
+ */
+function orphan(
+	id: string,
+	installedVersion: string,
+	over: Partial<PluginInfo> = {},
+): PluginInfo {
+	return info({
+		id,
+		version: installedVersion,
+		installedVersion,
+		isOrphaned: true,
+		projectScope: { enabled: true, version: installedVersion },
+		...over,
+	});
+}
+
+describe("classifyPlugin — an orphan is never 'current'", () => {
+	test("REGRESSION: an orphan used to plan current against its own version", () => {
+		// Before: `catalog.has(id)` was true for an orphan, its `version` equalled
+		// its installed version, and the plan said `current` while the TUI drew
+		// the same row red as "deprecated".
+		const [item] = planPluginUpdates(
+			{ "seo@magus": "latest" },
+			catalog(
+				orphan("seo@magus", "1.8.0"),
+				info({ id: "dev@magus", version: "4.7.0" }),
+			),
+		);
+		expect(item.action).toBe("unknown");
+		expect(item.action).not.toBe("current");
+		expect(item.available).toBeNull();
+		expect(item.target).toBeNull();
+		expect(item.scopes).toEqual([]);
+	});
+
+	// `moved` is GONE, and `movedTo` with it. It was inferred from a bare name
+	// match: a plugin published to two marketplaces — claudish is — reported
+	// "moved → magus" when nothing had moved and both copies were installed.
+	// The inference cannot tell a move from a dual publication, so it is not made
+	// at all. An orphan is `not-offered`, which is a fact rather than a guess.
+	test("an orphan is 'not offered', and never guesses where it went", () => {
+		const [item] = planPluginUpdates(
+			{ "seo@magus": "latest" },
+			catalog(
+				orphan("seo@magus", "1.8.0"),
+				info({ id: "dev@magus", version: "4.7.0" }),
+			),
+		);
+		expect(item).toMatchObject({
+			action: "unknown",
+			reason: "not-offered",
+		});
+		expect(item.note).not.toMatch(/moved/i);
+	});
+
+	test("an orphan whose marketplace we DID read is 'not offered'", () => {
+		const [item] = planPluginUpdates(
+			{ "seo@magus": "latest" },
+			catalog(
+				orphan("seo@magus", "1.8.0"),
+				info({ id: "dev@magus", version: "4.7.0" }),
+			),
+		);
+		expect(item).toMatchObject({
+			action: "unknown",
+			reason: "not-offered",
+			note: "not offered by any configured marketplace",
+		});
+	});
+
+	test("an orphan whose marketplace contributed nothing is 'marketplace-unread'", () => {
+		// No listed id from @gone — we never read that catalog, so its absence is
+		// not evidence it was dropped. Claiming "not offered" would be a guess.
+		const [item] = planPluginUpdates(
+			{ "thing@gone": "latest" },
+			catalog(
+				orphan("thing@gone", "2.0.0"),
+				info({ id: "dev@magus", version: "4.7.0" }),
+			),
+		);
+		expect(item).toMatchObject({
+			action: "unknown",
+			reason: "marketplace-unread",
+			note: "its marketplace gone was not read, so whether it still offers this plugin is unknown",
+		});
+	});
+
+	test("another ORPHAN from the same marketplace is not proof we read it", () => {
+		// Two orphans under @gone used to make `marketplaceIsKnown` true for each
+		// other. Neither is listed, so neither proves anything.
+		const [item] = planPluginUpdates(
+			{ "thing@gone": "latest" },
+			catalog(orphan("thing@gone", "2.0.0"), orphan("other@gone", "1.0.0")),
+		);
+		expect(item.reason).toBe("marketplace-unread");
+	});
+
+	test("an orphan is unknown under an exact pin too", () => {
+		const [item] = planPluginUpdates(
+			{ "seo@magus": "1.8.0" },
+			catalog(
+				orphan("seo@magus", "1.8.0"),
+				info({ id: "dev@magus", version: "4.7.0" }),
+			),
+		);
+		expect(item.action).toBe("unknown");
+	});
+});
+
+// REVERSES F3, deliberately. `unorderable` is gone as a state: when two
+// versions cannot be ordered we assume what is installed IS the latest, rather
+// than raising a warning nothing can clear.
+//
+// F3's premise was that "cannot compare" might hide a plugin that is behind.
+// True, but the cost was paid on every run by rows that were fine — an install
+// recorded as a commit sha can never be ordered against a semver pin, so the
+// warning was permanent and unactionable. Do not restore `unorderable` without
+// changing that rule first.
+describe("classifyPlugin — an unorderable version is assumed current", () => {
+	test("a pinned plugin whose install cannot be ordered is current", () => {
+		const [item] = planPluginUpdates(
+			{ "playground@official": "7.3.0" },
+			catalog(
+				info({
+					id: "playground@official",
+					version: "7.3.0",
+					projectScope: { enabled: true, version: "unknown" },
+				}),
+			),
+		);
+		expect(item.action).toBe("current");
+		expect(item.reason).not.toBe("unorderable");
+		// Nothing is planned against it, which is the part F3 actually protected.
+		expect(item.scopes).toEqual([]);
+	});
+
+	test("no published version, under an exact pin, is also current", () => {
+		const [item] = planPluginUpdates(
+			{ "playground@official": "7.3.0" },
+			catalog(
+				info({
+					id: "playground@official",
+					version: null,
+					projectScope: { enabled: true, version: "3ea32df27be7" },
+				}),
+			),
+		);
+		expect(item.action).toBe("current");
+		expect(item.note).toBeUndefined();
+		// The exact-pin path reports `up-to-date` here where the "latest" path
+		// reports `no-published-version` — same verdict, different machine code.
+		// Asserted as observed rather than as preferred: nothing renders the two
+		// differently today, and forcing them to agree is a change to the
+		// classifier, not to this test.
+		expect(item.reason).toBe("up-to-date");
+	});
+
+	test("a scope that IS behind still wins: it is planned, not hidden", () => {
+		const [item] = planPluginUpdates(
+			{ "dev@magus": "4.7.0" },
+			catalog(
+				info({
+					id: "dev@magus",
+					version: "4.7.0",
+					userScope: { enabled: true, version: "unknown" },
+					projectScope: { enabled: true, version: "4.6.1" },
+				}),
+			),
+		);
+		expect(item).toMatchObject({ action: "update", scopes: ["project"] });
+	});
+});
+
+describe("classifyPlugin — install reasons", () => {
+	test("enabled in settings with no files anywhere says so", () => {
+		const [item] = planPluginUpdates(
+			{ "dev@magus": "latest" },
+			catalog(
+				info({
+					id: "dev@magus",
+					version: "4.7.0",
+					projectScope: { enabled: true },
+				}),
+			),
+		);
+		expect(item).toMatchObject({
+			action: "install",
+			reason: "enabled-not-installed",
+			note: "enabled in settings, but no files on disk",
+		});
+	});
+
+	test("a plain absence carries no note", () => {
+		const [item] = planPluginUpdates(
+			{ "dev@magus": "latest" },
+			catalog(info({ id: "dev@magus", version: "4.7.0" })),
+		);
+		expect(item.reason).toBe("absent");
+		expect(item.note).toBeUndefined();
+	});
+});
+
+describe("classifyPlugin — beforeVersions records every installed scope", () => {
+	test("each installed scope's version, and nothing for an absent one", () => {
+		const [item] = planPluginUpdates(
+			{ "dev@magus": "latest" },
+			catalog(
+				info({
+					id: "dev@magus",
+					version: "4.7.0",
+					userScope: { enabled: true, version: "4.6.0" },
+					projectScope: { enabled: true, version: "4.6.1" },
+					localScope: { enabled: true },
+				}),
+			),
+		);
+		expect(item.beforeVersions).toEqual({ user: "4.6.0", project: "4.6.1" });
+	});
+
+	test("an uninstalled plugin has none", () => {
+		const [item] = planPluginUpdates(
+			{ "dev@magus": "latest" },
+			catalog(info({ id: "dev@magus", version: "4.7.0" })),
+		);
+		expect(item.beforeVersions).toEqual({});
+	});
+});
+
+describe("indexCatalog", () => {
+	const idx = indexCatalog([
+		info({ id: "dev@magus", version: "4.7.0" }),
+		orphan("seo@magus", "1.8.0"),
+		orphan("thing@gone", "2.0.0"),
+	]);
+
+	test("isListed excludes orphans", () => {
+		expect(idx.isListed("dev@magus")).toBe(true);
+		expect(idx.isListed("seo@magus")).toBe(false);
+		expect(idx.isListed("absent@magus")).toBe(false);
+		// Still reachable by id — the classifier needs its scopes.
+		expect(idx.get("seo@magus")?.isOrphaned).toBe(true);
+	});
+
+	test("marketplaceIsKnown counts OTHER listed ids only", () => {
+		expect(idx.marketplaceIsKnown("seo@magus")).toBe(true); // dev@magus is listed
+		expect(idx.marketplaceIsKnown("absent@magus")).toBe(true);
+		// dev@magus is the only listed @magus id — itself does not count.
+		expect(idx.marketplaceIsKnown("dev@magus")).toBe(false);
+		// Only an orphan there.
+		expect(idx.marketplaceIsKnown("other@gone")).toBe(false);
+		expect(idx.marketplaceIsKnown("no-marketplace")).toBe(false);
+		expect(idx.marketplaceIsKnown("trailing@")).toBe(false);
+	});
+
+	test("a Map and an array index identically", () => {
+		const list = [
+			info({ id: "a@m", version: "1.0.0" }),
+			info({ id: "b@m", version: "1.0.0" }),
+		];
+		const fromMap = indexCatalog(catalog(...list));
+		const fromArray = indexCatalog(list);
+		for (const id of ["a@m", "b@m", "c@m"]) {
+			expect(fromMap.isListed(id)).toBe(fromArray.isListed(id));
+			expect(fromMap.marketplaceIsKnown(id)).toBe(
+				fromArray.marketplaceIsKnown(id),
+			);
+		}
+	});
+});
+
+describe("classifyPlugin and planPluginUpdates are the same function", () => {
+	test("planPluginUpdates is classifyPlugin over each pin, sorted", () => {
+		const cat = catalog(
+			info({
+				id: "b@magus",
+				version: "2.0.0",
+				projectScope: { enabled: true, version: "1.0.0" },
+			}),
+			info({ id: "a@magus", version: "1.0.0" }),
+		);
+		const pins = { "b@magus": "latest", "a@magus": "1.0.0" };
+		const idx = indexCatalog(cat);
+		expect(planPluginUpdates(pins, cat)).toEqual([
+			classifyPlugin("a@magus", "1.0.0", idx),
+			classifyPlugin("b@magus", "latest", idx),
+		]);
+	});
+});
+
+describe("pinForRow — which pin a TUI row is judged against", () => {
+	test("the profile's pin wins, exact or latest", () => {
+		const i = info({
+			id: "dev@magus",
+			projectScope: { enabled: true, version: "1.0.0" },
+		});
+		expect(pinForRow(i, { "dev@magus": "4.6.1" })).toBe("4.6.1");
+		expect(pinForRow(i, { "dev@magus": "latest" })).toBe("latest");
+	});
+
+	test("a declared plugin gets its pin even when it is installed nowhere", () => {
+		expect(
+			pinForRow(info({ id: "dev@magus" }), { "dev@magus": "latest" }),
+		).toBe("latest");
+	});
+
+	test("undeclared but installed in any scope is judged against latest", () => {
+		for (const scope of ["userScope", "projectScope", "localScope"] as const) {
+			const i = info({
+				id: "dev@magus",
+				[scope]: { enabled: false, version: "1.0.0" },
+			});
+			expect(pinForRow(i, {})).toBe("latest");
+		}
+	});
+
+	test("undeclared, enabled but not installed is judged against latest", () => {
+		expect(
+			pinForRow(info({ id: "dev@magus", localScope: { enabled: true } }), {}),
+		).toBe("latest");
+	});
+
+	test("undeclared and neither installed nor enabled gets NO status", () => {
+		// A catalog entry the user is only browsing. `install` would claim the
+		// profile wants it, which nothing says.
+		expect(
+			pinForRow(info({ id: "dev@magus", version: "1.0.0" }), {}),
+		).toBeNull();
+	});
+
+	test("an inherited key from Object.prototype is not a pin", () => {
+		expect(
+			pinForRow(info({ id: "toString", version: "1.0.0" }), {}),
+		).toBeNull();
+	});
+});
+
+describe("classifyPluginRows", () => {
+	test("one status per row with a pin; browse-only rows are absent", () => {
+		const rows = [
+			info({ id: "declared@magus", version: "1.0.0" }),
+			info({
+				id: "installed@magus",
+				version: "2.0.0",
+				projectScope: { enabled: true, version: "1.0.0" },
+			}),
+			info({ id: "browse@magus", version: "3.0.0" }),
+		];
+		const statuses = classifyPluginRows(rows, { "declared@magus": "latest" });
+		expect([...statuses.keys()].sort()).toEqual([
+			"declared@magus",
+			"installed@magus",
+		]);
+		expect(statuses.get("declared@magus")).toMatchObject({
+			action: "install",
+			reason: "absent",
+		});
+		expect(statuses.get("installed@magus")).toMatchObject({
+			action: "update",
+			reason: "behind",
+		});
+		expect(statuses.has("browse@magus")).toBe(false);
+	});
+
+	test("a declared row gets exactly what the CLI plans for it", () => {
+		const rows = [
+			info({
+				id: "dev@magus",
+				version: "4.7.0",
+				projectScope: { enabled: true, version: "4.6.1" },
+			}),
+			info({ id: "terminal@magus", version: "5.0.1" }),
+		];
+		const pins = { "dev@magus": "4.6.1", "terminal@magus": "latest" };
+		const cli = planPluginUpdates(pins, catalog(...rows));
+		const tui = classifyPluginRows(rows, pins);
+		for (const item of cli) expect(tui.get(item.pluginId)).toEqual(item);
+	});
+});
+
+describe("countPluginStates", () => {
+	test("counts every action, including zeros", () => {
+		const items = [
+			{ action: "install" },
+			{ action: "update" },
+			{ action: "update" },
+			{ action: "repair" },
+			{ action: "unknown" },
+		] as PluginUpdateItem[];
+		expect(countPluginStates(items)).toEqual({
+			install: 1,
+			update: 2,
+			repair: 1,
+			current: 0,
+			unknown: 1,
+		});
+	});
+
+	test("accepts a Map's values directly", () => {
+		const m = new Map([["a", { action: "current" } as PluginUpdateItem]]);
+		expect(countPluginStates(m.values()).current).toBe(1);
+	});
+});
+
+describe("scopeIsBehind — the scope picker's one question", () => {
+	const status = (over: Partial<PluginUpdateItem>) =>
+		({ action: "update", scopes: ["project"], ...over }) as PluginUpdateItem;
+
+	test("an update touching the scope says yes", () => {
+		expect(scopeIsBehind(status({}), "project")).toBe(true);
+	});
+
+	test("an update touching OTHER scopes says no for this one", () => {
+		expect(scopeIsBehind(status({}), "user")).toBe(false);
+	});
+
+	test("repair, unknown, current and install all say no", () => {
+		// `claude plugin install` on the same version is a no-op, so a repair
+		// scope must not be offered "update".
+		for (const action of ["repair", "unknown", "current", "install"] as const) {
+			expect(scopeIsBehind(status({ action }), "project")).toBe(false);
+		}
+	});
+
+	test("no status says no", () => {
+		expect(scopeIsBehind(null, "project")).toBe(false);
+		expect(scopeIsBehind(undefined, "project")).toBe(false);
+	});
+});