claudeup 4.30.0 → 4.32.0

package/src/__tests__/moved-marketplace.test.ts

@@ -0,0 +1,87 @@
+/**
+ * An orphaned plugin that merely changed marketplace is not deprecated.
+ *
+ * Splitting `magus` into `magus` + `magus-marketing` left `seo@magus`,
+ * `instantly@magus`, `video-editing@magus` and `nanobanana@magus` installed
+ * under a namespace that no longer lists them. They rendered as bare
+ * "deprecated", whose only action is deletion — which drops a plugin that is
+ * still published, just under a different id.
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { LocalMarketplace } from "../services/local-marketplace.js";
+
+/**
+ * Mirrors `findPluginInOtherMarketplace` in plugin-manager.ts, which is module
+ * -private. Kept in lockstep with it; the behaviour, not the binding, is what
+ * these tests pin.
+ */
+function findPluginInOtherMarketplace(
+	pluginName: string,
+	currentMarketplace: string,
+	localMarketplaces: Map<string, LocalMarketplace>,
+): string | undefined {
+	for (const [name, mp] of localMarketplaces) {
+		if (name === currentMarketplace) continue;
+		if (mp.plugins.some((p) => p.name === pluginName)) return name;
+	}
+	return undefined;
+}
+
+const mp = (name: string, plugins: string[]): [string, LocalMarketplace] => [
+	name,
+	{
+		name,
+		description: "",
+		plugins: plugins.map((p) => ({
+			name: p,
+			version: "1.0.0",
+			description: "",
+		})),
+	},
+];
+
+describe("moved-marketplace detection", () => {
+	test("finds a plugin that moved to a sibling marketplace", () => {
+		const marketplaces = new Map([
+			mp("magus", ["dev", "terminal"]),
+			mp("magus-marketing", ["seo", "instantly", "video-editing"]),
+		]);
+
+		expect(findPluginInOtherMarketplace("seo", "magus", marketplaces)).toBe(
+			"magus-marketing",
+		);
+	});
+
+	test("a genuinely retired plugin reports no destination", () => {
+		// `conductor` was removed at magus v8.0.0 and republished nowhere.
+		const marketplaces = new Map([
+			mp("magus", ["dev"]),
+			mp("magus-marketing", ["seo"]),
+		]);
+
+		expect(
+			findPluginInOtherMarketplace("conductor", "magus", marketplaces),
+		).toBeUndefined();
+	});
+
+	test("does not propose the marketplace it is already installed from", () => {
+		const marketplaces = new Map([mp("magus", ["dev"])]);
+		expect(findPluginInOtherMarketplace("dev", "magus", marketplaces)).toBe(
+			undefined,
+		);
+	});
+
+	test("a renamed plugin is not matched — the name is the identity", () => {
+		// nanobanana became image-generate. Names differ, so this correctly
+		// reports no destination rather than guessing at a rename.
+		const marketplaces = new Map([
+			mp("magus", ["dev"]),
+			mp("magus-marketing", ["image-generate"]),
+		]);
+
+		expect(
+			findPluginInOtherMarketplace("nanobanana", "magus", marketplaces),
+		).toBeUndefined();
+	});
+});

package/src/__tests__/profile-materializer.test.ts

@@ -38,6 +38,36 @@ describe("buildProfileSettings", () => {
 		});
 		expect(s.enableAllProjectMcpServers).toBe(true);
 	});
+
+	// Regression: `install` enables the manifest-wide union at USER scope, and
+	// Claude Code resolves enabledPlugins per plugin id — an id the project
+	// scope omits falls through to the user scope's `true`. A profile that
+	// merely omits another profile's plugins therefore never disables them, so
+	// `profile switch` silently becomes additive instead of exclusive.
+	test("explicitly disables union plugins the profile excludes", () => {
+		const s = buildProfileSettings(
+			closure({ plugins: { "designer@magus": "latest" } }),
+			["designer@magus", "terminal@magus", "gtd@magus"],
+		);
+		expect(s.enabledPlugins).toEqual({
+			"designer@magus": true,
+			"terminal@magus": false,
+			"gtd@magus": false,
+		});
+	});
+
+	test("a profile's own plugin wins over its union entry", () => {
+		const s = buildProfileSettings(
+			closure({ plugins: { "terminal@magus": "4.1.4" } }),
+			["terminal@magus"],
+		);
+		expect(s.enabledPlugins).toEqual({ "terminal@magus": true });
+	});
+
+	test("no union given -> no false entries (unchanged legacy shape)", () => {
+		const s = buildProfileSettings(closure({ plugins: { "dev@magus": "latest" } }));
+		expect(s.enabledPlugins).toEqual({ "dev@magus": true });
+	});
 });
 
 describe("buildProfileMcp", () => {
@@ -79,4 +109,61 @@ describe("materializeProfile", () => {
 		const settings = await fs.readJson(join(dir, "settings.json"));
 		expect(settings.enabledPlugins).toEqual({ "b@m": true });
 	});
+
+	// Regression: activating a profile replaces .claude/skills with a symlink,
+	// and replacing means fs.remove first. A repo that committed its own project
+	// skills before adopting profiles would lose them at that moment.
+	test("seeds skills/ from the project's pre-existing .claude/skills", async () => {
+		const src = join(project, ".claude", "skills", "systematic-debugging");
+		await fs.outputFile(join(src, "SKILL.md"), "# committed project skill\n");
+
+		const dir = await materializeProfile("p", closure(), project);
+
+		expect(
+			await fs.readFile(join(dir, "skills", "systematic-debugging", "SKILL.md"), "utf8"),
+		).toContain("committed project skill");
+	});
+
+	test("does not re-seed skills/ once the profile dir exists", async () => {
+		await fs.outputFile(
+			join(project, ".claude", "skills", "gone", "SKILL.md"),
+			"# removed later\n",
+		);
+		const dir = await materializeProfile("p", closure(), project);
+		await fs.remove(join(dir, "skills", "gone"));
+
+		await materializeProfile("p", closure(), project);
+
+		expect(await fs.pathExists(join(dir, "skills", "gone"))).toBe(false);
+	});
+
+	test("still creates an empty skills/ when the project has none", async () => {
+		const dir = await materializeProfile("p", closure(), project);
+		expect(await fs.pathExists(join(dir, "skills"))).toBe(true);
+		expect(await fs.readdir(join(dir, "skills"))).toEqual([]);
+	});
+
+	test("two profiles from one union each disable the other's plugins", async () => {
+		const union = ["designer@magus", "terminal@magus"];
+		const fe = await materializeProfile(
+			"frontend",
+			closure({ plugins: { "designer@magus": "latest" } }),
+			project,
+			union,
+		);
+		const be = await materializeProfile(
+			"backend",
+			closure({ plugins: { "terminal@magus": "latest" } }),
+			project,
+			union,
+		);
+		expect((await fs.readJson(join(fe, "settings.json"))).enabledPlugins).toEqual({
+			"designer@magus": true,
+			"terminal@magus": false,
+		});
+		expect((await fs.readJson(join(be, "settings.json"))).enabledPlugins).toEqual({
+			"designer@magus": false,
+			"terminal@magus": true,
+		});
+	});
 });

package/src/__tests__/version-snapshot.test.ts

@@ -1,7 +1,12 @@
 import { describe, expect, test } from "bun:test";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import {
   diffVersions,
   isKnownVersion,
+  loadSeenVersions,
+  saveSeenVersions,
   UNKNOWN_VERSION,
 } from "../services/version-snapshot.js";
 
@@ -109,3 +114,83 @@ describe("diffVersions — removals and mixed sets", () => {
     ]);
   });
 });
+
+describe("per-project baselines", () => {
+  /**
+   * The baseline used to be one flat map for the whole machine, but the
+   * versions written into it are resolved per project. Two projects
+   * legitimately on different versions overwrote each other's baseline, so
+   * every differing plugin was reported as "updated" on the next render — a
+   * change that never happened.
+   *
+   * CLAUDE_CONFIG_DIR, not HOME: os.homedir() reads the passwd database on
+   * macOS and ignores $HOME, so a HOME-only override writes to the operator's
+   * real ~/.claude. That is not hypothetical — it happened while writing these.
+   */
+  const withSandbox = async (fn: () => Promise<void>): Promise<void> => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "vsnap-"));
+    const prev = process.env.CLAUDE_CONFIG_DIR;
+    process.env.CLAUDE_CONFIG_DIR = dir;
+    try {
+      await fn();
+    } finally {
+      if (prev === undefined) delete process.env.CLAUDE_CONFIG_DIR;
+      else process.env.CLAUDE_CONFIG_DIR = prev;
+      await fs.rm(dir, { recursive: true, force: true });
+    }
+  };
+
+  test("a project with no baseline of its own reports nothing", async () => {
+    await withSandbox(async () => {
+      await saveSeenVersions("/proj/a", { "statusline@magus": "2.2.0" });
+      const baseline = await loadSeenVersions("/proj/b");
+      expect(baseline).toBeNull();
+      expect(diffVersions(baseline, { "statusline@magus": "2.5.0" })).toEqual([]);
+    });
+  });
+
+  test("saving one project preserves the others", async () => {
+    await withSandbox(async () => {
+      await saveSeenVersions("/proj/a", { "gtd@magus": "2.0.0" });
+      await saveSeenVersions("/proj/b", { "gtd@magus": "2.0.1" });
+      expect(await loadSeenVersions("/proj/a")).toEqual({ "gtd@magus": "2.0.0" });
+      expect(await loadSeenVersions("/proj/b")).toEqual({ "gtd@magus": "2.0.1" });
+    });
+  });
+
+  test("a real update inside one project is still reported", async () => {
+    await withSandbox(async () => {
+      await saveSeenVersions("/proj/a", { "dev@magus": "3.0.0" });
+      const previous = await loadSeenVersions("/proj/a");
+      expect(diffVersions(previous, { "dev@magus": "3.0.1" })).toEqual([
+        { pluginId: "dev@magus", kind: "updated", from: "3.0.0", to: "3.0.1" },
+      ]);
+    });
+  });
+
+  test("a pre-migration flat baseline is adopted once, then replaced", async () => {
+    await withSandbox(async () => {
+      const file = path.join(
+        process.env.CLAUDE_CONFIG_DIR as string,
+        "claudeup-version-snapshot.json",
+      );
+      await fs.writeFile(
+        file,
+        JSON.stringify({
+          seen: { "dev@magus": "3.0.0" },
+          seededAt: "2026-07-29T00:00:00.000Z",
+          updatedAt: "2026-07-29T00:00:00.000Z",
+        }),
+      );
+
+      // Legacy shape carries no project, so it stands in for whoever asks first
+      // rather than being thrown away.
+      expect(await loadSeenVersions("/proj/a")).toEqual({ "dev@magus": "3.0.0" });
+
+      await saveSeenVersions("/proj/a", { "dev@magus": "3.0.1" });
+      // Once per-project entries exist, the flat map is no longer consulted.
+      expect(await loadSeenVersions("/proj/b")).toBeNull();
+      expect(await loadSeenVersions("/proj/a")).toEqual({ "dev@magus": "3.0.1" });
+    });
+  });
+});

package/src/cli/install.ts

@@ -126,7 +126,16 @@ async function runCheck(
 // ── install steps ───────────────────────────────────────────────────────────
 
 async function ensureToolchains(closure: ResolvedClosure, yes: boolean): Promise<void> {
-	const toolchains = await detectToolchains(closure.bins);
+	// Only the binaries actually missing can need a toolchain. Checking all of
+	// them warns "pip isn't installed" on a machine whose pip-provided binaries
+	// are already on PATH — an alarming message about work that will not happen.
+	const missing: ResolvedBin[] = [];
+	for (const bin of closure.bins) {
+		if (!(await resolveExecutable(bin.name))) missing.push(bin);
+	}
+	if (missing.length === 0) return;
+
+	const toolchains = await detectToolchains(missing);
 	for (const tc of toolchains) {
 		if (tc.present) continue;
 		const bootstrap = TOOLCHAIN_BOOTSTRAP[tc.name];
@@ -160,11 +169,25 @@ async function registerMarketplaces(closure: ResolvedClosure): Promise<void> {
 	}
 }
 
+/**
+ * Install the closure's plugins at PROJECT scope.
+ *
+ * A profile is a property of one repo, so its plugins must be too. At user
+ * scope, adopting profiles in a single repo would enable that repo's plugins in
+ * every other project on the machine — and since Claude Code resolves
+ * enabledPlugins per id with fall-through, those would stay on everywhere.
+ * Project scope keeps the blast radius to this repo. The plugin *cache* is
+ * global either way, so `profile switch` stays offline.
+ *
+ * Whatever the CLI writes into .claude/settings.json here is transient:
+ * materialization rewrites that file from the manifest, and activation replaces
+ * it with a symlink. The manifest stays authoritative.
+ */
 async function installPlugins(closure: ResolvedClosure): Promise<void> {
 	for (const pluginId of Object.keys(closure.plugins)) {
 		try {
 			console.log(`+ plugin ${pluginId}`);
-			await installPlugin(pluginId, "user");
+			await installPlugin(pluginId, "project");
 		} catch (e) {
 			console.warn(`⚠ plugin ${pluginId}: ${(e as Error).message}`);
 		}
@@ -317,10 +340,18 @@ export async function runInstallCommand(
 
 	// Materialize every profile (so `profile switch` needs no reinstall), then
 	// activate the target (or the sole/first profile).
-	const toMaterialize = flags.profile ? [flags.profile] : profileIds;
-	for (const id of toMaterialize) {
+	//
+	// Every profile is materialized even when one was named: a profile arg scopes
+	// what gets *installed* and which becomes active, not which settings files
+	// exist. It also keeps the union below consistent across all of them — a
+	// profile left holding an older union would stop disabling plugins added
+	// since, silently making `switch` additive again.
+	const unionPluginIds = Object.keys(
+		(flags.profile ? await resolveAllProfiles(manifest) : closure).plugins,
+	);
+	for (const id of profileIds) {
 		const profileClosure = await resolveProfile(manifest, id);
-		await materializeProfile(id, profileClosure, projectPath);
+		await materializeProfile(id, profileClosure, projectPath, unionPluginIds);
 	}
 
 	// Keep the generated dir + active-profile symlinks out of git before

package/src/cli/router.ts

@@ -73,25 +73,33 @@ function printHelp(version: string): void {
 
 TUI tool for managing Claude Code plugins, MCPs, and configuration.
 
-Usage: claudeup [options]
-       claudeup claude [args...]  Run claude with auto-update prerunner
-       claudeup update            Update claudeup to latest version
+Usage: claudeup                    Open the interactive TUI
+       claudeup <command> [args]
 
 Options:
   -v, --version  Show version and check for updates
   -h, --help     Show this help message
   --no-refresh   Skip auto-refresh of marketplaces on startup
 
-Commands:
+Team profiles — reproduce this repo's Claude Code setup on any machine.
+The manifest is .claude/profiles.json, committed. See docs/team-configuration.md.
+  install [profile]  Install the profile's plugins, binaries, skills and env,
+                     then activate it. No argument installs every profile.
+    --check          Report drift only, write nothing (exits 1 in strict mode)
+    --yes, -y        Skip the confirmation prompt
+    --force          Discard unsynced local edits instead of refusing
+  profile list       Show every profile; ● marks the active one
+  profile show <n>   Print a profile's fully resolved closure
+  profile switch <n> Repoint the active profile — offline, no reinstall
+  profile sync       Promote local edits back into .claude/profiles.json
+  doctor             Check binary deps, profile symlinks, and conventions
+    --fix            Apply the repairs it can make itself
+
+Other commands:
   claude [args...]   Check for plugin updates (1h cache), then run claude
     -f, --force      Force update check (bypass 1h cache)
   update             Update claudeup itself to latest version
 
-Experimental (in development):
-  install [profile]  Install a team profile from .claude/profiles.json
-  profile <cmd>      list | show | switch | sync team profiles
-  doctor             Diagnose & repair plugin/marketplace/profile state
-
 Navigation (TUI):
   [1] Plugins    [4] Settings   [7] Git State
   [2] Skills     [5] Profiles   [8] Alias

package/src/prerunner/index.ts

@@ -1,7 +1,12 @@
 import os from "node:os";
 import path from "node:path";
 import fs from "fs-extra";
-import { isClaudeAvailable, updatePlugin } from "../services/claude-cli.js";
+import {
+	isClaudeAvailable,
+	type PluginScope,
+	repairPlugin,
+	updatePlugin,
+} from "../services/claude-cli.js";
 import { runClaude } from "../services/claude-runner.js";
 import {
 	cleanupExtraKnownMarketplaces,
@@ -10,6 +15,7 @@ import {
 	readGlobalSettings,
 	recoverMarketplaceSettings,
 	saveGlobalInstalledPluginVersion,
+	saveLocalInstalledPluginVersion,
 	writeGlobalSettings,
 } from "../services/claude-settings.js";
 import {
@@ -18,9 +24,12 @@ import {
 } from "../services/gitignore-prerun.js";
 import { refreshRegisteredMarketplaces } from "../services/marketplace-refresh.js";
 import { autoAddMissingMarketplaces } from "../services/marketplace-sync.js";
+import { clearContentDriftCache } from "../services/content-drift.js";
 import {
 	clearMarketplaceCache,
+	compareVersions,
 	getAvailablePlugins,
+	saveInstalledPluginVersion,
 } from "../services/plugin-manager.js";
 import {
 	checkPluginVersionMismatches,
@@ -32,6 +41,27 @@ export interface PrerunOptions {
 	force?: boolean; // Bypass cache and force update check
 }
 
+/**
+ * Record an installed version in the settings file that owns the given scope.
+ *
+ * Claude Code's CLI does not maintain `installedPluginVersions`, so claudeup
+ * keeps its own copy. Writing it at the WRONG scope is worse than not writing
+ * it: it makes a scope claim a version it does not have installed.
+ */
+async function saveInstalledPluginVersionForScope(
+	pluginId: string,
+	version: string,
+	scope: PluginScope,
+): Promise<void> {
+	if (scope === "user") {
+		await saveGlobalInstalledPluginVersion(pluginId, version);
+	} else if (scope === "local") {
+		await saveLocalInstalledPluginVersion(pluginId, version, process.cwd());
+	} else {
+		await saveInstalledPluginVersion(pluginId, version, process.cwd());
+	}
+}
+
 const CONTINUITY_PLUGIN_SENTINEL = "tmux-claude-continuity";
 const CONTINUITY_PLUGIN_SCRIPT = path.join(
 	os.homedir(),
@@ -290,12 +320,28 @@ export async function prerunClaude(
 					`✓ Refreshed marketplaces: ${mpRefresh.refreshed.join(", ")}`,
 				);
 			}
+			if (mpRefresh.autoUpdateDisabled.length > 0) {
+				// Silence here is what let a clone sit 11 days behind: the catalog
+				// stops moving, so every plugin from that marketplace reads as up
+				// to date and no update is ever offered.
+				for (const name of mpRefresh.autoUpdateDisabled) {
+					console.log(
+						`⚠ ${name}: auto-update disabled — its plugin catalog will not refresh, so updates stay hidden.`,
+					);
+				}
+				console.log(
+					`  Re-enable with: claude plugin marketplace update ${mpRefresh.autoUpdateDisabled[0]}  (or set autoUpdate:true in ~/.claude/plugins/known_marketplaces.json)`,
+				);
+			}
 			for (const name of mpRefresh.failed) {
 				console.warn(`⚠ Failed to refresh marketplace: ${name}`);
 			}
 
 			// STEP 2: Clear cache to force fresh plugin info
 			clearMarketplaceCache();
+			// The marketplace refresh above may have moved each clone's HEAD, and
+			// drift answers are relative to HEAD.
+			clearContentDriftCache();
 
 			// STEP 3: Get updated plugin info (to detect versions)
 			const plugins = await getAvailablePlugins();
@@ -305,6 +351,13 @@ export async function prerunClaude(
 				pluginId: string;
 				oldVersion: string;
 				newVersion: string;
+				/** Scopes actually updated — never assume "user". */
+				scopes: ReadonlyArray<PluginScope>;
+			}> = [];
+			/** Plugins whose files drifted under an unchanged version. */
+			const repairedPlugins: Array<{
+				pluginId: string;
+				scope: PluginScope;
 			}> = [];
 
 			const cliAvailable = await isClaudeAvailable();
@@ -314,6 +367,43 @@ export async function prerunClaude(
 				// 1. Plugin is enabled
 				// 2. Plugin has an update available
 				// 3. Plugin has both installedVersion and version (newVersion)
+				// A content-stale plugin has NO version bump to detect — its files
+				// changed under an unchanged version — so it must be repaired
+				// (uninstall+install) rather than updated. Auto-fixing broken state
+				// without human interaction is claudeup's job; leaving a plugin
+				// silently running deleted skills is exactly the state it exists
+				// to prevent.
+				if (
+					plugin.enabled &&
+					!plugin.hasUpdate &&
+					plugin.contentStale &&
+					plugin.installedVersion
+				) {
+					if (!cliAvailable) continue;
+					const staleScopes = (
+						[
+							["user", plugin.userScope],
+							["project", plugin.projectScope],
+							["local", plugin.localScope],
+						] as const
+					)
+						.filter(([, status]) => !!status?.version)
+						.map(([scope]) => scope);
+
+					for (const scope of staleScopes) {
+						try {
+							await repairPlugin(plugin.id, scope, process.cwd());
+							repairedPlugins.push({ pluginId: plugin.id, scope });
+						} catch (error) {
+							console.warn(
+								`⚠ Failed to repair ${plugin.id} (${scope}):`,
+								error instanceof Error ? error.message : "Unknown error",
+							);
+						}
+					}
+					continue;
+				}
+
 				if (
 					plugin.enabled &&
 					plugin.hasUpdate &&
@@ -325,14 +415,51 @@ export async function prerunClaude(
 							// CLI unavailable — skip update entirely, don't write phantom state
 							continue;
 						}
-						await updatePlugin(plugin.id, "user");
-						// CLI does NOT update installedPluginVersions — save it ourselves
-						await saveGlobalInstalledPluginVersion(plugin.id, plugin.version);
+
+						// Update every scope that actually holds an outdated install.
+						//
+						// This used to be a hardcoded `updatePlugin(plugin.id, "user")`,
+						// which was wrong for almost every real install: `hasUpdate` is
+						// computed from the CURRENT PROJECT's resolved version, while
+						// installs live per project in installed_plugins.json. On this
+						// machine 495 of 496 magus installs are project-scoped, so the
+						// prerunner detected project drift, "fixed" it at user scope,
+						// reported success — and left the project row untouched. Next run
+						// it detected the same drift again. The update never converged,
+						// which is what "auto-update ran but an update is still available"
+						// actually was.
+						const outdatedScopes = (
+							[
+								["user", plugin.userScope],
+								["project", plugin.projectScope],
+								["local", plugin.localScope],
+							] as const
+						)
+							.filter(
+								([, status]) =>
+									!!status?.version &&
+									compareVersions(plugin.version, status.version) > 0,
+							)
+							.map(([scope]) => scope);
+
+						if (outdatedScopes.length === 0) continue;
+
+						for (const scope of outdatedScopes) {
+							await updatePlugin(plugin.id, scope);
+							// The CLI does not maintain installedPluginVersions, so keep
+							// claudeup's own copy in step for the scope we just touched.
+							await saveInstalledPluginVersionForScope(
+								plugin.id,
+								plugin.version,
+								scope,
+							);
+						}
 
 						autoUpdatedPlugins.push({
 							pluginId: plugin.id,
 							oldVersion: plugin.installedVersion,
 							newVersion: plugin.version,
+							scopes: outdatedScopes,
 						});
 					} catch (error) {
 						// Non-fatal: Log warning and continue
@@ -357,8 +484,27 @@ export async function prerunClaude(
 			// STEP 6: Display auto-update summary
 			if (autoUpdatedPlugins.length > 0) {
 				console.log(`✓ Auto-updated ${autoUpdatedPlugins.length} plugin(s):`);
-				for (const { pluginId, oldVersion, newVersion } of autoUpdatedPlugins) {
-					console.log(`  - ${pluginId}: ${oldVersion} → ${newVersion}`);
+				for (const {
+					pluginId,
+					oldVersion,
+					newVersion,
+					scopes,
+				} of autoUpdatedPlugins) {
+					// Name the scope. "Auto-updated" that silently touched only user
+					// scope, while the project stayed behind, is exactly how this became
+					// untrustworthy.
+					console.log(
+						`  - ${pluginId}: ${oldVersion} → ${newVersion} (${scopes.join(", ")})`,
+					);
+				}
+			}
+
+			if (repairedPlugins.length > 0) {
+				console.log(
+					`✓ Repaired ${repairedPlugins.length} plugin(s) whose files changed without a version bump:`,
+				);
+				for (const { pluginId, scope } of repairedPlugins) {
+					console.log(`  - ${pluginId} (${scope})`);
 				}
 			}
 		}

package/src/services/claude-cli.ts

@@ -160,6 +160,37 @@ export async function uninstallPlugin(
 	}
 }
 
+/**
+ * Repair a plugin whose files drifted from the marketplace under an unchanged
+ * version — uninstall, then install again at the same scope.
+ *
+ * `claude plugin install` cannot do this alone. Measured against the real
+ * `MadAppGang/magus` marketplace (autotest/plugin-system/probe-05): with the
+ * version unchanged it reports *"Plugin is already installed"* and copies
+ * nothing — cache content and the recorded `gitCommitSha` both stay put.
+ * Uninstall-then-install refreshes both. That is why the only cure users ever
+ * found was removing the plugin and adding it back.
+ *
+ * The window between the two calls is real: if the install fails, the plugin is
+ * left uninstalled. The caller must surface that rather than swallow it, which
+ * is why the install error is rethrown with the state spelled out.
+ */
+export async function repairPlugin(
+	pluginId: string,
+	scope: PluginScope = "user",
+	projectPath?: string,
+): Promise<void> {
+	await uninstallPlugin(pluginId, scope, projectPath);
+	try {
+		await execClaude(["plugin", "install", pluginId, "--scope", scope], 60000);
+	} catch (error) {
+		const msg = error instanceof Error ? error.message : String(error);
+		throw new Error(
+			`${pluginId} was uninstalled from ${scope} scope but could not be reinstalled: ${msg}. Reinstall it manually with: claude plugin install ${pluginId} --scope ${scope}`,
+		);
+	}
+}
+
 /**
  * Enable a previously disabled plugin
  */