claudeup 4.40.0 → 4.41.0

package/package.json

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

package/src/__tests__/cache-provenance.test.ts

@@ -0,0 +1,84 @@
+/**
+ * REGRESSION: every installed plugin rendered "stale — reinstall" at once.
+ *
+ * `updateInstalledPluginsRegistry` re-copies a plugin's files out of the
+ * marketplace clone on every in-place update, but used to carry the pre-update
+ * `gitCommitSha` forward verbatim. The recorded commit therefore named whichever
+ * release the plugin was FIRST installed from — measured 2026-08-22 on one
+ * machine: dev claimed 4.3.0 against a sha holding 3.3.0, browser-use 1.4.1
+ * against 1.1.3 — and the subtree diff across those releases is always
+ * non-empty. Fixed in /dev:fix session dev-fix-20260822-125510-03db093b.
+ *
+ * Hermetic: exercises the provenance rule directly, with a real git repo. The
+ * registry write itself resolves through os.homedir() and is not sandboxable
+ * without new test infrastructure, so the decision is tested where it lives.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { resolveCacheProvenance } from "../services/claude-settings.js";
+
+let repo: string;
+let plain: string;
+
+const git = (args: string[]) =>
+	spawnSync("git", ["-c", "commit.gpgsign=false", ...args], {
+		cwd: repo,
+		encoding: "utf-8",
+	});
+
+beforeEach(async () => {
+	repo = await fs.mkdtemp(path.join(os.tmpdir(), "provenance-repo-"));
+	plain = await fs.mkdtemp(path.join(os.tmpdir(), "provenance-plain-"));
+	await fs.mkdir(path.join(repo, "plugins", "alpha"), { recursive: true });
+	await fs.writeFile(path.join(repo, "plugins", "alpha", "plugin.json"), "{}");
+	git(["init", "-q", "-b", "main"]);
+	git(["config", "user.email", "probe@example.invalid"]);
+	git(["config", "user.name", "probe"]);
+	git(["add", "-A"]);
+	git(["commit", "-q", "-m", "release"]);
+});
+
+afterEach(async () => {
+	await fs.rm(repo, { recursive: true, force: true });
+	await fs.rm(plain, { recursive: true, force: true });
+});
+
+describe("resolveCacheProvenance", () => {
+	test("stamps the source repo's HEAD when files were copied", async () => {
+		const head = git(["rev-parse", "HEAD"]).stdout.trim();
+		const stale = "0".repeat(40);
+
+		expect(
+			await resolveCacheProvenance(path.join(repo, "plugins", "alpha"), stale),
+		).toBe(head);
+	});
+
+	test("does NOT carry a stale sha forward after a successful copy", async () => {
+		// The bug in one line: the old code returned `stale` here, so the
+		// recorded commit fell further behind with every release.
+		const stale = "0".repeat(40);
+		expect(
+			await resolveCacheProvenance(path.join(repo, "plugins", "alpha"), stale),
+		).not.toBe(stale);
+	});
+
+	test("keeps the previous sha when nothing was copied", async () => {
+		// A failed copy leaves the cache untouched, so the old sha still
+		// describes it. Advancing it would claim the cache holds newer files
+		// than it does, which hides real drift.
+		const previous = "a".repeat(40);
+		expect(await resolveCacheProvenance(null, previous)).toBe(previous);
+		expect(await resolveCacheProvenance(null, undefined)).toBeUndefined();
+	});
+
+	test("records no sha for a source outside any git repo", async () => {
+		// Directory-type marketplaces have no commit to name. Inventing one
+		// would assert a provenance that is false; content-drift reads an
+		// absent sha as "cannot answer" and stays silent.
+		expect(await resolveCacheProvenance(plain, "b".repeat(40))).toBeUndefined();
+	});
+});

package/src/__tests__/content-drift.test.ts

@@ -14,6 +14,7 @@ import path from "node:path";
 import {
 	clearContentDriftCache,
 	hasContentDrift,
+	repoHeadSha,
 } from "../services/content-drift.js";
 
 let configDir: string;
@@ -34,6 +35,13 @@ const git = (args: string[]) =>
 
 const head = () => git(["rev-parse", "HEAD"]).stdout.trim();
 
+/** Rewrite a plugin's manifest version, mimicking a release. */
+const setVersion = (plugin: string, version: string) =>
+	fs.writeFile(
+		path.join(repo, "plugins", plugin, "plugin.json"),
+		JSON.stringify({ name: plugin, version }, null, 2),
+	);
+
 beforeEach(async () => {
 	prevConfigDir = process.env.CLAUDE_CONFIG_DIR;
 	configDir = await fs.mkdtemp(path.join(os.tmpdir(), "drift-"));
@@ -47,6 +55,8 @@ beforeEach(async () => {
 	await fs.mkdir(path.join(repo, "plugins", "beta"), { recursive: true });
 	await fs.writeFile(path.join(repo, "plugins", "alpha", "skills", "s.md"), "v1");
 	await fs.writeFile(path.join(repo, "plugins", "beta", "readme.md"), "v1");
+	await setVersion("alpha", "1.0.0");
+	await setVersion("beta", "1.0.0");
 
 	git(["init", "-q", "-b", "main"]);
 	git(["config", "user.email", "probe@example.invalid"]);
@@ -69,6 +79,7 @@ describe("hasContentDrift", () => {
 				marketplace: "probemp",
 				pluginName: "alpha",
 				installedSha: sha,
+				installedVersion: "1.0.0",
 			}),
 		).toBe(false);
 	});
@@ -88,6 +99,7 @@ describe("hasContentDrift", () => {
 				marketplace: "probemp",
 				pluginName: "alpha",
 				installedSha: sha,
+				installedVersion: "1.0.0",
 			}),
 		).toBe(true);
 	});
@@ -105,6 +117,7 @@ describe("hasContentDrift", () => {
 				marketplace: "probemp",
 				pluginName: "alpha",
 				installedSha: sha,
+				installedVersion: "1.0.0",
 			}),
 		).toBe(false);
 		expect(
@@ -112,6 +125,7 @@ describe("hasContentDrift", () => {
 				marketplace: "probemp",
 				pluginName: "beta",
 				installedSha: sha,
+				installedVersion: "1.0.0",
 			}),
 		).toBe(true);
 	});
@@ -129,6 +143,7 @@ describe("hasContentDrift", () => {
 				marketplace: "probemp",
 				pluginName: "alpha",
 				installedSha: sha,
+				installedVersion: "1.0.0",
 			}),
 		).toBe(true);
 	});
@@ -141,6 +156,7 @@ describe("hasContentDrift", () => {
 				marketplace: "probemp",
 				pluginName: "alpha",
 				installedSha: undefined,
+				installedVersion: "1.0.0",
 			}),
 		).toBe(false);
 		expect(
@@ -148,6 +164,7 @@ describe("hasContentDrift", () => {
 				marketplace: "probemp",
 				pluginName: "alpha",
 				installedSha: "0".repeat(40),
+				installedVersion: "1.0.0",
 			}),
 		).toBe(false);
 		expect(
@@ -155,7 +172,118 @@ describe("hasContentDrift", () => {
 				marketplace: "does-not-exist",
 				pluginName: "alpha",
 				installedSha: head(),
+				installedVersion: "1.0.0",
+			}),
+		).toBe(false);
+	});
+
+	// REGRESSION: every installed plugin rendered "stale — reinstall" because
+	// updateInstalledPluginsRegistry bumped `version` while carrying the
+	// pre-update `gitCommitSha` forward. The sha then named a commit several
+	// releases old, so the subtree diff was non-empty for essentially every
+	// plugin. Fixed in /dev:fix session dev-fix-20260822-125510-03db093b.
+	test("a sha recorded against a DIFFERENT version cannot answer the question", async () => {
+		const oldSha = head();
+
+		// Ship 2.0.0 — the plugin genuinely changed, as a release does.
+		await fs.writeFile(
+			path.join(repo, "plugins", "alpha", "skills", "s.md"),
+			"v2 content",
+		);
+		await setVersion("alpha", "2.0.0");
+		git(["add", "-A"]);
+		git(["commit", "-q", "-m", "release 2.0.0"]);
+
+		// 2.0.0 is installed, but the registry still carries the 1.0.0 sha.
+		// The subtree diff between them is non-empty, and says nothing about
+		// whether the installed 2.0.0 files match the marketplace's 2.0.0.
+		expect(
+			await hasContentDrift({
+				marketplace: "probemp",
+				pluginName: "alpha",
+				installedSha: oldSha,
+				installedVersion: "2.0.0",
 			}),
 		).toBe(false);
 	});
+
+	test("a manifest that cannot be read at that sha reports no drift", async () => {
+		// Provenance unverifiable — the module's policy is silence, not a nag.
+		await fs.rm(path.join(repo, "plugins", "beta", "plugin.json"));
+		git(["add", "-A"]);
+		git(["commit", "-q", "-m", "beta loses its manifest"]);
+		const sha = head();
+
+		await fs.writeFile(path.join(repo, "plugins", "beta", "readme.md"), "v2");
+		git(["add", "-A"]);
+		git(["commit", "-q", "-m", "beta content changes"]);
+
+		expect(
+			await hasContentDrift({
+				marketplace: "probemp",
+				pluginName: "beta",
+				installedSha: sha,
+				installedVersion: "1.0.0",
+			}),
+		).toBe(false);
+	});
+
+	test("reads a manifest at .claude-plugin/plugin.json too", async () => {
+		// magus lays plugins out as plugins/<name>/plugin.json, but Claude Code's
+		// documented location is .claude-plugin/plugin.json. Both must resolve or
+		// the guard silences drift detection for half the ecosystem.
+		await fs.mkdir(path.join(repo, "plugins", "beta", ".claude-plugin"), {
+			recursive: true,
+		});
+		await fs.rm(path.join(repo, "plugins", "beta", "plugin.json"));
+		await fs.writeFile(
+			path.join(repo, "plugins", "beta", ".claude-plugin", "plugin.json"),
+			JSON.stringify({ name: "beta", version: "1.0.0" }),
+		);
+		git(["add", "-A"]);
+		git(["commit", "-q", "-m", "beta uses .claude-plugin"]);
+		const sha = head();
+
+		await fs.writeFile(path.join(repo, "plugins", "beta", "readme.md"), "v2");
+		git(["add", "-A"]);
+		git(["commit", "-q", "-m", "republish 1.0.0"]);
+
+		expect(
+			await hasContentDrift({
+				marketplace: "probemp",
+				pluginName: "beta",
+				installedSha: sha,
+				installedVersion: "1.0.0",
+			}),
+		).toBe(true);
+	});
+});
+
+describe("repoHeadSha", () => {
+	// The other half of the same bug: nothing in claudeup ever recorded a fresh
+	// sha, so the registry could only ever go stale. This is what
+	// updateInstalledPluginsRegistry now calls to stamp real provenance onto the
+	// files it just copied out of the marketplace clone.
+	test("resolves HEAD from a path inside the repo", async () => {
+		const sha = head();
+		expect(await repoHeadSha(path.join(repo, "plugins", "alpha"))).toBe(sha);
+		expect(await repoHeadSha(repo)).toBe(sha);
+	});
+
+	test("returns undefined for a directory that is not in a git repo", async () => {
+		// Directory-type marketplaces have no commit to name. Recording a sha
+		// from some unrelated clone would assert a provenance that is false.
+		const plain = await fs.mkdtemp(path.join(os.tmpdir(), "nogit-"));
+		try {
+			expect(await repoHeadSha(plain)).toBeUndefined();
+		} finally {
+			await fs.rm(plain, { recursive: true, force: true });
+		}
+	});
+
+	test("returns undefined for a path that does not exist", async () => {
+		expect(
+			await repoHeadSha(path.join(configDir, "no", "such", "dir")),
+		).toBeUndefined();
+	});
 });

package/src/__tests__/marketplaces.test.ts

@@ -38,3 +38,87 @@ describe("marketplaces", () => {
 		expect(names).not.toContain("superpowers");
 	});
 });
+
+/**
+ * The community marketplaces added alongside the Magus channels.
+ *
+ * `name` is not cosmetic: plugin ids are built as `${plugin.name}@${mpName}`
+ * (plugin-manager.ts), so it MUST equal the upstream
+ * .claude-plugin/marketplace.json "name" field. A mismatch fails at install
+ * time with "not found in marketplace", nowhere near the typo that caused it.
+ *
+ * Verify against upstream with:
+ *   gh api repos/<repo>/contents/.claude-plugin/marketplace.json \
+ *     -H "Accept: application/vnd.github.raw" | jq -r '.name'
+ */
+const COMMUNITY_MARKETPLACES: ReadonlyArray<[name: string, repo: string]> = [
+	["mattpocock", "mattpocock/skills"],
+	["ecc", "affaan-m/everything-claude-code"],
+	["ponytail", "DietrichGebert/ponytail"],
+	["addy-agent-skills", "addyosmani/agent-skills"],
+	["humanizer", "blader/humanizer"],
+	["opendesign", "manalkaff/opendesign"],
+];
+
+describe("community marketplaces", () => {
+	it.each(COMMUNITY_MARKETPLACES)(
+		"%s points at the repo whose manifest declares that name",
+		(name, repo) => {
+			const mp = defaultMarketplaces.find((m) => m.name === name);
+			expect(mp).toBeDefined();
+			expect(mp?.source.repo).toBe(repo);
+		},
+	);
+
+	it.each(COMMUNITY_MARKETPLACES)(
+		"%s is visible by default via the always-show gate",
+		(name) => {
+			const mp = defaultMarketplaces.find((m) => m.name === name);
+			// plugin-manager's gate: configured || official || featured || owned.
+			// Without one of these the entry is only a name-to-repo mapping and
+			// never appears, which is a silent no-op rather than a failure.
+			expect(mp?.official || mp?.featured || mp?.owned).toBe(true);
+		},
+	);
+
+	it.each(COMMUNITY_MARKETPLACES)(
+		"%s claims neither Anthropic nor MadAppGang ownership",
+		(name) => {
+			const mp = defaultMarketplaces.find((m) => m.name === name);
+			// `official` badges it as Anthropic-managed; `owned` sorts it above
+			// everything as a MadAppGang channel. Both would be a false claim.
+			expect(mp?.official).toBeUndefined();
+			expect(mp?.owned).toBeUndefined();
+		},
+	);
+
+	it("introduces no duplicate marketplace name or repo", () => {
+		const names = defaultMarketplaces.map((m) => m.name);
+		const repos = defaultMarketplaces.map((m) => m.source.repo.toLowerCase());
+
+		expect(new Set(names).size).toBe(names.length);
+		expect(new Set(repos).size).toBe(repos.length);
+	});
+
+	it("surfaces every community marketplace through getAllMarketplaces", () => {
+		const names = getAllMarketplaces().map((mp) => mp.name);
+
+		for (const [name] of COMMUNITY_MARKETPLACES) {
+			expect(names).toContain(name);
+		}
+	});
+
+	it("keeps the Magus channels sorted above the community ones", () => {
+		const order = getAllMarketplaces().map((mp) => mp.name);
+		const lastMagus = Math.max(
+			order.indexOf("magus"),
+			order.indexOf("magus-marketing"),
+			order.indexOf("magus-alpha"),
+		);
+		const firstCommunity = Math.min(
+			...COMMUNITY_MARKETPLACES.map(([name]) => order.indexOf(name)),
+		);
+
+		expect(lastMagus).toBeLessThan(firstCommunity);
+	});
+});

package/src/data/marketplaces.ts

@@ -87,6 +87,80 @@ export const defaultMarketplaces: Marketplace[] = [
 		description: "Curated Claude Code plugins for skills and workflows",
 		featured: true,
 	},
+	// Community marketplaces. Each `name` MUST equal the upstream
+	// .claude-plugin/marketplace.json "name" field — plugin ids are built as
+	// `${plugin.name}@${marketplaceName}`, so a mismatch here breaks install
+	// with a "not found in marketplace" error rather than anything obvious.
+	//
+	// All carry `featured` because that is the only flag that makes a
+	// third-party marketplace visible: the gate in plugin-manager is
+	// `configured || official || featured || owned`, and an unflagged entry is
+	// just a name→repo mapping for auto-recovery. `official` means Anthropic
+	// and `owned` means MadAppGang, so neither applies.
+	{
+		name: "mattpocock",
+		displayName: "Matt Pocock",
+		source: {
+			source: "github",
+			repo: "mattpocock/skills",
+		},
+		description:
+			"Agent skills for real engineering — grilling, spec and ticket flows, TDD, code review, domain modelling",
+		featured: true,
+	},
+	{
+		name: "ecc",
+		displayName: "Everything Claude Code",
+		source: {
+			source: "github",
+			repo: "affaan-m/everything-claude-code",
+		},
+		description:
+			"Operator layer for agent harnesses — 68 agents, 286 skills, and command shims",
+		featured: true,
+	},
+	{
+		name: "ponytail",
+		displayName: "Ponytail",
+		source: {
+			source: "github",
+			repo: "DietrichGebert/ponytail",
+		},
+		description:
+			"Pushes the agent toward the smallest solution that works — YAGNI, and the standard library before custom code",
+		featured: true,
+	},
+	{
+		name: "addy-agent-skills",
+		displayName: "Addy Osmani Skills",
+		source: {
+			source: "github",
+			repo: "addyosmani/agent-skills",
+		},
+		description: "Production-grade engineering skills for AI coding agents",
+		featured: true,
+	},
+	{
+		name: "humanizer",
+		displayName: "Humanizer",
+		source: {
+			source: "github",
+			repo: "blader/humanizer",
+		},
+		description: "Removes signs of AI-generated writing from text",
+		featured: true,
+	},
+	{
+		name: "opendesign",
+		displayName: "OpenDesign",
+		source: {
+			source: "github",
+			repo: "manalkaff/opendesign",
+		},
+		description:
+			"Designs and redesigns frontend UI and marketing graphics, routing to specialist skills per artifact type",
+		featured: true,
+	},
 	{
 		name: "claude-code-plugins",
 		displayName: "Anthropic Deprecated",

package/src/services/claude-settings.ts

@@ -13,6 +13,7 @@ import type {
 } from "../types/index.js";
 import { parsePluginId } from "../utils/string-utils.js";
 import { inheritablePaths } from "./git-worktree.js";
+import { repoHeadSha } from "./content-drift.js";
 
 const CLAUDE_DIR = ".claude";
 const SETTINGS_FILE = "settings.json";
@@ -1509,19 +1510,23 @@ async function getPluginSourcePath(
 /**
  * Copy plugin files from source to cache
  * This ensures the cache is populated with the latest plugin version
+ *
+ * Returns the directory the files were copied FROM, or null if nothing was
+ * copied. The caller needs the source path, not just a success flag: that path
+ * is what identifies the commit the cached files came from.
  */
 async function copyPluginToCache(
 	pluginId: string,
 	version: string,
 	marketplace: string,
-): Promise<boolean> {
+): Promise<string | null> {
 	const { pluginName } = parsePluginId(pluginId) || {
 		pluginName: pluginId.split("@")[0],
 	};
 
 	const sourcePath = await getPluginSourcePath(pluginName, marketplace);
 	if (!sourcePath) {
-		return false;
+		return null;
 	}
 
 	const cachePath = getPluginCachePath(pluginId, version, marketplace);
@@ -1538,16 +1543,42 @@ async function copyPluginToCache(
 			errorOnExist: false,
 		});
 
-		return true;
+		return sourcePath;
 	} catch (error) {
 		console.warn(
 			`Failed to copy plugin ${pluginId} to cache:`,
 			error instanceof Error ? error.message : "Unknown error",
 		);
-		return false;
+		return null;
 	}
 }
 
+/**
+ * The commit a cache copy should be stamped with.
+ *
+ * `gitCommitSha` must describe the files sitting in the cache RIGHT NOW, which
+ * is the single thing content-drift detection reads it for. Two rules:
+ *
+ * - Files were copied → the source repo's HEAD is their provenance. Undefined
+ *   is a legitimate answer here: a directory-type marketplace has no commit,
+ *   and content-drift stays silent rather than guessing.
+ * - Nothing was copied → the cache is untouched, so whatever sha already
+ *   described it still does. Advancing it would claim the cache holds newer
+ *   files than it does, hiding real drift.
+ *
+ * The bug this replaces did neither: it preserved the pre-update sha even when
+ * fresh files HAD been copied, so the recorded commit drifted further behind
+ * with every release and drift detection reported a false positive on every
+ * plugin at once.
+ */
+export async function resolveCacheProvenance(
+	copiedFrom: string | null,
+	previousSha: string | undefined,
+): Promise<string | undefined> {
+	if (!copiedFrom) return previousSha;
+	return await repoHeadSha(copiedFrom);
+}
+
 /**
  * Read installed_plugins.json registry
  */
@@ -1632,7 +1663,7 @@ export async function updateInstalledPluginsRegistry(
 
 		// Copy plugin files from source to cache
 		// This ensures the cache has the latest plugin version
-		await copyPluginToCache(pluginId, version, marketplace);
+		const copiedFrom = await copyPluginToCache(pluginId, version, marketplace);
 
 		const installPath = getPluginCachePath(pluginId, version, marketplace);
 		const now = new Date().toISOString();
@@ -1659,10 +1690,12 @@ export async function updateInstalledPluginsRegistry(
 					? registry.plugins[pluginId][existingIndex].installedAt
 					: now,
 			lastUpdated: now,
-			gitCommitSha:
+			gitCommitSha: await resolveCacheProvenance(
+				copiedFrom,
 				existingIndex >= 0
 					? registry.plugins[pluginId][existingIndex].gitCommitSha
 					: undefined,
+			),
 		};
 
 		if (existingIndex >= 0) {

package/src/services/content-drift.ts

@@ -67,12 +67,33 @@ function git(cwd: string, args: string[]): Promise<{ code: number; out: string }
 	});
 }
 
+/**
+ * HEAD of the git repo containing `dir`, or undefined when there is none.
+ *
+ * This is what stamps provenance onto a cache copy: `copyPluginToCache` reads
+ * the plugin's files out of the marketplace clone, so that clone's HEAD is the
+ * commit those files came from. Undefined is a real answer — a directory-type
+ * marketplace has no commit to name, and inventing one would assert a
+ * provenance that is false.
+ */
+export async function repoHeadSha(dir: string): Promise<string | undefined> {
+	const r = await git(dir, ["rev-parse", "HEAD"]);
+	if (r.code !== 0) return undefined;
+	return /^[0-9a-f]{40}$/.test(r.out) ? r.out : undefined;
+}
+
 export interface DriftQuery {
 	marketplace: string;
 	/** Plugin name without the @marketplace suffix. */
 	pluginName: string;
 	/** `gitCommitSha` from the installed_plugins.json entry. */
 	installedSha: string | undefined;
+	/**
+	 * Version currently installed. Required, not optional: the sha alone cannot
+	 * be trusted, and a caller that omitted this would silently get the old
+	 * always-drifted behaviour back.
+	 */
+	installedVersion: string | undefined;
 	/**
 	 * Path of the plugin inside the marketplace repo, from the catalog `source`
 	 * field (e.g. "./plugins/dev"). Defaults to `plugins/<name>`.
@@ -80,19 +101,52 @@ export interface DriftQuery {
 	sourcePath?: string;
 }
 
+/** Strip a leading "v" so "v1.2.3" and "1.2.3" compare equal. */
+const normalize = (v: string) => v.trim().replace(/^v/, "");
+
+/**
+ * The version a plugin's manifest declared at a given commit.
+ *
+ * Both layouts are tried because both are real: magus lays plugins out as
+ * `plugins/<name>/plugin.json`, while Claude Code documents
+ * `.claude-plugin/plugin.json`. Reading only one would silence drift detection
+ * for every plugin using the other.
+ */
+async function versionAtSha(
+	repo: string,
+	sha: string,
+	rel: string,
+): Promise<string | undefined> {
+	for (const manifest of [
+		`${rel}/plugin.json`,
+		`${rel}/.claude-plugin/plugin.json`,
+	]) {
+		const r = await git(repo, ["show", `${sha}:${manifest}`]);
+		if (r.code !== 0 || !r.out) continue;
+		try {
+			const v = JSON.parse(r.out)?.version;
+			if (typeof v === "string" && v) return v;
+		} catch {
+			// Unparseable manifest is the same as no manifest: unverifiable.
+		}
+	}
+	return undefined;
+}
+
 /**
  * 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.
+ * sha, no clone, git unavailable, the recorded commit is absent locally
+ * (force-push, shallow clone), or that commit declares a DIFFERENT version than
+ * the one installed. 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 key = `${q.marketplace}\0${q.pluginName}\0${q.installedSha}\0${q.installedVersion}`;
 	const hit = cache.get(key);
 	if (hit !== undefined) return hit;
 
@@ -106,6 +160,29 @@ export async function hasContentDrift(q: DriftQuery): Promise<boolean> {
 		return false;
 	}
 
+	// The recorded sha must describe the version actually installed, or the diff
+	// answers a different question than the one asked.
+	//
+	// This is the whole reason the badge fired on every plugin at once:
+	// `updateInstalledPluginsRegistry` bumps `version` on an in-place update but
+	// carries the pre-update `gitCommitSha` forward, so the sha names whichever
+	// commit the plugin was FIRST installed from. Measured 2026-08-22 on one
+	// machine: dev recorded 4.3.0 against a sha holding 3.3.0, browser-use 1.4.1
+	// against 1.1.3. Diffing across those releases is trivially non-empty, so
+	// every plugin rendered "stale — reinstall" while its cached files were in
+	// fact byte-identical to the marketplace.
+	const shaVersion = q.installedVersion
+		? await versionAtSha(repo, q.installedSha, rel)
+		: undefined;
+	if (
+		!q.installedVersion ||
+		!shaVersion ||
+		normalize(shaVersion) !== normalize(q.installedVersion)
+	) {
+		cache.set(key, false);
+		return false;
+	}
+
 	// Exit 0 = no difference, 1 = differs, anything else = could not tell.
 	const diff = await git(repo, [
 		"diff",

package/src/services/conventions-manager.ts

@@ -14,6 +14,7 @@
  */
 
 import { readFile, writeFile, stat, rename, unlink, open } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { dirname, basename, join, resolve } from 'node:path';
 import { homedir } from 'node:os';
@@ -692,7 +693,11 @@ export async function resolveGlobalGitignorePath(): Promise<string | null> {
 export async function resolvePluginConventions(
   pluginPath: string,
 ): Promise<PluginConventions | null> {
-  const manifestPath = join(pluginPath, 'plugin.json');
+  // `.claude-plugin/plugin.json` is the location Claude Code reads; a root-level
+  // manifest is inert to the runtime but still worth reading for a third-party plugin
+  // whose author put it there.
+  const nested = join(pluginPath, '.claude-plugin', 'plugin.json');
+  const manifestPath = existsSync(nested) ? nested : join(pluginPath, 'plugin.json');
 
   try {
     const raw = await readFile(manifestPath, 'utf-8');

package/src/services/plugin-manager.ts

@@ -722,6 +722,7 @@ async function annotateContentDrift(
 					marketplace: plugin.marketplace,
 					pluginName: plugin.name,
 					installedSha: entry.gitCommitSha,
+					installedVersion: plugin.installedVersion,
 				});
 			} catch {
 				/* leave unflagged */

package/src/services/plugin-requires.ts

@@ -156,15 +156,19 @@ export function parsePluginRequires(pluginJson: unknown): PluginRequires {
 export async function readPluginRequires(
 	pluginPath: string,
 ): Promise<PluginRequires> {
-	const manifestPath = path.join(pluginPath, "plugin.json");
+	// `.claude-plugin/plugin.json` FIRST — that is the only location Claude Code's
+	// runtime loader reads, and the only one its documentation describes. The root
+	// fallback stays for third-party plugins whose authors put it there; such a manifest
+	// is inert as far as Claude Code is concerned, but claudeup can still read metadata
+	// out of it rather than reporting nothing.
+	const manifestPath = path.join(pluginPath, ".claude-plugin", "plugin.json");
 	try {
 		if (await fs.pathExists(manifestPath)) {
 			return parsePluginRequires(await fs.readJson(manifestPath));
 		}
-		// Some plugins nest the manifest under .claude-plugin/plugin.json.
-		const nested = path.join(pluginPath, ".claude-plugin", "plugin.json");
-		if (await fs.pathExists(nested)) {
-			return parsePluginRequires(await fs.readJson(nested));
+		const rootLevel = path.join(pluginPath, "plugin.json");
+		if (await fs.pathExists(rootLevel)) {
+			return parsePluginRequires(await fs.readJson(rootLevel));
 		}
 	} catch {
 		// Unreadable/malformed — treat as no requirements.