claudeup 6.1.0 → 6.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudeup",
-  "version": "6.1.0",
+  "version": "6.2.1",
   "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": "6.1.0",
-    "claudeup-darwin-x64": "6.1.0",
-    "claudeup-linux-x64": "6.1.0"
+    "claudeup-darwin-arm64": "6.2.1",
+    "claudeup-darwin-x64": "6.2.1",
+    "claudeup-linux-x64": "6.2.1"
   }
 }

package/src/__tests__/catalog-cache-store.test.ts

@@ -152,19 +152,57 @@ describe("rate-limit cooldown — survives a relaunch", () => {
     base = Date.now();
   });
 
-  /** Let a write-behind cooldown reach disk. */
-  const flush = () => new Promise((r) => setTimeout(r, 80));
-
-  // Only this block triggers write-behind, so only this block pays for draining
-  // it. Held here rather than in the outer afterEach so the catalog tests — which
-  // await every write — are not each charged the delay too.
-  afterEach(flush);
+  /**
+   * Wait until a write-behind cooldown has actually reached disk.
+   *
+   * This used to be `setTimeout(80)` — a guess at how long an unawaited write
+   * takes, which is not a synchronisation point. `recordRateLimit` persists
+   * fire-and-forget by design (`github-budget.ts` explains why), so on a loaded
+   * runner the write had not landed when the next `hydrateGitHubBudget()` read,
+   * and the restored strike count came back low. That failed CI as
+   * `Expected: 3, Received: 2` on Linux while passing 15/15 on a quiet macOS
+   * laptop — the signature of a timing guess, not of a real defect.
+   *
+   * Polling the store itself removes the guess: it returns as soon as the value
+   * is observable, and only gives up after a deadline no healthy machine
+   * reaches. `expected` is the strike count the caller just recorded; passing
+   * nothing waits for any persisted entry at all.
+   */
+  const flush = async (
+    host: string,
+    expected?: number,
+  ): Promise<void> => {
+    const deadline = Date.now() + 5000;
+    for (;;) {
+      // `base` keeps the read on the same clock the writes used: cooldowns are
+      // dropped on read once expired, so reading with a later `now` could hide
+      // an entry that is genuinely there.
+      const stored = (await readStoredCooldowns(base))[host];
+      if (stored && (expected === undefined || stored.strikes >= expected)) {
+        return;
+      }
+      if (Date.now() > deadline) {
+        throw new Error(
+          `cooldown for ${host} never reached disk (wanted strikes >= ${expected ?? "any"}, got ${stored?.strikes ?? "nothing"})`,
+        );
+      }
+      await new Promise((r) => setTimeout(r, 10));
+    }
+  };
+
+  // Teardown hygiene, NOT a synchronisation point — which is why it is a plain
+  // sleep and `flush` is not. Its only job is to let an in-flight write land
+  // before the temp config dir is removed; a write that arrives afterwards
+  // recreates a file in a deleted directory and harms nothing. Polling for a
+  // specific host here would be wrong: several tests in this block end with
+  // nothing on disk on purpose.
+  afterEach(() => new Promise((r) => setTimeout(r, 50)));
 
   it("is still in force in the next process", async () => {
     // THE defect this store exists to fix. Without persistence, launch two fired
     // six more doomed requests at a host it had already been refused by.
     recordRateLimit("raw.githubusercontent.com", new Headers(), base);
-    await flush();
+    await flush("raw.githubusercontent.com");
 
     resetGitHubBudget();
     resetCatalogCacheMemo();
@@ -185,7 +223,7 @@ describe("rate-limit cooldown — survives a relaunch", () => {
     // requests, learns it is limited once, and exits.
     const first = recordRateLimit("raw.githubusercontent.com", undefined, base);
     expect(first.strikes).toBe(1);
-    await flush();
+    await flush("raw.githubusercontent.com", 1);
 
     resetGitHubBudget();
     resetCatalogCacheMemo();
@@ -194,7 +232,7 @@ describe("rate-limit cooldown — survives a relaunch", () => {
     const second = recordRateLimit("raw.githubusercontent.com", undefined, base);
     expect(second.strikes).toBe(2);
     expect(second.until).toBeGreaterThan(first.until);
-    await flush();
+    await flush("raw.githubusercontent.com", 2);
 
     resetGitHubBudget();
     resetCatalogCacheMemo();
@@ -213,7 +251,7 @@ describe("rate-limit cooldown — survives a relaunch", () => {
       new Headers({ "retry-after": "600" }),
       base,
     );
-    await flush();
+    await flush("api.github.com");
 
     resetGitHubBudget();
     await hydrateGitHubBudget();

package/src/__tests__/cli-apply-seams.test.ts

@@ -41,6 +41,7 @@ function item(over: Partial<PluginUpdateItem> = {}): PluginUpdateItem {
 
 function deps(): PluginApplyDeps {
 	return {
+		install: mock(async () => {}),
 		update: mock(async () => {}),
 		repair: mock(async () => {}),
 		readInstalled: mock(async () => "2.0.0"),
@@ -199,14 +200,14 @@ describe("installPluginInScope — the scope-targeted path", () => {
 		// The whole reason this exists beside applyPlugins: the user picked a
 		// scope from a menu, so "every scope that is behind" would override them.
 		const d = deps();
-		const updated: Array<[string, string]> = [];
-		d.update = mock(async (id, scope) => {
-			updated.push([id, scope]);
+		const installed: Array<[string, string]> = [];
+		d.install = mock(async (id, scope) => {
+			installed.push([id, scope]);
 		});
 
 		await installPluginInScope("dev@magus", "local", PROJECT, d);
 
-		expect(updated).toEqual([["dev@magus", "local"]]);
+		expect(installed).toEqual([["dev@magus", "local"]]);
 	});
 
 	test("an unreadable version is reported, never guessed", async () => {

package/src/__tests__/go-module.test.ts

@@ -0,0 +1,43 @@
+/**
+ * goBinaryName: the one rule for turning a Go module path into the binary
+ * `go install` produces. Both consumers (plugin-setup's Go path and
+ * plugin-requires' `setup.go` branch) are tested through their own surfaces;
+ * this file pins the rule itself.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { goBinaryName } from "../utils/go-module.js";
+
+describe("goBinaryName", () => {
+	test("takes the last segment of a v0/v1 module path", () => {
+		expect(goBinaryName("github.com/MadAppGang/tmux-mcp")).toBe("tmux-mcp");
+	});
+
+	test("strips a trailing /v2 major-version suffix before taking the name", () => {
+		expect(goBinaryName("github.com/MadAppGang/tmux-mcp/v2")).toBe("tmux-mcp");
+	});
+
+	test("strips multi-digit suffixes (/v10, /v42)", () => {
+		expect(goBinaryName("github.com/x/tool/v10")).toBe("tool");
+		expect(goBinaryName("github.com/x/tool/v42")).toBe("tool");
+	});
+
+	test("a segment that merely starts with v2 is a name, not a suffix", () => {
+		expect(goBinaryName("github.com/x/v2tool")).toBe("v2tool");
+	});
+
+	test("v0 and v1 are never path suffixes, so they stay as names", () => {
+		// Nobody names a binary this, but the rule must not invent an exception.
+		expect(goBinaryName("github.com/x/v1")).toBe("v1");
+		expect(goBinaryName("github.com/x/v0")).toBe("v0");
+	});
+
+	test("a suffix in the middle of the path is not trailing and is kept", () => {
+		expect(goBinaryName("github.com/x/repo/v2/cmd/cli")).toBe("cli");
+	});
+
+	test("single-segment and empty inputs pass through", () => {
+		expect(goBinaryName("mytool")).toBe("mytool");
+		expect(goBinaryName("")).toBe("");
+	});
+});

package/src/__tests__/plugin-cli-argv.test.ts

@@ -0,0 +1,109 @@
+/**
+ * What `claude` subcommand does each plugin operation actually run?
+ *
+ * This file exists because the answer was wrong for a long time and nothing
+ * could see it. `updatePlugin` ran `claude plugin install`, on a comment that
+ * asserted install "handles both fresh installs and re-installs (upgrades)".
+ * It does not. Measured against Claude Code 2.1.252, with designer@magus
+ * installed at 0.6.0 and 0.6.1 published:
+ *
+ *     $ claude plugin install designer@magus --scope project
+ *     ✔ Plugin "designer@magus" is already installed (scope: project)   # exit 0
+ *
+ *     $ claude plugin update designer@magus --scope project
+ *     ✔ Plugin "designer" updated from 0.6.0 to 0.6.1 for scope project # exit 0
+ *
+ * Both exit 0. The no-op is indistinguishable from success at every layer
+ * above, so every claudeup update path — the TUI's `U`, "update all", the
+ * scope menu, `claudeup update`, the prerunner's auto-update — reported
+ * success and changed nothing, for ever.
+ *
+ * Mocking the CLI cannot catch that: a stub answers whatever the test asks it
+ * to. Only the argv is checkable here, so the argv is what these assert, with a
+ * real `claude` shim on PATH recording what it was called with.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+	chmodSync,
+	mkdirSync,
+	mkdtempSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import {
+	installPlugin,
+	repairPlugin,
+	updatePlugin,
+} from "../services/claude-cli.js";
+
+let root: string;
+let logFile: string;
+let savedPath: string | undefined;
+
+beforeEach(() => {
+	root = mkdtempSync(path.join(tmpdir(), "claude-argv-"));
+	const bin = path.join(root, "bin");
+	mkdirSync(bin);
+	logFile = path.join(root, "argv.log");
+
+	// A real executable, so this goes through which(1), execFile and the whole
+	// wrapper rather than a module double.
+	const shim = path.join(bin, "claude");
+	writeFileSync(shim, `#!/bin/sh\necho "$@" >> "${logFile}"\nexit 0\n`);
+	chmodSync(shim, 0o755);
+
+	savedPath = process.env.PATH;
+	// The shim dir goes FIRST so it shadows a real claude, but the system dirs
+	// stay: `getClaudePath` resolves through which(1), which lives in /usr/bin.
+	process.env.PATH = [bin, "/usr/bin", "/bin"].join(path.delimiter);
+});
+
+afterEach(() => {
+	process.env.PATH = savedPath ?? "";
+	rmSync(root, { recursive: true, force: true });
+});
+
+/** Every argv the shim saw, one line per invocation. */
+function calls(): string[] {
+	try {
+		return readFileSync(logFile, "utf8").trim().split("\n").filter(Boolean);
+	} catch {
+		return [];
+	}
+}
+
+describe("which claude subcommand each operation runs", () => {
+	test("updatePlugin runs `plugin update` — NOT `plugin install`", async () => {
+		await updatePlugin("designer@magus", "project");
+		expect(calls()).toEqual(["plugin update designer@magus --scope project"]);
+	});
+
+	test("installPlugin runs `plugin install`", async () => {
+		await installPlugin("designer@magus", "project");
+		expect(calls()).toEqual(["plugin install designer@magus --scope project"]);
+	});
+
+	test("repairPlugin uninstalls then installs, in that order", async () => {
+		// Content drift under an unchanged version: `update` has no version bump
+		// to act on and `install` answers "already installed", so only the
+		// uninstall+install pair re-copies the files.
+		await repairPlugin("designer@magus", "project", root);
+		expect(calls()).toEqual([
+			"plugin uninstall designer@magus --scope project",
+			"plugin install designer@magus --scope project",
+		]);
+	});
+
+	test("the scope reaches the CLI verbatim, at every scope", async () => {
+		await updatePlugin("dev@magus", "user");
+		await updatePlugin("dev@magus", "local");
+		expect(calls()).toEqual([
+			"plugin update dev@magus --scope user",
+			"plugin update dev@magus --scope local",
+		]);
+	});
+});

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

@@ -69,6 +69,46 @@ describe("parsePluginRequires — setup block (the established convention)", ()
 		expect(tmux.formula).toBe("tmux");
 	});
 
+	// Negative control for the /vN fix: basename(base) yields "v2" here, so
+	// without the go-module helper this test FAILS on `name`.
+	test("terminal's v2 pin: /v2 is the module's major version, not the binary", () => {
+		const r = parsePluginRequires({
+			name: "terminal",
+			setup: { go: ["github.com/MadAppGang/tmux-mcp/v2@v2.0.0"] },
+		});
+		expect(r.bin).toEqual([
+			{
+				name: "tmux-mcp",
+				via: "go",
+				module: "github.com/MadAppGang/tmux-mcp/v2",
+				version: "v2.0.0",
+				check: "tmux-mcp --version",
+			},
+		]);
+	});
+
+	// One manifest per spec: entries are keyed by binary name, so a v1 and a v2
+	// pin of the same module in ONE setup would (correctly) collapse to one.
+	test.each([
+		[
+			"github.com/MadAppGang/tmux-mcp@v1.7.1",
+			{ name: "tmux-mcp", module: "github.com/MadAppGang/tmux-mcp", version: "v1.7.1" },
+		],
+		[
+			"github.com/MadAppGang/tmux-mcp/v2",
+			{ name: "tmux-mcp", module: "github.com/MadAppGang/tmux-mcp/v2", version: undefined },
+		],
+		[
+			"github.com/x/v2tool@v1.0.0",
+			{ name: "v2tool", module: "github.com/x/v2tool", version: "v1.0.0" },
+		],
+	])("go spec %s → name/module/version", (spec, expected) => {
+		const r = parsePluginRequires({ setup: { go: [spec] } });
+		expect(
+			r.bin!.map((b) => ({ name: b.name, module: b.module, version: b.version })),
+		).toEqual([expected]);
+	});
+
 	test("browser-use's setup: pip packages", () => {
 		const r = parsePluginRequires({
 			name: "browser-use",

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

@@ -86,6 +86,7 @@ const {
 	extractGoVersion,
 	extractBinaryName,
 	parseAtSpec,
+	parseGoSpec,
 	parsePipSpec,
 	goDepNeedsInstall,
 	goDepDecision,
@@ -127,6 +128,89 @@ describe("extractGoBinaryName", () => {
 	it("handles empty string gracefully", () => {
 		expect(extractGoBinaryName("")).toBe("");
 	});
+
+	// Negative control for the /vN fix: a plain basename returns "v2" here.
+	// Without the go-module helper wired in, this test FAILS.
+	it("names the binary after the module, not its /v2 major-version suffix", () => {
+		expect(
+			extractGoBinaryName("github.com/MadAppGang/tmux-mcp/v2@v2.0.0"),
+		).toBe("tmux-mcp");
+	});
+
+	it("strips the /v2 suffix from an unpinned module path too", () => {
+		expect(extractGoBinaryName("github.com/MadAppGang/tmux-mcp/v2")).toBe(
+			"tmux-mcp",
+		);
+	});
+
+	it("keeps a name that merely starts with v2", () => {
+		expect(extractGoBinaryName("github.com/x/v2tool@v1.0.0")).toBe("v2tool");
+	});
+});
+
+// ---------------------------------------------------------------------------
+// 1b. parseGoSpec — the Go-specific view over parseAtSpec
+// ---------------------------------------------------------------------------
+
+describe("parseGoSpec", () => {
+	it("v1 module: name and pinned version", () => {
+		expect(parseGoSpec("github.com/MadAppGang/tmux-mcp@v1.7.1")).toEqual({
+			spec: "github.com/MadAppGang/tmux-mcp@v1.7.1",
+			name: "tmux-mcp",
+			version: "v1.7.1",
+		});
+	});
+
+	it("v2 module: the /v2 suffix is not the name, the version survives", () => {
+		expect(parseGoSpec("github.com/MadAppGang/tmux-mcp/v2@v2.0.0")).toEqual({
+			spec: "github.com/MadAppGang/tmux-mcp/v2@v2.0.0",
+			name: "tmux-mcp",
+			version: "v2.0.0",
+		});
+	});
+
+	it("v2 module without a pin: name resolved, version null", () => {
+		expect(parseGoSpec("github.com/MadAppGang/tmux-mcp/v2")).toEqual({
+			spec: "github.com/MadAppGang/tmux-mcp/v2",
+			name: "tmux-mcp",
+			version: null,
+		});
+	});
+
+	it("a segment that starts with v2 is a real name", () => {
+		expect(parseGoSpec("github.com/x/v2tool@v1.0.0")).toEqual({
+			spec: "github.com/x/v2tool@v1.0.0",
+			name: "v2tool",
+			version: "v1.0.0",
+		});
+	});
+
+	it("@latest is unpinned, same as parseAtSpec", () => {
+		expect(parseGoSpec("github.com/MadAppGang/tmux-mcp/v2@latest")).toEqual({
+			spec: "github.com/MadAppGang/tmux-mcp/v2@latest",
+			name: "tmux-mcp",
+			version: null,
+		});
+	});
+
+	// Terminal 5.0.0 contract cases (test plan Area 3, C5 and C6). They live
+	// here rather than in their own file because any test file that imports
+	// plugin-setup.js ahead of the mock.module seam above bakes the real
+	// execFile into promisify() and fails the installPluginDeps suites.
+	it("C5: a /v10 suffix is stripped in full, not only its first digit", () => {
+		const { name, version } = parseGoSpec("github.com/x/tool/v10@v10.1.0");
+		expect({ name, version }).toEqual({ name: "tool", version: "v10.1.0" });
+	});
+
+	it("C6: /v1 is never a Go major-version suffix, so it stays the name", () => {
+		const { name, version } = parseGoSpec("github.com/x/tool/v1@v1.0.0");
+		expect({ name, version }).toEqual({ name: "v1", version: "v1.0.0" });
+	});
+
+	it("C6 control: the same shape at /v2 is a suffix and is stripped", () => {
+		const { name, version } = parseGoSpec("github.com/x/tool/v2@v2.0.0");
+		expect({ name, version }).toEqual({ name: "tool", version: "v2.0.0" });
+	});
 });
 
 // ---------------------------------------------------------------------------
@@ -295,6 +379,14 @@ describe("extractGoVersion", () => {
 	it("returns null when unpinned", () => {
 		expect(extractGoVersion("github.com/user/tool")).toBeNull();
 	});
+	it("reads the pin behind a /v2 module path", () => {
+		expect(
+			extractGoVersion("github.com/MadAppGang/tmux-mcp/v2@v2.0.0"),
+		).toBe("v2.0.0");
+	});
+	it("a /v2 module path with no pin is unpinned, not pinned to v2", () => {
+		expect(extractGoVersion("github.com/MadAppGang/tmux-mcp/v2")).toBeNull();
+	});
 });
 
 describe("goDepNeedsInstall — version awareness", () => {
@@ -666,6 +758,16 @@ describe("parseAtSpec", () => {
 		expect(parseAtSpec("tool@latest").version).toBeNull();
 	});
 
+	it("does NOT apply the Go /vN rule — an npm scope may be named v2", () => {
+		// The Go major-version strip lives in parseGoSpec only; folding it in
+		// here would turn this scoped npm package into "@scope".
+		expect(parseAtSpec("@scope/v2@1.0.0")).toEqual({
+			spec: "@scope/v2@1.0.0",
+			name: "v2",
+			version: "1.0.0",
+		});
+	});
+
 	it("treats a bare name as unpinned", () => {
 		expect(parseAtSpec("tool")).toEqual({
 			spec: "tool",

package/src/__tests__/update-apply.test.ts

@@ -11,6 +11,7 @@ import {
 	type PluginApplyDeps,
 	applyPlugins,
 	installPluginInScope,
+	updatePluginInScope,
 } from "../services/update-engine.js";
 import type { PluginScope } from "../services/claude-cli.js";
 import type { PluginUpdateItem } from "../services/update-plan.js";
@@ -22,10 +23,14 @@ function stubDeps(
 	installedAfter: string | null | ((scope: PluginScope) => string | null),
 ) {
 	const saved: Array<{ id: string; version: string; scope: PluginScope }> = [];
+	const installed: Array<{ id: string; scope: PluginScope }> = [];
 	const updated: Array<{ id: string; scope: PluginScope }> = [];
 	const repaired: Array<{ id: string; scope: PluginScope }> = [];
 
 	const deps: PluginApplyDeps = {
+		install: mock(async (id: string, scope: PluginScope) => {
+			installed.push({ id, scope });
+		}),
 		update: mock(async (id: string, scope: PluginScope) => {
 			updated.push({ id, scope });
 		}),
@@ -43,7 +48,7 @@ function stubDeps(
 			},
 		),
 	};
-	return { deps, saved, updated, repaired };
+	return { deps, saved, installed, updated, repaired };
 }
 
 function item(over: Partial<PluginUpdateItem>): PluginUpdateItem {
@@ -132,13 +137,77 @@ describe("what gets RECORDED is what got installed", () => {
 
 describe("scope handling", () => {
 	test("a fresh install goes to project scope only", async () => {
-		const { deps, updated } = stubDeps("2.0.0");
+		const { deps, installed } = stubDeps("2.0.0");
 		await applyPlugins(
 			[item({ action: "install", installed: null, scopes: [] })],
 			PROJECT,
 			deps,
 		);
+		expect(installed).toEqual([{ id: "dev@magus", scope: "project" }]);
+	});
+
+	// Three actions, three Claude Code commands, each a silent no-op in the
+	// other two cases. Folding `install` and `update` together is what made
+	// every claudeup update path exit 0 having changed nothing: measured on
+	// Claude Code 2.1.252, `claude plugin install designer@magus --scope
+	// project` answers "already installed" and leaves 0.6.0 in place while
+	// 0.6.1 is published, and `claude plugin update` is the command that moves
+	// it. The reverse holds too — `update` on a plugin absent from the scope
+	// answers "already at the latest version" and installs nothing — so this
+	// asserts BOTH directions, not just the one that was broken.
+
+	test("an update runs `update`, never `install`", async () => {
+		const { deps, installed, updated } = stubDeps("2.0.0");
+		await applyPlugins([item({ action: "update" })], PROJECT, deps);
 		expect(updated).toEqual([{ id: "dev@magus", scope: "project" }]);
+		expect(installed).toEqual([]);
+	});
+
+	test("an update with NO row for this project installs instead", async () => {
+		// `claude plugin update --scope project` resolves the project from the
+		// working directory, and with no row there it updates some OTHER
+		// project's row instead. Measured on 2.1.252 from a directory holding no
+		// madbench row, it moved /Users/jack/mag/tmux-mcp — a project nobody
+		// named. Live for git worktrees, which inherit the parent repo's version
+		// while owning no row of their own.
+		const { deps, installed, updated } = stubDeps(null);
+		await applyPlugins([item({ action: "update" })], PROJECT, deps);
+		expect(installed).toEqual([{ id: "dev@magus", scope: "project" }]);
+		expect(updated).toEqual([]);
+	});
+
+	test("the row check is per scope, not per plugin", async () => {
+		// user scope holds a row, project scope does not: one must update and
+		// the other install, in the same pass.
+		const { deps, installed, updated } = stubDeps((scope) =>
+			scope === "user" ? "1.5.0" : null,
+		);
+		await applyPlugins([item({ scopes: ["user", "project"] })], PROJECT, deps);
+		expect(updated).toEqual([{ id: "dev@magus", scope: "user" }]);
+		expect(installed).toEqual([{ id: "dev@magus", scope: "project" }]);
+	});
+
+	test("a fresh install runs `install`, never `update`", async () => {
+		const { deps, installed, updated } = stubDeps("2.0.0");
+		await applyPlugins(
+			[item({ action: "install", installed: null, scopes: [] })],
+			PROJECT,
+			deps,
+		);
+		expect(installed).toEqual([{ id: "dev@magus", scope: "project" }]);
+		expect(updated).toEqual([]);
+	});
+
+	test("a repair runs neither — content drift needs uninstall+install", async () => {
+		const { deps, installed, updated, repaired } = stubDeps("1.0.0");
+		await applyPlugins(
+			[item({ action: "repair", target: "1.0.0", scopes: ["project"] })],
+			PROJECT,
+			deps,
+		);
+		expect(repaired).toEqual([{ id: "dev@magus", scope: "project" }]);
+		expect(installed).toEqual([]);
+		expect(updated).toEqual([]);
 	});
 
 	test("every outdated scope is updated AND recorded separately", async () => {
@@ -265,4 +334,24 @@ describe("installPluginInScope — a fresh install records what landed", () => {
 		).toBeNull();
 		expect(saved).toEqual([]);
 	});
+
+	// The scope menu's update branch went through the install helper for as
+	// long as both issued `claude plugin install`. They no longer do, so the
+	// two helpers must reach different commands or the menu silently no-ops
+	// exactly the way "update all" did.
+	test("the install helper runs `install`, the update helper runs `update`", async () => {
+		const a = stubDeps("2.0.0");
+		await installPluginInScope("dev@magus", "user", PROJECT, a.deps);
+		expect(a.installed).toEqual([{ id: "dev@magus", scope: "user" }]);
+		expect(a.updated).toEqual([]);
+
+		const b = stubDeps("2.0.0");
+		await updatePluginInScope("dev@magus", "user", PROJECT, b.deps);
+		expect(b.updated).toEqual([{ id: "dev@magus", scope: "user" }]);
+		expect(b.installed).toEqual([]);
+	});
+
+	test("the update helper takes no version parameter either", () => {
+		expect(updatePluginInScope.length).toBe(3);
+	});
 });

package/src/services/claude-cli.ts

@@ -109,25 +109,28 @@ async function recoverMissingMarketplace(
 }
 
 /**
- * Install a plugin using claude CLI
- * Handles enabling + version tracking + cache copy in one shot.
+ * Run a `claude plugin` subcommand, recovering once from a missing or stale
+ * marketplace.
  *
- * If the install fails because the plugin is "not found in marketplace",
- * attempts to recover (add the marketplace if missing, or refresh it if
- * stale) and retries once.
+ * Shared by install and update because the recovery is identical and the two
+ * had already been written twice; a third copy for `update` is how the next
+ * divergence starts.
  */
-export async function installPlugin(
+async function execPluginCommand(
+	verb: "install" | "update",
 	pluginId: string,
-	scope: PluginScope = "user",
+	scope: PluginScope,
+	timeoutMs?: number,
 ): Promise<void> {
+	const argv = ["plugin", verb, pluginId, "--scope", scope];
 	try {
-		await execClaude(["plugin", "install", pluginId, "--scope", scope]);
+		await execClaude(argv, timeoutMs);
 	} catch (error) {
 		const msg = error instanceof Error ? error.message : String(error);
 		if (msg.includes("not found in marketplace")) {
 			const marketplace = pluginId.split("@")[1];
 			if (marketplace && (await recoverMissingMarketplace(marketplace))) {
-				await execClaude(["plugin", "install", pluginId, "--scope", scope]);
+				await execClaude(argv, timeoutMs);
 				return;
 			}
 		}
@@ -135,6 +138,29 @@ export async function installPlugin(
 	}
 }
 
+/**
+ * Install a plugin using claude CLI
+ * Handles enabling + version tracking + cache copy in one shot.
+ *
+ * ONLY for a plugin that is not installed at this scope yet. On one already
+ * installed there, `claude plugin install` is a no-op that ignores the version
+ * — see {@link updatePlugin}.
+ *
+ * If the install fails because the plugin is "not found in marketplace",
+ * attempts to recover (add the marketplace if missing, or refresh it if
+ * stale) and retries once.
+ */
+export async function installPlugin(
+	pluginId: string,
+	scope: PluginScope = "user",
+): Promise<void> {
+	// 60s, matching update and repair. Before the install/update split this path
+	// ran through `updatePlugin`'s 60s budget; leaving it on the 30s default
+	// would have quietly halved the time a fresh install — the SLOWEST of the
+	// three, since it downloads and copies — is allowed to take.
+	await execPluginCommand("install", pluginId, scope, 60000);
+}
+
 /**
  * Uninstall a plugin using claude CLI.
  * Falls back to direct settings removal if CLI uninstall fails
@@ -212,11 +238,37 @@ export async function disablePlugin(
 }
 
 /**
- * Update a plugin to the latest version.
- * Uses `install` as primary method since `update` only works for plugins
- * originally installed via the CLI. `install` handles both fresh installs
- * and re-installs (upgrades) of existing plugins regardless of how they
- * were originally added.
+ * Update an ALREADY-INSTALLED plugin to the latest version.
+ *
+ * Runs `claude plugin update`, not `claude plugin install`.
+ *
+ * This used to run `install`, on the documented premise that it "handles both
+ * fresh installs and re-installs (upgrades) of existing plugins". That premise
+ * is false, and every claudeup update path was silently doing nothing because
+ * of it. Measured against Claude Code 2.1.252, with designer@magus at 0.6.0 and
+ * 0.6.1 published:
+ *
+ *     $ claude plugin install designer@magus --scope project
+ *     Installing plugin "designer@magus"...
+ *     ✔ Plugin "designer@magus" is already installed (scope: project)
+ *     EXIT: 0
+ *
+ *     $ claude plugin update designer@magus --scope project
+ *     Checking for updates for plugin "designer@magus" at project scope…
+ *     ✔ Plugin "designer" updated from 0.6.0 to 0.6.1 for scope project. Restart to apply.
+ *     EXIT: 0
+ *
+ * `install` is idempotent on (plugin, scope) and never looks at the version, so
+ * it exits 0 having done nothing — indistinguishable from success to every
+ * caller. The registry keeps the old version, the read-back in `update-engine`
+ * records that old version as "what landed", and the same update is offered
+ * again on the next run, for ever.
+ *
+ * The two commands are NOT interchangeable in the other direction either:
+ * `claude plugin update` on a plugin absent from this scope reports "already at
+ * the latest version" and installs nothing. A fresh install must go through
+ * {@link installPlugin}, and content drift under an unchanged version still
+ * needs {@link repairPlugin} — `update` has no version bump to act on there.
  *
  * Retries with marketplace update on "not found" errors (same as installPlugin).
  */
@@ -224,22 +276,7 @@ export async function updatePlugin(
 	pluginId: string,
 	scope: PluginScope = "user",
 ): Promise<void> {
-	try {
-		await execClaude(["plugin", "install", pluginId, "--scope", scope], 60000);
-	} catch (error) {
-		const msg = error instanceof Error ? error.message : String(error);
-		if (msg.includes("not found in marketplace")) {
-			const marketplace = pluginId.split("@")[1];
-			if (marketplace && (await recoverMissingMarketplace(marketplace))) {
-				await execClaude(
-					["plugin", "install", pluginId, "--scope", scope],
-					60000,
-				);
-				return;
-			}
-		}
-		throw error;
-	}
+	await execPluginCommand("update", pluginId, scope, 60000);
 }
 
 /**

package/src/services/content-drift.ts

@@ -7,7 +7,7 @@
  * invisible. No update is offered, and the only cure is a reinstall — which is
  * exactly the "plugin says installed but its skills are missing" report.
  *
- * This is not a hypothetical. `publish-dist.sh` force-pushes a rebuilt tree, so
+ * This is not a hypothetical. `publish-dist.sh` pushes a rebuilt tree, so
  * same-version-different-content is a normal outcome of the release process.
  * Measured on 2026-08-06: `cache/magus/dev/3.0.1/skills` held
  * {audit, tui-progress} while `marketplaces/magus/plugins/dev/skills` held

package/src/services/local-marketplace.ts

@@ -113,11 +113,13 @@ function getGitRemote(marketplacePath: string): string | undefined {
  * Names of the skills under `skillsDir`, recursing through grouping directories.
  *
  * A skill is a directory holding a SKILL.md, and it may sit one or more levels
- * down: dev groups its 43 skills under `skills/frontend/`, `skills/backend/`
- * and so on, and mattpocock groups its 37 under `skills/engineering/`. Reading
- * only the top level counted the *groups* — dev reported 9 skills against 43 on
- * disk, mattpocock 5 against 37 — and that count is what the plugin detail
- * panel prints.
+ * down: dev nests its skills by category under `skills/frontend/`,
+ * `skills/backend/` and so on, and mattpocock groups its 37 under
+ * `skills/engineering/`. Reading only the top level counted the *groups* — dev
+ * once reported 9 skills against 43 on disk, mattpocock 5 against 37 — and that
+ * count is what the plugin detail panel prints. dev also ships a `knowledge/`
+ * tree beside `skills/`: reference manuals reached by path, holding no SKILL.md
+ * and registering nothing, so this scan correctly never sees them.
  *
  * Depth is capped because this runs over every plugin of every cloned
  * marketplace on each list load, and a skill nested four levels below `skills/`

package/src/services/plugin-requires.ts

@@ -15,6 +15,7 @@ import type {
 	BinRequirement,
 	PluginRequires,
 } from "../types/index.js";
+import { goBinaryName } from "../utils/go-module.js";
 import { parsePluginId } from "../utils/string-utils.js";
 import { getLocalMarketplacesInfo } from "./plugin-manager.js";
 
@@ -98,15 +99,19 @@ function parseSetup(setup: unknown): BinRequirement[] {
 	pkgManager("npm");
 	pkgManager("pip");
 
+	// Not basename(): a Go module's trailing /vN is its major version, not the
+	// binary. `tmux-mcp/v2` installs `tmux-mcp`; naming it `v2` here made every
+	// downstream presence check look for a binary that never exists.
 	for (const spec of (s.go as string[] | undefined) ?? []) {
 		if (typeof spec !== "string") continue;
 		const { base, version } = splitVersion(spec);
+		const name = goBinaryName(base);
 		bins.push({
-			name: basename(base),
+			name,
 			via: "go",
 			module: base,
 			version,
-			check: `${basename(base)} --version`,
+			check: `${name} --version`,
 		});
 	}
 	for (const spec of (s.brew as string[] | undefined) ?? []) {

package/src/services/plugin-setup.ts

@@ -33,6 +33,7 @@ import { constants as fsConstants } from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { which } from "../utils/command-utils.js";
+import { goBinaryName } from "../utils/go-module.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -392,14 +393,32 @@ async function installCargoPackages(
 	}
 }
 
+/**
+ * {@link parseAtSpec} for a Go module spec.
+ *
+ * Same split, but the name comes from {@link goBinaryName}: Go's `/vN`
+ * major-version suffix is part of the module path, not the binary, so
+ * "github.com/MadAppGang/tmux-mcp/v2@v2.0.0" installs `tmux-mcp`, not `v2`.
+ * The generic parser cannot do this — an npm scope may legitimately be `v2`.
+ */
+export function parseGoSpec(spec: string): ParsedSpec {
+	const parsed = parseAtSpec(spec);
+	// Same separator rule as parseAtSpec: a leading `@` is never a version.
+	const at = spec.lastIndexOf("@");
+	const modulePath = at > 0 ? spec.slice(0, at) : spec;
+	return { ...parsed, name: goBinaryName(modulePath) };
+}
+
 /**
  * Extract binary name from a Go module path.
- * The binary name is the last path segment before @version.
- * e.g., "github.com/MadAppGang/tmux-mcp@latest" → "tmux-mcp"
- *       "github.com/user/tool" → "tool"
+ * The binary name is the last path segment before @version, minus any /vN
+ * major-version suffix.
+ * e.g., "github.com/MadAppGang/tmux-mcp@latest"    → "tmux-mcp"
+ *       "github.com/MadAppGang/tmux-mcp/v2@v2.0.0" → "tmux-mcp"
+ *       "github.com/user/tool"                      → "tool"
  */
 export function extractGoBinaryName(pkg: string): string {
-	return parseAtSpec(pkg).name;
+	return parseGoSpec(pkg).name;
 }
 
 /**
@@ -409,7 +428,7 @@ export function extractGoBinaryName(pkg: string): string {
  *       "github.com/user/tool"                  → null
  */
 export function extractGoVersion(pkg: string): string | null {
-	return parseAtSpec(pkg).version;
+	return parseGoSpec(pkg).version;
 }
 
 /** Normalize a semver-ish string for comparison: trim and drop a leading "v". */
@@ -641,7 +660,7 @@ export async function binaryDepDecision(
 
 /** {@link binaryDepDecision} for a Go module path. */
 export async function goDepDecision(pkg: string): Promise<GoDepDecision> {
-	return binaryDepDecision(parseAtSpec(pkg), getGoInstallDir);
+	return binaryDepDecision(parseGoSpec(pkg), getGoInstallDir);
 }
 
 /**

package/src/services/update-engine.ts

@@ -20,7 +20,7 @@
  * So the engine lives here, in `services/`, and both front ends drive it.
  * `cli/` and `ui/` are sibling presentation layers: they own how progress looks
  * and nothing else. Everything IO-shaped is injected — `PluginApplyDeps` for
- * the four Claude Code calls, `ApplyReporter` for progress, `runCommand` for
+ * the five Claude Code calls, `ApplyReporter` for progress, `runCommand` for
  * installers — so the same code drives an animated terminal meter, a TUI modal,
  * and a test that wants silence.
  *
@@ -31,7 +31,7 @@
 
 import path from "node:path";
 import type { PluginScope } from "./claude-cli.js";
-import { repairPlugin, updatePlugin } from "./claude-cli.js";
+import { installPlugin, repairPlugin, updatePlugin } from "./claude-cli.js";
 import {
 	readInstalledVersionForScope,
 	saveInstalledPluginVersionForScope,
@@ -114,6 +114,14 @@ export const SILENT_REPORTER: ApplyReporter = {
  * not there.
  */
 export interface PluginApplyDeps {
+	/**
+	 * A plugin NOT installed at this scope yet.
+	 *
+	 * Separate from {@link PluginApplyDeps.update} because the two are separate
+	 * Claude Code commands that each no-op in the other's case — see the note on
+	 * `updatePlugin` in claude-cli.ts.
+	 */
+	install: (pluginId: string, scope: PluginScope) => Promise<void>;
 	update: (pluginId: string, scope: PluginScope) => Promise<void>;
 	repair: (
 		pluginId: string,
@@ -134,6 +142,7 @@ export interface PluginApplyDeps {
 }
 
 export const REAL_PLUGIN_DEPS: PluginApplyDeps = {
+	install: installPlugin,
 	update: updatePlugin,
 	repair: repairPlugin,
 	readInstalled: readInstalledVersionForScope,
@@ -173,6 +182,43 @@ export function pluginNeedsWork(item: PluginUpdateItem): boolean {
 
 // -- plugins -----------------------------------------------------------------
 
+/**
+ * Advance a plugin at `scope`, choosing the command by whether THIS project
+ * actually holds an install row there.
+ *
+ * The check is not defensive tidiness — without it `update` mutates a project
+ * nobody named. `claude plugin update --scope project` resolves the project
+ * from the CLI's working directory, and when that directory has no row for the
+ * plugin it falls back to some OTHER project's row and updates that one.
+ * Measured on Claude Code 2.1.252, run from a directory with no madbench row:
+ *
+ *     $ claude plugin update madbench@magus --scope project
+ *     ✔ Plugin "madbench" updated from 0.2.4 to 0.3.0 for scope project
+ *       (/Users/jack/mag/tmux-mcp). Restart to apply changes.
+ *
+ * `/Users/jack/mag/tmux-mcp` was not the working directory and had nothing to
+ * do with the request. `plugin install` has no such fallback — it keys on the
+ * working directory — so the absent case must go there instead.
+ *
+ * This is live for git worktrees in particular: claudeup resolves a worktree's
+ * installed version by inheriting the parent repo's rows, so a worktree can
+ * report "0.2.4 installed, 0.3.0 available" while owning no row of its own.
+ * That is exactly the shape that used to reach `update`.
+ *
+ * `readInstalled` matches the project path EXACTLY (no worktree inheritance),
+ * which is what makes it the right question to ask here.
+ */
+async function advanceInScope(
+	deps: PluginApplyDeps,
+	pluginId: string,
+	scope: PluginScope,
+	projectPath: string,
+): Promise<void> {
+	const here = await deps.readInstalled(pluginId, scope, projectPath);
+	if (here) await deps.update(pluginId, scope);
+	else await deps.install(pluginId, scope);
+}
+
 export async function applyPlugins(
 	items: PluginUpdateItem[],
 	projectPath: string,
@@ -190,10 +236,22 @@ export async function applyPlugins(
 
 		try {
 			for (const scope of scopes) {
+				// Three actions, three DIFFERENT Claude Code commands. Each is a
+				// silent no-op in the other two cases:
+				//   repair  — same version, changed files: only uninstall+install
+				//             re-copies; `update` sees no version bump to act on.
+				//   install — absent at this scope: `update` answers "already at the
+				//             latest version" and installs nothing.
+				//   update  — installed but behind: `install` answers "already
+				//             installed", ignores the version, and exits 0.
+				// Folding install and update together is the bug that made every
+				// claudeup update path do nothing while reporting success.
 				if (item.action === "repair") {
 					await deps.repair(item.pluginId, scope, projectPath);
+				} else if (item.action === "install") {
+					await deps.install(item.pluginId, scope);
 				} else {
-					await deps.update(item.pluginId, scope);
+					await advanceInScope(deps, item.pluginId, scope, projectPath);
 				}
 
 				// Record what LANDED, not what we asked for.
@@ -240,26 +298,40 @@ export async function applyPlugins(
 }
 
 /**
- * Install ONE plugin into ONE explicitly chosen scope, recording what landed.
- *
- * "Install" covers updating too, because at the CLI layer there is no such
- * distinction: `claude-cli.ts`'s `installPlugin` and `updatePlugin` issue the
- * identical `claude plugin install <id> --scope <scope>`, and `install` is
- * documented there as how an update is performed. Naming this after the command
- * actually run is what makes it obvious that the fresh-install path belongs here
- * too — while it was called `updatePluginInScope`, the TUI's install branches
- * read as a different operation and grew their own record-keeping.
+ * One plugin, ONE explicitly chosen scope, recording what landed.
  *
  * For the scope-targeted actions — a menu where the user picked "install in user
  * scope" — where {@link applyPlugins}'s "every scope that is behind" would
  * override the choice they just made.
  *
- * It exists so those call sites still get the read-back: writing the version
+ * These exist so those call sites still get the read-back: writing the version
  * you EXPECTED is the bug documented at length in `applyPlugins`, and it was
  * live in the TUI's per-scope menu long after the CLI had fixed it.
  *
- * Takes no version parameter, deliberately: there is nothing for a caller to
- * pass that could be wrong.
+ * They take no version parameter, deliberately: there is nothing for a caller
+ * to pass that could be wrong.
+ */
+async function applyOneInScope(
+	run: (pluginId: string, scope: PluginScope) => Promise<void>,
+	pluginId: string,
+	scope: PluginScope,
+	projectPath: string,
+	deps: PluginApplyDeps,
+): Promise<string | null> {
+	await run(pluginId, scope);
+	const actual = await deps.readInstalled(pluginId, scope, projectPath);
+	if (actual) await deps.saveInstalled(pluginId, actual, scope, projectPath);
+	return actual;
+}
+
+/**
+ * Install a plugin NOT yet present at `scope`.
+ *
+ * This used to cover updating too, on the premise that `installPlugin` and
+ * `updatePlugin` issued the identical command. They no longer do, and never
+ * safely did: `claude plugin install` ignores the version of an install that is
+ * already there. Sending an update through here is why the TUI's scope menu
+ * reported success and changed nothing. Use {@link updatePluginInScope}.
  *
  * @returns the version actually on disk afterwards, or null if it could not be
  *   read — which is reported, never guessed.
@@ -270,10 +342,29 @@ export async function installPluginInScope(
 	projectPath: string,
 	deps: PluginApplyDeps = REAL_PLUGIN_DEPS,
 ): Promise<string | null> {
-	await deps.update(pluginId, scope);
-	const actual = await deps.readInstalled(pluginId, scope, projectPath);
-	if (actual) await deps.saveInstalled(pluginId, actual, scope, projectPath);
-	return actual;
+	return applyOneInScope(deps.install, pluginId, scope, projectPath, deps);
+}
+
+/**
+ * Advance a plugin ALREADY installed at `scope` to the latest published version.
+ *
+ * @returns the version actually on disk afterwards, or null if it could not be
+ *   read — which is reported, never guessed.
+ */
+export async function updatePluginInScope(
+	pluginId: string,
+	scope: PluginScope,
+	projectPath: string,
+	deps: PluginApplyDeps = REAL_PLUGIN_DEPS,
+): Promise<string | null> {
+	// Same guard as the apply loop, for the same reason — see advanceInScope.
+	return applyOneInScope(
+		(id, sc) => advanceInScope(deps, id, sc, projectPath),
+		pluginId,
+		scope,
+		projectPath,
+		deps,
+	);
 }
 
 // -- binaries ----------------------------------------------------------------

package/src/ui/screens/PluginsScreen.tsx

@@ -24,6 +24,7 @@ import {
 	applyPlugins,
 	pluginNeedsWork,
 	installPluginInScope,
+	updatePluginInScope,
 } from "../../services/update-engine.js";
 import { planPluginUpdates } from "../../services/update-plan.js";
 import {
@@ -932,7 +933,7 @@ export function PluginsScreen() {
 					// Scope is the user's explicit choice here, so this does NOT go
 					// through applyPlugins (which advances every scope behind). It
 					// still records the version READ BACK, not `latestVersion`.
-					await installPluginInScope(
+					await updatePluginInScope(
 						plugin.id,
 						scope,
 						state.projectPath || process.cwd(),
@@ -1162,7 +1163,7 @@ export function PluginsScreen() {
 					`Updating ${plugin.name} in ${scopeLabel}…\nclaude plugin install ${plugin.id} --scope ${scope}`,
 				);
 				// Explicit scope, read-back version — see the note above.
-				await installPluginInScope(
+				await updatePluginInScope(
 					plugin.id,
 					scope,
 					state.projectPath || process.cwd(),

package/src/utils/go-module.ts

@@ -0,0 +1,36 @@
+/**
+ * Go module path → installed binary name.
+ *
+ * `go install` names the binary after the last path element of the module
+ * path, EXCEPT when that element is a major-version suffix: the module
+ * `github.com/MadAppGang/tmux-mcp/v2` installs `tmux-mcp`, not `v2`. Taking a
+ * plain basename therefore points every later check at a binary that never
+ * exists — presence probes fail, so the module is reinstalled on every run,
+ * doctor reports it missing, and the pin comparison never runs at all.
+ *
+ * Only the Go rule lives here. npm and cargo share the `name@version` syntax
+ * but not the suffix convention — an npm scoped package can legitimately be
+ * called `@scope/v2` — so this must not be folded into the generic spec parser.
+ */
+
+/**
+ * Trailing major-version suffix per the Go modules spec: `/vN` with N >= 2.
+ * Anchored to the END of the path with nothing after `vN`, so a segment that
+ * merely starts with "v2" (`github.com/x/v2tool`) is a real name, not a suffix.
+ * v0 and v1 are never written as a path suffix. The alternation, not a plain
+ * `[2-9][0-9]*`, because that shorthand rejects v10–v19 — a first digit of 1
+ * is only excluded when it is the ONLY digit.
+ */
+const MAJOR_VERSION_SUFFIX = /\/v(?:[2-9]|[1-9][0-9]+)$/;
+
+/**
+ * The binary `go install <modulePath>` produces.
+ *
+ * Takes the MODULE PATH — the part before any `@version` — so callers that
+ * hold a full `path@version` spec split it first. An empty or single-segment
+ * input is returned unchanged.
+ */
+export function goBinaryName(modulePath: string): string {
+	const withoutSuffix = modulePath.replace(MAJOR_VERSION_SUFFIX, "");
+	return withoutSuffix.split("/").pop() || withoutSuffix;
+}