magus-cli 7.2.0 → 7.3.1

package/src/services/update-plan.ts

@@ -34,6 +34,7 @@ import {
 	type PluginInfo,
 	compareVersions,
 	isBehind,
+	isRepairablyBehind,
 } from "./plugin-manager.js";
 import {
 	type ToolFacts,
@@ -54,6 +55,23 @@ export type PluginUpdateAction =
 	| "repair"
 	/** Already on the right version. */
 	| "current"
+	/**
+	 * BROKEN: the right version is installed, but Claude Code's loader will
+	 * resolve an OLDER one — so the session runs stale code while every version
+	 * magus records looks correct.
+	 *
+	 * A REINSTALL DOES NOT FIX IT (measured). `claude plugin install` writes a
+	 * row for this project, and the row that wins belongs to another one — often
+	 * a worktree that no longer exists, whose registry entry nothing prunes.
+	 *
+	 * It IS applied, by `repairStaleLoad` (services/claude-settings.ts), which
+	 * moves those rows forward onto the installed version rather than reinstalling
+	 * anything. `target` is therefore the version installed here — the one whose
+	 * cache directory exists — and not what the catalog offers. `scopes` stays
+	 * empty because this is not a per-scope install: one registry rewrite covers
+	 * every row, whichever scope or project each belongs to.
+	 */
+	| "stale-load"
 	/** The catalog check failed; we cannot claim either way. */
 	| "unknown";
 
@@ -78,6 +96,8 @@ export type PluginReason =
 	| "content-stale"
 	/** update: a scope is provably behind. */
 	| "behind"
+	/** stale-load: the loader resolves an older version than the one installed. */
+	| "older-version-loads"
 	/** current|update: an exact pin differs from what the marketplace offers. */
 	| "pin-undeliverable"
 	/** current: every installed scope is at (or ahead of) the target. */
@@ -89,6 +109,16 @@ export interface PluginUpdateItem {
 	pinned: string;
 	/** Highest version installed in any scope, or null when absent. */
 	installed: string | null;
+	/**
+	 * The version Claude Code's loader will ACTUALLY load in this project, or
+	 * null when it will load nothing (and when the registry was unreadable).
+	 *
+	 * A separate column from `installed` because they answer different questions
+	 * and routinely disagree — see services/plugin-resolution.ts. `installed` is
+	 * what the settings file and this project's registry rows record; `loaded` is
+	 * what runs.
+	 */
+	loaded: string | null;
 	/** Version the marketplace catalog offers, or null when unknown. */
 	available: string | null;
 	/** Version this item would move to. Null for `current`/`unknown`. */
@@ -142,6 +172,40 @@ function highestInstalled(info: PluginInfo | undefined): string | null {
 	);
 }
 
+/**
+ * The highest installed version THE PIN PERMITS — the ceiling a stale-load
+ * repair may aim at. Null when no installed version qualifies.
+ *
+ * Under "latest" that is simply {@link highestInstalled}: nothing caps it, and
+ * the newest version on this machine is the one to converge on.
+ *
+ * Under an EXACT pin it is the highest installed version at or below the pin.
+ * `installed` reaches across every scope and `scopesNeeding` never downgrades, so
+ * a scope sitting above an exact pin is a normal, permanent state — not something
+ * to plan toward. Comparing the stale-load branch against the uncapped
+ * `installed` made a plugin loading exactly its pinned version read as BROKEN,
+ * and the repair then moved the pinned rows off the pin.
+ *
+ * A version that cannot be ORDERED against the pin (a commit sha, the literal
+ * "unknown") is excluded rather than assumed to qualify: "cannot tell" must never
+ * license a registry rewrite, which is the same rule {@link isRepairablyBehind}
+ * applies one step later.
+ */
+function highestPermittedInstalled(
+	info: PluginInfo | undefined,
+	pin: string,
+): string | null {
+	if (pin === "latest") return highestInstalled(info);
+	const permitted = scopeVersions(info)
+		.map(([, v]) => v)
+		// pin >= v, i.e. v is at or below the pin. Null (unorderable) fails this.
+		.filter((v) => (compareVersions(pin, v) ?? -1) >= 0);
+	if (permitted.length === 0) return null;
+	return permitted.reduce((a, b) =>
+		(compareVersions(a, b) ?? -1) >= 0 ? a : b,
+	);
+}
+
 /**
  * Scopes that are strictly BEHIND `target`.
  *
@@ -277,6 +341,7 @@ export function classifyPlugin(
 		pluginId,
 		pinned: pin,
 		installed,
+		loaded: info?.loadedVersion ?? null,
 		available,
 		beforeVersions: Object.fromEntries(scopeVersions(info)) as Partial<
 			Record<PluginScope, string>
@@ -375,6 +440,112 @@ export function classifyPlugin(
 		};
 	}
 
+	// Installed and listed — but the loader will resolve an OLDER version than
+	// what is installed here, so this session runs stale code.
+	//
+	// Decided BEFORE every branch below, and that ordering is the whole fix.
+	// Those branches compare the REGISTERED version against the catalog, and the
+	// registered version is precisely the one that is not loading: a plugin at
+	// the newest version in every scope classified `current` while Claude Code
+	// loaded a two-versions-old copy. The report was green about code that was
+	// not running — which is worse than no report, because magus is the tool
+	// relied on to stay current.
+	//
+	// `loaded` is the loader's own answer (services/plugin-resolution.ts), not
+	// magus's registry resolution. Null means we could not establish it, and
+	// "cannot tell" never becomes a finding here — the plugin falls through to
+	// the ordinary comparisons below.
+	//
+	// `target` is what is INSTALLED here, never `available`. The repair points
+	// registry rows at a cache directory, and only the installed version's cache
+	// is on disk — aiming at the catalog version would name a directory that does
+	// not exist, which `repairStaleLoad` refuses. When the install is also behind
+	// the catalog, the next run plans the ordinary `update` on top, so the two
+	// steps converge instead of competing.
+	//
+	// `scopes` stays empty: one registry rewrite covers every row, so there is no
+	// per-scope work to enumerate. `pluginNeedsWork` says so directly.
+	//
+	// `isRepairablyBehind`, NOT `isBehind` — the one predicate `findStaleLoads`
+	// asks too, so this header's count and the startup popup's count are the same
+	// question. `isBehind` calls two differing commit shas "behind", which is the
+	// right answer to ITS question and the wrong one to this: moving rows forward
+	// between two unordered shas is a guess, not a repair. That difference alone
+	// made the popup claim 8 broken plugins where this header said 6.
+	//
+	// INSTALLED against LOADED — never `available` against loaded. This state is
+	// "what is installed HERE is not what runs here", and the catalog is not a
+	// party to it. Asking the catalog question here was wrong in both directions,
+	// measured against this module:
+	//
+	//  - installed 7.1.0, loaded 7.1.0, catalog 7.2.0 — an ordinary pending
+	//    release, nothing stale at all — classified `stale-load` with an empty
+	//    `scopes`, so no installer ran, `repairStaleLoad` found no row behind
+	//    7.1.0, wrote nothing, and its post-write assertion passed because the
+	//    loader already resolved 7.1.0. The engine counted that as a success and
+	//    7.2.0 was never installed. Every run classified identically while
+	//    `planIsBehind` stayed true, so `magus update --check` failed forever over
+	//    something `magus update` could not clear — the un-greenable gate the note
+	//    on `planIsBehind` argues must not exist. It fired on any machine with a
+	//    pending release, which is the normal state for this marketplace.
+	//  - a marketplace publishing NO version (278 of the 292 official plugins)
+	//    leaves `available` null, so `isRepairablyBehind` answered false and a
+	//    genuine stale load classified `current` — green about a session running
+	//    old code, the exact defect this state exists to end.
+	//
+	// The two formulas agree whenever `available` equals `installed`, which is
+	// every machine with nothing pending — which is why it held up by hand and why
+	// the parity fixture in stale-load-repair.test.ts had to be changed to be able
+	// to fail at all.
+	//
+	// BOTH AT ONCE — stale-loaded AND behind the catalog — is deliberately NOT
+	// folded together, and neither fact is dropped. This branch wins (what runs is
+	// the more consequential fact, and a reinstall is measured not to clear it),
+	// `target` stays an installed version because only an installed version's cache
+	// directory exists, and the pending catalog version is named in the note rather
+	// than left for the user to infer from a column. `magus update` then converges
+	// over consecutive runs: repair the load, then install the update once the load
+	// is no longer stale. It is not collapsed into one run because the two are
+	// different mechanisms — a registry rewrite and an installer — and the apply
+	// engine runs one action per item; interleaving them silently would make a
+	// failed half look like a whole success.
+	//
+	// CAPPED AT THE PIN, which is why the comparison is against `staleTarget` and
+	// not `installed`. `installed` is the highest version in ANY scope, and
+	// `scopesNeeding` deliberately never downgrades, so a scope legitimately sits
+	// ABOVE an exact pin. Measured: pin 0.3.0, project scope at 0.3.0 and loading,
+	// user scope at 0.5.0 — `installed` is 0.5.0, so an uncapped comparison called
+	// a plugin loading exactly what its pin asked for a broken load, and the repair
+	// then succeeded (this repo's row is writable, and 0.5.0's cache exists because
+	// user scope installed it), moving a pinned plugin off its pin and reporting
+	// success. An exact pin is a request, not a starting point: this branch may
+	// never plan past it, for the same reason the pin branch below refuses to plan
+	// toward something the marketplace cannot deliver.
+	//
+	// A pin naming a version installed NOWHERE at or below it leaves `staleTarget`
+	// null and the branch silent. That is the honest answer rather than a quiet
+	// promotion: the only versions on disk are above the pin, so there is no repair
+	// this may perform, and the pin branch below reports the pin state instead.
+	const staleTarget = highestPermittedInstalled(info, pin);
+	if (isRepairablyBehind(staleTarget, base.loaded)) {
+		// Only ever under "latest". Under an exact pin the catalog is not what this
+		// plugin is judged against, so naming a newer published version as something
+		// "available once the load is repaired" would advertise a move the pin
+		// forbids.
+		const pending =
+			pin === "latest" && isRepairablyBehind(available, installed);
+		return {
+			...base,
+			target: staleTarget,
+			action: "stale-load",
+			reason: "older-version-loads",
+			scopes: [],
+			note: pending
+				? `loads v${base.loaded}, installed v${staleTarget}; v${available} is available once the load is repaired`
+				: `loads v${base.loaded}, installed v${staleTarget}`,
+		};
+	}
+
 	// An exact pin is planned against what can ACTUALLY be delivered.
 	//
 	// This is dependency management, not a package manager: there is no
@@ -563,6 +734,12 @@ export interface PluginStateCounts {
 	update: number;
 	repair: number;
 	current: number;
+	/**
+	 * Its own count, never folded into `current`. The installed version being
+	 * right is exactly what makes this state dangerous: counted as current, the
+	 * header would report a clean bill of health for a session running old code.
+	 */
+	"stale-load": number;
 	unknown: number;
 }
 
@@ -575,6 +752,7 @@ export function countPluginStates(
 		update: 0,
 		repair: 0,
 		current: 0,
+		"stale-load": 0,
 		unknown: 0,
 	};
 	for (const item of items) counts[item.action]++;
@@ -762,6 +940,14 @@ export function planHasWork(plan: UpdatePlan): boolean {
  * 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.
  *
+ * A `stale-load` plugin DOES count. It was excluded while it was report-only, on
+ * the un-greenable-gate argument above: nothing magus ran could clear it, so a
+ * gate that failed on it would have failed forever. `repairStaleLoad` clears it
+ * now, and `magus update` applies that, so the gate closes — and leaving it out
+ * would mean `--check` printing "nothing behind" over a plugin whose session
+ * loads a version nobody installed, which is the deception the state exists to
+ * end.
+ *
  * 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
@@ -784,7 +970,8 @@ export function planIsBehind(plan: UpdatePlan): boolean {
 			(p) =>
 				p.action === "install" ||
 				p.action === "update" ||
-				p.action === "repair",
+				p.action === "repair" ||
+				p.action === "stale-load",
 		) ||
 		plan.bins.some((b) => b.action === "install" || b.action === "upgrade") ||
 		plan.skills.some((s) => s.action === "install")

package/src/services/version-check.ts

@@ -1,5 +1,6 @@
 import semver from "semver";
 import pkg from "../../package.json";
+import { MAGUS_NPM_PACKAGE } from "../data/npm-package.js";
 
 // Cache the result for the session
 let cachedResult: VersionCheckResult | null = null;
@@ -29,15 +30,20 @@ async function fetchLatestVersion(): Promise<string | null> {
 		const controller = new AbortController();
 		const timeout = setTimeout(() => controller.abort(), 3000); // 3s timeout
 
-		const response = await fetch("https://registry.npmjs.org/magus/latest", {
-			signal: controller.signal,
-			headers: {
-				Accept: "application/json",
-				// Always revalidate — a CDN/HTTP-cached response serves a stale
-				// "latest" right after a release (the 4.25-vs-4.26 flicker).
-				"Cache-Control": "no-cache",
+		// The npm package, not the command: bare `magus` on npm is an unrelated
+		// package whose latest is 0.0.2, which hid every release from this check.
+		const response = await fetch(
+			`https://registry.npmjs.org/${MAGUS_NPM_PACKAGE}/latest`,
+			{
+				signal: controller.signal,
+				headers: {
+					Accept: "application/json",
+					// Always revalidate — a CDN/HTTP-cached response serves a stale
+					// "latest" right after a release (the 4.25-vs-4.26 flicker).
+					"Cache-Control": "no-cache",
+				},
 			},
-		});
+		);
 
 		clearTimeout(timeout);
 
@@ -117,11 +123,15 @@ export async function checkForUpdates(
 }
 
 /**
- * Format update message for display
+ * Format update message for display.
+ *
+ * Points at `magus upgrade`, which picks bun or npm from the active binary. A
+ * hard-coded `npm i -g …` would give every bun user a second, npm-owned copy —
+ * the duplicate state `magus upgrade` itself warns about.
  */
 export function formatUpdateMessage(result: VersionCheckResult): string {
 	if (!result.updateAvailable) return "";
 
 	const typeLabel = result.updateType ? ` (${result.updateType})` : "";
-	return `Update available: v${result.currentVersion} → v${result.latestVersion}${typeLabel}. Run: npm i -g magus-cli`;
+	return `Update available: v${result.currentVersion} → v${result.latestVersion}${typeLabel}. Run: magus upgrade`;
 }

package/src/ui/App.tsx

@@ -1,10 +1,13 @@
 import fs from "node:fs";
 import { useRenderer } from "@opentui/react";
 import React, { useEffect, useState } from "react";
+import { activePluginPins } from "../services/active-closure.js";
 import { isClaudeAvailable } from "../services/claude-cli.js";
 import {
+	findStaleLoads,
 	migrateMarketplaceRename,
 	recoverMarketplaceSettings,
+	repairAllStaleLoads,
 } from "../services/claude-settings.js";
 import { checkGitignore } from "../services/gitignore-check.js";
 import {
@@ -28,6 +31,10 @@ import { ModalContainer } from "./components/modals/index.js";
 import { useGitignoreModal } from "./hooks/useGitignoreModal.js";
 import { useKeyboardHandler } from "./hooks/useKeyboardHandler.js";
 import { useProfileStartupModal } from "./hooks/useProfileStartupModal.js";
+import {
+	staleLoadRepairSummary,
+	useStaleLoadModal,
+} from "./hooks/useStaleLoadModal.js";
 import {
 	AliasScreen,
 	CliToolsScreen,
@@ -391,6 +398,10 @@ function AppContent({ onExit }: AppContentProps) {
 		null,
 	);
 	const gitignoreModal = useGitignoreModal();
+	const [brokenPluginCount, setBrokenPluginCount] = useState<number | null>(
+		null,
+	);
+	const staleLoadModal = useStaleLoadModal();
 	// The profile modal cannot be dismissed, so it needs the app's own exit: its
 	// only non-action is to leave.
 	const profileModal = useProfileStartupModal(onExit);
@@ -436,6 +447,58 @@ function AppContent({ onExit }: AppContentProps) {
 		setGitignoreData(null);
 	}, [gitignoreData, gitignoreModal, state.modal, state.projectPath]);
 
+	// Show the broken-plugin modal — same "wait for the modal slot" rule as the
+	// gitignore one above, so two startup findings queue instead of one stomping
+	// the other.
+	useEffect(() => {
+		if (brokenPluginCount === null) return;
+		if (state.modal) return;
+		staleLoadModal.show({
+			brokenCount: brokenPluginCount,
+			// Re-surveys before repairing, like the gitignore fixer: the registry may
+			// have moved between the startup scan and the user pressing Enter, and
+			// repairing from the stale count would act on rows that are no longer
+			// there. `repairAllStaleLoads` is the same `repairStaleLoad` the Plugins
+			// screen's `a` key drives through the apply engine.
+			//
+			// The pins are re-read with it, from the same helper the survey used: a
+			// repair that capped at a different ceiling than the offer was counted
+			// against would move rows the dialog never mentioned.
+			onFix: async () =>
+				staleLoadRepairSummary(
+					await repairAllStaleLoads(
+						state.projectPath,
+						undefined,
+						await activePluginPins(state.projectPath),
+					),
+				),
+		});
+		setBrokenPluginCount(null);
+	}, [brokenPluginCount, staleLoadModal, state.modal, state.projectPath]);
+
+	// Does this project load an older plugin than it installed? Detection only;
+	// nothing is written until the user chooses Fix.
+	//
+	// Its own effect for the same reason the profile check below has one: the
+	// marketplace block returns early on `--no-refresh`, which is about network
+	// calls, and this question is answered from the local registry alone. Sharing
+	// that effect let the flag silently disable the check — observed, while this
+	// was still inside it.
+	useEffect(() => {
+		(async () => {
+			try {
+				const broken = await findStaleLoads(
+					process.cwd(),
+					undefined,
+					await activePluginPins(process.cwd()),
+				);
+				if (broken.length > 0) setBrokenPluginCount(broken.length);
+			} catch {
+				// non-fatal: the Plugins tab still shows the same rows
+			}
+		})();
+	}, []);
+
 	// Show the profile modal on the same terms as the gitignore one: only once
 	// the modal slot is free, so two startup checks that both found something do
 	// not stomp on each other. Gitignore is asked first simply because its

package/src/ui/hooks/useStaleLoadModal.ts

@@ -0,0 +1,157 @@
+import { useCallback } from "react";
+import { useApp, useNavigation } from "../state/AppContext.js";
+import type { ModalState } from "../state/types.js";
+
+/**
+ * Startup broken-plugin modal: magus launches, finds that Claude Code will load
+ * an older version of a plugin than the one installed here, and offers to fix it.
+ *
+ * Same shape as the gitignore modal beside it — a startup repair magus can make
+ * without being asked to, surfaced as a choice rather than done silently. The
+ * difference is the DEFAULT: fixing is the first option and `defaultIndex` says
+ * so explicitly, because a broken plugin means every session in this directory
+ * runs code nobody installed, and there is no reason to prefer leaving it.
+ *
+ * The copy names the CAUSE, not magus's internal state. An earlier version read
+ * "Claude Code loads an older version here than the one installed", which is a
+ * report on two stores disagreeing and leaves the reader with nothing to do. It
+ * is a defect in Claude Code's plugin loader, the user did nothing to cause it,
+ * and the sentence they need is what is wrong and how far it reaches.
+ *
+ * Keep it plain and keep it accurate. A draft said "your sessions run code you
+ * did not install", which is both overstated and wrong: nothing happens to the
+ * user's code, an old cached plugin version is used instead of the current one.
+ * Say that, in those words.
+ *
+ * The reach is not this directory. Relevance is decided by repository root, so
+ * every worktree of this repo — and the main checkout — resolve identically and
+ * are affected together. Saying "in this directory" understated it.
+ *
+ * NO UPSTREAM LINK YET, deliberately. anthropics/claude-code#45997 is the
+ * nearest issue and is CLOSED, and its title states the `[0]`-index diagnosis,
+ * which measurement disproved: the loader filters by repository root first and
+ * takes the first RELEVANT row. Linking a closed issue with a wrong cause sends
+ * the reader somewhere that contradicts this dialog. Add a link here when an
+ * accurate issue exists.
+ *
+ * Pure builder is exported separately for tests.
+ */
+
+export interface BuildStaleLoadModalArgs {
+	brokenCount: number;
+	onFix: () => void;
+	onOpenTab: () => void;
+	onDismiss: () => void;
+}
+
+export function buildStaleLoadModal(args: BuildStaleLoadModalArgs): ModalState {
+	const { brokenCount, onFix, onOpenTab, onDismiss } = args;
+	const plural = brokenCount === 1 ? "plugin" : "plugins";
+	return {
+		type: "select",
+		title: "Claude Code is loading old plugin versions",
+		message: `It picks up a stale cached version — the one recorded by another directory in this repo, including worktrees you deleted. ${brokenCount} ${plural} ${brokenCount === 1 ? "is" : "are"} on an older version than you installed, in every worktree and the main checkout.\n\nFix updates this repo's install records to the versions you installed. installed_plugins.json is backed up first. Nothing is deleted or downgraded.`,
+		options: [
+			{ label: `Fix it (${brokenCount} ${plural})`, value: "fix" },
+			{ label: "Open the Plugins tab to review", value: "open-tab" },
+			{ label: "Not now", value: "dismiss" },
+		],
+		// FIX, stated rather than inherited from being first — a reordering must not
+		// silently make "leave it broken" the thing Enter does.
+		defaultIndex: 0,
+		onSelect: (value: string) => {
+			if (value === "fix") onFix();
+			else if (value === "open-tab") onOpenTab();
+			else onDismiss();
+		},
+		onCancel: onDismiss,
+	};
+}
+
+export function useStaleLoadModal() {
+	const { dispatch } = useApp();
+	const { navigateToScreen } = useNavigation();
+
+	const show = useCallback(
+		(args: {
+			brokenCount: number;
+			/** Runs the repair. Resolves to what to tell the user afterwards. */
+			onFix: () => Promise<string> | string;
+		}) => {
+			if (args.brokenCount === 0) return;
+			const dismiss = () => dispatch({ type: "HIDE_MODAL" });
+			const modal = buildStaleLoadModal({
+				brokenCount: args.brokenCount,
+				onFix: () => {
+					dispatch({
+						type: "SHOW_MODAL",
+						modal: { type: "loading", message: "Repairing plugins…" },
+					});
+					// The outcome is REPORTED, never assumed. `repairStaleLoad` re-asks
+					// the loader after writing and can legitimately answer "still not
+					// loading the target"; swallowing that would leave the user believing
+					// a broken plugin was fixed.
+					void Promise.resolve(args.onFix())
+						.then((summary) => {
+							dispatch({
+								type: "SHOW_MODAL",
+								modal: {
+									type: "message",
+									title: "Plugin repair",
+									message: summary,
+									variant: "info",
+									onDismiss: dismiss,
+								},
+							});
+						})
+						.catch((err) => {
+							dispatch({
+								type: "SHOW_MODAL",
+								modal: {
+									type: "message",
+									title: "Plugin repair failed",
+									message: err instanceof Error ? err.message : String(err),
+									variant: "error",
+									onDismiss: dismiss,
+								},
+							});
+						});
+				},
+				onOpenTab: () => {
+					dispatch({ type: "HIDE_MODAL" });
+					navigateToScreen("plugins");
+				},
+				onDismiss: dismiss,
+			});
+			dispatch({ type: "SHOW_MODAL", modal });
+		},
+		[dispatch, navigateToScreen],
+	);
+
+	return { show };
+}
+
+/**
+ * One line per repair attempt, for the modal that follows the fix.
+ *
+ * Exported and pure so the wording is tested rather than inspected by eye. Each
+ * line says what the loader resolves NOW, because that — not the row count — is
+ * the thing the user came here to change.
+ */
+export function staleLoadRepairSummary(
+	results: ReadonlyArray<{
+		pluginId: string;
+		target: string;
+		ok: boolean;
+		error?: string;
+	}>,
+): string {
+	if (results.length === 0) return "Nothing to repair.";
+	return results
+		.map((r) =>
+			r.ok
+				? `✓ ${r.pluginId} now loads v${r.target}`
+				: `✗ ${r.pluginId} — ${r.error ?? "repair did not take effect"}`,
+		)
+		.join("\n");
+}

package/src/ui/renderers/pluginRenderers.tsx

@@ -278,6 +278,9 @@ const ACTION_LABEL: Record<PluginUpdateAction, string> = {
 	update: "UPDATE AVAILABLE",
 	repair: "NEEDS REINSTALL",
 	current: "UP TO DATE",
+	// The DETAIL panel's label, not the row's — this is where the mechanism is
+	// allowed to be named, and the note beside it spells out both versions.
+	"stale-load": "BROKEN — OLDER VERSION LOADS",
 	unknown: "UNKNOWN",
 };
 
@@ -463,6 +466,32 @@ function pluginDetail(
 					</text>
 				</box>
 			) : null}
+			{/*
+			 * THE panel where the mechanism is spelled out in full. The row above
+			 * says only "BROKEN — press a to fix", on purpose; a reader who wants to
+			 * know why comes here, so this names both versions, says which registry
+			 * row wins, and says what the fix does. A reinstall is measured NOT to
+			 * fix it — it writes another row for this project while the winner
+			 * belongs to a different one — so the fix rewrites those rows instead.
+			 */}
+			{status?.action === "stale-load" ? (
+				<box flexDirection="column">
+					<text fg={theme.colors.danger}>
+						✗ Broken: Claude Code loads v{status.loaded ?? "?"} in this
+						directory, not the v{status.installed ?? "?"} that is installed.
+					</text>
+					<text fg={theme.colors.muted}>
+						An install row belonging to another directory in this repository —
+						often a worktree that no longer exists — is resolved first. `magus
+						doctor` names which one.
+					</text>
+					<text fg={theme.colors.muted}>
+						Press a to fix: magus moves those rows forward to v
+						{status.target ?? status.installed ?? "?"}, backing up
+						installed_plugins.json first. Nothing is deleted or downgraded.
+					</text>
+				</box>
+			) : null}
 
 			{/* Description */}
 			<box marginTop={1} marginBottom={1}>

package/src/ui/renderers/pluginStatusText.ts

@@ -41,6 +41,20 @@ export function pluginStatusText(
 			};
 		case "repair":
 			return { suffix: ` stale — reinstall${withNote}`, tone: "warning" };
+		case "stale-load":
+			// NO VERSIONS, and the note is deliberately not shown. This row used to
+			// print the classifier's note verbatim — "≠ loads v0.3.0, installed
+			// v0.5.0" — which is internal vocabulary: it tells a reader neither what
+			// is wrong nor what to do, because "loads" versus "installed" is a
+			// distinction only this codebase draws. The row's job is the verdict and
+			// the key; the mechanism, including which project's registry row wins,
+			// belongs in the detail panel, which is where someone curious looks.
+			//
+			// Red, not the amber it carried while this was report-only. Amber is
+			// this file's tone for "cannot tell" and for routine work; a plugin
+			// whose session runs a version nobody installed is broken, and there is
+			// now a key that fixes it.
+			return { suffix: " BROKEN — press a to fix", tone: "danger" };
 		case "install":
 			// `absent` only ever comes from a profile pin (see `pinForRow`), so it
 			// may say so. An undeclared row that is merely enabled must not.