magus-cli 7.3.0 → 7.4.0

package/src/__tests__/tabbar-layout.test.ts

@@ -1,71 +1,83 @@
 import { describe, expect, test } from "bun:test";
-import { TABS, barWidth, layoutTabs } from "../ui/components/TabBar.js";
+import {
+	TABS,
+	type TabLayout,
+	barWidth,
+	layoutTabs,
+} from "../ui/components/TabBar.js";
 
 const FULL = TABS.map((t) => `${t.key}:${t.label}`);
 const FULL_WIDTH = barWidth(FULL);
 
-/** The widest the compacted bar ever gets — whichever active label is longest. */
+/** Columns a layout actually paints. */
+const painted = (layout: TabLayout) => barWidth(layout.texts, layout.padded);
+
+/** The widest the key-only bar ever gets — whichever active label is longest. */
 const WIDEST_COMPACT = Math.max(
-	...TABS.map((tab) => barWidth(layoutTabs(TABS, tab.screen, 0))),
+	...TABS.map((tab) => painted(layoutTabs(TABS, tab.screen, 0))),
 );
 
 describe("tab bar layout", () => {
-	test("shows every label when the bar fits", () => {
-		expect(layoutTabs(TABS, "plugins", FULL_WIDTH)).toEqual(FULL);
+	test("shows every label, padded, when the full bar fits", () => {
+		expect(layoutTabs(TABS, "plugins", FULL_WIDTH)).toEqual({
+			texts: FULL,
+			padded: true,
+		});
 	});
 
-	test("drops inactive labels when the bar does not fit", () => {
-		// A 94-column pane leaves ~90 usable, and ten full tabs need ~110 — the
-		// width at which OpenTUI clipped each cell into a meaningless stub.
-		const texts = layoutTabs(TABS, "styles", 90);
-		expect(texts).toContain("9:Styles");
-		expect(texts).toContain("1");
-		expect(texts).not.toContain("1:Plugins");
+	test("drops the padding before it drops any label", () => {
+		// A 94-column pane leaves 90 usable. Ten padded tabs need 110, but the
+		// same ten names unpadded need exactly 90 — so every tab keeps its name.
+		// The old rule jumped straight to bare numbers here.
+		expect(layoutTabs(TABS, "styles", 90)).toEqual({
+			texts: FULL,
+			padded: false,
+		});
 	});
 
-	test("the compact bar actually fits a narrow pane", () => {
-		// The point of compacting is that the result fits. If it did not, the
-		// fallback would just be a differently-truncated mess.
-		expect(barWidth(layoutTabs(TABS, "styles", 90))).toBeLessThanOrEqual(90);
+	test("shortens inactive labels to prefixes before dropping them", () => {
+		const layout = layoutTabs(TABS, "styles", 70);
+		expect(layout.texts).toContain("9:Styles");
+		expect(layout.texts).not.toContain("1");
+		expect(layout.texts.find((t) => t.startsWith("1:"))).toMatch(/^1:Plu/);
+		expect(painted(layout)).toBeLessThanOrEqual(70);
 	});
 
-	test("the full bar no longer fits a standard window, so compacting is the norm", () => {
-		// The tenth tab pushed the full bar past 100 columns. That is not a
-		// regression — it is why the compact form has to stay readable, and why
-		// the test below measures it rather than assuming.
+	test("a 100-column window names every tab", () => {
+		// The tenth tab pushed the padded bar past 100 columns. That no longer
+		// costs the names: at 96 usable columns the unpadded bar fits whole.
 		expect(FULL_WIDTH).toBeGreaterThan(100);
-		expect(layoutTabs(TABS, "models", 100)).not.toEqual(FULL);
+		expect(layoutTabs(TABS, "models", 96).texts).toEqual(FULL);
 	});
 
-	test("the compact bar fits an 80-column terminal, on every tab", () => {
-		// The real question a tenth tab raises. ScreenLayout pads the bar by 1
-		// each side inside a container padded by 1, so an 80-column terminal
-		// leaves 76 — and the widest compact bar is well under it.
+	test("the bar fits an 80-column terminal, on every tab", () => {
+		// ScreenLayout pads the bar by 1 each side inside a container padded by
+		// 1, so an 80-column terminal leaves 76.
 		expect(WIDEST_COMPACT).toBeLessThanOrEqual(76);
 		for (const tab of TABS) {
-			expect(barWidth(layoutTabs(TABS, tab.screen, 76))).toBeLessThanOrEqual(
-				76,
-			);
+			expect(painted(layoutTabs(TABS, tab.screen, 76))).toBeLessThanOrEqual(76);
 		}
 	});
 
 	test("keeps the label of whichever tab is active", () => {
 		for (const tab of TABS) {
-			const texts = layoutTabs(TABS, tab.screen, 40);
+			const { texts } = layoutTabs(TABS, tab.screen, 40);
 			expect(texts).toContain(`${tab.key}:${tab.label}`);
-			// Exactly one tab keeps its label.
+			// At 40 columns only the active tab keeps a label.
 			expect(texts.filter((t) => t.includes(":"))).toHaveLength(1);
 		}
 	});
 
 	test("compacting never changes how many tabs are drawn", () => {
-		expect(layoutTabs(TABS, "plugins", 20)).toHaveLength(TABS.length);
-		expect(layoutTabs(TABS, "plugins", 10_000)).toHaveLength(TABS.length);
+		expect(layoutTabs(TABS, "plugins", 20).texts).toHaveLength(TABS.length);
+		expect(layoutTabs(TABS, "plugins", 10_000).texts).toHaveLength(TABS.length);
 	});
 
 	test("barWidth counts padding and separators", () => {
 		// " a " + "│" + " bb " = 3 + 1 + 4
 		expect(barWidth(["a", "bb"])).toBe(8);
+		// "a" + "│" + "bb" = 1 + 1 + 2
+		expect(barWidth(["a", "bb"], false)).toBe(4);
 		expect(barWidth([])).toBe(0);
 	});
 

package/src/__tests__/theme-adaptive-colors.test.ts

@@ -24,8 +24,10 @@ import { CONTRAST_REFERENCE, brand, theme } from "../ui/theme.js";
  *     can clear a text-grade ratio against that terminal's own background).
  *  2. Every accent clears 3:1 against BOTH reference backgrounds.
  *  3. Ink on our own badges clears 4.5:1 against that badge.
- *  4. The three scope colours are far enough apart in hue to read as squares.
- *  5. No component invents a colour outside the palette.
+ *  4. No component invents a colour outside the palette.
+ *
+ * The scope squares no longer own a hue each (see theme.ts): position names the
+ * scope and shape says the state, so there is no scope palette to measure here.
  */
 
 // ─── Contrast maths (WCAG 2.1 relative luminance) ─────────────────────────────
@@ -48,37 +50,6 @@ function contrastRatio(a: string, b: string): number {
 	return (hi + 0.05) / (lo + 0.05);
 }
 
-/**
- * Perceptual distance (CIE76 ΔE) in L*a*b*.
- *
- * Contrast ratio is the wrong tool for "are these two swatches telling apart":
- * it only compares luminance, and the scope colours are deliberately close in
- * luminance — that is precisely what lets each of them clear 3:1 against both a
- * light and a dark background. Measured, they sit at ratios of 1.00-1.03 to each
- * other while being obviously different colours. ΔE sees the hue difference that
- * a luminance ratio is blind to.
- */
-function deltaE(aHex: string, bHex: string): number {
-	const toLab = (hex: string): [number, number, number] => {
-		const n = hex.replace("#", "");
-		const [r, g, b] = [0, 2, 4].map((i) => {
-			const c = Number.parseInt(n.slice(i, i + 2), 16) / 255;
-			return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
-		});
-		// sRGB -> XYZ (D65), then XYZ -> Lab
-		const x = (r * 0.4124 + g * 0.3576 + b * 0.1805) / 0.95047;
-		const y = r * 0.2126 + g * 0.7152 + b * 0.0722;
-		const z = (r * 0.0193 + g * 0.1192 + b * 0.9505) / 1.08883;
-		const f = (t: number) =>
-			t > 0.008856 ? Math.cbrt(t) : 7.787 * t + 16 / 116;
-		const [fx, fy, fz] = [f(x), f(y), f(z)];
-		return [116 * fy - 16, 500 * (fx - fy), 200 * (fy - fz)];
-	};
-	const [l1, a1, b1] = toLab(aHex);
-	const [l2, a2, b2] = toLab(bHex);
-	return Math.hypot(l1 - l2, a1 - a2, b1 - b2);
-}
-
 /** WCAG threshold for UI components and large text. 4.5 is unreachable against
  *  both a light and a dark background at once — the luminance bands do not overlap. */
 const UI_CONTRAST = 3;
@@ -129,9 +100,9 @@ describe("accents are legible on light AND dark terminals", () => {
 
 	test("badge ink clears 4.5:1 on every badge colour we paint", () => {
 		const failures: string[] = [];
-		for (const [tone, colors] of Object.entries(theme.category)) {
+		for (const [tone, colors] of Object.entries(theme.badge)) {
 			const r = contrastRatio(brand.ink, colors.bg as string);
-			if (r < INK_CONTRAST) failures.push(`category.${tone} ${r.toFixed(2)}`);
+			if (r < INK_CONTRAST) failures.push(`badge.${tone} ${r.toFixed(2)}`);
 		}
 		for (const key of ["defaultBg", "primaryBg", "dangerBg"] as const) {
 			const r = contrastRatio(brand.ink, theme.hints[key]);
@@ -177,30 +148,6 @@ describe("accents are legible on light AND dark terminals", () => {
 			Object.keys(theme.meta).sort(),
 		);
 	});
-
-	test("the three scope colours are perceptually far apart", () => {
-		// They render as single-character squares, where a subtle shift is not
-		// readable at all. Deferring to ANSI put project and local on slots 2 and 3,
-		// which one real theme drew as two near-identical olives — the reason this
-		// rule exists. ΔE > 25 is comfortably past "different colour" (~2.3 is the
-		// just-noticeable difference); the bar is set high because these are tiny.
-		const scopes = Object.entries(theme.scopes) as [string, string][];
-		const tooClose: string[] = [];
-		for (let i = 0; i < scopes.length; i++) {
-			for (let j = i + 1; j < scopes.length; j++) {
-				const d = deltaE(scopes[i][1], scopes[j][1]);
-				if (d < 25)
-					tooClose.push(`${scopes[i][0]}~${scopes[j][0]} ΔE=${d.toFixed(1)}`);
-			}
-		}
-		expect(tooClose).toEqual([]);
-		expect(new Set(scopes.map(([, hex]) => hex)).size).toBe(scopes.length);
-	});
-
-	test("ΔE agrees that identical colours are identical (guards the metric)", () => {
-		expect(deltaE(brand.success, brand.success)).toBeCloseTo(0, 5);
-		expect(deltaE("#000000", "#FFFFFF")).toBeGreaterThan(90);
-	});
 });
 
 describe("the canvas stays the terminal's", () => {

package/src/__tests__/tool-probe.test.ts

@@ -605,7 +605,7 @@ describe("isInside — containment in the package's OWN directory", () => {
 // ── ownership through the probe, with a fake IO ─────────────────────────────
 
 describe("probeTool — ownership decides managed", () => {
-	test("native claude is NOT npm-owned: not-managed, never an upgrade", async () => {
+	test("native claude is its own installer's: managed, `claude update`, never the npm veto", async () => {
 		const io = fakeIO({
 			onPath: { claude: "/Users/j/.local/bin/claude" },
 			real: {
@@ -616,6 +616,10 @@ describe("probeTool — ownership decides managed", () => {
 				"npm root -g": { stdout: "/Users/j/.local/lib/node_modules\n" },
 				"claude --version": { stdout: "2.1.268 (Claude Code)\n" },
 			},
+			fetch: {
+				"https://registry.npmjs.org/-/package/@anthropic-ai%2Fclaude-code/dist-tags":
+					{ ok: true, body: { latest: "2.1.270" } },
+			},
 		});
 		const s = spec({
 			name: "claude",
@@ -623,16 +627,21 @@ describe("probeTool — ownership decides managed", () => {
 			package: "@anthropic-ai/claude-code",
 			check: "claude --version",
 		});
-		// The read-back path's opt-in. Planning never runs a check command —
-		// see "a check command is never run while planning" below.
 		const f = await probeTool(s, io, { allowCheckCommand: true });
 		expect(f).toMatchObject({
 			present: true,
-			managed: false,
+			managed: true,
 			installed: "2.1.268",
+			latest: "2.1.270",
+			upgradeCommand: { cmd: "claude", args: ["update"] },
 		});
-		expect(classifyTool(s, f).reason).toBe("not-managed");
-		expect(io.fetches).toEqual([]);
+		expect(classifyTool(s, f)).toMatchObject({
+			state: "upgrade",
+			reason: "behind",
+			target: "2.1.270",
+		});
+		// The version is the directory entry's name: nothing ran, npm was not asked.
+		expect(io.calls).toEqual([]);
 	});
 
 	test("bun-owned codex: version from its package.json, latest from dist-tags", async () => {
@@ -732,27 +741,41 @@ describe("probeTool — ownership decides managed", () => {
 		expect(classifyTool(s, await probeTool(s, io)).reason).toBe("held-back");
 	});
 
-	test("crush under nvm while PATH's npm writes elsewhere: not-managed", async () => {
+	test("crush under nvm while PATH's npm writes elsewhere: managed through --prefix", async () => {
+		const prefix = "/Users/j/.nvm/versions/node/v24.14.0";
+		const pkgDir = `${prefix}/lib/node_modules/@charmland/crush`;
 		const io = fakeIO({
-			onPath: { crush: "/Users/j/.nvm/versions/node/v24.14.0/bin/crush" },
-			real: {
-				"/Users/j/.nvm/versions/node/v24.14.0/bin/crush":
-					"/Users/j/.nvm/versions/node/v24.14.0/lib/node_modules/@charmland/crush/run-crush.js",
-			},
+			onPath: { crush: `${prefix}/bin/crush` },
+			real: { [`${prefix}/bin/crush`]: `${pkgDir}/run-crush.js` },
+			files: { [`${pkgDir}/package.json`]: '{"version":"0.7.1"}' },
 			exec: {
 				"npm root -g": { stdout: "/Users/j/.local/lib/node_modules\n" },
 				"crush --version": { stdout: "crush version v0.7.1\n" },
 			},
+			fetch: {
+				"https://registry.npmjs.org/-/package/@charmland%2Fcrush/dist-tags": {
+					ok: true,
+					body: { latest: "0.8.0" },
+				},
+			},
 		});
 		const s = spec({ name: "crush", via: "npm", package: "@charmland/crush" });
-		const status = classifyTool(
-			s,
-			await probeTool(s, io, { allowCheckCommand: true }),
-		);
-		expect(status.reason).toBe("not-managed");
-		expect(status.note).toContain(
-			"npm (root /Users/j/.local/lib/node_modules)",
-		);
+		const f = await probeTool(s, io, { allowCheckCommand: true });
+		expect(f).toMatchObject({
+			managed: true,
+			installed: "0.7.1",
+			latest: "0.8.0",
+			upgradeCommand: {
+				cmd: "npm",
+				args: ["install", "-g", "--prefix", prefix, "@charmland/crush@latest"],
+			},
+		});
+		expect(classifyTool(s, f)).toMatchObject({
+			state: "upgrade",
+			target: "0.8.0",
+		});
+		// Version from the package.json, not by running the tool.
+		expect(io.calls).toEqual(["npm root -g"]);
 	});
 
 	test("go: tmux-mcp pinned v2.0.0 reads build info only — no network", async () => {
@@ -843,10 +866,12 @@ describe("probeTool — ownership decides managed", () => {
 		const [f] = await probeTools([hostile], io);
 		expect(io.calls).toEqual(["npm root -g"]);
 		expect(f?.installed).toBeNull();
-		// Cannot tell ⇒ unknown, so it is reported and never applied.
+		// Cannot tell ⇒ unknown, so it is reported and never applied. The file
+		// is outside npm's tree, so the reason is ownership (R9.9), not the
+		// unread version that follows from it.
 		expect(classifyTool(hostile, f!)).toMatchObject({
 			state: "unknown",
-			reason: "version-unreadable",
+			reason: "not-managed",
 		});
 
 		// Even an honest check command stays unrun while planning.

package/src/__tests__/upgrade-spawn.test.ts

@@ -0,0 +1,355 @@
+/**
+ * `magus upgrade`, end to end, with node:child_process replaced.
+ *
+ * The upgrade must install the npm PACKAGE (`package.json` `name`,
+ * `magus-cli`) at `latest`, with whichever package manager owns the active
+ * `magus` binary. The bare npm name is an unrelated package: installing it
+ * leaves magus where it was. The duplicate-install hint must name the real
+ * package too. The probes that look for the COMMAND (`which magus`,
+ * `bun pm -g bin`, `npm prefix -g`) stay as they are.
+ *
+ * SAFETY. This is the one test that could run a real global install, so three
+ * independent layers stand between it and one:
+ *   1. identity guard: before every call, the imported `spawn` and `execSync`
+ *      must BE the fakes, or the test throws without calling anything;
+ *   2. PATH is an empty temp directory for the duration of the call, so even a
+ *      real `spawn("bun", ...)` finds nothing (bun 1.4.0's child_process.spawn
+ *      honours a runtime PATH change; `Bun.which` does not, so it is not used);
+ *   3. the module mock is restored in afterAll, the way cli-router.test.ts
+ *      restores its own, so no later file in the same process inherits it.
+ * Every other process launcher on the module is replaced by a fake that
+ * records and throws.
+ *
+ * Written black-box from the API contract.
+ */
+
+import {
+	afterAll,
+	afterEach,
+	beforeAll,
+	beforeEach,
+	describe,
+	expect,
+	mock,
+	test,
+} from "bun:test";
+import * as childProcessNamespace from "node:child_process";
+import { EventEmitter } from "node:events";
+import {
+	mkdirSync,
+	mkdtempSync,
+	readFileSync,
+	realpathSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { stripVTControlCharacters } from "node:util";
+
+// Read at test time: the single source of truth the requirements name.
+const PKG = JSON.parse(
+	readFileSync(join(import.meta.dir, "..", "..", "package.json"), "utf8"),
+) as { name: string; version: string };
+
+const COMMAND = "magus";
+const PACKAGE = "magus-cli";
+const EXPECTED_ARGS = ["install", "-g", `${PACKAGE}@latest`];
+
+// Snapshot the real module BEFORE mocking. mock.module is process-global and
+// updates live namespaces, so the snapshot is what gets put back.
+const realChildProcess: Record<string, unknown> = { ...childProcessNamespace };
+const realDefault = (realChildProcess.default ?? {}) as Record<string, unknown>;
+
+// ---------------------------------------------------------------------------
+// Fakes
+// ---------------------------------------------------------------------------
+
+interface SpawnCall {
+	cmd: string;
+	args: string[];
+	options: Record<string, unknown>;
+}
+
+interface Scenario {
+	/** What `which magus` answers: the active binary. */
+	which: string;
+	/** What `bun pm -g bin` answers. */
+	bunBin: string;
+	/** What `npm prefix -g` answers. */
+	npmPrefix: string;
+	/** The exit code the fake child reports. */
+	exitCode: number;
+}
+
+let scenario: Scenario = { which: "", bunBin: "", npmPrefix: "", exitCode: 0 };
+let spawnCalls: SpawnCall[] = [];
+let execCalls: string[] = [];
+
+function fakeExecSync(command: string, options?: { encoding?: string }) {
+	const text = String(command);
+	execCalls.push(text);
+	let answer: string | undefined;
+	if (text.includes("which magus")) answer = scenario.which;
+	else if (text.includes("bun pm -g bin")) answer = scenario.bunBin;
+	else if (text.includes("npm prefix -g")) answer = scenario.npmPrefix;
+	if (!answer) {
+		throw new Error(`fake execSync has no answer for: ${text}`);
+	}
+	// Mirror Node: a string when an encoding is asked for, a Buffer otherwise.
+	const out = `${answer}\n`;
+	const encoding = options?.encoding;
+	return encoding && encoding !== "buffer" ? out : Buffer.from(out);
+}
+
+function fakeSpawn(
+	cmd: string,
+	args?: readonly string[],
+	options?: Record<string, unknown>,
+) {
+	spawnCalls.push({
+		cmd: String(cmd),
+		args: [...(args ?? [])],
+		options: options ?? {},
+	});
+	const child = Object.assign(new EventEmitter(), {
+		pid: 424242,
+		stdin: null,
+		stdout: null,
+		stderr: null,
+		kill: () => true,
+	});
+	const code = scenario.exitCode;
+	setTimeout(() => {
+		child.emit("exit", code, null);
+		child.emit("close", code, null);
+	}, 0);
+	return child;
+}
+
+function refuse(name: string) {
+	return (...a: unknown[]) => {
+		throw new Error(
+			`upgrade-spawn test refused child_process.${name}(${String(a[0])}): no real process may run here`,
+		);
+	};
+}
+
+const fakes = {
+	spawn: fakeSpawn,
+	execSync: fakeExecSync,
+	spawnSync: refuse("spawnSync"),
+	exec: refuse("exec"),
+	execFile: refuse("execFile"),
+	execFileSync: refuse("execFileSync"),
+	fork: refuse("fork"),
+};
+
+// ---------------------------------------------------------------------------
+// Lifecycle
+// ---------------------------------------------------------------------------
+
+let runUpgradeCommand: () => Promise<number>;
+
+beforeAll(async () => {
+	mock.module("node:child_process", () => ({
+		...realChildProcess,
+		...fakes,
+		default: { ...realDefault, ...fakes },
+	}));
+	// Imported only AFTER the mock, so the module binds to the fakes.
+	({ runUpgradeCommand } = await import("../cli/upgrade.js"));
+});
+
+afterAll(() => {
+	mock.module("node:child_process", () => realChildProcess);
+});
+
+/** Layer 1: refuse to proceed unless the fakes are what callers will get. */
+async function assertChildProcessIsFake(): Promise<void> {
+	const cp = (await import("node:child_process")) as unknown as Record<
+		string,
+		unknown
+	>;
+	if (cp.spawn !== fakeSpawn || cp.execSync !== fakeExecSync) {
+		throw new Error(
+			"SAFETY: node:child_process is not mocked. Refusing to call runUpgradeCommand, which would run a real global install.",
+		);
+	}
+}
+
+let root: string;
+let logs: string[];
+let otherOutput: string[];
+const realLog = console.log;
+const realError = console.error;
+const realWarn = console.warn;
+const realFetch = globalThis.fetch;
+
+beforeEach(() => {
+	// realpath: on macOS the temp dir sits behind a symlink.
+	root = realpathSync(mkdtempSync(join(tmpdir(), "magus-upgrade-spawn-")));
+	const bunBin = join(root, ".bun", "bin");
+	const npmPrefix = join(root, "npm");
+	mkdirSync(bunBin, { recursive: true });
+	mkdirSync(join(npmPrefix, "bin"), { recursive: true });
+	mkdirSync(join(root, "empty-path"));
+	// Two real installs of the command, one per manager (amendment M3).
+	writeFileSync(join(bunBin, COMMAND), "#!/bin/sh\nexit 0\n", { mode: 0o755 });
+	writeFileSync(join(npmPrefix, "bin", COMMAND), "#!/bin/sh\nexit 0\n", {
+		mode: 0o755,
+	});
+
+	scenario = { which: "", bunBin, npmPrefix, exitCode: 0 };
+	spawnCalls = [];
+	execCalls = [];
+	logs = [];
+	otherOutput = [];
+
+	console.log = (...a: unknown[]) => {
+		logs.push(a.map(String).join(" "));
+	};
+	console.error = (...a: unknown[]) => {
+		otherOutput.push(a.map(String).join(" "));
+	};
+	console.warn = (...a: unknown[]) => {
+		otherOutput.push(a.map(String).join(" "));
+	};
+	// No network, in case the upgrade consults the registry first.
+	globalThis.fetch = (async () =>
+		new Response(JSON.stringify({ version: "999.0.0" }), {
+			status: 200,
+			headers: { "content-type": "application/json" },
+		})) as unknown as typeof fetch;
+});
+
+afterEach(() => {
+	console.log = realLog;
+	console.error = realError;
+	console.warn = realWarn;
+	globalThis.fetch = realFetch;
+	rmSync(root, { recursive: true, force: true });
+});
+
+const bunWhich = () => join(scenario.bunBin, COMMAND);
+const npmWhich = () => join(scenario.npmPrefix, "bin", COMMAND);
+
+async function runUpgrade(which: string, exitCode = 0): Promise<number> {
+	scenario.which = which;
+	scenario.exitCode = exitCode;
+	await assertChildProcessIsFake();
+	// Layer 2: nothing is reachable by name while the upgrade runs (M2).
+	const savedPath = process.env.PATH;
+	process.env.PATH = join(root, "empty-path");
+	try {
+		return await runUpgradeCommand();
+	} finally {
+		if (savedPath === undefined) Reflect.deleteProperty(process.env, "PATH");
+		else process.env.PATH = savedPath;
+	}
+}
+
+/** Captured console.log output, one entry per physical line, ANSI removed. */
+function logLines(): string[] {
+	return logs.flatMap((l) => stripVTControlCharacters(l).split("\n"));
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("runUpgradeCommand installs the npm package with the owning manager", () => {
+	test("a bun-owned binary upgrades with `bun install -g <package>@latest`", async () => {
+		const code = await runUpgrade(bunWhich());
+
+		expect(code).toBe(0);
+		expect(spawnCalls).toHaveLength(1);
+		const call = spawnCalls[0]!;
+		expect(call.cmd).toBe("bun");
+		expect(call.args).toEqual(EXPECTED_ARGS);
+		expect(call.args).toEqual(["install", "-g", `${PKG.name}@latest`]);
+		expect(call.options).toMatchObject({ stdio: "inherit", shell: false });
+	});
+
+	test("an npm-owned binary upgrades with `npm install -g <package>@latest`", async () => {
+		// Precondition: nothing in this path may look bun-owned.
+		expect(npmWhich()).not.toContain(".bun");
+		expect(npmWhich()).not.toContain("bun/bin");
+
+		const code = await runUpgrade(npmWhich());
+
+		expect(code).toBe(0);
+		expect(spawnCalls).toHaveLength(1);
+		const call = spawnCalls[0]!;
+		expect(call.cmd).toBe("npm");
+		expect(call.args).toEqual(EXPECTED_ARGS);
+		expect(call.args).toEqual(["install", "-g", `${PKG.name}@latest`]);
+		expect(call.options).toMatchObject({ stdio: "inherit", shell: false });
+	});
+
+	test("a `bun/bin` path without `.bun` also counts as bun-owned", async () => {
+		const dir = join(root, "opt", "bun", "bin");
+		mkdirSync(dir, { recursive: true });
+		const which = join(dir, COMMAND);
+		writeFileSync(which, "#!/bin/sh\nexit 0\n", { mode: 0o755 });
+		expect(which).not.toContain(".bun");
+
+		await runUpgrade(which);
+
+		expect(spawnCalls).toHaveLength(1);
+		expect(spawnCalls[0]!.cmd).toBe("bun");
+		expect(spawnCalls[0]!.args).toEqual(EXPECTED_ARGS);
+	});
+
+	test("resolves with the child's exit code", async () => {
+		const code = await runUpgrade(npmWhich(), 3);
+
+		expect(spawnCalls).toHaveLength(1);
+		expect(code).toBe(3);
+	});
+});
+
+describe("the duplicate-install hint names the npm package", () => {
+	function expectBothHints() {
+		const out = logLines().join("\n");
+		expect(out).toContain(`bun uninstall -g ${PACKAGE}`);
+		expect(out).toContain(`npm uninstall -g ${PACKAGE}`);
+		// Every uninstall hint that was printed targets the package.
+		const hints = logLines().filter((l) => /\buninstall\b/.test(l));
+		expect(hints.length).toBeGreaterThanOrEqual(2);
+		for (const line of hints) {
+			const tokens = line.trim().split(/\s+/);
+			const i = tokens.indexOf("-g");
+			expect(i).toBeGreaterThanOrEqual(0);
+			expect(tokens[i + 1]).toBe(PKG.name);
+		}
+	}
+
+	test("both installs present, bun active: both hints name the package", async () => {
+		await runUpgrade(bunWhich());
+
+		expectBothHints();
+	});
+
+	test("both installs present, npm active: both hints name the package", async () => {
+		await runUpgrade(npmWhich());
+
+		expectBothHints();
+	});
+});
+
+describe("the probes still look for the command (R6)", () => {
+	test("`which magus`, `bun pm -g bin` and `npm prefix -g` are what gets asked", async () => {
+		await runUpgrade(bunWhich());
+
+		const probes = execCalls.join("\n");
+		expect(probes).toContain("bun pm -g bin");
+		expect(probes).toContain("npm prefix -g");
+		// `which` is asked about the COMMAND, not the package.
+		const whichProbe = execCalls
+			.map((c) => c.trim().split(/\s+/))
+			.find((tokens) => tokens.includes("which"));
+		expect(whichProbe).toBeDefined();
+		expect(whichProbe![whichProbe!.indexOf("which") + 1]).toBe(COMMAND);
+	});
+});