magus-cli 7.1.0 → 7.3.0

package/src/services/manifest.ts

@@ -52,6 +52,12 @@ export function migrateToV2(raw: unknown): ProfileManifest {
 	// Only carry strictVersions when enabled, so a committed manifest that
 	// doesn't opt in stays minimal (no spurious `"strictVersions": false`).
 	if (obj.strictVersions === true) manifest.strictVersions = true;
+	// Carried through even when it names no existing profile: dropping it here
+	// would silently "fix" a typo that `validateManifest` is meant to report,
+	// and the commands that read it all check the id resolves first.
+	if (typeof obj.default === "string" && obj.default !== "") {
+		manifest.default = obj.default;
+	}
 	return manifest;
 }
 
@@ -110,6 +116,21 @@ export function validateManifest(
 		errors.push({ path: "profiles", message: "no profiles defined" });
 	}
 
+	// A `default` naming nothing is worse than none: a fresh clone would fall
+	// through to asking, with no sign that the repo tried to answer and got the
+	// id wrong. Reported here so it fails the same gate every other manifest
+	// mistake does, rather than being discovered as silence.
+	if (manifest.default !== undefined) {
+		if (typeof manifest.default !== "string") {
+			errors.push({ path: "default", message: "must be a profile id" });
+		} else if (!ids.includes(manifest.default)) {
+			errors.push({
+				path: "default",
+				message: `no profile "${manifest.default}" — declared: ${ids.join(", ")}`,
+			});
+		}
+	}
+
 	for (const [id, entry] of Object.entries(manifest.profiles ?? {})) {
 		const base = `profiles.${id}`;
 		if (!entry || typeof entry !== "object") {

package/src/services/plugin-manager.ts

@@ -45,6 +45,7 @@ import {
 	isAuthoritative,
 	resolveMarketplacePlugins,
 } from "./marketplace-fetcher.js";
+import { resolveLoadedVersions } from "./plugin-resolution.js";
 export {
 	fetchMarketplacePlugins,
 	getMarketplaceFetchFailures,
@@ -72,6 +73,17 @@ export interface PluginInfo {
 	marketplaceDisplay: string;
 	enabled: boolean;
 	installedVersion?: string;
+	/**
+	 * The version Claude Code's loader will ACTUALLY load in this project, or
+	 * null when it will load nothing here.
+	 *
+	 * An INDEPENDENT column from `installedVersion`, not a correction of it. The
+	 * two answer different questions — what magus records as installed here,
+	 * versus what the loader resolves (services/plugin-resolution.ts) — and when
+	 * they disagree the session runs code that no version magus records names.
+	 * That disagreement is the finding; averaging the two would hide it.
+	 */
+	loadedVersion?: string | null;
 	/**
 	 * Provably behind the catalog, on ONE version pair.
 	 *
@@ -277,6 +289,18 @@ export async function getAvailablePlugins(
 	const enabledPlugins = await getEnabledPlugins(projectPath);
 	const installedVersions = await getInstalledPluginVersions(projectPath);
 
+	// What Claude Code will LOAD here, which is a different question from what is
+	// installed here and is answered by a different algorithm — the loader's own,
+	// ported in services/plugin-resolution.ts. Resolved once for the whole
+	// registry and carried alongside `installedVersion` on every row below; where
+	// the two disagree, the classifier calls it `stale-load`.
+	const loadedVersions = resolveLoadedVersions(
+		await readInstalledPluginsRegistry(),
+		projectPath ?? process.cwd(),
+	);
+	const loadedVersionOf = (pluginId: string): string | null =>
+		loadedVersions[pluginId] ?? null;
+
 	// Fetch all scopes for per-scope status
 	const userEnabledPlugins = await getGlobalEnabledPlugins();
 	const userInstalledVersions = await getGlobalInstalledPluginVersions();
@@ -384,6 +408,7 @@ export async function getAvailablePlugins(
 				marketplaceDisplay: marketplace.displayName,
 				enabled: isEnabled,
 				installedVersion: installedVersion,
+				loadedVersion: loadedVersionOf(pluginId),
 				hasUpdate: isBehind(plugin.version, installedVersion) === true,
 				catalogSource: resolution.source,
 				updateCheckFailed: unverified,
@@ -423,6 +448,7 @@ export async function getAvailablePlugins(
 				marketplaceDisplay: localMp.name || formatMarketplaceName(mpName),
 				enabled: isEnabled,
 				installedVersion: installedVersion,
+				loadedVersion: loadedVersionOf(pluginId),
 				hasUpdate: isBehind(localPlugin.version, installedVersion) === true,
 				...scopeStatus,
 				category: localPlugin.category,
@@ -472,6 +498,7 @@ export async function getAvailablePlugins(
 			marketplaceDisplay: localMp?.name || formatMarketplaceName(mpName),
 			enabled: isEnabled,
 			installedVersion: installedVersion,
+			loadedVersion: loadedVersionOf(pluginId),
 			hasUpdate,
 			isOrphaned: true,
 			...scopeStatus,
@@ -652,6 +679,40 @@ export function isBehind(
 	return bothOpaque ? true : null;
 }
 
+/**
+ * Is `loaded` behind `target` in a way that MOVING FORWARD would actually fix?
+ *
+ * THE predicate behind the `stale-load` state. Both the classifier (which counts
+ * broken plugins in the Plugins header) and `findStaleLoads` (which counts them
+ * for the startup popup) ask this and nothing else, so the two surfaces cannot
+ * report different numbers for the same directory. They did: the popup said 8
+ * where the header said 6, because it asked {@link isBehind} instead.
+ *
+ * Stricter than `isBehind` in exactly one place, and deliberately: `isBehind`
+ * answers TRUE for two differing opaque ids, because for its question — "is this
+ * what the marketplace publishes now" — a different commit sha means no. That
+ * reasoning does not carry here. "Move the rows forward from sha A to sha B" is
+ * not a repair, it is a coin toss: the two carry no ordering, so nothing
+ * establishes which is later. Measured on the reporting machine, that alone put
+ * `skill-creator@claude-plugins-official` (two differing shas) and
+ * `plugin-dev@claude-plugins-official` (version literally `"unknown"`) into the
+ * popup's count, and neither could be repaired — `repairStaleLoad` rejects them
+ * at its cache-directory check.
+ *
+ * So this requires an ORDERED pair: `compareVersions` must return a number, and
+ * that number must be positive. A version against `null`, a semver against an
+ * opaque id, `"unknown"` against anything, and two differing shas all answer
+ * false — "cannot rank these" is never grounds for rewriting a registry row.
+ */
+export function isRepairablyBehind(
+	target: string | null | undefined,
+	loaded: string | null | undefined,
+): boolean {
+	if (!target || !loaded) return false;
+	const cmp = compareVersions(target, loaded);
+	return cmp !== null && cmp > 0;
+}
+
 // Get installed plugin versions from settings.json (shared, not secret)
 async function getInstalledPluginVersions(
 	projectPath?: string,

package/src/services/plugin-resolution.ts

@@ -0,0 +1,280 @@
+/**
+ * What Claude Code's loader will ACTUALLY load in this directory.
+ *
+ * Ported from Claude Code 2.1.274, decompiled: the relevance filter `SF`
+ * (byte 178070986) and the selection function `Bls` (byte 178140984). The port
+ * was validated against the real loader over 123/123 plugin resolutions across
+ * 12 repositories and worktrees. RE-VALIDATE IT WHEN CLAUDE CODE UPDATES —
+ * this file describes someone else's algorithm, so a new release can move it
+ * without anything here failing.
+ *
+ * Why it exists: magus reported versions from `settings.installedPluginVersions`
+ * overlaid with this project's `installed_plugins.json` rows (see
+ * `pickRegistryEntry` in claude-settings.ts). The loader consults neither of
+ * those orderings, so magus could report "up to date" while the session in that
+ * same directory loaded a two-versions-old plugin. The two answers are
+ * genuinely different questions and both are kept:
+ *
+ *   pickRegistryEntry  — "what does magus consider installed for this scope"
+ *   pickLoadedEntry    — "what will Claude Code load here"
+ *
+ * This module holds NO magus policy. It answers the second question only, so
+ * that a disagreement between the two is visible rather than averaged away.
+ *
+ * KNOWN DIVERGENCES from the decompiled original, both of which only ever REMOVE
+ * candidates — so each can make this module name an entry the loader does not
+ * use, and neither can make it miss one the loader does use:
+ *
+ *  1. The binary additionally rejects an entry whose `installPath` fails a
+ *     path-safety check (`suspect(installPath)`). Not ported — every
+ *     `installPath` is treated as non-suspect here.
+ *  2. The binary's relevance filter reads `entry.projectPath === originalCwd ||
+ *     repoRoot(entry.projectPath) === repoRoot(originalCwd)` with no guard on
+ *     `projectPath` being absent at all. A project-scope row carrying no
+ *     `projectPath` is rejected outright here (`isRelevantInstallation`), because
+ *     what `repoRoot(undefined)` answers inside the binary was not measured and
+ *     guessing it would put a row into the selection on a guess. Claude Code
+ *     writes `projectPath` for every project-scope install, so the case is
+ *     theoretical rather than observed.
+ *
+ * A THIRD divergence was removed rather than documented: two rootless paths used
+ * to compare unequal here, so in a directory belonging to no repository every
+ * rootless row was irrelevant to magus while the loader still counted it. See
+ * {@link isRelevantInstallation}.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import type {
+	InstalledPluginEntry,
+	InstalledPluginsRegistry,
+} from "../types/index.js";
+
+/**
+ * Memo for {@link repoRootForPath}. A registry holds one row per project path
+ * and a well-used machine has hundreds of them, most repeated across plugins;
+ * each miss walks the tree to the filesystem root with a `stat` per level.
+ *
+ * Deliberately passed in rather than held at module scope: a git root can come
+ * into existence while the TUI is open, and a process-lifetime cache would
+ * answer from before it did.
+ */
+export type RepoRootCache = Map<string, string | null>;
+
+/**
+ * Claude Code writes a `managed` scope for policy-installed plugins. The
+ * registry type in `types/index.ts` names only the three scopes magus itself
+ * writes, so the extra one is widened here instead of loosening a type that
+ * dozens of call sites narrow on.
+ */
+type LoaderScope = InstalledPluginEntry["scope"] | "managed";
+
+/**
+ * Scopes the loader treats as relevant to EVERY project, whatever its path:
+ * `user` (the machine-wide install) and `managed` (administrator policy).
+ *
+ * Exported because a writer has to ask the same question the filter does. A row
+ * in one of these scopes is not this repository's record — moving it forward
+ * changes what every project on the machine loads — so `repairStaleLoad` refuses
+ * to rewrite one instead of quietly reaching that far.
+ */
+export function isMachineWideScope(
+	scope: LoaderScope | string | undefined,
+): boolean {
+	return scope === "user" || scope === "managed";
+}
+
+/** `.git` as an entry of `dir`: a directory (real checkout), a file (pointer), or absent. */
+function gitEntryKind(dir: string): "dir" | "file" | null {
+	try {
+		const stat = fs.statSync(path.join(dir, ".git"));
+		if (stat.isDirectory()) return "dir";
+		if (stat.isFile()) return "file";
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * The main repository root behind a linked worktree's `.git` FILE, which holds
+ * `gitdir: <main>/.git/worktrees/<name>`.
+ *
+ * The `.git` component is searched for first and the `worktrees` component only
+ * as a fallback, because the former sits ABOVE the latter in the usual layout
+ * and matching `worktrees` first would answer `<main>/.git`. The fallback is
+ * for a common directory kept outside a `.git` directory (a bare
+ * `/srv/repo.git/worktrees/<name>`), where the repository itself is the closest
+ * thing to a root. The same walk maps a submodule's
+ * `<super>/.git/modules/<name>` onto the superproject root.
+ */
+function mainRootFromGitFile(gitFile: string, dir: string): string | null {
+	let gitdir: string;
+	try {
+		const match = /^\s*gitdir:\s*(.+?)\s*$/m.exec(
+			fs.readFileSync(gitFile, "utf8"),
+		);
+		// A `.git` file we cannot parse still marks a working tree, and `dir` is
+		// the only root it could name.
+		if (!match?.[1]) return dir;
+		gitdir = path.resolve(dir, match[1]);
+	} catch {
+		return dir;
+	}
+
+	for (const component of [".git", "worktrees"]) {
+		let cur = gitdir;
+		for (;;) {
+			const parent = path.dirname(cur);
+			if (path.basename(cur) === component) return parent;
+			if (parent === cur) break;
+			cur = parent;
+		}
+	}
+	return gitdir;
+}
+
+/**
+ * The repository root containing `p`, or null when it is in no repository.
+ *
+ * PATH-BASED, never a `git` subprocess, and that is the whole point: registry
+ * rows for DELETED worktrees still take part in the selection below, and every
+ * git command fails on a directory that is not there — so a subprocess
+ * implementation returns "no root" for exactly the entries that decide the
+ * answer. Walking up works on a path that does not exist: the nearest surviving
+ * ancestor still carries the `.git` entry.
+ */
+export function repoRootForPath(
+	p: string,
+	cache?: RepoRootCache,
+): string | null {
+	if (!p) return null;
+	const start = path.resolve(p);
+	const memo = cache?.get(start);
+	if (memo !== undefined) return memo;
+
+	let dir = start;
+	let root: string | null = null;
+	for (;;) {
+		const kind = gitEntryKind(dir);
+		if (kind === "dir") {
+			root = dir;
+			break;
+		}
+		if (kind === "file") {
+			root = mainRootFromGitFile(path.join(dir, ".git"), dir);
+			break;
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+
+	cache?.set(start, root);
+	return root;
+}
+
+/**
+ * `SF` — is this installation relevant to the current project?
+ *
+ * Three ways to be relevant, and the third is the one that surprises people: a
+ * row installed ANYWHERE in the same repository counts, including a worktree
+ * that has since been deleted. Nothing prunes those rows, so they keep voting.
+ *
+ * @param cwdRoot {@link repoRootForPath} of `cwd`, resolved once by the caller
+ *                because it is the same answer for every entry.
+ */
+export function isRelevantInstallation(
+	entry: InstalledPluginEntry,
+	cwd: string,
+	cwdRoot: string | null,
+	cache?: RepoRootCache,
+): boolean {
+	if (isMachineWideScope(entry.scope)) return true;
+	if (!entry.projectPath) return false;
+
+	// The binary compares the two paths as raw strings. They are normalised here
+	// first, which can only turn a spelling difference of the same directory
+	// ("/p/a/" vs "/p/a") into a match — and that same pair already matches on
+	// the repository-root comparison below, which normalises on the way through.
+	if (path.resolve(entry.projectPath) === path.resolve(cwd)) return true;
+
+	// NULL MATCHES NULL, because the original's `repoRoot(entry.projectPath) ===
+	// repoRoot(originalCwd)` does: two directories in no repository at all compare
+	// equal there, so every rootless row competes when Claude Code runs from a
+	// scratch directory, a home directory, or any plain non-git folder.
+	//
+	// This used to `return false` on a null `cwdRoot`, on the reasoning that two
+	// unrelated rootless directories are not the same project. That reasoning is
+	// magus policy, and this module holds none: with it, magus could name a
+	// `loadedVersion` the loader would not pick, and a repair would skip the very
+	// rows the loader treats as relevant — the same class of wrong answer the port
+	// exists to eliminate.
+	//
+	// The policy did not disappear, it moved to where it belongs: `repairStaleLoad`
+	// rewrites a row only when it belongs to THIS repository, which requires either
+	// the exact same directory or a non-null shared root. So a rootless row from an
+	// unrelated directory is reported as relevant (true) and never written (correct).
+	return repoRootForPath(entry.projectPath, cache) === cwdRoot;
+}
+
+/**
+ * `Bls` — the entry the loader will use, or undefined when it loads nothing.
+ *
+ * Faithful to the decompiled original, including the two parts that look like
+ * bugs and are load-bearing:
+ *
+ *  - The single-candidate branch returns WITHOUT checking that `installPath`
+ *    exists. One relevant row means that row loads (or fails to), whatever is
+ *    on disk.
+ *  - `firstValid` is captured BEFORE the existence test, so the fallback is the
+ *    first entry that merely HAS an `installPath` — not the first existing one.
+ *
+ * ARRAY ORDER decides ties, and array order is install order. It is not sorted
+ * by version, by scope, or by recency, so an older install made earlier beats a
+ * newer one made later. That is the madbench 0.3.0 defect in one sentence.
+ */
+export function pickLoadedEntry(
+	entries: readonly InstalledPluginEntry[] | undefined,
+	cwd: string,
+	cache?: RepoRootCache,
+): InstalledPluginEntry | undefined {
+	if (!Array.isArray(entries) || entries.length === 0) return undefined;
+
+	const cwdRoot = repoRootForPath(cwd, cache);
+	const relevant = entries.filter((e) =>
+		isRelevantInstallation(e, cwd, cwdRoot, cache),
+	);
+	if (relevant.length === 0) return undefined;
+	if (relevant.length === 1) return relevant[0];
+
+	let firstValid: InstalledPluginEntry | undefined;
+	for (const entry of relevant) {
+		if (!entry.installPath) continue;
+		if (firstValid === undefined) firstValid = entry;
+		if (fs.existsSync(entry.installPath)) return entry;
+	}
+	return firstValid ?? relevant[0];
+}
+
+/**
+ * pluginId → the version that will actually load in `cwd`.
+ *
+ * Plugins whose winning entry carries no version are absent from the map rather
+ * than present with a placeholder: "no version recorded" is not "loads nothing",
+ * and a caller comparing against it must be able to tell.
+ */
+export function resolveLoadedVersions(
+	registry: InstalledPluginsRegistry,
+	cwd: string,
+): Record<string, string> {
+	// One cache for the whole pass: the same few hundred project paths repeat
+	// across every plugin in the registry.
+	const cache: RepoRootCache = new Map();
+	const out: Record<string, string> = {};
+	for (const [pluginId, entries] of Object.entries(registry.plugins ?? {})) {
+		const pick = pickLoadedEntry(entries, cwd, cache);
+		if (pick?.version) out[pluginId] = pick.version;
+	}
+	return out;
+}

package/src/services/profile-activate.ts

@@ -0,0 +1,147 @@
+/**
+ * Finish a migration: put a profile on disk and make the project run it.
+ *
+ * Adoption used to end at `writeManifest`, which is the whole reason migrating
+ * felt like it did nothing. "Active" is not a field anywhere — it is derived
+ * from whether `.claude/settings.json` is a symlink into `_profiles/<id>/`
+ * (see `activeProfile`). A manifest that nothing links to leaves the project in
+ * exactly the state it was in, so the next command still asks which profile to
+ * use, having just been told.
+ *
+ * The three steps have to happen together and in this order, which is why they
+ * live in one function rather than at each call site:
+ *
+ *   1. materialize — write `_profiles/<id>/`, or activation throws
+ *   2. gitignore   — before the links exist, or a symlink into generated state
+ *                    lands in `git status` (`.claude/` is committed)
+ *   3. activate    — point the four links at the profile
+ *
+ * No network and no installs: `resolveProfile` reads the manifest, and binary
+ * resolution is skipped outright because nothing here materializes bins. That
+ * matters — this runs inside a prompt the user answered, not inside `install`.
+ */
+
+import path from "node:path";
+import type { ProfileManifest } from "../types/index.js";
+import { ensureGitignoreEntries } from "./conventions-manager.js";
+import { writeManifest } from "./manifest.js";
+import { adoptCurrentProject } from "./profile-adopt.js";
+import { materializeProfile } from "./profile-materializer.js";
+import { resolveAllProfiles, resolveProfile } from "./resolver.js";
+import {
+	type DisplacedArtifact,
+	PROFILE_GITIGNORE_ENTRIES,
+	activateProfile,
+} from "./symlink-manager.js";
+
+/**
+ * Bins are declared by plugins and read from the marketplace cache, one
+ * `plugin.json` per plugin. Materialization writes settings, mcp, models and
+ * skills — never bins — so resolving them here would be pure latency, and on a
+ * machine with a cold cache it is latency inside a prompt.
+ */
+const noBins = async () => [];
+
+export interface ActivationResult {
+	/** The profile now live. */
+	profileId: string;
+	/** Hand-written artifacts moved aside to make room for the symlinks. */
+	displaced: DisplacedArtifact[];
+}
+
+/**
+ * Announce one displaced artifact, in project-relative terms.
+ *
+ * Shared by every command that activates, because a hand-written file moving is
+ * the same event whichever command caused it, and the one that is easiest to
+ * leave out: `activateProfile` returns the list, and a caller that discards the
+ * return value still compiles. `magus install` and `magus profile switch` both
+ * did exactly that.
+ *
+ * Paths are relative because absolute ones wrap over two terminal lines each,
+ * and this is the notice a user must not skim.
+ */
+export function reportDisplaced(
+	projectPath: string,
+): (artifact: DisplacedArtifact) => void {
+	const rel = (p: string) => path.relative(projectPath, p);
+	return ({ link, savedTo }) =>
+		console.log(`  ${rel(link)} → kept at ${rel(savedTo)}`);
+}
+
+/**
+ * Materialize `profileId` and make it the active profile.
+ *
+ * The union of plugin ids across EVERY profile is passed to materialization, so
+ * the profile writes an explicit `false` for plugins other profiles own. Without
+ * it an omitted id falls through to user scope and stays enabled, which would
+ * make the freshly adopted profile additive rather than a description of this
+ * project — the exact drift adoption was run to end.
+ */
+export async function materializeAndActivate(
+	manifest: ProfileManifest,
+	profileId: string,
+	projectPath: string,
+	/** Called as each artifact moves; defaults to printing it. */
+	onDisplace: (artifact: DisplacedArtifact) => void = reportDisplaced(
+		projectPath,
+	),
+): Promise<ActivationResult> {
+	const closure = await resolveProfile(manifest, profileId, {
+		binResolver: noBins,
+	});
+	const union = await resolveAllProfiles(manifest, { binResolver: noBins });
+
+	await materializeProfile(
+		profileId,
+		closure,
+		projectPath,
+		Object.keys(union.plugins),
+	);
+
+	await ensureGitignoreEntries(
+		path.join(projectPath, ".gitignore"),
+		PROFILE_GITIGNORE_ENTRIES,
+		"# magus: generated profile build output + active-profile symlinks",
+	);
+
+	const displaced = await activateProfile(profileId, projectPath, onDisplace);
+	return { profileId, displaced };
+}
+
+/** The two ways a project can be put onto a profile. */
+export type ProfileChoice =
+	| { kind: "adopt"; id: string }
+	| { kind: "activate"; id: string };
+
+/**
+ * Carry out the user's choice, whichever surface asked.
+ *
+ * One implementation because "migrate" is two writes that must not come apart —
+ * write the manifest, then link the project to it — and a second copy of that
+ * pairing in the other surface is how one of them ends up writing the manifest
+ * and stopping, which is the defect this whole area was fixed for.
+ */
+export async function applyProfileChoice(
+	choice: ProfileChoice,
+	manifest: ProfileManifest,
+	projectPath: string,
+	onDisplace?: (artifact: DisplacedArtifact) => void,
+): Promise<ActivationResult> {
+	if (choice.kind === "activate") {
+		return materializeAndActivate(manifest, choice.id, projectPath, onDisplace);
+	}
+	const result = await adoptCurrentProject(
+		projectPath,
+		undefined,
+		manifest,
+		choice.id,
+	);
+	await writeManifest(result.manifest, projectPath);
+	return materializeAndActivate(
+		result.manifest,
+		choice.id,
+		projectPath,
+		onDisplace,
+	);
+}

package/src/services/profile-adopt.ts

@@ -30,6 +30,21 @@ import { withDerivedMarketplaces } from "./resolver.js";
 /** The profile id used when adopting a project that has no manifest. */
 export const ADOPTED_PROFILE_ID = "default";
 
+/**
+ * First free profile id, so adopting never overwrites an existing profile.
+ *
+ * Lives here rather than at a call site because both surfaces adopt now — the
+ * CLI prompt and the TUI's startup offer — and two copies of "which id is
+ * free?" is two chances to overwrite somebody's profile.
+ */
+export function freeProfileId(manifest: ProfileManifest): string {
+	if (!manifest.profiles[ADOPTED_PROFILE_ID]) return ADOPTED_PROFILE_ID;
+	for (let n = 2; ; n++) {
+		const id = `${ADOPTED_PROFILE_ID}-${n}`;
+		if (!manifest.profiles[id]) return id;
+	}
+}
+
 export interface AdoptInput {
 	/** Union of enabled plugins across every scope: id -> enabled. */
 	enabledPlugins: Record<string, boolean>;
@@ -147,7 +162,7 @@ export type AdoptSource = "project" | "user";
  * everything globally would otherwise have nothing to adopt. The caller is told
  * which source was used and says so, so the choice is never invisible.
  */
-async function collectEnabledPlugins(
+export async function collectEnabledPlugins(
 	projectPath: string,
 ): Promise<{ plugins: Record<string, boolean>; source: AdoptSource }> {
 	const project = await getEnabledPlugins(projectPath).catch(() => ({}));
@@ -165,6 +180,19 @@ async function collectEnabledPlugins(
 export async function adoptCurrentProject(
 	projectPath: string,
 	name?: string,
+	/**
+	 * Manifest to add the adopted profile to. Omitted, adoption starts from an
+	 * empty manifest — correct for a repo that has none.
+	 *
+	 * This parameter is what makes adoption reachable twice. Without it the
+	 * function always returned `emptyManifest()` plus one profile, so calling
+	 * it on a repo that HAD profiles would have deleted them, and the zero-
+	 * profile gate in `ensureManifest` was the only thing preventing that.
+	 * Existing profiles are preserved untouched; only `id` is written.
+	 */
+	into?: ProfileManifest,
+	/** Profile id to write. Defaults to the adopted-profile id. */
+	id: string = ADOPTED_PROFILE_ID,
 ): Promise<AdoptResult> {
 	const { plugins: enabledPlugins, source } =
 		await collectEnabledPlugins(projectPath);
@@ -181,8 +209,26 @@ export async function adoptCurrentProject(
 		name,
 	});
 
-	const manifest = emptyManifest();
-	manifest.profiles[ADOPTED_PROFILE_ID] = entry;
+	// Copy rather than mutate the caller's manifest: this function does not
+	// write, and a caller that declines the plan must be left with the file it
+	// had, not a version already carrying the profile it refused.
+	const manifest: ProfileManifest = into
+		? { ...into, profiles: { ...into.profiles } }
+		: emptyManifest();
+	manifest.profiles[id] = entry;
+
+	// Record which profile the project wants, but ONLY when nothing has said yet.
+	//
+	// Writing it on a first adoption is the point: the manifest is committed, and
+	// a teammate who clones it should get this profile without being asked. It is
+	// the answer the repo now has.
+	//
+	// Overwriting an existing `default` would be different — one developer saving
+	// their local state would republish the team's committed choice as whatever
+	// they happened to have on. The new profile still becomes active for them,
+	// because activation is per-developer; the declared intent is not theirs to
+	// change by accident.
+	if (manifest.default === undefined) manifest.default = id;
 
 	const skipped = Object.entries(enabledPlugins)
 		.filter(([id, on]) => on && !id.includes("@"))
@@ -190,7 +236,7 @@ export async function adoptCurrentProject(
 
 	return {
 		manifest,
-		profileId: ADOPTED_PROFILE_ID,
+		profileId: id,
 		entry,
 		source,
 		counts: {