magus-cli 7.3.1 → 7.4.1

package/src/services/claude-settings.ts

@@ -28,6 +28,22 @@ import {
 	pickLoadedEntry,
 	repoRootForPath,
 } from "./plugin-resolution.js";
+import {
+	SettingsParseError,
+	SettingsShapeError,
+	describeJsonKind,
+	isJsonObject,
+	readSettingsFile,
+	writableList,
+	writableMap,
+} from "./settings-file.js";
+
+/**
+ * What every reader below throws for a file that exists but does not parse.
+ * Defined beside `readSettingsFile`, which all four readers delegate to, and
+ * re-exported here because this is the module callers read settings through.
+ */
+export { SettingsParseError } from "./settings-file.js";
 
 const CLAUDE_DIR = ".claude";
 const SETTINGS_FILE = "settings.json";
@@ -44,8 +60,17 @@ export function getClaudeDir(projectPath?: string): string {
 	return path.join(base, CLAUDE_DIR);
 }
 
+/**
+ * `~/.claude`, resolved per call.
+ *
+ * `HOME` first, then `os.homedir()` — Node's own rule for `os.homedir()`, done
+ * by hand because Bun does not follow it: under Bun 1.4 `os.homedir()` answers
+ * the home the process started with and ignores a later `process.env.HOME`
+ * (measured; Node follows the change). Reading `HOME` at call time is what lets
+ * a caller — a test above all — point the global settings somewhere else.
+ */
 export function getGlobalClaudeDir(): string {
-	return path.join(os.homedir(), CLAUDE_DIR);
+	return path.join(process.env.HOME || os.homedir(), CLAUDE_DIR);
 }
 
 export async function ensureClaudeDir(projectPath?: string): Promise<string> {
@@ -54,24 +79,76 @@ export async function ensureClaudeDir(projectPath?: string): Promise<string> {
 	return claudeDir;
 }
 
+/*
+ * THE FOUR READERS: a missing file reads as `{}`; a file that exists but does
+ * not parse throws `SettingsParseError`, never `{}`.
+ *
+ * They used to swallow every error and answer `{}`. Each has a writer beside
+ * it, and every read-modify-write in magus is `read → change one key →
+ * write`, so a settings file a human was mid-edit in came back as `{}` plus
+ * one key — and was written over, taking the rest of the configuration with
+ * it. Throwing from the read is what makes every one of those callers refuse:
+ * nothing reaches the write, so the file stays byte-for-byte as it was.
+ */
+
+/*
+ * Each file's path has one getter, used by its reader AND by every writer that
+ * checks a map before writing into it (`writableMap`), so a refusal names the
+ * file that was actually read.
+ */
+
+/**
+ * THE FOUR WRITERS all start here: the file as it is NOW must still be one this
+ * module would read, or nothing is written.
+ *
+ * Every caller reads before it writes, but not necessarily just before —
+ * `magus install` reads the local settings, puts a prompt per missing variable
+ * on screen, and writes when the last one is answered. Claude Code writes that
+ * same file while those prompts are up (a permission rule, whenever someone
+ * answers "don't ask again"), and `writeJson` would replace it with a document
+ * built from the pre-prompt read.
+ *
+ * Checking at write time is what makes the refusal hold for every writer instead
+ * of only the ones that happened to re-read — the same rule `writeManifest`
+ * applies to `.claude/profiles.json`. The read is for the throw alone; the
+ * contents are about to be replaced.
+ *
+ * It closes the gap, it does not close the race: the check and the write are two
+ * syscalls. The window is microseconds rather than however long a human takes to
+ * answer a prompt.
+ */
+async function refuseUnwritableFile(filePath: string): Promise<void> {
+	await readSettingsFile(filePath);
+}
+
+/** <project>/.claude/settings.json */
+export function getSettingsPath(projectPath?: string): string {
+	return path.join(getClaudeDir(projectPath), SETTINGS_FILE);
+}
+
+/** <project>/.claude/settings.local.json */
+export function getLocalSettingsPath(projectPath?: string): string {
+	return path.join(getClaudeDir(projectPath), LOCAL_SETTINGS_FILE);
+}
+
+/** ~/.claude/settings.json */
+export function getGlobalSettingsPath(): string {
+	return path.join(getGlobalClaudeDir(), SETTINGS_FILE);
+}
+
 export async function readSettings(
 	projectPath?: string,
 ): Promise<ClaudeSettings> {
-	const settingsPath = path.join(getClaudeDir(projectPath), SETTINGS_FILE);
-	try {
-		if (await fs.pathExists(settingsPath)) {
-			return await fs.readJson(settingsPath);
-		}
-	} catch {
-		// Return empty settings on error
-	}
-	return {};
+	return (await readSettingsFile(
+		getSettingsPath(projectPath),
+	)) as ClaudeSettings;
 }
 
 export async function writeSettings(
 	settings: ClaudeSettings,
 	projectPath?: string,
 ): Promise<void> {
+	await refuseUnwritableFile(getSettingsPath(projectPath));
 	const claudeDir = await ensureClaudeDir(projectPath);
 	const settingsPath = path.join(claudeDir, SETTINGS_FILE);
 	await fs.writeJson(settingsPath, settings, { spaces: 2 });
@@ -80,21 +157,16 @@ export async function writeSettings(
 export async function readLocalSettings(
 	projectPath?: string,
 ): Promise<ClaudeLocalSettings> {
-	const localPath = path.join(getClaudeDir(projectPath), LOCAL_SETTINGS_FILE);
-	try {
-		if (await fs.pathExists(localPath)) {
-			return await fs.readJson(localPath);
-		}
-	} catch {
-		// Return empty settings on error
-	}
-	return {};
+	return (await readSettingsFile(
+		getLocalSettingsPath(projectPath),
+	)) as ClaudeLocalSettings;
 }
 
 export async function writeLocalSettings(
 	settings: ClaudeLocalSettings,
 	projectPath?: string,
 ): Promise<void> {
+	await refuseUnwritableFile(getLocalSettingsPath(projectPath));
 	const claudeDir = await ensureClaudeDir(projectPath);
 	const localPath = path.join(claudeDir, LOCAL_SETTINGS_FILE);
 	await fs.writeJson(localPath, settings, { spaces: 2 });
@@ -109,15 +181,9 @@ export function getMcpConfigPath(projectPath?: string): string {
 export async function readMcpConfig(
 	projectPath?: string,
 ): Promise<McpConfigFile> {
-	const mcpPath = getMcpConfigPath(projectPath);
-	try {
-		if (await fs.pathExists(mcpPath)) {
-			return await fs.readJson(mcpPath);
-		}
-	} catch {
-		// Return empty config on error
-	}
-	return {};
+	return (await readSettingsFile(
+		getMcpConfigPath(projectPath),
+	)) as McpConfigFile;
 }
 
 export async function writeMcpConfig(
@@ -125,24 +191,18 @@ export async function writeMcpConfig(
 	projectPath?: string,
 ): Promise<void> {
 	const mcpPath = getMcpConfigPath(projectPath);
+	await refuseUnwritableFile(mcpPath);
 	await fs.writeJson(mcpPath, config, { spaces: 2 });
 }
 
 export async function readGlobalSettings(): Promise<ClaudeSettings> {
-	const settingsPath = path.join(getGlobalClaudeDir(), SETTINGS_FILE);
-	try {
-		if (await fs.pathExists(settingsPath)) {
-			return await fs.readJson(settingsPath);
-		}
-	} catch {
-		// Return empty settings on error
-	}
-	return {};
+	return (await readSettingsFile(getGlobalSettingsPath())) as ClaudeSettings;
 }
 
 export async function writeGlobalSettings(
 	settings: ClaudeSettings,
 ): Promise<void> {
+	await refuseUnwritableFile(getGlobalSettingsPath());
 	await fs.ensureDir(getGlobalClaudeDir());
 	const settingsPath = path.join(getGlobalClaudeDir(), SETTINGS_FILE);
 	await fs.writeJson(settingsPath, settings, { spaces: 2 });
@@ -160,15 +220,27 @@ export async function addMcpServer(
 	// biome-ignore lint/performance/noDelete: this object is serialised into .mcp.json; the env key must be absent, not present as undefined
 	delete configWithoutEnv.env;
 
-	// Add to .mcp.json (without env vars)
+	// Read BOTH files, and check every map written into, before writing either:
+	// if one does not parse or has the wrong shape, the whole operation refuses,
+	// rather than leaving .mcp.json changed and the local settings not.
 	const mcpConfig = await readMcpConfig(projectPath);
-	mcpConfig.mcpServers = mcpConfig.mcpServers || {};
-	mcpConfig.mcpServers[name] = configWithoutEnv;
+	const localSettings = await readLocalSettings(projectPath);
+	const localPath = getLocalSettingsPath(projectPath);
+	const mcpServers =
+		writableMap(mcpConfig, "mcpServers", getMcpConfigPath(projectPath)) ?? {};
+	const enabledServers =
+		writableList(localSettings, "enabledMcpjsonServers", localPath) ?? [];
+	const env =
+		Object.keys(envVars).length > 0
+			? (writableMap(localSettings, "env", localPath) ?? {})
+			: undefined;
+
+	// Add to .mcp.json (without env vars)
+	mcpConfig.mcpServers = mcpServers;
+	mcpServers[name] = configWithoutEnv;
 	await writeMcpConfig(mcpConfig, projectPath);
 
 	// Enable in settings.local.json and add env vars
-	const localSettings = await readLocalSettings(projectPath);
-	const enabledServers = localSettings.enabledMcpjsonServers || [];
 	if (!enabledServers.includes(name)) {
 		enabledServers.push(name);
 	}
@@ -176,12 +248,12 @@ export async function addMcpServer(
 	localSettings.enableAllProjectMcpServers = true;
 
 	// Add env vars to settings.local.json
-	if (Object.keys(envVars).length > 0) {
-		localSettings.env = localSettings.env || {};
+	if (env) {
+		localSettings.env = env;
 		for (const [key, value] of Object.entries(envVars)) {
 			// Only add non-reference values (references like ${VAR} don't need to be stored)
 			if (!value.startsWith("${") || !value.endsWith("}")) {
-				localSettings.env[key] = value;
+				env[key] = value;
 			}
 		}
 	}
@@ -193,18 +265,32 @@ export async function removeMcpServer(
 	name: string,
 	projectPath?: string,
 ): Promise<void> {
-	// Remove from .mcp.json
+	// Both reads and both shape checks first, for the same reason as in
+	// addMcpServer.
 	const mcpConfig = await readMcpConfig(projectPath);
-	if (mcpConfig.mcpServers) {
-		delete mcpConfig.mcpServers[name];
+	const localSettings = await readLocalSettings(projectPath);
+	const mcpServers = writableMap(
+		mcpConfig,
+		"mcpServers",
+		getMcpConfigPath(projectPath),
+	);
+	const enabledServers = writableList(
+		localSettings,
+		"enabledMcpjsonServers",
+		getLocalSettingsPath(projectPath),
+	);
+
+	// Remove from .mcp.json
+	if (mcpServers) {
+		delete mcpServers[name];
 	}
 	await writeMcpConfig(mcpConfig, projectPath);
 
 	// Remove from settings.local.json
-	const localSettings = await readLocalSettings(projectPath);
-	if (localSettings.enabledMcpjsonServers) {
-		localSettings.enabledMcpjsonServers =
-			localSettings.enabledMcpjsonServers.filter((s) => s !== name);
+	if (enabledServers) {
+		localSettings.enabledMcpjsonServers = enabledServers.filter(
+			(s) => s !== name,
+		);
 		await writeLocalSettings(localSettings, projectPath);
 	}
 }
@@ -242,12 +328,11 @@ export async function enablePlugin(
 	projectPath?: string,
 ): Promise<void> {
 	const settings = await readSettings(projectPath);
-	settings.enabledPlugins = settings.enabledPlugins || {};
-	if (enabled) {
-		settings.enabledPlugins[pluginId] = true;
-	} else {
-		delete settings.enabledPlugins[pluginId];
-	}
+	settings.enabledPlugins =
+		writableMap(settings, "enabledPlugins", getSettingsPath(projectPath)) ?? {};
+	// `false`, never a deleted key: Claude Code resolves enabledPlugins per id with
+	// fall-through, so a missing project entry lets a user-scope `true` win.
+	settings.enabledPlugins[pluginId] = enabled;
 	await writeSettings(settings, projectPath);
 }
 
@@ -398,7 +483,12 @@ export async function enableLocalPlugin(
 	projectPath?: string,
 ): Promise<void> {
 	const settings = await readLocalSettings(projectPath);
-	settings.enabledPlugins = settings.enabledPlugins || {};
+	settings.enabledPlugins =
+		writableMap(
+			settings,
+			"enabledPlugins",
+			getLocalSettingsPath(projectPath),
+		) ?? {};
 	if (enabled) {
 		settings.enabledPlugins[pluginId] = true;
 	} else {
@@ -413,7 +503,12 @@ export async function saveLocalInstalledPluginVersion(
 	projectPath?: string,
 ): Promise<void> {
 	const settings = await readLocalSettings(projectPath);
-	settings.installedPluginVersions = settings.installedPluginVersions || {};
+	settings.installedPluginVersions =
+		writableMap(
+			settings,
+			"installedPluginVersions",
+			getLocalSettingsPath(projectPath),
+		) ?? {};
 	settings.installedPluginVersions[pluginId] = version;
 	await writeLocalSettings(settings, projectPath);
 
@@ -431,11 +526,14 @@ export async function removeLocalInstalledPluginVersion(
 	projectPath?: string,
 ): Promise<void> {
 	const settings = await readLocalSettings(projectPath);
-	if (settings.installedPluginVersions) {
-		delete settings.installedPluginVersions[pluginId];
+	const localPath = getLocalSettingsPath(projectPath);
+	const versions = writableMap(settings, "installedPluginVersions", localPath);
+	const enabled = writableMap(settings, "enabledPlugins", localPath);
+	if (versions) {
+		delete versions[pluginId];
 	}
-	if (settings.enabledPlugins) {
-		delete settings.enabledPlugins[pluginId];
+	if (enabled) {
+		delete enabled[pluginId];
 	}
 	await writeLocalSettings(settings, projectPath);
 
@@ -556,7 +654,8 @@ export async function setMcpEnvVar(
 	projectPath?: string,
 ): Promise<void> {
 	const localSettings = await readLocalSettings(projectPath);
-	localSettings.env = localSettings.env || {};
+	localSettings.env =
+		writableMap(localSettings, "env", getLocalSettingsPath(projectPath)) ?? {};
 	localSettings.env[name] = value;
 	await writeLocalSettings(localSettings, projectPath);
 }
@@ -567,8 +666,13 @@ export async function removeMcpEnvVar(
 	projectPath?: string,
 ): Promise<void> {
 	const localSettings = await readLocalSettings(projectPath);
-	if (localSettings.env) {
-		delete localSettings.env[name];
+	const env = writableMap(
+		localSettings,
+		"env",
+		getLocalSettingsPath(projectPath),
+	);
+	if (env) {
+		delete env[name];
 		await writeLocalSettings(localSettings, projectPath);
 	}
 }
@@ -652,7 +756,8 @@ export async function enableGlobalPlugin(
 	enabled: boolean,
 ): Promise<void> {
 	const settings = await readGlobalSettings();
-	settings.enabledPlugins = settings.enabledPlugins || {};
+	settings.enabledPlugins =
+		writableMap(settings, "enabledPlugins", getGlobalSettingsPath()) ?? {};
 	if (enabled) {
 		settings.enabledPlugins[pluginId] = true;
 	} else {
@@ -683,7 +788,9 @@ export async function saveGlobalInstalledPluginVersion(
 	version: string,
 ): Promise<void> {
 	const settings = await readGlobalSettings();
-	settings.installedPluginVersions = settings.installedPluginVersions || {};
+	settings.installedPluginVersions =
+		writableMap(settings, "installedPluginVersions", getGlobalSettingsPath()) ??
+		{};
 	settings.installedPluginVersions[pluginId] = version;
 	await writeGlobalSettings(settings);
 
@@ -695,11 +802,14 @@ export async function removeGlobalInstalledPluginVersion(
 	pluginId: string,
 ): Promise<void> {
 	const settings = await readGlobalSettings();
-	if (settings.installedPluginVersions) {
-		delete settings.installedPluginVersions[pluginId];
+	const globalPath = getGlobalSettingsPath();
+	const versions = writableMap(settings, "installedPluginVersions", globalPath);
+	const enabled = writableMap(settings, "enabledPlugins", globalPath);
+	if (versions) {
+		delete versions[pluginId];
 	}
-	if (settings.enabledPlugins) {
-		delete settings.enabledPlugins[pluginId];
+	if (enabled) {
+		delete enabled[pluginId];
 	}
 	await writeGlobalSettings(settings);
 
@@ -1052,13 +1162,13 @@ export async function migrateMarketplaceRename(
 	}
 
 	// 4. known_marketplaces.json — rename old keys + physical directory cleanup
-	const pluginsDir = path.join(
+	const marketplacesDir = path.join(
 		os.homedir(),
 		".claude",
 		"plugins",
 		"marketplaces",
 	);
-	const newDir = path.join(pluginsDir, NEW_MARKETPLACE_NAME);
+	const newDir = path.join(marketplacesDir, NEW_MARKETPLACE_NAME);
 
 	try {
 		const known = await readKnownMarketplaces();
@@ -1100,7 +1210,7 @@ export async function migrateMarketplaceRename(
 
 	// 4b. Rename/remove old physical directories (runs even if keys were already migrated)
 	for (const oldName of OLD_MARKETPLACE_NAMES) {
-		const oldDir = path.join(pluginsDir, oldName);
+		const oldDir = path.join(marketplacesDir, oldName);
 		try {
 			if (await fs.pathExists(oldDir)) {
 				if (!(await fs.pathExists(newDir))) {
@@ -1139,29 +1249,32 @@ export async function migrateMarketplaceRename(
 
 	// 5. installed_plugins.json — rename plugin ID keys
 	try {
-		const registry = await readInstalledPluginsRegistry();
 		let regCount = 0;
-		const newPlugins: typeof registry.plugins = {};
-		for (const [pluginId, entries] of Object.entries(registry.plugins)) {
-			const oldName = OLD_MARKETPLACE_NAMES.find((n) =>
-				pluginId.endsWith(`@${n}`),
-			);
-			if (oldName) {
-				const pluginName = pluginId.slice(0, pluginId.lastIndexOf("@"));
-				const newKey = `${pluginName}@${NEW_MARKETPLACE_NAME}`;
-				if (!newPlugins[newKey]) {
-					newPlugins[newKey] = entries;
+		await updateRegistryFile((registry) => {
+			const newPlugins: typeof registry.plugins = {};
+			for (const [pluginId, entries] of Object.entries(registry.plugins)) {
+				const oldName = OLD_MARKETPLACE_NAMES.find((n) =>
+					pluginId.endsWith(`@${n}`),
+				);
+				if (oldName) {
+					const pluginName = pluginId.slice(0, pluginId.lastIndexOf("@"));
+					const newKey = `${pluginName}@${NEW_MARKETPLACE_NAME}`;
+					if (!newPlugins[newKey]) {
+						newPlugins[newKey] = entries;
+					}
+					regCount++;
+				} else {
+					newPlugins[pluginId] = entries;
 				}
-				regCount++;
-			} else {
-				newPlugins[pluginId] = entries;
 			}
-		}
-		if (regCount > 0) {
+			if (regCount === 0) return false;
 			registry.plugins = newPlugins;
-			await writeInstalledPluginsRegistry(registry);
-			result.registryMigrated = regCount;
-		}
+			return true;
+		});
+		// After the write, never inside the mutation: a refused write (a corrupt
+		// file, or one another session changed) must not report a migration that
+		// did not land.
+		result.registryMigrated = regCount;
 	} catch {
 		/* skip if unreadable */
 	}
@@ -1416,7 +1529,17 @@ export async function resolveCacheProvenance(
 }
 
 /**
- * Read installed_plugins.json registry
+ * Read installed_plugins.json registry.
+ *
+ * Missing reads as an empty registry — nothing is lost by starting from one.
+ * A file that EXISTS and cannot be used throws, exactly as the settings readers
+ * do: this is the record of what every project on the machine has installed,
+ * and "unreadable" is not the same answer as "nothing installed".
+ *
+ * It used to answer an empty registry for both, and the registry writers below
+ * then wrote that empty copy back with one plugin in it — so a registry a
+ * Claude Code write had truncated came back holding a single row, and every
+ * other plugin on the machine read as uninstalled.
  *
  * @param root the plugins directory to read from — see {@link pluginsDir}
  */
@@ -1424,20 +1547,7 @@ 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: {} };
+	return requireRegistry(file, await readRegistryBytes(file));
 }
 
 /**
@@ -1457,18 +1567,104 @@ async function readRegistryBytes(file: string): Promise<string | null> {
 	}
 }
 
-/** Parse + structure check. Null means "not a registry", including absent. */
-function parseRegistryBytes(
+/** An empty, valid registry: what an absent file reads as. */
+function emptyRegistry(): InstalledPluginsRegistry {
+	return { version: 2, plugins: {} };
+}
+
+/**
+ * Refuse a registry document that cannot be read AT ALL — it does not parse, or
+ * its top level is not a JSON object — with the same refusal every settings file
+ * gets, naming the file. Absent or whitespace-only passes (and answers `null`).
+ *
+ * The weaker of the two checks, and deliberately so: it is what a WRITER asks
+ * before renaming over a file, where the question is only "is this a document
+ * anything could have read", not "does it match the shape this version of magus
+ * models". {@link requireRegistry} is the stronger one, asked by every reader.
+ */
+function refuseUnreadableRegistry(
+	file: string,
 	raw: string | null,
-): InstalledPluginsRegistry | null {
-	if (raw === null) return null;
+): Record<string, unknown> | null {
+	if (raw === null || raw.trim() === "") return null;
+
+	let parsed: unknown;
 	try {
-		const content = JSON.parse(raw);
-		if (!content?.version || !content?.plugins) return null;
-		return content as InstalledPluginsRegistry;
-	} catch {
-		return null;
+		parsed = JSON.parse(raw);
+	} catch (error) {
+		throw new SettingsParseError(file, error);
+	}
+	if (!isJsonObject(parsed)) {
+		throw new SettingsShapeError(
+			file,
+			"is not a JSON object",
+			`its top level is ${describeJsonKind(parsed)}`,
+		);
 	}
+	return parsed;
+}
+
+/**
+ * Parse + structure check, or throw.
+ *
+ * THE one place a registry document is judged for READING, so no two readers
+ * can disagree about whether the file on disk is usable. Absent or
+ * whitespace-only reads as an empty registry; anything else that is not
+ * `{version, plugins: {…}}` throws a {@link SettingsParseError} — a
+ * `SettingsShapeError` when it parsed but is the wrong shape — naming the file,
+ * so every read-modify-write refuses at the same point and nothing reaches a
+ * write.
+ */
+function requireRegistry(
+	file: string,
+	raw: string | null,
+): InstalledPluginsRegistry {
+	const parsed = refuseUnreadableRegistry(file, raw);
+	if (parsed === null) return emptyRegistry();
+
+	if (!parsed.version || !isJsonObject(parsed.plugins)) {
+		throw new SettingsShapeError(
+			file,
+			"is not a plugin registry",
+			`expected a "version" and a "plugins" object, got ${
+				parsed.plugins === undefined
+					? 'no "plugins" key'
+					: `"plugins" as ${describeJsonKind(parsed.plugins)}`
+			}`,
+		);
+	}
+	return parsed as unknown as InstalledPluginsRegistry;
+}
+
+/**
+ * Read the registry, change it, write it back — the ONE read-modify-write every
+ * registry writer goes through.
+ *
+ * Both halves of the safety live here rather than in each writer: the read
+ * refuses a document we cannot parse ({@link requireRegistry}), and the write
+ * carries the exact bytes that were read as a precondition, so a Claude Code
+ * install landing in between is refused instead of being silently dropped by our
+ * snapshot (see {@link writeInstalledPluginsRegistry}).
+ *
+ * `mutate` answers whether there is anything to write: `false` writes nothing
+ * and leaves the file untouched.
+ *
+ * {@link repairStaleLoad} is the one writer that does this by hand, because it
+ * takes an undo backup between the read and the write and reports its refusals
+ * as a result object instead of throwing. It reads and checks through the same
+ * {@link requireRegistry}.
+ */
+async function updateRegistryFile(
+	mutate: (registry: InstalledPluginsRegistry) => Promise<boolean> | boolean,
+	root: string = pluginsDir(),
+): Promise<void> {
+	const file = installedPluginsFile(root);
+	// The BYTES first, and the snapshot parsed from those same bytes: they have
+	// to describe one moment for the precondition to mean anything.
+	const before = await readRegistryBytes(file);
+	const registry = requireRegistry(file, before);
+	if (!(await mutate(registry))) return;
+	await writeInstalledPluginsRegistry(registry, root, before);
 }
 
 /** How many `installed_plugins.json.backup.*` files are kept. */
@@ -1547,10 +1743,23 @@ export class RegistryChangedError extends Error {
  *
  * 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.
+ * leaves a truncated JSON document nothing can read: every plugin on the machine
+ * would read 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.
+ *
+ * TWO preconditions, both checked as the last act before the rename, and the
+ * second is not implied by the first:
+ *
+ *  1. the file is the one the caller read (`expectBytes`);
+ *  2. the file on disk is still a document we can read at all — it parses, and
+ *     into an object.
+ *
+ * Byte-equality does not cover (2). A caller holding the raw bytes of a corrupt
+ * file passes the compare exactly, and the rename then replaces a registry
+ * nobody could read with one holding only the plugin being written — every other
+ * project's installs gone. The strict read in {@link requireRegistry} is the
+ * first line and stops every read-modify-write; this is the second, and it holds
+ * for a direct caller too, including one that passes no `expectBytes`.
  *
  * 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
@@ -1586,10 +1795,12 @@ export async function writeInstalledPluginsRegistry(
 	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);
+		// One read, both preconditions — they have to judge the same moment.
+		const current = await readRegistryBytes(file);
+		if (expectBytes !== undefined && current !== expectBytes) {
+			throw new RegistryChangedError(file);
 		}
+		refuseUnreadableRegistry(file, current);
 		await fs.rename(tmp, file);
 	} catch (error) {
 		await fs.remove(tmp).catch(() => {});
@@ -1625,65 +1836,73 @@ export async function updateInstalledPluginsRegistry(
 	projectPath?: string,
 ): Promise<void> {
 	try {
-		const registry = await readInstalledPluginsRegistry();
-
-		// Get marketplace from plugin ID
-		const parsed = parsePluginId(pluginId);
-		if (!parsed) {
-			console.warn(`Invalid plugin ID: ${pluginId}, skipping registry update`);
-			return;
-		}
-
-		const { marketplace } = parsed;
+		await updateRegistryFile(async (registry) => {
+			// Get marketplace from plugin ID
+			const parsed = parsePluginId(pluginId);
+			if (!parsed) {
+				console.warn(
+					`Invalid plugin ID: ${pluginId}, skipping registry update`,
+				);
+				return false;
+			}
 
-		// Copy plugin files from source to cache
-		// This ensures the cache has the latest plugin version
-		const copiedFrom = await copyPluginToCache(pluginId, version, marketplace);
+			const { marketplace } = parsed;
 
-		const installPath = getPluginCachePath(pluginId, version, marketplace);
-		const now = new Date().toISOString();
+			// Copy plugin files from source to cache
+			// This ensures the cache has the latest plugin version
+			const copiedFrom = await copyPluginToCache(
+				pluginId,
+				version,
+				marketplace,
+			);
 
-		// Initialize plugin array if it doesn't exist
-		if (!registry.plugins[pluginId]) {
-			registry.plugins[pluginId] = [];
-		}
+			const installPath = getPluginCachePath(pluginId, version, marketplace);
+			const now = new Date().toISOString();
 
-		// Find existing entry for this scope and project
-		const existingIndex = registry.plugins[pluginId].findIndex((entry) => {
-			if (entry.scope !== scope) return false;
-			if (scope === "user") return true;
-			return entry.projectPath === projectPath;
-		});
+			// Initialize plugin array if it doesn't exist
+			if (!registry.plugins[pluginId]) {
+				registry.plugins[pluginId] = [];
+			}
 
-		const entry: InstalledPluginEntry = {
-			scope,
-			projectPath,
-			installPath,
-			version,
-			installedAt:
-				existingIndex >= 0
-					? registry.plugins[pluginId][existingIndex].installedAt
-					: now,
-			lastUpdated: now,
-			gitCommitSha: await resolveCacheProvenance(
-				copiedFrom,
-				existingIndex >= 0
-					? registry.plugins[pluginId][existingIndex].gitCommitSha
-					: undefined,
-			),
-		};
+			// Find existing entry for this scope and project
+			const existingIndex = registry.plugins[pluginId].findIndex((entry) => {
+				if (entry.scope !== scope) return false;
+				if (scope === "user") return true;
+				return entry.projectPath === projectPath;
+			});
 
-		if (existingIndex >= 0) {
-			// Update existing entry
-			registry.plugins[pluginId][existingIndex] = entry;
-		} else {
-			// Add new entry
-			registry.plugins[pluginId].push(entry);
-		}
+			const entry: InstalledPluginEntry = {
+				scope,
+				projectPath,
+				installPath,
+				version,
+				installedAt:
+					existingIndex >= 0
+						? registry.plugins[pluginId][existingIndex].installedAt
+						: now,
+				lastUpdated: now,
+				gitCommitSha: await resolveCacheProvenance(
+					copiedFrom,
+					existingIndex >= 0
+						? registry.plugins[pluginId][existingIndex].gitCommitSha
+						: undefined,
+				),
+			};
 
-		await writeInstalledPluginsRegistry(registry);
+			if (existingIndex >= 0) {
+				// Update existing entry
+				registry.plugins[pluginId][existingIndex] = entry;
+			} else {
+				// Add new entry
+				registry.plugins[pluginId].push(entry);
+			}
+			return true;
+		});
 	} catch (error) {
-		// Log warning but don't block plugin operation
+		// Say what was refused and why, then let the plugin operation carry on:
+		// the install itself succeeded, and the registry is Claude Code's file to
+		// repair. What must not happen is writing over it, which is why the read
+		// throws rather than answering an empty registry.
 		console.warn(
 			`Failed to update registry for ${pluginId}:`,
 			error instanceof Error ? error.message : "Unknown error",
@@ -1700,23 +1919,24 @@ export async function removeFromInstalledPluginsRegistry(
 	projectPath?: string,
 ): Promise<void> {
 	try {
-		const registry = await readInstalledPluginsRegistry();
-
-		if (!registry.plugins[pluginId]) return;
+		await updateRegistryFile((registry) => {
+			if (!registry.plugins[pluginId]) return false;
+
+			// Remove entry matching scope and projectPath
+			registry.plugins[pluginId] = registry.plugins[pluginId].filter(
+				(entry) => {
+					if (entry.scope !== scope) return true;
+					if (scope === "user") return false;
+					return entry.projectPath !== projectPath;
+				},
+			);
 
-		// Remove entry matching scope and projectPath
-		registry.plugins[pluginId] = registry.plugins[pluginId].filter((entry) => {
-			if (entry.scope !== scope) return true;
-			if (scope === "user") return false;
-			return entry.projectPath !== projectPath;
+			// Remove plugin key if no entries remain
+			if (registry.plugins[pluginId].length === 0) {
+				delete registry.plugins[pluginId];
+			}
+			return true;
 		});
-
-		// Remove plugin key if no entries remain
-		if (registry.plugins[pluginId].length === 0) {
-			delete registry.plugins[pluginId];
-		}
-
-		await writeInstalledPluginsRegistry(registry);
 	} catch (error) {
 		// Log warning but don't block plugin operation
 		console.warn(
@@ -2050,12 +2270,17 @@ export async function repairStaleLoad(
 	// 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) {
+	if (before === null) return fail(`${file} does not exist`);
+	let registry: InstalledPluginsRegistry;
+	try {
+		registry = requireRegistry(file, before);
+	} catch (error) {
+		// The same check every other reader makes; a repair reports it as a result
+		// rather than throwing, because it is one item in a plan of many.
 		return fail(
-			before === null
-				? `${file} does not exist`
-				: `${file} is not a readable registry — refusing to write over it`,
+			`${file} is not a readable registry — refusing to write over it: ${
+				error instanceof Error ? error.message : String(error)
+			}`,
 		);
 	}
 	const rows = registry.plugins[pluginId];
@@ -2148,7 +2373,18 @@ export async function repairStaleLoad(
 
 	// 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);
+	// A refusal here is reported like every other outcome — this function answers
+	// with a result, and a plan of repairs must not be ended by a throw from one.
+	let after: InstalledPluginsRegistry;
+	try {
+		after = await readInstalledPluginsRegistry(root);
+	} catch (error) {
+		return fail(
+			`could not re-read ${file} to confirm the repair: ${
+				error instanceof Error ? error.message : String(error)
+			}`,
+		);
+	}
 	const loaded =
 		pickLoadedEntry(after.plugins[pluginId], projectPath)?.version ?? null;
 	if (loaded === target) {