magus-cli 7.7.0 → 7.8.0

package/src/__tests__/blind-780-failure-reasons.test.ts

@@ -0,0 +1,1004 @@
+/**
+ * magus 7.8.0 QA — failure reasons (F1, F2) and the failure popup (P1–P8).
+ *
+ * Written blind: from qa-spec-7.8.0.md §F1/F2, qa-spec-failures-popup.md, and
+ * the exported declarations of ui/adapters/pluginsAdapter.ts,
+ * ui/components/modals/FailureListModal.tsx, ui/state/types.ts,
+ * services/update-engine.ts, services/update-plan.ts and cli/update-view.ts
+ * (emitted with `tsc --emitDeclarationOnly`). No function body was read.
+ *
+ * Coverage map (requirement → describe block):
+ *   F1 install lands, older version still loads → exact detail   → "F1"
+ *   F2 engine failure details carry no internal word              → "F2"
+ *   P1 headline counts, verb matches the action, "or" when mixed  → "P1"
+ *   P2 one entry per plugin or per same-reason group; all named   → "P2"
+ *   P3 an exception: its own entry, first line of its message     → "P3"
+ *   P4 one shared fix at the bottom, otherwise none               → "P4"
+ *   P5 plugins that succeeded are not listed                      → "P5"
+ *   P6 entry reason is contained in the CLI ✗ row for that item   → "P6"
+ *   P7 no entry/headline carries an internal word                 → "P7"
+ *   P8 at 50 columns names are not split, long reasons wrap       → "P8"
+ *
+ * Failures are produced end to end: `applyPlugins` with injected
+ * `PluginApplyDeps`, its reporter fanned out to `failureReasons()` (the popup)
+ * and to `applyRow` (the CLI's ✗ row), exactly as the two front ends consume it.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { testRender } from "@opentui/react/test-utils";
+import { act, createElement } from "react";
+import { applyRow } from "../cli/update-view.js";
+import type { PluginScope } from "../services/claude-cli.js";
+import type { StaleLoadRepairResult } from "../services/claude-settings.js";
+import {
+	type ApplyReporter,
+	type FinishCause,
+	type PluginApplyDeps,
+	applyPlugins,
+	describeLoadNotForward,
+	pluginName,
+} from "../services/update-engine.js";
+import type {
+	PluginUpdateAction,
+	PluginUpdateItem,
+} from "../services/update-plan.js";
+import {
+	type PluginFailure,
+	failureReasons,
+	pluginFailureReport,
+} from "../ui/adapters/pluginsAdapter.js";
+import { FailureListModal } from "../ui/components/modals/FailureListModal.js";
+import type { FailureReport } from "../ui/state/types.js";
+
+const PROJECT = "/tmp/blind-780-project";
+
+/** Words user-facing failure text must never contain (F2, P7). */
+const FORBIDDEN: RegExp[] = [
+	/loader/i,
+	/registry/i,
+	/\brows?\b/i,
+	/\brecords?\b/i,
+	/installed_plugins/i,
+	/settings\.json/i,
+	/cache directory/i,
+];
+
+function leaks(text: string): string[] {
+	return FORBIDDEN.filter((re) => re.test(text)).map((re) => re.source);
+}
+
+const ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+function plain(text: string): string {
+	return text.replace(ANSI, "");
+}
+
+// ---------------------------------------------------------------------------
+// Plan items
+// ---------------------------------------------------------------------------
+
+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 installItem(
+	pluginId: string,
+	over: Partial<PluginUpdateItem> = {},
+): PluginUpdateItem {
+	return updateItem(pluginId, {
+		installed: null,
+		loaded: null,
+		action: "install",
+		reason: "absent",
+		scopes: [],
+		beforeVersions: {},
+		...over,
+	});
+}
+
+function removeItem(
+	pluginId: string,
+	over: Partial<PluginUpdateItem> = {},
+): PluginUpdateItem {
+	return updateItem(pluginId, {
+		available: null,
+		target: null,
+		action: "remove",
+		reason: "deprecated",
+		scopes: ["project"],
+		beforeVersions: { project: "1.0.0" },
+		...over,
+	});
+}
+
+// ---------------------------------------------------------------------------
+// A world of injected Claude Code calls, chosen per plugin
+// ---------------------------------------------------------------------------
+
+interface PluginWorld {
+	/** Version read back after the install/update lands. */
+	lands: string | null;
+	/** Version Claude Code loads here after the install, before any repair. */
+	loads: string | null;
+	/** What the stale-load repair answers. */
+	repair?: (target: string) => StaleLoadRepairResult;
+	/** Throw from install/update with this message. */
+	throws?: string;
+	/** remove: the plugin is still installed after the uninstall. */
+	stillInstalled?: boolean;
+}
+
+function depsFor(world: Record<string, PluginWorld>): PluginApplyDeps {
+	const w = (id: string): PluginWorld => {
+		const found = world[id];
+		if (!found) throw new Error(`no world for ${id}`);
+		return found;
+	};
+	const land = async (id: string, _scope: PluginScope) => {
+		const t = w(id).throws;
+		if (t) throw new Error(t);
+	};
+	return {
+		install: land,
+		update: land,
+		repair: land,
+		readInstalled: async (id) => w(id).lands,
+		saveInstalled: async () => {},
+		loadedVersion: async (id) => w(id).loads,
+		repairStaleLoad: async (id, target) =>
+			w(id).repair?.(target) ?? {
+				pluginId: id,
+				target,
+				rewritten: 0,
+				backup: null,
+				loaded: w(id).loads,
+				ok: w(id).loads === target,
+				...(w(id).loads === target
+					? {}
+					: { error: "rows in installed_plugins.json still behind" }),
+			},
+		remove: {
+			uninstall: async () => {},
+			isInstalled: async (id) => w(id).stillInstalled === true,
+			dropFromProfile: async () => true,
+		},
+	};
+}
+
+function refused(pluginId: string, error: string) {
+	return (target: string): StaleLoadRepairResult => ({
+		pluginId,
+		target,
+		rewritten: 0,
+		backup: null,
+		loaded: null,
+		ok: false,
+		error,
+	});
+}
+
+function recorder() {
+	const finished: Array<{
+		ok: boolean;
+		name: string;
+		detail: string;
+		cause?: FinishCause;
+	}> = [];
+	const reporter: ApplyReporter = {
+		begin: () => {},
+		finish: (ok, name, detail, _ms, cause) =>
+			finished.push({ ok, name, detail, cause }),
+		detach: (work) => work(),
+	};
+	return { reporter, finished };
+}
+
+function actionsOf(items: PluginUpdateItem[]) {
+	return new Map<string, PluginUpdateAction>(
+		items.map((i) => [i.pluginId, i.action]),
+	);
+}
+
+/**
+ * One apply, seen by both front ends: the popup (`failureReasons`) and the
+ * CLI's permanent `✗` row (`applyRow`), fed from the same reporter calls.
+ */
+async function runBoth(
+	items: PluginUpdateItem[],
+	world: Record<string, PluginWorld>,
+) {
+	const fr = failureReasons();
+	const cliRows: Array<{ ok: boolean; name: string; row: string }> = [];
+	const reporter: ApplyReporter = {
+		begin: (name) => fr.reporter.begin(name),
+		finish: (ok, name, detail, ms, cause) => {
+			fr.reporter.finish(ok, name, detail, ms, cause);
+			cliRows.push({
+				ok,
+				name,
+				row: plain(applyRow(ok, name, 24, detail, ms)),
+			});
+		},
+		detach: (work) => work(),
+	};
+	const result = await applyPlugins(items, PROJECT, depsFor(world), reporter);
+	const report = fr.report(result.failed, actionsOf(items));
+	/** The CLI's ✗ row for a plugin id, whichever form of name the engine used. */
+	const cliRowFor = (id: string) =>
+		cliRows.find((r) => !r.ok && (r.name === id || r.name === pluginName(id)))
+			?.row;
+	return { result, report, cliRows, cliRowFor };
+}
+
+/** Everything a report says, as the strings a user reads. */
+function reportTexts(report: FailureReport): string[] {
+	return [
+		report.headline,
+		...report.rows.flatMap((r) => [r.subject, r.reason]),
+		...(report.fix ? [report.fix] : []),
+	];
+}
+
+/** The row whose subject names `name` as a whole word. */
+function rowNaming(report: FailureReport, name: string) {
+	const re = new RegExp(`(^|[^\\w-])${name}($|[^\\w-])`);
+	return report.rows.filter((r) => re.test(r.subject));
+}
+
+// Failure kinds the engine can produce, each with its own injected world.
+type Kind = (id: string) => { item: PluginUpdateItem; world: PluginWorld };
+
+const KINDS: Record<string, Kind> = {
+	"update lands, older version still loads": (id) => ({
+		item: updateItem(id),
+		world: { lands: "2.0.0", loads: "1.0.0" },
+	}),
+	"install lands, older version still loads": (id) => ({
+		item: installItem(id),
+		world: { lands: "2.0.0", loads: "1.4.0" },
+	}),
+	"load repair refused before writing": (id) => ({
+		item: updateItem(id),
+		world: {
+			lands: "2.0.0",
+			loads: "1.0.0",
+			repair: refused(id, "the folder could not be written"),
+		},
+	}),
+	"update threw": (id) => ({
+		item: updateItem(id),
+		world: {
+			lands: "2.0.0",
+			loads: "2.0.0",
+			throws: "network unreachable (ECONNRESET)",
+		},
+	}),
+	"version could not be read back": (id) => ({
+		item: updateItem(id),
+		world: { lands: null, loads: null },
+	}),
+	"deprecated plugin still installed after removal": (id) => ({
+		item: removeItem(id),
+		world: { lands: null, loads: null, stillInstalled: true },
+	}),
+};
+
+async function runKinds(spec: Array<[string, string]>) {
+	const items: PluginUpdateItem[] = [];
+	const world: Record<string, PluginWorld> = {};
+	for (const [kind, id] of spec) {
+		const make = KINDS[kind];
+		if (!make) throw new Error(`no kind ${kind}`);
+		const k = make(id);
+		items.push(k.item);
+		world[id] = k.world;
+	}
+	return runBoth(items, world);
+}
+
+async function renderPopup(
+	report: FailureReport,
+	width: number,
+): Promise<string[]> {
+	const { captureCharFrame, renderOnce, renderer } = await testRender(
+		createElement(FailureListModal, { report, terminalWidth: width }),
+		{ width, height: 40 },
+	);
+	await act(async () => {
+		await renderOnce();
+		await renderOnce();
+	});
+	const lines = captureCharFrame().split("\n");
+	await act(async () => renderer.destroy());
+	return lines;
+}
+
+/** A frame's text with borders and all whitespace taken out. */
+function flatten(lines: string[]): string {
+	return lines.join("").replace(/[\s│┃║╭╮╰╯─━┌┐└┘╔╗╚╝═]/g, "");
+}
+
+// ---------------------------------------------------------------------------
+// F1
+// ---------------------------------------------------------------------------
+
+describe("F1 an install that lands but does not load", () => {
+	test("F1 update: the failure detail is exactly the installed and the still-loading versions", async () => {
+		const deps = depsFor({ "dev@magus": { lands: "2.0.0", loads: "1.0.0" } });
+		const r = recorder();
+
+		const result = await applyPlugins(
+			[updateItem("dev@magus")],
+			PROJECT,
+			deps,
+			r.reporter,
+		);
+
+		expect(result.failed).toHaveLength(1);
+		expect(r.finished.filter((f) => !f.ok).map((f) => f.detail)).toEqual([
+			"installed v2.0.0, but Claude Code still loads v1.0.0 in this folder",
+		]);
+	});
+
+	test("F1 install: the same exact detail", async () => {
+		const deps = depsFor({ "kit@magus": { lands: "3.1.0", loads: "2.9.4" } });
+		const r = recorder();
+
+		await applyPlugins(
+			[installItem("kit@magus", { target: "3.1.0", available: "3.1.0" })],
+			PROJECT,
+			deps,
+			r.reporter,
+		);
+
+		expect(r.finished.filter((f) => !f.ok).map((f) => f.detail)).toEqual([
+			"installed v3.1.0, but Claude Code still loads v2.9.4 in this folder",
+		]);
+	});
+
+	test("F1 describeLoadNotForward names both versions exactly when the repair saw the old one still loading", () => {
+		const text = describeLoadNotForward({
+			pluginId: "dev@magus",
+			target: "2.0.0",
+			rewritten: 3,
+			backup: "/somewhere/backup",
+			loaded: "1.0.0",
+			ok: false,
+			error: "rows still behind in the registry",
+		});
+
+		expect(text).toBe(
+			"installed v2.0.0, but Claude Code still loads v1.0.0 in this folder",
+		);
+	});
+
+	test("F1 control: when the new version loads, the item is not a failure", async () => {
+		const deps = depsFor({ "dev@magus": { lands: "2.0.0", loads: "2.0.0" } });
+		const r = recorder();
+
+		const result = await applyPlugins(
+			[updateItem("dev@magus")],
+			PROJECT,
+			deps,
+			r.reporter,
+		);
+
+		expect(result.failed).toEqual([]);
+		expect(r.finished.every((f) => f.ok)).toBe(true);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// F2
+// ---------------------------------------------------------------------------
+
+describe("F2 engine failure details are in the user's terms", () => {
+	test("F2 no reason-caused failure detail carries an internal word, across failure kinds", async () => {
+		const kinds = Object.keys(KINDS).filter((k) => k !== "update threw");
+		const items: PluginUpdateItem[] = [];
+		const world: Record<string, PluginWorld> = {};
+		kinds.forEach((kind, i) => {
+			const k = (KINDS[kind] as Kind)(`kind${i}@magus`);
+			items.push(k.item);
+			world[k.item.pluginId] = k.world;
+		});
+		const r = recorder();
+
+		await applyPlugins(items, PROJECT, depsFor(world), r.reporter);
+
+		const reasonFailures = r.finished.filter(
+			(f) => !f.ok && f.cause !== "exception",
+		);
+		expect(reasonFailures.length).toBeGreaterThanOrEqual(3);
+		for (const f of reasonFailures) {
+			expect({ detail: f.detail, leaks: leaks(f.detail) }).toEqual({
+				detail: f.detail,
+				leaks: [],
+			});
+		}
+	});
+
+	test("F2 a remove applied without the calls it needs fails in the user's terms", async () => {
+		const deps = depsFor({ "oldie@magus": { lands: null, loads: null } });
+		const { remove: _dropped, ...withoutRemove } = deps;
+		const r = recorder();
+
+		const result = await applyPlugins(
+			[removeItem("oldie@magus")],
+			PROJECT,
+			withoutRemove,
+			r.reporter,
+		);
+
+		expect(result.failed).toHaveLength(1);
+		const detail = r.finished.find((f) => !f.ok)?.detail ?? "";
+		expect(detail.length).toBeGreaterThan(0);
+		expect(leaks(detail)).toEqual([]);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// P1 headline
+// ---------------------------------------------------------------------------
+
+describe("P1 the headline counts what did not happen", () => {
+	test("P1 one failed update → '<name> was not updated'", async () => {
+		const { report } = await runKinds([
+			["update lands, older version still loads", "alpha@magus"],
+		]);
+		expect(report?.headline).toBe("alpha was not updated");
+	});
+
+	test("P1 one failed install → '<name> was not installed'", async () => {
+		const { report } = await runKinds([
+			["install lands, older version still loads", "kit@magus"],
+		]);
+		expect(report?.headline).toBe("kit was not installed");
+	});
+
+	test("P1 one failed removal → '<name> was not removed'", async () => {
+		const { report } = await runKinds([
+			["deprecated plugin still installed after removal", "oldie@magus"],
+		]);
+		expect(report?.headline).toBe("oldie was not removed");
+	});
+
+	test("P1 three failed updates → '3 plugins were not updated'", async () => {
+		const { report } = await runKinds([
+			["update lands, older version still loads", "alpha@magus"],
+			["load repair refused before writing", "bravo@magus"],
+			["update threw", "charlie@magus"],
+		]);
+		expect(report?.headline).toBe("3 plugins were not updated");
+	});
+
+	test("P1 an install and an update failing → the two verbs joined with 'or'", async () => {
+		const { report } = await runKinds([
+			["install lands, older version still loads", "kit@magus"],
+			["update lands, older version still loads", "alpha@magus"],
+		]);
+		expect(report?.headline).toMatch(
+			/^2 plugins were not (installed or updated|updated or installed)$/,
+		);
+	});
+
+	test("P1 install, update and remove failing → every verb named, joined with 'or'", async () => {
+		const { report } = await runKinds([
+			["install lands, older version still loads", "kit@magus"],
+			["update lands, older version still loads", "alpha@magus"],
+			["deprecated plugin still installed after removal", "oldie@magus"],
+		]);
+		const headline = report?.headline ?? "";
+		expect(headline).toStartWith("3 plugins were not ");
+		expect(headline).toContain("installed");
+		expect(headline).toContain("updated");
+		expect(headline).toContain("removed");
+		expect(headline).toContain(" or ");
+	});
+
+	test("P1 pure report: one failure's verb comes from that failure", () => {
+		const report = pluginFailureReport([
+			{
+				pluginId: "claudish@magus",
+				verb: "removed",
+				detail: "it is still installed for this project",
+			},
+		]);
+		expect(report?.headline).toBe("claudish was not removed");
+	});
+});
+
+// ---------------------------------------------------------------------------
+// P2 entries
+// ---------------------------------------------------------------------------
+
+describe("P2 one entry per plugin or per same-reason group", () => {
+	test("P2 the same reason at different versions is one entry naming every plugin", async () => {
+		const { report, result } = await runBoth(
+			[
+				updateItem("alpha@magus", { target: "2.0.0" }),
+				updateItem("bravo@magus", { target: "5.4.0", available: "5.4.0" }),
+				updateItem("charlie@magus", { target: "0.3.1", available: "0.3.1" }),
+			],
+			{
+				"alpha@magus": { lands: "2.0.0", loads: "1.0.0" },
+				"bravo@magus": { lands: "5.4.0", loads: "5.3.9" },
+				"charlie@magus": { lands: "0.3.1", loads: "0.2.0" },
+			},
+		);
+
+		expect(result.failed).toHaveLength(3);
+		expect(report?.rows).toHaveLength(1);
+		for (const name of ["alpha", "bravo", "charlie"]) {
+			expect(rowNaming(report as FailureReport, name)).toHaveLength(1);
+		}
+		expect(report?.rows[0]?.reason).toContain("Claude Code still loads");
+	});
+
+	test("P2 different reasons are different entries", async () => {
+		const { report } = await runKinds([
+			["update lands, older version still loads", "alpha@magus"],
+			["update lands, older version still loads", "bravo@magus"],
+			["load repair refused before writing", "delta@magus"],
+		]);
+
+		const r = report as FailureReport;
+		expect(r.rows).toHaveLength(2);
+		const grouped = rowNaming(r, "alpha");
+		const alone = rowNaming(r, "delta");
+		expect(grouped).toHaveLength(1);
+		expect(alone).toHaveLength(1);
+		expect(grouped[0]).not.toBe(alone[0]);
+		expect(rowNaming(r, "bravo")[0]).toBe(grouped[0]);
+		expect(grouped[0]?.subject).not.toContain("delta");
+		expect(alone[0]?.subject).not.toContain("alpha");
+	});
+
+	test("P2 every failed plugin name appears in the popup, across all failure kinds", async () => {
+		const spec = Object.keys(KINDS).map(
+			(kind, i) => [kind, `plug${i}@magus`] as [string, string],
+		);
+		const { report, result } = await runKinds(spec);
+
+		expect(result.failed.length).toBeGreaterThanOrEqual(5);
+		for (const id of result.failed) {
+			const name = pluginName(id);
+			expect({
+				name,
+				rows: rowNaming(report as FailureReport, name).length,
+			}).toEqual({ name, rows: 1 });
+		}
+	});
+
+	test("P2 pure report: same reason ignoring versions shares an entry; a different reason does not", () => {
+		const failures: PluginFailure[] = [
+			{
+				pluginId: "alpha@magus",
+				verb: "updated",
+				detail:
+					"installed v2.0.0, but Claude Code still loads v1.0.0 in this folder",
+			},
+			{
+				pluginId: "bravo@magus",
+				verb: "updated",
+				detail:
+					"installed v7.1.3, but Claude Code still loads v7.0.9 in this folder",
+			},
+			{
+				pluginId: "delta@magus",
+				verb: "updated",
+				detail: "the folder could not be written",
+			},
+		];
+		const report = pluginFailureReport(failures) as FailureReport;
+
+		expect(report.rows).toHaveLength(2);
+		expect(rowNaming(report, "alpha")[0]).toBe(rowNaming(report, "bravo")[0]);
+		expect(rowNaming(report, "delta")[0]).not.toBe(
+			rowNaming(report, "alpha")[0],
+		);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// P3 exceptions
+// ---------------------------------------------------------------------------
+
+describe("P3 an unexpected exception", () => {
+	test("P3 gets its own entry, apart from plugins sharing a worded reason", async () => {
+		const { report } = await runKinds([
+			["update lands, older version still loads", "alpha@magus"],
+			["update lands, older version still loads", "bravo@magus"],
+			["update threw", "omega@magus"],
+		]);
+
+		const r = report as FailureReport;
+		expect(r.rows).toHaveLength(2);
+		const own = rowNaming(r, "omega");
+		expect(own).toHaveLength(1);
+		expect(own[0]?.subject).not.toContain("alpha");
+		expect(own[0]?.reason).toContain("network unreachable (ECONNRESET)");
+	});
+
+	test("P3 keeps only the FIRST line of a multi-line message", async () => {
+		const { report } = await runBoth([updateItem("omega@magus")], {
+			"omega@magus": {
+				lands: "2.0.0",
+				loads: "2.0.0",
+				throws:
+					"network unreachable (ECONNRESET)\n    at fetchCatalog (/opt/x/fetch.js:12:7)\n    at async main (/opt/x/main.js:3:1)",
+			},
+		});
+
+		const row = rowNaming(report as FailureReport, "omega")[0];
+		expect(row?.reason).toContain("network unreachable (ECONNRESET)");
+		expect(row?.reason).not.toContain("\n");
+		expect(row?.reason).not.toContain("fetchCatalog");
+		expect(row?.reason).not.toContain("main.js");
+	});
+
+	test("P3 two exceptions with the same message stay separate entries", async () => {
+		const { report } = await runBoth(
+			[updateItem("one@magus"), updateItem("two@magus")],
+			{
+				"one@magus": { lands: "2.0.0", loads: "2.0.0", throws: "boom" },
+				"two@magus": { lands: "2.0.0", loads: "2.0.0", throws: "boom" },
+			},
+		);
+
+		const r = report as FailureReport;
+		expect(r.rows).toHaveLength(2);
+		expect(rowNaming(r, "one")[0]).not.toBe(rowNaming(r, "two")[0]);
+	});
+
+	test("P3 pure report: an exception is not merged with a worded reason of the same text", () => {
+		const report = pluginFailureReport([
+			{
+				pluginId: "one@magus",
+				verb: "updated",
+				detail: "the folder could not be written",
+			},
+			{
+				pluginId: "two@magus",
+				verb: "updated",
+				detail: "the folder could not be written\nstack line",
+				exception: true,
+			},
+		]) as FailureReport;
+
+		expect(report.rows).toHaveLength(2);
+		const two = rowNaming(report, "two")[0];
+		expect(two?.reason).not.toContain("stack line");
+	});
+});
+
+// ---------------------------------------------------------------------------
+// P4 the shared fix
+// ---------------------------------------------------------------------------
+
+describe("P4 one fix, only when every entry shares it", () => {
+	/** Each failure kind's fix, from a report where two plugins fail that way. */
+	async function fixPerKind() {
+		const fixOf = new Map<string, string | null>();
+		for (const kind of Object.keys(KINDS)) {
+			const { report } = await runKinds([
+				[kind, "first@magus"],
+				[kind, "second@magus"],
+			]);
+			if (report) fixOf.set(kind, report.fix);
+		}
+		return fixOf;
+	}
+
+	test("P4 the spec's example fix is offered for at least one kind of plugin failure", async () => {
+		// P4 cites `Run magus update to try again`; if no plugin failure ever
+		// carries a fix, the popup's fix line is unreachable from this screen.
+		const fixOf = await fixPerKind();
+		expect(fixOf.size).toBeGreaterThanOrEqual(5);
+		expect(
+			[...fixOf.entries()].filter(([, f]) => f !== null).map(([k]) => k),
+		).not.toEqual([]);
+	});
+
+	test("P4 a mixed report's fix is the shared fix when both kinds have it, else none", async () => {
+		const fixOf = await fixPerKind();
+		// Every kind above is a failure the engine reports.
+		expect(fixOf.size).toBeGreaterThanOrEqual(5);
+
+		const mismatches: string[] = [];
+		const known = [...fixOf.keys()];
+		for (const a of known) {
+			for (const b of known) {
+				if (a >= b) continue;
+				const { report } = await runKinds([
+					[a, "first@magus"],
+					[b, "second@magus"],
+				]);
+				const fa = fixOf.get(a) ?? null;
+				const fb = fixOf.get(b) ?? null;
+				const expected = fa === fb ? fa : null;
+				if ((report?.fix ?? null) !== expected) {
+					mismatches.push(
+						`${a} + ${b}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(report?.fix)}`,
+					);
+				}
+			}
+		}
+		expect(mismatches).toEqual([]);
+	});
+
+	test("P4 a fix is not repeated inside any entry", async () => {
+		for (const kind of Object.keys(KINDS)) {
+			const { report } = await runKinds([
+				[kind, "first@magus"],
+				[kind, "second@magus"],
+			]);
+			if (!report?.fix) continue;
+			for (const row of report.rows) {
+				expect(row.reason).not.toContain(report.fix);
+			}
+		}
+	});
+
+	test("P4 rendered: the fix appears once, below every entry", async () => {
+		const fix = "Run magus update to try again";
+		const lines = await renderPopup(
+			{
+				headline: "3 plugins were not updated",
+				rows: [
+					{ subject: "alpha, bravo", reason: "the download was interrupted" },
+					{ subject: "charlie", reason: "the folder could not be written" },
+				],
+				fix,
+			},
+			100,
+		);
+
+		const at = lines.flatMap((l, i) => (l.includes(fix) ? [i] : []));
+		expect(at).toHaveLength(1);
+		const fixLine = at[0] as number;
+		for (const needle of [
+			"alpha",
+			"charlie",
+			"the download was interrupted",
+			"the folder could not be written",
+		]) {
+			const idx = lines.findIndex((l) => l.includes(needle));
+			expect({ needle, before: idx >= 0 && idx < fixLine }).toEqual({
+				needle,
+				before: true,
+			});
+		}
+	});
+
+	test("P4 rendered: no fix → no fix line", async () => {
+		const lines = await renderPopup(
+			{
+				headline: "2 plugins were not updated",
+				rows: [
+					{ subject: "alpha", reason: "the download was interrupted" },
+					{ subject: "charlie", reason: "the folder could not be written" },
+				],
+				fix: null,
+			},
+			100,
+		);
+		const text = lines.join("\n");
+		expect(text).toContain("alpha");
+		expect(text).not.toContain("try again");
+		expect(text).not.toContain("Run magus");
+	});
+});
+
+// ---------------------------------------------------------------------------
+// P5 successes
+// ---------------------------------------------------------------------------
+
+describe("P5 plugins that succeeded are not listed", () => {
+	test("P5 only the failed plugin is named; the headline counts only it", async () => {
+		const { report } = await runBoth(
+			[
+				updateItem("alpha@magus"),
+				updateItem("bravo@magus"),
+				installItem("charlie@magus"),
+			],
+			{
+				"alpha@magus": { lands: "2.0.0", loads: "1.0.0" },
+				"bravo@magus": { lands: "2.0.0", loads: "2.0.0" },
+				"charlie@magus": { lands: "2.0.0", loads: "2.0.0" },
+			},
+		);
+
+		const r = report as FailureReport;
+		expect(r.headline).toBe("alpha was not updated");
+		const all = reportTexts(r).join("\n");
+		expect(all).not.toContain("bravo");
+		expect(all).not.toContain("charlie");
+	});
+
+	test("P5 control: nothing failed → no popup", async () => {
+		const { report } = await runBoth([updateItem("alpha@magus")], {
+			"alpha@magus": { lands: "2.0.0", loads: "2.0.0" },
+		});
+		expect(report).toBeNull();
+	});
+});
+
+// ---------------------------------------------------------------------------
+// P6 one source of wording
+// ---------------------------------------------------------------------------
+
+describe("P6 an entry's reason is the CLI's ✗ row wording for that item", () => {
+	test("P6 each single-plugin entry's reason is contained in that plugin's CLI ✗ row", async () => {
+		const spec = Object.keys(KINDS).map(
+			(kind, i) => [kind, `plug${i}@magus`] as [string, string],
+		);
+		const { report, result, cliRowFor } = await runKinds(spec);
+
+		const problems: string[] = [];
+		for (const id of result.failed) {
+			const name = pluginName(id);
+			const row = rowNaming(report as FailureReport, name)[0];
+			const cli = cliRowFor(id);
+			if (!row || !cli) {
+				problems.push(`${name}: entry ${!!row}, cli row ${!!cli}`);
+				continue;
+			}
+			// A group at differing versions drops them (P2); that is not this test.
+			const shared = result.failed.filter(
+				(other) =>
+					other !== id &&
+					rowNaming(report as FailureReport, pluginName(other))[0] === row,
+			);
+			if (shared.length > 0) continue;
+			if (!cli.includes(row.reason)) {
+				problems.push(`${name}: "${row.reason}" not in "${cli}"`);
+			}
+		}
+		expect(problems).toEqual([]);
+	});
+
+	test("P6 plugins grouped at the SAME versions: the shared reason is in each one's CLI row", async () => {
+		const { report, cliRowFor } = await runKinds([
+			["update lands, older version still loads", "alpha@magus"],
+			["update lands, older version still loads", "bravo@magus"],
+		]);
+
+		const r = report as FailureReport;
+		expect(r.rows).toHaveLength(1);
+		const reason = r.rows[0]?.reason ?? "";
+		expect(cliRowFor("alpha@magus")).toContain(reason);
+		expect(cliRowFor("bravo@magus")).toContain(reason);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// P7 internal words
+// ---------------------------------------------------------------------------
+
+describe("P7 the popup names no internals", () => {
+	test("P7 no headline, subject, reason or fix carries an internal word, across worded failures", async () => {
+		const spec = Object.keys(KINDS)
+			.filter((k) => k !== "update threw")
+			.map((kind, i) => [kind, `plug${i}@magus`] as [string, string]);
+		const { report } = await runKinds(spec);
+
+		const texts = reportTexts(report as FailureReport);
+		expect(texts.length).toBeGreaterThan(2);
+		for (const t of texts) {
+			expect({ text: t, leaks: leaks(t) }).toEqual({ text: t, leaks: [] });
+		}
+	});
+
+	test("P7 each single-kind report is clean, including its fix", async () => {
+		for (const kind of Object.keys(KINDS)) {
+			const { report } = await runKinds([
+				[kind, "first@magus"],
+				[kind, "second@magus"],
+			]);
+			if (!report) continue;
+			for (const t of reportTexts(report)) {
+				expect({ kind, text: t, leaks: leaks(t) }).toEqual({
+					kind,
+					text: t,
+					leaks: [],
+				});
+			}
+		}
+	});
+});
+
+// ---------------------------------------------------------------------------
+// P8 rendering at 50 columns
+// ---------------------------------------------------------------------------
+
+describe("P8 the popup at 50 columns", () => {
+	const names = [
+		"design-tokens-kit",
+		"storybook-bridge",
+		"screenshot-differ",
+		"component-auditor",
+	];
+
+	test("P8 plugin names sharing a long subject are each drawn whole on one line", async () => {
+		const report = pluginFailureReport(
+			names.map((n) => ({
+				pluginId: `${n}@magus`,
+				verb: "updated" as const,
+				detail:
+					"installed v2.0.0, but Claude Code still loads v1.0.0 in this folder",
+			})),
+		) as FailureReport;
+		// The subject is wider than the popup can be, so it must break somewhere.
+		expect(report.rows).toHaveLength(1);
+		expect(report.rows[0]?.subject.length).toBeGreaterThan(50);
+
+		const lines = await renderPopup(report, 50);
+
+		for (const n of names) {
+			expect({ name: n, whole: lines.some((l) => l.includes(n)) }).toEqual({
+				name: n,
+				whole: true,
+			});
+		}
+	});
+
+	test("P8 a long reason wraps onto several lines with nothing cut off", async () => {
+		const reason =
+			"the plugin catalogue could not be fetched because the remote host answered with an unexpected status while this project folder was being refreshed";
+		const report = pluginFailureReport([
+			{
+				pluginId: "design-tokens-kit@magus",
+				verb: "updated",
+				detail: reason,
+				exception: true,
+			},
+		]) as FailureReport;
+
+		const lines = await renderPopup(report, 50);
+
+		expect(flatten(lines)).toContain(reason.replace(/\s/g, ""));
+		const first = lines.findIndex((l) => l.includes("catalogue"));
+		const last = lines.findIndex((l) => l.includes("refreshed"));
+		expect(first).toBeGreaterThanOrEqual(0);
+		expect(last).toBeGreaterThan(first);
+		expect(lines.some((l) => l.includes("design-tokens-kit"))).toBe(true);
+	});
+
+	test("P8 the popup fits in 50 columns: nothing drawn is cut at the right edge", async () => {
+		const report = pluginFailureReport(
+			names.map((n, i) => ({
+				pluginId: `${n}@magus`,
+				verb: "updated" as const,
+				detail:
+					i % 2 === 0
+						? "installed v2.0.0, but Claude Code still loads v1.0.0 in this folder"
+						: "the folder could not be written because another program holds it open",
+			})),
+		) as FailureReport;
+
+		const lines = await renderPopup(report, 50);
+		const flat = flatten(lines);
+
+		for (const t of [report.headline, ...report.rows.map((r) => r.reason)]) {
+			expect({ text: t, drawn: flat.includes(t.replace(/\s/g, "")) }).toEqual({
+				text: t,
+				drawn: true,
+			});
+		}
+	});
+});