claudeup 6.5.1 → 6.6.0

package/src/services/marketplace-refresh.ts

@@ -173,9 +173,27 @@ function tap(fn: (() => void) | undefined): void {
  *   one unreachable marketplace must not block launching Claude. Pulls run
  *   concurrently, so a slow one doesn't serialize the rest onto the launch path.
  */
+/**
+ * Select and report, writing nothing.
+ *
+ * Everything above the pull loop is a read — the marketplace registry and each
+ * entry's `autoUpdate` flag — so a read-only caller can have the full selection
+ * verdict for free. `--dry-run` and `--check` promise to write nothing and
+ * therefore cannot pull, but they must still be able to say "your magus clone
+ * has autoUpdate off, so its catalog will never advance". Gating the whole call
+ * off silently dropped that warning, which is the same "no signal reads as no
+ * problem" failure the flag exists to prevent.
+ */
+export async function reportRegisteredMarketplaces(
+	skip: Iterable<string> = [],
+): Promise<RefreshResult> {
+	return refreshRegisteredMarketplaces(skip, {}, { reportOnly: true });
+}
+
 export async function refreshRegisteredMarketplaces(
 	skip: Iterable<string> = [],
 	progress: RefreshProgress = {},
+	options: { reportOnly?: boolean } = {},
 ): Promise<RefreshResult> {
 	const refreshed: string[] = [];
 	const failed: string[] = [];
@@ -200,6 +218,18 @@ export async function refreshRegisteredMarketplaces(
 		eligible.push(name);
 	}
 
+	// A read-only caller stops here, with the selection verdict intact and not
+	// one clone touched. `eligible` becomes `skipped`: nothing was refreshed, so
+	// claiming otherwise would be the false "all current" this module guards.
+	if (options.reportOnly) {
+		return {
+			refreshed: [],
+			failed: [],
+			skipped: [...skipped, ...eligible],
+			autoUpdateDisabled,
+		};
+	}
+
 	// Fast-forward every eligible clone in parallel so a slow one doesn't
 	// serialize the rest onto the launch path. fastForwardCloneIfPresent never
 	// throws, so the batch always resolves.

package/src/services/plugin-manager.ts

@@ -72,6 +72,19 @@ export interface PluginInfo {
 	marketplaceDisplay: string;
 	enabled: boolean;
 	installedVersion?: string;
+	/**
+	 * Provably behind the catalog, on ONE version pair.
+	 *
+	 * @deprecated Derive plugin state from `classifyPlugin` (update-plan.ts),
+	 * which answers per scope and distinguishes "cannot tell" from "current".
+	 * Nothing in `src/` reads this any more — the content-drift gate was its
+	 * last reader, and it now asks the version pair directly. It is still
+	 * computed because `blackbox-parity.test.ts` reproduces the pre-classifier
+	 * rule from it, which is what proves the fixture discriminates.
+	 *
+	 * Its sibling `updateUnknown` was written in six places and read in none,
+	 * and is gone.
+	 */
 	hasUpdate?: boolean;
 	// Per-scope installation status
 	userScope?: ScopeStatus;
@@ -120,7 +133,7 @@ export interface PluginInfo {
 	movedTo?: string;
 	/**
 	 * Set when this plugin's installed version changed since claudeup last
-	 * rendered it — including updates made by Claude Code or the prerunner
+	 * rendered it — including updates made by Claude Code or a direct CLI call
 	 * rather than by claudeup itself. Drives the "updated" badge.
 	 */
 	recentlyUpdatedFrom?: string;
@@ -160,7 +173,7 @@ export interface PluginInfo {
  *
  * This is a broken state, not a healthy one: Claude Code will not load the
  * plugin, and because the update check is `installedVersion && compare(...)`,
- * it is also invisible to both the update list and the prerunner's auto-update.
+ * it is also invisible to every update path.
  * It previously rendered identically to a working install.
  *
  * `isOrphaned` is a different failure — installed, but no longer offered by any
@@ -196,7 +209,38 @@ export function isEnabledButNotInstalled(plugin: PluginInfo): boolean {
  * record exactly that — which is why this tests presence, not `isKnownVersion`.
  */
 export function isInstalledInScope(scope: ScopeStatus | undefined): boolean {
-	return !!scope?.enabled && !!scope.version;
+	// Presence of files, NOT permission to load them. `enabled` was in this
+	// test until it was measured: a plugin with a real registry row that the
+	// user had simply switched off reported "not installed", so the row offered
+	// to install what was already on disk. Installation is a registry fact;
+	// enablement is a separate one, and `isEnabledButNotInstalled` is where the
+	// broken combination of the two is named.
+	return !!scope?.version;
+}
+
+/**
+ * One scope's status, from the two facts that define it.
+ *
+ * Exported and taken as arguments so this is testable and has exactly one
+ * implementation. It previously lived inline in `getAvailablePlugins` and its
+ * global twin — two copies, and both keyed existence off the settings flag:
+ *
+ *   enabledPlugins[id] !== undefined ? {...} : undefined
+ *
+ * so a plugin with a registry row but no settings key produced NO scope at all
+ * and rendered exactly like one that was never installed. Existence is now
+ * "either fact is present", and `enabled` defaults to false rather than
+ * deciding whether the scope exists.
+ */
+export function buildScopeStatus(
+	enabledPlugins: Record<string, boolean>,
+	installedVersions: Record<string, string>,
+	pluginId: string,
+): ScopeStatus | undefined {
+	const enabled = enabledPlugins[pluginId];
+	const version = installedVersions[pluginId];
+	if (enabled === undefined && version === undefined) return undefined;
+	return { enabled: enabled === true, version };
 }
 
 /**
@@ -208,16 +252,31 @@ export function isInstalledInScope(scope: ScopeStatus | undefined): boolean {
  * `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).
+ *
+ * `behind` is the answer to "is this scope provably behind?", and it comes from
+ * the plugin classifier (`scopeIsBehind` in update-plan.ts), never from a
+ * comparison made here. This used to take the catalog version and compare raw
+ * strings — a fourth "is it behind?" rule, which offered `update` for a scope
+ * AHEAD of the catalog or one whose version cannot be ordered at all, while the
+ * row beside it said something else.
  */
 export function resolveScopeAction(
 	scope: ScopeStatus | undefined,
-	latestVersion: string,
+	behind: boolean,
 ): "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";
+	// `enabled` is deliberately part of THIS decision even though it is no longer
+	// part of `isInstalledInScope`. The two ask different questions:
+	// "is it on disk" (installation) versus "what should this key do next".
+	//
+	// Installed-but-disabled must NOT resolve to uninstall. The scope key runs
+	// `cliUninstallPlugin` with no confirmation, so that combination would delete
+	// a plugin the user had merely switched off — with the row beside it showing
+	// no scope square, which reads as "not installed" and invites the press.
+	// `install` re-installs and re-enables, which is what the key meant before
+	// installation and enablement were separated, and is the only non-destructive
+	// answer here.
+	if (!isInstalledInScope(scope) || !scope?.enabled) return "install";
+	return behind ? "update" : "uninstall";
 }
 
 export async function getAvailablePlugins(
@@ -241,28 +300,25 @@ export async function getAvailablePlugins(
 	const seenPluginIds = new Set<string>();
 
 	// Helper to build scope status
-	const buildScopeStatus = (pluginId: string) => ({
-		userScope:
-			userEnabledPlugins[pluginId] !== undefined
-				? {
-						enabled: userEnabledPlugins[pluginId],
-						version: userInstalledVersions[pluginId],
-					}
-				: undefined,
-		projectScope:
-			projectEnabledPlugins[pluginId] !== undefined
-				? {
-						enabled: projectEnabledPlugins[pluginId],
-						version: projectInstalledVersions[pluginId],
-					}
-				: undefined,
-		localScope:
-			localEnabledPlugins[pluginId] !== undefined
-				? {
-						enabled: localEnabledPlugins[pluginId],
-						version: localInstalledVersions[pluginId],
-					}
-				: undefined,
+	// One implementation, shared with the global view and unit-tested. Both
+	// copies used to key scope existence off the settings flag, so an installed
+	// plugin with no settings key produced no scope at all.
+	const scopeStatusFor = (pluginId: string) => ({
+		userScope: buildScopeStatus(
+			userEnabledPlugins,
+			userInstalledVersions,
+			pluginId,
+		),
+		projectScope: buildScopeStatus(
+			projectEnabledPlugins,
+			projectInstalledVersions,
+			pluginId,
+		),
+		localScope: buildScopeStatus(
+			localEnabledPlugins,
+			localInstalledVersions,
+			pluginId,
+		),
 	});
 
 	// Get all marketplace names (configured + official/featured defaults)
@@ -325,7 +381,7 @@ export async function getAvailablePlugins(
 			const pluginId = `${plugin.name}@${mpName}`;
 			const installedVersion = installedVersions[pluginId];
 			const isEnabled = enabledPlugins[pluginId] === true;
-			const scopeStatus = buildScopeStatus(pluginId);
+			const scopeStatus = scopeStatusFor(pluginId);
 
 			seenPluginIds.add(pluginId);
 			plugins.push({
@@ -337,10 +393,7 @@ export async function getAvailablePlugins(
 				marketplaceDisplay: marketplace.displayName,
 				enabled: isEnabled,
 				installedVersion: installedVersion,
-				hasUpdate:
-					installedVersion && plugin.version
-						? compareVersions(plugin.version, installedVersion) > 0
-						: false,
+				hasUpdate: isBehind(plugin.version, installedVersion) === true,
 				catalogSource: resolution.source,
 				updateCheckFailed: unverified,
 				updateCheckFailure: resolution.failure,
@@ -367,7 +420,7 @@ export async function getAvailablePlugins(
 
 			const installedVersion = installedVersions[pluginId];
 			const isEnabled = enabledPlugins[pluginId] === true;
-			const scopeStatus = buildScopeStatus(pluginId);
+			const scopeStatus = scopeStatusFor(pluginId);
 
 			seenPluginIds.add(pluginId);
 			plugins.push({
@@ -379,9 +432,7 @@ export async function getAvailablePlugins(
 				marketplaceDisplay: localMp.name || formatMarketplaceName(mpName),
 				enabled: isEnabled,
 				installedVersion: installedVersion,
-				hasUpdate: installedVersion
-					? compareVersions(localPlugin.version, installedVersion) > 0
-					: false,
+				hasUpdate: isBehind(localPlugin.version, installedVersion) === true,
 				...scopeStatus,
 				category: localPlugin.category,
 				author: localPlugin.author,
@@ -411,7 +462,7 @@ export async function getAvailablePlugins(
 		const { pluginName, marketplace: mpName } = parsed;
 		const installedVersion = installedVersions[pluginId];
 		const isEnabled = enabledPlugins[pluginId] === true;
-		const scopeStatus = buildScopeStatus(pluginId);
+		const scopeStatus = scopeStatusFor(pluginId);
 
 		// Try to get plugin info from local marketplace cache (fallback)
 		const localMp = localMarketplaces.get(mpName);
@@ -422,10 +473,7 @@ export async function getAvailablePlugins(
 
 		const latestVersion = localPlugin?.version || installedVersion || "unknown";
 		const description = localPlugin?.description || "Installed plugin";
-		const hasUpdate =
-			installedVersion && localPlugin?.version
-				? compareVersions(localPlugin.version, installedVersion) > 0
-				: false;
+		const hasUpdate = isBehind(localPlugin?.version, installedVersion) === true;
 
 		plugins.push({
 			id: pluginId,
@@ -447,230 +495,6 @@ export async function getAvailablePlugins(
 	return plugins;
 }
 
-export async function getGlobalAvailablePlugins(): Promise<PluginInfo[]> {
-	const configuredMarketplaces = await getGlobalConfiguredMarketplaces();
-	const enabledPlugins = await getGlobalEnabledPlugins();
-	const installedVersions = await getGlobalInstalledPluginVersions();
-
-	// Fetch all scopes for per-scope status display
-	const userEnabledPlugins = await getGlobalEnabledPlugins();
-	const userInstalledVersions = await getGlobalInstalledPluginVersions();
-	// Also fetch project and local scope for complete status display
-	const projectEnabledPlugins = await getEnabledPlugins();
-	const projectInstalledVersions = await getInstalledPluginVersions();
-	const localEnabledPlugins = await getLocalEnabledPlugins();
-	const localInstalledVersions = await getLocalInstalledPluginVersions();
-
-	const plugins: PluginInfo[] = [];
-	const seenPluginIds = new Set<string>();
-
-	// Helper to build scope status (show all scopes)
-	const buildScopeStatus = (pluginId: string) => ({
-		userScope:
-			userEnabledPlugins[pluginId] !== undefined
-				? {
-						enabled: userEnabledPlugins[pluginId],
-						version: userInstalledVersions[pluginId],
-					}
-				: undefined,
-		projectScope:
-			projectEnabledPlugins[pluginId] !== undefined
-				? {
-						enabled: projectEnabledPlugins[pluginId],
-						version: projectInstalledVersions[pluginId],
-					}
-				: undefined,
-		localScope:
-			localEnabledPlugins[pluginId] !== undefined
-				? {
-						enabled: localEnabledPlugins[pluginId],
-						version: localInstalledVersions[pluginId],
-					}
-				: undefined,
-	});
-
-	// Get all marketplace names (configured + official/featured defaults)
-	// Always include official and featured marketplaces so users can browse them
-	const marketplaceNames = new Set<string>();
-	for (const mp of defaultMarketplaces) {
-		if (
-			configuredMarketplaces[mp.name] ||
-			mp.official ||
-			mp.featured ||
-			mp.owned
-		) {
-			marketplaceNames.add(mp.name);
-		}
-	}
-
-	// Fetch local marketplace caches up front so we can detect stale caches
-	let localMarketplaces = await getLocalMarketplaces();
-
-	// Resolve every marketplace concurrently. These are independent HTTP calls
-	// with a 10s timeout each; awaited in sequence, one unreachable marketplace
-	// added its full timeout to the "Loading..." the user stares at. Measured on
-	// six marketplaces with four unreachable: 44.9s sequential.
-	const resolutions = await Promise.all(
-		[...marketplaceNames].map(async (mpName) => {
-			const marketplace = defaultMarketplaces.find((m) => m.name === mpName);
-			if (!marketplace) return null;
-			return {
-				mpName,
-				marketplace,
-				resolution: await resolveMarketplacePlugins(
-					mpName,
-					marketplace.source.repo,
-					localMarketplaces,
-				),
-			};
-		}),
-	);
-
-	for (const entry of resolutions) {
-		if (!entry) continue;
-		const { mpName, marketplace, resolution } = entry;
-		const marketplacePlugins = resolution.plugins;
-
-		// Auto-sync local cache if remote has plugins the local cache doesn't
-		localMarketplaces = await autoSyncIfStale(
-			mpName,
-			marketplacePlugins.map((p) => p.name),
-			localMarketplaces,
-		);
-
-		// The catalog that answered was not the authoritative one, so every
-		// version compare below is a guess, not a check.
-		// `remote-git` counts as verified: it is upstream's own catalog file, read
-		// through a git remote ref rather than over HTTP. Only the pinned working
-		// tree (`local-clone`) is untrustworthy for versions.
-		const unverified = !isAuthoritative(resolution.source);
-
-		for (const plugin of marketplacePlugins) {
-			const pluginId = `${plugin.name}@${mpName}`;
-			const installedVersion = installedVersions[pluginId];
-			const isEnabled = enabledPlugins[pluginId] === true;
-			const scopeStatus = buildScopeStatus(pluginId);
-
-			seenPluginIds.add(pluginId);
-			plugins.push({
-				id: pluginId,
-				name: plugin.name,
-				version: plugin.version,
-				description: plugin.description,
-				marketplace: mpName,
-				marketplaceDisplay: marketplace.displayName,
-				enabled: isEnabled,
-				installedVersion: installedVersion,
-				hasUpdate:
-					installedVersion && plugin.version
-						? compareVersions(plugin.version, installedVersion) > 0
-						: false,
-				catalogSource: resolution.source,
-				updateCheckFailed: unverified,
-				updateCheckFailure: resolution.failure,
-				...scopeStatus,
-				category: plugin.category,
-				author: plugin.author,
-				homepage: plugin.homepage,
-				tags: plugin.tags,
-				releases: plugin.releases,
-				source: plugin.source,
-				sourceRepo: plugin.sourceRepo,
-			});
-		}
-	}
-
-	for (const [mpName, localMp] of localMarketplaces) {
-		// Skip if already fetched from defaults
-		if (marketplaceNames.has(mpName)) continue;
-
-		// Add ALL plugins from this local marketplace cache
-		for (const localPlugin of localMp.plugins) {
-			const pluginId = `${localPlugin.name}@${mpName}`;
-			if (seenPluginIds.has(pluginId)) continue;
-
-			const installedVersion = installedVersions[pluginId];
-			const isEnabled = enabledPlugins[pluginId] === true;
-			const scopeStatus = buildScopeStatus(pluginId);
-
-			seenPluginIds.add(pluginId);
-			plugins.push({
-				id: pluginId,
-				name: localPlugin.name,
-				version: localPlugin.version,
-				description: localPlugin.description || "",
-				marketplace: mpName,
-				marketplaceDisplay: localMp.name || formatMarketplaceName(mpName),
-				enabled: isEnabled,
-				installedVersion: installedVersion,
-				hasUpdate: installedVersion
-					? compareVersions(localPlugin.version, installedVersion) > 0
-					: false,
-				...scopeStatus,
-				category: localPlugin.category,
-				author: localPlugin.author,
-				agents: localPlugin.agents,
-				commands: localPlugin.commands,
-				skills: localPlugin.skills,
-				source: localPlugin.source,
-				mcpServers: localPlugin.mcpServers,
-				lspServers: localPlugin.lspServers,
-				releases: localPlugin.releases,
-			});
-		}
-	}
-
-	// Add orphaned plugins (enabled/installed but not in any cache)
-	const allPluginIds = new Set([
-		...Object.keys(enabledPlugins),
-		...Object.keys(installedVersions),
-	]);
-
-	for (const pluginId of allPluginIds) {
-		if (seenPluginIds.has(pluginId)) continue;
-
-		const parsed = parsePluginId(pluginId);
-		if (!parsed) continue;
-
-		const { pluginName, marketplace: mpName } = parsed;
-		const installedVersion = installedVersions[pluginId];
-		const isEnabled = enabledPlugins[pluginId] === true;
-		const scopeStatus = buildScopeStatus(pluginId);
-
-		// 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";
-		const hasUpdate =
-			installedVersion && localPlugin?.version
-				? compareVersions(localPlugin.version, installedVersion) > 0
-				: false;
-
-		plugins.push({
-			id: pluginId,
-			name: pluginName,
-			version: latestVersion,
-			description,
-			marketplace: mpName,
-			marketplaceDisplay: localMp?.name || formatMarketplaceName(mpName),
-			enabled: isEnabled,
-			...scopeStatus,
-			installedVersion: installedVersion,
-			hasUpdate,
-			isOrphaned: true,
-			movedTo,
-		});
-	}
-
-	await annotateContentDrift(plugins, "user");
-	return plugins;
-}
-
 /**
  * Find another configured marketplace that still publishes this plugin name.
  *
@@ -689,13 +513,39 @@ function findPluginInOtherMarketplace(
 	return undefined;
 }
 
+/**
+ * Is this plugin one whose files could have moved while its version did not?
+ *
+ * Drift is defined as "same version, different files", so it is only a
+ * question at all when the catalog version and the installed version are
+ * PROVABLY the same — `compareVersions` returning exactly 0, never null, which
+ * would be "cannot tell". A pending version bump is not drift: `hasContentDrift`
+ * compares the installed commit's subtree against the marketplace clone's HEAD,
+ * and for a plugin that is simply behind, that subtree differs BECAUSE of the
+ * newer version. Flagging it would turn an `update` into a `repair`, and a
+ * repair reinstalls whatever the clone holds — past a pin.
+ *
+ * This used to open with `if (plugin.hasUpdate || …)`, the pre-classifier
+ * boolean. It decided nothing the version compare below does not (`isBehind`
+ * cannot be true for a pair that compares 0), and gating the input the shared
+ * classifier reads on the rule it replaced is how the two drift apart again.
+ * An orphan is still excluded: it has no marketplace entry to diff against.
+ *
+ * Exported to be tested directly; `annotateContentDrift` itself needs the real
+ * registry.
+ */
+export function contentDriftCandidate(plugin: PluginInfo): boolean {
+	if (plugin.isOrphaned) return false;
+	if (!plugin.installedVersion || !plugin.version) return false;
+	return compareVersions(plugin.version, plugin.installedVersion) === 0;
+}
+
 /**
  * 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.
+ * PluginInfo gets the same treatment. Which plugins are worth asking about is
+ * {@link contentDriftCandidate}.
  *
  * Best-effort throughout: a plugin whose drift cannot be determined is left
  * exactly as it is today.
@@ -721,10 +571,7 @@ async function annotateContentDrift(
 
 	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;
+			if (!contentDriftCandidate(plugin)) return;
 
 			const entry = pickRegistryEntry(
 				registry.plugins[plugin.id],
@@ -748,24 +595,94 @@ async function annotateContentDrift(
 	);
 }
 
-// Simple version comparison (returns 1 if a > b, -1 if a < b, 0 if equal)
+/** A dotted run of digits, optionally `v`-prefixed. Anything else is opaque. */
+const SEMVER_ISH = /^\d+(\.\d+)*$/;
+
+const normalize = (v: string) => v.replace(/^v/, "");
+
+/**
+ * Version comparison: 1 if a > b, -1 if a < b, 0 if equal, **null if the pair
+ * carries no ordering at all**.
+ *
+ * `null` is the whole point. This used to return 0 for every unorderable pair,
+ * and 0 means "equal" to every caller — so "I cannot tell" was indistinguishable
+ * from "they match". Measured against real registry values before the fix:
+ *
+ *   compareVersions("517b2fcd1b60", "b819188d2eea") = 0   ← two DIFFERENT commits
+ *   compareVersions("7.2.0",        "517b2fcd1b60") = 1   ← a fabricated ordering
+ *
+ * Anthropic's official plugins record a commit sha as their version, so the
+ * first line made every one of them permanently un-updatable, and the second
+ * invented an update whenever a sha met a semver.
+ *
+ * Three cases, and only the first has an answer:
+ * - both dotted-numeric → compare numerically, shorter side zero-padded
+ * - both opaque         → equal strings are 0; different strings are `null`,
+ *                         because two commit ids carry no order between them
+ * - one of each         → `null`; there is no shared scale
+ *
+ * A missing side is `null` too. It used to be 0, which claimed an absent
+ * version matched a present one.
+ *
+ * Callers asking "should this be updated?" want {@link isBehind}, not this.
+ */
 export function compareVersions(
 	a: string | null | undefined,
 	b: string | null | undefined,
-): number {
-	if (!a || !b) return 0;
-	const partsA = a.replace(/^v/, "").split(".").map(Number);
-	const partsB = b.replace(/^v/, "").split(".").map(Number);
+): number | null {
+	if (!a || !b) return null;
+	const A = normalize(a);
+	const B = normalize(b);
 
+	const aNumeric = SEMVER_ISH.test(A);
+	const bNumeric = SEMVER_ISH.test(B);
+
+	if (aNumeric !== bNumeric) return null; // no shared scale
+	if (!aNumeric) return A === B ? 0 : null; // two opaque ids: equal, or unordered
+
+	const partsA = A.split(".").map(Number);
+	const partsB = B.split(".").map(Number);
 	for (let i = 0; i < Math.max(partsA.length, partsB.length); i++) {
-		const numA = partsA[i] || 0;
-		const numB = partsB[i] || 0;
+		const numA = partsA[i] ?? 0;
+		const numB = partsB[i] ?? 0;
 		if (numA > numB) return 1;
 		if (numA < numB) return -1;
 	}
 	return 0;
 }
 
+/**
+ * Is `installed` out of date against what the catalog publishes as `latest`?
+ *
+ * `true` / `false` / `null`, where **null means unknown** — never a silent
+ * `false`. This is the question every update path actually asks, and keeping it
+ * separate from {@link compareVersions} is what lets the two opaque-id cases
+ * differ:
+ *
+ * - Ordering two commit shas is impossible, so `compareVersions` says `null`.
+ * - But the catalog is authoritative for what is published *now*, so an
+ *   installed sha that differs from it is **not current** — `isBehind` says
+ *   `true`. That is what makes a sha-versioned plugin updatable at all.
+ *
+ * Not installed is `null`, not `false`. The old inline check was
+ * `installedVersion && compare(...) > 0`, so a plugin with no install at all
+ * evaluated to `false` and was reported — and counted — as up to date.
+ */
+export function isBehind(
+	latest: string | null | undefined,
+	installed: string | null | undefined,
+): boolean | null {
+	if (!latest || !installed) return null;
+	const cmp = compareVersions(latest, installed);
+	if (cmp !== null) return cmp > 0;
+
+	// Unorderable. Two opaque ids that differ still mean "not what is published".
+	const bothOpaque =
+		!SEMVER_ISH.test(normalize(latest)) &&
+		!SEMVER_ISH.test(normalize(installed));
+	return bothOpaque ? true : null;
+}
+
 // Get installed plugin versions from settings.json (shared, not secret)
 async function getInstalledPluginVersions(
 	projectPath?: string,

package/src/services/resolver.ts

@@ -79,8 +79,13 @@ export function resolveExtends(
 	};
 }
 
-/** Map a manifest cliTools entry (name -> version) to a BinRequirement. */
-function cliToolToBin(name: string, version: string): BinRequirement {
+/**
+ * Map a manifest cliTools entry (name -> version) to a BinRequirement.
+ *
+ * Exported so the TUI's CLI Tools screen maps a catalogue tool the same way the
+ * resolver does, rather than keeping a second copy of the mapping.
+ */
+export function cliToolToBin(name: string, version: string): BinRequirement {
 	const tool = cliTools.find((t) => t.name === name);
 	const pinned = version && version !== "latest" ? version : undefined;
 	if (tool) {