magus-cli 7.2.0 → 7.3.0

package/src/services/claude-settings.ts

@@ -14,6 +14,20 @@ import type {
 import { parsePluginId } from "../utils/string-utils.js";
 import { repoHeadSha } from "./content-drift.js";
 import { inheritablePaths } from "./git-worktree.js";
+// `isRepairablyBehind` is the ONE predicate behind the `stale-load` state, shared
+// with the classifier so the popup and the Plugins header cannot count different
+// plugins — see the notes on it and on `findStaleLoads`. plugin-manager imports
+// this module in turn; the cycle is binding-only (neither module calls the other
+// at evaluation time), so both resolve whichever is loaded second against a live,
+// hoisted function.
+import { compareVersions, isRepairablyBehind } from "./plugin-manager.js";
+import {
+	type RepoRootCache,
+	isMachineWideScope,
+	isRelevantInstallation,
+	pickLoadedEntry,
+	repoRootForPath,
+} from "./plugin-resolution.js";
 
 const CLAUDE_DIR = ".claude";
 const SETTINGS_FILE = "settings.json";
@@ -790,8 +804,18 @@ export async function discoverAllGlobalMarketplaces(): Promise<
 // os.homedir() in a module-level constant makes the path capture whatever
 // HOME was set to when this module was first imported, which is fragile
 // (import-order-dependent) and breaks any caller that changes HOME afterward.
-const installedPluginsFile = (): string =>
-	path.join(os.homedir(), ".claude", "plugins", "installed_plugins.json");
+/**
+ * `~/.claude/plugins` — the directory holding BOTH the registry and the plugin
+ * cache. The two are derived from one root rather than spelled out twice, so a
+ * caller that needs to point the pair somewhere else (a test, above all) moves
+ * one argument and cannot land the registry in a temp directory while the cache
+ * path it writes still names the operator's real home.
+ */
+export const pluginsDir = (): string =>
+	path.join(os.homedir(), ".claude", "plugins");
+
+const installedPluginsFile = (root: string = pluginsDir()): string =>
+	path.join(root, "installed_plugins.json");
 
 const knownMarketplacesFile = (): string =>
 	path.join(os.homedir(), ".claude", "plugins", "known_marketplaces.json");
@@ -1393,62 +1417,201 @@ export async function resolveCacheProvenance(
 
 /**
  * Read installed_plugins.json registry
+ *
+ * @param root the plugins directory to read from — see {@link pluginsDir}
  */
-export async function readInstalledPluginsRegistry(): Promise<InstalledPluginsRegistry> {
-	try {
-		if (await fs.pathExists(installedPluginsFile())) {
-			const content = await fs.readJson(installedPluginsFile());
-			// Validate structure
-			if (!content.version || !content.plugins) {
-				throw new Error("Invalid registry structure");
-			}
-			return content;
-		}
-	} catch (error) {
-		// Backup corrupted file
-		if (await fs.pathExists(installedPluginsFile())) {
-			try {
-				const backup = `${installedPluginsFile()}.backup.${Date.now()}`;
-				await fs.copy(installedPluginsFile(), backup);
-				console.warn(`Corrupted registry backed up to: ${backup}`);
-			} catch {
-				// Ignore backup errors
-			}
+export async function readInstalledPluginsRegistry(
+	root: string = pluginsDir(),
+): Promise<InstalledPluginsRegistry> {
+	const file = installedPluginsFile(root);
+	const raw = await readRegistryBytes(file);
+	const parsed = parseRegistryBytes(raw);
+	if (parsed) return parsed;
+	if (raw !== null) {
+		// Corrupt rather than absent — keep a copy before any caller writes over it.
+		try {
+			const backup = await registryBackupPath(file, "corrupt");
+			await fs.copy(file, backup);
+			console.warn(`Corrupted registry backed up to: ${backup}`);
+		} catch {
+			// Ignore backup errors
 		}
 	}
 	return { version: 2, plugins: {} };
 }
 
 /**
- * Write installed_plugins.json registry
+ * The registry file's exact bytes, or null when it is not there.
+ *
+ * Separate from the parse so a caller can hold what it read and hand it back as
+ * a write PRECONDITION — see {@link writeInstalledPluginsRegistry}. Parsing from
+ * those same bytes, rather than re-reading the file, is what makes the
+ * precondition mean anything: a snapshot parsed from a second read would already
+ * be a different document than the one the precondition names.
+ */
+async function readRegistryBytes(file: string): Promise<string | null> {
+	try {
+		return await fs.readFile(file, "utf8");
+	} catch {
+		return null;
+	}
+}
+
+/** Parse + structure check. Null means "not a registry", including absent. */
+function parseRegistryBytes(
+	raw: string | null,
+): InstalledPluginsRegistry | null {
+	if (raw === null) return null;
+	try {
+		const content = JSON.parse(raw);
+		if (!content?.version || !content?.plugins) return null;
+		return content as InstalledPluginsRegistry;
+	} catch {
+		return null;
+	}
+}
+
+/** How many `installed_plugins.json.backup.*` files are kept. */
+const MAX_REGISTRY_BACKUPS = 10;
+
+/**
+ * The one backup naming rule, so a reader can find every backup with one glob —
+ * and so that two backups taken in the same millisecond are two files.
+ *
+ * `Date.now()` alone was the name. Two repairs inside one millisecond produced
+ * the same path and `fs.copy` overwrote, which matters most in
+ * `repairAllStaleLoads`: the second backup is a copy of the file AFTER the first
+ * repair, so the surviving file no longer holds the pre-repair state of the
+ * first plugin — the undo for it was gone. A process-lifetime sequence number
+ * plus a label fixes the within-process case, and the existence loop covers two
+ * magus processes landing on the same millisecond.
+ *
+ * The timestamp stays FIRST so a plain name sort is chronological, which is what
+ * {@link pruneRegistryBackups} ranks by.
+ */
+let registryBackupSeq = 0;
+async function registryBackupPath(
+	file: string,
+	label: string,
+): Promise<string> {
+	const safe = label.replace(/[^A-Za-z0-9._-]+/g, "-");
+	const stamp = Date.now();
+	for (;;) {
+		// Fixed-width sequence: two backups in the same millisecond must still sort
+		// in the order they were taken, and "10" sorts before "2" otherwise.
+		const seq = String(registryBackupSeq++).padStart(3, "0");
+		const candidate = `${file}.backup.${stamp}.${seq}.${safe}`;
+		if (!(await fs.pathExists(candidate))) return candidate;
+	}
+}
+
+/**
+ * Keep the newest {@link MAX_REGISTRY_BACKUPS} backups and delete the rest.
+ *
+ * Nothing pruned these, so every repair left another copy of a multi-hundred-KB
+ * file in a directory magus does not own. Best-effort by design: a failure to
+ * delete an old copy must never turn into a failed repair.
+ */
+async function pruneRegistryBackups(file: string): Promise<void> {
+	try {
+		const dir = path.dirname(file);
+		const prefix = `${path.basename(file)}.backup.`;
+		const names = (await fs.readdir(dir))
+			.filter((n) => n.startsWith(prefix))
+			.sort();
+		for (const name of names.slice(0, -MAX_REGISTRY_BACKUPS)) {
+			await fs.remove(path.join(dir, name)).catch(() => {});
+		}
+	} catch {
+		// Best-effort.
+	}
+}
+
+/**
+ * A registry write was refused because the file changed after the caller read it.
+ *
+ * Its own type so a caller can tell a lost-update refusal from an IO failure and
+ * say which happened, rather than reporting "could not write" for both.
+ */
+export class RegistryChangedError extends Error {
+	constructor(readonly file: string) {
+		super(
+			`${file} changed on disk after it was read — another Claude Code session wrote it. Nothing was written; re-run to work from the current file.`,
+		);
+		this.name = "RegistryChangedError";
+	}
+}
+
+/**
+ * Write installed_plugins.json registry.
+ *
+ * ATOMIC — temp file in the same directory, then rename. This file is read by
+ * every Claude Code session on the machine, so a write interrupted partway
+ * leaves a truncated JSON document that `readInstalledPluginsRegistry` treats as
+ * corrupt and replaces with an EMPTY registry: every plugin on the machine
+ * reads as not installed. `rename(2)` within one directory cannot be observed
+ * half-done, so a reader sees either the old file or the new one.
+ *
+ * ATOMICITY IS NOT ISOLATION, and conflating the two is how this silently lost
+ * other sessions' work. A read-modify-write rewrites the WHOLE file from the
+ * snapshot the caller parsed, so a `claude plugin install` landing in between —
+ * for any plugin, in any project — is discarded by a write that is perfectly
+ * atomic. This repo's own note (`ai-docs/claude-code-plugin-resolution.md`)
+ * measured that file drifting across sessions inside minutes and losing 12 of
+ * 123 resolutions to it; dozens of sessions on one machine is the normal case.
+ *
+ * @param root the plugins directory to write to — see {@link pluginsDir}
+ * @param expectBytes the exact bytes the caller read, from
+ *   {@link readRegistryBytes} — `null` means "the file did not exist". Given
+ *   one, this compares it against the file as the LAST act before the rename and
+ *   throws {@link RegistryChangedError} rather than renaming over a newer
+ *   document. Omitted (`undefined`), there is no precondition and the write
+ *   clobbers, which is the old behaviour of every caller that has no snapshot to
+ *   offer.
+ *
+ *   It is a precondition, not a lock: the compare and the rename are two
+ *   syscalls, so a write landing between them is still lost. That window is
+ *   microseconds instead of the whole read-modify-write, and a loop that retried
+ *   until it won would be the other failure mode — an unbounded retry against a
+ *   file other processes write constantly. Refusing hands the decision back to
+ *   the caller, which is why the repair reports it instead of spinning.
  */
 export async function writeInstalledPluginsRegistry(
 	registry: InstalledPluginsRegistry,
+	root: string = pluginsDir(),
+	expectBytes?: string | null,
 ): Promise<void> {
-	await fs.ensureDir(path.dirname(installedPluginsFile()));
-	await fs.writeJson(installedPluginsFile(), registry, { spaces: 2 });
+	const file = installedPluginsFile(root);
+	await fs.ensureDir(path.dirname(file));
+	const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+	try {
+		await fs.writeJson(tmp, registry, { spaces: 2 });
+		if (expectBytes !== undefined) {
+			const current = await readRegistryBytes(file);
+			if (current !== expectBytes) throw new RegistryChangedError(file);
+		}
+		await fs.rename(tmp, file);
+	} catch (error) {
+		await fs.remove(tmp).catch(() => {});
+		throw error;
+	}
 }
 
 /**
  * Get install path for a plugin version in cache
+ *
+ * @param root the plugins directory the cache sits under — see {@link pluginsDir}
  */
 function getPluginCachePath(
 	pluginId: string,
 	version: string,
 	marketplace: string,
+	root: string = pluginsDir(),
 ): string {
 	const { pluginName } = parsePluginId(pluginId) || {
 		pluginName: pluginId.split("@")[0],
 	};
-	return path.join(
-		os.homedir(),
-		".claude",
-		"plugins",
-		"cache",
-		marketplace,
-		pluginName,
-		version,
-	);
+	return path.join(root, "cache", marketplace, pluginName, version);
 }
 
 /**
@@ -1562,3 +1725,451 @@ export async function removeFromInstalledPluginsRegistry(
 		);
 	}
 }
+
+// ── Stale-load repair ────────────────────────────────────────────────────────
+
+/**
+ * Rows {@link repairStaleLoad} is allowed to rewrite: THIS repository's own
+ * install records, and nothing else.
+ *
+ * Narrower than the loader's `isRelevantInstallation` in two deliberate ways, and
+ * the difference is the point — relevance is the LOADER's question, this is the
+ * WRITER's:
+ *
+ *  - A `user` or `managed` row is relevant to every project on the machine, so
+ *    rewriting one moves every project at once. Measured before this filter
+ *    existed: repairing one project moved a user-scope row installed from an
+ *    unrelated directory forward on its own, while the dialog the user consented
+ *    on said "Fix updates this repo's install records". A repair must not exceed
+ *    the reach it states, so those rows are never written here. When such a row is
+ *    the one that WINS, the repair refuses outright and names the scope — silently
+ *    rewriting nothing would be the worse answer of the two.
+ *  - A null repository root matches null in the loader (two rootless directories
+ *    are relevant to each other there, and this port now says so). It must not
+ *    match here: "the same repository" cannot be true of two directories that are
+ *    in no repository at all, and treating it as true would have a repair run
+ *    from a scratch directory rewrite another scratch directory's rows. Only the
+ *    exact same directory qualifies without a root.
+ */
+function belongsToThisRepository(
+	entry: InstalledPluginEntry,
+	cwd: string,
+	cwdRoot: string | null,
+	cache?: RepoRootCache,
+): boolean {
+	if (isMachineWideScope(entry.scope)) return false;
+	if (!entry.projectPath) return false;
+	if (path.resolve(entry.projectPath) === path.resolve(cwd)) return true;
+	if (!cwdRoot) return false;
+	return repoRootForPath(entry.projectPath, cache) === cwdRoot;
+}
+
+/** A plugin whose loader-resolved version is behind a row this repair can rewrite. */
+export interface StaleLoad {
+	pluginId: string;
+	/** What Claude Code resolves in this directory. */
+	loaded: string;
+	/** The newest version a row relevant to this directory holds — the target. */
+	target: string;
+}
+
+/**
+ * Which plugins {@link repairStaleLoad} can fix here, and to what version.
+ *
+ * REGISTRY ONLY — no catalog, no settings, no `git` subprocess. That is not a
+ * shortcut, it is the question: this function's answer is the repair's own
+ * PRECONDITION, and the repair rewrites registry rows, so the registry is the
+ * only authority that can answer it. It therefore works offline and costs
+ * nothing, which is what lets the TUI ask it during startup before any plugin
+ * data or marketplace catalog has loaded.
+ *
+ * REPORTS ONLY WHAT IS ACTUALLY REPAIRABLE — with the one stated exception at the
+ * end of this comment — and every exclusion below is a measured one. The first version of this function counted 8 broken plugins on
+ * the reporting machine where the Plugins header counted 6, and offered to fix
+ * all 8. The two extras could not be fixed by anything:
+ *
+ *  - `plugin-dev@claude-plugins-official` recorded the version string
+ *    `"unknown"`. There is no cache directory named `unknown`, so
+ *    `repairStaleLoad` would reject it — the popup was offering a fix that
+ *    cannot run.
+ *  - `skill-creator@claude-plugins-official` held two differing commit shas.
+ *    `isBehind` calls those "behind" by design, but moving rows forward between
+ *    two unordered shas is a guess rather than a repair.
+ *
+ * So the version test is {@link isRepairablyBehind} — the SAME predicate
+ * `classifyPlugin` uses for its `stale-load` state, which is what makes the
+ * popup's count and the Plugins header's count the same question rather than two
+ * that happen to agree. And the target's cache directory must exist, which is
+ * `repairStaleLoad`'s own refusal asked in advance: a finding nothing can act on
+ * does not belong in a popup that offers to act.
+ *
+ * ONE refusal is deliberately NOT asked in advance: a stale load whose winning
+ * row is machine-wide (`user` or `managed`) is still reported here. It is a real
+ * stale load — this directory runs old code — and the Plugins header counts it,
+ * since the classifier sees versions and not scopes. Dropping it from the popup
+ * to keep "everything I name is fixable" would mean the startup surface staying
+ * silent about a session running a version nobody installed, which is the
+ * deception this whole state exists to end. `repairStaleLoad` refuses it by name
+ * and the fix summary prints that reason per plugin, so pressing Fix reports what
+ * to do instead rather than a bare failure.
+ *
+ * Deliberately NOT the same question as `magus doctor`'s plugin-loads section,
+ * which reports what MAGUS RECORDS as installed against what loads. That one is
+ * a report and may legitimately name a mismatch nothing can act on.
+ *
+ * @param pins the active profile's pins — `pluginId -> exact version | "latest"`,
+ *   the SAME map `classifyPlugin` is given, so the popup and the Plugins header
+ *   cap their targets identically. An id the map does not mention is "latest",
+ *   which is also what `pinForRow` assumes for an installed-but-undeclared plugin.
+ *   The default `{}` therefore means "latest for everything".
+ *
+ *   It is the one non-registry input, and it earns its place: without it a
+ *   user-scope row at 0.5.0 made this offer to move a plugin pinned to 0.3.0 —
+ *   installed at 0.3.0 here and loading it — up to 0.5.0, and the repair
+ *   succeeded. A machine-wide row is relevant to every directory, so the pin is
+ *   the only thing that can say the move is unwanted. Reading it costs one local
+ *   manifest read (`loadActiveClosure`), no network, so the offline promise holds.
+ */
+export async function findStaleLoads(
+	projectPath: string,
+	root: string = pluginsDir(),
+	pins: Readonly<Record<string, string>> = {},
+): Promise<StaleLoad[]> {
+	const registry = await readInstalledPluginsRegistry(root);
+	// One cache for the whole pass — the same project paths repeat across every
+	// plugin's rows, and each miss walks the tree to the filesystem root.
+	const cache: RepoRootCache = new Map();
+	const cwdRoot = repoRootForPath(projectPath, cache);
+	const out: StaleLoad[] = [];
+
+	for (const [pluginId, rows] of Object.entries(registry.plugins ?? {})) {
+		if (!Array.isArray(rows) || rows.length === 0) continue;
+		const relevant = rows.filter((row) =>
+			isRelevantInstallation(row, projectPath, cwdRoot, cache),
+		);
+		if (relevant.length === 0) continue;
+
+		// The newest version any relevant row holds THAT THE PIN PERMITS — by the
+		// same ordered comparison, so a set of unrankable ids keeps the incumbent
+		// instead of crowning one arbitrarily. The plugin is dropped below in that
+		// case anyway.
+		//
+		// An exact pin is a ceiling, not a starting point: a row above it (usually
+		// the machine-wide one) must not become the version this repository is moved
+		// to. A version that cannot be ORDERED against the pin is excluded for the
+		// same reason `isRepairablyBehind` excludes it — "cannot tell" never
+		// licenses a rewrite.
+		const pin = pins[pluginId] ?? "latest";
+		const permitted = (version: string): boolean =>
+			pin === "latest" || (compareVersions(pin, version) ?? -1) >= 0;
+		let target: string | null = null;
+		for (const row of relevant) {
+			if (!row.version) continue;
+			if (!permitted(row.version)) continue;
+			if (target === null || isRepairablyBehind(row.version, target)) {
+				target = row.version;
+			}
+		}
+		if (!target) continue;
+
+		const loaded = pickLoadedEntry(rows, projectPath, cache)?.version ?? null;
+		if (!isRepairablyBehind(target, loaded)) continue;
+
+		// `repairStaleLoad`'s cache-directory refusal, asked before offering the
+		// fix instead of after accepting it.
+		const parsed = parsePluginId(pluginId);
+		if (!parsed) continue;
+		if (
+			!(await fs.pathExists(
+				getPluginCachePath(pluginId, target, parsed.marketplace, root),
+			))
+		) {
+			continue;
+		}
+
+		out.push({ pluginId, loaded: loaded as string, target });
+	}
+
+	out.sort((a, b) => a.pluginId.localeCompare(b.pluginId));
+	return out;
+}
+
+/**
+ * Repair every plugin {@link findStaleLoads} reports, one at a time.
+ *
+ * The same `repairStaleLoad` the apply engine calls per plan item, so the
+ * startup popup and the Plugins screen's `a` key run identical work — there is
+ * one repair, reached two ways, not two repairs.
+ *
+ * @param pins passed straight through to {@link findStaleLoads}, so the fix moves
+ *   rows to exactly the versions the survey named. Handing the survey a pin map
+ *   and the repair a different one is how a dialog would offer one thing and do
+ *   another.
+ */
+export async function repairAllStaleLoads(
+	projectPath: string,
+	root: string = pluginsDir(),
+	pins: Readonly<Record<string, string>> = {},
+): Promise<StaleLoadRepairResult[]> {
+	const out: StaleLoadRepairResult[] = [];
+	// Sequential, not Promise.all: every repair reads, mutates and rewrites the
+	// SAME file, so running two concurrently means the second overwrites the
+	// first's rows from a snapshot taken before them.
+	for (const broken of await findStaleLoads(projectPath, root, pins)) {
+		out.push(
+			await repairStaleLoad(broken.pluginId, broken.target, projectPath, root),
+		);
+	}
+	return out;
+}
+
+/**
+ * What one {@link repairStaleLoad} attempt did, and whether it worked.
+ *
+ * `ok` is the POST-WRITE assertion, not "the write succeeded". Rewriting rows
+ * and reporting success without re-asking the loader is how a repair that
+ * changed nothing would read as a fix — the exact failure mode that made the
+ * `stale-load` finding necessary in the first place.
+ */
+export interface StaleLoadRepairResult {
+	pluginId: string;
+	/** The version every stale row was moved forward to. */
+	target: string;
+	/** Rows rewritten. Zero when no relevant row was behind the target. */
+	rewritten: number;
+	/** The backup taken before the first write; null when nothing was written. */
+	backup: string | null;
+	/** What the loader resolves here AFTER the write. */
+	loaded: string | null;
+	/** True only when `loaded` is now `target`. */
+	ok: boolean;
+	/** Why it failed. Absent when `ok`. */
+	error?: string;
+}
+
+/**
+ * Make Claude Code's loader resolve `target` for `pluginId` in `projectPath`, by
+ * moving this repository's stale registry rows FORWARD onto it.
+ *
+ * ── Why this edits installed_plugins.json directly ──
+ *
+ * The project's CLAUDE.md forbids writing `installed_plugins.json`: it is
+ * Claude Code-owned state, and everything else goes through a `claude plugin`
+ * command. This function is a DELIBERATE exception, and the user approved it,
+ * because no `claude plugin` command can reach the rows that cause this bug.
+ *
+ * The loader takes the first row relevant to this repository whose `installPath`
+ * exists (`pickLoadedEntry`, services/plugin-resolution.ts). "Relevant" includes
+ * any row installed ANYWHERE in the same repository — including worktrees that
+ * have since been deleted, whose rows nothing prunes. Measured on the reporting
+ * machine, the winning rows belonged to other worktrees, several of them gone.
+ * `claude plugin install` keys on the working directory, so it writes ANOTHER
+ * row for this project and leaves the winner untouched; `claude plugin uninstall
+ * --scope project` resolves the project from the working directory too, so it
+ * cannot name a directory that no longer exists. A reinstall is measured not to
+ * clear this. There is no CLI path to those rows at all.
+ *
+ * ── The rules this obeys ──
+ *
+ * MOVE FORWARD ONLY, DELETE NOTHING — the same promise `magus update` makes.
+ * Rows are rewritten in place, so the array order the loader's tie-break depends
+ * on is preserved, and a row belonging to a deleted worktree is moved forward
+ * like any other. That is not collateral damage: it is the point, since that row
+ * is usually the winner.
+ *
+ * A row is rewritten only when {@link belongsToThisRepository} accepts it AND
+ * `isRepairablyBehind` says its version is ORDERED behind `target`. A row ahead
+ * of the target, and one that cannot be ranked against it at all — two commit
+ * shas, a `"unknown"` version — is left exactly as it is. "Cannot compare" is
+ * never a licence to overwrite; the same predicate is what {@link findStaleLoads}
+ * and the Plugins header ask, so nothing offers a repair this would then decline
+ * to make.
+ *
+ * THIS REPOSITORY ONLY, which is what the dialog offering the fix promises. The
+ * relevance filter the LOADER uses counts `user` and `managed` rows for every
+ * project on the machine, and rewriting through it moved a machine-wide record
+ * from an unrelated directory forward — measured. `belongsToThisRepository` is
+ * the writer's narrower question; `pickLoadedEntry` keeps modelling the loader
+ * faithfully, machine-wide relevance included, because a repair that misjudges
+ * what loads is worse than one that declines to write.
+ *
+ * WHEN THE MACHINE-WIDE ROW IS THE WINNER, this refuses and says so, naming the
+ * scope and the action that would fix it. The alternatives were both worse:
+ * rewriting it exceeds the stated reach, and writing this repository's rows
+ * anyway would change nothing the loader reads and then report `ok: false` from
+ * the post-write assertion with no explanation of why. `magus update --check`
+ * stays red for such a plugin until the user acts on that scope — the state is
+ * real, and the one thing that must not happen is reporting it green.
+ *
+ * NOTHING IS WRITTEN OVER A FILE THAT MOVED. The snapshot is taken as bytes and
+ * handed back to `writeInstalledPluginsRegistry` as a precondition, so a
+ * concurrent `claude plugin install` makes this refuse rather than discard that
+ * session's row. Dozens of sessions write this file on a working machine.
+ *
+ * @param root the plugins directory holding the registry and cache — see
+ *   {@link pluginsDir}. Tests pass a temp directory; nothing else should.
+ */
+export async function repairStaleLoad(
+	pluginId: string,
+	target: string,
+	projectPath: string,
+	root: string = pluginsDir(),
+): Promise<StaleLoadRepairResult> {
+	const fail = (error: string): StaleLoadRepairResult => ({
+		pluginId,
+		target,
+		rewritten: 0,
+		backup: null,
+		loaded: null,
+		ok: false,
+		error,
+	});
+
+	const parsed = parsePluginId(pluginId);
+	if (!parsed) return fail(`not a plugin id: ${pluginId}`);
+
+	// Refuse a target with no cache directory. Writing that row would leave the
+	// registry naming a directory that is not there — the loader would resolve
+	// it, fail to load anything, and the state would be worse than the stale load
+	// it replaced. The installed version's cache always exists, which is why the
+	// target is what is installed here rather than what the catalog offers.
+	const cacheDir = getPluginCachePath(
+		pluginId,
+		target,
+		parsed.marketplace,
+		root,
+	);
+	if (!(await fs.pathExists(cacheDir))) {
+		return fail(
+			`no cache directory for v${target} — ${cacheDir} does not exist`,
+		);
+	}
+
+	const file = installedPluginsFile(root);
+	// The BYTES first, and the snapshot parsed from those same bytes. They are the
+	// precondition the write is checked against, so they have to describe one
+	// moment — see `writeInstalledPluginsRegistry`.
+	const before = await readRegistryBytes(file);
+	const registry = parseRegistryBytes(before);
+	if (!registry) {
+		return fail(
+			before === null
+				? `${file} does not exist`
+				: `${file} is not a readable registry — refusing to write over it`,
+		);
+	}
+	const rows = registry.plugins[pluginId];
+	if (!Array.isArray(rows) || rows.length === 0) {
+		return fail(`${pluginId} has no rows in ${file}`);
+	}
+
+	// One cache for the whole pass: the same project paths repeat across rows,
+	// and each miss walks the tree to the filesystem root.
+	const cache: RepoRootCache = new Map();
+	const cwdRoot = repoRootForPath(projectPath, cache);
+
+	// The row the loader picks here, asked BEFORE anything is written. When that
+	// row is machine-wide, no rewrite this function is willing to make can change
+	// the resolution, so it says so instead of writing rows that will not help —
+	// and instead of reaching machine-wide, which is what it used to do.
+	const winner = pickLoadedEntry(rows, projectPath, cache);
+	if (
+		winner &&
+		isMachineWideScope(winner.scope) &&
+		isRepairablyBehind(target, winner.version)
+	) {
+		// Widened: Claude Code writes a `managed` scope for policy-installed
+		// plugins, which the registry type in types/index.ts does not name — see
+		// `LoaderScope` in plugin-resolution.ts.
+		const scope: string = winner.scope;
+		return fail(
+			`the row Claude Code loads here is the machine-wide ${scope}-scope record at v${
+				winner.version
+			}, which every project on this machine resolves through. This repair only rewrites THIS repository's records, so it will not move it. ${
+				scope === "managed"
+					? "A managed record is administrator policy — raise it with whoever set that policy."
+					: `Update that scope directly instead: claude plugin install ${pluginId} --scope user`
+			}`,
+		);
+	}
+
+	const stale = rows.filter(
+		(row) =>
+			belongsToThisRepository(row, projectPath, cwdRoot, cache) &&
+			isRepairablyBehind(target, row.version),
+	);
+
+	let backup: string | null = null;
+	if (stale.length > 0) {
+		// BEFORE the first mutation, and a failure here aborts the repair. This
+		// file is the only record of what every project on the machine has
+		// installed; an edit with no undo is not one to offer.
+		try {
+			backup = await registryBackupPath(file, pluginId);
+			await fs.copy(file, backup);
+		} catch (error) {
+			return fail(
+				`could not back up ${file}: ${
+					error instanceof Error ? error.message : String(error)
+				}`,
+			);
+		}
+
+		const now = new Date().toISOString();
+		for (const row of stale) {
+			row.version = target;
+			row.installPath = cacheDir;
+			row.lastUpdated = now;
+			// The recorded commit describes the version we just moved AWAY from, so
+			// keeping it would have content-drift diff two different releases and
+			// report every repaired plugin as "stale — reinstall". Unknown
+			// provenance is `undefined`, which `hasContentDrift` answers false for.
+			row.gitCommitSha = undefined;
+		}
+		try {
+			// `before` makes this a compare-and-set: another session's write landing
+			// since the read means this snapshot would silently drop it, so the write
+			// is refused instead. Nothing was changed at that point — the rows were
+			// mutated in memory only — so the backup just taken is an undo for a file
+			// nobody touched, and it goes rather than accumulating.
+			await writeInstalledPluginsRegistry(registry, root, before);
+		} catch (error) {
+			if (backup) await fs.remove(backup).catch(() => {});
+			return fail(
+				error instanceof RegistryChangedError
+					? error.message
+					: `could not write ${file}: ${
+							error instanceof Error ? error.message : String(error)
+						}`,
+			);
+		}
+		await pruneRegistryBackups(file);
+	}
+
+	// Re-read from DISK, not from the object just mutated: the assertion has to
+	// judge the file the loader will read, which also proves the write landed.
+	const after = await readInstalledPluginsRegistry(root);
+	const loaded =
+		pickLoadedEntry(after.plugins[pluginId], projectPath)?.version ?? null;
+	if (loaded === target) {
+		return {
+			pluginId,
+			target,
+			rewritten: stale.length,
+			backup,
+			loaded,
+			ok: true,
+		};
+	}
+	return {
+		pluginId,
+		target,
+		rewritten: stale.length,
+		backup,
+		loaded,
+		ok: false,
+		error: `the loader still resolves ${
+			loaded ? `v${loaded}` : "nothing"
+		} here, not v${target}`,
+	};
+}