claudeup 6.5.0 → 6.6.0

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

@@ -1,13 +1,28 @@
 import { describe, expect, test } from "bun:test";
-import type { BinCheckResult } from "../services/doctor-bins.js";
 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";
@@ -30,6 +45,21 @@ 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",
@@ -53,12 +83,14 @@ describe("planPluginUpdates — the profile declares it, the machine lacks it",
 			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", () => {
@@ -67,6 +99,7 @@ describe("planPluginUpdates — the profile declares it, the machine lacks it",
 			catalog(info({ id: "dev@magus", version: "4.7.0" })),
 		);
 		expect(item.target).toBe("4.6.1");
+		expect(item.reason).toBe("absent");
 	});
 });
 
@@ -88,6 +121,7 @@ describe("planPluginUpdates — advancing a 'latest' pin", () => {
 			target: "4.7.0",
 			scopes: ["project"],
 		});
+		expect(item.reason).toBe("behind");
 	});
 
 	test("the same version is current, with no scopes to touch", () => {
@@ -102,6 +136,7 @@ describe("planPluginUpdates — advancing a 'latest' pin", () => {
 			),
 		);
 		expect(item).toMatchObject({ action: "current", scopes: [] });
+		expect(item.reason).toBe("up-to-date");
 	});
 
 	test("an older catalog version does not downgrade a 'latest' pin", () => {
@@ -116,6 +151,7 @@ describe("planPluginUpdates — advancing a 'latest' pin", () => {
 			),
 		);
 		expect(item.action).toBe("current");
+		expect(item.reason).toBe("up-to-date");
 	});
 });
 
@@ -142,9 +178,13 @@ describe("planPluginUpdates — a failed check is never 'up to date'", () => {
 		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 keeps --check failing", () => {
+	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" },
@@ -159,6 +199,7 @@ describe("planPluginUpdates — a failed check is never 'up to date'", () => {
 			),
 		});
 		expect(planHasWork(p)).toBe(true);
+		expect(planIsBehind(p)).toBe(false);
 	});
 });
 
@@ -178,6 +219,7 @@ describe("planPluginUpdates — content drift", () => {
 		);
 		expect(item.action).toBe("repair");
 		expect(item.scopes).toEqual(["user", "project"]);
+		expect(item.reason).toBe("content-stale");
 	});
 });
 
@@ -199,6 +241,7 @@ describe("planPluginUpdates — an exact pin plans against what is deliverable",
 			),
 		);
 		expect(item).toMatchObject({ action: "update", target: "9.9.9" });
+		expect(item.reason).toBe("pin-undeliverable");
 	});
 
 	test("an unreachable pin is NOTED, never silently abandoned", () => {
@@ -215,6 +258,7 @@ describe("planPluginUpdates — an exact pin plans against what is deliverable",
 		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", () => {
@@ -233,6 +277,7 @@ describe("planPluginUpdates — an exact pin plans against what is deliverable",
 		);
 		expect(item.action).toBe("current");
 		expect(item.scopes).toEqual([]);
+		expect(item.reason).toBe("pin-undeliverable");
 	});
 
 	test("an unsatisfiable pin does not fail --check forever", () => {
@@ -264,6 +309,7 @@ describe("planPluginUpdates — an exact pin plans against what is deliverable",
 		);
 		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", () => {
@@ -278,6 +324,7 @@ describe("planPluginUpdates — an exact pin plans against what is deliverable",
 			),
 		);
 		expect(item.target).toBe("4.6.1");
+		expect(item.reason).toBe("behind");
 	});
 });
 
@@ -299,6 +346,7 @@ describe("per-scope decisions — a stale scope is never masked", () => {
 		);
 		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", () => {
@@ -319,6 +367,7 @@ describe("per-scope decisions — a stale scope is never masked", () => {
 		);
 		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", () => {
@@ -335,6 +384,7 @@ describe("per-scope decisions — a stale scope is never masked", () => {
 		);
 		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", () => {
@@ -350,9 +400,14 @@ describe("per-scope decisions — a stale scope is never masked", () => {
 			),
 		);
 		expect(item.action).toBe("current");
+		expect(item.reason).toBe("up-to-date");
 	});
 
-	test("an installed plugin no marketplace offers is 'unknown', not 'current'", () => {
+	test("an installed plugin whose catalog declares no version is 'unknown'", () => {
+		// This fixture puts dev@magus IN the catalog with a null version, so it is
+		// the declares-no-version case, not the withdrawn one — the assertion used
+		// to say "not offered", which is what conflated them. 278 of the 292
+		// plugins in claude-plugins-official are in exactly this state.
 		const [item] = planPluginUpdates(
 			{ "dev@magus": "latest" },
 			catalog(
@@ -364,7 +419,20 @@ describe("per-scope decisions — a stale scope is never masked", () => {
 			),
 		);
 		expect(item.action).toBe("unknown");
-		expect(item.note).toContain("not offered");
+		expect(item.note).toContain("publishes no version");
+		expect(item.reason).toBe("no-published-version");
+	});
+
+	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");
 	});
 });
 
@@ -391,16 +459,40 @@ describe("planIsBehind — the --check gate", () => {
 		expect(planIsBehind(p)).toBe(true);
 	});
 
-	test("a present unpinned binary does NOT fail the gate", () => {
-		// There is no version probe for a binary, only present/absent. "Upgrade"
-		// is best-effort advancement, not evidence anything is behind.
+	test("a present tool its installer calls current does NOT fail the gate, and is no work", () => {
 		const p = plan({
 			bins: planBinUpdates(
-				[{ name: "tmux-mcp", via: "bun", sources: [] }],
-				[{ name: "tmux-mcp", present: true, installCommand: "", sources: [] }],
+				[{ name: "tmux", via: "brew", sources: [] }],
+				[toolFacts("tmux", { behind: false })],
 			),
 		});
-		expect(planHasWork(p)).toBe(true);
+		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);
 	});
 
@@ -408,13 +500,17 @@ describe("planIsBehind — the --check gate", () => {
 		const p = plan({
 			bins: planBinUpdates(
 				[{ name: "tmux-mcp", via: "bun", sources: [] }],
-				[{ name: "tmux-mcp", present: false, installCommand: "", sources: [] }],
+				[toolFacts("tmux-mcp", { present: false, installed: null })],
 			),
 		});
 		expect(planIsBehind(p)).toBe(true);
 	});
 
-	test("an unverifiable plugin still fails the gate", () => {
+	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" },
@@ -428,7 +524,69 @@ describe("planIsBehind — the --check gate", () => {
 				),
 			),
 		});
-		expect(planIsBehind(p)).toBe(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", () => {
@@ -445,7 +603,7 @@ describe("planIsBehind — the --check gate", () => {
 			),
 			bins: planBinUpdates(
 				[{ name: "tmux-mcp", via: "bun", version: "1.0.0", sources: [] }],
-				[{ name: "tmux-mcp", present: true, installCommand: "", sources: [] }],
+				[toolFacts("tmux-mcp", { installed: "1.0.0" })],
 			),
 			skills: planSkillUpdates([skillRef], new Set(["release"])),
 		});
@@ -472,6 +630,7 @@ describe("nothing ever plans a downgrade", () => {
 		);
 		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", () => {
@@ -489,6 +648,7 @@ describe("nothing ever plans a downgrade", () => {
 		);
 		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", () => {
@@ -504,6 +664,7 @@ describe("nothing ever plans a downgrade", () => {
 			),
 		);
 		expect(item.scopes).toEqual(["project"]);
+		expect(item.reason).toBe("behind");
 	});
 
 	test("scopesNeeding never returns a scope ahead of the target", () => {
@@ -519,8 +680,8 @@ describe("nothing ever plans a downgrade", () => {
 
 describe("scopesNeeding", () => {
 	test("returns every outdated scope, not just user", () => {
-		// The prerunner's original bug: it fixed 'user' and left the project row
-		// behind, so the same drift reappeared on every run.
+		// 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" },
@@ -546,29 +707,155 @@ describe("planBinUpdates", () => {
 		sources: ["profile:test.cliTools"],
 		...over,
 	});
-	const check = (name: string, present: boolean): BinCheckResult => ({
-		name,
-		present,
-		installCommand: "",
-		sources: [],
-	});
 
 	test("a missing binary is an install", () => {
-		const [item] = planBinUpdates([bin({})], [check("tmux-mcp", false)]);
-		expect(item.action).toBe("install");
+		const [item] = planBinUpdates(
+			[bin({})],
+			[toolFacts("tmux-mcp", { present: false, installed: null })],
+		);
+		expect(item).toMatchObject({ action: "install", reason: "absent" });
 	});
 
-	test("present and unpinned is an upgrade — that is what 'update' means", () => {
-		const [item] = planBinUpdates([bin({})], [check("tmux-mcp", true)]);
-		expect(item.action).toBe("upgrade");
+	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 pinned is left alone — there is nothing to advance to", () => {
+	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" })],
-			[check("tmux-mcp", true)],
+			[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,
 		);
-		expect(item).toMatchObject({ action: "current", version: "1.2.3" });
+	});
+});
+
+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();
 	});
 });
 
@@ -623,9 +910,464 @@ describe("planHasWork / summarizePlan", () => {
 			),
 			bins: planBinUpdates(
 				[{ name: "tmux-mcp", via: "bun", sources: [] }],
-				[{ name: "tmux-mcp", present: true, installCommand: "", 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": "latest" },
+				catalog(
+					info({
+						id: "a@magus",
+						version: null,
+						projectScope: { enabled: true, version: "abc123" },
+					}),
+				),
+			),
+			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([]);
+	});
+
+	test("an orphan another marketplace publishes is 'moved', naming it", () => {
+		const [item] = planPluginUpdates(
+			{ "seo@magus": "latest" },
+			catalog(
+				orphan("seo@magus", "1.8.0", { movedTo: "magus-marketing" }),
+				info({ id: "dev@magus", version: "4.7.0" }),
+			),
+		);
+		expect(item).toMatchObject({
+			action: "unknown",
+			reason: "moved",
+			note: "moved to magus-marketing",
+		});
+	});
+
+	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");
+	});
+});
+
+describe("classifyPlugin — an exact pin that cannot be ordered is unknown (F3)", () => {
+	test("REGRESSION: a pinned plugin at an unorderable version used to be current", () => {
+		// The "latest" path already refused this; the exact-pin path did not.
+		const [item] = planPluginUpdates(
+			{ "playground@official": "7.3.0" },
+			catalog(
+				info({
+					id: "playground@official",
+					version: "7.3.0",
+					projectScope: { enabled: true, version: "unknown" },
+				}),
+			),
+		);
+		expect(item).toMatchObject({
+			action: "unknown",
+			reason: "unorderable",
+			target: null,
+			scopes: [],
+			note: "installed version cannot be compared with the published 7.3.0",
+		});
+	});
+
+	test("with no published version the note names the pin instead", () => {
+		const [item] = planPluginUpdates(
+			{ "playground@official": "7.3.0" },
+			catalog(
+				info({
+					id: "playground@official",
+					version: null,
+					projectScope: { enabled: true, version: "3ea32df27be7" },
+				}),
+			),
+		);
+		expect(item).toMatchObject({
+			action: "unknown",
+			reason: "unorderable",
+			note: "installed version cannot be compared with the pin 7.3.0",
+		});
+	});
+
+	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);
+	});
 });