claudeup 4.31.0 → 4.32.1

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
  */

package/src/services/claude-settings.ts

@@ -302,7 +302,23 @@ async function overlayRegistryVersions(
 	const merged = { ...base };
 	for (const [pluginId, entries] of Object.entries(registry.plugins ?? {})) {
 		const pick = pickRegistryEntry(entries, scope, projectPath);
-		if (pick?.version) merged[pluginId] = pick.version;
+		if (pick?.version) {
+			merged[pluginId] = pick.version;
+			continue;
+		}
+
+		// The registry knows this plugin but has no entry for this scope, so it
+		// is NOT installed here. Any leftover `installedPluginVersions` value is
+		// a claim about an install that does not exist.
+		//
+		// Claude Code never writes that field — it appears 0 times in the 2.1.223
+		// binary, and `claude plugin install` writes it at no scope — so only
+		// claudeup's own past writes can be in there, and they go stale silently.
+		// Measured: user settings claimed browser-use 1.1.2 / terminal 4.0.2 /
+		// code-analysis 5.1.0 while the registry said 1.4.0 / 4.1.4 / 5.3.1, and
+		// none of the claimed versions had a cache directory. Keeping the stale
+		// value made every one of them read as a permanent pending update.
+		if (entries && entries.length > 0) delete merged[pluginId];
 	}
 	return merged;
 }

package/src/services/content-drift.ts

@@ -0,0 +1,121 @@
+/**
+ * content-drift.ts — detect a plugin whose files changed without its version.
+ *
+ * The whole update system keys off one signal: the version string.
+ * `hasUpdate` is `compareVersions(catalogVersion, installedVersion) > 0`, so a
+ * marketplace that republishes different content under an unchanged version is
+ * 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
+ * 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
+ * {security-audit} — both stamped 3.0.1.
+ *
+ * The fix uses a signal already present in `installed_plugins.json`: each entry
+ * records `gitCommitSha`, the marketplace commit it was installed from. Asking
+ * git whether THIS PLUGIN'S SUBTREE changed between that commit and the
+ * marketplace's current HEAD answers the question exactly.
+ *
+ * Comparing whole-marketplace SHAs would be wrong: any commit to any plugin
+ * would flag every plugin as drifted. The subtree scope is what makes this
+ * precise enough to act on.
+ */
+
+import { spawn } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * Resolved per call, honouring CLAUDE_CONFIG_DIR — the same override Claude
+ * Code uses. A module-level constant would bake in `os.homedir()` at import
+ * time, which on macOS ignores $HOME and makes the service impossible to test
+ * without touching the operator's real marketplaces.
+ */
+function marketplacesDir(): string {
+	const configDir =
+		process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
+	return path.join(configDir, "plugins", "marketplaces");
+}
+
+/**
+ * Session cache. Keyed by marketplace + installed sha + plugin, because the
+ * answer cannot change while claudeup is open — the marketplace clone is only
+ * refreshed by Claude Code, out of process.
+ */
+const cache = new Map<string, boolean>();
+
+export function clearContentDriftCache(): void {
+	cache.clear();
+}
+
+function git(cwd: string, args: string[]): Promise<{ code: number; out: string }> {
+	return new Promise((resolve) => {
+		const child = spawn("git", args, { cwd, stdio: ["ignore", "pipe", "ignore"] });
+		let out = "";
+		child.stdout.on("data", (d) => {
+			out += String(d);
+		});
+		child.on("error", () => resolve({ code: -1, out: "" }));
+		child.on("close", (code) => resolve({ code: code ?? -1, out: out.trim() }));
+		// Never let a wedged git block the UI.
+		setTimeout(() => {
+			child.kill();
+			resolve({ code: -1, out: "" });
+		}, 5000).unref?.();
+	});
+}
+
+export interface DriftQuery {
+	marketplace: string;
+	/** Plugin name without the @marketplace suffix. */
+	pluginName: string;
+	/** `gitCommitSha` from the installed_plugins.json entry. */
+	installedSha: string | undefined;
+	/**
+	 * Path of the plugin inside the marketplace repo, from the catalog `source`
+	 * field (e.g. "./plugins/dev"). Defaults to `plugins/<name>`.
+	 */
+	sourcePath?: string;
+}
+
+/**
+ * True when the plugin's files in the marketplace differ from the commit it was
+ * installed from — i.e. a reinstall would deliver different content.
+ *
+ * Returns false whenever the question cannot be answered honestly: no recorded
+ * sha, no clone, git unavailable, or the recorded commit is absent locally
+ * (force-push, shallow clone). A false negative leaves today's behaviour; a
+ * false positive would nag the user to reinstall for no reason.
+ */
+export async function hasContentDrift(q: DriftQuery): Promise<boolean> {
+	if (!q.installedSha) return false;
+
+	const key = `${q.marketplace}\0${q.pluginName}\0${q.installedSha}`;
+	const hit = cache.get(key);
+	if (hit !== undefined) return hit;
+
+	const repo = path.join(marketplacesDir(), q.marketplace);
+	const rel = (q.sourcePath ?? `plugins/${q.pluginName}`).replace(/^\.\//, "");
+
+	// The recorded commit must exist locally, or the diff is meaningless.
+	const known = await git(repo, ["cat-file", "-e", `${q.installedSha}^{commit}`]);
+	if (known.code !== 0) {
+		cache.set(key, false);
+		return false;
+	}
+
+	// Exit 0 = no difference, 1 = differs, anything else = could not tell.
+	const diff = await git(repo, [
+		"diff",
+		"--quiet",
+		q.installedSha,
+		"HEAD",
+		"--",
+		rel,
+	]);
+	const drifted = diff.code === 1;
+	cache.set(key, drifted);
+	return drifted;
+}

package/src/services/marketplace-refresh.ts

@@ -34,8 +34,19 @@ export interface RefreshResult {
 	refreshed: string[];
 	/** Pull errored (network, diverged, timeout) — clone left intact and stale. */
 	failed: string[];
-	/** Nothing to do: no clone on disk, not a git repo, dirty tree, or opted out. */
+	/** Nothing to do: no clone on disk, not a git repo, or dirty tree. */
 	skipped: string[];
+	/**
+	 * Skipped specifically because `autoUpdate: false` in known_marketplaces.json.
+	 *
+	 * Called out separately from `skipped` because the consequence is invisible
+	 * and open-ended: the clone is the catalog, so a marketplace opted out here
+	 * never learns about new plugin versions, and every plugin from it reads as
+	 * up to date forever. The reporter's `magus` clone sat 11 days behind this
+	 * way — Claude Code would not refresh it, and this function skipped it too,
+	 * with nothing printed either time.
+	 */
+	autoUpdateDisabled: string[];
 }
 
 function cloneDir(name: string): string {
@@ -136,6 +147,7 @@ export async function refreshRegisteredMarketplaces(
 	const refreshed: string[] = [];
 	const failed: string[] = [];
 	const skipped: string[] = [];
+	const autoUpdateDisabled: string[] = [];
 
 	const configured = await getConfiguredMarketplaces();
 	const skipSet = new Set(skip);
@@ -149,7 +161,7 @@ export async function refreshRegisteredMarketplaces(
 			continue;
 		}
 		if ((await getMarketplaceAutoUpdate(name)) === false) {
-			skipped.push(name);
+			autoUpdateDisabled.push(name);
 			continue;
 		}
 		eligible.push(name);
@@ -169,5 +181,5 @@ export async function refreshRegisteredMarketplaces(
 		else skipped.push(name); // absent | skipped
 	});
 
-	return { refreshed, failed, skipped };
+	return { refreshed, failed, skipped, autoUpdateDisabled };
 }

package/src/services/plugin-manager.ts

@@ -12,11 +12,17 @@ import {
 	getLocalEnabledPlugins,
 	getLocalInstalledPluginVersions,
 	getProjectInstalledPluginVersions,
+	pickRegistryEntry,
+	readInstalledPluginsRegistry,
 	updateInstalledPluginsRegistry,
 	removeFromInstalledPluginsRegistry,
 } from "./claude-settings.js";
+import { hasContentDrift } from "./content-drift.js";
 import { defaultMarketplaces } from "../data/marketplaces.js";
-import type { PluginRelease } from "../types/index.js";
+import type {
+	InstalledPluginsRegistry,
+	PluginRelease,
+} from "../types/index.js";
 import {
 	scanLocalMarketplaces,
 	repairAllMarketplaces,
@@ -75,6 +81,23 @@ export interface PluginInfo {
 	mcpServers?: string[];
 	lspServers?: Record<string, unknown>;
 	isOrphaned?: boolean;
+	/**
+	 * Set when the installed version equals the catalog version, but the
+	 * plugin's files in the marketplace have changed since the commit it was
+	 * installed from. The version compare says "up to date" and is wrong: only
+	 * a reinstall delivers the current content. See content-drift.ts.
+	 */
+	contentStale?: boolean;
+	/**
+	 * For an orphaned plugin: another configured marketplace that publishes a
+	 * plugin of the same name — i.e. it did not disappear, it moved.
+	 *
+	 * Splitting `magus` into `magus` + `magus-marketing` left seo, instantly,
+	 * video-editing and image-generate installed under a namespace that no
+	 * longer lists them. Rendered as bare "deprecated", the only offered action
+	 * was deletion, which silently drops a plugin that is still published.
+	 */
+	movedTo?: string;
 	/**
 	 * Set when this plugin's installed version changed since claudeup last
 	 * rendered it — including updates made by Claude Code or the prerunner
@@ -112,6 +135,48 @@ export function isEnabledButNotInstalled(plugin: PluginInfo): boolean {
 	return enabledSomewhere && !plugin.installedVersion;
 }
 
+/**
+ * True when a scope genuinely has the plugin installed.
+ *
+ * `enabled` on its own is not proof. It is the `enabledPlugins` flag out of a
+ * settings file, and only claudeup and the user maintain it; `version` comes
+ * from `installed_plugins.json` via `overlayRegistryVersions`, which is what
+ * Claude Code actually loaded. When the two disagree — flag set, no registry
+ * entry — the plugin is in the broken enabled-but-not-installed state that the
+ * list already renders as "not installed".
+ *
+ * Every action that touches the filesystem must use this, not the flag alone.
+ * Deciding on the flag is what made the scope keys uninstall a plugin the row
+ * had just labelled "not installed".
+ *
+ * A version of "0.0.0" still counts as installed — Anthropic's official plugins
+ * record exactly that — which is why this tests presence, not `isKnownVersion`.
+ */
+export function isInstalledInScope(scope: ScopeStatus | undefined): boolean {
+	return !!scope?.enabled && !!scope.version;
+}
+
+/**
+ * What a scope toggle (`u` / `p` / `l`, or the Enter scope picker) should do.
+ *
+ * `install` doubles as the repair for enabled-but-not-installed. Measured
+ * against Claude Code 2.1.223 in exactly that state — `dev@magus` flagged in
+ * `.claude/settings.json` with no registry entry for the project path —
+ * `claude plugin install dev@magus --scope project` installed it normally and
+ * wrote the registry entry. It does not report "already installed", so this
+ * needs no uninstall-first dance (unlike content drift, see repairPlugin).
+ */
+export function resolveScopeAction(
+	scope: ScopeStatus | undefined,
+	latestVersion: string,
+): "install" | "update" | "uninstall" {
+	if (!isInstalledInScope(scope)) return "install";
+	const installed = scope?.version;
+	const hasUpdate =
+		!!installed && latestVersion !== "0.0.0" && installed !== latestVersion;
+	return hasUpdate ? "update" : "uninstall";
+}
+
 
 export async function getAvailablePlugins(
 	projectPath?: string,
@@ -282,6 +347,9 @@ export async function getAvailablePlugins(
 		// Try to get plugin info from local marketplace cache (fallback)
 		const localMp = localMarketplaces.get(mpName);
 		const localPlugin = localMp?.plugins.find((p) => p.name === pluginName);
+		const movedTo = localPlugin
+			? undefined
+			: findPluginInOtherMarketplace(pluginName, mpName, localMarketplaces);
 
 		const latestVersion = localPlugin?.version || installedVersion || "unknown";
 		const description = localPlugin?.description || "Installed plugin";
@@ -301,10 +369,12 @@ export async function getAvailablePlugins(
 			installedVersion: installedVersion,
 			hasUpdate,
 			isOrphaned: true,
+			movedTo,
 			...scopeStatus,
 		});
 	}
 
+	await annotateContentDrift(plugins, "project", projectPath);
 	return plugins;
 }
 
@@ -474,6 +544,9 @@ export async function getGlobalAvailablePlugins(): Promise<PluginInfo[]> {
 		// Try to get plugin info from local marketplace cache (fallback)
 		const localMp = localMarketplaces.get(mpName);
 		const localPlugin = localMp?.plugins.find((p) => p.name === pluginName);
+		const movedTo = localPlugin
+			? undefined
+			: findPluginInOtherMarketplace(pluginName, mpName, localMarketplaces);
 
 		const latestVersion = localPlugin?.version || installedVersion || "unknown";
 		const description = localPlugin?.description || "Installed plugin";
@@ -494,14 +567,83 @@ export async function getGlobalAvailablePlugins(): Promise<PluginInfo[]> {
 			installedVersion: installedVersion,
 			hasUpdate,
 			isOrphaned: true,
+			movedTo,
 		});
 	}
 
+	await annotateContentDrift(plugins, "user");
 	return plugins;
 }
 
+/**
+ * Find another configured marketplace that still publishes this plugin name.
+ *
+ * Answers "did it disappear, or did it move?" for an orphaned plugin, so the
+ * UI can offer migration rather than only deletion.
+ */
+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;
+}
+
+/**
+ * Flag plugins whose files moved without their version moving.
+ *
+ * Runs after the plugin list is assembled so every code path that builds a
+ * PluginInfo gets the same treatment. Only plugins that already look "up to
+ * date" are worth checking — anything with a pending version bump will be
+ * reinstalled by that update anyway.
+ *
+ * Best-effort throughout: a plugin whose drift cannot be determined is left
+ * exactly as it is today.
+ */
+async function annotateContentDrift(
+	plugins: PluginInfo[],
+	scope: "user" | "project" | "local",
+	projectPath?: string,
+): Promise<void> {
+	let registry: InstalledPluginsRegistry;
+	try {
+		registry = await readInstalledPluginsRegistry();
+	} catch {
+		return;
+	}
+
+	await Promise.all(
+		plugins.map(async (plugin) => {
+			if (plugin.hasUpdate || plugin.isOrphaned) return;
+			if (!plugin.installedVersion || !plugin.version) return;
+			if (compareVersions(plugin.version, plugin.installedVersion) !== 0) return;
+
+			const entry = pickRegistryEntry(
+				registry.plugins[plugin.id],
+				scope,
+				projectPath,
+			);
+			if (!entry?.gitCommitSha) return;
+
+			try {
+				plugin.contentStale = await hasContentDrift({
+					marketplace: plugin.marketplace,
+					pluginName: plugin.name,
+					installedSha: entry.gitCommitSha,
+				});
+			} catch {
+				/* leave unflagged */
+			}
+		}),
+	);
+}
+
 // Simple version comparison (returns 1 if a > b, -1 if a < b, 0 if equal)
-function compareVersions(
+export function compareVersions(
 	a: string | null | undefined,
 	b: string | null | undefined,
 ): number {