magus-cli 7.10.1 → 7.10.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magus-cli",
-  "version": "7.10.1",
+  "version": "7.10.2",
   "description": "TUI tool for managing Claude Code plugins, MCPs, and configuration",
   "type": "module",
   "main": "src/main.tsx",
@@ -65,8 +65,8 @@
     "typescript": "^5.6.3"
   },
   "optionalDependencies": {
-    "magus-cli-darwin-arm64": "7.10.1",
-    "magus-cli-darwin-x64": "7.10.1",
-    "magus-cli-linux-x64": "7.10.1"
+    "magus-cli-darwin-arm64": "7.10.2",
+    "magus-cli-darwin-x64": "7.10.2",
+    "magus-cli-linux-x64": "7.10.2"
   }
 }

package/src/__tests__/blind/c16-probe-adopts-node-global.test.ts

@@ -0,0 +1,323 @@
+/**
+ * Blind tests, contract C16: a tool whose declared installer does not own the
+ * file PATH runs is adopted by the node installer (bun or npm) when that file
+ * lies in bun's global tree or an npm global prefix. Otherwise it stays
+ * external / not-managed with a note that names no path.
+ *
+ * Written from the spec only. Every fact reaches `probeTool` through a
+ * scripted fake `ToolProbeIO`.
+ */
+import { describe, expect, test } from "bun:test";
+import {
+	type ExecResult,
+	type FetchJsonResult,
+	type ToolProbeIO,
+	classifyTool,
+	probeTool,
+} from "../../services/tool-probe.js";
+import type { BinRequirement } from "../../types/index.js";
+
+interface FakeSetup {
+	exec?: Record<string, Partial<ExecResult>>;
+	fetch?: Record<string, FetchJsonResult>;
+	files?: Record<string, string>;
+	real?: Record<string, string>;
+	onPath?: Record<string, string>;
+	env?: Record<string, string>;
+}
+
+function fakeIO(setup: FakeSetup): ToolProbeIO & { calls: string[] } {
+	const calls: string[] = [];
+	return {
+		calls,
+		exec: async (command) => {
+			const key = [command.cmd, ...command.args].join(" ");
+			calls.push(key);
+			const h = setup.exec?.[key];
+			if (h === undefined) {
+				return {
+					code: null,
+					stdout: "",
+					stderr: "",
+					timedOut: false,
+					missing: true,
+				};
+			}
+			return {
+				code: 0,
+				stdout: "",
+				stderr: "",
+				timedOut: false,
+				missing: false,
+				...h,
+			};
+		},
+		fetchJson: async (url) => {
+			const r = setup.fetch?.[url];
+			return r ?? { ok: false, reason: "returned 404" };
+		},
+		readJson: async (file) => {
+			const t = setup.files?.[file];
+			if (t === undefined) return null;
+			try {
+				return JSON.parse(t);
+			} catch {
+				return null;
+			}
+		},
+		readText: async (file) => setup.files?.[file] ?? null,
+		readlink: async () => null,
+		realpath: async (file) => setup.real?.[file] ?? null,
+		resolveExecutable: async (name) => setup.onPath?.[name] ?? null,
+		env: setup.env ?? {},
+		homedir: "/Users/j",
+	};
+}
+
+const BUN_ROOT = "/Users/j/.bun/install/global/node_modules";
+const BREW_ENV = { HOMEBREW_PREFIX: "/opt/homebrew" };
+const CELLAR = { "/opt/homebrew/Cellar": "/opt/homebrew/Cellar" };
+
+const distTags = (pkg: string, latest: string) => ({
+	[`https://registry.npmjs.org/-/package/${pkg.replace("/", "%2F")}/dist-tags`]:
+		{ ok: true, body: { latest } } as FetchJsonResult,
+});
+
+const pkgJson = (name: string, version: string) =>
+	JSON.stringify({ name, version });
+
+/** A tool whose PATH entry resolves into bun's global tree. */
+function bunWorld(
+	bin: string,
+	pkg: string,
+	installed: string,
+	latest: string,
+): FakeSetup {
+	const pkgDir = `${BUN_ROOT}/${pkg}`;
+	const file = `${pkgDir}/dist/index.js`;
+	const onPath = `/Users/j/.bun/bin/${bin}`;
+	return {
+		env: BREW_ENV,
+		onPath: { [bin]: onPath },
+		real: {
+			[onPath]: file,
+			[file]: file,
+			[pkgDir]: pkgDir,
+			[BUN_ROOT]: BUN_ROOT,
+			...CELLAR,
+		},
+		files: { [`${pkgDir}/package.json`]: pkgJson(pkg, installed) },
+		fetch: distTags(pkg, latest),
+	};
+}
+
+const MNEMEX: BinRequirement = {
+	name: "mnemex",
+	via: "brew",
+	formula: "madappgang/tap/mnemex",
+};
+
+describe("C16 case 1: brew spec, file in bun's global tree", () => {
+	test("managed, versions read, bun upgrade command, state upgrade", async () => {
+		const f = await probeTool(
+			MNEMEX,
+			fakeIO(bunWorld("mnemex", "mnemex", "0.36.1", "0.36.2")),
+		);
+		expect(f.managed).toBe(true);
+		expect(f.installed).toBe("0.36.1");
+		expect(f.latest).toBe("0.36.2");
+		expect(f.upgradeCommand).toEqual({
+			cmd: "bun",
+			args: ["install", "-g", "mnemex@latest"],
+		});
+		const s = classifyTool(MNEMEX, f);
+		expect(s.state).toBe("upgrade");
+		expect(s.target).toBe("0.36.2");
+	});
+});
+
+describe("C16 case 2: latest equals installed", () => {
+	test("state is current", async () => {
+		const f = await probeTool(
+			MNEMEX,
+			fakeIO(bunWorld("mnemex", "mnemex", "0.36.2", "0.36.2")),
+		);
+		expect(f.managed).toBe(true);
+		expect(classifyTool(MNEMEX, f).state).toBe("current");
+	});
+});
+
+describe("C16 case 3: scoped package under bun's tree", () => {
+	test("the package is @scope/tool in the upgrade command", async () => {
+		const spec: BinRequirement = {
+			name: "tool",
+			via: "brew",
+			formula: "madappgang/tap/tool",
+		};
+		const f = await probeTool(
+			spec,
+			fakeIO(bunWorld("tool", "@scope/tool", "1.0.0", "1.1.0")),
+		);
+		expect(f.managed).toBe(true);
+		expect(f.installed).toBe("1.0.0");
+		expect(f.latest).toBe("1.1.0");
+		expect(f.upgradeCommand).toEqual({
+			cmd: "bun",
+			args: ["install", "-g", "@scope/tool@latest"],
+		});
+		expect(classifyTool(spec, f).state).toBe("upgrade");
+	});
+});
+
+describe("C16 case 4: npm global prefix", () => {
+	test("brew spec adopted by npm under the root npm reports", async () => {
+		const root = "/usr/local/lib/node_modules";
+		const pkgDir = `${root}/claudish`;
+		const file = `${pkgDir}/dist/index.js`;
+		const spec: BinRequirement = {
+			name: "claudish",
+			via: "brew",
+			formula: "madappgang/tap/claudish",
+		};
+		const f = await probeTool(
+			spec,
+			fakeIO({
+				env: BREW_ENV,
+				onPath: { claudish: "/usr/local/bin/claudish" },
+				real: {
+					"/usr/local/bin/claudish": file,
+					[file]: file,
+					[pkgDir]: pkgDir,
+					[root]: root,
+					...CELLAR,
+				},
+				files: { [`${pkgDir}/package.json`]: pkgJson("claudish", "10.0.0") },
+				exec: { "npm root -g": { stdout: `${root}\n` } },
+				fetch: distTags("claudish", "10.1.0"),
+			}),
+		);
+		expect(f.managed).toBe(true);
+		expect(f.installed).toBe("10.0.0");
+		expect(f.latest).toBe("10.1.0");
+		expect(f.upgradeCommand).toEqual({
+			cmd: "npm",
+			args: ["install", "-g", "claudish@latest"],
+		});
+		const s = classifyTool(spec, f);
+		expect(s.state).toBe("upgrade");
+		expect(s.target).toBe("10.1.0");
+	});
+});
+
+describe("C16 case 5: pinned npm spec, file in bun's tree", () => {
+	const spec: BinRequirement = {
+		name: "tool",
+		via: "npm",
+		package: "tool",
+		version: "1.0.0",
+	};
+	test("managed, target is the pin, command carries tool@1.0.0", async () => {
+		const f = await probeTool(
+			spec,
+			fakeIO({
+				...bunWorld("tool", "tool", "0.9.0", "2.0.0"),
+				exec: { "npm root -g": { stdout: "/usr/local/lib/node_modules\n" } },
+			}),
+		);
+		expect(f.managed).toBe(true);
+		expect(f.installed).toBe("0.9.0");
+		const args = f.upgradeCommand?.args ?? [];
+		expect(args).toContain("tool@1.0.0");
+		expect(args.some((a) => a.includes("@latest"))).toBe(false);
+		const s = classifyTool(spec, f);
+		expect(s.state).toBe("upgrade");
+		expect(s.target).toBe("1.0.0");
+	});
+});
+
+describe("C16 case 6: file in no node tree, brew spec", () => {
+	const spec: BinRequirement = { name: "uv", via: "brew", formula: "uv" };
+	const world: FakeSetup = {
+		env: BREW_ENV,
+		onPath: { uv: "/Users/j/.local/bin/uv" },
+		real: {
+			"/Users/j/.local/bin/uv": "/Users/j/.local/bin/uv",
+			...CELLAR,
+		},
+	};
+	test("external / not-managed, note names who did not install it", async () => {
+		const f = await probeTool(spec, fakeIO(world));
+		const s = classifyTool(spec, f);
+		expect(s.state).toBe("external");
+		expect(s.reason).toBe("not-managed");
+		expect(s.note).toBe("installed outside Homebrew");
+		expect(s.note?.includes("/")).toBe(false);
+	});
+	test("an npm spec says installed outside npm", async () => {
+		const npmSpec: BinRequirement = { name: "uv", via: "npm", package: "uv" };
+		const f = await probeTool(
+			npmSpec,
+			fakeIO({
+				...world,
+				exec: { "npm root -g": { stdout: "/usr/local/lib/node_modules\n" } },
+			}),
+		);
+		const s = classifyTool(npmSpec, f);
+		expect(s.state).toBe("external");
+		expect(s.note).toBe("installed outside npm");
+	});
+	test("a pinned spec in that situation stays unknown", async () => {
+		const pinned: BinRequirement = { ...spec, version: "1.0.0" };
+		const f = await probeTool(pinned, fakeIO(world));
+		expect(classifyTool(pinned, f).state).toBe("unknown");
+	});
+});
+
+describe("C16 case 7: operating-system file", () => {
+	test("zsh in /bin is external with the operating-system note", async () => {
+		const spec: BinRequirement = { name: "zsh", via: "brew", formula: "zsh" };
+		const f = await probeTool(
+			spec,
+			fakeIO({
+				env: BREW_ENV,
+				onPath: { zsh: "/bin/zsh" },
+				real: { "/bin/zsh": "/bin/zsh", ...CELLAR },
+			}),
+		);
+		const s = classifyTool(spec, f);
+		expect(s.state).toBe("external");
+		expect(s.reason).toBe("not-managed");
+		expect(s.note).toBe("comes with the operating system");
+	});
+});
+
+describe("C16 case 8: a Homebrew keg is never adopted as an npm install", () => {
+	test("npm spec, file in a keg's libexec/lib/node_modules", async () => {
+		const keg = "/opt/homebrew/Cellar/gemini-cli/0.46.0/libexec";
+		const pkgDir = `${keg}/lib/node_modules/gemini-pkg`;
+		const file = `${pkgDir}/bundle/gemini.js`;
+		const spec: BinRequirement = {
+			name: "gemini",
+			via: "npm",
+			package: "gemini-pkg",
+		};
+		const f = await probeTool(
+			spec,
+			fakeIO({
+				env: BREW_ENV,
+				onPath: { gemini: "/opt/homebrew/bin/gemini" },
+				real: {
+					"/opt/homebrew/bin/gemini": file,
+					[file]: file,
+					[pkgDir]: pkgDir,
+					...CELLAR,
+				},
+				files: { [`${pkgDir}/package.json`]: pkgJson("gemini-pkg", "0.46.0") },
+				exec: { "npm root -g": { stdout: "/opt/homebrew/lib/node_modules\n" } },
+				fetch: distTags("gemini-pkg", "0.50.0"),
+			}),
+		);
+		expect(f.upgradeCommand?.cmd).not.toBe("npm");
+		expect(classifyTool(spec, f).state).not.toBe("upgrade");
+	});
+});

package/src/__tests__/blind/c17-misdirected-update-already-landed.test.ts

@@ -0,0 +1,271 @@
+import {
+	afterAll,
+	beforeAll,
+	beforeEach,
+	describe,
+	expect,
+	test,
+} from "bun:test";
+import { execFileSync } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+import fs from "fs-extra";
+import {
+	loadedVersionHere,
+	repairStaleLoad,
+} from "../../services/claude-settings.js";
+import {
+	type PluginApplyDeps,
+	applyPlugins,
+} from "../../services/update-engine.js";
+import type {
+	InstalledPluginEntry,
+	InstalledPluginsRegistry,
+} from "../../types/index.js";
+
+/**
+ * Written blind from a spec. The row Claude Code picks for `plugin update`
+ * already holds the target, so the update writes nothing and no row moves.
+ * magus must treat it as the same misdirection as when a row moves.
+ */
+
+const GIT_CFG = [
+	"-c",
+	"user.name=test",
+	"-c",
+	"user.email=test@example.com",
+	"-c",
+	"commit.gpgsign=false",
+	"-c",
+	"init.defaultBranch=main",
+];
+const git = (cwd: string, ...args: string[]) =>
+	execFileSync("git", [...GIT_CFG, ...args], { cwd, encoding: "utf8" }).trim();
+
+const PLUGIN = "madbench@magus";
+const SAME_REPO_DETAIL =
+	"project → 0.5.0 · Claude Code updated another folder of this repository instead of this one — this folder now loads v0.5.0 too";
+
+let base: string;
+let mainTree: string;
+let here: string;
+let gone: string;
+let otherRepo: string;
+let root: string;
+let registryFile: string;
+
+const cacheFor = (version: string) =>
+	path.join(root, "cache", "magus", "madbench", version);
+
+const row = (
+	over: Partial<InstalledPluginEntry> & { version: string },
+): InstalledPluginEntry => ({
+	scope: "project",
+	installPath: cacheFor(over.version),
+	installedAt: "2026-01-01T00:00:00.000Z",
+	lastUpdated: "2026-01-01T00:00:00.000Z",
+	...over,
+});
+
+async function writeRegistry(rows: InstalledPluginEntry[]): Promise<void> {
+	const registry: InstalledPluginsRegistry = {
+		version: 2,
+		plugins: { [PLUGIN]: rows },
+	};
+	await fs.outputJson(registryFile, registry, { spaces: 2 });
+}
+
+const readRegistry = (): Promise<InstalledPluginsRegistry> =>
+	fs.readJson(registryFile);
+
+const versionsByPath = async () =>
+	(await readRegistry()).plugins[PLUGIN].map((e) => [e.projectPath, e.version]);
+
+const hereVersion = async () =>
+	(await readRegistry()).plugins[PLUGIN].find((e) => e.projectPath === here)
+		?.version;
+
+beforeAll(async () => {
+	base = await fs.realpath(
+		await fs.mkdtemp(path.join(os.tmpdir(), "magus-c17-")),
+	);
+	mainTree = path.join(base, "magus-src");
+	here = path.join(mainTree, ".claude", "worktrees", "madbench");
+	gone = path.join(mainTree, ".claude", "worktrees", "gone");
+	otherRepo = path.join(base, "unrelated");
+
+	await fs.ensureDir(mainTree);
+	git(mainTree, "init", "-q");
+	await fs.writeFile(path.join(mainTree, "README.md"), "hello\n");
+	git(mainTree, "add", "-A");
+	git(mainTree, "commit", "-qm", "initial");
+	git(mainTree, "worktree", "add", "-q", "-b", "madbench", here);
+	git(mainTree, "worktree", "add", "-q", "-b", "gone", gone);
+	await fs.remove(gone);
+
+	await fs.ensureDir(otherRepo);
+	git(otherRepo, "init", "-q");
+});
+
+afterAll(async () => {
+	if (base) await fs.remove(base);
+});
+
+beforeEach(async () => {
+	root = await fs.mkdtemp(path.join(base, "plugins-"));
+	registryFile = path.join(root, "installed_plugins.json");
+	for (const v of ["0.3.0", "0.4.0", "0.5.0", "0.6.0"]) {
+		await fs.ensureDir(cacheFor(v));
+	}
+});
+
+/** `claude plugin update` that finds its row already on the target: writes nothing. */
+function deps(): PluginApplyDeps {
+	return {
+		install: async () => {},
+		update: async () => {},
+		repair: async () => {},
+		readInstalled: async () =>
+			(await readRegistry()).plugins[PLUGIN].find((e) => e.projectPath === here)
+				?.version ?? null,
+		saveInstalled: async () => {},
+		registryRows: async () => (await readRegistry()).plugins[PLUGIN],
+		repairStaleLoad: (id, target, projectPath) =>
+			repairStaleLoad(id, target, projectPath, root),
+		loadedVersion: (id, projectPath) =>
+			loadedVersionHere(id, projectPath, root),
+	};
+}
+
+const item = (target: string) => ({
+	pluginId: PLUGIN,
+	pinned: "latest",
+	installed: "0.4.0",
+	available: target,
+	target,
+	action: "update" as const,
+	reason: "behind" as const,
+	scopes: ["project" as const],
+	beforeVersions: { project: "0.4.0" },
+});
+
+function collect() {
+	const details: string[] = [];
+	return {
+		details,
+		reporter: {
+			begin: () => {},
+			finish: (_ok: boolean, _name: string, detail: string) =>
+				details.push(detail),
+			detach: <T>(work: () => T) => work(),
+		},
+	};
+}
+
+const NO_CHANGE = `no change — the installer exited 0 but ${PLUGIN} is still 0.4.0`;
+
+describe("a misdirected update whose row already held the target", () => {
+	test("1: another row of the repository is at the target — this row follows, counted as changed", async () => {
+		await writeRegistry([
+			row({ version: "0.5.0", projectPath: mainTree }),
+			row({ version: "0.4.0", projectPath: here }),
+		]);
+		const { details, reporter } = collect();
+
+		const result = await applyPlugins([item("0.5.0")], here, deps(), reporter);
+
+		expect(result.ok).toBe(1);
+		expect(result.unchanged).toEqual([]);
+		expect(await versionsByPath()).toEqual([
+			[mainTree, "0.5.0"],
+			[here, "0.5.0"],
+		]);
+		expect(details).toEqual([SAME_REPO_DETAIL]);
+		expect(await loadedVersionHere(PLUGIN, here, root)).toBe("0.5.0");
+	});
+
+	test("2: several other rows at the target — still one folder, 'another folder'", async () => {
+		await writeRegistry([
+			row({ version: "0.5.0", projectPath: gone }),
+			row({ version: "0.5.0", projectPath: mainTree }),
+			row({ version: "0.4.0", projectPath: here }),
+		]);
+		const { details, reporter } = collect();
+
+		const result = await applyPlugins([item("0.5.0")], here, deps(), reporter);
+
+		expect(result.ok).toBe(1);
+		expect(result.unchanged).toEqual([]);
+		expect(await hereVersion()).toBe("0.5.0");
+		expect(details).toEqual([SAME_REPO_DETAIL]);
+		expect(details[0]).not.toMatch(/other folders/);
+	});
+
+	test("3 (negative a): the only row at the target is another repository's — no follow", async () => {
+		await writeRegistry([
+			row({ version: "0.5.0", projectPath: otherRepo }),
+			row({ version: "0.4.0", projectPath: mainTree }),
+			row({ version: "0.4.0", projectPath: here }),
+		]);
+		const { details, reporter } = collect();
+
+		const result = await applyPlugins([item("0.5.0")], here, deps(), reporter);
+
+		expect(result.unchanged).toEqual([PLUGIN]);
+		expect(result.ok).toBe(0);
+		expect(await hereVersion()).toBe("0.4.0");
+		expect(details).toEqual([NO_CHANGE]);
+	});
+
+	test("4 (negative b): other repository rows are NEWER than the target — no follow", async () => {
+		await writeRegistry([
+			row({ version: "0.6.0", projectPath: mainTree }),
+			row({ version: "0.4.0", projectPath: here }),
+		]);
+		const { details, reporter } = collect();
+
+		const result = await applyPlugins([item("0.5.0")], here, deps(), reporter);
+
+		expect(result.unchanged).toEqual([PLUGIN]);
+		expect(await hereVersion()).toBe("0.4.0");
+		expect(await versionsByPath()).toEqual([
+			[mainTree, "0.6.0"],
+			[here, "0.4.0"],
+		]);
+		expect(details).toEqual([NO_CHANGE]);
+	});
+
+	test("4b (negative b): other repository rows are OLDER than the target — no follow", async () => {
+		await writeRegistry([
+			row({ version: "0.3.0", projectPath: mainTree }),
+			row({ version: "0.4.0", projectPath: here }),
+		]);
+		const { details, reporter } = collect();
+
+		await applyPlugins([item("0.5.0")], here, deps(), reporter);
+
+		// The older row is not the target, so this row does not follow it. (The
+		// stale-load repair that raises that older row to this one's version is
+		// older behaviour, tested on its own.)
+		expect(await hereVersion()).toBe("0.4.0");
+		expect(details.join("\n")).not.toContain("another folder");
+	});
+
+	test("5: the target is not downloaded — could not follow, row stays", async () => {
+		await writeRegistry([
+			row({ version: "0.5.0", projectPath: mainTree }),
+			row({ version: "0.4.0", projectPath: here }),
+		]);
+		await fs.remove(cacheFor("0.5.0"));
+		const { details, reporter } = collect();
+
+		const result = await applyPlugins([item("0.5.0")], here, deps(), reporter);
+
+		expect(result.unchanged).toEqual([PLUGIN]);
+		expect(await hereVersion()).toBe("0.4.0");
+		expect(details).toHaveLength(1);
+		expect(details[0]).toContain(
+			`no change — the installer exited 0 but ${PLUGIN} is still 0.4.0 (Claude Code updated another folder of this repository instead of this one, and this folder could not follow: v0.5.0 is not downloaded — run magus install)`,
+		);
+	});
+});

package/src/__tests__/blind/c18-probe-adopts-homebrew-keg.test.ts

@@ -0,0 +1,345 @@
+/**
+ * Blind tests, contract C18: Homebrew owns an installed tool whose file lies
+ * in `<brew prefix>/Cellar/<short name>/<version>/...`, whatever installer the
+ * spec declares. A pinned spec is not adopted (brew takes no version).
+ *
+ * Written from the spec only, through a scripted fake `ToolProbeIO`.
+ */
+import { describe, expect, test } from "bun:test";
+import {
+	type ExecResult,
+	type FetchJsonResult,
+	type ToolProbeIO,
+	classifyTool,
+	probeTool,
+} from "../../services/tool-probe.js";
+import type { BinRequirement } from "../../types/index.js";
+
+interface FakeSetup {
+	exec?: Record<string, Partial<ExecResult>>;
+	fetch?: Record<string, FetchJsonResult>;
+	files?: Record<string, string>;
+	real?: Record<string, string>;
+	onPath?: Record<string, string>;
+	env?: Record<string, string>;
+}
+
+function fakeIO(setup: FakeSetup): ToolProbeIO & { calls: string[] } {
+	const calls: string[] = [];
+	return {
+		calls,
+		exec: async (command) => {
+			const key = [command.cmd, ...command.args].join(" ");
+			calls.push(key);
+			const h = setup.exec?.[key];
+			if (h === undefined) {
+				return {
+					code: null,
+					stdout: "",
+					stderr: "",
+					timedOut: false,
+					missing: true,
+				};
+			}
+			return {
+				code: 0,
+				stdout: "",
+				stderr: "",
+				timedOut: false,
+				missing: false,
+				...h,
+			};
+		},
+		fetchJson: async (url) => {
+			const r = setup.fetch?.[url];
+			return r ?? { ok: false, reason: "returned 404" };
+		},
+		readJson: async (file) => {
+			const t = setup.files?.[file];
+			if (t === undefined) return null;
+			try {
+				return JSON.parse(t);
+			} catch {
+				return null;
+			}
+		},
+		readText: async (file) => setup.files?.[file] ?? null,
+		readlink: async () => null,
+		realpath: async (file) => setup.real?.[file] ?? null,
+		resolveExecutable: async (name) => setup.onPath?.[name] ?? null,
+		env: setup.env ?? {},
+		homedir: "/Users/j",
+	};
+}
+
+const PREFIX = "/opt/homebrew";
+const CELLAR = { "/opt/homebrew/Cellar": "/opt/homebrew/Cellar" };
+const BREW_PREFIX_OK: Record<string, Partial<ExecResult>> = {
+	"brew --prefix": { stdout: `${PREFIX}\n` },
+};
+
+const OUTDATED_NONE = JSON.stringify({ formulae: [], casks: [] });
+const outdatedBehind = (name: string, installed: string, current: string) =>
+	JSON.stringify({
+		formulae: [
+			{
+				name,
+				installed_versions: [installed],
+				current_version: current,
+				pinned: false,
+			},
+		],
+		casks: [],
+	});
+
+/** A tool whose PATH entry resolves into a Homebrew keg. */
+function kegWorld(
+	bin: string,
+	short: string,
+	version: string,
+	outdatedKey: string,
+	outdatedStdout: string,
+	extraExec: Record<string, Partial<ExecResult>> = BREW_PREFIX_OK,
+): FakeSetup {
+	const file = `${PREFIX}/Cellar/${short}/${version}/bin/${bin}`;
+	const onPath = `${PREFIX}/bin/${bin}`;
+	return {
+		onPath: { [bin]: onPath },
+		real: { [onPath]: file, [file]: file, ...CELLAR },
+		exec: {
+			...extraExec,
+			[`brew outdated --json=v2 ${outdatedKey}`]: { stdout: outdatedStdout },
+		},
+	};
+}
+
+const MNEMEX: BinRequirement = {
+	name: "mnemex",
+	via: "brew",
+	formula: "madappgang/tap/mnemex",
+};
+
+describe("C18 case 1: tap formula, brew spec, current", () => {
+	test("managed, version from the keg, state current", async () => {
+		const f = await probeTool(
+			MNEMEX,
+			fakeIO(
+				kegWorld(
+					"mnemex",
+					"mnemex",
+					"0.36.2",
+					"madappgang/tap/mnemex",
+					OUTDATED_NONE,
+				),
+			),
+		);
+		expect(f.managed).toBe(true);
+		expect(f.installed).toBe("0.36.2");
+		expect(classifyTool(MNEMEX, f).state).toBe("current");
+	});
+});
+
+describe("C18 case 2: tap formula behind", () => {
+	test("state upgrade, latest from brew", async () => {
+		const f = await probeTool(
+			MNEMEX,
+			fakeIO(
+				kegWorld(
+					"mnemex",
+					"mnemex",
+					"0.36.2",
+					"madappgang/tap/mnemex",
+					outdatedBehind("madappgang/tap/mnemex", "0.36.2", "0.37.0"),
+				),
+			),
+		);
+		expect(f.managed).toBe(true);
+		expect(f.latest).toBe("0.37.0");
+		expect(classifyTool(MNEMEX, f).state).toBe("upgrade");
+	});
+});
+
+describe("C18 case 3: bun spec, file in a Homebrew keg", () => {
+	const spec: BinRequirement = {
+		name: "claudish",
+		via: "bun",
+		package: "claudish",
+	};
+	test("adopted by brew: brew upgrade command, never bun", async () => {
+		const f = await probeTool(
+			spec,
+			fakeIO(
+				kegWorld(
+					"claudish",
+					"claudish",
+					"10.5.0",
+					"claudish",
+					outdatedBehind("claudish", "10.5.0", "10.6.0"),
+				),
+			),
+		);
+		expect(f.managed).toBe(true);
+		expect(f.installed).toBe("10.5.0");
+		expect(f.latest).toBe("10.6.0");
+		expect(f.upgradeCommand).toEqual({
+			cmd: "brew",
+			args: ["upgrade", "claudish"],
+		});
+		expect(f.upgradeCommand?.cmd).not.toBe("bun");
+		expect(classifyTool(spec, f).state).toBe("upgrade");
+	});
+});
+
+describe("C18 case 4: npm spec, file in a Homebrew keg", () => {
+	const spec: BinRequirement = {
+		name: "claudish",
+		via: "npm",
+		package: "claudish",
+	};
+	test("current, upgrade command is brew", async () => {
+		const f = await probeTool(
+			spec,
+			fakeIO(
+				kegWorld("claudish", "claudish", "10.5.0", "claudish", OUTDATED_NONE),
+			),
+		);
+		expect(f.upgradeCommand?.cmd).toBe("brew");
+		expect(classifyTool(spec, f).state).toBe("current");
+	});
+});
+
+describe("C18 case 5: a pinned spec is not adopted by Homebrew", () => {
+	const spec: BinRequirement = {
+		name: "claudish",
+		via: "bun",
+		package: "claudish",
+		version: "10.4.0",
+	};
+	test("unknown, no brew command, note mentions the pin", async () => {
+		const f = await probeTool(
+			spec,
+			fakeIO(
+				kegWorld(
+					"claudish",
+					"claudish",
+					"10.5.0",
+					"claudish",
+					outdatedBehind("claudish", "10.5.0", "10.6.0"),
+				),
+			),
+		);
+		expect(f.upgradeCommand?.cmd).not.toBe("brew");
+		const s = classifyTool(spec, f);
+		expect(s.state).toBe("unknown");
+		expect(s.note ?? "").toContain("10.4.0");
+	});
+});
+
+describe("C18 case 6: a directory merely named Cellar is not Homebrew's", () => {
+	const spec: BinRequirement = {
+		name: "claudish",
+		via: "bun",
+		package: "claudish",
+	};
+	test("not adopted: external, no upgrade command", async () => {
+		const file = "/Users/u/projects/Cellar/claudish/1.0.0/bin/claudish";
+		const f = await probeTool(
+			spec,
+			fakeIO({
+				onPath: { claudish: file },
+				real: { [file]: file, ...CELLAR },
+				exec: BREW_PREFIX_OK,
+			}),
+		);
+		expect(f.managed).not.toBe(true);
+		expect(f.upgradeCommand).toBeUndefined();
+		expect(classifyTool(spec, f).state).toBe("external");
+	});
+});
+
+describe("C18 case 7: Homebrew unavailable", () => {
+	const spec: BinRequirement = {
+		name: "claudish",
+		via: "bun",
+		package: "claudish",
+	};
+	const world = (exec: Record<string, Partial<ExecResult>>): FakeSetup =>
+		kegWorld(
+			"claudish",
+			"claudish",
+			"10.5.0",
+			"claudish",
+			outdatedBehind("claudish", "10.5.0", "10.6.0"),
+			exec,
+		);
+	test("brew --prefix missing: not adopted", async () => {
+		const f = await probeTool(spec, fakeIO(world({})));
+		expect(f.upgradeCommand?.cmd).not.toBe("brew");
+		expect(classifyTool(spec, f).state).not.toBe("upgrade");
+	});
+	test("brew --prefix exits non-zero: not adopted", async () => {
+		const f = await probeTool(
+			spec,
+			fakeIO(world({ "brew --prefix": { code: 1, stderr: "boom" } })),
+		);
+		expect(f.upgradeCommand?.cmd).not.toBe("brew");
+		expect(classifyTool(spec, f).state).not.toBe("upgrade");
+	});
+});
+
+describe("C18 case 8: a non-tap brew spec still works", () => {
+	test("tmux current, installed 3.8", async () => {
+		const spec: BinRequirement = {
+			name: "tmux",
+			via: "brew",
+			formula: "tmux",
+			check: "tmux -V",
+		};
+		const f = await probeTool(
+			spec,
+			fakeIO(kegWorld("tmux", "tmux", "3.8", "tmux", OUTDATED_NONE)),
+		);
+		expect(f.managed).toBe(true);
+		expect(f.installed).toBe("3.8");
+		expect(classifyTool(spec, f).state).toBe("current");
+	});
+});
+
+describe("C18 case 9: bun ownership still wins over a brew spec", () => {
+	test("file in bun's global tree: bun command, current", async () => {
+		const root = "/Users/j/.bun/install/global/node_modules";
+		const pkgDir = `${root}/mnemex`;
+		const file = `${pkgDir}/dist/index.js`;
+		const onPath = "/Users/j/.bun/bin/mnemex";
+		const f = await probeTool(
+			MNEMEX,
+			fakeIO({
+				env: { HOMEBREW_PREFIX: PREFIX },
+				onPath: { mnemex: onPath },
+				real: {
+					[onPath]: file,
+					[file]: file,
+					[pkgDir]: pkgDir,
+					[root]: root,
+					...CELLAR,
+				},
+				files: {
+					[`${pkgDir}/package.json`]: JSON.stringify({
+						name: "mnemex",
+						version: "0.36.2",
+					}),
+				},
+				exec: BREW_PREFIX_OK,
+				fetch: {
+					"https://registry.npmjs.org/-/package/mnemex/dist-tags": {
+						ok: true,
+						body: { latest: "0.36.2" },
+					},
+				},
+			}),
+		);
+		expect(f.managed).toBe(true);
+		expect(f.upgradeCommand?.cmd).toBe("bun");
+		expect(classifyTool(MNEMEX, f).state).toBe("current");
+	});
+});

package/src/__tests__/cli-tools-adapter.test.ts

@@ -213,9 +213,7 @@ describe("buildToolRow — which installer a catalogue row is judged through", (
 		expect(row.status?.state).toBe("external");
 		expect(row.status?.reason).toBe("not-managed");
 		// No path and no installer directory: the user acts on neither.
-		expect(row.status?.note).toBe(
-			"installed outside npm, so magus leaves it as is",
-		);
+		expect(row.status?.note).toBe("installed outside npm");
 		expect(row.status?.note).not.toContain("/");
 		// Enter still follows how it IS installed (pnpm).
 		expect(row.updateCommand?.cmd).toBe("pnpm");

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

@@ -238,7 +238,7 @@ describe("classifyTool — every rule of §4.3, in order", () => {
 			}),
 		);
 		expect(s).toMatchObject({ state: "external", reason: "not-managed" });
-		expect(s.note).toBe("installed outside npm, so magus leaves it as is");
+		expect(s.note).toBe("installed outside npm");
 		expect(s.note).not.toContain("/");
 	});
 
@@ -254,7 +254,7 @@ describe("classifyTool — every rule of §4.3, in order", () => {
 				spec({ via: "brew" }),
 				facts({ managed: false, behind: true }),
 			).note,
-		).toBe("installed outside Homebrew, so magus leaves it as is");
+		).toBe("installed outside Homebrew");
 	});
 
 	test("7. held back → unknown, with the hold as the note", () => {

package/src/cli/update-view.ts

@@ -458,6 +458,10 @@ function binDetail(item: BinUpdateItem, plan: UpdatePlan): string {
 				item.adopted ? `  ${dim(`(${item.adopted})`)}` : ""
 			}`;
 		case "external":
+			// Kept as is: a missing version is not a finding, so no "—" stands in.
+			return [item.installed, item.note ? dim(`(${item.note})`) : ""]
+				.filter(Boolean)
+				.join("  ");
 		case "unknown":
 			return `${item.installed ?? "—"}${
 				item.note ? `  ${dim(`(${item.note})`)}` : ""

package/src/services/tool-probe.ts

@@ -52,6 +52,8 @@ import {
 	versionFromVersionedPath,
 } from "./cli-tool-version.js";
 import {
+	binPinCommand,
+	binUpgradeCommand,
 	claudeNativeUpgradeCommand,
 	npmPrefixInstallCommand,
 } from "./toolchain.js";
@@ -231,6 +233,15 @@ export function installerWord(via: ManagedTool["via"]): string {
 	return via === "brew" ? "Homebrew" : via;
 }
 
+/** The directories the operating system itself installs programs into. */
+const SYSTEM_DIRS = ["/bin", "/sbin", "/usr/bin", "/usr/sbin", "/System"];
+
+function isSystemPath(resolved: string | null): boolean {
+	return (
+		resolved !== null && SYSTEM_DIRS.some((dir) => isInside(resolved, dir))
+	);
+}
+
 /**
  * The `not-managed` sentence, in the user's terms: who did not install it,
  * and what magus does about it. Never the path or the installer's directory:
@@ -241,8 +252,12 @@ function notManagedNote(spec: ManagedTool, facts: ToolFacts): string {
 	if (facts.managed === false && pin) {
 		return `installed outside ${installerWord(spec.via)}, so magus cannot move it to the pin ${pin}`;
 	}
+	// The KEPT chip already says magus leaves it as is; the note says only who
+	// installed it.
 	return facts.managed === false
-		? `installed outside ${installerWord(spec.via)}, so magus leaves it as is`
+		? isSystemPath(facts.resolvedPath)
+			? "comes with the operating system"
+			: `installed outside ${installerWord(spec.via)}`
 		: withFailure(
 				`could not tell whether ${installerWord(spec.via)} installed it`,
 				facts.failure,
@@ -1223,6 +1238,9 @@ async function probeBrew(
 	resolvedPath: string,
 ): Promise<void> {
 	const formula = spec.formula ?? spec.name;
+	// A tap formula ("user/tap/f") keeps its keg under the short name, so the
+	// full name never matched and a Homebrew mnemex read as installed outside it.
+	const keg = formula.slice(formula.lastIndexOf("/") + 1);
 	const prefix = await s.brewPrefix();
 	if ("failure" in prefix) {
 		f.managed = null;
@@ -1232,11 +1250,11 @@ async function probeBrew(
 	const cellar =
 		(await s.io.realpath(path.join(prefix.dir, "Cellar"))) ??
 		path.join(prefix.dir, "Cellar");
-	const ownerDir = path.join(cellar, formula);
+	const ownerDir = path.join(cellar, keg);
 	f.owner = `brew (Cellar ${ownerDir})`;
 	f.managed = isInside(resolvedPath, ownerDir);
 	if (!f.managed) return;
-	f.installed = brewKegVersion(resolvedPath, cellar, formula);
+	f.installed = brewKegVersion(resolvedPath, cellar, keg);
 	if (f.installed) addSource(f, "brew");
 
 	const r = await s.run("brew", ["outdated", "--json=v2", formula], BREW_ENV);
@@ -1386,6 +1404,129 @@ async function readNodePackage(
 	if (!pinned) await npmLatest(s, pkg, f);
 }
 
+/** Where `bun add -g` puts packages: `$BUN_INSTALL/install/global/node_modules`. */
+function bunGlobalRoot(io: ToolProbeIO): string {
+	return path.join(
+		io.env.BUN_INSTALL ?? path.join(io.homedir, ".bun"),
+		"install",
+		"global",
+		"node_modules",
+	);
+}
+
+/** The package a path names, from its segments under `node_modules`. */
+function packageFromSegments(rel: string): string | null {
+	const [first, second] = rel.split(path.sep);
+	if (!first || first.startsWith(".")) return null;
+	if (!first.startsWith("@")) return first;
+	return second ? `${first}/${second}` : null;
+}
+
+/**
+ * The bun or npm global package that holds `resolvedPath`, read from the path
+ * alone. Null when the file lies in neither tree (a Homebrew keg included:
+ * `npmGlobalPrefixOf` refuses one).
+ */
+async function nodeGlobalOwner(
+	s: ProbeSession,
+	resolvedPath: string,
+): Promise<{ via: "bun" | "npm"; pkg: string } | null> {
+	const bunRoot = await s.io.realpath(bunGlobalRoot(s.io));
+	if (bunRoot && isInside(resolvedPath, bunRoot)) {
+		const pkg = packageFromSegments(path.relative(bunRoot, resolvedPath));
+		return pkg ? { via: "bun", pkg } : null;
+	}
+	const marker = `${path.sep}${path.join("lib", "node_modules")}${path.sep}`;
+	const at = resolvedPath.lastIndexOf(marker);
+	if (at < 0) return null;
+	const pkg = packageFromSegments(resolvedPath.slice(at + marker.length));
+	return pkg && npmGlobalPrefixOf(resolvedPath, pkg) !== null
+		? { via: "npm", pkg }
+		: null;
+}
+
+/**
+ * The formula whose keg holds `resolvedPath` (`…/Cellar/<formula>/<version>/…`),
+ * read from the path alone. `probeBrew` then checks that this Cellar is brew's.
+ */
+function kegFormulaOf(resolvedPath: string): string | null {
+	const parts = resolvedPath.split(path.sep);
+	const at = parts.lastIndexOf("Cellar");
+	return at >= 0 && parts.length > at + 2 ? (parts[at + 1] ?? null) : null;
+}
+
+/**
+ * The spec as the installer that actually holds `resolvedPath` would state it,
+ * or null when that is the spec's own installer or none magus drives.
+ */
+async function actualOwnerSpec(
+	s: ProbeSession,
+	spec: ManagedTool,
+	resolvedPath: string,
+): Promise<ManagedTool | null> {
+	const base = {
+		name: spec.name,
+		...(spec.check ? { check: spec.check } : {}),
+		...(spec.version ? { version: spec.version } : {}),
+	};
+	const node = await nodeGlobalOwner(s, resolvedPath);
+	if (node) {
+		return node.via === spec.via
+			? null
+			: { ...base, via: node.via, package: node.pkg };
+	}
+	const formula = kegFormulaOf(resolvedPath);
+	// Homebrew takes no version, so it cannot honour a pin: such a tool stays
+	// "installed outside", which the classifier reports as unknown.
+	if (!formula || spec.via === "brew" || spec.version) return null;
+	return { ...base, via: "brew", formula };
+}
+
+/**
+ * The spec's installer does not own the file PATH runs, but bun's or npm's
+ * global tree or a Homebrew keg does: re-read the tool through THAT installer.
+ *
+ * A plugin's `requires` lists its install options in preference order for a
+ * FRESH install, and magus plans through the first. That order says how to
+ * install a missing tool, not which owner an installed one must have. A
+ * mnemex from `bun add -g` or from Homebrew has a version, a registry and an
+ * upgrade command like any other. Reading it as "installed outside" the
+ * first option's installer showed a settled, upgradeable tool as one magus
+ * could not touch.
+ *
+ * The catalogue's tools already follow how a tool IS installed
+ * (`specForCatalogTool`); this gives a plugin's requirements the same rule.
+ * The upgrade command is carried on the facts, so `magus update` and the TUI
+ * run the owner's command rather than the spec's.
+ */
+async function adoptActualOwner(
+	s: ProbeSession,
+	spec: ManagedTool,
+	f: ToolFacts,
+	resolvedPath: string,
+): Promise<void> {
+	const actual = await actualOwnerSpec(s, spec, resolvedPath);
+	if (!actual) return;
+	const read = blankFacts(spec.name);
+	if (actual.via === "brew") await probeBrew(s, actual, read, resolvedPath);
+	else await probeNodeGlobal(s, actual, read, resolvedPath);
+	if (read.managed !== true) return;
+	f.managed = true;
+	f.owner = read.owner;
+	f.installed = read.installed;
+	f.latest = read.latest;
+	f.behind = read.behind;
+	// What the spec's installer could not answer is moot once the owner is
+	// known: only the owner's own failure describes this tool.
+	f.failure = read.failure;
+	for (const source of read.sources) addSource(f, source);
+	f.upgradeCommand =
+		read.upgradeCommand ??
+		(spec.version
+			? (binPinCommand(actual) ?? undefined)
+			: binUpgradeCommand(actual));
+}
+
 async function probeNodeGlobal(
 	s: ProbeSession,
 	spec: ManagedTool,
@@ -1396,12 +1537,7 @@ async function probeNodeGlobal(
 	const pin = pinOf(spec);
 	const pinned = pin !== undefined;
 	if (spec.via === "bun") {
-		const root = path.join(
-			s.io.env.BUN_INSTALL ?? path.join(s.io.homedir, ".bun"),
-			"install",
-			"global",
-			"node_modules",
-		);
+		const root = bunGlobalRoot(s.io);
 		f.owner = `bun (global ${root})`;
 		const { inside, real } = await containedIn(
 			s,
@@ -1654,6 +1790,11 @@ async function probeInto(
 			break;
 	}
 
+	// Not the spec's installer's file, or it could not tell (npm with no `npm`
+	// to ask), but the path names bun's, npm's or Homebrew's tree: then that is
+	// the owner, and it can upgrade the file PATH runs.
+	if (f.managed !== true) await adoptActualOwner(s, spec, f, resolvedPath);
+
 	// The method's own record was silent. Before anything runs, read what the
 	// installed files already say about themselves.
 	if (f.installed === null) versionFromFiles(f, resolvedPath);

package/src/services/update-engine.ts

@@ -397,7 +397,7 @@ async function readRows(
  * The row Claude Code moved is left as it is: it belongs to this repository,
  * and bringing this repository's rows forward is what the repair does anyway.
  * Null when there was nothing to follow — this project's row moved (2.1.280),
- * or no row of this repository moved at all.
+ * or no row of this repository moved at all and none already holds `target`.
  */
 async function followMisdirectedUpdate(
 	deps: PluginApplyDeps,
@@ -422,14 +422,32 @@ async function followMisdirectedUpdate(
 		scope,
 		projectPath: scope === "user" ? undefined : projectPath,
 	});
-	if (moved.length === 0 || moved.some((row) => rowKey(row) === mine)) {
-		return null;
-	}
-	const version = moved
+	if (moved.some((row) => rowKey(row) === mine)) return null;
+	// The row Claude Code picked may ALREADY hold the target — an earlier run
+	// from another checkout put it there. Then the update writes nothing, so
+	// nothing moves, and this project's row stays behind on every run (seen on
+	// 2.1.296: "the installer exited 0 but mnemex@magus is still 1.1.0" while
+	// tools/claudeup held 1.1.1). A row of this repository at exactly the
+	// target is the same misdirection, already landed.
+	const landed =
+		moved.length > 0 || !target
+			? moved
+			: after.filter(
+					(row) =>
+						row.version === target &&
+						rowKey(row) !== mine &&
+						inThisRepository(row, projectPath),
+				);
+	if (landed.length === 0) return null;
+	const version = landed
 		.map((row) => row.version)
 		.reduce((a, b) => ((compareVersions(b, a) ?? 0) > 0 ? b : a));
 	if (!isRepairablyBehind(version, now)) return null;
-	const elsewhere = moved.map((row) => row.projectPath ?? `${row.scope} scope`);
+	// Already landed, every checkout at the target matches, but Claude Code
+	// wrote to one of them: report one folder, not all of them.
+	const elsewhere = (moved.length > 0 ? landed : landed.slice(0, 1)).map(
+		(row) => row.projectPath ?? `${row.scope} scope`,
+	);
 	if (target && version !== target) {
 		return {
 			elsewhere,