magus-cli 7.10.2 → 7.10.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magus-cli",
-  "version": "7.10.2",
+  "version": "7.10.3",
   "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.2",
-    "magus-cli-darwin-x64": "7.10.2",
-    "magus-cli-linux-x64": "7.10.2"
+    "magus-cli-darwin-arm64": "7.10.3",
+    "magus-cli-darwin-x64": "7.10.3",
+    "magus-cli-linux-x64": "7.10.3"
   }
 }

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

@@ -250,10 +250,10 @@ describe("C16 case 6: file in no node tree, brew spec", () => {
 		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).toBe("installed by an installer magus does not update");
 		expect(s.note?.includes("/")).toBe(false);
 	});
-	test("an npm spec says installed outside npm", async () => {
+	test("an npm spec gets the same note: it names who installed it, never the spec installer", async () => {
 		const npmSpec: BinRequirement = { name: "uv", via: "npm", package: "uv" };
 		const f = await probeTool(
 			npmSpec,
@@ -264,7 +264,7 @@ describe("C16 case 6: file in no node tree, brew spec", () => {
 		);
 		const s = classifyTool(npmSpec, f);
 		expect(s.state).toBe("external");
-		expect(s.note).toBe("installed outside npm");
+		expect(s.note).toBe("installed by an installer magus does not update");
 	});
 	test("a pinned spec in that situation stays unknown", async () => {
 		const pinned: BinRequirement = { ...spec, version: "1.0.0" };

package/src/__tests__/blind/c19-probe-owner-version-shadow.test.ts

@@ -0,0 +1,389 @@
+/**
+ * Blind tests, contract C19: a KEPT row names who installed the file, shows its
+ * version whenever it can be read, drives a self-updating standalone installer
+ * (uv's receipt), and reports a newer copy hidden later on PATH.
+ *
+ * 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>;
+	allOnPath?: Record<string, string[]>;
+	env?: Record<string, string>;
+	noAll?: boolean;
+}
+
+const HOME = "/home/u";
+
+function fakeIO(
+	setup: FakeSetup,
+): ToolProbeIO & { calls: string[]; reads: string[] } {
+	const calls: string[] = [];
+	const reads: string[] = [];
+	const io: ToolProbeIO & { calls: string[]; reads: string[] } = {
+		calls,
+		reads,
+		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) =>
+			setup.fetch?.[url] ?? { ok: false, reason: "returned 404" },
+		readJson: async (file) => {
+			reads.push(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: HOME,
+	};
+	if (!setup.noAll) {
+		io.resolveAllExecutables = async (name: string) =>
+			setup.allOnPath?.[name] ??
+			(setup.onPath?.[name] !== undefined
+				? [setup.onPath[name] as string]
+				: []);
+	}
+	return io;
+}
+
+const PREFIX = "/opt/homebrew";
+const BREW_PREFIX_OK: Record<string, Partial<ExecResult>> = {
+	"brew --prefix": { stdout: `${PREFIX}\n` },
+};
+const CELLAR = { "/opt/homebrew/Cellar": "/opt/homebrew/Cellar" };
+
+const UV: BinRequirement = { name: "uv", via: "brew", formula: "uv" };
+const UV_FILE = "/home/u/.local/bin/uv";
+const UV_RECEIPT_PATH = "/home/u/.config/uv/uv-receipt.json";
+const uvReceipt = (prefix = "/home/u/.local/bin", version = "0.11.15") =>
+	JSON.stringify({
+		binaries: ["uv", "uvx"],
+		install_prefix: prefix,
+		source: { app_name: "uv", name: "uv", owner: "astral-sh" },
+		version,
+	});
+const pypi = (v: string): Record<string, FetchJsonResult> => ({
+	"https://pypi.org/pypi/uv/json": { ok: true, body: { info: { version: v } } },
+});
+
+function uvWorld(opts: {
+	latest?: string;
+	receiptPrefix?: string;
+	receiptAt?: string;
+	env?: Record<string, string>;
+	extra?: Partial<FakeSetup>;
+}): FakeSetup {
+	return {
+		onPath: { uv: UV_FILE },
+		real: { [UV_FILE]: UV_FILE },
+		files: {
+			[opts.receiptAt ?? UV_RECEIPT_PATH]: uvReceipt(opts.receiptPrefix),
+		},
+		fetch: pypi(opts.latest ?? "0.13.0"),
+		env: opts.env ?? {},
+		...opts.extra,
+	};
+}
+
+describe("C19 A: uv's own installer is a driven owner", () => {
+	test("1. receipt, PyPI newer: managed, upgrade, uv self update", async () => {
+		const f = await probeTool(UV, fakeIO(uvWorld({})));
+		expect(f.installed).toBe("0.11.15");
+		expect(f.managed).toBe(true);
+		expect(f.latest).toBe("0.13.0");
+		expect(f.upgradeCommand).toEqual({ cmd: "uv", args: ["self", "update"] });
+		const s = classifyTool(UV, f);
+		expect(s.state).toBe("upgrade");
+		expect(s.target).toBe("0.13.0");
+	});
+
+	test("2. PyPI equals installed: current", async () => {
+		const f = await probeTool(UV, fakeIO(uvWorld({ latest: "0.11.15" })));
+		expect(classifyTool(UV, f).state).toBe("current");
+	});
+
+	test("3. pinned spec: upgrade to the pin with a versioned command", async () => {
+		const spec: BinRequirement = { ...UV, version: "0.12.0" };
+		const f = await probeTool(spec, fakeIO(uvWorld({})));
+		expect(f.upgradeCommand).toEqual({
+			cmd: "uv",
+			args: ["self", "update", "0.12.0"],
+		});
+		const s = classifyTool(spec, f);
+		expect(s.state).toBe("upgrade");
+		expect(s.target).toBe("0.12.0");
+	});
+
+	test("4. receipt for a different install_prefix is ignored", async () => {
+		const f = await probeTool(
+			UV,
+			fakeIO(uvWorld({ receiptPrefix: "/somewhere/else" })),
+		);
+		expect(f.managed).not.toBe(true);
+		expect(f.upgradeCommand).toBeUndefined();
+		expect(classifyTool(UV, f).state).not.toBe("upgrade");
+	});
+
+	test("5. XDG_CONFIG_HOME relocates the receipt", async () => {
+		const io = fakeIO(
+			uvWorld({
+				env: { XDG_CONFIG_HOME: "/xdg" },
+				extra: {
+					// a decoy at the default place must not be the one used
+					files: {
+						"/xdg/uv/uv-receipt.json": uvReceipt(),
+						[UV_RECEIPT_PATH]: uvReceipt("/home/u/.local/bin", "9.9.9"),
+					},
+				},
+			}),
+		);
+		const f = await probeTool(UV, io);
+		expect(f.installed).toBe("0.11.15");
+		expect(f.managed).toBe(true);
+		expect(io.reads).toContain("/xdg/uv/uv-receipt.json");
+		expect(io.reads).not.toContain(UV_RECEIPT_PATH);
+	});
+
+	test("6. receipt of an installer magus cannot update: external, versioned, named", async () => {
+		const spec: BinRequirement = { name: "ruff", via: "brew", formula: "ruff" };
+		const file = "/home/u/.local/bin/ruff";
+		const f = await probeTool(
+			spec,
+			fakeIO({
+				onPath: { ruff: file },
+				real: { [file]: file },
+				files: {
+					"/home/u/.config/ruff/ruff-receipt.json": JSON.stringify({
+						binaries: ["ruff"],
+						install_prefix: "/home/u/.local/bin",
+						source: { app_name: "ruff", name: "ruff", owner: "astral-sh" },
+						version: "0.9.1",
+					}),
+				},
+				exec: BREW_PREFIX_OK,
+			}),
+		);
+		expect(f.installed).toBe("0.9.1");
+		expect(f.upgradeCommand).toBeUndefined();
+		const s = classifyTool(spec, f);
+		expect(s.state).toBe("external");
+		expect(s.note).toBe("installed by ruff's own installer");
+	});
+});
+
+describe("C19 B: KEPT notes name who installed it", () => {
+	const spec = (
+		name: string,
+		extra: Partial<BinRequirement> = {},
+	): BinRequirement => ({
+		name,
+		via: "brew",
+		formula: name,
+		...extra,
+	});
+	const world = (
+		name: string,
+		file: string,
+		env: Record<string, string> = {},
+	): FakeSetup => ({
+		onPath: { [name]: file },
+		real: { [file]: file, ...CELLAR },
+		exec: BREW_PREFIX_OK,
+		env,
+	});
+
+	test("7. Homebrew cask", async () => {
+		const sp = spec("madbench");
+		const file = "/opt/homebrew/Caskroom/madbench/0.43.2/madbench";
+		const f = await probeTool(sp, fakeIO(world("madbench", file)));
+		const s = classifyTool(sp, f);
+		expect(s.state).toBe("external");
+		expect(s.note).toBe("installed by a Homebrew cask");
+	});
+
+	test("8a. cargo bin under the home directory", async () => {
+		const sp = spec("rg");
+		const f = await probeTool(sp, fakeIO(world("rg", "/home/u/.cargo/bin/rg")));
+		const s = classifyTool(sp, f);
+		expect(s.state).toBe("external");
+		expect(s.note).toBe("installed by cargo");
+	});
+
+	test("8b. cargo bin under CARGO_HOME", async () => {
+		const sp = spec("rg");
+		const f = await probeTool(
+			sp,
+			fakeIO(world("rg", "/opt/cargo/bin/rg", { CARGO_HOME: "/opt/cargo" })),
+		);
+		const s = classifyTool(sp, f);
+		expect(s.state).toBe("external");
+		expect(s.note).toBe("installed by cargo");
+	});
+
+	test("9. unrecognised place, never says 'outside'", async () => {
+		const sp = spec("foo");
+		const f = await probeTool(
+			sp,
+			fakeIO(world("foo", "/home/u/tools/bin/foo")),
+		);
+		const s = classifyTool(sp, f);
+		expect(s.state).toBe("external");
+		expect(s.note).toBe("installed by an installer magus does not update");
+		expect(s.note ?? "").not.toContain("outside");
+	});
+
+	test("10. pinned spec with a cargo file", async () => {
+		const sp = spec("rg", { version: "1.0.0" });
+		const f = await probeTool(sp, fakeIO(world("rg", "/home/u/.cargo/bin/rg")));
+		const s = classifyTool(sp, f);
+		expect(s.state).toBe("unknown");
+		expect(s.note).toBe(
+			"installed by cargo, so magus cannot move it to the pin 1.0.0",
+		);
+	});
+});
+
+describe("C19 C: operating-system programs show their version", () => {
+	const zsh: BinRequirement = { name: "zsh", via: "brew", formula: "zsh" };
+	const world = (zshExec?: Partial<ExecResult>): FakeSetup => ({
+		onPath: { zsh: "/bin/zsh" },
+		real: { "/bin/zsh": "/bin/zsh", ...CELLAR },
+		exec: {
+			...BREW_PREFIX_OK,
+			...(zshExec ? { "/bin/zsh --version": zshExec } : {}),
+		},
+	});
+
+	test("11. version read from --version", async () => {
+		const f = await probeTool(
+			zsh,
+			fakeIO(world({ stdout: "zsh 5.9 (arm64-apple-darwin25.0)\n" })),
+		);
+		expect(f.installed).toBe("5.9");
+		const s = classifyTool(zsh, f);
+		expect(s.state).toBe("external");
+		expect(s.note).toBe("comes with the operating system");
+	});
+
+	test("12a. --version exits non-zero: still external, installed null", async () => {
+		const f = await probeTool(
+			zsh,
+			fakeIO(world({ code: 1, stdout: "", stderr: "" })),
+		);
+		expect(f.installed).toBeNull();
+		const s = classifyTool(zsh, f);
+		expect(s.state).toBe("external");
+		expect(s.note).toBe("comes with the operating system");
+	});
+
+	test("12b. --version missing: still external, installed null", async () => {
+		const f = await probeTool(zsh, fakeIO(world()));
+		expect(f.installed).toBeNull();
+		const s = classifyTool(zsh, f);
+		expect(s.state).toBe("external");
+		expect(s.note).toBe("comes with the operating system");
+	});
+});
+
+describe("C19 D: a newer copy later on PATH is reported", () => {
+	const BREW_BIN = "/opt/homebrew/bin/uv";
+	const cellarFile = (v: string) => `/opt/homebrew/Cellar/uv/${v}/bin/uv`;
+	const world = (second: string, secondReal: string): FakeSetup =>
+		uvWorld({
+			extra: {
+				allOnPath: { uv: [UV_FILE, second] },
+				real: { [UV_FILE]: UV_FILE, [second]: secondReal, ...CELLAR },
+				exec: BREW_PREFIX_OK,
+				env: { HOMEBREW_PREFIX: PREFIX },
+			},
+		});
+	const NOTE =
+		"Homebrew also has 0.13.0, unused: ~/.local/bin comes first on PATH";
+
+	test("13. newer Homebrew copy: pathDir, otherCopies, shadowed", async () => {
+		const f = await probeTool(
+			UV,
+			fakeIO(world(BREW_BIN, cellarFile("0.13.0"))),
+		);
+		expect(f.pathDir).toBe("~/.local/bin");
+		expect(f.otherCopies).toEqual([
+			{ owner: "Homebrew", version: "0.13.0", dir: "/opt/homebrew/bin" },
+		]);
+		expect(classifyTool(UV, f).shadowed).toBe(NOTE);
+	});
+
+	test("14. older later copy: listed, not shadowed", async () => {
+		const f = await probeTool(
+			UV,
+			fakeIO(world(BREW_BIN, cellarFile("0.10.0"))),
+		);
+		expect(f.otherCopies).toEqual([
+			{ owner: "Homebrew", version: "0.10.0", dir: "/opt/homebrew/bin" },
+		]);
+		expect(classifyTool(UV, f).shadowed).toBeUndefined();
+	});
+
+	test("15. a symlink to the running file is not another copy", async () => {
+		const f = await probeTool(UV, fakeIO(world("/usr/local/bin/uv", UV_FILE)));
+		expect(f.otherCopies ?? []).toEqual([]);
+		expect(classifyTool(UV, f).shadowed).toBeUndefined();
+	});
+
+	test("16. IO without resolveAllExecutables: nothing reported, nothing throws", async () => {
+		const w = world(BREW_BIN, cellarFile("0.13.0"));
+		w.noAll = true;
+		const f = await probeTool(UV, fakeIO(w));
+		expect(f.otherCopies ?? []).toEqual([]);
+		expect(classifyTool(UV, f).shadowed).toBeUndefined();
+	});
+
+	test("17. shadowed is set on a current row too", async () => {
+		const w = world(BREW_BIN, cellarFile("0.13.0"));
+		w.fetch = pypi("0.11.15");
+		const f = await probeTool(UV, fakeIO(w));
+		const s = classifyTool(UV, f);
+		expect(s.state).toBe("current");
+		expect(s.shadowed).toBe(NOTE);
+	});
+});

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

@@ -213,7 +213,9 @@ 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");
+		expect(row.status?.note).toBe(
+			"installed by an installer magus does not update",
+		);
 		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");
+		expect(s.note).toBe("installed by an installer magus does not update");
 		expect(s.note).not.toContain("/");
 	});
 
@@ -248,13 +248,13 @@ describe("classifyTool — every rule of §4.3, in order", () => {
 		).toMatchObject({ state: "unknown", reason: "not-managed" });
 	});
 
-	test("6. brew is named as the user knows it", () => {
-		expect(
-			classifyTool(
-				spec({ via: "brew" }),
-				facts({ managed: false, behind: true }),
-			).note,
-		).toBe("installed outside Homebrew");
+	test("6. the note names who DID install it, never the spec's installer", () => {
+		const note = classifyTool(
+			spec({ via: "brew" }),
+			facts({ managed: false, behind: true, ownerName: "cargo" }),
+		).note;
+		expect(note).toBe("installed by cargo");
+		expect(note).not.toContain("Homebrew");
 	});
 
 	test("7. held back → unknown, with the hold as the note", () => {

package/src/cli/update-view.ts

@@ -435,6 +435,16 @@ function pluginDetail(item: PluginUpdateItem): string {
  * pin is shown only when there is one.
  */
 function binDetail(item: BinUpdateItem, plan: UpdatePlan): string {
+	const detail = binStateDetail(item, plan);
+	// A newer copy later on PATH is the one thing here only the user can settle.
+	return item.shadowed
+		? [detail, fg(brand.warning, `⚠ ${item.shadowed}`)]
+				.filter(Boolean)
+				.join("  ")
+		: detail;
+}
+
+function binStateDetail(item: BinUpdateItem, plan: UpdatePlan): string {
 	const spec = plan.binSpecs.get(item.name);
 	// Rendered for the reader's eyes only — this row says what WILL run, while
 	// applyBins runs the argv itself. Same builder, so they cannot differ.

package/src/services/tool-probe.ts

@@ -106,7 +106,20 @@ export type ToolFactSource =
 	| "package-json"
 	/** the file name of a versioned install (`…/versions/2.1.276`). */
 	| "version-dir"
-	| "check-command";
+	| "check-command"
+	/** an installer's own receipt (`~/.config/uv/uv-receipt.json`). */
+	| "installer-receipt"
+	/** `--version` of a program the operating system ships. */
+	| "os-version";
+
+/** Another copy of the tool on PATH, behind the one that runs. */
+export interface OtherCopy {
+	/** The installer as the user knows it: "Homebrew", "uv's own installer". */
+	owner: string;
+	version: string | null;
+	/** The PATH directory it was found in, with the home folder as `~`. */
+	dir: string;
+}
 
 export interface ToolFacts {
 	name: string;
@@ -135,6 +148,16 @@ export interface ToolFacts {
 	 * "npm (root /Users/x/.local/lib/node_modules)". Diagnostic only.
 	 */
 	owner?: string;
+	/**
+	 * Who installed the file PATH runs, as the user knows it ("uv's own
+	 * installer", "a Homebrew cask"), when that is not the spec's installer and
+	 * magus could name it. Read by the not-managed note.
+	 */
+	ownerName?: string;
+	/** The PATH directory the running copy was found in, home as `~`. */
+	pathDir?: string;
+	/** Other copies of the tool later on PATH, which nothing runs. */
+	otherCopies?: OtherCopy[];
 	/** e.g. "held by brew pin". */
 	heldBack?: string;
 	/**
@@ -178,6 +201,12 @@ export interface ToolStatus {
 	note?: string;
 	/** {@link ToolFacts.adopted}, carried when this state plans work. */
 	adopted?: string;
+	/**
+	 * Set in every state when a NEWER copy sits later on PATH, unused: e.g.
+	 * "Homebrew also has 0.13.0, unused: ~/.local/bin comes first on PATH".
+	 * A warning, because only the user can decide which copy to keep.
+	 */
+	shadowed?: string;
 	installed: string | null;
 	latest: string | null;
 	target: string | null;
@@ -248,20 +277,40 @@ function isSystemPath(resolved: string | null): boolean {
  * the user acts on neither.
  */
 function notManagedNote(spec: ManagedTool, facts: ToolFacts): string {
-	const pin = pinOf(spec);
-	if (facts.managed === false && pin) {
-		return `installed outside ${installerWord(spec.via)}, so magus cannot move it to the pin ${pin}`;
+	if (facts.managed !== false) {
+		return withFailure(
+			`could not tell whether ${installerWord(spec.via)} installed it`,
+			facts.failure,
+		);
 	}
+	// Who DID install it. "Outside Homebrew" named the installer magus would
+	// have used, which says nothing about the copy the user has.
+	const who = isSystemPath(facts.resolvedPath)
+		? "comes with the operating system"
+		: facts.ownerName
+			? `installed by ${facts.ownerName}`
+			: "installed by an installer magus does not update";
+	const pin = pinOf(spec);
 	// The KEPT chip already says magus leaves it as is; the note says only who
-	// installed it.
-	return facts.managed === false
-		? 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,
-			);
+	// installed it, and what that means for a pin.
+	return pin ? `${who}, so magus cannot move it to the pin ${pin}` : who;
+}
+
+/**
+ * The warning for a newer copy later on PATH, or undefined. Only a NEWER one
+ * (or any, when the running version is unknown) is worth a line: an older
+ * copy changes nothing the user runs.
+ */
+function shadowNote(facts: ToolFacts): string | undefined {
+	const running = facts.installed;
+	const newer = (facts.otherCopies ?? []).find(
+		(copy) =>
+			copy.version !== null &&
+			(running === null || compareToolVersions(copy.version, running) === 1),
+	);
+	if (!newer?.version) return undefined;
+	const first = facts.pathDir ? `${facts.pathDir} comes first on PATH` : "";
+	return `${newer.owner} also has ${newer.version}, unused${first ? `: ${first}` : ""}`;
 }
 
 /**
@@ -292,6 +341,12 @@ function externalOr(pin: string | undefined): ToolState {
  * none.
  */
 export function classifyTool(spec: ManagedTool, facts: ToolFacts): ToolStatus {
+	const status = classifyState(spec, facts);
+	const shadowed = facts.present ? shadowNote(facts) : undefined;
+	return shadowed ? { ...status, shadowed } : status;
+}
+
+function classifyState(spec: ManagedTool, facts: ToolFacts): ToolStatus {
 	const pin = pinOf(spec);
 	const base = {
 		name: spec.name,
@@ -392,7 +447,10 @@ export function classifyTool(spec: ManagedTool, facts: ToolFacts): ToolStatus {
 	// From here on a row can plan work, so an adoption must travel with it.
 	const adopted = facts.adopted ? { adopted: facts.adopted } : {};
 	if (pin) {
-		if (spec.via === "brew") {
+		// Homebrew cannot install a chosen version, but the spec's installer is
+		// not always the owner: an owner's own command (`uv self update <pin>`)
+		// is already aimed at the pin.
+		if (spec.via === "brew" && !facts.upgradeCommand) {
 			return {
 				...base,
 				state: "unknown",
@@ -758,6 +816,11 @@ export interface ToolProbeIO {
 	 * null. A dangling symlink is not executable and does not count.
 	 */
 	resolveExecutable(name: string): Promise<string | null>;
+	/**
+	 * Every executable `name` on PATH, in PATH order, as found. Optional: an IO
+	 * without it reports no other copies.
+	 */
+	resolveAllExecutables?(name: string): Promise<string[]>;
 	env: Readonly<Record<string, string | undefined>>;
 	homedir: string;
 }
@@ -876,6 +939,16 @@ export const REAL_TOOL_PROBE_IO: ToolProbeIO = {
 		}
 		return null;
 	},
+	resolveAllExecutables: async (name) => {
+		const found: string[] = [];
+		for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
+			if (!dir) continue;
+			const candidate = path.join(dir, name);
+			if (!found.includes(candidate) && (await isExecutable(candidate)))
+				found.push(candidate);
+		}
+		return found;
+	},
 	env: process.env,
 	homedir: os.homedir(),
 };
@@ -1527,6 +1600,207 @@ async function adoptActualOwner(
 			: binUpgradeCommand(actual));
 }
 
+/**
+ * Standalone installers that update their own copy in place, keyed by the
+ * app their receipt names: the arguments after the program, and the PyPI
+ * project that publishes it. uv's own installer writes a receipt and ships
+ * `uv self update`, so a uv from it is as upgradeable as one from Homebrew.
+ */
+const SELF_UPDATERS: Readonly<
+	Record<string, { args: readonly string[]; pypi: string }>
+> = {
+	uv: { args: ["self", "update"], pypi: "uv" },
+};
+
+interface InstallerReceipt {
+	app: string;
+	version: string;
+	file: string;
+}
+
+/**
+ * The receipt a standalone installer (cargo-dist's format, which uv's uses)
+ * left for `name`, when it covers `resolvedPath`:
+ * `$XDG_CONFIG_HOME/<name>/<name>-receipt.json`, whose `install_prefix` holds
+ * the file and whose `binaries` list it. A receipt for another folder is a
+ * different copy and says nothing about this one.
+ */
+async function installerReceipt(
+	s: ProbeSession,
+	name: string,
+	resolvedPath: string,
+): Promise<InstallerReceipt | null> {
+	const config = s.io.env.XDG_CONFIG_HOME || path.join(s.io.homedir, ".config");
+	const file = path.join(config, name, `${name}-receipt.json`);
+	const body = await s.io.readJson(file);
+	if (!body || typeof body !== "object") return null;
+	const r = body as {
+		version?: unknown;
+		install_prefix?: unknown;
+		binaries?: unknown;
+		source?: { app_name?: unknown } | null;
+	};
+	if (typeof r.version !== "string" || typeof r.install_prefix !== "string")
+		return null;
+	if (
+		!Array.isArray(r.binaries) ||
+		!r.binaries.includes(path.basename(resolvedPath))
+	)
+		return null;
+	const prefix = (await s.io.realpath(r.install_prefix)) ?? r.install_prefix;
+	if (!isInside(resolvedPath, prefix)) return null;
+	const app = typeof r.source?.app_name === "string" ? r.source.app_name : name;
+	return { app, version: r.version, file };
+}
+
+/**
+ * The file is a standalone installer's: its receipt gives the version, and
+ * when that installer updates itself ({@link SELF_UPDATERS}) it is the owner
+ * `magus update` drives. Otherwise the tool stays KEPT, but its row can say
+ * who installed it and which version runs.
+ */
+async function adoptOwnInstaller(
+	s: ProbeSession,
+	spec: ManagedTool,
+	f: ToolFacts,
+	resolvedPath: string,
+): Promise<void> {
+	const receipt = await installerReceipt(s, spec.name, resolvedPath);
+	if (!receipt) return;
+	const ownerName = `${receipt.app}'s own installer`;
+	f.installed = receipt.version;
+	addSource(f, "installer-receipt");
+	const updater = SELF_UPDATERS[receipt.app];
+	if (!updater) {
+		f.managed = false;
+		f.ownerName = ownerName;
+		return;
+	}
+	f.managed = true;
+	f.owner = `${ownerName} (receipt ${receipt.file})`;
+	f.latest = null;
+	f.behind = null;
+	// What the spec's installer could not answer is moot: the owner is known.
+	f.failure = undefined;
+	const pin = pinOf(spec);
+	f.upgradeCommand = {
+		cmd: spec.name,
+		args: [...updater.args, ...(pin ? [pin] : [])],
+	};
+	if (!pin) await pypiLatest(s, updater.pypi, f);
+}
+
+/**
+ * Who installed a file no installer magus drives owns, as the user knows it,
+ * or undefined when the path does not say.
+ */
+async function nameOwner(
+	s: ProbeSession,
+	resolvedPath: string,
+): Promise<string | undefined> {
+	if (resolvedPath.split(path.sep).includes("Caskroom"))
+		return "a Homebrew cask";
+	if (kegFormulaOf(resolvedPath)) return "Homebrew";
+	const node = await nodeGlobalOwner(s, resolvedPath);
+	if (node) return node.via;
+	const cargoHome = s.io.env.CARGO_HOME || path.join(s.io.homedir, ".cargo");
+	if (isInside(resolvedPath, path.join(cargoHome, "bin"))) return "cargo";
+	return undefined;
+}
+
+/**
+ * Where an operating-system program is safe to run for `--version`. Not
+ * macOS's /usr/bin: several programs there are Xcode stubs that open an
+ * install dialog when run on a machine without the developer tools.
+ */
+function osVersionDirs(): string[] {
+	return process.platform === "darwin" ? ["/bin", "/sbin"] : SYSTEM_DIRS;
+}
+
+/**
+ * The version of a program the operating system ships, from its own
+ * `--version`. No installer keeps a record of these, and the file is the OS
+ * vendor's, not a string a catalogue wrote, so running it is safe.
+ */
+async function versionFromOs(
+	s: ProbeSession,
+	f: ToolFacts,
+	resolvedPath: string,
+): Promise<void> {
+	if (!osVersionDirs().some((dir) => isInside(resolvedPath, dir))) return;
+	const r = await s.run(resolvedPath, ["--version"], PLAIN_ENV);
+	if (r.missing || r.timedOut) return;
+	const v = parseVersionToken(`${r.stdout}\n${r.stderr}`);
+	if (v) {
+		f.installed = v;
+		addSource(f, "os-version");
+	}
+}
+
+/** `dir` with the home folder written as `~`, for a line the user reads. */
+function homeShort(io: ToolProbeIO, dir: string): string {
+	return isInside(dir, io.homedir)
+		? path.join("~", path.relative(io.homedir, dir))
+		: dir;
+}
+
+/** Owner and version of a copy PATH does not run, read from its path. */
+async function describeCopy(
+	s: ProbeSession,
+	name: string,
+	real: string,
+): Promise<{ owner: string; version: string | null }> {
+	const parts = real.split(path.sep);
+	for (const [marker, owner] of [
+		["Cellar", "Homebrew"],
+		["Caskroom", "a Homebrew cask"],
+	] as const) {
+		const at = parts.lastIndexOf(marker);
+		if (at >= 0 && parts.length > at + 2)
+			return { owner, version: parts[at + 2] ?? null };
+	}
+	const receipt = await installerReceipt(s, name, real);
+	if (receipt)
+		return {
+			owner: `${receipt.app}'s own installer`,
+			version: receipt.version,
+		};
+	const node = await nodeGlobalOwner(s, real);
+	if (node) return { owner: node.via, version: readPackageVersionForBin(real) };
+	if (isSystemPath(real))
+		return { owner: "the operating system", version: null };
+	return { owner: "another installer", version: null };
+}
+
+/**
+ * The other copies of the tool on PATH. The first one wins, and whatever
+ * comes later is never run: a newer copy there is a surprise only the user
+ * can settle, by removing one or reordering PATH.
+ */
+async function findOtherCopies(
+	s: ProbeSession,
+	name: string,
+	f: ToolFacts,
+	onPath: string,
+	resolvedPath: string,
+): Promise<void> {
+	f.pathDir = homeShort(s.io, path.dirname(onPath));
+	if (!s.io.resolveAllExecutables) return;
+	const seen = new Set([resolvedPath]);
+	const copies: OtherCopy[] = [];
+	for (const candidate of await s.io.resolveAllExecutables(name)) {
+		if (candidate === onPath) continue;
+		const real = await s.io.realpath(candidate);
+		if (!real || seen.has(real)) continue;
+		seen.add(real);
+		copies.push({
+			...(await describeCopy(s, name, real)),
+			dir: homeShort(s.io, path.dirname(candidate)),
+		});
+	}
+	if (copies.length > 0) f.otherCopies = copies;
+}
+
 async function probeNodeGlobal(
 	s: ProbeSession,
 	spec: ManagedTool,
@@ -1794,14 +2068,27 @@ async function probeInto(
 	// 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);
+	// Or a standalone installer's, which may update itself (`uv self update`).
+	if (f.managed !== true) await adoptOwnInstaller(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);
 
+	// A program the operating system ships keeps no record anywhere: ask it.
+	if (f.installed === null) await versionFromOs(s, f, resolvedPath);
+
 	// Still nothing: read the running file itself — but only where the caller
 	// opted into running a check command (see there).
 	if (f.installed === null) await versionFromCheck(s, spec, f, onPath);
+
+	// A KEPT row names who installed it, not the installer magus would use.
+	if (f.managed === false && !f.ownerName) {
+		const who = await nameOwner(s, resolvedPath);
+		if (who) f.ownerName = who;
+	}
+
+	await findOtherCopies(s, spec.name, f, onPath, resolvedPath);
 }
 
 /**

package/src/services/update-plan.ts

@@ -1034,6 +1034,8 @@ export interface BinUpdateItem {
 	 * the same value the TUI's row runs on Enter.
 	 */
 	upgradeCommand?: Command;
+	/** {@link ToolStatus.shadowed}: a newer copy later on PATH, unused. */
+	shadowed?: string;
 	/** The exact pin, when the profile declares one. */
 	version?: string;
 	/** The version PATH runs, or null when absent / unreadable. */
@@ -1089,6 +1091,7 @@ export function planBinUpdates(
 		};
 		if (status.note) item.note = status.note;
 		if (status.adopted) item.adopted = status.adopted;
+		if (status.shadowed) item.shadowed = status.shadowed;
 		if (f?.upgradeCommand) item.upgradeCommand = f.upgradeCommand;
 		if (bin.version) item.version = bin.version;
 		return item;

package/src/ui/renderers/cliToolRenderers.tsx

@@ -397,6 +397,17 @@ export function renderCliToolDetail(
 						</text>
 					</box>
 				) : null}
+				{/* A newer copy later on PATH, which nothing runs. */}
+				{status?.shadowed ? (
+					<box flexDirection="row">
+						<text fg={theme.colors.muted} flexShrink={0}>
+							{"Warning  "}
+						</text>
+						<text fg={theme.colors.warning} minWidth={0}>
+							{wrapValue(`⚠ ${status.shadowed}`, width)}
+						</text>
+					</box>
+				) : null}
 				{status?.installed ? (
 					<box flexDirection="row">
 						<text fg={theme.colors.muted} flexShrink={0}>