claudeup 6.5.1 → 6.6.0

package/src/services/update-plan.ts

@@ -1,24 +1,47 @@
 /**
- * Pure planning for `claudeup update` — the dependency-facing update.
+ * The ONE place plugin state is decided, and the planning for `claudeup update`.
+ *
+ * `classifyPlugin` answers "what state is this plugin in, and why" for a plugin
+ * id, the version the profile pins it to, and the catalog. Every consumer reads
+ * its answer and nothing else: `claudeup update`'s plan, and in the TUI the
+ * Plugins row text, the detail panel, the header counts, the `U`/`a` actions
+ * and the scope picker. The TUI used to derive the same state from raw
+ * `PluginInfo` flags with its own rules, and the two front ends drifted — the
+ * same plugin, in the same project, could read green in one and red in the
+ * other, or carry a different reason in each.
+ *
+ * Tools follow the same rule: `planBinUpdates` plans from `classifyTool`
+ * (services/tool-probe.ts), the same classifier the TUI's CLI Tools screen
+ * renders, so a tool has one state in both front ends.
  *
  * `install` makes the machine match the manifest's pins. `update` advances it:
  * anything the active profile declares but the machine lacks gets installed,
  * and anything pinned "latest" moves to the newest version the marketplace
  * catalog offers. Everything here is a pure function of a closure plus captured
- * machine state, so the decisions are unit-testable and the command file only
- * does IO.
+ * machine state, so the decisions are unit-testable and the callers only do IO.
  *
- * The one rule worth stating out loud: a catalog fetch that FAILED must never
- * be reported as "up to date". `PluginInfo.updateCheckFailed` exists because a
- * rate-limited fetch once compared the installed version against a stale local
- * clone, found them equal, and rendered the failure as a clean bill of health.
- * That case gets its own action (`unknown`) rather than folding into `current`.
+ * The one rule worth stating out loud: "cannot tell" must never be reported as
+ * "up to date". `PluginInfo.updateCheckFailed` exists because a rate-limited
+ * fetch once compared the installed version against a stale local clone, found
+ * them equal, and rendered the failure as a clean bill of health. That case, and
+ * every other one where the answer is not provable, gets its own action
+ * (`unknown`) rather than folding into `current`.
  */
 
 import type { ProfileSkillRef, ResolvedBin } from "../types/index.js";
 import type { PluginScope } from "./claude-cli.js";
-import type { BinCheckResult } from "./doctor-bins.js";
-import { type PluginInfo, compareVersions } from "./plugin-manager.js";
+import {
+	type PluginInfo,
+	compareVersions,
+	isBehind,
+} from "./plugin-manager.js";
+import {
+	type ToolFacts,
+	type ToolReason,
+	type ToolState,
+	type ToolStatus,
+	classifyTool,
+} from "./tool-probe.js";
 
 // ── Plugins ──────────────────────────────────────────────────────────────────
 
@@ -34,6 +57,36 @@ export type PluginUpdateAction =
 	/** The catalog check failed; we cannot claim either way. */
 	| "unknown";
 
+/**
+ * WHY a plugin is in its state — a machine code, so tests and styling can key
+ * on it without parsing the human `note`.
+ */
+export type PluginReason =
+	/** install: declared by the profile, installed nowhere. */
+	| "absent"
+	/** install: enabled in a settings file, but no registry row in any scope. */
+	| "enabled-not-installed"
+	/** unknown: a marketplace we READ does not list it. */
+	| "not-offered"
+	/** unknown: installed, unlisted, and another marketplace publishes the name. */
+	| "moved"
+	/** unknown: installed, unlisted, and its marketplace contributed no listed ids. */
+	| "marketplace-unread"
+	/** unknown: the catalog fetch failed ("latest" pins only). */
+	| "catalog-unverified"
+	/** unknown: listed, but its marketplace publishes no version for it. */
+	| "no-published-version"
+	/** unknown: an installed scope cannot be ordered against the target. */
+	| "unorderable"
+	/** repair: files changed without a version bump. */
+	| "content-stale"
+	/** update: a scope is provably behind. */
+	| "behind"
+	/** current|update: an exact pin differs from what the marketplace offers. */
+	| "pin-undeliverable"
+	/** current: every installed scope is at (or ahead of) the target. */
+	| "up-to-date";
+
 export interface PluginUpdateItem {
 	pluginId: string;
 	/** What the profile pins: an exact version, or "latest". */
@@ -45,9 +98,19 @@ export interface PluginUpdateItem {
 	/** Version this item would move to. Null for `current`/`unknown`. */
 	target: string | null;
 	action: PluginUpdateAction;
+	/** Why it is in this state. */
+	reason: PluginReason;
 	/** Scopes holding an install this action must touch. Empty for a fresh install. */
 	scopes: PluginScope[];
-	/** Human explanation, set for `unknown` and `repair`. */
+	/**
+	 * The version installed in each scope BEFORE any work, so an apply can tell
+	 * by reading back whether anything actually moved.
+	 */
+	beforeVersions: Partial<Record<PluginScope, string>>;
+	/**
+	 * The exact human reason. The CLI prints it and the TUI shows it verbatim, so
+	 * it is the SAME string in both front ends.
+	 */
 	note?: string;
 }
 
@@ -67,21 +130,30 @@ function scopeVersions(
 	return out;
 }
 
-/** The highest version installed across scopes, or null. */
+/**
+ * The highest version installed across scopes, or null.
+ *
+ * `compareVersions` answers null for an unorderable pair, and null is not
+ * `>= 0`, so the reduce keeps the right-hand side when two versions cannot be
+ * ranked. "Highest" is not meaningful across commit ids; picking one
+ * deterministically is, and every caller only needs *an* installed version.
+ */
 function highestInstalled(info: PluginInfo | undefined): string | null {
 	const versions = scopeVersions(info).map(([, v]) => v);
 	if (versions.length === 0) return null;
-	return versions.reduce((a, b) => (compareVersions(a, b) >= 0 ? a : b));
+	return versions.reduce((a, b) =>
+		(compareVersions(a, b) ?? -1) >= 0 ? a : b,
+	);
 }
 
 /**
  * Scopes that are strictly BEHIND `target`.
  *
- * Every scope that holds an outdated install is returned, not just "user". The
- * prerunner learned this the expensive way: it detected drift from the current
- * project's resolved version, then "fixed" it at user scope and reported
- * success, leaving the project row untouched so the same drift reappeared on
- * every run.
+ * Every scope that holds an outdated install is returned, not just "user".
+ * Updating one hardcoded scope does not converge: drift is detected from the
+ * CURRENT PROJECT's resolved version, so "fixing" user scope reports success
+ * and leaves the project row untouched, and the same drift reappears on the
+ * next run.
  *
  * This only ever moves FORWARD, and there is deliberately no option to do
  * otherwise. Nothing here can perform a downgrade: `claude plugin install`
@@ -100,182 +172,567 @@ export function scopesNeeding(
 	info: PluginInfo | undefined,
 	target: string,
 ): PluginScope[] {
+	// `isBehind`, not a raw compare: a scope holding a commit sha that differs
+	// from the published one IS behind, even though the two carry no ordering.
+	// A raw `compareVersions(...) > 0` reported false for that pair and the
+	// scope was silently left alone. An unknown (null) is still left alone —
+	// moving a scope we cannot rank would be a guess.
 	return scopeVersions(info)
-		.filter(([, version]) => compareVersions(target, version) > 0)
+		.filter(([, version]) => isBehind(target, version) === true)
 		.map(([scope]) => scope);
 }
 
+/** True when some installed scope cannot be ordered against `target` at all. */
+function hasUnorderableScope(
+	info: PluginInfo | undefined,
+	target: string,
+): boolean {
+	return scopeVersions(info).some(
+		([, version]) => isBehind(target, version) === null,
+	);
+}
+
+/** The "@marketplace" suffix of an id, or null when it has none to reason about. */
+function marketplaceSuffix(id: string): string | null {
+	const at = id.indexOf("@");
+	if (at < 0) return null;
+	const suffix = id.slice(at);
+	return suffix.length < 2 ? null : suffix;
+}
+
 /**
- * Decide what to do with every plugin the profile declares.
+ * The catalog, indexed for the questions the classifier asks of it.
  *
- * @param pinned  closure.plugins — pluginId -> exact version | "latest"
- * @param catalog getAvailablePlugins() output, keyed by plugin id
+ * "Listed" is narrower than "present". `getAvailablePlugins` puts ORPHANS —
+ * installed or enabled, but published by no marketplace we read — into the same
+ * list with `isOrphaned: true`, so a plain `has(id)` is true for a plugin that
+ * nothing publishes. Treating an orphan as listed is what let an orphan plan as
+ * `current`: its `version` is filled in from its own installed version, so the
+ * compare found them equal.
  */
-export function planPluginUpdates(
-	pinned: Record<string, string>,
-	catalog: Map<string, PluginInfo>,
-): PluginUpdateItem[] {
-	const items: PluginUpdateItem[] = [];
+export interface CatalogIndex {
+	get(pluginId: string): PluginInfo | undefined;
+	/** In the catalog AND not an orphan: a marketplace we read publishes it. */
+	isListed(pluginId: string): boolean;
+	/** Some OTHER listed id shares this id's "@marketplace" suffix. False for ids without "@". */
+	marketplaceIsKnown(pluginId: string): boolean;
+}
 
-	for (const [pluginId, pin] of Object.entries(pinned)) {
-		const info = catalog.get(pluginId);
-		const installed = highestInstalled(info);
-		const available = info?.version ?? null;
+export function indexCatalog(
+	catalog: ReadonlyMap<string, PluginInfo> | readonly PluginInfo[],
+): CatalogIndex {
+	const byId: ReadonlyMap<string, PluginInfo> =
+		catalog instanceof Map
+			? catalog
+			: new Map((catalog as readonly PluginInfo[]).map((p) => [p.id, p]));
 
-		const base = { pluginId, pinned: pin, installed, available };
+	// Listed ids per marketplace suffix, counted once. The previous inline check
+	// scanned every catalog key for every plugin, which is quadratic in a catalog
+	// of ~300 official plugins.
+	const listedPerSuffix = new Map<string, number>();
+	for (const [id, info] of byId) {
+		if (info.isOrphaned) continue;
+		const suffix = marketplaceSuffix(id);
+		if (suffix)
+			listedPerSuffix.set(suffix, (listedPerSuffix.get(suffix) ?? 0) + 1);
+	}
 
-		// Not installed anywhere — the "checked but not installed" case.
-		if (!installed) {
-			items.push({
-				...base,
-				target: pin === "latest" ? available : pin,
-				action: "install",
-				scopes: [],
-			});
-			continue;
-		}
+	const isListed = (id: string): boolean => {
+		const info = byId.get(id);
+		return !!info && !info.isOrphaned;
+	};
 
-		// An exact pin is planned against what can ACTUALLY be delivered.
-		//
-		// This is dependency management, not a package manager: there is no
-		// resolver and no version negotiation. `claude plugin install` takes no
-		// version — it fetches whatever the marketplace publishes now — so a pin
-		// naming anything else is a request nothing can satisfy.
-		//
-		// Planning toward the pin regardless is an infinite loop with a progress
-		// bar: plan 9.9.9 → 4.6.1, install, get 9.9.9 back, replan the same thing
-		// next run, and fail `--check` every time in between. Targeting the
-		// deliverable version converges, and the note carries the shortfall so it
-		// is recorded rather than hidden. `install --check` + `strictVersions`
-		// remains the place that GATES on pin drift; this command reports it.
-		//
-		// `scopesNeeding` only ever moves forward, so a scope already AHEAD of the
-		// deliverable version is left alone rather than downgraded — the same rule
-		// as the "latest" path below, because in both cases the target is what the
-		// marketplace currently publishes.
-		//
-		// The decision comes from the PER-SCOPE versions, never from `installed`.
-		// `installed` is the highest across scopes, so comparing it to the target
-		// hides the case that matters most: user scope at the target and project
-		// scope behind it reads as "current" while the project — the scope that
-		// actually loads for this repo — stays stale.
-		if (pin !== "latest") {
-			const deliverable = available ?? pin;
-			const needing = scopesNeeding(info, deliverable);
-			items.push({
-				...base,
-				target: deliverable,
-				action: needing.length === 0 ? "current" : "update",
-				scopes: needing,
-				...(available !== null && available !== pin
-					? {
-							note: `manifest pins ${pin}; the marketplace offers only ${available}`,
-						}
-					: {}),
-			});
-			continue;
-		}
+	return {
+		get: (id) => byId.get(id),
+		isListed,
+		marketplaceIsKnown: (id) => {
+			const suffix = marketplaceSuffix(id);
+			if (!suffix) return false;
+			const others =
+				(listedPerSuffix.get(suffix) ?? 0) - (isListed(id) ? 1 : 0);
+			return others > 0;
+		},
+	};
+}
 
-		// "latest" — and the catalog is the only source for what that means.
-		if (info?.updateCheckFailed) {
-			items.push({
-				...base,
-				target: null,
-				action: "unknown",
-				scopes: [],
-				note:
-					info.updateCheckFailure?.detail ??
-					"catalog fetch failed — cannot tell whether a newer version exists",
-			});
-			continue;
-		}
+/** True when a settings file enables the plugin in at least one scope. */
+function enabledAnywhere(info: PluginInfo | undefined): boolean {
+	return (
+		!!info?.userScope?.enabled ||
+		!!info?.projectScope?.enabled ||
+		!!info?.localScope?.enabled
+	);
+}
 
-		// Same version, changed files. There is no version bump to detect, so a
-		// plain install is a no-op ("Plugin is already installed") and only
-		// uninstall+install refreshes the content.
-		if (info?.contentStale) {
-			items.push({
-				...base,
-				target: installed,
-				action: "repair",
-				scopes: scopeVersions(info).map(([scope]) => scope),
-				note: "files changed without a version bump",
-			});
-			continue;
+/**
+ * THE plugin classifier. Pure.
+ *
+ * The rules are evaluated in order and the first match wins. Each branch below
+ * returns, so reading top to bottom is reading the precedence.
+ *
+ * @param pluginId the plugin
+ * @param pin      what it is judged against: an exact version, or "latest"
+ * @param index    the catalog — see {@link indexCatalog}
+ */
+export function classifyPlugin(
+	pluginId: string,
+	pin: string,
+	index: CatalogIndex,
+): PluginUpdateItem {
+	const info = index.get(pluginId);
+	const listed = index.isListed(pluginId);
+	const installed = highestInstalled(info);
+	// An orphan's `version` is its own installed version (or a stale local
+	// clone's), not something a marketplace we read offers — so it is not
+	// "available" from anywhere.
+	const available = listed ? (info?.version ?? null) : null;
+
+	const base = {
+		pluginId,
+		pinned: pin,
+		installed,
+		available,
+		beforeVersions: Object.fromEntries(scopeVersions(info)) as Partial<
+			Record<PluginScope, string>
+		>,
+	};
+
+	// Declared by the profile, installed nowhere, and its marketplace IS
+	// known to us but does not list it. That pin names a plugin that cannot
+	// be installed, and saying so is the whole point of this branch.
+	//
+	// Measured on the reporter's machine: mnemex's profile pinned
+	// `agentdev@magus` (retired) and `seo@magus` (moved to magus-marketing),
+	// and every run reported "3 install" while two of the three could never
+	// succeed — `claude plugin install` had nothing to fetch. Applied, failed,
+	// replanned identically, forever, with no diagnostic.
+	//
+	// "Not offered" is CATALOG MEMBERSHIP, not a missing version. Keying this
+	// on `available === null` was wrong twice over, and the second way was
+	// worse than the bug it replaced:
+	//
+	// - 278 of the 292 plugins in `claude-plugins-official` declare no
+	//   version at all — `feature-dev` among them. They are listed, they are
+	//   installable, and `available` is null for every one. Treating that as
+	//   "not offered" made a profile pin for any of them plan `unknown` and
+	//   never install. Measured on the reporting machine.
+	// - An INSTALLED plugin whose catalog version is unreadable is handled
+	//   further down against what is on disk. Hence `!installed` here.
+	//
+	// Listing answers the real question directly. The remaining trap is that a
+	// marketplace this machine has not registered yet contributes NO entries, so
+	// its plugins are also absent — but installing one is exactly what registers
+	// the marketplace. `marketplaceIsKnown` separates the two: holding other
+	// LISTED ids from that marketplace proves we genuinely read its catalog, so
+	// absence is an answer; holding none proves nothing.
+	if (!listed && !installed && index.marketplaceIsKnown(pluginId)) {
+		return {
+			...base,
+			target: null,
+			action: "unknown",
+			reason: "not-offered",
+			scopes: [],
+			note: "not offered by any configured marketplace",
+		};
+	}
+
+	// Not installed anywhere — the "checked but not installed" case.
+	//
+	// Nothing is installed in any scope here, so "enabled somewhere" is exactly
+	// "enabled but not installed". It is tested directly rather than through
+	// `isEnabledButNotInstalled`, which excludes orphans: an orphan that is only
+	// a settings key would otherwise read as `absent`, and the TUI renders
+	// `absent` as "the profile declares it", which an undeclared orphan does not.
+	if (!installed) {
+		const brokenEnable = enabledAnywhere(info);
+		return {
+			...base,
+			target: pin === "latest" ? available : pin,
+			action: "install",
+			reason: brokenEnable ? "enabled-not-installed" : "absent",
+			scopes: [],
+			...(brokenEnable
+				? { note: "enabled in settings, but no files on disk" }
+				: {}),
+		};
+	}
+
+	// Installed, but no marketplace we read lists it — an orphan.
+	//
+	// Planning this against its own installed version (which is what an
+	// orphan's `version` holds) found the two equal and reported `current`,
+	// while the TUI rendered the same plugin red as "deprecated". Neither is
+	// the fact. What is known is one of three things, and each gets its own
+	// text: it moved to a marketplace that does publish it; a marketplace we
+	// did read no longer lists it; or its marketplace contributed nothing we
+	// could read, so its absence proves nothing either way.
+	if (!listed) {
+		const orphan = {
+			...base,
+			target: null,
+			action: "unknown" as const,
+			scopes: [],
+		};
+		if (info?.movedTo) {
+			return {
+				...orphan,
+				reason: "moved",
+				note: `moved to ${info.movedTo}`,
+			};
+		}
+		if (index.marketplaceIsKnown(pluginId)) {
+			return {
+				...orphan,
+				reason: "not-offered",
+				note: "not offered by any configured marketplace",
+			};
 		}
+		const mp =
+			info?.marketplace || marketplaceSuffix(pluginId)?.slice(1) || pluginId;
+		return {
+			...orphan,
+			reason: "marketplace-unread",
+			note: `its marketplace ${mp} was not read, so whether it still offers this plugin is unknown`,
+		};
+	}
 
-		// Installed, but no marketplace offers it any more. "current" would be a
-		// claim we cannot support — there is nothing to compare against.
-		if (!available) {
-			items.push({
+	// An exact pin is planned against what can ACTUALLY be delivered.
+	//
+	// This is dependency management, not a package manager: there is no
+	// resolver and no version negotiation. `claude plugin install` takes no
+	// version — it fetches whatever the marketplace publishes now — so a pin
+	// naming anything else is a request nothing can satisfy.
+	//
+	// Planning toward the pin regardless is an infinite loop with a progress
+	// bar: plan 9.9.9 → 4.6.1, install, get 9.9.9 back, replan the same thing
+	// next run, and fail `--check` every time in between. Targeting the
+	// deliverable version converges, and the note carries the shortfall so it
+	// is recorded rather than hidden. `install --check` + `strictVersions`
+	// remains the place that GATES on pin drift; this command reports it.
+	//
+	// `scopesNeeding` only ever moves forward, so a scope already AHEAD of the
+	// deliverable version is left alone rather than downgraded — the same rule
+	// as the "latest" path below, because in both cases the target is what the
+	// marketplace currently publishes.
+	//
+	// The decision comes from the PER-SCOPE versions, never from `installed`.
+	// `installed` is the highest across scopes, so comparing it to the target
+	// hides the case that matters most: user scope at the target and project
+	// scope behind it reads as "current" while the project — the scope that
+	// actually loads for this repo — stays stale.
+	if (pin !== "latest") {
+		const deliverable = available ?? pin;
+		const needing = scopesNeeding(info, deliverable);
+
+		// The same "cannot tell is not current" rule as the "latest" path below.
+		// A scope that cannot be ordered against the deliverable contributes
+		// nothing to `needing`, and used to fall through to `current` here.
+		if (needing.length === 0 && hasUnorderableScope(info, deliverable)) {
+			return {
 				...base,
 				target: null,
 				action: "unknown",
+				reason: "unorderable",
 				scopes: [],
-				note: "not offered by any configured marketplace",
-			});
-			continue;
+				note:
+					available !== null
+						? `installed version cannot be compared with the published ${available}`
+						: `installed version cannot be compared with the pin ${pin}`,
+			};
 		}
 
-		// Again per-scope, and only ever forward.
-		const needing = scopesNeeding(info, available);
-		items.push({
+		const undeliverable = available !== null && available !== pin;
+		return {
 			...base,
-			target: needing.length === 0 ? installed : available,
+			target: deliverable,
 			action: needing.length === 0 ? "current" : "update",
+			reason: undeliverable
+				? "pin-undeliverable"
+				: needing.length === 0
+					? "up-to-date"
+					: "behind",
 			scopes: needing,
-		});
+			...(undeliverable
+				? {
+						note: `manifest pins ${pin}; the marketplace offers only ${available}`,
+					}
+				: {}),
+		};
 	}
 
-	return items.sort((a, b) => a.pluginId.localeCompare(b.pluginId));
+	// "latest" — and the catalog is the only source for what that means.
+	if (info?.updateCheckFailed) {
+		return {
+			...base,
+			target: null,
+			action: "unknown",
+			reason: "catalog-unverified",
+			scopes: [],
+			note:
+				info.updateCheckFailure?.detail ??
+				"catalog fetch failed — cannot tell whether a newer version exists",
+		};
+	}
+
+	// Same version, changed files. There is no version bump to detect, so a
+	// plain install is a no-op ("Plugin is already installed") and only
+	// uninstall+install refreshes the content.
+	if (info?.contentStale) {
+		return {
+			...base,
+			target: installed,
+			action: "repair",
+			reason: "content-stale",
+			scopes: scopeVersions(info).map(([scope]) => scope),
+			note: "files changed without a version bump",
+		};
+	}
+
+	// Installed and listed, with nothing to compare against. The answer is
+	// `unknown` — "current" is a claim we cannot support — and the note must not
+	// confuse this with the withdrawn case (handled above as an orphan): it is
+	// still published, still installable; we simply have no number to compare.
+	// 278 of the 292 plugins in `claude-plugins-official` are in this state, so
+	// reporting them as "not offered by any configured marketplace" told the
+	// user their installed, working, currently-published plugin had been
+	// withdrawn.
+	if (!available) {
+		return {
+			...base,
+			target: null,
+			action: "unknown",
+			reason: "no-published-version",
+			scopes: [],
+			note: "its marketplace publishes no version for this plugin, so there is nothing to compare",
+		};
+	}
+
+	// Again per-scope, and only ever forward.
+	const needing = scopesNeeding(info, available);
+
+	// No scope is provably behind — but that is not the same as being current.
+	// `scopesNeeding` filters on `isBehind(...) === true`, so a scope whose
+	// version cannot be ordered against the catalog contributes nothing and
+	// would fall through to `current`, which is precisely the "cannot tell
+	// rendered as nothing wrong" this whole change removes.
+	//
+	// Real and measured: 21 registry rows carry the literal string "unknown"
+	// as their version, across 8 `@claude-plugins-official` ids. Against a
+	// semver catalog they are unorderable, so they land here every run.
+	if (needing.length === 0 && hasUnorderableScope(info, available)) {
+		return {
+			...base,
+			target: null,
+			action: "unknown",
+			reason: "unorderable",
+			scopes: [],
+			note: `installed version cannot be compared with the published ${available}`,
+		};
+	}
+
+	return {
+		...base,
+		target: needing.length === 0 ? installed : available,
+		action: needing.length === 0 ? "current" : "update",
+		reason: needing.length === 0 ? "up-to-date" : "behind",
+		scopes: needing,
+	};
+}
+
+/**
+ * Decide what to do with every plugin the profile declares.
+ *
+ * @param pinned  closure.plugins — pluginId -> exact version | "latest"
+ * @param catalog getAvailablePlugins() output, keyed by plugin id
+ */
+export function planPluginUpdates(
+	pinned: Record<string, string>,
+	catalog: Map<string, PluginInfo>,
+): PluginUpdateItem[] {
+	const index = indexCatalog(catalog);
+	return Object.entries(pinned)
+		.map(([pluginId, pin]) => classifyPlugin(pluginId, pin, index))
+		.sort((a, b) => a.pluginId.localeCompare(b.pluginId));
+}
+
+/**
+ * The pin a TUI row is judged against.
+ *
+ * 1. The active profile's pin, when it declares the plugin — the SAME value
+ *    `claudeup update` plans with, which is what makes the two agree.
+ * 2. Otherwise "latest", when the plugin is installed in any scope or enabled
+ *    in one — what the TUI's own update actions have always planned with, so
+ *    the row and the action agree.
+ * 3. Otherwise null: an undeclared catalog entry the user is only browsing. It
+ *    gets no status at all. `install` means "the profile wants it", and an
+ *    undeclared plugin carries no such claim.
+ *
+ * A consequence the renderer relies on: reason `absent` can only come from
+ * rule 1, because rule 2 never assigns a pin to a row that is neither installed
+ * nor enabled.
+ */
+export function pinForRow(
+	info: PluginInfo,
+	pins: Readonly<Record<string, string>>,
+): string | null {
+	if (Object.hasOwn(pins, info.id)) return pins[info.id] ?? null;
+	if (scopeVersions(info).length > 0 || enabledAnywhere(info)) return "latest";
+	return null;
+}
+
+/**
+ * One status per row that has a pin. Rows whose {@link pinForRow} is null are
+ * absent from the map.
+ *
+ * Computed once per data/pins change, and the same map feeds every consumer —
+ * so the row, the detail panel, the header and the scope picker cannot disagree.
+ */
+export function classifyPluginRows(
+	plugins: readonly PluginInfo[],
+	pins: Readonly<Record<string, string>>,
+): Map<string, PluginUpdateItem> {
+	const index = indexCatalog(plugins);
+	const out = new Map<string, PluginUpdateItem>();
+	for (const info of plugins) {
+		const pin = pinForRow(info, pins);
+		if (pin === null) continue;
+		out.set(info.id, classifyPlugin(info.id, pin, index));
+	}
+	return out;
+}
+
+export interface PluginStateCounts {
+	install: number;
+	update: number;
+	repair: number;
+	current: number;
+	unknown: number;
+}
+
+/** Counts per action. One implementation, so a header cannot recount differently. */
+export function countPluginStates(
+	items: Iterable<PluginUpdateItem>,
+): PluginStateCounts {
+	const counts: PluginStateCounts = {
+		install: 0,
+		update: 0,
+		repair: 0,
+		current: 0,
+		unknown: 0,
+	};
+	for (const item of items) counts[item.action]++;
+	return counts;
+}
+
+/**
+ * The scope picker's one question: would advancing THIS scope be an update?
+ *
+ * Only a provable `update` that touches the scope says yes. A scope ahead of the
+ * catalog, one that cannot be ordered, and a `repair` all say no — `claude
+ * plugin install` on the same version is a no-op, so offering "update" there
+ * runs something that changes nothing.
+ */
+export function scopeIsBehind(
+	status: PluginUpdateItem | null | undefined,
+	scope: PluginScope,
+): boolean {
+	return status?.action === "update" && status.scopes.includes(scope);
 }
 
 // ── Binaries ─────────────────────────────────────────────────────────────────
 
-export type BinUpdateAction =
-	/** Not on PATH. */
-	| "install"
-	/** Present and unpinned — re-run the installer to advance it. */
-	| "upgrade"
-	/** Present and pinned to an exact version; nothing to advance to. */
-	| "current";
+/**
+ * A tool's action is exactly its state from `classifyTool` — the same word the
+ * TUI's CLI Tools screen shows for the same tool.
+ */
+export type BinUpdateAction = ToolState;
 
 export interface BinUpdateItem {
 	name: string;
 	action: BinUpdateAction;
+	/** Why it is in this state. */
+	reason: ToolReason;
+	/** The exact human reason; the same string the TUI shows. */
+	note?: string;
+	/**
+	 * Set when the upgrade will take the tool over from another installer —
+	 * {@link ToolStatus.adopted}. The row must say so: it is an ordinary
+	 * `upgrade` otherwise, and the owner changing is not something to discover
+	 * afterwards.
+	 */
+	adopted?: string;
 	/** The exact pin, when the profile declares one. */
 	version?: string;
+	/** The version PATH runs, or null when absent / unreadable. */
+	installed: string | null;
+	/** The newest version its installer offers, when known. */
+	latest: string | null;
+	/** The version an install/upgrade aims at, when known. */
+	target: string | null;
 	sources: string[];
 }
 
 /**
- * Plan binary work from a presence check.
+ * Plan binary work from probe facts, through {@link classifyTool}.
+ *
+ * This used to plan from a presence check alone: present-and-unpinned was an
+ * UPGRADE, every run, because nothing could say whether the tool was behind.
+ * `brew upgrade tmux` on a current tmux, `uv tool install --force --upgrade`
+ * on a current browser-use — each "succeeded", changed nothing, and was
+ * planned identically the next time. Now an upgrade is planned only when the
+ * installer that owns the running binary says it is behind (or its registry
+ * does), and a tool whose state cannot be established is `unknown`, which is
+ * shown and never applied.
  *
- * There is no version probe for an arbitrary binary — `checkBinaries` answers
- * present/absent only — so a PINNED bin that is present is left alone rather
- * than reinstalled on a guess. An unpinned one is re-run through its installer,
- * which is what "update" means for a dependency with no declared version.
+ * Facts are matched by name. A bin with no facts entry was never probed, and
+ * that is `unknown` too — "not checked" is not "fine".
  */
 export function planBinUpdates(
 	bins: ResolvedBin[],
-	checks: BinCheckResult[],
+	facts: readonly ToolFacts[],
 ): BinUpdateItem[] {
-	const present = new Map(checks.map((c) => [c.name, c.present]));
+	const byName = new Map(facts.map((f) => [f.name, f]));
 	return bins.map((bin) => {
+		const f = byName.get(bin.name);
+		const status: ToolStatus = f
+			? classifyTool(bin, f)
+			: {
+					name: bin.name,
+					state: "unknown",
+					reason: "not-probed",
+					note: "not probed",
+					installed: null,
+					latest: null,
+					target: null,
+				};
 		const item: BinUpdateItem = {
 			name: bin.name,
+			action: status.state,
+			reason: status.reason,
+			installed: status.installed,
+			latest: status.latest,
+			target: status.target,
 			sources: bin.sources,
-			action: !present.get(bin.name)
-				? "install"
-				: bin.version
-					? "current"
-					: "upgrade",
 		};
+		if (status.note) item.note = status.note;
+		if (status.adopted) item.adopted = status.adopted;
 		if (bin.version) item.version = bin.version;
 		return item;
 	});
 }
 
+/**
+ * Whether a bin item is WORK: an install or an upgrade.
+ *
+ * The one predicate `applyBins`, `planWorkItems` and `planHasWork` share. The
+ * apply loop used to skip only `current` and run everything else, so the day an
+ * `unknown` existed it would have been applied — "cannot tell" executed as an
+ * upgrade. One predicate means the three cannot disagree about that.
+ */
+export function binNeedsWork(item: BinUpdateItem): boolean {
+	return item.action === "install" || item.action === "upgrade";
+}
+
 // ── Skills ───────────────────────────────────────────────────────────────────
 
 export interface SkillUpdateItem {
@@ -329,7 +786,7 @@ export interface UpdatePlan {
 export function planHasWork(plan: UpdatePlan): boolean {
 	return (
 		plan.plugins.some((p) => p.action !== "current") ||
-		plan.bins.some((b) => b.action !== "current") ||
+		plan.bins.some(binNeedsWork) ||
 		plan.skills.length > 0
 	);
 }
@@ -338,24 +795,41 @@ export function planHasWork(plan: UpdatePlan): boolean {
  * True when something is actually MISSING or KNOWN TO BE BEHIND. This is what
  * `--check` gates on, and it is deliberately narrower than {@link planHasWork}.
  *
- * The distinction exists because two kinds of item are re-run every time
- * without that meaning anything is wrong:
- * - a skill, whose manifest ref carries no content hash, so it is re-fetched
- *   rather than compared;
- * - an unpinned binary, for which there is no version probe at all, only
- *   present/absent.
+ * The distinction exists because a skill is re-run every time without that
+ * meaning anything is wrong: its manifest ref carries no content hash, so it is
+ * re-fetched rather than compared. Counting that as drift made `--check` exit 1
+ * forever for any profile that declared a single skill — a gate that can never
+ * pass tells you nothing, and would have been switched off in CI within a week.
  *
- * Counting those as drift made `--check` exit 1 forever for any profile that
- * declared a single skill — a gate that can never pass tells you nothing, and
- * would have been switched off in CI within a week.
+ * A bin `upgrade` DOES count now. It used to be excluded because an unpinned
+ * binary had no version probe and "upgrade" meant "re-run the installer"; it
+ * now means the owning installer says the tool is behind, which is drift.
  *
- * `unknown` DOES count: an unverifiable plugin is exactly what a gate must not
- * wave through.
+ * NEITHER an `unknown` plugin NOR an `unknown` tool counts. "We could not check
+ * this" is not evidence of drift, and most unknowns are structural and
+ * permanent rather than transient: a plugin whose marketplace publishes no
+ * version (278 of the official ones), a tool on PATH but installed by a
+ * different npm, `go` absent, a private registry. A gate that exits 1 on those
+ * can never pass, so it protects nothing and is switched off. The cost is that
+ * an item whose check merely FAILED this run — a rate-limited catalog fetch, a
+ * timed-out probe — also passes, so the exit code alone must never be read as
+ * "everything verified": the caller prints how many items went unchecked
+ * (`summarizePlan`'s `unknownPlugins`/`unknownTools`, rendered by
+ * `cli/update-view.ts`), and every unknown row carries its own reason above.
+ *
+ * Both unknowns are listed positively rather than as `!== "current"`, so a new
+ * action has to be classified here deliberately instead of defaulting into the
+ * gate.
  */
 export function planIsBehind(plan: UpdatePlan): boolean {
 	return (
-		plan.plugins.some((p) => p.action !== "current") ||
-		plan.bins.some((b) => b.action === "install") ||
+		plan.plugins.some(
+			(p) =>
+				p.action === "install" ||
+				p.action === "update" ||
+				p.action === "repair",
+		) ||
+		plan.bins.some((b) => b.action === "install" || b.action === "upgrade") ||
 		plan.skills.some((s) => s.action === "install")
 	);
 }
@@ -366,18 +840,24 @@ export function summarizePlan(plan: UpdatePlan): {
 	updated: number;
 	repaired: number;
 	current: number;
+	/** unknownPlugins + unknownTools. */
 	unknown: number;
+	unknownPlugins: number;
+	unknownTools: number;
 } {
 	const count = (a: PluginUpdateAction) =>
 		plan.plugins.filter((p) => p.action === a).length;
+	const bins = (a: BinUpdateAction) =>
+		plan.bins.filter((b) => b.action === a).length;
+	const unknownPlugins = count("unknown");
+	const unknownTools = bins("unknown");
 	return {
-		installed:
-			count("install") + plan.bins.filter((b) => b.action === "install").length,
-		updated:
-			count("update") + plan.bins.filter((b) => b.action === "upgrade").length,
+		installed: count("install") + bins("install"),
+		updated: count("update") + bins("upgrade"),
 		repaired: count("repair"),
-		current:
-			count("current") + plan.bins.filter((b) => b.action === "current").length,
-		unknown: count("unknown"),
+		current: count("current") + bins("current"),
+		unknown: unknownPlugins + unknownTools,
+		unknownPlugins,
+		unknownTools,
 	};
 }