magus-cli 7.4.0 → 7.5.0

package/src/__tests__/profile-absorb.test.ts

@@ -0,0 +1,1138 @@
+/**
+ * A Claude Code edit to the live config in a magus project IS a change to the
+ * active profile. It is written into `.claude/profiles.json` — never moved into
+ * a backup — and a change to profiles.json itself (a teammate's commit) is
+ * regenerated into the live config. Both at once are merged.
+ */
+
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { mkdtemp, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import fs from "fs-extra";
+import { switchProfile } from "../cli/profile.js";
+import { readManifest, writeManifest } from "../services/manifest.js";
+import type { ModelsConfig } from "../services/models-core.js";
+import { clearModels } from "../services/models-manager.js";
+import {
+	computeAbsorb,
+	losesNothing,
+	merge3,
+	reconcileActiveProfile,
+} from "../services/profile-absorb.js";
+import {
+	activateProfile,
+	regenerateLiveFiles,
+} from "../services/profile-activate.js";
+import {
+	backupRoot,
+	jsonEqual,
+	readActiveMarker,
+	writeActiveMarker,
+} from "../services/profile-live.js";
+import { renderProfile } from "../services/profile-render.js";
+import { withCliBookkeeping } from "../services/profile-state.js";
+import type { ProfileManifest, ProfileManifestEntry } from "../types/index.js";
+
+const ROUTING: ModelsConfig = {
+	version: 1,
+	preset: "test",
+	main: { model: "opus", effort: "medium" },
+	grades: {
+		smart: { model: "fable", effort: "xhigh" },
+		normal: { model: "opus", effort: "medium" },
+		cheap: { model: "sonnet", effort: "low" },
+	},
+	agents: { "dev:architect": "smart" },
+	fallback: "normal",
+};
+
+function baseManifest(): ProfileManifest {
+	return {
+		version: 2,
+		profiles: {
+			team: {
+				name: "Team",
+				plugins: { "dev@magus": "2.1.0", "terminal@magus": "latest" },
+				mcpServers: { srv: { command: "srv" } },
+			},
+			other: { name: "Other", plugins: { "designer@magus": "latest" } },
+		},
+	};
+}
+
+let project: string;
+let log: ReturnType<typeof spyOn>;
+
+const settingsPath = () => join(project, ".claude", "settings.json");
+const mcpPath = () => join(project, ".mcp.json");
+const modelsPath = () => join(project, ".claude", "models.json");
+
+async function start(manifest: ProfileManifest, profile = "team") {
+	await writeManifest(manifest, project);
+	await activateProfile(manifest, profile, project, { onDisplace: () => {} });
+}
+
+async function editLive(
+	file: string,
+	mutate: (json: Record<string, unknown>) => void,
+): Promise<void> {
+	const json = await fs.readJson(file);
+	mutate(json);
+	// Claude Code's writer formats differently from magus; the bytes change.
+	await fs.writeFile(file, JSON.stringify(json));
+}
+
+async function entry(name = "team"): Promise<ProfileManifestEntry> {
+	const manifest = await readManifest(project);
+	return manifest.profiles[name] as ProfileManifestEntry;
+}
+
+beforeEach(async () => {
+	project = await mkdtemp(join(tmpdir(), "absorb-"));
+	log = spyOn(console, "log").mockImplementation(() => {});
+});
+afterEach(async () => {
+	log.mockRestore();
+	await rm(project, { recursive: true, force: true });
+});
+
+describe("absorbing Claude Code's edits into the active profile", () => {
+	test("a plugin Claude Code installed is added to the profile", async () => {
+		await start(baseManifest());
+		await editLive(settingsPath(), (s) => {
+			(s.enabledPlugins as Record<string, boolean>)["code-search@magus"] = true;
+		});
+
+		const result = await reconcileActiveProfile(project);
+
+		expect(result.lines).toEqual(['Added code-search@magus to profile "team"']);
+		expect((await entry()).plugins).toEqual({
+			"dev@magus": "2.1.0",
+			"terminal@magus": "latest",
+			"code-search@magus": "latest",
+		});
+		// The live file still enables it — nothing was lost or backed up.
+		const live = await fs.readJson(settingsPath());
+		expect(live.enabledPlugins["code-search@magus"]).toBe(true);
+		expect(await fs.pathExists(backupRoot(project))).toBe(false);
+	});
+
+	test("an uninstalled plugin is removed; a pin elsewhere is kept", async () => {
+		await start(baseManifest());
+		await editLive(settingsPath(), (s) => {
+			// biome-ignore lint/performance/noDelete: `claude plugin uninstall` removes the key; undefined would not serialise the same
+			delete (s.enabledPlugins as Record<string, boolean>)["terminal@magus"];
+		});
+
+		const result = await reconcileActiveProfile(project);
+
+		expect(result.lines).toEqual([
+			'Removed terminal@magus from profile "team"',
+		]);
+		expect((await entry()).plugins).toEqual({ "dev@magus": "2.1.0" });
+	});
+
+	test("a plugin disabled here is recorded as false so it stays off", async () => {
+		await start(baseManifest());
+		await editLive(settingsPath(), (s) => {
+			(s.enabledPlugins as Record<string, boolean>)["terminal@magus"] = false;
+		});
+
+		await reconcileActiveProfile(project);
+
+		expect((await entry()).plugins?.["terminal@magus"]).toBe(false);
+		const rendered = await renderProfile(await readManifest(project), "team");
+		expect(
+			(rendered.settings.enabledPlugins as Record<string, boolean>)[
+				"terminal@magus"
+			],
+		).toBe(false);
+	});
+
+	test("a changed setting updates the profile's settings", async () => {
+		await start(baseManifest());
+		await editLive(settingsPath(), (s) => {
+			s.permissions = { allow: ["Bash(ls:*)"] };
+		});
+
+		const result = await reconcileActiveProfile(project);
+
+		expect(result.lines).toEqual(['Updated settings of profile "team"']);
+		expect((await entry()).settings).toEqual({
+			permissions: { allow: ["Bash(ls:*)"] },
+		});
+	});
+
+	test("an MCP server Claude Code added updates the profile's servers", async () => {
+		await start(baseManifest());
+		await editLive(mcpPath(), (m) => {
+			(m.mcpServers as Record<string, unknown>).added = { command: "added" };
+		});
+
+		const result = await reconcileActiveProfile(project);
+
+		expect(result.lines).toEqual(['Updated MCP servers of profile "team"']);
+		expect((await entry()).mcpServers).toEqual({
+			srv: { command: "srv" },
+			added: { command: "added" },
+		});
+	});
+
+	test("an edited models.json maps back to the profile's models field", async () => {
+		const manifest = baseManifest();
+		(manifest.profiles.team as ProfileManifestEntry).models = ROUTING;
+		await start(manifest);
+		await editLive(modelsPath(), (m) => {
+			(m.agents as Record<string, string>)["dev:developer"] = "cheap";
+		});
+
+		const result = await reconcileActiveProfile(project);
+
+		expect(result.lines).toEqual(['Updated model routing of profile "team"']);
+		const e = await entry();
+		expect(e.models?.agents).toEqual({
+			"dev:architect": "smart",
+			"dev:developer": "cheap",
+		});
+		expect(e.settings).toBeUndefined();
+	});
+
+	test("the marker records the absorbed file, so a second pass is a no-op", async () => {
+		await start(baseManifest());
+		await editLive(settingsPath(), (s) => {
+			(s.enabledPlugins as Record<string, boolean>)["code-search@magus"] = true;
+		});
+		await reconcileActiveProfile(project);
+		const manifestMtime = (
+			await stat(join(project, ".claude", "profiles.json"))
+		).mtimeMs;
+
+		const again = await reconcileActiveProfile(project);
+
+		expect(again.lines).toEqual([]);
+		expect(again.changes).toEqual([]);
+		expect(
+			(await stat(join(project, ".claude", "profiles.json"))).mtimeMs,
+		).toBe(manifestMtime);
+	});
+
+	test("machine-local installedPluginVersions is never absorbed and survives re-render", async () => {
+		await start(baseManifest());
+		await editLive(settingsPath(), (s) => {
+			s.installedPluginVersions = { "dev@magus": "2.1.0" };
+		});
+
+		const result = await reconcileActiveProfile(project);
+
+		expect(result.changes).toEqual([]);
+		expect((await entry()).settings).toBeUndefined();
+		expect((await fs.readJson(settingsPath())).installedPluginVersions).toEqual(
+			{ "dev@magus": "2.1.0" },
+		);
+	});
+
+	test("an unparseable live file is reported and left exactly as it is", async () => {
+		await start(baseManifest());
+		await fs.writeFile(settingsPath(), "{ not json");
+		const before = JSON.stringify(await readManifest(project));
+
+		const result = await reconcileActiveProfile(project);
+
+		expect(result.problems).toHaveLength(1);
+		expect(result.problems[0]).toContain(".claude/settings.json");
+		expect(await fs.readFile(settingsPath(), "utf8")).toBe("{ not json");
+		expect(JSON.stringify(await readManifest(project))).toBe(before);
+	});
+
+	test("a deleted live file is written again from the profile", async () => {
+		await start(baseManifest());
+		await fs.remove(mcpPath());
+
+		const result = await reconcileActiveProfile(project);
+
+		expect(result.lines).toEqual(['Restored .mcp.json from profile "team"']);
+		expect(await fs.readJson(mcpPath())).toEqual({
+			mcpServers: { srv: { command: "srv" } },
+		});
+	});
+});
+
+describe("round trip: render(absorb(live)) equals live", () => {
+	/** An entry as `magus models use` and a style leave it. */
+	function routedEntry(): ProfileManifestEntry {
+		return {
+			name: "Team",
+			plugins: { "dev@magus": "latest" },
+			settings: {
+				model: "opus",
+				effortLevel: "medium",
+				modelSettings: { opus: { effortLevel: "medium" } },
+				outputStyle: "composed-team",
+			},
+			models: ROUTING,
+		};
+	}
+
+	test("models routing and outputStyle map back to their own fields, once", async () => {
+		const manifest: ProfileManifest = {
+			version: 2,
+			profiles: { team: routedEntry() },
+		};
+		await start(manifest);
+		await editLive(settingsPath(), (s) => {
+			(s.enabledPlugins as Record<string, boolean>)["code-search@magus"] = true;
+			s.permissions = { allow: ["Read"] };
+			s.effortLevel = "high";
+		});
+
+		await reconcileActiveProfile(project);
+
+		const e = await entry();
+		// Routing stays in `models`, untouched; nothing of it leaks into settings.
+		expect(e.models).toEqual(ROUTING);
+		expect(Object.keys(e.settings ?? {}).sort()).toEqual([
+			"effortLevel",
+			"model",
+			"modelSettings",
+			"outputStyle",
+			"permissions",
+		]);
+		expect(e.settings?.outputStyle).toBe("composed-team");
+		expect(e.settings?.effortLevel).toBe("high");
+		expect("models" in (e.settings ?? {})).toBe(false);
+
+		// And rendering the absorbed entry reproduces the live config.
+		const rendered = await renderProfile(await readManifest(project), "team");
+		expect(
+			jsonEqual(rendered.settings, await fs.readJson(settingsPath())),
+		).toBe(true);
+		expect(jsonEqual(rendered.models, await fs.readJson(modelsPath()))).toBe(
+			true,
+		);
+	});
+
+	test("keys inherited through extends are not duplicated into settings", async () => {
+		const withExtends: ProfileManifestEntry = {
+			name: "Team",
+			extends: "must-have",
+			plugins: { "dev@magus": "latest" },
+			settings: { outputStyle: "composed-team" },
+		};
+		const manifest: ProfileManifest = {
+			version: 2,
+			profiles: { team: withExtends },
+		};
+		const rendered = await renderProfile(manifest, "team");
+		const live = structuredClone(rendered.settings);
+		(live.enabledPlugins as Record<string, boolean>)["code-search@magus"] =
+			true;
+		live.permissions = { allow: ["Read"] };
+
+		const { entry: absorbed } = computeAbsorb(
+			withExtends,
+			{ settings: live, mcp: rendered.mcp, models: null },
+			new Set(),
+		);
+
+		// Only what the profile itself says — never must-have's inherited keys.
+		expect(absorbed.settings).toEqual({
+			outputStyle: "composed-team",
+			permissions: { allow: ["Read"] },
+		});
+		expect(absorbed.plugins).toEqual({
+			"dev@magus": "latest",
+			"code-search@magus": "latest",
+		});
+		const again = await renderProfile(
+			{ version: 2, profiles: { team: absorbed } },
+			"team",
+		);
+		expect(jsonEqual(again.settings, live)).toBe(true);
+	});
+
+	test("disabling an inherited plugin is expressed as false and round-trips", () => {
+		const withExtends: ProfileManifestEntry = {
+			name: "Team",
+			extends: "must-have",
+		};
+		const live = {
+			enabledPlugins: { "setup@magus": false },
+		};
+		const { entry: absorbed, changes } = computeAbsorb(
+			withExtends,
+			{ settings: live, mcp: { mcpServers: {} }, models: null },
+			new Set(),
+		);
+		expect(absorbed.plugins?.["setup@magus"]).toBe(false);
+		expect(changes).toContainEqual({
+			kind: "plugin-removed",
+			plugin: "setup@magus",
+		});
+	});
+});
+
+describe("losesNothing", () => {
+	test("rendered may add false entries, never drop or change a key", () => {
+		const live = { enabledPlugins: { a: true }, x: 1 };
+		expect(
+			losesNothing("settings", live, {
+				enabledPlugins: { a: true, b: false },
+				x: 1,
+			}),
+		).toBe(true);
+		expect(
+			losesNothing("settings", live, { enabledPlugins: { a: true } }),
+		).toBe(false);
+		expect(
+			losesNothing("settings", live, {
+				enabledPlugins: { a: true, b: true },
+				x: 1,
+			}),
+		).toBe(false);
+	});
+});
+
+describe("merge3", () => {
+	test("local and remote changes to different keys both survive", () => {
+		const base: ProfileManifestEntry = {
+			name: "T",
+			plugins: { a: "latest" },
+			settings: { k: 1 },
+		};
+		const local: ProfileManifestEntry = {
+			name: "T",
+			plugins: { a: "latest", mine: "latest" },
+			settings: { k: 1 },
+		};
+		const remote: ProfileManifestEntry = {
+			name: "T renamed",
+			plugins: { a: "latest", theirs: "latest" },
+			settings: { k: 2 },
+		};
+		expect(merge3(base, local, remote)).toEqual({
+			entry: {
+				name: "T renamed",
+				plugins: { a: "latest", mine: "latest", theirs: "latest" },
+				settings: { k: 2 },
+			},
+			conflicts: [],
+		});
+	});
+
+	// Reviewer S7: `permissions` used to merge as one value, so a local allow
+	// rule and a teammate's deny rule could not both survive.
+	test("changes under the same top-level key merge recursively", () => {
+		const base: ProfileManifestEntry = {
+			name: "T",
+			settings: { permissions: { allow: ["Bash(bun test:*)"] } },
+		};
+		const local: ProfileManifestEntry = {
+			name: "T",
+			settings: { permissions: { allow: ["Bash(bun test:*)", "Bash(ls)"] } },
+		};
+		const remote: ProfileManifestEntry = {
+			name: "T",
+			settings: {
+				permissions: {
+					allow: ["Bash(bun test:*)"],
+					deny: ["Bash(rm -rf:*)"],
+				},
+			},
+		};
+		const { entry, conflicts } = merge3(base, local, remote);
+		expect(entry.settings).toEqual({
+			permissions: {
+				allow: ["Bash(bun test:*)", "Bash(ls)"],
+				deny: ["Bash(rm -rf:*)"],
+			},
+		});
+		expect(conflicts).toEqual([]);
+	});
+
+	test("arrays merge as sets: remote's additions, local's additions, local's removals", () => {
+		const base: ProfileManifestEntry = {
+			name: "T",
+			settings: { permissions: { allow: ["A", "B", "C"] } },
+		};
+		// Locally: removed B, added D. Remotely: removed C, added E.
+		const local: ProfileManifestEntry = {
+			name: "T",
+			settings: { permissions: { allow: ["A", "C", "D"] } },
+		};
+		const remote: ProfileManifestEntry = {
+			name: "T",
+			settings: { permissions: { allow: ["A", "B", "E"] } },
+		};
+		expect(merge3(base, local, remote).entry.settings).toEqual({
+			permissions: { allow: ["A", "E", "D"] },
+		});
+	});
+
+	test("a true leaf conflict keeps local and names the key path", () => {
+		const base: ProfileManifestEntry = {
+			name: "T",
+			settings: { permissions: { defaultMode: "default", allow: ["A"] } },
+		};
+		const local: ProfileManifestEntry = {
+			name: "T",
+			settings: { permissions: { defaultMode: "acceptEdits", allow: ["A"] } },
+		};
+		const remote: ProfileManifestEntry = {
+			name: "T",
+			settings: {
+				permissions: { defaultMode: "plan", allow: ["A", "B"] },
+			},
+		};
+		const { entry, conflicts } = merge3(base, local, remote);
+		expect(entry.settings).toEqual({
+			permissions: { defaultMode: "acceptEdits", allow: ["A", "B"] },
+		});
+		expect(conflicts).toEqual(["settings.permissions.defaultMode"]);
+	});
+
+	test("reviewer r11: an array of objects is one value — one hook edited on both sides is not duplicated", () => {
+		const hook = (command: string, timeout = 10) => ({
+			matcher: "Bash",
+			hooks: [{ type: "command", command, timeout }],
+		});
+		const base: ProfileManifestEntry = {
+			name: "T",
+			settings: { hooks: { PreToolUse: [hook("guard.sh")] } },
+		};
+		const local: ProfileManifestEntry = {
+			name: "T",
+			settings: { hooks: { PreToolUse: [hook("guard.sh --strict")] } },
+		};
+		const remote: ProfileManifestEntry = {
+			name: "T",
+			settings: { hooks: { PreToolUse: [hook("guard.sh", 30)] } },
+		};
+		const { entry: merged, conflicts } = merge3(base, local, remote);
+		expect(merged.settings).toEqual({
+			hooks: { PreToolUse: [hook("guard.sh --strict")] },
+		});
+		expect(conflicts).toEqual(["settings.hooks.PreToolUse"]);
+		// Only one side changed: that side's list, whole.
+		expect(merge3(base, base, remote).entry.settings).toEqual(remote.settings);
+		expect(merge3(base, local, base).entry.settings).toEqual(local.settings);
+	});
+
+	test('reviewer r11: a teammate\'s version pin beats an absorbed "latest" and is no conflict', () => {
+		const { entry: merged, conflicts } = merge3(
+			{ name: "T", plugins: {} },
+			{ name: "T", plugins: { "x@m": "latest" } },
+			{ name: "T", plugins: { "x@m": "1.4.0" } },
+		);
+		expect(merged.plugins).toEqual({ "x@m": "1.4.0" });
+		expect(conflicts).toEqual([]);
+		// Two different pins are still a conflict.
+		expect(
+			merge3(
+				{ name: "T", plugins: {} },
+				{ name: "T", plugins: { "x@m": "1.3.0" } },
+				{ name: "T", plugins: { "x@m": "1.4.0" } },
+			).conflicts,
+		).toEqual(["plugins.x@m"]);
+	});
+
+	test("an MCP server is merged whole: its args are a command line, not a set", () => {
+		const base: ProfileManifestEntry = {
+			name: "T",
+			mcpServers: { s: { command: "x", args: ["-a"] } },
+		};
+		const local: ProfileManifestEntry = {
+			name: "T",
+			mcpServers: { s: { command: "x", args: ["-a", "-b"] } },
+		};
+		const remote: ProfileManifestEntry = {
+			name: "T",
+			mcpServers: { s: { command: "x", args: ["-c"] } },
+		};
+		const { entry, conflicts } = merge3(base, local, remote);
+		expect(entry.mcpServers).toEqual({
+			s: { command: "x", args: ["-a", "-b"] },
+		});
+		expect(conflicts).toEqual(["mcpServers.s"]);
+	});
+});
+
+describe("a pulled change and a local edit under the same settings key", () => {
+	test("reviewer S7: the local allow rule and the teammate's deny rule both survive", async () => {
+		const manifest: ProfileManifest = {
+			version: 2,
+			profiles: {
+				team: {
+					name: "Team",
+					plugins: { "dev@magus": "latest" },
+					settings: { permissions: { allow: ["Bash(bun test:*)"] } },
+				},
+			},
+		};
+		await start(manifest);
+		await editLive(settingsPath(), (s) => {
+			(s.permissions as { allow: string[] }).allow.push("Bash(ls)");
+		});
+		const pulled = structuredClone(manifest);
+		(
+			pulled.profiles.team?.settings as { permissions: Record<string, unknown> }
+		).permissions.deny = ["Bash(rm -rf:*)"];
+		await writeManifest(pulled, project);
+
+		const result = await reconcileActiveProfile(project);
+
+		expect((await entry()).settings).toEqual({
+			permissions: {
+				allow: ["Bash(bun test:*)", "Bash(ls)"],
+				deny: ["Bash(rm -rf:*)"],
+			},
+		});
+		expect((await fs.readJson(settingsPath())).permissions).toEqual({
+			allow: ["Bash(bun test:*)", "Bash(ls)"],
+			deny: ["Bash(rm -rf:*)"],
+		});
+		expect(result.conflicts).toEqual([]);
+	});
+
+	test("reconcile: a plugin Claude Code enabled keeps the version a teammate pinned meanwhile", async () => {
+		await start(baseManifest());
+		await editLive(settingsPath(), (s) => {
+			(s.enabledPlugins as Record<string, boolean>)["code-search@magus"] = true;
+		});
+		const pulled = baseManifest();
+		(pulled.profiles.team as ProfileManifestEntry).plugins = {
+			...(pulled.profiles.team as ProfileManifestEntry).plugins,
+			"code-search@magus": "8.1.0",
+		};
+		await writeManifest(pulled, project);
+
+		const result = await reconcileActiveProfile(project);
+
+		expect((await entry()).plugins?.["code-search@magus"]).toBe("8.1.0");
+		expect(result.conflicts).toEqual([]);
+	});
+
+	test("a leaf changed differently on both sides keeps local, and says which key", async () => {
+		const manifest: ProfileManifest = {
+			version: 2,
+			profiles: {
+				team: {
+					name: "Team",
+					settings: { permissions: { defaultMode: "default" } },
+				},
+			},
+		};
+		await start(manifest);
+		await editLive(settingsPath(), (s) => {
+			(s.permissions as Record<string, unknown>).defaultMode = "acceptEdits";
+		});
+		const pulled = structuredClone(manifest);
+		(
+			pulled.profiles.team?.settings as { permissions: Record<string, unknown> }
+		).permissions.defaultMode = "plan";
+		await writeManifest(pulled, project);
+
+		const result = await reconcileActiveProfile(project);
+
+		expect(
+			((await entry()).settings as { permissions: Record<string, unknown> })
+				.permissions.defaultMode,
+		).toBe("acceptEdits");
+		expect(result.lines).toContain(
+			'Profile "team": settings.permissions.defaultMode was changed both here and in profiles.json — kept the local value; the other is in git history',
+		);
+	});
+});
+
+describe("regenerating when profiles.json changes underneath", () => {
+	test("a pulled change is regenerated into the live config, without a prompt or backup", async () => {
+		await start(baseManifest());
+		// A teammate's commit arrives by git pull.
+		const pulled = baseManifest();
+		(pulled.profiles.team as ProfileManifestEntry).plugins = {
+			...(pulled.profiles.team as ProfileManifestEntry).plugins,
+			"mnemex@magus": "latest",
+		};
+		await writeManifest(pulled, project);
+
+		const result = await reconcileActiveProfile(project);
+
+		expect(result.lines).toEqual([
+			'Profile "team" changed in profiles.json — regenerated .claude/settings.json',
+		]);
+		expect(
+			(await fs.readJson(settingsPath())).enabledPlugins["mnemex@magus"],
+		).toBe(true);
+		expect(await fs.pathExists(backupRoot(project))).toBe(false);
+		// Recorded: the next pass has nothing to do.
+		expect((await reconcileActiveProfile(project)).lines).toEqual([]);
+	});
+
+	test("a local edit alone is absorbed and nothing is regenerated", async () => {
+		await start(baseManifest());
+		await editLive(settingsPath(), (s) => {
+			(s.enabledPlugins as Record<string, boolean>)["code-search@magus"] = true;
+		});
+		const result = await reconcileActiveProfile(project);
+		expect(result.regenerated).toEqual([]);
+		expect(result.changes).toHaveLength(1);
+	});
+
+	test("both at once, touching different plugins: both survive", async () => {
+		await start(baseManifest());
+		// Locally, Claude Code installs code-search...
+		await editLive(settingsPath(), (s) => {
+			(s.enabledPlugins as Record<string, boolean>)["code-search@magus"] = true;
+		});
+		// ...while a teammate's commit adds mnemex and drops terminal.
+		const pulled = baseManifest();
+		(pulled.profiles.team as ProfileManifestEntry).plugins = {
+			"dev@magus": "2.1.0",
+			"mnemex@magus": "latest",
+		};
+		await writeManifest(pulled, project);
+
+		const result = await reconcileActiveProfile(project);
+
+		expect(result.lines[0]).toBe('Added code-search@magus to profile "team"');
+		expect(result.lines[1]).toContain(
+			'Profile "team" changed in profiles.json',
+		);
+		expect((await entry()).plugins).toEqual({
+			"dev@magus": "2.1.0",
+			"mnemex@magus": "latest",
+			"code-search@magus": "latest",
+		});
+		const enabled = (await fs.readJson(settingsPath())).enabledPlugins;
+		expect(enabled["code-search@magus"]).toBe(true);
+		expect(enabled["mnemex@magus"]).toBe(true);
+		expect(enabled["terminal@magus"]).toBeUndefined();
+		expect(enabled["dev@magus"]).toBe(true);
+		const marker = await readActiveMarker(project);
+		expect(marker?.base).toEqual(await entry());
+	});
+});
+
+describe("profile switch", () => {
+	test("absorbs into the OLD profile, then renders the new one with zero backups", async () => {
+		await start(baseManifest());
+		await editLive(settingsPath(), (s) => {
+			(s.enabledPlugins as Record<string, boolean>)["code-search@magus"] = true;
+		});
+
+		const code = await switchProfile("other", project);
+
+		expect(code).toBe(0);
+		expect((await entry("team")).plugins?.["code-search@magus"]).toBe("latest");
+		expect((await entry("other")).plugins).toEqual({
+			"designer@magus": "latest",
+		});
+		const live = await fs.readJson(settingsPath());
+		expect(live.enabledPlugins["designer@magus"]).toBe(true);
+		// code-search now belongs to "team", so "other" turns it off explicitly.
+		expect(live.enabledPlugins["code-search@magus"]).toBe(false);
+		expect(await fs.pathExists(backupRoot(project))).toBe(false);
+		expect((await readActiveMarker(project))?.profile).toBe("other");
+		const printed = log.mock.calls.map((c) => String(c[0])).join("\n");
+		expect(printed).toContain('Added code-search@magus to profile "team"');
+	});
+});
+
+describe("magus's own Claude CLI writes are not profile changes", () => {
+	test("regenerateLiveFiles renders over `claude plugin install` bookkeeping", async () => {
+		await start(baseManifest());
+		// `magus install` with no argument installs EVERY profile's plugins at
+		// project scope; the CLI records each in the live settings.json.
+		await editLive(settingsPath(), (s) => {
+			(s.enabledPlugins as Record<string, boolean>)["designer@magus"] = true;
+		});
+
+		expect(await regenerateLiveFiles(project)).toBe(true);
+
+		// "other" owns designer; "team" keeps it off, and the profile is unchanged.
+		expect(
+			(await fs.readJson(settingsPath())).enabledPlugins["designer@magus"],
+		).toBe(false);
+		expect((await entry()).plugins).toEqual(
+			baseManifest().profiles.team?.plugins as never,
+		);
+		expect((await reconcileActiveProfile(project)).lines).toEqual([]);
+	});
+});
+
+describe("the definition covers the whole render input", () => {
+	test("a pulled change to ANOTHER profile's plugins regenerates the active live file", async () => {
+		await start(baseManifest());
+		const before = await fs.readFile(settingsPath(), "utf8");
+		// A teammate adds a plugin to "other". "team" did not change, but its
+		// settings.json must now say `false` for it, or the plugin would fall
+		// through to user scope and stay on here.
+		const pulled = baseManifest();
+		(pulled.profiles.other as ProfileManifestEntry).plugins = {
+			"designer@magus": "latest",
+			"mnemex@magus": "latest",
+		};
+		await writeManifest(pulled, project);
+
+		const result = await reconcileActiveProfile(project);
+
+		expect(result.lines).toEqual([
+			'Another profile\'s plugins changed in profiles.json — regenerated .claude/settings.json for profile "team"',
+		]);
+		const live = await fs.readJson(settingsPath());
+		expect(live.enabledPlugins["mnemex@magus"]).toBe(false);
+		expect(await fs.readFile(settingsPath(), "utf8")).not.toBe(before);
+		// The active entry itself was not touched.
+		expect(await entry()).toEqual(baseManifest().profiles.team as never);
+		expect(await fs.pathExists(backupRoot(project))).toBe(false);
+		// Recorded: the next pass has nothing to do.
+		expect((await reconcileActiveProfile(project)).lines).toEqual([]);
+	});
+
+	test("a change to another profile that renders nothing here regenerates nothing", async () => {
+		await start(baseManifest());
+		const before = await fs.readFile(settingsPath(), "utf8");
+		const pulled = baseManifest();
+		(pulled.profiles.other as ProfileManifestEntry).mcpServers = {
+			theirs: { command: "theirs" },
+		};
+		await writeManifest(pulled, project);
+
+		const result = await reconcileActiveProfile(project);
+
+		expect(result.lines).toEqual([]);
+		expect(result.regenerated).toEqual([]);
+		expect(await fs.readFile(settingsPath(), "utf8")).toBe(before);
+	});
+});
+
+describe("the recorded profile no longer exists in profiles.json", () => {
+	/** Activate "ghost", then remove it from profiles.json, as a pull might. */
+	async function orphan(): Promise<void> {
+		const manifest: ProfileManifest = {
+			version: 2,
+			profiles: {
+				default: { name: "Default", plugins: { "dev@magus": "latest" } },
+				ghost: { name: "Ghost", plugins: { "terminal@magus": "latest" } },
+			},
+		};
+		await start(manifest, "ghost");
+		await writeManifest(
+			{
+				version: 2,
+				profiles: { default: manifest.profiles.default as never },
+			},
+			project,
+		);
+	}
+
+	test("switching keeps Claude Code's edit, in the target profile and the live file", async () => {
+		await orphan();
+		// Claude Code edits the live file while "ghost" is recorded.
+		await editLive(settingsPath(), (s) => {
+			s.spinnerTipsEnabled = false;
+			(s.enabledPlugins as Record<string, boolean>)["code-search@magus"] = true;
+		});
+
+		expect(await switchProfile("default", project)).toBe(0);
+
+		const e = await entry("default");
+		expect(e.settings).toEqual({ spinnerTipsEnabled: false });
+		expect(e.plugins).toEqual({
+			"dev@magus": "latest",
+			"code-search@magus": "latest",
+		});
+		// Only the EDIT moved over: ghost's own plugin did not.
+		expect(e.plugins?.["terminal@magus"]).toBeUndefined();
+		const live = await fs.readJson(settingsPath());
+		expect(live.spinnerTipsEnabled).toBe(false);
+		expect(live.enabledPlugins["code-search@magus"]).toBe(true);
+		expect(live.enabledPlugins["dev@magus"]).toBe(true);
+		expect((await readActiveMarker(project))?.profile).toBe("default");
+		expect(await fs.pathExists(backupRoot(project))).toBe(false);
+	});
+
+	test("the message names the vanished profile and the one that received its changes", async () => {
+		await orphan();
+		await editLive(settingsPath(), (s) => {
+			s.spinnerTipsEnabled = false;
+		});
+
+		await switchProfile("default", project);
+
+		const printed = log.mock.calls.map((c) => String(c[0])).join("\n");
+		expect(printed).toContain(
+			'Profile "ghost" no longer exists in profiles.json — its unsaved changes were added to profile "default"',
+		);
+		expect(printed).toContain('Updated settings of profile "default"');
+	});
+
+	test("with no recorded base, every key the live file holds is kept, and it says so", async () => {
+		await writeManifest(
+			{
+				version: 2,
+				profiles: {
+					default: { name: "Default", plugins: { "dev@magus": "latest" } },
+				},
+			},
+			project,
+		);
+		// An earlier release's marker: no definition, no base, stale hashes.
+		await fs.outputJson(join(project, ".claude", "_profiles", ".active"), {
+			version: 1,
+			profile: "ghost",
+			files: { settings: "stale" },
+		});
+		await fs.outputJson(settingsPath(), {
+			enabledPlugins: { "x@y": true },
+			spinnerTipsEnabled: false,
+		});
+
+		expect(await switchProfile("default", project)).toBe(0);
+
+		const e = await entry("default");
+		expect(e.plugins).toEqual({ "dev@magus": "latest", "x@y": "latest" });
+		expect(e.settings).toEqual({ spinnerTipsEnabled: false });
+		const live = await fs.readJson(settingsPath());
+		expect(live.spinnerTipsEnabled).toBe(false);
+		expect(live.enabledPlugins["x@y"]).toBe(true);
+		const printed = log.mock.calls.map((c) => String(c[0])).join("\n");
+		expect(printed).toContain('Profile "ghost" no longer exists');
+		expect(printed).toContain('There is no record of what "ghost" contained');
+	});
+
+	test("with nothing edited, switching changes no profile and says nothing about it", async () => {
+		await orphan();
+		await switchProfile("default", project);
+		const printed = log.mock.calls.map((c) => String(c[0])).join("\n");
+		expect(printed).not.toContain("no longer exists");
+		expect(await entry("default")).toEqual({
+			name: "Default",
+			plugins: { "dev@magus": "latest" },
+		});
+	});
+});
+
+describe("a live file that cannot be read is left exactly as it is", () => {
+	const broken =
+		'{\n  "enabledPlugins": { "team@magus": true },\n  "permissions": { "allow": ["Bash(make deploy)",] }\n}\n';
+
+	test("unparseable settings.json + a changed profiles.json: bytes unchanged, nothing written", async () => {
+		await start(baseManifest());
+		await fs.writeFile(settingsPath(), broken);
+		// A teammate's pull changes profiles.json — the case that used to
+		// regenerate right over the file the problem said was left alone.
+		const pulled = baseManifest();
+		(pulled.profiles.other as ProfileManifestEntry).plugins = {
+			"designer@magus": "latest",
+			"y@magus": "latest",
+		};
+		await writeManifest(pulled, project);
+		const manifestBefore = await fs.readFile(
+			join(project, ".claude", "profiles.json"),
+			"utf8",
+		);
+
+		const result = await reconcileActiveProfile(project);
+
+		expect(result.problems).toHaveLength(1);
+		expect(result.unreadable).toHaveLength(1);
+		expect(result.regenerated).toEqual([]);
+		expect(await fs.readFile(settingsPath(), "utf8")).toBe(broken);
+		expect(
+			await fs.readFile(join(project, ".claude", "profiles.json"), "utf8"),
+		).toBe(manifestBefore);
+	});
+
+	test("regenerateLiveFiles refuses rather than render over it", async () => {
+		await start(baseManifest());
+		await fs.writeFile(settingsPath(), broken);
+		await expect(regenerateLiveFiles(project)).rejects.toThrow(
+			/refusing to overwrite/,
+		);
+		expect(await fs.readFile(settingsPath(), "utf8")).toBe(broken);
+	});
+
+	test("clearModels (the TUI Models screen's call) refuses and writes nothing", async () => {
+		const manifest = baseManifest();
+		(manifest.profiles.team as ProfileManifestEntry).models = ROUTING;
+		await start(manifest);
+		await fs.writeFile(settingsPath(), broken);
+		const modelsBefore = await fs.readFile(modelsPath(), "utf8");
+		const configDir = await mkdtemp(join(tmpdir(), "absorb-config-"));
+		const previous = process.env.CLAUDE_CONFIG_DIR;
+		process.env.CLAUDE_CONFIG_DIR = configDir;
+		try {
+			await expect(clearModels(project)).rejects.toThrow(
+				/refusing to overwrite/,
+			);
+		} finally {
+			// biome-ignore lint/performance/noDelete: an unset env var must be absent, not "undefined"
+			if (previous === undefined) delete process.env.CLAUDE_CONFIG_DIR;
+			else process.env.CLAUDE_CONFIG_DIR = previous;
+			await rm(configDir, { recursive: true, force: true });
+		}
+		expect(await fs.readFile(settingsPath(), "utf8")).toBe(broken);
+		expect(await fs.readFile(modelsPath(), "utf8")).toBe(modelsBefore);
+		expect((await entry()).models).toEqual(ROUTING);
+	});
+});
+
+describe("the Claude CLI's install bookkeeping is never absorbed", () => {
+	/** What `claude plugin install --scope project` does to the live file. */
+	async function cliInstall(id: string): Promise<void> {
+		await editLive(settingsPath(), (s) => {
+			(s.enabledPlugins as Record<string, boolean>)[id] = true;
+		});
+	}
+
+	test("a throw part-way through the install loop still renders the profile over it", async () => {
+		await start(baseManifest());
+		await expect(
+			withCliBookkeeping(project, async () => {
+				await cliInstall("designer@magus");
+				throw new Error("interrupted");
+			}),
+		).rejects.toThrow("interrupted");
+
+		expect(
+			(await fs.readJson(settingsPath())).enabledPlugins["designer@magus"],
+		).toBe(false);
+		expect((await readActiveMarker(project))?.cliBookkeeping).toBeUndefined();
+		const next = await reconcileActiveProfile(project);
+		expect(next.lines).toEqual([]);
+		expect((await entry()).plugins).toEqual(
+			baseManifest().profiles.team?.plugins as never,
+		);
+	});
+
+	test("a run killed part-way leaves the flag, and the next reconcile discards only the bookkeeping", async () => {
+		await start(baseManifest());
+		const marker = await readActiveMarker(project);
+		if (!marker) throw new Error("no marker");
+		// What withCliBookkeeping writes before the loop; `finally` never ran.
+		await writeActiveMarker({ ...marker, cliBookkeeping: true }, project);
+		// The CLI's record: a plugin another profile names.
+		await cliInstall("designer@magus");
+		// ...and a real edit made meanwhile, which must still be kept.
+		await editLive(settingsPath(), (s) => {
+			s.permissions = { allow: ["Bash(ls)"] };
+		});
+
+		const result = await reconcileActiveProfile(project);
+
+		expect(result.lines[0]).toBe(
+			"An interrupted magus install left the Claude CLI's plugin records in .claude/settings.json — discarded them (designer@magus)",
+		);
+		const e = await entry();
+		expect(e.plugins).toEqual(baseManifest().profiles.team?.plugins as never);
+		expect(e.settings).toEqual({ permissions: { allow: ["Bash(ls)"] } });
+		const live = await fs.readJson(settingsPath());
+		expect(live.enabledPlugins["designer@magus"]).toBe(false);
+		expect(live.permissions).toEqual({ allow: ["Bash(ls)"] });
+		expect((await readActiveMarker(project))?.cliBookkeeping).toBeUndefined();
+	});
+
+	test("reviewer r9a: after a killed run, a plugin the user installed themselves is kept", async () => {
+		await start(baseManifest());
+		const marker = await readActiveMarker(project);
+		if (!marker) throw new Error("no marker");
+		await writeActiveMarker({ ...marker, cliBookkeeping: true }, project);
+		await cliInstall("designer@magus"); // the CLI, before the kill
+		await cliInstall("my-own@market"); // the user, afterwards — no profile names it
+		// ...and a `false` the user set is theirs too.
+		await editLive(settingsPath(), (s) => {
+			(s.enabledPlugins as Record<string, boolean>)["terminal@magus"] = false;
+		});
+
+		const result = await reconcileActiveProfile(project);
+
+		expect(result.lines).toContain('Added my-own@market to profile "team"');
+		expect(result.lines).toContain(
+			'Removed terminal@magus from profile "team"',
+		);
+		expect(result.lines.join("\n")).toContain(
+			"discarded them (designer@magus)",
+		);
+		expect((await entry()).plugins).toEqual({
+			"dev@magus": "2.1.0",
+			"terminal@magus": false,
+			"my-own@market": "latest",
+		});
+		const live = await fs.readJson(settingsPath());
+		expect(live.enabledPlugins["my-own@market"]).toBe(true);
+		expect(live.enabledPlugins["designer@magus"]).toBe(false);
+		expect(live.enabledPlugins["terminal@magus"]).toBe(false);
+	});
+
+	test("reviewer r9b: an edit Claude Code writes while the installs run is kept, not overwritten", async () => {
+		await start(baseManifest());
+		const reported: string[] = [];
+		await withCliBookkeeping(
+			project,
+			async () => {
+				await cliInstall("designer@magus"); // the CLI's record
+				await editLive(settingsPath(), (s) => {
+					s.permissions = { allow: ["Bash(make deploy)"] }; // "always allow"
+				});
+			},
+			{ report: (line) => reported.push(line) },
+		);
+
+		expect(reported).toEqual(['Updated settings of profile "team"']);
+		expect((await entry()).settings).toEqual({
+			permissions: { allow: ["Bash(make deploy)"] },
+		});
+		const live = await fs.readJson(settingsPath());
+		expect(live.permissions).toEqual({ allow: ["Bash(make deploy)"] });
+		expect(live.enabledPlugins["designer@magus"]).toBe(false);
+		expect((await readActiveMarker(project))?.cliBookkeeping).toBeUndefined();
+		expect((await reconcileActiveProfile(project)).lines).toEqual([]);
+	});
+});
+
+describe("a false left over from an older render is not a disable", () => {
+	test("reviewer S3: a teammate drops a plugin from another profile while an edit is pending", async () => {
+		const manifest: ProfileManifest = {
+			version: 2,
+			profiles: {
+				team: { name: "Team", plugins: { "dev@magus": "latest" } },
+				other: {
+					name: "Other",
+					plugins: { "terminal@magus": "latest", "x@magus": "latest" },
+				},
+			},
+		};
+		await start(manifest);
+		// The live file says `x@magus: false` — the render's own output.
+		await editLive(settingsPath(), (s) => {
+			s.permissions = { allow: ["Bash(ls)"] };
+		});
+		const pulled = structuredClone(manifest);
+		// biome-ignore lint/performance/noDelete: the teammate's edit removes the key from profiles.json
+		delete (pulled.profiles.other?.plugins as Record<string, unknown>)[
+			"x@magus"
+		];
+		await writeManifest(pulled, project);
+
+		const result = await reconcileActiveProfile(project);
+
+		expect(result.lines.join("\n")).not.toContain("Disabled x@magus");
+		expect((await entry()).plugins).toEqual({ "dev@magus": "latest" });
+		expect((await entry()).settings).toEqual({
+			permissions: { allow: ["Bash(ls)"] },
+		});
+		expect(
+			(await fs.readJson(settingsPath())).enabledPlugins["x@magus"],
+		).toBeUndefined();
+	});
+
+	test("the marker records the plugin ids the render wrote", async () => {
+		await start(baseManifest());
+		expect((await readActiveMarker(project))?.allPluginIds).toEqual([
+			"designer@magus",
+			"dev@magus",
+			"terminal@magus",
+		]);
+	});
+});