magus-cli 7.7.0 → 7.8.0

package/src/__tests__/blind-780-review2.test.ts

@@ -0,0 +1,1203 @@
+/**
+ * magus 7.8.0 QA, review round 2 — failure reporting and removal follow-ups.
+ *
+ * Written blind from qa-spec-review2.md (U1–U13) and the exported declarations
+ * of ui/adapters/{failureReport,startupReports,pluginsAdapter}.ts,
+ * services/{update-engine,update-plan,resolver,plugin-manager}.ts,
+ * cli/doctor.ts and ui/components/modals/FailureListModal.tsx, emitted with
+ * `tsc --emitDeclarationOnly`. No function body was read.
+ *
+ * Coverage map (requirement → describe block):
+ *   U1  ran, changed nothing → "<name> was not updated", no fix     → "U1"
+ *   U2  profile gate problem → subject file/profile, fix by hand    → "U2"
+ *   U3  activation: blocked, not downloaded, skill failed, conflict → "U3"
+ *   U4  stale repairs: "N plugins were not repaired", failed only   → "U4"
+ *   U5  marketplace refresh failure → subject is the marketplace    → "U5"
+ *   U6  grouping: same reason one row, versions → nouns, exceptions → "U6"
+ *   U7  claude not on PATH → install fix once, not in the reason    → "U7"
+ *   U8  version did not download → exact reason + `Run magus install`→ "U8"
+ *   U9  exception text: no `Command failed:`, no claude binary path → "U9"
+ *   U10 remove → forgetVersion only at scopes actually removed      → "U10"
+ *   U11 doctor: a bare installedPluginVersions claim is not a load  → "U11"
+ *   U12 a deprecated plugin still required is never planned remove  → "U12"
+ *   U13 popup caps rows to the terminal height, ends `+N more`      → "U13"
+ */
+
+import { describe, expect, test } from "bun:test";
+import { testRender } from "@opentui/react/test-utils";
+import { act, createElement } from "react";
+import { findPluginLoadProblems } from "../cli/doctor.js";
+import {
+	type PluginScope,
+	claudeFailureMessage,
+} from "../services/claude-cli.js";
+import {
+	type StaleLoadRepairResult,
+	notDownloadedReason,
+} from "../services/claude-settings.js";
+import type { PluginInfo } from "../services/plugin-manager.js";
+import type { ActivationResult } from "../services/profile-activate.js";
+import { requiredByHere } from "../services/resolver.js";
+import {
+	type ApplyReporter,
+	type PluginApplyDeps,
+	applyPlugins,
+	describeLoadNotForward,
+} from "../services/update-engine.js";
+import {
+	type PluginUpdateAction,
+	type PluginUpdateItem,
+	planPluginUpdates,
+} from "../services/update-plan.js";
+import {
+	type PluginFailure,
+	exceptionReason,
+	failureReasons,
+	pluginFailureReport,
+	reasonWithoutVersions,
+} from "../ui/adapters/pluginsAdapter.js";
+import {
+	activationFailureReport,
+	marketplaceRefreshReport,
+	profileProblemRow,
+	profileProblemsReport,
+	staleRepairReport,
+} from "../ui/adapters/startupReports.js";
+import {
+	FailureListModal,
+	visibleFailureRows,
+} from "../ui/components/modals/FailureListModal.js";
+import type { FailureReport, FailureRow } from "../ui/state/types.js";
+
+const PROJECT = "/tmp/blind-780-review2-project";
+
+/** Spec-quoted fix lines. */
+const INSTALL_CLAUDE =
+	"Install Claude Code: npm install -g @anthropic-ai/claude-code";
+const RUN_MAGUS_INSTALL = "Run magus install";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function updateItem(
+	pluginId: string,
+	over: Partial<PluginUpdateItem> = {},
+): PluginUpdateItem {
+	return {
+		pluginId,
+		pinned: "latest",
+		installed: "1.0.0",
+		loaded: "1.0.0",
+		available: "2.0.0",
+		target: "2.0.0",
+		action: "update",
+		reason: "behind",
+		scopes: ["project"],
+		beforeVersions: { project: "1.0.0" },
+		...over,
+	};
+}
+
+function removeItem(pluginId: string, scopes: PluginScope[]): PluginUpdateItem {
+	const before: Partial<Record<PluginScope, string>> = {};
+	for (const s of scopes) before[s] = "1.0.0";
+	return updateItem(pluginId, {
+		available: null,
+		target: null,
+		action: "remove",
+		reason: "deprecated",
+		scopes,
+		beforeVersions: before,
+	});
+}
+
+function actionsOf(items: PluginUpdateItem[]) {
+	return new Map<string, PluginUpdateAction>(
+		items.map((i) => [i.pluginId, i.action]),
+	);
+}
+
+/** The fix a user reads for a row: its own, or the report's shared one. */
+function fixFor(report: FailureReport, row: FailureRow): string | null {
+	return row.fix ?? report.fix;
+}
+
+/** Rows whose subject names `word` as a whole word. */
+function rowsNaming(report: FailureReport, word: string): FailureRow[] {
+	const esc = word.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const re = new RegExp(`(^|[^\\w-])${esc}($|[^\\w-])`);
+	return report.rows.filter((r) => re.test(r.subject));
+}
+
+function oneRowNaming(report: FailureReport, word: string): FailureRow {
+	const rows = rowsNaming(report, word);
+	expect(rows).toHaveLength(1);
+	return rows[0] as FailureRow;
+}
+
+function allText(report: FailureReport): string {
+	return [
+		report.headline,
+		...report.rows.flatMap((r) => [r.subject, r.reason, r.fix ?? ""]),
+		report.fix ?? "",
+	].join("\n");
+}
+
+const SILENT: ApplyReporter = {
+	begin: () => {},
+	finish: () => {},
+	detach: (work) => work(),
+};
+
+function emptyActivation(
+	over: Partial<ActivationResult> = {},
+): ActivationResult {
+	return {
+		profileId: "team",
+		displaced: [],
+		skills: { skills: {}, installed: [], removed: [], failed: [] },
+		conversion: {
+			converted: false,
+			managed: {},
+			restored: [],
+			conflicts: [],
+			keptAt: null,
+		},
+		tracked: [],
+		keptAt: null,
+		dependencies: { derived: [], unreadable: [], blocked: [] },
+		...over,
+	};
+}
+
+function repairResult(
+	pluginId: string,
+	ok: boolean,
+	error?: string,
+): StaleLoadRepairResult {
+	return {
+		pluginId,
+		target: "2.0.0",
+		rewritten: ok ? 1 : 0,
+		backup: null,
+		loaded: ok ? "2.0.0" : "1.0.0",
+		ok,
+		...(ok ? {} : { error: error ?? "Claude Code still loads v1.0.0" }),
+	};
+}
+
+async function renderPopup(
+	report: FailureReport,
+	width: number,
+	height: number,
+	terminalHeight?: number,
+): Promise<string[]> {
+	const { captureCharFrame, renderOnce, renderer } = await testRender(
+		createElement(FailureListModal, {
+			report,
+			terminalWidth: width,
+			...(terminalHeight === undefined ? {} : { terminalHeight }),
+		}),
+		{ width, height },
+	);
+	await act(async () => {
+		await renderOnce();
+		await renderOnce();
+	});
+	const lines = captureCharFrame().split("\n");
+	await act(async () => renderer.destroy());
+	return lines;
+}
+
+// ---------------------------------------------------------------------------
+// U1
+// ---------------------------------------------------------------------------
+
+describe("U1 an update that ran and changed nothing", () => {
+	/** The installer exits cleanly and the read-back is the version before. */
+	function noMoveDeps(): PluginApplyDeps {
+		return {
+			install: async () => {},
+			update: async () => {},
+			repair: async () => {},
+			readInstalled: async () => "1.0.0",
+			saveInstalled: async () => {},
+			repairStaleLoad: async (pluginId, target) => ({
+				pluginId,
+				target,
+				rewritten: 0,
+				backup: null,
+				loaded: target,
+				ok: true,
+			}),
+		};
+	}
+
+	test("U1 reported as '<name> was not updated', reason says it ran but is still v1.0.0, no fix", async () => {
+		const items = [updateItem("kanban@magus")];
+		const fr = failureReasons();
+		const result = await applyPlugins(
+			items,
+			PROJECT,
+			noMoveDeps(),
+			fr.reporter,
+		);
+		// Precondition: the engine classed it as unchanged, not failed.
+		expect(result.unchanged.join(" ")).toContain("kanban");
+		expect(result.failed).toEqual([]);
+
+		const report = fr.report(result.failed, actionsOf(items), result.unchanged);
+		expect(report).not.toBeNull();
+		const r = report as FailureReport;
+		expect(r.headline).toBe("kanban was not updated");
+		expect(r.rows).toHaveLength(1);
+		const row = oneRowNaming(r, "kanban");
+		expect(row.reason).toMatch(/\bran\b/i);
+		expect(row.reason).toMatch(/still/i);
+		expect(row.reason).toContain("v1.0.0");
+		expect(row.fix).toBeUndefined();
+		expect(r.fix).toBeNull();
+	});
+
+	test("U1 beside a real failure, the unchanged row still carries no fix", async () => {
+		const items = [updateItem("kanban@magus"), updateItem("broken@magus")];
+		const deps = noMoveDeps();
+		deps.update = async (id) => {
+			if (id === "broken@magus")
+				throw new Error("getaddrinfo ENOTFOUND github.com");
+		};
+		const fr = failureReasons();
+		const result = await applyPlugins(items, PROJECT, deps, fr.reporter);
+		const r = fr.report(
+			result.failed,
+			actionsOf(items),
+			result.unchanged,
+		) as FailureReport;
+		expect(r).not.toBeNull();
+		const row = oneRowNaming(r, "kanban");
+		expect(row.reason).toContain("v1.0.0");
+		expect(row.fix).toBeUndefined();
+		// Rows differ in fix, so no shared fix line may apply to the unchanged row.
+		expect(r.fix).toBeNull();
+	});
+});
+
+// ---------------------------------------------------------------------------
+// U2
+// ---------------------------------------------------------------------------
+
+describe("U2 startup profile gate problems", () => {
+	const problem =
+		".claude/settings.json cannot be read (Unexpected token } in JSON at position 12) — fix it by hand; magus left it as it is and did not switch";
+
+	test("U2 the file is the subject and the fix tells the user to fix it by hand", () => {
+		const r = profileProblemsReport([problem]);
+		expect(r).not.toBeNull();
+		const report = r as FailureReport;
+		expect(report.rows).toHaveLength(1);
+		const row = report.rows[0] as FailureRow;
+		expect(row.subject).toBe(".claude/settings.json");
+		expect(row.reason).toContain("cannot be read");
+		expect(row.reason).not.toMatch(/fix it by hand/i);
+		expect(fixFor(report, row) ?? "").toMatch(/fix it by hand/i);
+	});
+
+	test("U2 profileProblemRow alone: the file is the subject", () => {
+		const row = profileProblemRow(problem);
+		expect(row.subject).toBe(".claude/settings.json");
+		expect(`${row.reason} ${row.fix ?? ""}`).toMatch(/fix it by hand/i);
+	});
+
+	test("U2 a line of another shape is about the profile", () => {
+		const row = profileProblemRow(
+			'Profile "team" is not defined in profiles.json',
+		);
+		expect(row.subject).toMatch(/profile/i);
+		expect(row.reason.length).toBeGreaterThan(0);
+	});
+
+	test("U2 no problems → no report", () => {
+		expect(profileProblemsReport([])).toBeNull();
+	});
+});
+
+// ---------------------------------------------------------------------------
+// U3
+// ---------------------------------------------------------------------------
+
+describe("U3 profile activation failures", () => {
+	const full = emptyActivation({
+		dependencies: {
+			derived: [],
+			unreadable: ["imagegen@magus"],
+			blocked: [{ plugin: "kanban@magus", dependency: "dev@magus" }],
+		},
+		skills: {
+			skills: {},
+			installed: [],
+			removed: [],
+			failed: [{ skill: "pdfkit", reason: "GitHub answered 404 Not Found" }],
+		},
+		conversion: {
+			converted: true,
+			managed: {},
+			restored: [],
+			conflicts: [
+				{
+					folder: "notesync",
+					kept: ".claude/skills/notesync",
+					other: ".claude/_profiles/team/skills/notesync",
+				},
+			],
+			keptAt: null,
+		},
+	});
+
+	test("U3 one report with a row for each of the four", () => {
+		const r = activationFailureReport([full]);
+		expect(r).not.toBeNull();
+		const report = r as FailureReport;
+		expect(rowsNaming(report, "kanban").length).toBe(1);
+		expect(rowsNaming(report, "imagegen").length).toBe(1);
+		expect(rowsNaming(report, "pdfkit").length).toBe(1);
+		expect(rowsNaming(report, "notesync").length).toBe(1);
+		expect(report.rows.length).toBe(4);
+	});
+
+	test("U3 (a) the blocked plugin's row names the dependency the profile turns off", () => {
+		const report = activationFailureReport([full]) as FailureReport;
+		const row = oneRowNaming(report, "kanban");
+		expect(`${row.reason} ${row.fix ?? ""}`).toContain("dev");
+	});
+
+	test("U3 (b) dependencies not downloaded carry the fix `Run magus install`", () => {
+		const report = activationFailureReport([full]) as FailureReport;
+		const row = oneRowNaming(report, "imagegen");
+		expect(fixFor(report, row)).toBe(RUN_MAGUS_INSTALL);
+	});
+
+	test("U3 (b) alone: the fix is `Run magus install`", () => {
+		const report = activationFailureReport([
+			emptyActivation({
+				dependencies: {
+					derived: [],
+					unreadable: ["imagegen@magus"],
+					blocked: [],
+				},
+			}),
+		]) as FailureReport;
+		expect(report).not.toBeNull();
+		const row = oneRowNaming(report, "imagegen");
+		expect(fixFor(report, row)).toBe(RUN_MAGUS_INSTALL);
+	});
+
+	test("U3 (c) a failed skill install carries its reason", () => {
+		const report = activationFailureReport([full]) as FailureReport;
+		const row = oneRowNaming(report, "pdfkit");
+		expect(row.reason).toContain("GitHub answered 404 Not Found");
+	});
+
+	test("U3 (d) a skill conflict has a row", () => {
+		const report = activationFailureReport([full]) as FailureReport;
+		const row = oneRowNaming(report, "notesync");
+		expect(row.reason.length).toBeGreaterThan(0);
+	});
+
+	test("U3 only (b) carries `Run magus install` — no shared fix across the four", () => {
+		const report = activationFailureReport([full]) as FailureReport;
+		expect(report.fix).not.toBe(RUN_MAGUS_INSTALL);
+		for (const word of ["kanban", "pdfkit", "notesync"]) {
+			const row = oneRowNaming(report, word);
+			expect(fixFor(report, row)).not.toBe(RUN_MAGUS_INSTALL);
+		}
+	});
+
+	test("U3 an ActivationResult with none of these → no report", () => {
+		const r = activationFailureReport([emptyActivation()]);
+		expect(r === null || r.rows.length === 0).toBe(true);
+	});
+
+	test("U3 nulls and undefined → no report", () => {
+		const r = activationFailureReport([null, undefined]);
+		expect(r === null || r.rows.length === 0).toBe(true);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// U4
+// ---------------------------------------------------------------------------
+
+describe("U4 failed stale-load repairs", () => {
+	test("U4 two failed and one repaired → '2 plugins were not repaired', repaired one not listed", () => {
+		const r = staleRepairReport([
+			repairResult("alpha@magus", false),
+			repairResult("bravo@magus", true),
+			repairResult("charlie@magus", false),
+		]);
+		expect(r).not.toBeNull();
+		const report = r as FailureReport;
+		expect(report.headline).toBe("2 plugins were not repaired");
+		expect(rowsNaming(report, "alpha").length).toBe(1);
+		expect(rowsNaming(report, "charlie").length).toBe(1);
+		expect(allText(report)).not.toContain("bravo");
+	});
+
+	test("U4 only successful repairs → no report", () => {
+		const r = staleRepairReport([repairResult("bravo@magus", true)]);
+		expect(r === null || r.rows.length === 0).toBe(true);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// U5
+// ---------------------------------------------------------------------------
+
+describe("U5 a failed marketplace refresh", () => {
+	test("U5 the row's subject is the marketplace name", () => {
+		const r = marketplaceRefreshReport([
+			{
+				marketplace: "magus-marketing",
+				error: new Error("fatal: unable to access remote"),
+			},
+		]);
+		expect(r).not.toBeNull();
+		const report = r as FailureReport;
+		expect(report.rows).toHaveLength(1);
+		expect((report.rows[0] as FailureRow).subject).toBe("magus-marketing");
+	});
+
+	test("U5 nothing failed → no report", () => {
+		const r = marketplaceRefreshReport([]);
+		expect(r === null || r.rows.length === 0).toBe(true);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// U6
+// ---------------------------------------------------------------------------
+
+describe("U6 grouping", () => {
+	const f = (
+		pluginId: string,
+		detail: string,
+		extra: Partial<PluginFailure> = {},
+	): PluginFailure => ({ pluginId, verb: "updated", detail, ...extra });
+
+	test("U6 the same reason → one row naming every subject", () => {
+		const detail = "the marketplace does not list this plugin any more";
+		const report = pluginFailureReport([
+			f("alpha@magus", detail),
+			f("bravo@magus", detail),
+		]) as FailureReport;
+		expect(report.rows).toHaveLength(1);
+		const subject = (report.rows[0] as FailureRow).subject;
+		expect(subject).toContain("alpha");
+		expect(subject).toContain("bravo");
+	});
+
+	test("U6 reasons differing only in versions → one row in nouns, never 'still loads in this folder'", () => {
+		const report = pluginFailureReport([
+			f(
+				"alpha@magus",
+				"installed v2.0.6, but Claude Code still loads v2.0.3 in this folder",
+			),
+			f(
+				"bravo@magus",
+				"installed v1.5.0, but Claude Code still loads v1.4.0 in this folder",
+			),
+		]) as FailureReport;
+		expect(report.rows).toHaveLength(1);
+		const row = report.rows[0] as FailureRow;
+		expect(row.subject).toContain("alpha");
+		expect(row.subject).toContain("bravo");
+		expect(row.reason).toContain("the new version");
+		expect(row.reason).toContain("an older version");
+		expect(row.reason).not.toContain("still loads in this folder");
+		expect(row.reason).not.toMatch(/v\d+\.\d+/);
+	});
+
+	test("U6 'did not download' at different versions → one row, never 'installed, but is not downloaded'", () => {
+		const report = pluginFailureReport([
+			f("alpha@magus", "installed v1.3.0, but it did not download"),
+			f("bravo@magus", "installed v2.2.0, but it did not download"),
+		]) as FailureReport;
+		expect(report.rows).toHaveLength(1);
+		const row = report.rows[0] as FailureRow;
+		expect(row.reason).not.toContain("installed, but is not downloaded");
+		expect(row.reason).not.toMatch(/installed,\s*but/);
+		expect(row.reason).toContain("the new version");
+	});
+
+	test("U6 reasonWithoutVersions itself uses nouns", () => {
+		const s = reasonWithoutVersions(
+			"installed v2.0.6, but Claude Code still loads v2.0.3 in this folder",
+		);
+		expect(s).toContain("the new version");
+		expect(s).toContain("an older version");
+		expect(s).not.toContain("still loads in this folder");
+	});
+
+	test("U6 recognised network exception with the same message → one shared row", () => {
+		const msg = "getaddrinfo ENOTFOUND github.com";
+		const report = pluginFailureReport([
+			f("alpha@magus", msg, { exception: true }),
+			f("bravo@magus", msg, { exception: true }),
+		]) as FailureReport;
+		expect(report.rows).toHaveLength(1);
+		const subject = (report.rows[0] as FailureRow).subject;
+		expect(subject).toContain("alpha");
+		expect(subject).toContain("bravo");
+	});
+
+	test("U6 unrecognised exceptions with the same message keep one row each", () => {
+		const msg = "Unexpected token } in JSON at position 42";
+		const report = pluginFailureReport([
+			f("alpha@magus", msg, { exception: true }),
+			f("bravo@magus", msg, { exception: true }),
+		]) as FailureReport;
+		expect(report.rows).toHaveLength(2);
+		expect(rowsNaming(report, "alpha").length).toBe(1);
+		expect(rowsNaming(report, "bravo").length).toBe(1);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// U7
+// ---------------------------------------------------------------------------
+
+/** Arguments a failing `claude plugin update` ran with. */
+const ARGS = ["plugin", "update", "alpha@magus", "--scope", "project"];
+
+/** An error shaped like the one a child-process call throws. */
+function procError(message: string, extra: Record<string, unknown> = {}) {
+	return Object.assign(new Error(message), extra);
+}
+
+/**
+ * "claude is not on PATH", as the user-facing message the wrapper produces
+ * for each way the machine says so.
+ */
+const CLAUDE_MISSING: Array<[string, string]> = [
+	[
+		"node spawn ENOENT",
+		claudeFailureMessage(
+			procError("spawn claude ENOENT", {
+				code: "ENOENT",
+				errno: -2,
+				syscall: "spawn claude",
+				path: "claude",
+				spawnargs: ARGS.slice(),
+			}),
+			ARGS,
+			60_000,
+		),
+	],
+	[
+		"bun executable not found",
+		claudeFailureMessage(
+			procError('Executable not found in $PATH: "claude"', { code: "ENOENT" }),
+			ARGS,
+			60_000,
+		),
+	],
+	[
+		"worded, with the install command",
+		"Claude CLI not found in PATH. Install Claude Code: npm install -g @anthropic-ai/claude-code",
+	],
+];
+
+describe("U7 claude not on PATH", () => {
+	for (const [label, msg] of CLAUDE_MISSING) {
+		test(`U7 [${label}] the reason does not repeat the install command; the fix is the install line`, () => {
+			const report = pluginFailureReport([
+				{
+					pluginId: "alpha@magus",
+					verb: "updated",
+					detail: msg,
+					exception: true,
+				},
+				{
+					pluginId: "bravo@magus",
+					verb: "installed",
+					detail: msg,
+					exception: true,
+				},
+			]) as FailureReport;
+			expect(report).not.toBeNull();
+			for (const row of report.rows) {
+				expect(row.reason).not.toContain("npm install");
+				expect(row.reason).not.toContain("@anthropic-ai/claude-code");
+			}
+			expect(report.fix).toBe(INSTALL_CLAUDE);
+		});
+
+		test(`U7 [${label}] recognised, sharing one row across plugins (U6)`, () => {
+			const report = pluginFailureReport([
+				{
+					pluginId: "alpha@magus",
+					verb: "updated",
+					detail: msg,
+					exception: true,
+				},
+				{
+					pluginId: "bravo@magus",
+					verb: "updated",
+					detail: msg,
+					exception: true,
+				},
+			]) as FailureReport;
+			expect(report.rows).toHaveLength(1);
+			const e = exceptionReason(msg);
+			expect(e.known).toBe(true);
+			expect(e.fix).toBe(INSTALL_CLAUDE);
+		});
+	}
+
+	test("U7 end to end: install and update throw, the popup's fix line is the install line", async () => {
+		const [, worded] = CLAUDE_MISSING[2] as [string, string];
+		const deps: PluginApplyDeps = {
+			install: async () => {
+				throw new Error(worded);
+			},
+			update: async () => {
+				throw new Error(worded);
+			},
+			repair: async () => {},
+			readInstalled: async () => "1.0.0",
+			saveInstalled: async () => {},
+			repairStaleLoad: async (pluginId, target) => ({
+				pluginId,
+				target,
+				rewritten: 0,
+				backup: null,
+				loaded: target,
+				ok: true,
+			}),
+		};
+		const items = [
+			updateItem("alpha@magus"),
+			updateItem("bravo@magus", {
+				action: "install",
+				reason: "absent",
+				installed: null,
+				loaded: null,
+				scopes: [],
+				beforeVersions: {},
+			}),
+		];
+		const fr = failureReasons();
+		const result = await applyPlugins(items, PROJECT, deps, fr.reporter);
+		expect(result.failed.length).toBe(2);
+		const report = fr.report(result.failed, actionsOf(items)) as FailureReport;
+		expect(report.fix).toBe(INSTALL_CLAUDE);
+		for (const row of report.rows)
+			expect(row.reason).not.toContain("npm install");
+	});
+});
+
+// ---------------------------------------------------------------------------
+// U8
+// ---------------------------------------------------------------------------
+
+describe("U8 a version that did not download", () => {
+	/** Update lands v1.3.0, loader resolves v1.2.0, repair refuses: no download. */
+	function notDownloadedDeps(): PluginApplyDeps {
+		return {
+			install: async () => {},
+			update: async () => {},
+			repair: async () => {},
+			readInstalled: async () => "1.3.0",
+			saveInstalled: async () => {},
+			loadedVersion: async () => "1.2.0",
+			repairStaleLoad: async (pluginId, target) => ({
+				pluginId,
+				target,
+				rewritten: 0,
+				backup: null,
+				loaded: null,
+				ok: false,
+				error: notDownloadedReason(target),
+			}),
+		};
+	}
+
+	test("U8 describeLoadNotForward: 'installed v1.3.0, but it did not download', never 'v1.3.0 is not downloaded'", () => {
+		// The refusal repairStaleLoad makes for a version with no download.
+		const detail = describeLoadNotForward({
+			pluginId: "alpha@magus",
+			target: "1.3.0",
+			rewritten: 0,
+			backup: null,
+			loaded: null,
+			ok: false,
+			error: notDownloadedReason("1.3.0"),
+		});
+		expect(detail).toContain("installed v1.3.0, but it did not download");
+		expect(detail).not.toContain("v1.3.0 is not downloaded");
+	});
+
+	test("U8 end to end: reason `installed v1.3.0, but it did not download`, fix `Run magus install`", async () => {
+		const items = [
+			updateItem("alpha@magus", {
+				available: "1.3.0",
+				target: "1.3.0",
+				installed: "1.2.0",
+				loaded: "1.2.0",
+				beforeVersions: { project: "1.2.0" },
+			}),
+		];
+		const fr = failureReasons();
+		const result = await applyPlugins(
+			items,
+			PROJECT,
+			notDownloadedDeps(),
+			fr.reporter,
+		);
+		expect(result.failed.join(" ")).toContain("alpha");
+		const report = fr.report(result.failed, actionsOf(items)) as FailureReport;
+		expect(report).not.toBeNull();
+		const row = oneRowNaming(report, "alpha");
+		expect(row.reason).toBe("installed v1.3.0, but it did not download");
+		expect(fixFor(report, row)).toBe(RUN_MAGUS_INSTALL);
+		expect(allText(report)).not.toContain("v1.3.0 is not downloaded");
+	});
+});
+
+// ---------------------------------------------------------------------------
+// U9
+// ---------------------------------------------------------------------------
+
+describe("U9 exception text", () => {
+	const BIN = "/Users/someone/.local/bin/claude";
+	const cmd = `${BIN} ${ARGS.join(" ")}`;
+	const errors: Array<[string, unknown]> = [
+		[
+			"Command failed + a following line, no output",
+			procError(`Command failed: ${cmd}\nerror: Plugin alpha not found`, {
+				code: 1,
+				stderr: "",
+				stdout: "",
+			}),
+		],
+		[
+			"Command failed alone, no output",
+			procError(`Command failed: ${cmd}`, { code: 1, stderr: "", stdout: "" }),
+		],
+		[
+			"Command failed with stderr",
+			procError(`Command failed: ${cmd}`, {
+				code: 1,
+				stderr: "Plugin alpha not found in marketplace magus\n",
+				stdout: "",
+			}),
+		],
+		[
+			"spawn <abs path> EACCES",
+			procError(`spawn ${BIN} EACCES`, {
+				code: "EACCES",
+				errno: -13,
+				syscall: `spawn ${BIN}`,
+				path: BIN,
+				spawnargs: ARGS.slice(),
+			}),
+		],
+		[
+			"spawn <abs path> ENOENT",
+			procError(`spawn ${BIN} ENOENT`, {
+				code: "ENOENT",
+				errno: -2,
+				syscall: `spawn ${BIN}`,
+				path: BIN,
+				spawnargs: ARGS.slice(),
+			}),
+		],
+		[
+			"killed after the timeout",
+			procError(`Command failed: ${cmd}`, {
+				killed: true,
+				signal: "SIGTERM",
+				stderr: "",
+				stdout: "",
+			}),
+		],
+	];
+
+	for (const [label, error] of errors) {
+		test(`U9 [${label}] the wrapper's message: no 'Command failed:', no claude binary path`, () => {
+			const msg = claudeFailureMessage(error, ARGS, 60_000);
+			expect(msg).not.toMatch(/^Command failed:/m);
+			expect(msg).not.toContain(BIN);
+			expect(msg.trim().length).toBeGreaterThan(0);
+		});
+
+		test(`U9 [${label}] the popup built from it is clean too`, () => {
+			const msg = claudeFailureMessage(error, ARGS, 60_000);
+			const report = pluginFailureReport([
+				{
+					pluginId: "alpha@magus",
+					verb: "updated",
+					detail: msg,
+					exception: true,
+				},
+			]) as FailureReport;
+			const text = allText(report);
+			expect(text).not.toMatch(/^Command failed:/m);
+			expect(text).not.toContain(BIN);
+		});
+	}
+
+	test("U9 end to end: an update that throws the wrapper's message", async () => {
+		const thrown = claudeFailureMessage(errors[0]?.[1], ARGS, 60_000);
+		const deps: PluginApplyDeps = {
+			install: async () => {},
+			update: async () => {
+				throw new Error(thrown);
+			},
+			repair: async () => {},
+			readInstalled: async () => "1.0.0",
+			saveInstalled: async () => {},
+			repairStaleLoad: async (pluginId, target) => ({
+				pluginId,
+				target,
+				rewritten: 0,
+				backup: null,
+				loaded: target,
+				ok: true,
+			}),
+		};
+		const items = [updateItem("alpha@magus")];
+		const fr = failureReasons();
+		const result = await applyPlugins(items, PROJECT, deps, fr.reporter);
+		const report = fr.report(result.failed, actionsOf(items)) as FailureReport;
+		expect(report).not.toBeNull();
+		const text = allText(report);
+		expect(text).not.toMatch(/^Command failed:/m);
+		expect(text).not.toContain(BIN);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// U10
+// ---------------------------------------------------------------------------
+
+describe("U10 removal forgets the version only where removed", () => {
+	/** Installed scopes per plugin; uninstall removes unless the scope is stuck. */
+	function world(
+		installed: Record<string, PluginScope[]>,
+		stuck: Partial<Record<PluginScope, "throw" | "stays">> = {},
+	) {
+		const state = new Map(
+			Object.entries(installed).map(([id, s]) => [id, new Set(s)]),
+		);
+		const forgotten: Array<{ id: string; scope: PluginScope }> = [];
+		const deps: PluginApplyDeps = {
+			install: async () => {},
+			update: async () => {},
+			repair: async () => {},
+			readInstalled: async () => null,
+			saveInstalled: async () => {},
+			repairStaleLoad: async (pluginId, target) => ({
+				pluginId,
+				target,
+				rewritten: 0,
+				backup: null,
+				loaded: target,
+				ok: true,
+			}),
+			remove: {
+				uninstall: async (id, scope) => {
+					if (stuck[scope] === "throw") {
+						throw new Error("Command failed: claude plugin uninstall");
+					}
+					if (stuck[scope] === "stays") return;
+					state.get(id)?.delete(scope);
+				},
+				isInstalled: async (id, scope) => state.get(id)?.has(scope) ?? false,
+				dropFromProfile: async () => true,
+				forgetVersion: async (id, scope) => {
+					forgotten.push({ id, scope });
+				},
+			},
+		};
+		return { deps, forgotten };
+	}
+
+	test("U10 removed at every scope → forgotten at every scope", async () => {
+		const { deps, forgotten } = world({ "old@magus": ["project", "user"] });
+		const result = await applyPlugins(
+			[removeItem("old@magus", ["project", "user"])],
+			PROJECT,
+			deps,
+			SILENT,
+		);
+		expect(result.failed).toEqual([]);
+		const scopes = forgotten
+			.filter((f) => f.id === "old@magus")
+			.map((f) => f.scope)
+			.sort();
+		expect(scopes).toEqual(["project", "user"]);
+	});
+
+	test("U10 uninstall throws at user → forgotten at project only", async () => {
+		const { deps, forgotten } = world(
+			{ "old@magus": ["project", "user"] },
+			{ user: "throw" },
+		);
+		await applyPlugins(
+			[removeItem("old@magus", ["project", "user"])],
+			PROJECT,
+			deps,
+			SILENT,
+		);
+		const scopes = forgotten
+			.filter((f) => f.id === "old@magus")
+			.map((f) => f.scope);
+		expect(scopes).toContain("project");
+		expect(scopes).not.toContain("user");
+	});
+
+	test("U10 uninstall exits cleanly but user still installed → not forgotten at user", async () => {
+		const { deps, forgotten } = world(
+			{ "old@magus": ["project", "user"] },
+			{ user: "stays" },
+		);
+		const result = await applyPlugins(
+			[removeItem("old@magus", ["project", "user"])],
+			PROJECT,
+			deps,
+			SILENT,
+		);
+		const scopes = forgotten
+			.filter((f) => f.id === "old@magus")
+			.map((f) => f.scope);
+		expect(scopes).toContain("project");
+		expect(scopes).not.toContain("user");
+		expect(result.failed.join(" ")).toContain("old");
+	});
+
+	test("U10 never forgets at a scope the item does not name", async () => {
+		const { deps, forgotten } = world({ "old@magus": ["project"] });
+		await applyPlugins(
+			[removeItem("old@magus", ["project"])],
+			PROJECT,
+			deps,
+			SILENT,
+		);
+		const scopes = forgotten.map((f) => f.scope);
+		expect(scopes).toEqual(["project"]);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// U11
+// ---------------------------------------------------------------------------
+
+describe("U11 doctor: what loads nothing", () => {
+	/**
+	 * findPluginLoadProblems is declared pure over its inputs, so "resolves to
+	 * no version" is a row for this folder that carries none.
+	 */
+	const row = (version: string) => ({
+		scope: "project" as const,
+		projectPath: PROJECT,
+		installPath: `${PROJECT}/.cache/real/${version || "none"}`,
+		version,
+		installedAt: "2026-09-01T00:00:00.000Z",
+		lastUpdated: "2026-09-01T00:00:00.000Z",
+	});
+
+	test("U11 a bare installedPluginVersions claim is not 'loads nothing'", () => {
+		const findings = findPluginLoadProblems(
+			{ "ghost@magus": "1.0.0" },
+			{},
+			PROJECT,
+			{},
+		);
+		expect(findings.loadsNothing).not.toContain("ghost@magus");
+	});
+
+	test("U11 claim with an undefined registry and no enabledPlugins is not 'loads nothing'", () => {
+		const findings = findPluginLoadProblems(
+			{ "ghost@magus": "1.0.0" },
+			undefined,
+			PROJECT,
+		);
+		expect(findings.loadsNothing).not.toContain("ghost@magus");
+	});
+
+	test("U11 a registry row for this folder that resolves to no version IS 'loads nothing'", () => {
+		const findings = findPluginLoadProblems(
+			{ "real@magus": "1.0.0" },
+			{ "real@magus": [row("")] },
+			PROJECT,
+			{},
+		);
+		expect(findings.loadsNothing).toContain("real@magus");
+	});
+
+	test("U11 control: a row for this folder at the installed version is not 'loads nothing'", () => {
+		const findings = findPluginLoadProblems(
+			{ "real@magus": "1.0.0" },
+			{ "real@magus": [row("1.0.0")] },
+			PROJECT,
+			{},
+		);
+		expect(findings.loadsNothing).not.toContain("real@magus");
+	});
+});
+
+// ---------------------------------------------------------------------------
+// U12
+// ---------------------------------------------------------------------------
+
+describe("U12 a deprecated plugin another installed plugin requires", () => {
+	const installedAtProject = (v: string) => ({ installed: true, version: v });
+
+	function catalog(): PluginInfo[] {
+		const base = {
+			description: "",
+			marketplace: "magus",
+			marketplaceDisplay: "magus",
+		};
+		return [
+			{
+				...base,
+				id: "parent@magus",
+				name: "parent",
+				version: "2.0.0",
+				installedVersion: "2.0.0",
+				loadedVersion: "2.0.0",
+				projectScope: installedAtProject("2.0.0"),
+			},
+			{
+				...base,
+				id: "sibling@magus",
+				name: "sibling",
+				version: "1.0.0",
+			},
+			{
+				...base,
+				id: "old@magus",
+				name: "old",
+				version: "1.0.0",
+				installedVersion: "1.0.0",
+				loadedVersion: "1.0.0",
+				isOrphaned: true,
+				projectScope: installedAtProject("1.0.0"),
+			},
+		];
+	}
+
+	const reader = async (id: string): Promise<string[] | null> =>
+		id === "parent@magus" ? ["old@magus"] : [];
+
+	const action = (items: PluginUpdateItem[], id: string) =>
+		items.find((i) => i.pluginId === id)?.action;
+
+	test("U12 control: with nothing requiring it, the deprecated plugin IS planned remove", () => {
+		const items = planPluginUpdates({}, catalog(), {});
+		expect(action(items, "old@magus")).toBe("remove");
+	});
+
+	test("U12 required by an installed plugin (edges from requiredByHere) → not remove", async () => {
+		const requiredBy = await requiredByHere(
+			undefined,
+			["parent@magus", "old@magus"],
+			PROJECT,
+			reader,
+		);
+		expect(requiredBy["old@magus"]).toBe("parent@magus");
+		const items = planPluginUpdates({}, catalog(), requiredBy);
+		expect(action(items, "old@magus")).toBeDefined();
+		expect(action(items, "old@magus")).not.toBe("remove");
+	});
+
+	test("U12 the profile names it directly and it is still required → not remove", async () => {
+		const requiredBy = await requiredByHere(
+			undefined,
+			["parent@magus", "old@magus"],
+			PROJECT,
+			reader,
+		);
+		const items = planPluginUpdates(
+			{ "old@magus": "latest", "parent@magus": "latest" },
+			catalog(),
+			requiredBy,
+		);
+		expect(action(items, "old@magus")).toBeDefined();
+		expect(action(items, "old@magus")).not.toBe("remove");
+	});
+
+	test("U12 the profile names both and records the edge itself → not remove", () => {
+		const items = planPluginUpdates(
+			{ "old@magus": "latest", "parent@magus": "latest" },
+			catalog(),
+			{ "old@magus": "parent@magus" },
+		);
+		expect(action(items, "old@magus")).not.toBe("remove");
+	});
+});
+
+// ---------------------------------------------------------------------------
+// U13
+// ---------------------------------------------------------------------------
+
+describe("U13 the popup fits the terminal height", () => {
+	function bigReport(n: number): FailureReport {
+		const rows: FailureRow[] = [];
+		for (let i = 0; i < n; i++) {
+			rows.push({
+				subject: `plugin${String(i).padStart(2, "0")}`,
+				reason: `reason number ${i}`,
+			});
+		}
+		return { headline: `${n} plugins were not updated`, rows, fix: null };
+	}
+
+	test("U13 visibleFailureRows: cut rows are counted, at least one shown", () => {
+		const report = bigReport(30);
+		const { rows, hidden } = visibleFailureRows(report, 80, 14);
+		expect(rows.length).toBeGreaterThanOrEqual(1);
+		expect(hidden).toBeGreaterThan(0);
+		expect(rows.length + hidden).toBe(30);
+		expect(rows.length).toBeLessThan(14);
+	});
+
+	test("U13 visibleFailureRows without a height draws every row", () => {
+		const { rows, hidden } = visibleFailureRows(bigReport(30), 80);
+		expect(rows.length).toBe(30);
+		expect(hidden).toBe(0);
+	});
+
+	test("U13 rendered at 16 rows: headline visible, rows capped, ends with '+N more'", async () => {
+		const height = 16;
+		const report = bigReport(30);
+		const lines = await renderPopup(report, 80, height, height);
+		const frame = lines.join("\n");
+		expect(frame).toContain("30 plugins were not updated");
+		const shown = report.rows.filter((r) => frame.includes(r.subject)).length;
+		expect(shown).toBeGreaterThanOrEqual(1);
+		expect(shown).toBeLessThan(height);
+		const more = frame.match(/\+(\d+) more/);
+		expect(more).not.toBeNull();
+		expect(Number(more?.[1])).toBe(30 - shown);
+		// '+N more' comes after the last shown row.
+		const lastShown = report.rows
+			.filter((r) => frame.includes(r.subject))
+			.pop();
+		const idxMore = lines.findIndex((l) => /\+\d+ more/.test(l));
+		const idxLast = lines.findIndex((l) =>
+			l.includes(lastShown?.subject ?? "\0"),
+		);
+		expect(idxMore).toBeGreaterThan(idxLast);
+	});
+
+	test("U13 rows that fit → no '+N more'", async () => {
+		const report = bigReport(3);
+		const lines = await renderPopup(report, 80, 30, 30);
+		const frame = lines.join("\n");
+		for (const r of report.rows) expect(frame).toContain(r.subject);
+		expect(frame).not.toMatch(/\+\d+ more/);
+	});
+});