claudeup 6.1.0 → 6.2.0

package/package.json

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

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__/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__/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/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(),