claudeup 4.29.0 → 4.30.0

package/package.json

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

package/src/__tests__/plugin-setup.test.ts

@@ -6,7 +6,10 @@
  * and `required` setup keys.
  */
 
-import { describe, it, expect, mock, beforeEach } from "bun:test";
+import { describe, it, expect, mock, beforeEach, afterEach } from "bun:test";
+import { mkdtemp, mkdir, writeFile, chmod, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
 // Real modules captured before the mock.module() overrides, so the mocks spread
 // the full surface instead of stripping exports (e.g. resolveExecutable) that
 // bun's global, non-restored mock.module would otherwise remove for later files.
@@ -81,7 +84,13 @@ mock.module("node:child_process", () => ({
 const {
 	extractGoBinaryName,
 	extractGoVersion,
+	extractBinaryName,
+	parseAtSpec,
+	parsePipSpec,
 	goDepNeedsInstall,
+	goDepDecision,
+	parseGoEnv,
+	classifyInstallReach,
 	installPluginDeps,
 	checkMissingDeps,
 } = await import("../services/plugin-setup.js");
@@ -296,7 +305,10 @@ describe("goDepNeedsInstall — version awareness", () => {
 
 	it("reinstalls when the pinned version differs from the installed one", async () => {
 		availableBinaries.add("tmux-mcp");
-		execResults.set("tmux-mcp --version", { stdout: "v1.6.1", stderr: "" });
+		execResults.set("/usr/bin/tmux-mcp --version", {
+			stdout: "v1.6.1",
+			stderr: "",
+		});
 
 		expect(
 			await goDepNeedsInstall("github.com/MadAppGang/tmux-mcp@v1.6.2"),
@@ -305,7 +317,10 @@ describe("goDepNeedsInstall — version awareness", () => {
 
 	it("skips when the installed version matches the pin (v-prefix insensitive)", async () => {
 		availableBinaries.add("tmux-mcp");
-		execResults.set("tmux-mcp --version", { stdout: "1.6.2", stderr: "" });
+		execResults.set("/usr/bin/tmux-mcp --version", {
+			stdout: "1.6.2",
+			stderr: "",
+		});
 
 		expect(
 			await goDepNeedsInstall("github.com/MadAppGang/tmux-mcp@v1.6.2"),
@@ -314,7 +329,7 @@ describe("goDepNeedsInstall — version awareness", () => {
 
 	it("reinstalls when the binary can't report its version", async () => {
 		availableBinaries.add("tmux-mcp");
-		execResults.set("tmux-mcp --version", {
+		execResults.set("/usr/bin/tmux-mcp --version", {
 			stdout: "",
 			stderr: "flag provided but not defined: -version",
 			error: true,
@@ -346,7 +361,10 @@ describe("checkMissingDeps — pinned go version mismatch", () => {
 	});
 
 	it("reports a present-but-outdated pinned binary as missing", async () => {
-		execResults.set("tmux-mcp --version", { stdout: "v1.6.1", stderr: "" });
+		execResults.set("/usr/bin/tmux-mcp --version", {
+			stdout: "v1.6.1",
+			stderr: "",
+		});
 
 		const missing = await checkMissingDeps({
 			go: ["github.com/MadAppGang/tmux-mcp@v1.6.2"],
@@ -363,7 +381,10 @@ describe("installPluginDeps — reinstalls an outdated pinned go binary", () =>
 	});
 
 	it("runs go install when the pinned version is newer than installed", async () => {
-		execResults.set("tmux-mcp --version", { stdout: "v1.6.1", stderr: "" });
+		execResults.set("/usr/bin/tmux-mcp --version", {
+			stdout: "v1.6.1",
+			stderr: "",
+		});
 		execResults.set("/usr/bin/go install", { stdout: "", stderr: "" });
 
 		const result = await installPluginDeps({
@@ -377,6 +398,481 @@ describe("installPluginDeps — reinstalls an outdated pinned go binary", () =>
 	});
 });
 
+// ---------------------------------------------------------------------------
+// 4c. Install reach — a version check is worthless if the install lands
+//     somewhere PATH never looks. Pure ordering rules, no mocking needed.
+// ---------------------------------------------------------------------------
+
+describe("parseGoEnv", () => {
+	it("reads GOBIN and GOPATH", () => {
+		expect(
+			parseGoEnv('{"GOBIN": "/custom/gobin", "GOPATH": "/home/u/go"}'),
+		).toEqual({ gobin: "/custom/gobin", gopath: "/home/u/go" });
+	});
+
+	// The line-oriented `go env GOBIN GOPATH` puts an EMPTY line first when GOBIN
+	// is unset. run() trims stdout, which used to shift GOPATH into GOBIN's slot
+	// and aim the install dir at ~/go instead of ~/go/bin. Keyed JSON can't shift.
+	it("keeps an unset GOBIN empty even though output gets trimmed", () => {
+		expect(parseGoEnv('{"GOBIN": "", "GOPATH": "/Users/jack/go"}')).toEqual({
+			gobin: "",
+			gopath: "/Users/jack/go",
+		});
+	});
+
+	it("survives empty output", () => {
+		expect(parseGoEnv("")).toEqual({ gobin: "", gopath: "" });
+	});
+
+	it("survives non-JSON output", () => {
+		expect(parseGoEnv("go: unknown flag -json")).toEqual({
+			gobin: "",
+			gopath: "",
+		});
+	});
+
+	it("ignores non-string values", () => {
+		expect(parseGoEnv('{"GOBIN": null, "GOPATH": 7}')).toEqual({
+			gobin: "",
+			gopath: "",
+		});
+	});
+});
+
+describe("classifyInstallReach", () => {
+	it("wins when the install dir is the first PATH entry holding it", () => {
+		expect(
+			classifyInstallReach(
+				["/home/u/go/bin", "/usr/bin"],
+				[],
+				"/home/u/go/bin",
+			),
+		).toEqual({ reach: "wins" });
+	});
+
+	it("wins when the install dir precedes another copy", () => {
+		expect(
+			classifyInstallReach(
+				["/home/u/go/bin", "/opt/homebrew/bin"],
+				["/opt/homebrew/bin"],
+				"/home/u/go/bin",
+			),
+		).toEqual({ reach: "wins" });
+	});
+
+	it("is shadowed when another copy precedes the install dir", () => {
+		expect(
+			classifyInstallReach(
+				["/home/u/.local/bin", "/home/u/go/bin"],
+				["/home/u/.local/bin"],
+				"/home/u/go/bin",
+			),
+		).toEqual({ reach: "shadowed", byDir: "/home/u/.local/bin" });
+	});
+
+	// The generalisation of the tmux-mcp incident: no foreign package needed,
+	// just Homebrew ahead of GOPATH/bin. go install writes one file, the version
+	// probe reads another, and the mismatch never resolves.
+	it("is shadowed by a homebrew copy ordered ahead of the go bin dir", () => {
+		expect(
+			classifyInstallReach(
+				["/opt/homebrew/bin", "/home/u/go/bin"],
+				["/opt/homebrew/bin"],
+				"/home/u/go/bin",
+			),
+		).toEqual({ reach: "shadowed", byDir: "/opt/homebrew/bin" });
+	});
+
+	it("reports off-path when the install dir is absent from PATH", () => {
+		expect(
+			classifyInstallReach(["/usr/bin", "/bin"], [], "/home/u/go/bin"),
+		).toEqual({ reach: "off-path" });
+	});
+
+	it("normalises trailing slashes and redundant segments", () => {
+		expect(
+			classifyInstallReach(["/home/u/go/bin/"], [], "/home/u/go/./bin"),
+		).toEqual({ reach: "wins" });
+	});
+
+	it("lets the first of several duplicate PATH entries decide", () => {
+		expect(
+			classifyInstallReach(
+				["/home/u/.local/bin", "/home/u/go/bin", "/home/u/.local/bin"],
+				["/home/u/.local/bin"],
+				"/home/u/go/bin",
+			),
+		).toEqual({ reach: "shadowed", byDir: "/home/u/.local/bin" });
+	});
+});
+
+// ---------------------------------------------------------------------------
+// 4d. End-to-end shadowing — real directories on a real PATH, so the fs scan
+//     is exercised rather than stubbed. Mirrors the tmux-mcp incident: a
+//     foreign binary earlier in PATH that cannot report a version.
+// ---------------------------------------------------------------------------
+
+describe("go deps shadowed by an earlier PATH entry", () => {
+	let tmpRoot: string;
+	let shadowDir: string;
+	let goBinDir: string;
+	let originalPath: string | undefined;
+
+	beforeEach(async () => {
+		availableBinaries = new Set(["go", "tmux-mcp"]);
+		execResults = new Map();
+
+		tmpRoot = await mkdtemp(path.join(tmpdir(), "claudeup-shadow-"));
+		shadowDir = path.join(tmpRoot, "shadow");
+		goBinDir = path.join(tmpRoot, "gobin");
+		await mkdir(shadowDir);
+		await mkdir(goBinDir);
+
+		// A foreign `tmux-mcp` earlier in PATH than the go install target.
+		const shim = path.join(shadowDir, "tmux-mcp");
+		await writeFile(shim, "#!/bin/sh\nexit 1\n");
+		await chmod(shim, 0o755);
+
+		originalPath = process.env.PATH;
+		process.env.PATH = [shadowDir, goBinDir].join(path.delimiter);
+
+		// GOBIN points at the (later) go bin dir.
+		execResults.set("/usr/bin/go env -json GOBIN GOPATH", {
+			stdout: JSON.stringify({ GOBIN: goBinDir, GOPATH: tmpRoot }),
+			stderr: "",
+		});
+		// The shim chokes on --version, exactly like the npm package did.
+		execResults.set("/usr/bin/tmux-mcp --version", {
+			stdout: "",
+			stderr: "ERR_PARSE_ARGS_UNKNOWN_OPTION",
+			error: true,
+		});
+	});
+
+	afterEach(async () => {
+		process.env.PATH = originalPath ?? "";
+		await rm(tmpRoot, { recursive: true, force: true });
+	});
+
+	it("reports blocked instead of asking for a futile install", async () => {
+		const decision = await goDepDecision(
+			"github.com/MadAppGang/tmux-mcp@v1.6.2",
+		);
+
+		expect(decision.action).toBe("blocked");
+		if (decision.action !== "blocked") return;
+		expect(decision.reason).toBe("shadowed");
+		expect(decision.detail).toContain(path.join(shadowDir, "tmux-mcp"));
+		expect(decision.detail).toContain(goBinDir);
+		expect(decision.detail).toContain("cannot change what runs");
+	});
+
+	it("fails the install rather than reporting a success that changes nothing", async () => {
+		execResults.set("/usr/bin/go install", { stdout: "", stderr: "" });
+
+		const result = await installPluginDeps({
+			go: ["github.com/MadAppGang/tmux-mcp@v1.6.2"],
+		});
+
+		expect(result.installed).toHaveLength(0);
+		expect(result.skipped).toHaveLength(0);
+		expect(result.failed).toHaveLength(1);
+		expect(result.failed[0].pkg).toBe(
+			"go:github.com/MadAppGang/tmux-mcp@v1.6.2",
+		);
+		expect(result.failed[0].error).toContain("cannot change what runs");
+	});
+
+	it("still counts as needing attention, so the UI surfaces it", async () => {
+		expect(
+			await goDepNeedsInstall("github.com/MadAppGang/tmux-mcp@v1.6.2"),
+		).toBe(true);
+
+		const missing = await checkMissingDeps({
+			go: ["github.com/MadAppGang/tmux-mcp@v1.6.2"],
+		});
+		expect(missing.go).toEqual(["github.com/MadAppGang/tmux-mcp@v1.6.2"]);
+	});
+
+	it("installs normally once the shadow is out of the way", async () => {
+		process.env.PATH = [goBinDir, shadowDir].join(path.delimiter);
+		execResults.set("/usr/bin/go install", { stdout: "", stderr: "" });
+
+		const result = await installPluginDeps({
+			go: ["github.com/MadAppGang/tmux-mcp@v1.6.2"],
+		});
+
+		expect(result.installed).toContain(
+			"go:github.com/MadAppGang/tmux-mcp@v1.6.2",
+		);
+		expect(result.failed).toHaveLength(0);
+	});
+
+	it("reports off-path when the go bin dir is not in PATH at all", async () => {
+		process.env.PATH = path.join(tmpRoot, "elsewhere");
+		availableBinaries.delete("tmux-mcp");
+
+		const decision = await goDepDecision(
+			"github.com/MadAppGang/tmux-mcp@v1.6.2",
+		);
+
+		expect(decision.action).toBe("blocked");
+		if (decision.action !== "blocked") return;
+		expect(decision.reason).toBe("install-dir-off-path");
+		expect(decision.detail).toContain("not in PATH");
+	});
+});
+
+// ---------------------------------------------------------------------------
+// 4e. Spec parsing — the root of both bug directions. Go never reinstalled
+//     because the pin was never compared; npm/cargo/pip always reinstalled
+//     because the raw spec was used as a lookup key.
+// ---------------------------------------------------------------------------
+
+describe("parseAtSpec", () => {
+	it("splits name and pinned version", () => {
+		expect(parseAtSpec("ripgrep@14.1.0")).toEqual({
+			spec: "ripgrep@14.1.0",
+			name: "ripgrep",
+			version: "14.1.0",
+		});
+	});
+
+	it("treats a leading @ as an npm scope, not a version", () => {
+		expect(parseAtSpec("@babel/cli")).toEqual({
+			spec: "@babel/cli",
+			name: "cli",
+			version: null,
+		});
+	});
+
+	it("pins a scoped npm package", () => {
+		expect(parseAtSpec("@babel/cli@7.0.0")).toEqual({
+			spec: "@babel/cli@7.0.0",
+			name: "cli",
+			version: "7.0.0",
+		});
+	});
+
+	it("keeps go module paths working", () => {
+		expect(parseAtSpec("github.com/MadAppGang/tmux-mcp@v1.6.2")).toEqual({
+			spec: "github.com/MadAppGang/tmux-mcp@v1.6.2",
+			name: "tmux-mcp",
+			version: "v1.6.2",
+		});
+	});
+
+	it("treats @latest as unpinned", () => {
+		expect(parseAtSpec("tool@latest").version).toBeNull();
+	});
+
+	it("treats a bare name as unpinned", () => {
+		expect(parseAtSpec("tool")).toEqual({
+			spec: "tool",
+			name: "tool",
+			version: null,
+		});
+	});
+});
+
+describe("parsePipSpec", () => {
+	it("reads an == pin", () => {
+		expect(parsePipSpec("mcp==1.2.3")).toEqual({
+			spec: "mcp==1.2.3",
+			name: "mcp",
+			version: "1.2.3",
+		});
+	});
+
+	it("tolerates whitespace around ==", () => {
+		expect(parsePipSpec("mcp == 1.2.3").version).toBe("1.2.3");
+	});
+
+	// A range is not a single version, so there is nothing to verify against.
+	it("treats >= as unpinned but still reads the name", () => {
+		expect(parsePipSpec("browser-use>=0.1.0")).toEqual({
+			spec: "browser-use>=0.1.0",
+			name: "browser-use",
+			version: null,
+		});
+	});
+
+	it("strips extras from the name", () => {
+		expect(parsePipSpec("uvicorn[standard]").name).toBe("uvicorn");
+	});
+
+	it("handles a bare distribution name", () => {
+		expect(parsePipSpec("browser-use")).toEqual({
+			spec: "browser-use",
+			name: "browser-use",
+			version: null,
+		});
+	});
+});
+
+describe("extractBinaryName — brew", () => {
+	it("drops the tap prefix", () => {
+		expect(extractBinaryName("memextech/tap/ht-mcp")).toBe("ht-mcp");
+	});
+
+	// brew's @ is part of the formula name, but the binary it provides is not
+	// called "node@18" — the old code looked for exactly that and never found it.
+	it("drops a versioned-formula suffix from the binary name", () => {
+		expect(extractBinaryName("node@18")).toBe("node");
+	});
+
+	it("leaves a plain formula alone", () => {
+		expect(extractBinaryName("ripgrep")).toBe("ripgrep");
+	});
+});
+
+// ---------------------------------------------------------------------------
+// 4f. Version awareness across the other managers
+// ---------------------------------------------------------------------------
+
+describe("pipDepNeedsInstall — via installPluginDeps", () => {
+	const PIP_VERSION = /^python3 -c import importlib\.metadata/;
+
+	beforeEach(() => {
+		availableBinaries = new Set(["uv"]);
+		execResults = new Map();
+	});
+
+	function pipVersion(stdout: string, error = false) {
+		// The probe is `python3 -c "...m.version('mcp')"`, matched by prefix.
+		execResults.set("python3 -c import importlib.metadata as m", {
+			stdout,
+			stderr: error ? "no such distribution" : "",
+			error,
+		});
+	}
+
+	it("skips a pinned package already at that version", async () => {
+		pipVersion("1.2.3");
+		const result = await installPluginDeps({ pip: ["mcp==1.2.3"] });
+
+		expect(result.skipped).toContain("pip:mcp==1.2.3");
+		expect(result.installed).toHaveLength(0);
+	});
+
+	it("reinstalls a pinned package sitting at another version", async () => {
+		pipVersion("1.2.2");
+		execResults.set("/usr/bin/uv pip install", { stdout: "", stderr: "" });
+
+		const result = await installPluginDeps({ pip: ["mcp==1.2.3"] });
+
+		expect(result.installed).toContain("pip:mcp==1.2.3");
+		expect(result.skipped).toHaveLength(0);
+	});
+
+	it("skips an unpinned package that is present", async () => {
+		pipVersion("0.9.0");
+		const result = await installPluginDeps({ pip: ["browser-use"] });
+
+		expect(result.skipped).toContain("pip:browser-use");
+	});
+
+	it("installs when the distribution is absent", async () => {
+		pipVersion("", true);
+		execResults.set("/usr/bin/uv pip install", { stdout: "", stderr: "" });
+
+		const result = await installPluginDeps({ pip: ["browser-use"] });
+
+		expect(result.installed).toContain("pip:browser-use");
+	});
+
+	it("reports a pinned mismatch through checkMissingDeps too", async () => {
+		pipVersion("1.2.2");
+		const missing = await checkMissingDeps({ pip: ["mcp==1.2.3"] });
+		expect(missing.pip).toEqual(["mcp==1.2.3"]);
+		expect(PIP_VERSION.test("python3 -c import importlib.metadata")).toBe(true);
+	});
+});
+
+describe("npm and cargo version awareness", () => {
+	// The reach check consults the real PATH and filesystem, so both are pinned
+	// to a temp dir here. Without that these tests would pass or fail depending
+	// on whether the machine running them happens to have ~/.cargo/bin on PATH.
+	let envRoot: string;
+	let savedPath: string | undefined;
+	let savedCargoRoot: string | undefined;
+
+	beforeEach(async () => {
+		availableBinaries = new Set(["bun", "cargo", "ripgrep"]);
+		execResults = new Map();
+
+		envRoot = await mkdtemp(path.join(tmpdir(), "claudeup-env-"));
+		await mkdir(path.join(envRoot, "bin"));
+		savedPath = process.env.PATH;
+		savedCargoRoot = process.env.CARGO_INSTALL_ROOT;
+		process.env.PATH = path.join(envRoot, "bin");
+		process.env.CARGO_INSTALL_ROOT = envRoot;
+	});
+
+	afterEach(async () => {
+		process.env.PATH = savedPath ?? "";
+		if (savedCargoRoot === undefined) process.env.CARGO_INSTALL_ROOT = "";
+		else process.env.CARGO_INSTALL_ROOT = savedCargoRoot;
+		await rm(envRoot, { recursive: true, force: true });
+	});
+
+	// The old code passed "ripgrep@14.1.0" to which(), never matched, and
+	// reinstalled on every single run.
+	it("skips a pinned npm package already at that version", async () => {
+		execResults.set("/usr/bin/ripgrep --version", {
+			stdout: "14.1.0",
+			stderr: "",
+		});
+		execResults.set("/usr/bin/bun pm bin -g", { stdout: "", stderr: "" });
+
+		const result = await installPluginDeps({ npm: ["ripgrep@14.1.0"] });
+
+		expect(result.skipped).toContain("npm:ripgrep@14.1.0");
+		expect(result.installed).toHaveLength(0);
+	});
+
+	it("reinstalls a pinned npm package at the wrong version", async () => {
+		execResults.set("/usr/bin/ripgrep --version", {
+			stdout: "14.0.0",
+			stderr: "",
+		});
+		execResults.set("/usr/bin/bun install -g", { stdout: "", stderr: "" });
+
+		const result = await installPluginDeps({ npm: ["ripgrep@14.1.0"] });
+
+		expect(result.installed).toContain("bun:ripgrep@14.1.0");
+	});
+
+	it("skips a pinned cargo crate already at that version", async () => {
+		execResults.set("/usr/bin/ripgrep --version", {
+			stdout: "ripgrep 14.1.0",
+			stderr: "",
+		});
+
+		const result = await installPluginDeps({ cargo: ["ripgrep@14.1.0"] });
+
+		expect(result.skipped).toContain("cargo:ripgrep@14.1.0");
+	});
+
+	it("installs a pinned cargo crate with --version, not crate@ver", async () => {
+		execResults.set("/usr/bin/ripgrep --version", {
+			stdout: "ripgrep 14.0.0",
+			stderr: "",
+		});
+		execResults.set("/usr/bin/cargo install ripgrep --version 14.1.0", {
+			stdout: "",
+			stderr: "",
+		});
+
+		const result = await installPluginDeps({ cargo: ["ripgrep@14.1.0"] });
+
+		// Only the exact `--version` invocation is stubbed as success, so this
+		// passing proves the argv shape.
+		expect(result.installed).toContain("cargo:ripgrep@14.1.0");
+		expect(result.failed).toHaveLength(0);
+	});
+});
+
 // ---------------------------------------------------------------------------
 // 5. checkMissingDeps tests — required binaries
 // ---------------------------------------------------------------------------

package/src/services/plugin-setup.ts

@@ -28,6 +28,8 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import fs from "fs-extra";
+import { access } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { which } from "../utils/command-utils.js";
@@ -105,28 +107,90 @@ async function detectPipCommand(): Promise<{
 }
 
 /**
- * Check if a Python package is already installed
+ * Check if a binary is available in PATH
  */
-async function isPythonPackageInstalled(pkg: string): Promise<boolean> {
-	// Convert package name to importable module name (e.g., browser-use → browser_use)
-	const moduleName = pkg.replace(/-/g, "_");
-	const result = await run("python3", ["-c", `import ${moduleName}`]);
-	return result.ok;
+async function isBinaryAvailable(name: string): Promise<boolean> {
+	return (await which(name)) !== null;
+}
+
+/** Last path segment, e.g. "memextech/tap/ht-mcp" → "ht-mcp". */
+function lastSegment(s: string): string {
+	return s.split("/").pop() || s;
 }
 
 /**
- * Check if a binary is available in PATH
+ * Extract binary name from a brew formula.
+ *
+ * Brew's `@` is part of the FORMULA NAME, not a version pin — `node@18` is a
+ * distinct formula, not "node pinned to 18" — so the spec is installed verbatim
+ * while the binary it provides drops the suffix.
  */
-async function isBinaryAvailable(name: string): Promise<boolean> {
-	return (await which(name)) !== null;
+export function extractBinaryName(pkg: string): string {
+	return lastSegment(pkg).replace(/@[^@/]*$/, "") || lastSegment(pkg);
+}
+
+/** A dependency spec split into what to install and what to verify. */
+export interface ParsedSpec {
+	/** The spec as declared, handed to the installer verbatim. */
+	spec: string;
+	/** Name used to locate the installed artifact. */
+	name: string;
+	/** Exact pinned version, or null when unpinned or a moving target. */
+	version: string | null;
+}
+
+/**
+ * Parse an `name@version` spec — the shared syntax of go, npm and cargo.
+ *
+ * A leading `@` is an npm SCOPE, not a version separator, so `@babel/cli` is
+ * unpinned while `@babel/cli@7.0.0` pins 7.0.0.
+ */
+export function parseAtSpec(spec: string): ParsedSpec {
+	const at = spec.lastIndexOf("@");
+	if (at <= 0) return { spec, name: lastSegment(spec), version: null };
+
+	const version = spec.slice(at + 1).trim();
+	const name = lastSegment(spec.slice(0, at));
+	if (!version || version === "latest") return { spec, name, version: null };
+	return { spec, name, version };
 }
 
 /**
- * Extract binary name from a brew formula or npm package
- * e.g., "memextech/tap/ht-mcp" → "ht-mcp"
+ * Parse a pip requirement. Only `==` is an exact, verifiable pin; `>=`, `~=`
+ * and friends describe a range, so there is no single version to check against.
  */
-function extractBinaryName(pkg: string): string {
-	return pkg.split("/").pop() || pkg;
+export function parsePipSpec(spec: string): ParsedSpec {
+	const exact = spec.match(/^\s*([A-Za-z0-9._-]+)\s*==\s*([^\s;]+)/);
+	if (exact) return { spec, name: exact[1], version: exact[2] };
+	const name = spec.split(/[<>=!~[;\s]/)[0].trim();
+	return { spec, name: name || spec, version: null };
+}
+
+/**
+ * The installed version of a pip distribution, or null when absent/unreadable.
+ * Uses importlib.metadata rather than an import probe: it reports the VERSION,
+ * and it works for distributions whose import name differs from their package
+ * name (browser-use → browser_use).
+ */
+async function getPipInstalledVersion(name: string): Promise<string | null> {
+	const { ok, stdout } = await run("python3", [
+		"-c",
+		`import importlib.metadata as m; print(m.version(${JSON.stringify(name)}))`,
+	]);
+	if (!ok || !stdout) return null;
+	return normalizeVersion(stdout.split("\n")[0]);
+}
+
+/**
+ * Does this pip requirement still need installing? Present-but-wrong-version
+ * counts: without that, bumping a pin in plugin.json is inert.
+ */
+async function pipDepNeedsInstall(pkg: string): Promise<boolean> {
+	const { name, version } = parsePipSpec(pkg);
+	const installed = await getPipInstalledVersion(name);
+	if (installed === null) return true;
+	if (!version) return false;
+	return normalizeVersion(version) !== installed;
 }
 
 /**
@@ -144,13 +208,13 @@ async function installPipPackages(
 		return;
 	}
 
-	// Filter out already installed
+	// Filter out those already at the pinned version
 	const toInstall: string[] = [];
 	for (const pkg of packages) {
-		if (await isPythonPackageInstalled(pkg)) {
-			result.skipped.push(`pip:${pkg}`);
-		} else {
+		if (await pipDepNeedsInstall(pkg)) {
 			toInstall.push(pkg);
+		} else {
+			result.skipped.push(`pip:${pkg}`);
 		}
 	}
 
@@ -188,11 +252,15 @@ async function installBrewPackages(
 	}
 
 	for (const pkg of packages) {
-		const binaryName = extractBinaryName(pkg);
-		if (await isBinaryAvailable(binaryName)) {
+		const decision = await brewDepDecision(pkg);
+		if (decision.action === "skip") {
 			result.skipped.push(`brew:${pkg}`);
 			continue;
 		}
+		if (decision.action === "blocked") {
+			result.failed.push({ pkg: `brew:${pkg}`, error: decision.detail });
+			continue;
+		}
 
 		const { ok, stderr } = await run(brewPath, ["install", pkg]);
 		if (ok) {
@@ -223,6 +291,24 @@ async function detectNpmCommand(): Promise<{
 	return null;
 }
 
+/**
+ * Global bin dir for the detected Node installer. Best effort: bun and npm
+ * report it differently, and null simply disables the reach check rather than
+ * blocking an install we can't reason about.
+ */
+async function getNpmInstallDir(installer: {
+	cmd: string;
+	label: string;
+}): Promise<string | null> {
+	if (installer.label === "bun") {
+		const { ok, stdout } = await run(installer.cmd, ["pm", "bin", "-g"], 10000);
+		return ok && stdout ? stdout.split("\n")[0].trim() : null;
+	}
+	const { ok, stdout } = await run(installer.cmd, ["prefix", "-g"], 10000);
+	if (!ok || !stdout) return null;
+	return path.join(stdout.split("\n")[0].trim(), "bin");
+}
+
 /**
  * Install global Node.js packages (prefers bun > npm)
  */
@@ -238,11 +324,23 @@ async function installNpmPackages(
 		return;
 	}
 
+	const installDir = () => getNpmInstallDir(installer);
+
 	for (const pkg of packages) {
-		if (await isBinaryAvailable(pkg)) {
+		// Parsed, not raw: `isBinaryAvailable("foo@1.2.3")` looks for a binary
+		// literally named "foo@1.2.3", never finds one, and reinstalls forever.
+		const decision = await binaryDepDecision(parseAtSpec(pkg), installDir);
+		if (decision.action === "skip") {
 			result.skipped.push(`npm:${pkg}`);
 			continue;
 		}
+		if (decision.action === "blocked") {
+			result.failed.push({
+				pkg: `${installer.label}:${pkg}`,
+				error: decision.detail,
+			});
+			continue;
+		}
 
 		const { ok, stderr } = await run(installer.cmd, [...installer.args, pkg]);
 		if (ok) {
@@ -269,12 +367,23 @@ async function installCargoPackages(
 	}
 
 	for (const pkg of packages) {
-		if (await isBinaryAvailable(pkg)) {
+		const parsed = parseAtSpec(pkg);
+		const decision = await binaryDepDecision(parsed, getCargoInstallDir);
+		if (decision.action === "skip") {
 			result.skipped.push(`cargo:${pkg}`);
 			continue;
 		}
+		if (decision.action === "blocked") {
+			result.failed.push({ pkg: `cargo:${pkg}`, error: decision.detail });
+			continue;
+		}
 
-		const { ok, stderr } = await run(cargoPath, ["install", pkg], 300000);
+		// `--version` rather than `crate@ver`: the explicit flag works on every
+		// cargo, the @ form only on recent ones.
+		const args = parsed.version
+			? ["install", parsed.name, "--version", parsed.version]
+			: ["install", parsed.spec];
+		const { ok, stderr } = await run(cargoPath, args, 300000);
 		if (ok) {
 			result.installed.push(`cargo:${pkg}`);
 		} else {
@@ -290,9 +399,7 @@ async function installCargoPackages(
  *       "github.com/user/tool" → "tool"
  */
 export function extractGoBinaryName(pkg: string): string {
-	// Strip @version suffix first
-	const withoutVersion = pkg.replace(/@[^/]*$/, "");
-	return withoutVersion.split("/").pop() || pkg;
+	return parseAtSpec(pkg).name;
 }
 
 /**
@@ -302,11 +409,7 @@ export function extractGoBinaryName(pkg: string): string {
  *       "github.com/user/tool"                  → null
  */
 export function extractGoVersion(pkg: string): string | null {
-	const at = pkg.lastIndexOf("@");
-	if (at === -1) return null;
-	const version = pkg.slice(at + 1);
-	if (version === "" || version === "latest") return null;
-	return version;
+	return parseAtSpec(pkg).version;
 }
 
 /** Normalize a semver-ish string for comparison: trim and drop a leading "v". */
@@ -315,43 +418,278 @@ function normalizeVersion(v: string): string {
 }
 
 /**
- * Read an installed binary's version via `<binary> --version`, normalized, or
- * null if it produced no usable version string. Used to tell whether a pinned Go
- * dependency is already at the right version.
+ * Read a binary's version via `<path> --version`, normalized, or null when it
+ * produced no usable version string.
+ *
+ * Takes a RESOLVED path, never a bare name. Probing by name would re-run PATH
+ * resolution and can read a different binary than the one whose presence was
+ * checked — which is how a version check ends up passing judgement on one file
+ * while `go install` fixes another.
  */
 async function getInstalledBinaryVersion(
-	binaryName: string,
+	binaryPath: string,
 ): Promise<string | null> {
-	const { ok, stdout } = await run(binaryName, ["--version"], 10000);
+	const { ok, stdout } = await run(binaryPath, ["--version"], 10000);
 	if (!ok || !stdout) return null;
 	const match = stdout.split("\n")[0].match(/v?\d+\.\d+\.\d+[^\s]*/);
 	return match ? normalizeVersion(match[0]) : null;
 }
 
+/** PATH split into ordered, non-empty entries. */
+function pathEntries(): string[] {
+	return (process.env.PATH || "").split(path.delimiter).filter(Boolean);
+}
+
 /**
- * Decide whether a Go dependency needs (re)installing. This is what makes a
- * plugin *update* actually update its binary: without a version check an
- * already-present binary is skipped forever, so a bumped plugin never pulls the
- * new binary.
+ * Parse `go env -json GOBIN GOPATH`.
  *
- *  - binary absent                                    → yes
- *  - pinned version, installed reports the same one   → no
- *  - pinned version, installed reports a different one → yes
- *  - pinned version, installed version can't be read  → yes (can't confirm the
- *    pin, so reinstall to be safe)
- *  - unpinned (@latest) and present                   → no (a moving target
+ * JSON rather than the line-oriented form deliberately: `go env GOBIN GOPATH`
+ * prints an empty FIRST line when GOBIN is unset, so any trimming of the output
+ * (which {@link run} does) silently promotes GOPATH into GOBIN's slot and points
+ * the install dir one level too high.
+ */
+export function parseGoEnv(stdout: string): { gobin: string; gopath: string } {
+	try {
+		const parsed = JSON.parse(stdout) as Record<string, unknown>;
+		const str = (v: unknown) => (typeof v === "string" ? v.trim() : "");
+		return { gobin: str(parsed.GOBIN), gopath: str(parsed.GOPATH) };
+	} catch {
+		return { gobin: "", gopath: "" };
+	}
+}
+
+/**
+ * The directory `go install` writes into: GOBIN when set, else GOPATH/bin.
+ * Null when go can't be asked — callers must then draw no conclusions about
+ * where an install would land.
+ */
+async function getGoInstallDir(): Promise<string | null> {
+	const goPath = await which("go");
+	if (!goPath) return null;
+	const { ok, stdout } = await run(
+		goPath,
+		["env", "-json", "GOBIN", "GOPATH"],
+		10000,
+	);
+	if (!ok) return null;
+	const { gobin, gopath } = parseGoEnv(stdout);
+	if (gobin) return gobin;
+	if (gopath) return path.join(gopath, "bin");
+	return null;
+}
+
+/** Directories in `entries` (PATH order) holding an executable `binaryName`. */
+async function findOccurrenceDirs(
+	binaryName: string,
+	entries: string[],
+): Promise<string[]> {
+	const dirs: string[] = [];
+	for (const entry of entries) {
+		try {
+			await access(path.join(entry, binaryName), fsConstants.X_OK);
+			dirs.push(entry);
+		} catch {
+			// absent here, or not executable
+		}
+	}
+	return dirs;
+}
+
+export type InstallReach =
+	| { reach: "wins" }
+	| { reach: "shadowed"; byDir: string }
+	| { reach: "off-path" };
+
+/**
+ * Whether writing a binary into `installDir` would change what PATH resolves —
+ * the question `go install` on its own cannot answer.
+ *
+ * Walks PATH in order; the first entry that either IS the install dir or
+ * already holds the binary decides. Running off the end without meeting the
+ * install dir means a binary placed there can never be executed.
+ *
+ * Pure by design: the caller supplies `occurrenceDirs` and `installDir`, so the
+ * ordering rules are testable without touching a filesystem or a PATH.
+ */
+export function classifyInstallReach(
+	entries: string[],
+	occurrenceDirs: string[],
+	installDir: string,
+): InstallReach {
+	const target = path.resolve(installDir);
+	const occupied = new Set(occurrenceDirs.map((d) => path.resolve(d)));
+
+	for (const entry of entries) {
+		const dir = path.resolve(entry);
+		if (dir === target) return { reach: "wins" };
+		if (occupied.has(dir)) return { reach: "shadowed", byDir: entry };
+	}
+	return { reach: "off-path" };
+}
+
+export type GoDepDecision =
+	| {
+			action: "install";
+			reason: "absent" | "version-mismatch" | "version-unreadable";
+	  }
+	| { action: "skip"; reason: "up-to-date" | "unpinned-present" }
+	| {
+			action: "blocked";
+			reason: "shadowed" | "install-dir-off-path";
+			detail: string;
+	  };
+
+/**
+ * Why an install into the go bin dir would not take effect, or null when it
+ * would — or when we cannot tell, in which case we don't stand in the way.
+ */
+async function findInstallBlocker(
+	binaryName: string,
+	installedVersion: string | null,
+	getInstallDir: () => Promise<string | null>,
+): Promise<GoDepDecision | null> {
+	const installDir = await getInstallDir();
+	if (!installDir) return null;
+
+	const entries = pathEntries();
+	const reach = classifyInstallReach(
+		entries,
+		await findOccurrenceDirs(binaryName, entries),
+		installDir,
+	);
+
+	if (reach.reach === "wins") return null;
+
+	if (reach.reach === "off-path") {
+		return {
+			action: "blocked",
+			reason: "install-dir-off-path",
+			detail: [
+				`go install writes ${binaryName} to ${installDir}, which is not in`,
+				"PATH, so the installed binary would never run.",
+				`Add ${installDir} to PATH.`,
+			].join(" "),
+		};
+	}
+
+	const shadowPath = path.join(reach.byDir, binaryName);
+	const reports =
+		installedVersion === null
+			? "which cannot report a version"
+			: `which reports ${installedVersion}`;
+	return {
+		action: "blocked",
+		reason: "shadowed",
+		detail: [
+			`go install would write ${binaryName} to ${installDir}, but PATH resolves`,
+			`${binaryName} to ${shadowPath} first (${reports}), so installing cannot`,
+			`change what runs. Remove ${shadowPath}, or move ${installDir} ahead of`,
+			`${reach.byDir} in PATH.`,
+		].join(" "),
+	};
+}
+
+/**
+ * Decide what to do about a Go dependency. This is what makes a plugin *update*
+ * actually update its binary: without a version check an already-present binary
+ * is skipped forever, so a bumped plugin never pulls the new one.
+ *
+ * The binary is resolved ONCE and that exact path is probed. Resolving per step
+ * is how a version check judges one file while `go install` fixes another, then
+ * repeats forever — reporting success every time.
+ *
+ *  - binary absent                                      → install
+ *  - pinned version, resolved binary reports the same   → skip
+ *  - pinned version, resolved binary reports another     → install
+ *  - pinned version, version can't be read              → install (can't
+ *    confirm the pin, so reinstall to be safe)
+ *  - unpinned (@latest) and present                     → skip (a moving target
  *    can't be verified without a network round-trip)
+ *  - an install PATH would ignore                       → blocked, naming the
+ *    binary that shadows it
  */
-export async function goDepNeedsInstall(pkg: string): Promise<boolean> {
-	const binaryName = extractGoBinaryName(pkg);
-	if (!(await isBinaryAvailable(binaryName))) return true;
+export async function binaryDepDecision(
+	parsed: ParsedSpec,
+	getInstallDir: () => Promise<string | null>,
+): Promise<GoDepDecision> {
+	const { name, version: pinned } = parsed;
+	const resolved = await which(name);
+
+	if (!resolved) {
+		return (
+			(await findInstallBlocker(name, null, getInstallDir)) ?? {
+				action: "install",
+				reason: "absent",
+			}
+		);
+	}
 
-	const pinned = extractGoVersion(pkg);
-	if (!pinned) return false;
+	if (!pinned) return { action: "skip", reason: "unpinned-present" };
 
-	const installed = await getInstalledBinaryVersion(binaryName);
-	if (installed === null) return true;
-	return normalizeVersion(pinned) !== installed;
+	const installed = await getInstalledBinaryVersion(resolved);
+	if (installed !== null && installed === normalizeVersion(pinned)) {
+		return { action: "skip", reason: "up-to-date" };
+	}
+
+	return (
+		(await findInstallBlocker(name, installed, getInstallDir)) ?? {
+			action: "install",
+			reason: installed === null ? "version-unreadable" : "version-mismatch",
+		}
+	);
+}
+
+/** {@link binaryDepDecision} for a Go module path. */
+export async function goDepDecision(pkg: string): Promise<GoDepDecision> {
+	return binaryDepDecision(parseAtSpec(pkg), getGoInstallDir);
+}
+
+/**
+ * Where `cargo install` puts binaries: CARGO_INSTALL_ROOT, else CARGO_HOME/bin,
+ * else ~/.cargo/bin.
+ */
+async function getCargoInstallDir(): Promise<string | null> {
+	const root = process.env.CARGO_INSTALL_ROOT;
+	if (root) return path.join(root, "bin");
+	const home = process.env.CARGO_HOME;
+	if (home) return path.join(home, "bin");
+	return path.join(os.homedir(), ".cargo", "bin");
+}
+
+/** Where brew links binaries: `brew --prefix`/bin. */
+async function getBrewInstallDir(): Promise<string | null> {
+	const brewPath = await which("brew");
+	if (!brewPath) return null;
+	const { ok, stdout } = await run(brewPath, ["--prefix"], 10000);
+	if (!ok || !stdout) return null;
+	return path.join(stdout.split("\n")[0].trim(), "bin");
+}
+
+/** {@link binaryDepDecision} for a cargo crate. */
+export async function cargoDepDecision(pkg: string): Promise<GoDepDecision> {
+	return binaryDepDecision(parseAtSpec(pkg), getCargoInstallDir);
+}
+
+/**
+ * Decision for a brew formula. Brew has no exact-pin syntax, so `version` is
+ * always null and this reduces to presence plus a reach check — which is the
+ * case that actually bit us: a Homebrew copy sitting behind another PATH entry.
+ */
+export async function brewDepDecision(pkg: string): Promise<GoDepDecision> {
+	const name = extractBinaryName(pkg);
+	return binaryDepDecision(
+		{ spec: pkg, name, version: null },
+		getBrewInstallDir,
+	);
+}
+
+/**
+ * Boolean view of {@link goDepDecision}: does this dependency still need
+ * attention? A blocked dep counts — it is not satisfied, and the install path
+ * reports why rather than silently succeeding.
+ */
+export async function goDepNeedsInstall(pkg: string): Promise<boolean> {
+	return (await goDepDecision(pkg)).action !== "skip";
 }
 
 /**
@@ -370,11 +708,21 @@ async function installGoPackages(
 	}
 
 	for (const pkg of packages) {
-		if (!(await goDepNeedsInstall(pkg))) {
+		const decision = await goDepDecision(pkg);
+
+		if (decision.action === "skip") {
 			result.skipped.push(`go:${pkg}`);
 			continue;
 		}
 
+		// Installing would leave what actually runs untouched. Reporting success
+		// here is what turned a broken PATH into an endless reinstall loop that
+		// looked healthy every round, so say what's wrong instead.
+		if (decision.action === "blocked") {
+			result.failed.push({ pkg: `go:${pkg}`, error: decision.detail });
+			continue;
+		}
+
 		const { ok, stderr } = await run(goPath, ["install", pkg], 300000);
 		if (ok) {
 			result.installed.push(`go:${pkg}`);
@@ -529,10 +877,12 @@ export async function checkMissingDeps(
 ): Promise<SetupConfig> {
 	const missing: SetupConfig = {};
 
+	// Each of these mirrors its installer's decision function. When the two
+	// disagree the UI reports one thing and the install does another.
 	if (setup.pip?.length) {
 		const missingPip: string[] = [];
 		for (const pkg of setup.pip) {
-			if (!(await isPythonPackageInstalled(pkg))) {
+			if (await pipDepNeedsInstall(pkg)) {
 				missingPip.push(pkg);
 			}
 		}
@@ -542,8 +892,7 @@ export async function checkMissingDeps(
 	if (setup.brew?.length) {
 		const missingBrew: string[] = [];
 		for (const pkg of setup.brew) {
-			const bin = extractBinaryName(pkg);
-			if (!(await isBinaryAvailable(bin))) {
+			if ((await brewDepDecision(pkg)).action !== "skip") {
 				missingBrew.push(pkg);
 			}
 		}
@@ -551,9 +900,14 @@ export async function checkMissingDeps(
 	}
 
 	if (setup.npm?.length) {
+		const installer = await detectNpmCommand();
+		const installDir = installer
+			? () => getNpmInstallDir(installer)
+			: async () => null;
 		const missingNpm: string[] = [];
 		for (const pkg of setup.npm) {
-			if (!(await isBinaryAvailable(pkg))) {
+			const decision = await binaryDepDecision(parseAtSpec(pkg), installDir);
+			if (decision.action !== "skip") {
 				missingNpm.push(pkg);
 			}
 		}
@@ -563,7 +917,7 @@ export async function checkMissingDeps(
 	if (setup.cargo?.length) {
 		const missingCargo: string[] = [];
 		for (const pkg of setup.cargo) {
-			if (!(await isBinaryAvailable(pkg))) {
+			if ((await cargoDepDecision(pkg)).action !== "skip") {
 				missingCargo.push(pkg);
 			}
 		}