magus-cli 7.5.3 → 7.6.0

package/src/cli/install.ts

@@ -48,9 +48,20 @@ import { bringLoadForward } from "../services/update-engine.js";
 import type { ResolvedBin, ResolvedClosure } from "../types/index.js";
 import { formatCommand, resolveExecutable } from "../utils/command-utils.js";
 import { runCommand, runShellScript } from "../utils/run.js";
+import { bold } from "./ansi.js";
 import { ensureManifest, printActivationNotes } from "./bootstrap.js";
-import { confirm, promptValue } from "./prompt.js";
-import { note as noteLine } from "./update-view.js";
+import { askYesNo, promptValue } from "./prompt.js";
+import { selectOption } from "./select.js";
+import {
+	commandHeader,
+	fail as failLine,
+	field,
+	info as infoLine,
+	note as noteLine,
+	ok as okLine,
+	question,
+	warn as warnLine,
+} from "./update-view.js";
 
 interface InstallFlags {
 	check: boolean;
@@ -119,8 +130,10 @@ async function ensureToolchains(
 		}
 		const ok =
 			yes ||
-			(await confirm(
-				`${tc.name} is missing (needed by ${tc.requiredBy.join(", ")}). Install it?`,
+			(await askYesNo(
+				question(
+					`${tc.name} is missing — ${tc.requiredBy.join(", ")} need${tc.requiredBy.length === 1 ? "s" : ""} it. Install it?`,
+				),
 			));
 		if (ok) {
 			console.log(`Installing ${tc.name}…`);
@@ -149,15 +162,18 @@ async function ensureToolchains(
  * EVERY profile's plugins — so the caller runs this inside
  * `withCliBookkeeping`, which renders the live files over it afterwards.
  */
-async function installPlugins(closure: ResolvedClosure): Promise<void> {
+async function installPlugins(closure: ResolvedClosure): Promise<string[]> {
+	const installed: string[] = [];
 	for (const pluginId of Object.keys(closure.plugins)) {
 		try {
 			console.log(`+ plugin ${pluginId}`);
 			await installPlugin(pluginId, "project");
+			installed.push(pluginId);
 		} catch (e) {
 			console.warn(`⚠ plugin ${pluginId}: ${(e as Error).message}`);
 		}
 	}
+	return installed;
 }
 
 /**
@@ -176,7 +192,15 @@ async function bringLoadsForward(
 			"project",
 			projectPath,
 		);
-		if (!here) continue;
+		if (!here) {
+			// Skipped rather than checked against another scope's record: that
+			// would repair toward a version this project does not have. Said, so a
+			// plugin that installed but left nothing to check is not silent.
+			console.warn(
+				`⚠ ${pluginId}: installed, but Claude Code recorded no version for this project, so magus cannot check which version loads here`,
+			);
+			continue;
+		}
 		const forward = await bringLoadForward(pluginId, here, projectPath);
 		if (!forward) continue;
 		if (forward.ok) {
@@ -314,18 +338,32 @@ export async function runInstallCommand(
 	}
 
 	// Plan
-	console.log(`\nPlan for ${flags.profile ?? "all profiles"}:`);
-	for (const line of summarizeClosure(closure)) console.log(`  ${line}`);
+	// In the report style `update` uses: a header, then the plan as aligned
+	// rows. `summarizeClosure` pads each line as "label  values"; split at the
+	// padding so the label takes the dim label column.
+	for (const line of commandHeader(
+		"install",
+		flags.profile
+			? { label: "profile", value: flags.profile }
+			: { label: "profiles", value: "all" },
+	)) {
+		console.log(line);
+	}
+	for (const line of summarizeClosure(closure)) {
+		const [label, ...rest] = line.split(/ {2,}/);
+		console.log(field(label ?? "", rest.join("  ")));
+	}
+	console.log("");
 	if (closure.conflicts?.length) {
 		console.log(
-			"\n⚠ Version conflicts across profiles (resolved to the higher pin):",
+			warnLine("Profiles pin different versions — the higher pin wins"),
 		);
-		for (const c of closure.conflicts) console.log(`  ${c}`);
+		for (const c of closure.conflicts) console.log(noteLine(c));
+		console.log("");
 	}
-	console.log();
 
-	if (!flags.yes && !(await confirm("Apply?"))) {
-		console.log("Aborted.");
+	if (!flags.yes && !(await askYesNo(question("Install this plan?")))) {
+		console.log(infoLine("Nothing installed."));
 		return 0;
 	}
 
@@ -363,6 +401,10 @@ export async function runInstallCommand(
 		flags.profile ??
 		current ??
 		(await pickActiveProfile(profileIds, flags.yes));
+	if (activeId === null) {
+		console.error(failLine("No profile chosen — stopping."));
+		return 1;
+	}
 	if (activeId) {
 		// The one switch path: what Claude Code wrote into the live config — or
 		// through an older layout's links — goes into the profile it was written
@@ -375,10 +417,10 @@ export async function runInstallCommand(
 		});
 		for (const line of switched.lines) console.log(noteLine(line));
 		if (!switched.activation) {
-			for (const problem of switched.problems) console.error(problem);
+			for (const problem of switched.problems) console.error(failLine(problem));
 			return 1;
 		}
-		console.log(`\n✓ Active profile: ${activeId}`);
+		console.log(okLine(`Active profile ${bold(activeId)}`));
 		printActivationNotes(switched.activation);
 	}
 
@@ -387,11 +429,16 @@ export async function runInstallCommand(
 	// while they run and reconciles in `finally`: what the user changed in the
 	// meantime is kept, only the install's own records are discarded, and a
 	// Ctrl-C leaves the flag for the next command to do the same.
-	await withCliBookkeeping(projectPath, () => installPlugins(closure), {
-		installable: Object.keys(closure.plugins),
-		report: (line) => console.log(noteLine(line)),
-	});
-	await bringLoadsForward(Object.keys(closure.plugins), projectPath);
+	const installed = await withCliBookkeeping(
+		projectPath,
+		() => installPlugins(closure),
+		{
+			installable: Object.keys(closure.plugins),
+			report: (line) => console.log(noteLine(line)),
+		},
+	);
+	// Only what installed: a failed install already printed its own warning.
+	await bringLoadsForward(installed, projectPath);
 	await installBins(closure.bins);
 
 	if (activeId) {
@@ -406,16 +453,25 @@ export async function runInstallCommand(
 	return 0;
 }
 
+/**
+ * Which profile to make active when none is: the only one, the first under
+ * `--yes` or with nobody at the terminal, else the user's pick from an
+ * arrow-key list. Null when the user cancels the list — the install stops then,
+ * since magus does not run a project without a profile.
+ */
 async function pickActiveProfile(
 	profileIds: string[],
 	yes: boolean,
-): Promise<string | undefined> {
+): Promise<string | undefined | null> {
 	if (profileIds.length === 0) return undefined;
 	if (profileIds.length === 1) return profileIds[0];
-	if (yes) return profileIds[0];
-	console.log("\nWhich profile should be active?");
-	profileIds.forEach((id, i) => console.log(`  ${i + 1}) ${id}`));
-	const answer = await promptValue("Choose [1]: ");
-	const idx = answer ? Number.parseInt(answer, 10) - 1 : 0;
-	return profileIds[idx] ?? profileIds[0];
+	if (yes || !process.stdin.isTTY || !process.stdout.isTTY) {
+		return profileIds[0];
+	}
+	console.log("");
+	const picked = await selectOption(
+		"Which profile should be active?",
+		profileIds.map((id) => ({ label: id })),
+	);
+	return picked === null ? null : profileIds[picked];
 }

package/src/cli/prompt.ts

@@ -39,22 +39,36 @@ export function isPromptAborted(error: unknown): boolean {
 	);
 }
 
-/** One readline question, with Ctrl+C normalised. */
+/** One readline question, with Ctrl+C and end of input normalised. */
 async function ask(question: string): Promise<string> {
 	const rl = createInterface({ input: process.stdin, output: process.stdout });
+	// End of input (Ctrl+D, or a pipe that ran dry) closes the interface and
+	// never settles `question()` — MEASURED under Bun, it waits forever. Input
+	// that ends before an answer is a cancellation, the same as Ctrl+C.
+	let settled = false;
+	const closed = new Promise<never>((_, reject) => {
+		rl.once("close", () => {
+			if (!settled) reject(new PromptAborted());
+		});
+	});
 	try {
-		return (await rl.question(question)).trim();
+		return (await Promise.race([rl.question(question), closed])).trim();
 	} catch (error) {
 		if (isPromptAborted(error)) throw new PromptAborted();
 		throw error;
 	} finally {
+		settled = true;
 		rl.close();
 	}
 }
 
-/** Y/n prompt. Empty input means yes. */
-export async function confirm(question: string): Promise<boolean> {
-	const answer = (await ask(`${question} [Y/n] `)).toLowerCase();
+/**
+ * A yes/no answer to `prompt`, printed as given — the caller styles it (see
+ * `question` in update-view.ts). Empty input means yes. Line-based, so a piped
+ * stdin (`yes | magus install`) answers it like a person does.
+ */
+export async function askYesNo(prompt: string): Promise<boolean> {
+	const answer = (await ask(prompt)).toLowerCase();
 	return answer === "" || answer === "y" || answer === "yes";
 }
 

package/src/cli/router.ts

@@ -192,6 +192,7 @@ export async function route(
 			// Both of these fix a marker naming a missing profile by activating
 			// one that exists.
 			allowUnknown: command === "install" || command === "profile",
+			yes: rest.includes("--yes") || rest.includes("-y"),
 		});
 		if (!ok) return HANDLED(1);
 	}

package/src/cli/select.ts

@@ -0,0 +1,168 @@
+/**
+ * An arrow-key choice in the terminal — interactive, but not a TUI.
+ *
+ * No renderer and no alternate screen: the rows of `selectFrame` are written
+ * under the report, redrawn in place on each keypress, and collapse to one
+ * `selectDone` line once answered. The owner asked for this in place of typing
+ * a number ("not this ugly thing … not tui, interactive cli").
+ *
+ * The key handling is `selectKey`, pure, so it is testable without a terminal;
+ * `selectOption` is only the terminal around it.
+ */
+
+import { emitKeypressEvents } from "node:readline";
+import { selectDone, selectFrame } from "./update-view.js";
+
+export interface SelectItem {
+	label: string;
+	meta?: string;
+}
+
+/** The fields of a readline keypress that the choice reads. */
+export interface SelectKeypress {
+	name?: string;
+	ctrl?: boolean;
+	sequence?: string;
+}
+
+export type SelectStep =
+	| { index: number }
+	| { chosen: number }
+	| { cancelled: true };
+
+/**
+ * What one keypress does: ↑/↓ (and k/j) move with wrap-around, Enter picks the
+ * current row, a digit picks that row at once, Esc and Ctrl+C cancel. Any other
+ * key leaves the cursor where it is.
+ */
+export function selectKey(
+	index: number,
+	key: SelectKeypress,
+	count: number,
+): SelectStep {
+	if ((key.ctrl && key.name === "c") || key.name === "escape") {
+		return { cancelled: true };
+	}
+	if (key.name === "return" || key.name === "enter") return { chosen: index };
+	if (key.name === "up" || key.name === "k") {
+		return { index: (index - 1 + count) % count };
+	}
+	if (key.name === "down" || key.name === "j") {
+		return { index: (index + 1) % count };
+	}
+	const digit = Number(key.sequence);
+	if (Number.isInteger(digit) && digit >= 1 && digit <= count) {
+		return { chosen: digit - 1 };
+	}
+	return { index };
+}
+
+/** 128 + signum, the shell convention `cli/live.ts` exits with too. */
+const SIGNAL_EXIT = { SIGINT: 130, SIGTERM: 143, SIGHUP: 129 } as const;
+
+/**
+ * Ask. Resolves to the chosen index, or null when the user cancels — and at
+ * once when there is no terminal on either end, since nobody can answer and a
+ * redraw would write cursor codes into a pipe. Callers decide what null means.
+ *
+ * Whatever ends it — an answer, a throw, a signal, or the process exiting —
+ * puts the terminal back: raw mode off, the keypress listener gone, the cursor
+ * shown. Only Enter, Esc and Ctrl+C used to, so anything else left the shell
+ * typing blind until `reset`. Ctrl+C typed at the list arrives as a keypress
+ * in raw mode; the SIGINT handler is for one sent from outside (`kill -INT`).
+ */
+export async function selectOption(
+	title: string,
+	items: SelectItem[],
+	defaultIndex = 0,
+): Promise<number | null> {
+	const { stdin, stdout } = process;
+	if (!stdin.isTTY || !stdout.isTTY || items.length === 0) return null;
+
+	let index = Math.min(Math.max(0, defaultIndex), items.length - 1);
+	let height = 0;
+	const draw = (): void => {
+		const lines = selectFrame(title, items, index);
+		// Back to the block's first row, then rewrite every row in full.
+		if (height > 0) stdout.write(`\x1b[${height}F`);
+		stdout.write(`${lines.map((l) => `\x1b[2K${l}`).join("\n")}\n`);
+		height = lines.length;
+	};
+
+	emitKeypressEvents(stdin);
+	const wasRaw = stdin.isRaw;
+	let onKey: ((_: string, key: SelectKeypress | undefined) => void) | null =
+		null;
+
+	// Once only: `finish`, a throw's `finally` and a signal can all reach it.
+	let released = false;
+	const release = (): void => {
+		if (released) return;
+		released = true;
+		process.off("exit", release);
+		process.off("SIGINT", onSigint);
+		process.off("SIGTERM", onSigterm);
+		process.off("SIGHUP", onSighup);
+		if (onKey) stdin.off("keypress", onKey);
+		stdin.setRawMode(wasRaw);
+		stdin.pause();
+		stdout.write("\x1b[?25h");
+	};
+	// A listener for a signal replaces its default action, so each one exits
+	// itself once the terminal is back.
+	const onSigint = (): void => {
+		release();
+		process.exit(SIGNAL_EXIT.SIGINT);
+	};
+	const onSigterm = (): void => {
+		release();
+		process.exit(SIGNAL_EXIT.SIGTERM);
+	};
+	const onSighup = (): void => {
+		release();
+		process.exit(SIGNAL_EXIT.SIGHUP);
+	};
+	process.once("exit", release);
+	process.once("SIGINT", onSigint);
+	process.once("SIGTERM", onSigterm);
+	process.once("SIGHUP", onSighup);
+
+	try {
+		stdin.setRawMode(true);
+		stdin.resume();
+		stdout.write("\x1b[?25l"); // hide the cursor while the list is open
+
+		return await new Promise<number | null>((resolve, reject) => {
+			const finish = (chosen: number | null): void => {
+				// Clear the open block; an answer leaves one line behind it.
+				stdout.write(`\x1b[${height}F\x1b[0J`);
+				if (chosen !== null) {
+					stdout.write(`${selectDone(title, items[chosen]?.label ?? "")}\n`);
+				}
+				// Before resolving, not in `finally`: one read can carry several
+				// keys, and the listener must be gone before the next is emitted.
+				release();
+				resolve(chosen);
+			};
+			onKey = (_, key) => {
+				try {
+					const step = selectKey(index, key ?? {}, items.length);
+					if ("cancelled" in step) finish(null);
+					else if ("chosen" in step) finish(step.chosen);
+					else {
+						index = step.index;
+						draw();
+					}
+				} catch (error) {
+					// Thrown inside an event listener it would reach no caller.
+					release();
+					reject(error);
+				}
+			};
+			stdin.on("keypress", onKey);
+			draw();
+		});
+	} finally {
+		release();
+	}
+}

package/src/cli/update-view.ts

@@ -1,5 +1,7 @@
 /**
- * update-view.ts — every string `magus update` prints, and nothing else.
+ * update-view.ts — every string `magus update` prints, plus the pieces the
+ * other CLI commands reuse so they look the same (`commandHeader`, `field`,
+ * the `ok`/`warn`/`fail`/`info`/`note` rows, and `question`).
  *
  * Pure functions: plan in, lines out. No IO, no timers, no terminal. That is
  * what makes the look testable — the old report was `console.log` calls braided
@@ -128,16 +130,128 @@ function rowText(key: ActionKey, text: string): string {
 
 // -- header ------------------------------------------------------------------
 
-export function header(profileId: string): string[] {
+/**
+ * `◆ magus <command>   <label> <value>` — the line a CLI report opens with.
+ *
+ * Shared so `install` and the adoption question open the way `update` does,
+ * rather than each command printing its own plain "Plan for …:" heading.
+ */
+export function commandHeader(
+	command: string,
+	context?: { label: string; value: string },
+): string[] {
+	const tail = context
+		? `   ${dim(context.label)} ${fg(brand.accent, context.value)}`
+		: "";
 	return [
 		"",
-		`${PAD}${fg(brand.accent, "◆")} ${bold("magus update")}   ${dim(
-			"profile",
-		)} ${fg(brand.accent, profileId)}`,
+		`${PAD}${fg(brand.accent, "◆")} ${bold(`magus ${command}`)}${tail}`,
 		"",
 	];
 }
 
+export function header(profileId: string): string[] {
+	return commandHeader("update", { label: "profile", value: profileId });
+}
+
+/** Width of the label column in `field` rows. */
+const FIELD_WIDTH = 14;
+
+/**
+ * `label   value`, indented to the text column of the glyph rows (`ok`, `warn`,
+ * …) so a block of facts lines up under the notice it belongs to.
+ */
+export function field(label: string, value: string): string {
+	return `${PAD}   ${dim(padEnd(label, FIELD_WIDTH))}${value}`;
+}
+
+/**
+ * A multi-paragraph note, word-wrapped to the terminal in the `note` column.
+ * Paragraphs are separated by "\n"; an empty paragraph stays an empty line. A
+ * note printed as one line per paragraph wrapped mid-word at the terminal edge.
+ */
+export function noteBlock(text: string, columns = 80): string[] {
+	const room = Math.max(20, Math.min(columns, 100) - PAD.length - 4);
+	const out: string[] = [];
+	for (const paragraph of text.split("\n")) {
+		if (paragraph === "") {
+			out.push("");
+			continue;
+		}
+		const indent = /^ */.exec(paragraph)?.[0] ?? "";
+		let line = indent;
+		for (const word of paragraph.trimStart().split(" ")) {
+			if (line.trim() !== "" && width(line) + 1 + width(word) > room) {
+				out.push(note(line));
+				line = word;
+			} else {
+				line = line.trim() === "" ? `${line}${word}` : `${line} ${word}`;
+			}
+		}
+		if (line.trim() !== "") out.push(note(line));
+	}
+	return out;
+}
+
+/** One entry of a list under a `field`, indented to the field's value column. */
+export function listItem(text: string): string {
+	return `${PAD}   ${" ".repeat(FIELD_WIDTH)}${text}`;
+}
+
+/** The scopes a user deals in. Where each is stored is magus's business. */
+export type ScopeName = "user" | "project" | "local";
+
+const SCOPE_BADGE: Record<ScopeName, [string, string]> = {
+	user: ["USER", brand.accent],
+	project: ["PROJECT", brand.info],
+	local: ["LOCAL", brand.warning],
+};
+
+/** A scope as a badge — the word a user knows it by, never a file name. */
+export function scopeBadge(scope: ScopeName): string {
+	const [label, color] = SCOPE_BADGE[scope];
+	return badge(label, color);
+}
+
+/**
+ * The prompt for a question, in the glyph column: `?  <question>  [Y/n] `.
+ * Printed by readline, so the answer is typed on the same line. `hint` is what
+ * an empty answer means — yes by default, or the suggested value for a
+ * free-text question.
+ */
+export function question(text: string, hint = "[Y/n]"): string {
+	return `${PAD}${fg(brand.accent, "?")}  ${bold(text)}  ${dim(hint)} `;
+}
+
+/**
+ * An arrow-key choice while it is open: the question, one row per option with
+ * `❯` on the current one, then the keys. `select.ts` redraws the whole block in
+ * place on every keypress, so its height never changes while it is open.
+ */
+export function selectFrame(
+	title: string,
+	options: { label: string; meta?: string }[],
+	index: number,
+): string[] {
+	const labelWidth = Math.max(0, ...options.map((o) => width(o.label)));
+	return [
+		`${PAD}${fg(brand.accent, "?")}  ${bold(title)}`,
+		...options.map((o, i) => {
+			const label = padEnd(o.label, labelWidth);
+			const meta = o.meta ? `  ${dim(o.meta)}` : "";
+			return i === index
+				? `${PAD}   ${fg(brand.accent, "❯")} ${bold(fg(brand.accent, label))}${meta}`
+				: `${PAD}     ${label}${meta}`;
+		}),
+		`${PAD}   ${dim("↑↓ move · enter select · esc cancel")}`,
+	];
+}
+
+/** The one line an answered choice collapses to: `✓  <title>  <answer>`. */
+export function selectDone(title: string, answer: string): string {
+	return `${PAD}${fg(brand.success, "✓")}  ${title}  ${fg(brand.accent, answer)}`;
+}
+
 // -- phase checklist ---------------------------------------------------------
 
 export type StepState = "pending" | "running" | "done" | "warn" | "fail";
@@ -346,7 +460,7 @@ function binDetail(item: BinUpdateItem, plan: UpdatePlan): string {
  *
  *   Update        something an apply would move forward
  *   Deprecated    no configured marketplace offers it
- *   Fix required  declared or enabled, with nothing on disk
+ *   Fix required  declared or installed, with its files missing
  *   Unverified    the check itself did not complete
  *   Current       settled — the version was compared, or there was none to compare
  *

package/src/cli/update.ts

@@ -51,7 +51,7 @@ import {
 import {
 	recordRefetchedSkills,
 	trackFetchedSkills,
-	trackedGeneratedWarnings,
+	trackedGeneratedNotices,
 	updatableSkills,
 } from "../services/profile-activate.js";
 import { activeProfile } from "../services/profile-live.js";
@@ -84,7 +84,6 @@ import { brand } from "../ui/theme.js";
 import { bold, dim, fg, width } from "./ansi.js";
 import { ensureManifest, requireActiveProfile } from "./bootstrap.js";
 import { LiveRegion, withPaused } from "./live.js";
-import { selectDialog } from "./tui-prompt.js";
 import {
 	type ApplyState,
 	type Step,
@@ -205,8 +204,9 @@ export async function runUpdateCommand(
 
 	// A generated file git tracks is written like any other; say so once, with
 	// the fix. magus never runs git itself.
-	for (const line of await trackedGeneratedWarnings(projectPath)) {
-		console.log(warnLine(line));
+	for (const n of await trackedGeneratedNotices(projectPath)) {
+		console.log(warnLine(n.problem));
+		for (const line of n.fix) console.log(noteLine(line));
 	}
 
 	// No active profile, no update: that is where plugin state is read from and
@@ -238,6 +238,8 @@ export async function runUpdateCommand(
 			? manifest
 			: await requireActiveProfile(projectPath, manifest, {
 					check: flags.check || flags.dryRun,
+					// Said once already, by the check above.
+					reportTracked: false,
 				});
 	// A refused dry run exits 0: it wrote nothing and previewed nothing, which is
 	// what it promised. A refused `--check` exits 1, because that is a gate.

package/src/services/claude-settings.ts

@@ -406,6 +406,34 @@ export function pickRegistryEntry(
 	return entries.find((e) => e.scope === "user");
 }
 
+/**
+ * The row a `claude plugin … --scope <scope>` run from `projectPath` owns: the
+ * user row for user scope; for project or local scope, the row of exactly that
+ * scope pinned to exactly this path.
+ *
+ * NOT {@link pickRegistryEntry}, which answers "what version applies here" and
+ * so falls back to inherited rows and then to the user row. That fallback asked
+ * the apply engine's "does this project hold a row?" guard made a plugin
+ * installed only at user scope, and turned on in project settings, look like it
+ * held a project row — so `claude plugin update --scope project` ran from a
+ * folder with none, and Claude Code updated some other project's row instead.
+ */
+export function ownRegistryEntry(
+	entries: InstalledPluginEntry[] | undefined,
+	scope: "user" | "project" | "local",
+	projectPath: string,
+): InstalledPluginEntry | undefined {
+	if (!Array.isArray(entries)) return undefined;
+	if (scope === "user") return entries.find((e) => e.scope === "user");
+	const target = path.resolve(projectPath);
+	return entries.find(
+		(e) =>
+			e.scope === scope &&
+			e.projectPath !== undefined &&
+			path.resolve(e.projectPath) === target,
+	);
+}
+
 async function overlayRegistryVersions(
 	base: Record<string, string>,
 	scope: "user" | "project" | "local",

package/src/services/manifest.ts

@@ -7,6 +7,7 @@
  * structural subset of a v2 manifest entry, so migration is a version bump.
  */
 
+import os from "node:os";
 import path from "node:path";
 import fs from "fs-extra";
 import {
@@ -41,6 +42,36 @@ export function getManifestPath(projectPath?: string): string {
 	return path.join(base, MANIFEST_FILE);
 }
 
+/**
+ * The nearest ANCESTOR directory holding a `.claude/profiles.json`, searched no
+ * higher than the repository root — so magus can say so when it runs in a
+ * subdirectory.
+ *
+ * magus manages the directory it runs in because that is the project Claude Code
+ * reads: launched in `tools/magus`, it watches `tools/magus/.claude/settings.json`
+ * and never the root's (MEASURED with `--debug-file`, Claude Code 2.1.281). A
+ * root profiles.json is therefore not this directory's — but someone who meant
+ * the root has to hear that it exists before creating a second one here.
+ *
+ * A directory holding `.git` (file or folder) is a repository root, a worktree's
+ * included: nothing above it is searched, or a worktree under
+ * `<repo>/.claude/worktrees/` would find the main checkout's file. The home
+ * directory is never checked — its `.claude/` is Claude Code's user config.
+ */
+export async function findEnclosingManifest(
+	projectPath: string,
+): Promise<string | null> {
+	const home = os.homedir();
+	let dir = path.resolve(projectPath);
+	for (;;) {
+		if (await fs.pathExists(path.join(dir, ".git"))) return null;
+		const parent = path.dirname(dir);
+		if (parent === dir || parent === home) return null;
+		dir = parent;
+		if (await fs.pathExists(path.join(dir, MANIFEST_FILE))) return dir;
+	}
+}
+
 /** An empty, valid v2 manifest. */
 export function emptyManifest(): ProfileManifest {
 	return { version: 2, profiles: {} };