magus-cli 7.4.1 → 7.5.1

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

@@ -0,0 +1,1110 @@
+/**
+ * The strict active-profile check, the entry-point gate, older-layout
+ * conversion, and generated files git still tracks.
+ */
+
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+import { lstat, mkdtemp, readdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import fs from "fs-extra";
+import { ensureManifest, profileGate } from "../cli/bootstrap.js";
+import { reportProfileState, runDoctorCommand } from "../cli/doctor.js";
+import { runModelsCommand } from "../cli/models.js";
+import { route } from "../cli/router.js";
+import { installPlugin, uninstallPlugin } from "../services/claude-cli.js";
+import {
+	readSettings,
+	writeMcpConfig,
+	writeSettings,
+} from "../services/claude-settings.js";
+import { trackedByGit } from "../services/git-worktree.js";
+import { readManifest, writeManifest } from "../services/manifest.js";
+import type { ModelsConfig } from "../services/models-core.js";
+import { reconcileActiveProfile } from "../services/profile-absorb.js";
+import {
+	activateProfile,
+	regenerateLiveFiles,
+	trackedGeneratedFiles,
+} from "../services/profile-activate.js";
+import {
+	activeMarkerPath,
+	activeProfile,
+	backupRoot,
+	readActiveMarker,
+	sha256,
+	writeActiveMarker,
+} from "../services/profile-live.js";
+import { renderProfile } from "../services/profile-render.js";
+import {
+	applyProfileChoice,
+	checkActiveProfile,
+	prepareProfileState,
+	switchToProfile,
+} from "../services/profile-state.js";
+import { applyUserProfile } from "../services/profiles.js";
+import {
+	GitCheckError,
+	TrackedLiveFileError,
+} from "../services/tracked-live-files.js";
+import type { ProfileManifest } from "../types/index.js";
+
+const MANIFEST: ProfileManifest = {
+	version: 2,
+	profiles: {
+		team: { name: "Team", plugins: { "dev@magus": "latest" } },
+		other: { name: "Other", plugins: { "terminal@magus": "latest" } },
+	},
+};
+
+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",
+};
+
+let project: string;
+let wasTTY: boolean | undefined;
+let log: ReturnType<typeof spyOn>;
+let err: ReturnType<typeof spyOn>;
+
+const settingsPath = () => join(project, ".claude", "settings.json");
+const printed = () =>
+	[...log.mock.calls, ...err.mock.calls].map((c) => String(c[0])).join("\n");
+
+beforeEach(async () => {
+	project = await mkdtemp(join(tmpdir(), "state-"));
+	await writeManifest(MANIFEST, project);
+	wasTTY = process.stdin.isTTY;
+	Object.defineProperty(process.stdin, "isTTY", {
+		value: false,
+		configurable: true,
+	});
+	log = spyOn(console, "log").mockImplementation(() => {});
+	err = spyOn(console, "error").mockImplementation(() => {});
+});
+afterEach(async () => {
+	log.mockRestore();
+	err.mockRestore();
+	Object.defineProperty(process.stdin, "isTTY", {
+		value: wasTTY,
+		configurable: true,
+	});
+	await rm(project, { recursive: true, force: true });
+});
+
+describe("strict active-profile check", () => {
+	test("a marker naming a defined profile is active", async () => {
+		await activateProfile(MANIFEST, "team", project, { onDisplace: () => {} });
+		expect(await checkActiveProfile(project)).toEqual({
+			state: "active",
+			profile: "team",
+			restored: false,
+		});
+	});
+
+	test("a marker naming a profile profiles.json lacks is an error naming the fix", async () => {
+		await activateProfile(MANIFEST, "team", project, { onDisplace: () => {} });
+		await writeManifest(
+			{ version: 2, profiles: { other: MANIFEST.profiles.other as never } },
+			project,
+		);
+
+		expect(await checkActiveProfile(project)).toEqual({
+			state: "unknown",
+			profile: "team",
+			available: ["other"],
+			// The only profile left is the one to suggest.
+			suggested: "other",
+		});
+		expect(await activeProfile(project)).toBeNull();
+
+		// magus must not act on profile state...
+		expect(await profileGate(project)).toBe(false);
+		expect(printed()).toContain('recorded as "team"');
+		expect(printed()).toContain("`magus profile switch other`");
+		expect(printed()).not.toContain("<other>");
+		// ...except the command that fixes it.
+		expect(await profileGate(project, { allowUnknown: true })).toBe(true);
+	});
+
+	test("no marker, live config equal to exactly one profile: marker restored", async () => {
+		const rendered = await renderProfile(MANIFEST, "other");
+		await fs.outputJson(settingsPath(), rendered.settings);
+		await fs.writeJson(join(project, ".mcp.json"), rendered.mcp);
+
+		const prep = await prepareProfileState(project);
+
+		expect(prep.check).toEqual({
+			state: "active",
+			profile: "other",
+			restored: false,
+		});
+		expect(prep.lines[0]).toContain('matches profile "other" exactly');
+		expect((await readActiveMarker(project))?.profile).toBe("other");
+		expect(await activeProfile(project)).toBe("other");
+	});
+
+	test("no marker, live config matching no profile: non-interactive CLI stops with the instruction", async () => {
+		await fs.outputJson(settingsPath(), { enabledPlugins: { "x@y": true } });
+
+		expect(await checkActiveProfile(project)).toEqual({
+			state: "unmarked",
+			available: ["team", "other"],
+			liveFiles: true,
+			// Two profiles and no declared default: nothing to suggest.
+			suggested: null,
+			match: null,
+		});
+		// A command that writes profile state refuses rather than hanging.
+		expect(await runModelsCommand(["off"], project)).toBe(1);
+		expect(printed()).toContain(
+			"`magus profile switch <name>` (profiles: team, other)",
+		);
+		expect(await readActiveMarker(project)).toBeNull();
+	});
+
+	test("no manifest profiles at all is its own state", async () => {
+		await writeManifest({ version: 2, profiles: {} }, project);
+		expect(await checkActiveProfile(project)).toEqual({ state: "no-profiles" });
+	});
+});
+
+/** The profile directory an older layout's links point into. */
+const oldDir = () => join(project, ".claude", "_profiles", "team");
+
+/** Every `.claude/.magus-backups/*-layout` directory. */
+async function layoutBackups(): Promise<string[]> {
+	try {
+		return (await readdir(backupRoot(project))).filter((d) =>
+			d.endsWith("-layout"),
+		);
+	} catch {
+		return [];
+	}
+}
+
+describe("older layouts: Claude Code's edits are kept, the old directory is backed up", () => {
+	// magus 7.4.1: settings.json, .mcp.json and skills are links into
+	// `.claude/_profiles/team/`, and there is no marker. Claude Code before
+	// 2.1.280 wrote its edits THROUGH the links — they are in `_profiles/`.
+	async function stage741(): Promise<void> {
+		await fs.ensureDir(join(oldDir(), "skills"));
+		await fs.outputJson(join(oldDir(), "settings.json"), {
+			enabledPlugins: { "dev@magus": true, "code-search@magus": true },
+			permissions: { allow: ["Bash(bun test:*)"] },
+		});
+		await fs.outputJson(join(oldDir(), "mcp.json"), {
+			mcpServers: { db: { command: "pg-mcp" } },
+		});
+		await fs.symlink(
+			"_profiles/team/settings.json",
+			join(project, ".claude", "settings.json"),
+		);
+		await fs.symlink(
+			".claude/_profiles/team/mcp.json",
+			join(project, ".mcp.json"),
+		);
+		await fs.symlink(
+			"_profiles/team/skills",
+			join(project, ".claude", "skills"),
+		);
+	}
+
+	test("7.4.1 layout: a plugin, an allow rule and an MCP server written through the links survive conversion", async () => {
+		await stage741();
+		expect((await checkActiveProfile(project)).state).toBe("old-layout");
+
+		const prep = await prepareProfileState(project);
+
+		expect(prep.problems).toEqual([]);
+		expect(prep.lines).toContain(
+			'Changes Claude Code made under the older layout were added to profile "team"',
+		);
+		expect(prep.lines).toContain('Added code-search@magus to profile "team"');
+		expect(prep.lines).toContain(
+			'Converted profile "team" from the older layout to real files',
+		);
+		// In profiles.json...
+		const team = (await readManifest(project)).profiles.team;
+		expect(team?.plugins).toEqual({
+			"dev@magus": "latest",
+			"code-search@magus": "latest",
+		});
+		expect(team?.settings).toEqual({
+			permissions: { allow: ["Bash(bun test:*)"] },
+		});
+		expect(team?.mcpServers).toEqual({ db: { command: "pg-mcp" } });
+		// ...and in the live files, which are real files now.
+		for (const rel of [
+			".claude/settings.json",
+			".mcp.json",
+			".claude/skills",
+		]) {
+			expect((await lstat(join(project, rel))).isSymbolicLink()).toBe(false);
+		}
+		const live = await fs.readJson(settingsPath());
+		expect(live.enabledPlugins["code-search@magus"]).toBe(true);
+		expect(live.permissions).toEqual({ allow: ["Bash(bun test:*)"] });
+		expect(await fs.readJson(join(project, ".mcp.json"))).toEqual({
+			mcpServers: { db: { command: "pg-mcp" } },
+		});
+		// The old directory was moved, not deleted, and the run said where.
+		expect(await fs.pathExists(join(project, ".claude", "_profiles"))).toBe(
+			false,
+		);
+		const kept = await layoutBackups();
+		expect(kept).toHaveLength(1);
+		const keptDir = join(backupRoot(project), kept[0] as string);
+		expect(await fs.readJson(join(keptDir, "team", "settings.json"))).toEqual({
+			enabledPlugins: { "dev@magus": true, "code-search@magus": true },
+			permissions: { allow: ["Bash(bun test:*)"] },
+		});
+		expect(prep.lines.join("\n")).toContain(
+			`was kept at .claude/.magus-backups/${kept[0]}/`,
+		);
+		expect(await readdir(join(project, ".claude", "profiles"))).toEqual([
+			"active.json",
+		]);
+	});
+
+	test("the release before (7b330366): real files, marker at _profiles/.active, symlinked models.json", async () => {
+		const withRouting = structuredClone(MANIFEST);
+		(withRouting.profiles.team as { models?: unknown }).models = ROUTING;
+		await writeManifest(withRouting, project);
+		const rendered = await renderProfile(withRouting, "team");
+		// Real settings.json with a Claude Code edit; an unedited .mcp.json.
+		const edited = structuredClone(rendered.settings);
+		(edited.enabledPlugins as Record<string, boolean>)["code-search@magus"] =
+			true;
+		edited.permissions = { allow: ["Read"] };
+		await fs.outputFile(settingsPath(), JSON.stringify(edited));
+		const mcpBytes = `${JSON.stringify(rendered.mcp, null, 2)}\n`;
+		await fs.writeFile(join(project, ".mcp.json"), mcpBytes);
+		// models.json and skills were still links; a hand edit went through.
+		await fs.ensureDir(join(oldDir(), "skills"));
+		const editedRouting = structuredClone(ROUTING);
+		editedRouting.agents = { "dev:developer": "cheap" };
+		await fs.outputJson(join(oldDir(), "models.json"), editedRouting);
+		await fs.symlink(
+			"_profiles/team/models.json",
+			join(project, ".claude", "models.json"),
+		);
+		await fs.symlink(
+			"_profiles/team/skills",
+			join(project, ".claude", "skills"),
+		);
+		await fs.outputJson(join(project, ".claude", "_profiles", ".active"), {
+			version: 1,
+			profile: "team",
+			files: { settings: "stale", mcp: sha256(mcpBytes) },
+		});
+
+		const prep = await prepareProfileState(project);
+
+		expect(prep.problems).toEqual([]);
+		expect(prep.lines).toContain('Added code-search@magus to profile "team"');
+		const team = (await readManifest(project)).profiles.team;
+		expect(team?.plugins?.["code-search@magus"]).toBe("latest");
+		expect(team?.settings).toEqual({ permissions: { allow: ["Read"] } });
+		// The routing file disagrees with profiles.json: profiles.json's value
+		// stands, the key is named, and the older copy is in the backup.
+		expect(team?.models?.agents).toEqual({ "dev:architect": "smart" });
+		expect(prep.lines).toContain(
+			'Profile "team": models differs between the older layout and profiles.json — kept profiles.json\'s value; the older copy is in the -layout backup under .claude/.magus-backups/',
+		);
+		const live = await fs.readJson(settingsPath());
+		expect(live.enabledPlugins["code-search@magus"]).toBe(true);
+		expect(live.permissions).toEqual({ allow: ["Read"] });
+		expect(
+			(await lstat(join(project, ".claude", "models.json"))).isSymbolicLink(),
+		).toBe(false);
+		expect(
+			(await fs.readJson(join(project, ".claude", "models.json"))).agents,
+		).toEqual({ "dev:architect": "smart" });
+		expect(
+			(await lstat(join(project, ".claude", "skills"))).isDirectory(),
+		).toBe(true);
+		expect(await fs.pathExists(join(project, ".claude", "_profiles"))).toBe(
+			false,
+		);
+		const kept = await layoutBackups();
+		expect(kept).toHaveLength(1);
+		expect(
+			await fs.pathExists(
+				join(backupRoot(project), kept[0] as string, ".active"),
+			),
+		).toBe(true);
+		expect(await fs.pathExists(activeMarkerPath(project))).toBe(true);
+	});
+
+	test("reviewer r8: a teammate's change pulled after the last 7.4.1 install is not reverted", async () => {
+		// profiles.json NOW, after a pull: a teammate added a plugin, a deny rule
+		// and an MCP server to "team", and removed z@magus from "other".
+		const pulled: ProfileManifest = {
+			version: 2,
+			profiles: {
+				team: {
+					name: "Team",
+					plugins: { "dev@magus": "latest", "new-p@magus": "latest" },
+					settings: {
+						permissions: {
+							allow: ["Bash(bun test:*)"],
+							deny: ["Bash(rm -rf:*)"],
+						},
+					},
+					mcpServers: { team: { command: "team-mcp" } },
+				},
+				other: { name: "Other", plugins: { "terminal@magus": "latest" } },
+			},
+		};
+		await writeManifest(pulled, project);
+		// The 7.4.1 files, rendered from the OLD entry, plus Claude Code's edits.
+		await fs.ensureDir(join(oldDir(), "skills"));
+		await fs.outputJson(join(oldDir(), "settings.json"), {
+			enabledPlugins: {
+				"dev@magus": true,
+				"terminal@magus": false,
+				"z@magus": false,
+				"code-search@magus": true,
+			},
+			permissions: { allow: ["Bash(bun test:*)", "Bash(ls)"] },
+		});
+		await fs.outputJson(join(oldDir(), "mcp.json"), { mcpServers: {} });
+		// 7.4.1 materialized every profile: "other"'s render still names z@magus.
+		await fs.outputJson(
+			join(project, ".claude", "_profiles", "other", "settings.json"),
+			{
+				enabledPlugins: {
+					"dev@magus": false,
+					"terminal@magus": true,
+					"z@magus": true,
+				},
+			},
+		);
+		await fs.symlink(
+			"_profiles/team/settings.json",
+			join(project, ".claude", "settings.json"),
+		);
+		await fs.symlink(
+			".claude/_profiles/team/mcp.json",
+			join(project, ".mcp.json"),
+		);
+		await fs.symlink(
+			"_profiles/team/skills",
+			join(project, ".claude", "skills"),
+		);
+
+		const prep = await prepareProfileState(project);
+
+		const team = (await readManifest(project)).profiles.team;
+		// The teammate's additions all stand...
+		expect(team?.plugins).toEqual({
+			"dev@magus": "latest",
+			"new-p@magus": "latest",
+			"code-search@magus": "latest",
+		});
+		expect(team?.settings).toEqual({
+			permissions: {
+				allow: ["Bash(bun test:*)", "Bash(ls)"],
+				deny: ["Bash(rm -rf:*)"],
+			},
+		});
+		expect(team?.mcpServers).toEqual({ team: { command: "team-mcp" } });
+		// ...no stale `false` is written, and nothing is blamed on Claude Code
+		// that it did not add.
+		expect(team?.plugins?.["z@magus"]).toBeUndefined();
+		const lines = prep.lines.join("\n");
+		expect(lines).not.toContain("Removed new-p@magus");
+		expect(lines).not.toContain("Disabled z@magus");
+		expect(lines).toContain('Added code-search@magus to profile "team"');
+		// Removals are not applied, and the run says so, once.
+		expect(
+			prep.lines.filter((l) =>
+				l.includes("a removal made under the older layout is not applied"),
+			),
+		).toHaveLength(1);
+		const live = await fs.readJson(settingsPath());
+		expect(live.enabledPlugins["new-p@magus"]).toBe(true);
+		expect(live.permissions.deny).toEqual(["Bash(rm -rf:*)"]);
+	});
+
+	test("where the old file and profiles.json hold different values, profiles.json's stands and the key is named", async () => {
+		await writeManifest(
+			{
+				version: 2,
+				profiles: {
+					team: {
+						name: "Team",
+						plugins: { "dev@magus": "latest" },
+						settings: {
+							model: "opus",
+							permissions: { defaultMode: "plan" },
+						},
+						mcpServers: { db: { command: "pg-mcp", args: ["--new"] } },
+					},
+				},
+			},
+			project,
+		);
+		await stage741();
+		await fs.outputJson(join(oldDir(), "settings.json"), {
+			enabledPlugins: { "dev@magus": true },
+			model: "sonnet",
+			permissions: { defaultMode: "acceptEdits", allow: ["Read"] },
+		});
+		await fs.outputJson(join(oldDir(), "mcp.json"), {
+			mcpServers: { db: { command: "pg-mcp", args: ["--old"] } },
+		});
+
+		const prep = await prepareProfileState(project);
+
+		const team = (await readManifest(project)).profiles.team;
+		expect(team?.settings).toEqual({
+			model: "opus",
+			permissions: { defaultMode: "plan", allow: ["Read"] },
+		});
+		expect(team?.mcpServers).toEqual({
+			db: { command: "pg-mcp", args: ["--new"] },
+		});
+		for (const at of [
+			"settings.model",
+			"settings.permissions.defaultMode",
+			"mcpServers.db",
+		]) {
+			expect(prep.lines).toContain(
+				`Profile "team": ${at} differs between the older layout and profiles.json — kept profiles.json's value; the older copy is in the -layout backup under .claude/.magus-backups/`,
+			);
+		}
+		// The older copy really is in the backup.
+		const kept = await layoutBackups();
+		expect(
+			(
+				await fs.readJson(
+					join(backupRoot(project), kept[0] as string, "team", "settings.json"),
+				)
+			).model,
+		).toBe("sonnet");
+	});
+
+	/** A 7.4.1 layout where "team" is live and "other"'s dir holds its render. */
+	async function stage741WithOther(
+		teamSettings: Record<string, unknown>,
+		otherSettings: Record<string, unknown>,
+	): Promise<void> {
+		await fs.ensureDir(join(oldDir(), "skills"));
+		await fs.outputJson(join(oldDir(), "settings.json"), teamSettings);
+		await fs.outputJson(join(oldDir(), "mcp.json"), { mcpServers: {} });
+		await fs.outputJson(
+			join(project, ".claude", "_profiles", "other", "settings.json"),
+			otherSettings,
+		);
+		await fs.symlink(
+			"_profiles/team/settings.json",
+			join(project, ".claude", "settings.json"),
+		);
+		await fs.symlink(
+			".claude/_profiles/team/mcp.json",
+			join(project, ".mcp.json"),
+		);
+		await fs.symlink(
+			"_profiles/team/skills",
+			join(project, ".claude", "skills"),
+		);
+	}
+
+	test("reviewer r12c: a user's own disable of a plugin no profile named is kept", async () => {
+		await stage741WithOther(
+			{
+				enabledPlugins: {
+					"dev@magus": true,
+					"terminal@magus": false,
+					"noisy@user-mkt": false,
+				},
+			},
+			{ enabledPlugins: { "dev@magus": false, "terminal@magus": true } },
+		);
+
+		const prep = await prepareProfileState(project);
+
+		expect(prep.lines).toContain('Disabled noisy@user-mkt in profile "team"');
+		const team = (await readManifest(project)).profiles.team;
+		expect(team?.plugins).toEqual({
+			"dev@magus": "latest",
+			"noisy@user-mkt": false,
+		});
+		// terminal@magus: false was the render's own output — not added.
+		expect(team?.plugins?.["terminal@magus"]).toBeUndefined();
+		const live = await fs.readJson(settingsPath());
+		expect(live.enabledPlugins["noisy@user-mkt"]).toBe(false);
+	});
+
+	test("a false the older render wrote — the id is in another profile's old file — is skipped", async () => {
+		// gone@magus was in "other" at the 7.4.1 render and has since been
+		// removed from profiles.json, so the current manifest does not name it.
+		await stage741WithOther(
+			{ enabledPlugins: { "dev@magus": true, "gone@magus": false } },
+			{
+				enabledPlugins: {
+					"dev@magus": false,
+					"terminal@magus": true,
+					"gone@magus": true,
+				},
+			},
+		);
+
+		const prep = await prepareProfileState(project);
+
+		expect(prep.lines.join("\n")).not.toContain("gone@magus");
+		expect((await readManifest(project)).profiles.team?.plugins).toEqual({
+			"dev@magus": "latest",
+		});
+		expect(
+			(await fs.readJson(settingsPath())).enabledPlugins["gone@magus"],
+		).toBeUndefined();
+	});
+
+	test("an older layout file that cannot be read stops the conversion, and nothing moves", async () => {
+		await stage741();
+		const broken = '{ "enabledPlugins": { "dev@magus": true, } }';
+		await fs.writeFile(join(oldDir(), "settings.json"), broken);
+
+		const prep = await prepareProfileState(project);
+
+		expect(prep.problems).toHaveLength(1);
+		expect(prep.problems[0]).toContain("did not convert it");
+		expect(
+			(await lstat(join(project, ".claude", "settings.json"))).isSymbolicLink(),
+		).toBe(true);
+		expect(await fs.readFile(join(oldDir(), "settings.json"), "utf8")).toBe(
+			broken,
+		);
+		expect(await layoutBackups()).toEqual([]);
+	});
+
+	test("magus doctor without --fix converts nothing and writes nothing", async () => {
+		await stage741();
+		const snapshot = async () => ({
+			manifest: await fs.readFile(
+				join(project, ".claude", "profiles.json"),
+				"utf8",
+			),
+			settingsIsLink: (
+				await lstat(join(project, ".claude", "settings.json"))
+			).isSymbolicLink(),
+			old: await fs.readFile(join(oldDir(), "settings.json"), "utf8"),
+			claude: (await readdir(join(project, ".claude"))).sort(),
+		});
+		const before = await snapshot();
+		const cwd = process.cwd();
+		const home = await mkdtemp(join(tmpdir(), "state-doctor-home-"));
+		const saved = {
+			HOME: process.env.HOME,
+			CLAUDE_CONFIG_DIR: process.env.CLAUDE_CONFIG_DIR,
+		};
+		process.env.HOME = home;
+		process.env.CLAUDE_CONFIG_DIR = join(home, ".claude");
+		process.chdir(project);
+		try {
+			await runDoctorCommand([]);
+		} finally {
+			process.chdir(cwd);
+			process.env.HOME = saved.HOME;
+			if (saved.CLAUDE_CONFIG_DIR === undefined) {
+				// biome-ignore lint/performance/noDelete: an unset env var must be absent, not "undefined"
+				delete process.env.CLAUDE_CONFIG_DIR;
+			} else process.env.CLAUDE_CONFIG_DIR = saved.CLAUDE_CONFIG_DIR;
+			await rm(home, { recursive: true, force: true });
+		}
+
+		expect(await snapshot()).toEqual(before);
+		expect(printed()).toContain("is on an older magus layout");
+		expect(await fs.pathExists(activeMarkerPath(project))).toBe(false);
+	});
+
+	test("doctor without --fix: no marker, live config matching one profile — one line, not an error", async () => {
+		const rendered = await renderProfile(MANIFEST, "other");
+		await fs.outputJson(settingsPath(), rendered.settings);
+		await fs.writeJson(join(project, ".mcp.json"), rendered.mcp);
+		// The profile section alone: doctor's other sections read this machine's
+		// real plugin registry, so the whole command's exit code would test the
+		// machine. This section's counts are what it adds to that exit code.
+		const counts = await reportProfileState(project, false);
+
+		const out = printed();
+		expect(out).toContain(
+			'No active-profile marker, but the live config matches profile "other" exactly',
+		);
+		// The contradicting line is gone, and so is the failure.
+		expect(out).not.toContain("matches no single profile");
+		expect(counts).toEqual({ fixable: 0, unfixable: 0 });
+		// Report only: the marker is not restored.
+		expect(await readActiveMarker(project)).toBeNull();
+	});
+
+	test("a directory under .claude/profiles/ that is not magus's survives (reviewer S4)", async () => {
+		await activateProfile(MANIFEST, "team", project, { onDisplace: () => {} });
+		await fs.outputFile(
+			join(project, ".claude", "profiles", "notes", "README.md"),
+			"not magus's",
+		);
+
+		const prep = await prepareProfileState(project);
+
+		expect(prep.lines).toEqual([]);
+		expect(
+			await fs.readFile(
+				join(project, ".claude", "profiles", "notes", "README.md"),
+				"utf8",
+			),
+		).toBe("not magus's");
+		expect((await checkActiveProfile(project)).state).toBe("active");
+	});
+});
+
+function git(cwd: string, ...args: string[]) {
+	return spawnSync(
+		"git",
+		[
+			"-c",
+			"user.email=test@example.com",
+			"-c",
+			"user.name=test",
+			"-c",
+			"commit.gpgsign=false",
+			...args,
+		],
+		{ cwd, encoding: "utf8" },
+	);
+}
+
+describe("generated files git still tracks", () => {
+	/** A repo that committed profiles.json AND settings.json, like magus-src. */
+	async function commitTrackedSettings(): Promise<void> {
+		expect(git(project, "init", "-q").status).toBe(0);
+		await fs.outputJson(settingsPath(), {
+			enabledPlugins: { "dev@magus": true },
+			installedPluginVersions: { "dev@magus": "8.0.0" },
+		});
+		git(project, "add", ".claude/settings.json", ".claude/profiles.json");
+		expect(git(project, "commit", "-q", "-m", "init").status).toBe(0);
+	}
+
+	/** Everything B1 says must not change when magus refuses. */
+	async function untouched(): Promise<void> {
+		expect(git(project, "status", "--porcelain").stdout).toBe("");
+		expect(await fs.pathExists(join(project, ".claude", "profiles"))).toBe(
+			false,
+		);
+		expect(await fs.pathExists(backupRoot(project))).toBe(false);
+		expect(await fs.pathExists(join(project, ".gitignore"))).toBe(false);
+	}
+
+	test("B1: activating over a tracked settings.json writes nothing and names the fix", async () => {
+		await commitTrackedSettings();
+
+		const error = await activateProfile(MANIFEST, "team", project, {
+			onDisplace: () => {},
+		}).then(
+			() => null,
+			(e: unknown) => e,
+		);
+
+		expect(error).toBeInstanceOf(TrackedLiveFileError);
+		const message = (error as Error).message;
+		expect(message).toContain(".claude/settings.json");
+		expect(message).toContain("git rm --cached .claude/settings.json");
+		expect(message).toContain("Nothing was changed.");
+		await untouched();
+	});
+
+	test("B1: the gate, the switch path and a startup choice all refuse, writing nothing", async () => {
+		await commitTrackedSettings();
+
+		const prep = await prepareProfileState(project);
+		expect(prep.refusal).toBeInstanceOf(TrackedLiveFileError);
+		expect(prep.problems[0]).toContain("git rm --cached .claude/settings.json");
+		expect(await profileGate(project)).toBe(false);
+
+		const switched = await switchToProfile(project, "other", {
+			onDisplace: () => {},
+		});
+		expect(switched.activation).toBeNull();
+		expect(switched.problems[0]).toContain(".claude/settings.json");
+
+		for (const choice of [
+			{ kind: "activate", id: "team" },
+			{ kind: "adopt", id: "default-2" },
+		] as const) {
+			await expect(
+				applyProfileChoice(choice, MANIFEST, project, { onDisplace: () => {} }),
+			).rejects.toBeInstanceOf(TrackedLiveFileError);
+		}
+		await untouched();
+	});
+
+	test("B1: the CLI router exits 1 for `magus profile switch`, and writes nothing", async () => {
+		await commitTrackedSettings();
+		const cwd = process.cwd();
+		process.chdir(project);
+		let outcome: Awaited<ReturnType<typeof route>>;
+		try {
+			outcome = await route(["profile", "switch", "other"], "0.0.0-test");
+		} finally {
+			process.chdir(cwd);
+		}
+		expect(outcome.exitCode).toBe(1);
+		expect(printed()).toContain("git rm --cached .claude/settings.json");
+		await untouched();
+	});
+
+	test("B1: once settings.json is tracked, a pulled change regenerates nothing", async () => {
+		expect(git(project, "init", "-q").status).toBe(0);
+		await activateProfile(MANIFEST, "team", project, { onDisplace: () => {} });
+		// Somebody commits the generated file after all.
+		git(project, "add", "-f", ".claude/settings.json");
+		git(project, "add", ".claude/profiles.json");
+		expect(git(project, "commit", "-q", "-m", "oops").status).toBe(0);
+		const before = await fs.readFile(settingsPath(), "utf8");
+		// A teammate's pull changes the profile.
+		const pulled = structuredClone(MANIFEST);
+		(pulled.profiles.team as { plugins: Record<string, string> }).plugins[
+			"mnemex@magus"
+		] = "latest";
+		await writeManifest(pulled, project);
+		const manifestBefore = await fs.readFile(
+			join(project, ".claude", "profiles.json"),
+			"utf8",
+		);
+
+		const prep = await prepareProfileState(project);
+		expect(prep.problems[0]).toContain("git rm --cached .claude/settings.json");
+		expect((await reconcileActiveProfile(project)).problems[0]).toContain(
+			".claude/settings.json",
+		);
+		await expect(regenerateLiveFiles(project)).rejects.toBeInstanceOf(
+			TrackedLiveFileError,
+		);
+		expect(await fs.readFile(settingsPath(), "utf8")).toBe(before);
+		expect(
+			await fs.readFile(join(project, ".claude", "profiles.json"), "utf8"),
+		).toBe(manifestBefore);
+	});
+
+	test("B1: after `git rm --cached` and a commit, activation proceeds and keeps the committed profiles.json", async () => {
+		await commitTrackedSettings();
+		git(project, "rm", "-q", "--cached", ".claude/settings.json");
+		expect(git(project, "commit", "-q", "-m", "untrack").status).toBe(0);
+		const manifestBytes = await fs.readFile(
+			join(project, ".claude", "profiles.json"),
+			"utf8",
+		);
+
+		await activateProfile(MANIFEST, "team", project, { onDisplace: () => {} });
+
+		expect((await lstat(settingsPath())).isFile()).toBe(true);
+		expect((await readActiveMarker(project))?.profile).toBe("team");
+		expect(
+			await fs.readFile(join(project, ".claude", "profiles.json"), "utf8"),
+		).toBe(manifestBytes);
+	});
+
+	test("B1: adopting a repo with no profiles.json and a tracked settings.json writes nothing", async () => {
+		await fs.remove(join(project, ".claude", "profiles.json"));
+		expect(git(project, "init", "-q").status).toBe(0);
+		await fs.outputJson(settingsPath(), {
+			enabledPlugins: { "dev@magus": true },
+		});
+		git(project, "add", ".claude/settings.json");
+		expect(git(project, "commit", "-q", "-m", "init").status).toBe(0);
+		const home = await mkdtemp(join(tmpdir(), "state-adopt-home-"));
+		const savedHome = process.env.HOME;
+		process.env.HOME = home;
+		try {
+			await expect(
+				ensureManifest(project, { allowAdopt: true }),
+			).rejects.toBeInstanceOf(TrackedLiveFileError);
+		} finally {
+			process.env.HOME = savedHome;
+			await rm(home, { recursive: true, force: true });
+		}
+		expect(await fs.pathExists(join(project, ".claude", "profiles.json"))).toBe(
+			false,
+		);
+		await untouched();
+	});
+
+	test("B1: doctor counts a tracked live file as a problem", async () => {
+		await commitTrackedSettings();
+		const counts = await reportProfileState(project, false);
+		expect(counts.unfixable).toBeGreaterThan(0);
+		expect(printed()).toContain("git rm --cached .claude/settings.json");
+		await untouched();
+	});
+
+	test("review M1: writeSettings and writeMcpConfig refuse a tracked live file and leave it as it is", async () => {
+		await commitTrackedSettings();
+		await fs.outputJson(join(project, ".mcp.json"), { mcpServers: {} });
+		git(project, "add", ".mcp.json");
+		expect(git(project, "commit", "-q", "-m", "mcp").status).toBe(0);
+		const before = await fs.readFile(settingsPath(), "utf8");
+
+		// What the TUI Profiles tab's "apply predefined" does.
+		const settings = await readSettings(project);
+		(settings.enabledPlugins as Record<string, boolean>)["frontend@magus"] =
+			true;
+		await expect(writeSettings(settings, project)).rejects.toBeInstanceOf(
+			TrackedLiveFileError,
+		);
+		await expect(
+			writeMcpConfig({ mcpServers: { x: { command: "x" } } }, project),
+		).rejects.toBeInstanceOf(TrackedLiveFileError);
+
+		expect(await fs.readFile(settingsPath(), "utf8")).toBe(before);
+		await untouched();
+	});
+
+	test("review M1: a project-scope Claude CLI install or uninstall is refused before the CLI runs", async () => {
+		await commitTrackedSettings();
+		const cwd = process.cwd();
+		const pathBefore = process.env.PATH;
+		// git stays reachable; `claude` does not — were the refusal missing, the
+		// CLI could not run here and touch this machine's plugins anyway.
+		const gitDir = spawnSync("sh", ["-c", "command -v git"], {
+			encoding: "utf8",
+		}).stdout.trim();
+		process.env.PATH = gitDir.slice(0, gitDir.lastIndexOf("/"));
+		process.chdir(project);
+		try {
+			await expect(
+				installPlugin("dev@magus", "project"),
+			).rejects.toBeInstanceOf(TrackedLiveFileError);
+			await expect(
+				uninstallPlugin("dev@magus", "project", project),
+			).rejects.toBeInstanceOf(TrackedLiveFileError);
+		} finally {
+			process.chdir(cwd);
+			process.env.PATH = pathBefore;
+		}
+		await untouched();
+	});
+
+	test("review M1: a project without profiles writes its own settings.json as before", async () => {
+		await commitTrackedSettings();
+		await writeManifest({ version: 2, profiles: {} }, project);
+		const settings = await readSettings(project);
+		(settings.enabledPlugins as Record<string, boolean>)["frontend@magus"] =
+			true;
+		await writeSettings(settings, project);
+		expect(
+			(await fs.readJson(settingsPath())).enabledPlugins["frontend@magus"],
+		).toBe(true);
+	});
+
+	test("review 3a: inside a work tree git cannot read, activation refuses with git's own message", async () => {
+		// A .git pointing at a repository that is not there: git exits 128.
+		await fs.outputFile(
+			join(project, ".git"),
+			`gitdir: ${join(project, "no-such-repository")}\n`,
+		);
+
+		const error = await activateProfile(MANIFEST, "team", project, {
+			onDisplace: () => {},
+		}).then(
+			() => null,
+			(e: unknown) => e,
+		);
+
+		expect(error).toBeInstanceOf(GitCheckError);
+		expect((error as Error).message).toContain("not a git repository");
+		expect((error as Error).message).toContain("Nothing was changed.");
+		expect(await fs.pathExists(settingsPath())).toBe(false);
+		expect(await fs.pathExists(join(project, ".claude", "profiles"))).toBe(
+			false,
+		);
+		const prep = await prepareProfileState(project);
+		expect(prep.refusal).toBeInstanceOf(GitCheckError);
+	});
+
+	test("review 3a: git missing is a refusal inside a work tree, and no check outside one", async () => {
+		expect(git(project, "init", "-q").status).toBe(0);
+		const outside = await mkdtemp(join(tmpdir(), "no-git-"));
+		const pathBefore = process.env.PATH;
+		// Not empty: an empty PATH falls back to the system default, where git is.
+		process.env.PATH = join(outside, "no-bin");
+		try {
+			await expect(
+				trackedByGit(project, [".claude/settings.json"]),
+			).rejects.toThrow("could not run git");
+			expect([...(await trackedByGit(outside, [".mcp.json"]))]).toEqual([]);
+		} finally {
+			process.env.PATH = pathBefore;
+			await rm(outside, { recursive: true, force: true });
+		}
+	});
+
+	test("committed custom skills are not reported", async () => {
+		expect(git(project, "init", "-q").status).toBe(0);
+		await fs.outputFile(
+			join(project, ".claude", "skills", "mine", "SKILL.md"),
+			"# mine\n",
+		);
+		git(project, "add", ".");
+		expect(git(project, "commit", "-q", "-m", "init").status).toBe(0);
+
+		expect(await trackedGeneratedFiles(project)).toEqual([]);
+	});
+
+	test("outside a git repository nothing is reported", async () => {
+		await activateProfile(MANIFEST, "team", project, { onDisplace: () => {} });
+		expect(await trackedGeneratedFiles(project)).toEqual([]);
+	});
+});
+
+describe("machine-local settings survive every render", () => {
+	/** What `magus update` records: eleven plugins, as on the reporting machine. */
+	const VERSIONS = Object.fromEntries(
+		Array.from({ length: 11 }, (_, i) => [`p${i}@magus`, `1.${i}.0`]),
+	);
+
+	test("B3: first adoption carries installedPluginVersions out of the settings.json it moves aside", async () => {
+		await fs.outputJson(settingsPath(), {
+			enabledPlugins: { "hand@written": true },
+			installedPluginVersions: VERSIONS,
+		});
+		const moved: string[] = [];
+
+		await activateProfile(MANIFEST, "team", project, {
+			onDisplace: (artifact) => moved.push(artifact.savedTo),
+		});
+
+		expect(moved).toHaveLength(1);
+		const live = await fs.readJson(settingsPath());
+		expect(live.installedPluginVersions).toEqual(VERSIONS);
+		expect(live.enabledPlugins["dev@magus"]).toBe(true);
+		expect(live.enabledPlugins["hand@written"]).toBeUndefined();
+		// The backup still holds the whole original.
+		expect(
+			(await fs.readJson(moved[0] as string)).installedPluginVersions,
+		).toEqual(VERSIONS);
+	});
+
+	test("B3: a switch, then a regeneration from a pulled change, keep what an update recorded", async () => {
+		await activateProfile(MANIFEST, "team", project, { onDisplace: () => {} });
+		const live = await fs.readJson(settingsPath());
+		live.installedPluginVersions = VERSIONS;
+		await fs.writeJson(settingsPath(), live);
+
+		const switched = await switchToProfile(project, "other");
+		expect(switched.problems).toEqual([]);
+		expect((await fs.readJson(settingsPath())).installedPluginVersions).toEqual(
+			VERSIONS,
+		);
+		// Machine state, not a contract: nothing of it reached profiles.json.
+		expect(JSON.stringify(await readManifest(project))).not.toContain(
+			"installedPluginVersions",
+		);
+
+		// A teammate's commit adds a plugin to the active profile.
+		const manifest = await readManifest(project);
+		(manifest.profiles.other?.plugins as Record<string, string>)[
+			"designer@magus"
+		] = "latest";
+		await writeManifest(manifest, project);
+		expect(await regenerateLiveFiles(project)).toBe(true);
+
+		const after = await fs.readJson(settingsPath());
+		expect(after.enabledPlugins["designer@magus"]).toBe(true);
+		expect(after.installedPluginVersions).toEqual(VERSIONS);
+	});
+});
+
+describe("the gate is idempotent", () => {
+	test("a second pass with nothing changed prints nothing", async () => {
+		await activateProfile(MANIFEST, "team", project, { onDisplace: () => {} });
+		const marker = await readActiveMarker(project);
+		if (marker) await writeActiveMarker(marker, project);
+		const prep = await prepareProfileState(project);
+		expect(prep.lines).toEqual([]);
+		expect(prep.problems).toEqual([]);
+	});
+});
+
+describe("applying a profile from the TUI Profiles tab", () => {
+	test("a project profile goes through the switch path: absorb into the old, activate the new", async () => {
+		await activateProfile(MANIFEST, "team", project, { onDisplace: () => {} });
+		// Claude Code installs a plugin while "team" is active.
+		const live = await fs.readJson(settingsPath());
+		live.enabledPlugins["code-search@magus"] = true;
+		await fs.writeFile(settingsPath(), JSON.stringify(live));
+
+		const result = await switchToProfile(project, "other", {
+			onDisplace: () => {},
+		});
+
+		expect(result.problems).toEqual([]);
+		expect(result.lines).toEqual(['Added code-search@magus to profile "team"']);
+		expect(result.activation?.profileId).toBe("other");
+		expect(result.activation?.displaced).toEqual([]);
+		// The edit was kept in the profile it was made under...
+		const manifest = await readManifest(project);
+		expect(manifest.profiles.team?.plugins?.["code-search@magus"]).toBe(
+			"latest",
+		);
+		// ...and the live file is "other", rendered from the manifest — not a
+		// copy of its plugins spliced into whatever was there.
+		expect(await fs.readJson(settingsPath())).toEqual(
+			(await renderProfile(manifest, "other")).settings,
+		);
+		expect((await readActiveMarker(project))?.profile).toBe("other");
+		expect(await fs.pathExists(backupRoot(project))).toBe(false);
+	});
+
+	test("an unknown target changes nothing and says why", async () => {
+		await activateProfile(MANIFEST, "team", project, { onDisplace: () => {} });
+		const before = await fs.readFile(settingsPath(), "utf8");
+
+		const result = await switchToProfile(project, "nope");
+
+		expect(result.activation).toBeNull();
+		expect(result.problems).toEqual([
+			'Profile "nope" not found. Available: team, other',
+		]);
+		expect(await fs.readFile(settingsPath(), "utf8")).toBe(before);
+		expect((await readActiveMarker(project))?.profile).toBe("team");
+	});
+
+	test("a user-scope profile writes ~/.claude/settings.json and never the project's live files", async () => {
+		await activateProfile(MANIFEST, "team", project, { onDisplace: () => {} });
+		const beforeSettings = await fs.readFile(settingsPath(), "utf8");
+		const beforeMarker = await fs.readFile(activeMarkerPath(project), "utf8");
+		const home = await mkdtemp(join(tmpdir(), "state-home-"));
+		const previousHome = process.env.HOME;
+		process.env.HOME = home;
+		try {
+			await applyUserProfile({
+				plugins: { "dev@magus": "latest", "off@elsewhere": false },
+			});
+			expect(await fs.readJson(join(home, ".claude", "settings.json"))).toEqual(
+				{
+					enabledPlugins: { "dev@magus": true, "off@elsewhere": false },
+				},
+			);
+		} finally {
+			process.env.HOME = previousHome;
+			await rm(home, { recursive: true, force: true });
+		}
+		expect(await fs.readFile(settingsPath(), "utf8")).toBe(beforeSettings);
+		expect(await fs.readFile(activeMarkerPath(project), "utf8")).toBe(
+			beforeMarker,
+		);
+	});
+});