magus-cli 7.4.0 → 7.5.0

package/src/services/profile-absorb.ts

@@ -0,0 +1,1532 @@
+/**
+ * Keep `.claude/profiles.json` and the active profile's live config in step.
+ *
+ * In a magus project a change to the live config IS a change to the active
+ * profile. Claude Code writes `.claude/settings.json` and `.mcp.json` itself —
+ * `claude plugin install --scope project`, `/config`, `claude mcp add` — and a
+ * person may edit them, or `.claude/models.json`, or a skill folder magus
+ * installed. None of that is set aside: it is written into the profile.
+ *
+ * {@link reconcileActiveProfile} runs at every magus entry point that reads or
+ * writes profile state, before the command acts:
+ *
+ *   a. ABSORB. A live file whose hash differs from the marker is diffed against
+ *      the entry it was rendered from (`marker.base`), and the difference is
+ *      written into the entry. A magus-installed skill folder whose contents
+ *      changed stops being managed: it becomes a custom skill, and the profile
+ *      stops listing it.
+ *   b. REGENERATE. If the entry in profiles.json no longer hashes to the
+ *      marker's `definition` — a teammate's change arrived by `git pull` — the
+ *      live files and skills are regenerated from it. No prompt, no backup.
+ *   c. Both: a, then b. The local edits are merged into the pulled entry
+ *      against `marker.base`, the common ancestor, so neither side is lost.
+ *      When both changed the same key, the local edit wins; the pulled value
+ *      is still in git history.
+ *
+ * Idempotent, and cheap when nothing changed: three file hashes, the skill
+ * folder hashes and one read of profiles.json.
+ *
+ * ## How live keys map back to manifest fields
+ *
+ * The inverse of `profile-render.ts`:
+ *
+ *   enabledPlugins true   -> `plugins[id]` ("latest" unless already pinned)
+ *   enabledPlugins false  -> nothing when another profile owns the id (render
+ *                            writes that `false` itself); otherwise
+ *                            `plugins[id] = false`
+ *   any other settings key -> `settings[key]`, minus keys inherited unchanged
+ *                            through `extends`, minus machine-local keys
+ *   .mcp.json mcpServers  -> `mcpServers`
+ *   .claude/models.json   -> `models`
+ *
+ * Model routing and output style need no special case, and must not get one:
+ * `magus models use` records the settings keys it implies (`model`,
+ * `effortLevel`, `modelSettings`) in `profiles.<name>.settings` alongside the
+ * routing in `profiles.<name>.models`, and a style records `outputStyle` in
+ * `profiles.<name>.settings` too. Those are exactly the fields absorption
+ * writes, so an edit lands where the command that owns the key keeps it, once.
+ */
+
+import path from "node:path";
+import fs from "fs-extra";
+import type {
+	McpServerConfig,
+	ProfileManifest,
+	ProfileManifestEntry,
+	ProfileSkillRef,
+} from "../types/index.js";
+import { readManifest, writeManifest } from "./manifest.js";
+import { validateModelsConfig } from "./models-core.js";
+import {
+	type ActivateOptions,
+	activateProfile,
+	activationNotes,
+} from "./profile-activate.js";
+import {
+	type ActiveMarker,
+	LIVE_FILE_KEYS,
+	type LiveFileKey,
+	MACHINE_LOCAL_SETTINGS_KEYS,
+	type RenderedProfile,
+	canonicalJson,
+	hasCurrentMarker,
+	isJsonRecord,
+	jsonEqual,
+	legacyProfileDirs,
+	liveHash,
+	liveKind,
+	livePath,
+	markerFor,
+	readActiveMarker,
+	readLegacyMarkerHashes,
+	readLiveJson,
+	readLiveThrough,
+	writeActiveMarker,
+	writeLiveFile,
+} from "./profile-live.js";
+import { renderProfile } from "./profile-render.js";
+import {
+	inspectManagedSkills,
+	skillFolder,
+	updateSkillIgnoreLines,
+} from "./profile-skills.js";
+import { resolveExtends, resolveProfile } from "./resolver.js";
+import { SettingsParseError } from "./settings-file.js";
+
+// ─── Changes ─────────────────────────────────────────────────────────────────
+
+export type AbsorbChange =
+	| { kind: "plugin-added"; plugin: string }
+	| { kind: "plugin-removed"; plugin: string }
+	| { kind: "plugin-disabled"; plugin: string }
+	| { kind: "settings-changed" }
+	| { kind: "mcp-changed" }
+	| { kind: "models-changed" }
+	| { kind: "skill-released"; skill: string; folder: string };
+
+/** One line per change, naming the profile it went into. */
+export function describeChange(change: AbsorbChange, profile: string): string {
+	switch (change.kind) {
+		case "plugin-added":
+			return `Added ${change.plugin} to profile "${profile}"`;
+		case "plugin-removed":
+			return `Removed ${change.plugin} from profile "${profile}"`;
+		case "plugin-disabled":
+			return `Disabled ${change.plugin} in profile "${profile}"`;
+		case "settings-changed":
+			return `Updated settings of profile "${profile}"`;
+		case "mcp-changed":
+			return `Updated MCP servers of profile "${profile}"`;
+		case "models-changed":
+			return `Updated model routing of profile "${profile}"`;
+		case "skill-released":
+			return `Skill "${change.skill}" was edited — it is now a custom skill in .claude/skills/${change.folder}; commit it`;
+	}
+}
+
+// ─── The inverse of rendering ────────────────────────────────────────────────
+
+/** The live config as absorption reads it. */
+export interface LiveView {
+	settings: Record<string, unknown>;
+	mcp: Record<string, unknown>;
+	models: Record<string, unknown> | null;
+}
+
+/** What `extends` contributes on its own, or nothing. */
+function inheritedPart(entry: ProfileManifestEntry): ProfileManifestEntry {
+	if (!entry.extends) return { name: entry.name };
+	const base = resolveExtends({ name: entry.name, extends: entry.extends });
+	return base.extends === entry.extends && base.plugins === undefined
+		? { name: entry.name }
+		: base;
+}
+
+function isOn(value: string | boolean | undefined): boolean {
+	return value !== undefined && value !== false;
+}
+
+function withoutMachineKeys(
+	settings: Record<string, unknown>,
+): Record<string, unknown> {
+	const out = { ...settings };
+	for (const key of MACHINE_LOCAL_SETTINGS_KEYS) delete out[key];
+	return out;
+}
+
+function setOrDelete<K extends "plugins" | "settings" | "mcpServers">(
+	entry: ProfileManifestEntry,
+	key: K,
+	value: ProfileManifestEntry[K],
+): void {
+	if (value && Object.keys(value).length > 0) entry[key] = value;
+	else delete entry[key];
+}
+
+/**
+ * Write the live config into a manifest entry: the inverse of rendering. Pure.
+ *
+ * `otherPluginIds` are the plugins other profiles enable — rendering writes
+ * those as `false` in this profile on its own, so a `false` for one of them
+ * says nothing new.
+ */
+export function computeAbsorb(
+	entry: ProfileManifestEntry,
+	live: LiveView,
+	otherPluginIds: ReadonlySet<string>,
+	now: string = new Date().toISOString(),
+): { entry: ProfileManifestEntry; changes: AbsorbChange[] } {
+	const changes: AbsorbChange[] = [];
+	const next: ProfileManifestEntry = { ...entry };
+	const inherited = inheritedPart(entry);
+	const resolved = resolveExtends(entry);
+
+	// Plugins.
+	const enabled = isJsonRecord(live.settings.enabledPlugins)
+		? live.settings.enabledPlugins
+		: {};
+	const own: Record<string, string | boolean> = { ...(entry.plugins ?? {}) };
+	const ids = new Set([
+		...Object.keys(enabled),
+		...Object.keys(resolved.plugins ?? {}),
+		...Object.keys(own),
+	]);
+	for (const id of ids) {
+		const liveValue = enabled[id];
+		const on = isOn(resolved.plugins?.[id]);
+		const inheritedOn = isOn(inherited.plugins?.[id]);
+		if (liveValue === true && !on) {
+			// An own `false` over an inherited plugin is what kept it off.
+			if (own[id] === false && inheritedOn) delete own[id];
+			else own[id] = "latest";
+			changes.push({ kind: "plugin-added", plugin: id });
+		} else if (liveValue !== true && on) {
+			delete own[id];
+			const mustSayFalse =
+				inheritedOn || (liveValue === false && !otherPluginIds.has(id));
+			if (mustSayFalse) own[id] = false;
+			changes.push({ kind: "plugin-removed", plugin: id });
+		} else if (
+			liveValue === false &&
+			!on &&
+			!otherPluginIds.has(id) &&
+			own[id] !== false
+		) {
+			own[id] = false;
+			changes.push({ kind: "plugin-disabled", plugin: id });
+		} else if (liveValue === undefined && own[id] === false && !inheritedOn) {
+			delete own[id];
+			changes.push({ kind: "plugin-removed", plugin: id });
+		}
+	}
+	setOrDelete(next, "plugins", own);
+
+	// Settings: everything but enabledPlugins and machine-local keys, minus
+	// what `extends` supplies unchanged.
+	const { enabledPlugins: _drop, ...rest } = withoutMachineKeys(live.settings);
+	if (!jsonEqual(rest, resolved.settings ?? {})) {
+		const inheritedSettings = inherited.settings ?? {};
+		const ownSettings = entry.settings ?? {};
+		const settings: Record<string, unknown> = {};
+		for (const [key, value] of Object.entries(rest)) {
+			const fromBase =
+				key in inheritedSettings &&
+				!(key in ownSettings) &&
+				jsonEqual(inheritedSettings[key], value);
+			if (!fromBase) settings[key] = value;
+		}
+		setOrDelete(next, "settings", settings);
+		changes.push({ kind: "settings-changed" });
+	}
+
+	// MCP servers.
+	const servers = isJsonRecord(live.mcp.mcpServers)
+		? (live.mcp.mcpServers as Record<string, McpServerConfig>)
+		: {};
+	if (!jsonEqual(servers, entry.mcpServers ?? {})) {
+		setOrDelete(next, "mcpServers", servers);
+		changes.push({ kind: "mcp-changed" });
+	}
+
+	// Model routing.
+	if (!jsonEqual(live.models, resolved.models ?? null)) {
+		if (live.models) {
+			next.models = live.models as unknown as ProfileManifestEntry["models"];
+		} else {
+			// biome-ignore lint/performance/noDelete: the entry is serialised to profiles.json; the key must be absent, not undefined
+			delete next.models;
+		}
+		changes.push({ kind: "models-changed" });
+	}
+
+	if (changes.length > 0) next.updatedAt = now;
+	return { entry: next, changes };
+}
+
+/**
+ * Would writing `rendered` over `live` lose anything the live file says?
+ *
+ * The rendered file may ADD `false` entries to enabledPlugins — that is how a
+ * profile keeps other profiles' plugins off — but may not drop or change any
+ * key. Machine-local settings keys are carried across writes, so they are not
+ * compared.
+ */
+export function losesNothing(
+	key: LiveFileKey,
+	live: Record<string, unknown> | null,
+	rendered: Record<string, unknown> | null,
+): boolean {
+	if (key !== "settings") return jsonEqual(live, rendered);
+	if (!live || !rendered) return live === rendered;
+	const { enabledPlugins: liveEnabled, ...liveRest } = withoutMachineKeys(live);
+	const { enabledPlugins: renderedEnabled, ...renderedRest } = rendered;
+	if (!jsonEqual(liveRest, renderedRest)) return false;
+	const l = isJsonRecord(liveEnabled) ? liveEnabled : {};
+	const r = isJsonRecord(renderedEnabled) ? renderedEnabled : {};
+	for (const [id, value] of Object.entries(l)) {
+		if (r[id] !== value) return false;
+	}
+	for (const [id, value] of Object.entries(r)) {
+		if (!(id in l) && value !== false) return false;
+	}
+	return true;
+}
+
+// ─── Three-way merge ─────────────────────────────────────────────────────────
+
+/**
+ * A three-way merge of one JSON value: `base` is the common ancestor, `local`
+ * what the live config says, `remote` what profiles.json says now.
+ *
+ * Whichever side changed a value wins; where both did:
+ *   - plain objects are merged key by key, recursively — a local allow rule and
+ *     a teammate's deny rule under the same `permissions` both survive;
+ *   - arrays of scalars are merged as sets: remote's items, plus what local
+ *     added, minus what local removed, in remote's order then local's
+ *     (permission lists, additionalDirectories);
+ *   - anything else — a scalar, or an array holding objects, such as a list of
+ *     hooks — is one value, and both sides changing it differently is a true
+ *     conflict: local wins, and the path is recorded in `conflicts` so the
+ *     caller can say so. An array of objects is NOT merged as a set: one hook
+ *     edited on both sides would come out as two hooks, each with half the
+ *     edits.
+ */
+function merge3Deep(
+	base: unknown,
+	local: unknown,
+	remote: unknown,
+	at: string,
+	conflicts: string[],
+): unknown {
+	if (jsonEqual(local, remote)) return local;
+	if (jsonEqual(local, base)) return remote;
+	if (jsonEqual(remote, base)) return local;
+	if (
+		isJsonRecord(local) &&
+		isJsonRecord(remote) &&
+		(base === undefined || isJsonRecord(base))
+	) {
+		const b = (base ?? {}) as Record<string, unknown>;
+		const out: Record<string, unknown> = {};
+		const keys = new Set([
+			...Object.keys(remote),
+			...Object.keys(local),
+			...Object.keys(b),
+		]);
+		for (const key of keys) {
+			const value = merge3Deep(
+				b[key],
+				local[key],
+				remote[key],
+				`${at}.${key}`,
+				conflicts,
+			);
+			if (value !== undefined) out[key] = value;
+		}
+		return out;
+	}
+	if (
+		isScalarArray(local) &&
+		isScalarArray(remote) &&
+		(base === undefined || isScalarArray(base))
+	) {
+		const key = (v: unknown) => canonicalJson(v);
+		const baseKeys = new Set(((base ?? []) as unknown[]).map(key));
+		const localKeys = new Set(local.map(key));
+		const out: unknown[] = [];
+		const seen = new Set<string>();
+		for (const item of remote) {
+			const k = key(item);
+			// In base and gone locally: local removed it.
+			if ((baseKeys.has(k) && !localKeys.has(k)) || seen.has(k)) continue;
+			out.push(item);
+			seen.add(k);
+		}
+		for (const item of local) {
+			const k = key(item);
+			// In base: either remote kept it (already added) or removed it.
+			if (baseKeys.has(k) || seen.has(k)) continue;
+			out.push(item);
+			seen.add(k);
+		}
+		return out;
+	}
+	conflicts.push(at);
+	return local;
+}
+
+/** An array whose items are all strings, numbers, booleans or null. */
+function isScalarArray(value: unknown): value is unknown[] {
+	return (
+		Array.isArray(value) &&
+		value.every((item) => item === null || typeof item !== "object")
+	);
+}
+
+/**
+ * {@link merge3Deep} one level deep only: each value is merged whole. For maps
+ * whose values are units — an MCP server's config, whose `args` are an ordered
+ * command line and must not be merged as a set.
+ *
+ * `bothChanged`, when given, settles a key both sides changed differently
+ * before it counts as a conflict; returning undefined means it is one.
+ */
+function merge3Entries(
+	base: Record<string, unknown> | undefined,
+	local: Record<string, unknown> | undefined,
+	remote: Record<string, unknown> | undefined,
+	at: string,
+	conflicts: string[],
+	bothChanged?: (local: unknown, remote: unknown) => unknown,
+): Record<string, unknown> {
+	const out: Record<string, unknown> = {};
+	const keys = new Set([
+		...Object.keys(remote ?? {}),
+		...Object.keys(local ?? {}),
+		...Object.keys(base ?? {}),
+	]);
+	for (const key of keys) {
+		const [b, l, r] = [base?.[key], local?.[key], remote?.[key]];
+		let value: unknown;
+		if (jsonEqual(l, r) || jsonEqual(r, b)) value = l;
+		else if (jsonEqual(l, b)) value = r;
+		else {
+			const settled = bothChanged?.(l, r);
+			if (settled !== undefined) value = settled;
+			else {
+				conflicts.push(`${at}.${key}`);
+				value = l;
+			}
+		}
+		if (value !== undefined) out[key] = value;
+	}
+	return out;
+}
+
+function nonEmpty<T extends Record<string, unknown>>(
+	value: unknown,
+): T | undefined {
+	return isJsonRecord(value) && Object.keys(value).length > 0
+		? (value as T)
+		: undefined;
+}
+
+/**
+ * Both sides enabled a plugin, one with a version pin and one with "latest".
+ *
+ * Absorption can only ever write "latest" — Claude Code's settings say a
+ * plugin is on, never which version — so "latest" means "enabled", and a
+ * concrete version is somebody's deliberate pin. The pin wins, as it does when
+ * the resolver unions two profiles, and it is not a conflict. Anything else
+ * (two different pins, a pin against `false`) is left to be one.
+ */
+function pinOverLatest(local: unknown, remote: unknown): unknown {
+	const isPin = (v: unknown) =>
+		typeof v === "string" && v !== "" && v !== "latest";
+	const isLatest = (v: unknown) => v === "latest" || v === true || v === "";
+	if (isLatest(local) && isPin(remote)) return remote;
+	if (isPin(local) && isLatest(remote)) return local;
+	return undefined;
+}
+
+/** The result of {@link merge3}. */
+export interface Merge3Result {
+	entry: ProfileManifestEntry;
+	/**
+	 * Key paths both sides changed differently, where the local value was
+	 * kept — `settings.permissions.defaultMode`, `plugins.dev@magus`.
+	 */
+	conflicts: string[];
+}
+
+/**
+ * Merge a locally absorbed entry and the entry now in profiles.json against
+ * their common ancestor. Absorption only ever touches plugins, settings,
+ * mcpServers, models and (by releasing skills) skills, so every other field
+ * is taken from profiles.json as it stands.
+ *
+ * `settings` merge recursively (see {@link merge3Deep}); plugin pins, MCP
+ * servers and the routing config are each merged as whole values.
+ */
+export function merge3(
+	base: ProfileManifestEntry,
+	local: ProfileManifestEntry,
+	remote: ProfileManifestEntry,
+): Merge3Result {
+	const conflicts: string[] = [];
+	const out: ProfileManifestEntry = { ...remote };
+	const put = <K extends keyof ProfileManifestEntry>(
+		key: K,
+		value: ProfileManifestEntry[K] | undefined,
+	) => {
+		if (value === undefined) delete out[key];
+		else out[key] = value;
+	};
+	put(
+		"plugins",
+		nonEmpty(
+			merge3Entries(
+				base.plugins,
+				local.plugins,
+				remote.plugins,
+				"plugins",
+				conflicts,
+				pinOverLatest,
+			),
+		),
+	);
+	put(
+		"settings",
+		nonEmpty(
+			merge3Deep(
+				base.settings ?? {},
+				local.settings ?? {},
+				remote.settings ?? {},
+				"settings",
+				conflicts,
+			),
+		),
+	);
+	put(
+		"mcpServers",
+		nonEmpty(
+			merge3Entries(
+				base.mcpServers as Record<string, unknown> | undefined,
+				local.mcpServers as Record<string, unknown> | undefined,
+				remote.mcpServers as Record<string, unknown> | undefined,
+				"mcpServers",
+				conflicts,
+			),
+		),
+	);
+	// The routing config is validated as a unit, so it merges as one value.
+	let models = local.models;
+	if (!jsonEqual(local.models, remote.models)) {
+		if (jsonEqual(local.models, base.models)) models = remote.models;
+		else if (!jsonEqual(remote.models, base.models)) conflicts.push("models");
+	}
+	put("models", models);
+
+	const folders = (refs: ProfileSkillRef[] | undefined) =>
+		new Set((refs ?? []).map(skillFolder));
+	const localFolders = folders(local.skills);
+	const released = [...folders(base.skills)].filter(
+		(f) => !localFolders.has(f),
+	);
+	if (released.length > 0 && remote.skills) {
+		const kept = remote.skills.filter(
+			(ref) => !released.includes(skillFolder(ref)),
+		);
+		put("skills", kept.length > 0 ? kept : undefined);
+	}
+	if (!jsonEqual(local, base) && local.updatedAt) {
+		out.updatedAt = local.updatedAt;
+	}
+	return { entry: out, conflicts };
+}
+
+/** One line per leaf where the local value was kept over a pulled change. */
+export function describeConflict(at: string, profile: string): string {
+	return `Profile "${profile}": ${at} was changed both here and in profiles.json — kept the local value; the other is in git history`;
+}
+
+// ─── Reconcile ───────────────────────────────────────────────────────────────
+
+export interface ReconcileResult {
+	/** The profile reconciled, or null when there was no usable marker. */
+	profile: string | null;
+	/** What was absorbed into the profile. */
+	changes: AbsorbChange[];
+	/** Live paths rewritten because profiles.json changed underneath them. */
+	regenerated: string[];
+	/** Live files that were missing and were written again. */
+	restored: string[];
+	/**
+	 * Why nothing was written. When non-empty, the manifest and every live file
+	 * are exactly as they were — a caller that writes profile state must refuse
+	 * too (see {@link refuseOnProblems}).
+	 */
+	problems: string[];
+	/** The files behind `problems` that could not be parsed. */
+	unreadable: SettingsParseError[];
+	/** Leaf key paths where a local value was kept over a pulled change. */
+	conflicts: string[];
+	/** Everything worth printing, in order. */
+	lines: string[];
+}
+
+function emptyResult(profile: string | null): ReconcileResult {
+	return {
+		profile,
+		changes: [],
+		regenerated: [],
+		restored: [],
+		problems: [],
+		unreadable: [],
+		conflicts: [],
+		lines: [],
+	};
+}
+
+/**
+ * Stop a caller that is about to write profile state when absorbing could
+ * not: throws the first unreadable file's `SettingsParseError` — which every
+ * surface already reports as "fix it by hand, magus leaves it as it is" — or
+ * an Error listing the problems.
+ */
+export function refuseOnProblems(result: {
+	problems: string[];
+	unreadable?: SettingsParseError[];
+}): void {
+	const [first] = result.unreadable ?? [];
+	if (first) throw first;
+	if (result.problems.length > 0) throw new Error(result.problems.join("\n"));
+}
+
+/**
+ * The plugin ids whose `false` in the live settings is the render's own
+ * output: every other profile's plugins now, plus every id recorded as
+ * rendered (`marker.allPluginIds`) that `base` does not enable. The recorded
+ * ids matter when a teammate removes a plugin from every profile — the live
+ * `false` for it is left over from the old render, not a deliberate disable.
+ */
+function renderedFalseIds(
+	others: ReadonlySet<string>,
+	recorded: readonly string[] | undefined,
+	base: ProfileManifestEntry,
+): Set<string> {
+	const out = new Set(others);
+	const enabled = resolveExtends(base).plugins ?? {};
+	for (const id of recorded ?? []) {
+		if (!isOn(enabled[id])) out.add(id);
+	}
+	return out;
+}
+
+/** Every profile's plugin ids in the manifest as it is now. */
+async function allPluginIdsOf(manifest: ProfileManifest): Promise<string[]> {
+	const out = new Set<string>();
+	for (const id of Object.keys(manifest.profiles)) {
+		const closure = await resolveProfile(manifest, id, { binResolver: noBins });
+		for (const pluginId of Object.keys(closure.plugins)) out.add(pluginId);
+	}
+	return [...out];
+}
+
+/**
+ * The live settings with the Claude CLI's install records taken out.
+ *
+ * `claude plugin install --scope project` only ever writes `true` for the
+ * plugin it installs, and magus only runs it for plugins some profile names
+ * (`installable`). So a `true` for one of those that `base` does not enable is
+ * the install's record, and gives way to what the render says for that id. A
+ * `true` for any other id — a plugin the user installed themselves — every
+ * `false`, and every other key are the user's, and stay. The ids taken out
+ * are appended to `discarded`.
+ */
+function withoutCliRecords(
+	settings: Record<string, unknown>,
+	installable: ReadonlySet<string>,
+	base: ProfileManifestEntry,
+	renderedBase: RenderedProfile,
+	discarded: string[],
+): Record<string, unknown> {
+	if (!isJsonRecord(settings.enabledPlugins)) return settings;
+	const enabled: Record<string, unknown> = { ...settings.enabledPlugins };
+	const rendered = (renderedBase.settings.enabledPlugins ?? {}) as Record<
+		string,
+		unknown
+	>;
+	const baseEnabled = resolveExtends(base).plugins ?? {};
+	for (const [id, value] of Object.entries(enabled)) {
+		if (value !== true || !installable.has(id) || isOn(baseEnabled[id])) {
+			continue;
+		}
+		discarded.push(id);
+		if (id in rendered) enabled[id] = rendered[id];
+		else delete enabled[id];
+	}
+	return { ...settings, enabledPlugins: enabled };
+}
+
+/**
+ * Where `pinned` pins a plugin to a version and `entry` has it as "latest",
+ * the pin stands: absorption writes "latest" for any enable, because Claude
+ * Code never records a version.
+ */
+function keepPins(
+	entry: ProfileManifestEntry,
+	pinned: ProfileManifestEntry,
+): ProfileManifestEntry {
+	let out = entry;
+	for (const [id, pin] of Object.entries(pinned.plugins ?? {})) {
+		if (
+			typeof pin === "string" &&
+			pin !== "" &&
+			pin !== "latest" &&
+			entry.plugins?.[id] === "latest"
+		) {
+			out = { ...out, plugins: { ...out.plugins, [id]: pin } };
+		}
+	}
+	return out;
+}
+
+/**
+ * Keep everything the live config holds that `target` lacks: its plugins are
+ * added, and its settings, MCP servers and routing win where they differ. For
+ * when nothing records what the live config was rendered from, so an edit
+ * cannot be told apart from the rest — adding never drops a key.
+ */
+function mergeAdditively(
+	target: ProfileManifestEntry,
+	everything: ProfileManifestEntry,
+): ProfileManifestEntry {
+	const merged: ProfileManifestEntry = { ...target };
+	const plugins = { ...(target.plugins ?? {}) };
+	for (const [id, pin] of Object.entries(everything.plugins ?? {})) {
+		if (!(id in plugins)) plugins[id] = pin;
+	}
+	if (Object.keys(plugins).length > 0) merged.plugins = plugins;
+	if (everything.settings) {
+		merged.settings = { ...(target.settings ?? {}), ...everything.settings };
+	}
+	if (everything.mcpServers) {
+		merged.mcpServers = {
+			...(target.mcpServers ?? {}),
+			...everything.mcpServers,
+		};
+	}
+	if (everything.models) merged.models = everything.models;
+	return merged;
+}
+
+/** A routing file that parses but is not a valid config, as a parse error. */
+function checkModels(key: LiveFileKey, value: Record<string, unknown>): void {
+	if (key !== "models") return;
+	const errors = validateModelsConfig(value);
+	if (errors.length > 0) {
+		throw new SyntaxError(
+			errors.map((e) => `${e.path || "(root)"}: ${e.message}`).join("; "),
+		);
+	}
+}
+
+const noBins = async () => [];
+
+/** Plugins enabled by profiles other than `name`, in the manifest as it is. */
+async function otherProfilesPlugins(
+	manifest: ProfileManifest,
+	name: string,
+): Promise<Set<string>> {
+	const out = new Set<string>();
+	for (const id of Object.keys(manifest.profiles)) {
+		if (id === name) continue;
+		const closure = await resolveProfile(manifest, id, { binResolver: noBins });
+		for (const pluginId of Object.keys(closure.plugins)) out.add(pluginId);
+	}
+	return out;
+}
+
+function rel(projectPath: string, key: LiveFileKey): string {
+	return livePath(key, projectPath).slice(projectPath.length + 1);
+}
+
+/** What changed from `before` to `after`, as the lines absorption prints. */
+function diffEntries(
+	before: ProfileManifestEntry,
+	after: ProfileManifestEntry,
+): AbsorbChange[] {
+	const changes: AbsorbChange[] = [];
+	const b = before.plugins ?? {};
+	const a = after.plugins ?? {};
+	for (const id of new Set([...Object.keys(b), ...Object.keys(a)])) {
+		if (jsonEqual(b[id], a[id])) continue;
+		if (a[id] === false) changes.push({ kind: "plugin-disabled", plugin: id });
+		else if (a[id] === undefined)
+			changes.push({ kind: "plugin-removed", plugin: id });
+		else if (!isOn(b[id])) changes.push({ kind: "plugin-added", plugin: id });
+	}
+	if (!jsonEqual(before.settings ?? {}, after.settings ?? {})) {
+		changes.push({ kind: "settings-changed" });
+	}
+	if (!jsonEqual(before.mcpServers ?? {}, after.mcpServers ?? {})) {
+		changes.push({ kind: "mcp-changed" });
+	}
+	if (!jsonEqual(before.models ?? null, after.models ?? null)) {
+		changes.push({ kind: "models-changed" });
+	}
+	return changes;
+}
+
+/**
+ * The marker names a profile profiles.json no longer defines, and the user is
+ * about to activate `target` (`profile switch`, `install`): carry whatever was
+ * changed in the live config since magus last wrote it into `target` first, so
+ * the activation that follows does not render over it.
+ *
+ * With the marker's `base` — the vanished profile's entry — the edits are the
+ * difference between the live files and what that entry rendered, merged into
+ * `target` like a pulled change. Without one, nothing tells an edit apart from
+ * what the vanished profile said, so everything the live config holds that
+ * `target` lacks is kept: its plugins are added, and its settings, MCP servers
+ * and routing win where they differ. Never a key dropped.
+ *
+ * Magus-installed skill folders of the vanished profile that were edited
+ * become custom skills; unedited ones are removed by the activation as usual.
+ * A live file that cannot be read is a problem, and nothing is changed.
+ */
+export async function absorbOrphanedProfile(
+	projectPath: string,
+	target: string,
+): Promise<ReconcileResult> {
+	// An older layout's marker belongs to the older-layout path, which reads
+	// through its links (`absorbOlderLayout`).
+	if (!(await hasCurrentMarker(projectPath))) return emptyResult(null);
+	const marker = await readActiveMarker(projectPath);
+	if (!marker) return emptyResult(null);
+	const manifest = await readManifest(projectPath);
+	const targetEntry = manifest.profiles[target];
+	const orphan = marker.profile;
+	if (manifest.profiles[orphan] || !targetEntry) return emptyResult(null);
+	const result = emptyResult(target);
+
+	const edited: LiveFileKey[] = [];
+	for (const key of LIVE_FILE_KEYS) {
+		if ((await liveKind(key, projectPath)) !== "file") continue;
+		if ((await liveHash(key, projectPath)) !== marker.files[key]) {
+			edited.push(key);
+		}
+	}
+	const { edited: editedSkills } = await inspectManagedSkills(
+		marker.skills,
+		projectPath,
+	);
+	if (edited.length === 0 && editedSkills.length === 0) return result;
+
+	const base = marker.base ?? null;
+	const renderedBase = base
+		? await renderProfile(
+				{ ...manifest, profiles: { ...manifest.profiles, [orphan]: base } },
+				orphan,
+			)
+		: null;
+	const live: Record<LiveFileKey, Record<string, unknown> | null> = {
+		settings: renderedBase?.settings ?? {},
+		mcp: renderedBase?.mcp ?? { mcpServers: {} },
+		models: renderedBase?.models ?? null,
+	};
+	for (const key of edited) {
+		try {
+			const value = await readLiveJson(key, projectPath);
+			if (value) checkModels(key, value);
+			live[key] = value;
+		} catch (error) {
+			const why = error instanceof Error ? error.message : String(error);
+			result.unreadable.push(
+				new SettingsParseError(livePath(key, projectPath), error),
+			);
+			result.problems.push(
+				`${rel(projectPath, key)} cannot be read (${why}) — fix it by hand; magus left it as it is and did not switch`,
+			);
+		}
+	}
+	if (result.problems.length > 0) {
+		result.lines.push(...result.problems);
+		return result;
+	}
+
+	// Every manifest plugin is rendered as `false` where not wanted, so a
+	// `false` for one of them says nothing about an edit — nor does one for a
+	// plugin the last render named that no profile has any more.
+	const union = new Set<string>(marker.allPluginIds ?? []);
+	for (const id of Object.keys(manifest.profiles)) {
+		const closure = await resolveProfile(manifest, id, { binResolver: noBins });
+		for (const pluginId of Object.keys(closure.plugins)) union.add(pluginId);
+	}
+	const view: LiveView = {
+		settings: live.settings ?? {},
+		mcp: live.mcp ?? {},
+		models: live.models,
+	};
+
+	let merged: ProfileManifestEntry;
+	if (base) {
+		const local = computeAbsorb(base, view, union).entry;
+		const merge = merge3(base, local, targetEntry);
+		merged = merge.entry;
+		result.conflicts.push(...merge.conflicts);
+	} else {
+		const everything = computeAbsorb({ name: orphan }, view, union).entry;
+		merged = mergeAdditively(targetEntry, everything);
+	}
+	// A plugin the target pins keeps its pin when the edit merely enabled it.
+	for (const [id, pin] of Object.entries(targetEntry.plugins ?? {})) {
+		if (isOn(pin) && merged.plugins?.[id] === "latest") {
+			merged.plugins[id] = pin;
+		}
+	}
+
+	const changes = diffEntries(targetEntry, merged);
+	if (changes.length > 0) {
+		merged.updatedAt = new Date().toISOString();
+		await writeManifest(
+			{ ...manifest, profiles: { ...manifest.profiles, [target]: merged } },
+			projectPath,
+		);
+	}
+	result.changes.push(...changes);
+
+	if (editedSkills.length > 0) {
+		const managed = { ...marker.skills };
+		for (const folder of editedSkills) {
+			delete managed[folder];
+			const ref = (base?.skills ?? []).find((r) => skillFolder(r) === folder);
+			result.changes.push({
+				kind: "skill-released",
+				skill: ref?.name ?? folder,
+				folder,
+			});
+		}
+		await writeActiveMarker({ ...marker, skills: managed }, projectPath);
+		await updateSkillIgnoreLines(
+			projectPath,
+			editedSkills,
+			Object.keys(managed),
+		);
+	}
+
+	if (result.changes.length > 0) {
+		result.lines.push(
+			`Profile "${orphan}" no longer exists in profiles.json — its unsaved changes were added to profile "${target}"`,
+		);
+		if (!base && changes.length > 0) {
+			result.lines.push(
+				`There is no record of what "${orphan}" contained, so everything in the live config that "${target}" lacked was kept`,
+			);
+		}
+		result.lines.push(...result.changes.map((c) => describeChange(c, target)));
+		result.lines.push(
+			...result.conflicts.map((at) => describeConflict(at, target)),
+		);
+	}
+	return result;
+}
+
+/**
+ * Before an older layout is converted: record what Claude Code wrote through
+ * its links into profile `into`.
+ *
+ * magus 7.4.1 and earlier linked `.claude/settings.json`, `.mcp.json` and
+ * `.claude/models.json` into `.claude/_profiles/<name>/`, and Claude Code
+ * before 2.1.280 wrote its edits THROUGH those links. Each file is read
+ * through its link. (The release after 7.4.1 kept real settings/mcp files and
+ * a marker at `_profiles/.active` with their hashes; a real file whose hash
+ * still matches it is unedited and skipped.)
+ *
+ * The absorption is ADDITIVE ({@link absorbAdditively}). Those files were
+ * rendered at the last `magus install`, and 7.4.1 never re-rendered on a
+ * pull, so they may predate a teammate's change to profiles.json: a plugin
+ * profiles.json has that the old file lacks is as likely a pulled addition as
+ * a local removal, and the two cannot be told apart. So what the old files add
+ * is added; where they disagree with profiles.json, profiles.json's value is
+ * kept and the key named; and nothing is removed — a removal made under the
+ * older layout is not applied, which is the direction that loses nothing. The
+ * old files themselves are kept in the `-layout` backup.
+ *
+ * `named` is the profile the older layout names. When profiles.json no longer
+ * defines it, `into` is the profile about to be activated instead.
+ *
+ * A file that cannot be read stops everything: nothing is written, and the
+ * caller must not convert.
+ */
+export async function absorbOlderLayout(
+	projectPath: string,
+	into: string,
+	named: string | null,
+): Promise<ReconcileResult> {
+	const manifest = await readManifest(projectPath);
+	const entry = manifest.profiles[into];
+	if (!entry) return emptyResult(null);
+	const result = emptyResult(into);
+	const legacyHashes = await readLegacyMarkerHashes(projectPath);
+	const rendered = await renderProfile(manifest, into);
+	const view: Record<LiveFileKey, Record<string, unknown> | null> = {
+		settings: rendered.settings,
+		mcp: rendered.mcp,
+		models: rendered.models,
+	};
+	let readAny = false;
+	for (const key of LIVE_FILE_KEYS) {
+		const read = await readLiveThrough(key, projectPath);
+		if (read.missing) continue;
+		if (
+			!read.isLink &&
+			legacyHashes?.[key] &&
+			read.hash === legacyHashes[key]
+		) {
+			continue; // The release before's own unedited copy.
+		}
+		try {
+			if (read.error) throw read.error;
+			if (read.value) checkModels(key, read.value);
+		} catch (error) {
+			const parseError =
+				error instanceof SettingsParseError
+					? error
+					: new SettingsParseError(livePath(key, projectPath), error);
+			result.unreadable.push(parseError);
+			result.problems.push(
+				`${rel(projectPath, key)} cannot be read (${parseError.detail}) — fix it by hand; magus left the older layout as it is and did not convert it`,
+			);
+			continue;
+		}
+		view[key] = read.value;
+		readAny = true;
+	}
+	if (result.problems.length > 0) {
+		result.lines.push(...result.problems);
+		return result;
+	}
+	if (!readAny) return result;
+
+	const exact = named === into;
+	const absorbed = absorbAdditively(
+		entry,
+		{
+			settings: view.settings ?? {},
+			mcp: view.mcp ?? {},
+			models: view.models,
+		},
+		await olderRenderIds(projectPath, named, rendered.allPluginIds),
+	);
+	const next = absorbed.entry;
+	const changes = diffEntries(entry, next);
+	if (changes.length > 0) {
+		next.updatedAt = new Date().toISOString();
+		await writeManifest(
+			{ ...manifest, profiles: { ...manifest.profiles, [into]: next } },
+			projectPath,
+		);
+		result.changes.push(...changes);
+		result.lines.push(
+			exact
+				? `Changes Claude Code made under the older layout were added to profile "${into}"`
+				: `Profile "${named ?? "?"}" no longer exists in profiles.json — its unsaved changes under the older layout were added to profile "${into}"`,
+		);
+		if (!exact) {
+			result.lines.push(
+				`There is no record of what "${named ?? "?"}" contained, so everything in its files that "${into}" lacked was added`,
+			);
+		}
+		result.lines.push(...changes.map((c) => describeChange(c, into)));
+	}
+	result.conflicts.push(...absorbed.conflicts);
+	result.lines.push(
+		...absorbed.conflicts.map((at) => describeLayoutConflict(at, into)),
+	);
+	if (absorbed.keptMore) {
+		result.lines.push(
+			`profiles.json has entries the older layout's files lack; they were kept — a removal made under the older layout is not applied (the older files are in the -layout backup under .claude/.magus-backups/)`,
+		);
+	}
+	return result;
+}
+
+/**
+ * The plugin ids an older layout's render could have written as `false`.
+ *
+ * magus 7.4.1 wrote `false` only for plugins some profile named when it
+ * rendered, and it rendered every profile: each OTHER profile's
+ * `_profiles/<m>/settings.json` — a file Claude Code never writes, since only
+ * the active profile's was linked — lists every id any profile named at that
+ * render. Those, plus every id the manifest names now, are render output. A
+ * `false` for any other id was written by the user (a project-scope disable
+ * of a plugin enabled elsewhere) and is kept. With no other profile directory
+ * to read, the manifest's ids alone decide.
+ */
+async function olderRenderIds(
+	projectPath: string,
+	named: string | null,
+	currentIds: readonly string[],
+): Promise<Set<string>> {
+	const ids = new Set(currentIds);
+	for (const { name, dir } of await legacyProfileDirs(projectPath)) {
+		if (name === named) continue;
+		try {
+			const settings: unknown = await fs.readJson(
+				path.join(dir, "settings.json"),
+			);
+			if (isJsonRecord(settings) && isJsonRecord(settings.enabledPlugins)) {
+				for (const id of Object.keys(settings.enabledPlugins)) ids.add(id);
+			}
+		} catch {
+			// No readable render there; the others and the manifest still decide.
+		}
+	}
+	return ids;
+}
+
+/** One line for a value the older layout's file and profiles.json disagree on. */
+export function describeLayoutConflict(at: string, profile: string): string {
+	return `Profile "${profile}": ${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/`;
+}
+
+/**
+ * Add to `entry` what `old` has and `entry` lacks, recursively, and nothing
+ * else: objects gain missing keys, arrays of scalars gain missing items, and
+ * a value both hold differently keeps `entry`'s — its path goes in
+ * `conflicts`. `keptMore` records that `entry` holds something `old` lacks.
+ */
+function addMissing(
+	entryValue: unknown,
+	oldValue: unknown,
+	at: string,
+	conflicts: string[],
+	flags: { keptMore: boolean },
+): unknown {
+	if (oldValue === undefined) {
+		if (entryValue !== undefined) flags.keptMore = true;
+		return entryValue;
+	}
+	if (entryValue === undefined) return oldValue;
+	if (jsonEqual(entryValue, oldValue)) return entryValue;
+	if (isJsonRecord(entryValue) && isJsonRecord(oldValue)) {
+		const out: Record<string, unknown> = { ...entryValue };
+		for (const key of new Set([
+			...Object.keys(entryValue),
+			...Object.keys(oldValue),
+		])) {
+			const value = addMissing(
+				entryValue[key],
+				oldValue[key],
+				`${at}.${key}`,
+				conflicts,
+				flags,
+			);
+			if (value !== undefined) out[key] = value;
+		}
+		return out;
+	}
+	if (isScalarArray(entryValue) && isScalarArray(oldValue)) {
+		const have = new Set(entryValue.map((v) => canonicalJson(v)));
+		const oldHas = new Set(oldValue.map((v) => canonicalJson(v)));
+		if ([...have].some((k) => !oldHas.has(k))) flags.keptMore = true;
+		const out = [...entryValue];
+		for (const item of oldValue) {
+			const k = canonicalJson(item);
+			if (have.has(k)) continue;
+			out.push(item);
+			have.add(k);
+		}
+		return out;
+	}
+	conflicts.push(at);
+	return entryValue;
+}
+
+/**
+ * Absorb an older layout's files into `entry` ADDITIVELY — see
+ * {@link absorbOlderLayout} for why nothing is removed.
+ *
+ *   plugins      a plugin the old file enables and the entry does not name is
+ *                added ("latest"); a `false` for a plugin the entry does not
+ *                name is skipped when `renderIds` holds it (the render wrote
+ *                it) and added as `false` when it does not (the user wrote
+ *                it); where the old file and the entry disagree — one
+ *                enables, the other says `false` — the entry's value stands
+ *   settings     missing keys and missing array items are added, recursively
+ *   mcpServers   servers the entry lacks are added
+ *   models       added when the entry routes nothing
+ *
+ * Everywhere else the two disagree, the entry's value is kept and the key
+ * path is returned in `conflicts`.
+ */
+export function absorbAdditively(
+	entry: ProfileManifestEntry,
+	old: LiveView,
+	renderIds: ReadonlySet<string>,
+): { entry: ProfileManifestEntry; conflicts: string[]; keptMore: boolean } {
+	const conflicts: string[] = [];
+	const flags = { keptMore: false };
+	const next: ProfileManifestEntry = { ...entry };
+	const resolved = resolveExtends(entry);
+
+	// Plugins.
+	const enabled = isJsonRecord(old.settings.enabledPlugins)
+		? old.settings.enabledPlugins
+		: {};
+	const own: Record<string, string | boolean> = { ...(entry.plugins ?? {}) };
+	for (const [id, value] of Object.entries(enabled)) {
+		const declared = resolved.plugins?.[id];
+		if (value === true) {
+			if (isOn(declared)) continue;
+			if (declared === false) conflicts.push(`plugins.${id}`);
+			else own[id] = "latest";
+		} else if (value === false && isOn(declared)) {
+			conflicts.push(`plugins.${id}`);
+		} else if (
+			value === false &&
+			declared === undefined &&
+			!renderIds.has(id)
+		) {
+			own[id] = false;
+		}
+	}
+	for (const [id, declared] of Object.entries(resolved.plugins ?? {})) {
+		if (isOn(declared) && enabled[id] === undefined) flags.keptMore = true;
+	}
+	setOrDelete(next, "plugins", own);
+
+	// Settings, recursively; `extends` keys compare against what they resolve to.
+	const { enabledPlugins: _drop, ...oldSettings } = withoutMachineKeys(
+		old.settings,
+	);
+	const resolvedSettings = resolved.settings ?? {};
+	const merged = addMissing(
+		resolvedSettings,
+		oldSettings,
+		"settings",
+		conflicts,
+		flags,
+	) as Record<string, unknown>;
+	const ownSettings: Record<string, unknown> = { ...(entry.settings ?? {}) };
+	for (const [key, value] of Object.entries(merged)) {
+		if (!jsonEqual(value, resolvedSettings[key])) ownSettings[key] = value;
+	}
+	setOrDelete(next, "settings", ownSettings);
+
+	// MCP servers: added whole, never merged into a server the entry has.
+	const oldServers = isJsonRecord(old.mcp.mcpServers)
+		? (old.mcp.mcpServers as Record<string, McpServerConfig>)
+		: {};
+	const servers: Record<string, McpServerConfig> = {
+		...(entry.mcpServers ?? {}),
+	};
+	for (const [name, config] of Object.entries(oldServers)) {
+		if (!(name in servers)) servers[name] = config;
+		else if (!jsonEqual(servers[name], config)) {
+			conflicts.push(`mcpServers.${name}`);
+		}
+	}
+	for (const name of Object.keys(entry.mcpServers ?? {})) {
+		if (!(name in oldServers)) flags.keptMore = true;
+	}
+	setOrDelete(next, "mcpServers", servers);
+
+	// Model routing: a unit.
+	if (old.models) {
+		if (!resolved.models) {
+			next.models = old.models as unknown as ProfileManifestEntry["models"];
+		} else if (!jsonEqual(resolved.models, old.models)) {
+			conflicts.push("models");
+		}
+	}
+
+	return { entry: next, conflicts, keptMore: flags.keptMore };
+}
+
+/**
+ * Absorb edits to the live config into the active profile, then regenerate the
+ * live config if the profile changed in profiles.json. See the module doc.
+ *
+ * Does nothing without a current-format marker naming a profile profiles.json
+ * defines — the active-profile check (`profile-state.ts`) reports those
+ * states, and an older layout is absorbed through its links instead
+ * (`absorbOlderLayout`).
+ *
+ * Writes NOTHING when a live file cannot be read: `problems` then says why,
+ * and the manifest and every live file are exactly as they were.
+ */
+export interface ReconcileOptions
+	extends Pick<ActivateOptions, "installSkill"> {
+	/**
+	 * Set by `withCliBookkeeping` when the Claude CLI's installs have just
+	 * finished normally: discarding their records is expected then, and not
+	 * worth a line. Without it, discarding them means a run was interrupted.
+	 */
+	cliRunFinished?: boolean;
+}
+
+export async function reconcileActiveProfile(
+	projectPath: string,
+	opts: ReconcileOptions = {},
+): Promise<ReconcileResult> {
+	if (!(await hasCurrentMarker(projectPath))) return emptyResult(null);
+	const marker = await readActiveMarker(projectPath);
+	if (!marker) return emptyResult(null);
+	const manifest = await readManifest(projectPath);
+	const current = manifest.profiles[marker.profile];
+	if (!current) return emptyResult(null);
+	const name = marker.profile;
+
+	const edited: LiveFileKey[] = [];
+	const missing: LiveFileKey[] = [];
+	for (const key of LIVE_FILE_KEYS) {
+		const kind = await liveKind(key, projectPath);
+		if (kind === "file") {
+			if ((await liveHash(key, projectPath)) !== marker.files[key]) {
+				edited.push(key);
+			}
+		} else if (kind === "missing" && marker.files[key] !== undefined) {
+			missing.push(key);
+		}
+	}
+	const { edited: editedSkills } = await inspectManagedSkills(
+		marker.skills,
+		projectPath,
+	);
+	// Everything the live files are rendered from, not just this entry: a
+	// teammate's change to ANOTHER profile's plugins changes which `false`
+	// entries this profile writes.
+	const definitionChanged =
+		(await renderProfile(manifest, name)).definition !== marker.definition;
+	// Whether THIS entry changed underneath the live files — the case that
+	// needs merging against `base`, and the one the message names.
+	const entryChanged =
+		marker.base !== undefined && !jsonEqual(marker.base, current);
+
+	if (
+		edited.length === 0 &&
+		missing.length === 0 &&
+		editedSkills.length === 0 &&
+		!definitionChanged &&
+		!marker.cliBookkeeping
+	) {
+		return emptyResult(name);
+	}
+
+	const result = emptyResult(name);
+
+	// ── a. absorb ────────────────────────────────────────────────────────────
+	const base = marker.base ?? current;
+	const renderedBase = await renderProfile(
+		{ ...manifest, profiles: { ...manifest.profiles, [name]: base } },
+		name,
+	);
+	const live: Record<LiveFileKey, Record<string, unknown> | null> = {
+		settings: renderedBase.settings,
+		mcp: renderedBase.mcp,
+		models: renderedBase.models,
+	};
+	const parsed = new Map<LiveFileKey, Record<string, unknown>>();
+	const discarded: string[] = [];
+	for (const key of LIVE_FILE_KEYS) {
+		if ((await liveKind(key, projectPath)) !== "file") continue;
+		try {
+			let value = await readLiveJson(key, projectPath);
+			if (!value) continue;
+			checkModels(key, value);
+			// The Claude CLI's installs ran (or were interrupted) since the last
+			// render: see `withCliBookkeeping`. Its records are bookkeeping, not
+			// edits — but only a `true` for a plugin the install could have
+			// written is one of them. Everything else is the user's: a plugin
+			// they installed themselves, a `false`, every other key.
+			if (key === "settings" && marker.cliBookkeeping) {
+				value = withoutCliRecords(
+					value,
+					new Set(marker.allPluginIds ?? (await allPluginIdsOf(manifest))),
+					base,
+					renderedBase,
+					discarded,
+				);
+			}
+			parsed.set(key, value);
+			live[key] = value;
+		} catch (error) {
+			const why = error instanceof Error ? error.message : String(error);
+			if (edited.includes(key)) {
+				result.unreadable.push(
+					new SettingsParseError(livePath(key, projectPath), error),
+				);
+				result.problems.push(
+					`${rel(projectPath, key)} cannot be read (${why}) — fix it by hand; magus left it as it is and did not absorb it`,
+				);
+			}
+		}
+	}
+	// Nothing is written — not the manifest, not a regenerated file — when a
+	// live file cannot be read. It was reported as left as it is; it must be.
+	if (result.problems.length > 0) {
+		result.lines.push(...result.problems);
+		return result;
+	}
+	if (discarded.length > 0 && !opts.cliRunFinished) {
+		result.lines.push(
+			`An interrupted magus install left the Claude CLI's plugin records in .claude/settings.json — discarded them (${discarded.join(", ")})`,
+		);
+	}
+
+	let local: ProfileManifestEntry = base;
+	if (edited.some((key) => parsed.has(key))) {
+		const absorbed = computeAbsorb(
+			base,
+			{
+				settings: live.settings ?? {},
+				mcp: live.mcp ?? {},
+				models: live.models,
+			},
+			renderedFalseIds(
+				await otherProfilesPlugins(manifest, name),
+				marker.allPluginIds,
+				base,
+			),
+		);
+		local = absorbed.entry;
+		result.changes.push(...absorbed.changes);
+	}
+
+	const released = new Set(editedSkills);
+	if (released.size > 0) {
+		const refs = local.skills ?? [];
+		for (const folder of released) {
+			const ref = refs.find((r) => skillFolder(r) === folder);
+			result.changes.push({
+				kind: "skill-released",
+				skill: ref?.name ?? folder,
+				folder,
+			});
+		}
+		const kept = refs.filter((r) => !released.has(skillFolder(r)));
+		local = { ...local, updatedAt: new Date().toISOString() };
+		if (kept.length > 0) local.skills = kept;
+		// biome-ignore lint/performance/noDelete: absent, not undefined, in profiles.json
+		else delete local.skills;
+	}
+
+	let merged = local;
+	if (entryChanged) {
+		const merge = merge3(base, local, current);
+		merged = merge.entry;
+		result.conflicts.push(...merge.conflicts);
+	}
+	// An absorbed enable is "latest" — Claude Code never says which version —
+	// so a plugin profiles.json pins keeps its pin (the orphan path's rule).
+	merged = keepPins(merged, current);
+	const nextManifest: ProfileManifest = {
+		...manifest,
+		profiles: { ...manifest.profiles, [name]: merged },
+	};
+	if (!jsonEqual(merged, current))
+		await writeManifest(nextManifest, projectPath);
+
+	const managed: Record<string, string> = {};
+	for (const [folder, hash] of Object.entries(marker.skills)) {
+		if (!released.has(folder)) managed[folder] = hash;
+	}
+	if (released.size > 0) {
+		await updateSkillIgnoreLines(
+			projectPath,
+			[...released],
+			Object.keys(managed),
+		);
+	}
+
+	// ── b. regenerate ────────────────────────────────────────────────────────
+	const notes: string[] = [];
+	if (definitionChanged) {
+		// The marker loses the released folders first, so activation neither
+		// removes them nor keeps an ignore line for them.
+		await writeActiveMarker({ ...marker, skills: managed }, projectPath);
+		const before = new Map<LiveFileKey, string | null>();
+		for (const key of LIVE_FILE_KEYS) {
+			before.set(key, await liveHash(key, projectPath));
+		}
+		try {
+			const activation = await activateProfile(
+				nextManifest,
+				name,
+				projectPath,
+				{
+					installSkill: opts.installSkill,
+				},
+			);
+			notes.push(...activationNotes(activation));
+		} catch (error) {
+			result.problems.push(
+				error instanceof Error ? error.message : String(error),
+			);
+		}
+		for (const key of LIVE_FILE_KEYS) {
+			if ((await liveHash(key, projectPath)) !== before.get(key)) {
+				result.regenerated.push(rel(projectPath, key));
+			}
+		}
+	} else {
+		const rendered: RenderedProfile = await renderProfile(nextManifest, name);
+		const files: ActiveMarker["files"] = { ...marker.files };
+		for (const key of LIVE_FILE_KEYS) {
+			if (missing.includes(key)) {
+				const hash = await writeLiveFile(key, rendered[key], projectPath);
+				if (hash) {
+					files[key] = hash;
+					result.restored.push(rel(projectPath, key));
+				} else {
+					delete files[key];
+				}
+				continue;
+			}
+			if (!edited.includes(key) || !parsed.has(key)) continue;
+			const value = parsed.get(key) ?? null;
+			if (losesNothing(key, value, rendered[key])) {
+				const hash = await writeLiveFile(key, rendered[key], projectPath);
+				if (hash) files[key] = hash;
+				else delete files[key];
+			} else if (key === "settings" && marker.cliBookkeeping) {
+				// It says something the manifest cannot express, and it still
+				// holds the CLI's records: written without them, never kept as is.
+				const hash = await writeLiveFile(key, value, projectPath);
+				if (hash) files[key] = hash;
+			} else {
+				// The file says something the manifest cannot express; it is
+				// kept byte for byte and recorded as it stands.
+				const hash = await liveHash(key, projectPath);
+				if (hash) files[key] = hash;
+			}
+		}
+		await writeActiveMarker(
+			markerFor(name, rendered, files, managed),
+			projectPath,
+		);
+	}
+
+	result.lines.push(...result.changes.map((c) => describeChange(c, name)));
+	result.lines.push(
+		...result.conflicts.map((at) => describeConflict(at, name)),
+	);
+	// A marker from before definitions were recorded regenerates silently: that
+	// is a conversion, not a change anybody made to profiles.json.
+	if (result.regenerated.length > 0 && marker.definition !== undefined) {
+		result.lines.push(
+			entryChanged || marker.base === undefined
+				? `Profile "${name}" changed in profiles.json — regenerated ${result.regenerated.join(", ")}`
+				: `Another profile's plugins changed in profiles.json — regenerated ${result.regenerated.join(", ")} for profile "${name}"`,
+		);
+	}
+	result.lines.push(...notes);
+	for (const file of result.restored) {
+		result.lines.push(`Restored ${file} from profile "${name}"`);
+	}
+	result.lines.push(...result.problems);
+	return result;
+}