pi-profile-switch 0.3.1 → 0.4.2

package/src/extension-discovery.ts

@@ -0,0 +1,347 @@
+/**
+ * ExtensionDiscovery: implicit, read-only discovery of selectable extensions
+ * (ADR-0006), so profiles can reference extensions without registering them
+ * in resources.json first.
+ *
+ * Two implicit sources, both Pi-native and side-effect free:
+ * - Configured user packages: each package's `package.json#pi.extensions`
+ *   declares its extension entry files; the package name (or an alias like
+ *   the `npm:` source string) is the profile-facing reference.
+ * - Loose extension files: `<agentDir>/extensions/*.{ts,js}` and, for
+ *   trusted projects, `<projectDir>/.pi/extensions/*.{ts,js}`, referenced by
+ *   filename stem.
+ *
+ * Discovery never executes extension code and never installs anything: a
+ * package contributes entries only for declared files that exist on disk.
+ * Explicit resources.json entries merge over this discovery result in
+ * ResourceRegistry.load (registration remains the override, never the
+ * prerequisite).
+ */
+
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+
+import { minimatch } from "minimatch";
+
+import { isRecord } from "./json-file.ts";
+import type { ConfiguredPackageRoot } from "./settings-generator.ts";
+
+export interface DiscoveredPackage {
+	/** Selectable package name: package.json "name", or the source minus its
+	 *  npm:/git:/github: prefix (and any version spec) when unreadable. */
+	name: string;
+	/** The source string exactly as configured in the user's settings
+	 *  (e.g. "npm:pi-mcp-adapter"); accepted as a reference alias. */
+	source: string;
+	/** Absolute install/local root of the package. */
+	root: string;
+	/** Absolute paths of declared `pi.extensions` entries that exist on disk. */
+	entries: string[];
+}
+
+export interface DiscoveredLocalExtension {
+	/** Selectable ID: the filename stem ("conventions" for conventions.ts). */
+	id: string;
+	entry: string;
+}
+
+export interface ImplicitExtensionDiscovery {
+	packages: DiscoveredPackage[];
+	/** Loose files, project entries already merged over same-ID global ones. */
+	local: DiscoveredLocalExtension[];
+	/** Non-fatal notices (skipped packages, shadowed duplicates). */
+	warnings: string[];
+}
+
+export class ExtensionError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ExtensionError";
+	}
+}
+
+export interface SelectedExtension {
+	id: string;
+	entry: string;
+	origin?: "package" | "local" | "path";
+}
+
+export interface SelectExtensionsResult {
+	entries: SelectedExtension[];
+	unmatched: string[];
+}
+
+function toPosix(filePath: string): string {
+	return filePath.split(path.sep).join("/");
+}
+
+async function exists(filePath: string): Promise<boolean> {
+	try {
+		return (await stat(filePath)).isFile();
+	} catch {
+		return false;
+	}
+}
+
+function looksLikePath(reference: string): boolean {
+	return (
+		reference.startsWith("/") ||
+		reference.startsWith("~/") ||
+		reference.startsWith("./") ||
+		reference.startsWith("../") ||
+		/\.(ts|js)$/.test(reference)
+	);
+}
+
+export class DiscoveredExtensions {
+	readonly #packages: readonly DiscoveredPackage[];
+	readonly #local: readonly DiscoveredLocalExtension[];
+	readonly #warnings: string[];
+	readonly #entries: ReadonlyMap<string, { id: string; entry: string; packageName?: string; origin: "package" | "local" }>;
+
+	constructor(packages: readonly DiscoveredPackage[], local: readonly DiscoveredLocalExtension[], warnings: string[]) {
+		this.#packages = packages;
+		this.#local = local;
+		this.#warnings = [...warnings];
+
+		const entries = new Map<string, { id: string; entry: string; packageName?: string; origin: "package" | "local" }>();
+		for (const loc of local) {
+			entries.set(loc.id, { id: loc.id, entry: loc.entry, origin: "local" });
+		}
+		for (const pkg of packages) {
+			for (const entryPath of pkg.entries) {
+				const id = pkg.entries.length === 1 ? pkg.name : `${pkg.name}:${toPosix(path.relative(pkg.root, entryPath))}`;
+				if (entries.has(id)) {
+					this.#warnings.push(
+						`extension id "${id}" is provided by both a local file and package "${pkg.source}"; the local file wins — reference the package as "${pkg.source}"`,
+					);
+					continue;
+				}
+				entries.set(id, { id, entry: entryPath, packageName: pkg.name, origin: "package" });
+			}
+		}
+		this.#entries = entries;
+	}
+
+	get(id: string): { id: string; entry: string; origin: "package" | "local" } | undefined {
+		return this.#entries.get(id);
+	}
+
+	list(): SelectedExtension[] {
+		return [...this.#entries.values()].map((e) => ({ id: e.id, entry: e.entry, origin: e.origin }));
+	}
+
+	warnings(): string[] {
+		return [...this.#warnings];
+	}
+
+	selectableNames(): string[] {
+		const names = new Set(this.#entries.keys());
+		for (const pkg of this.#packages) names.add(pkg.name);
+		return [...names].sort();
+	}
+
+	#packageByNameOrAlias(reference: string): DiscoveredPackage | undefined {
+		return this.#packages.find((pkg) => pkg.name === reference || pkg.source === reference);
+	}
+
+	#packageEntries(pkg: DiscoveredPackage): SelectedExtension[] {
+		return pkg.entries.map((entryPath) => {
+			const id = pkg.entries.length === 1 ? pkg.name : `${pkg.name}:${toPosix(path.relative(pkg.root, entryPath))}`;
+			const existing = this.#entries.get(id);
+			if (existing !== undefined && existing.entry === entryPath) return existing;
+			return { id, entry: entryPath, origin: "package" };
+		});
+	}
+
+	#unknownMessage(reference: string, names: string[]): string {
+		const lines = [
+			`unknown extension: "${reference}" — no installed package, extension file, or path matches it.`,
+		];
+		if (names.length > 0) {
+			const shown = names.slice(0, 10);
+			lines.push(`discovered: ${shown.join(", ")}${names.length > shown.length ? ` (+${names.length - shown.length} more)` : ""}`);
+		}
+		const suggestion = names.find(
+			(name) =>
+				name.toLowerCase().includes(reference.toLowerCase()) || reference.toLowerCase().includes(name.toLowerCase()),
+		);
+		if (suggestion !== undefined) {
+			lines.push(`did you mean "${suggestion}"?`);
+		}
+		return lines.join("\n");
+	}
+
+	async select(references: string[]): Promise<SelectExtensionsResult> {
+		const byPath = new Map<string, SelectedExtension>();
+		const unmatched: string[] = [];
+		const names = this.selectableNames();
+
+		const add = (entry: SelectedExtension): void => {
+			if (!byPath.has(entry.entry)) byPath.set(entry.entry, entry);
+		};
+
+		for (const reference of references) {
+			if (reference.includes("*") || reference.includes("?")) {
+				let matched = 0;
+				for (const name of names) {
+					if (!minimatch(name, reference)) continue;
+					matched += 1;
+					const pkg = this.#packageByNameOrAlias(name);
+					const entry = this.#entries.get(name);
+					if (pkg !== undefined && pkg.name === name) {
+						for (const pkgEntry of this.#packageEntries(pkg)) add(pkgEntry);
+					}
+					if (entry !== undefined) add(entry);
+				}
+				if (matched === 0) unmatched.push(reference);
+				continue;
+			}
+
+			const entry = this.#entries.get(reference);
+			if (entry !== undefined) {
+				add(entry);
+				continue;
+			}
+			const pkg = this.#packageByNameOrAlias(reference);
+			if (pkg !== undefined) {
+				const pkgEntries = this.#packageEntries(pkg);
+				if (pkgEntries.length === 0) {
+					throw new ExtensionError(
+						`package "${reference}" declares no extension entries (its pi.extensions files are missing or shadowed by local files)`,
+					);
+				}
+				for (const pkgEntry of pkgEntries) add(pkgEntry);
+				continue;
+			}
+			if (looksLikePath(reference)) {
+				if (reference.startsWith("./") || reference.startsWith("../")) {
+					throw new ExtensionError(
+						`extension reference "${reference}" is a relative path; profiles take absolute paths (or ~/...) — catalogs live in both global and project scope, so a relative base would be ambiguous`,
+					);
+				}
+				const resolved = reference.startsWith("~/")
+					? path.join(process.env.HOME ?? "", reference.slice(1))
+					: path.resolve(reference);
+				if (!(await exists(resolved))) {
+					throw new ExtensionError(`extension path not found: ${resolved}`);
+				}
+				add({ id: resolved, entry: resolved, origin: "path" });
+				continue;
+			}
+			throw new ExtensionError(this.#unknownMessage(reference, names));
+		}
+
+		return { entries: [...byPath.values()], unmatched };
+	}
+}
+
+const LOOSE_FILE_PATTERN = /\.(ts|js)$/;
+
+/** Derives a package name from its source string when package.json is
+ *  unreadable: strips the npm:/git:/github: prefix and any version spec
+ *  (scoped names keep their "@scope/" prefix). */
+export function packageNameFromSource(source: string): string {
+	let name = source.replace(/^(npm|git|github):/, "");
+	if (name.startsWith("@")) {
+		// @scope/pkg[@version] — cut a version spec only after the scope path.
+		const slash = name.indexOf("/");
+		const versionAt = slash === -1 ? -1 : name.indexOf("@", slash);
+		if (versionAt !== -1) name = name.slice(0, versionAt);
+	} else {
+		const versionAt = name.indexOf("@");
+		if (versionAt !== -1) name = name.slice(0, versionAt);
+	}
+	return name;
+}
+
+/** Reads one installed package's declared extension entries. Packages
+ *  without a readable package.json or without `pi.extensions` contribute
+ *  nothing (skills-only packages are the common case). Declared entries
+ *  missing on disk are skipped — the spawned pi reports load errors itself. */
+async function readPackageExtensions(pkg: ConfiguredPackageRoot): Promise<DiscoveredPackage | undefined> {
+	if (pkg.root === undefined) return undefined;
+	let manifest: unknown;
+	try {
+		manifest = JSON.parse(await readFile(path.join(pkg.root, "package.json"), "utf8"));
+	} catch {
+		return undefined; // not installed yet or unreadable — nothing selectable
+	}
+	if (!isRecord(manifest)) return undefined;
+	const pi = manifest.pi;
+	const declared =
+		isRecord(pi) && Array.isArray(pi.extensions) ? pi.extensions.filter((e): e is string => typeof e === "string") : [];
+	if (declared.length === 0) return undefined;
+	const entries: string[] = [];
+	for (const rel of declared) {
+		const entry = path.resolve(pkg.root, rel);
+		if (await exists(entry)) entries.push(entry);
+	}
+	if (entries.length === 0) return undefined;
+	const name = typeof manifest.name === "string" && manifest.name.length > 0 ? manifest.name : packageNameFromSource(pkg.source);
+	return { name, source: pkg.source, root: pkg.root, entries };
+}
+
+/** Lists loose extension files in one directory; missing dir → empty.
+ *  A `.ts`/`.js` stem pair resolves to the `.ts` file (Pi's convention:
+ *  TypeScript sources are the canonical form) and is reported, not silent. */
+async function scanLooseDir(dir: string, warnings: string[]): Promise<DiscoveredLocalExtension[]> {
+	let files: string[];
+	try {
+		files = (await readdir(dir)).filter((name) => LOOSE_FILE_PATTERN.test(name));
+	} catch {
+		return [];
+	}
+	const byStem = new Map<string, string>();
+	for (const name of files.sort()) {
+		const stem = name.replace(LOOSE_FILE_PATTERN, "");
+		const full = path.join(dir, name);
+		const existing = byStem.get(stem);
+		if (existing !== undefined) {
+			if (!existing.endsWith(".ts") && name.endsWith(".ts")) {
+				warnings.push(`extension "${stem}" exists as both .ts and .js in ${dir}; the .ts file is used`);
+				byStem.set(stem, full);
+			}
+			continue;
+		}
+		byStem.set(stem, full);
+	}
+	return [...byStem.entries()].map(([id, entry]) => ({ id, entry }));
+}
+
+export async function discoverImplicitExtensions(options: {
+	agentDir: string;
+	/** Configured user-scope packages with resolved roots (launcher discovery). */
+	packages: ConfiguredPackageRoot[];
+	/** Trusted project dir; untrusted projects are never scanned. */
+	projectDir?: string;
+}): Promise<ImplicitExtensionDiscovery> {
+	const warnings: string[] = [];
+
+	const packages: DiscoveredPackage[] = [];
+	for (const pkg of options.packages) {
+		const discovered = await readPackageExtensions(pkg);
+		if (discovered !== undefined) packages.push(discovered);
+	}
+
+	const globalLocal = await scanLooseDir(path.join(options.agentDir, "extensions"), warnings);
+	const merged = new Map<string, DiscoveredLocalExtension>(globalLocal.map((entry) => [entry.id, entry]));
+	if (options.projectDir !== undefined) {
+		// Project loose files override same-ID global ones, mirroring the
+		// catalog/registry override convention.
+		for (const entry of await scanLooseDir(path.join(options.projectDir, ".pi", "extensions"), warnings)) {
+			merged.set(entry.id, entry);
+		}
+	}
+
+	return { packages, local: [...merged.values()], warnings };
+}
+
+export async function discoverExtensions(options: {
+	agentDir: string;
+	packages: ConfiguredPackageRoot[];
+	projectDir?: string;
+}): Promise<DiscoveredExtensions> {
+	const raw = await discoverImplicitExtensions(options);
+	return new DiscoveredExtensions(raw.packages, raw.local, raw.warnings);
+}

package/src/json-file.ts

@@ -1,11 +1,10 @@
 /**
- * Shared JSON-file reading for pi-profile-switch's file-backed stores (catalog,
+ * Shared JSON-file reading for pi-profile's file-backed stores (catalog,
  * resource registry, runtime state). Each store maps read failures to its
  * own error policy (loud CatalogError/RegistryError vs. quiet state
  * fallback); this helper only classifies the outcome.
  */
 
-import { readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 
 export type JsonFileResult =
@@ -31,25 +30,6 @@ export async function readJsonFile(filePath: string): Promise<JsonFileResult> {
 	}
 }
 
-/** Synchronous twin of `readJsonFile`, for callers that must finish before
- *  an event Pi is about to emit (extension loading). Same classification. */
-export function readJsonFileSync(filePath: string): JsonFileResult {
-	let raw: string;
-	try {
-		raw = readFileSync(filePath, "utf8");
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-			return { ok: false, reason: "missing" };
-		}
-		throw error;
-	}
-	try {
-		return { ok: true, value: JSON.parse(raw) };
-	} catch {
-		return { ok: false, reason: "invalid" };
-	}
-}
-
 export function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/src/launcher/args.ts

@@ -0,0 +1,57 @@
+/**
+ * Launcher argument parsing for the `pi-profile` binary.
+ *
+ * Grammar: `pi-profile [profile] [--] <pi args>...`
+ * - The launcher consumes exactly two things: an optional leading positional
+ *   profile name, and at most one `--` separator. Positional arguments after
+ *   the profile name belong to pi (they are pi's message arguments).
+ * - Everything else is passed through to Pi verbatim (ADR-0005): any pi flag,
+ *   known or unknown, reaches the real pi binary unchanged.
+ * - `--approve` / `-a` / `--no-approve` / `-na` are recognized and recorded as
+ *   a trust override input; the caller decides whether to re-apply them
+ *   (default profile: native passthrough) or feed them to the resolver
+ *   (non-default profiles: one-run trust input, never forwarded, so Pi never
+ *   auto-discovers unfiltered project resources). Contradictory repeats are
+ *   last-wins, matching CLI convention.
+ */
+
+export interface LauncherArgs {
+	/** Positional profile name; undefined means "use the default or saved profile". */
+	profile: string | undefined;
+	/** Arguments forwarded verbatim to the spawned pi process. */
+	piArgs: string[];
+	/** Trust override recorded from --approve/-a (true) or --no-approve/-na (false). */
+	trustOverride: boolean | undefined;
+}
+
+const APPROVE_FLAGS = new Set(["--approve", "-a"]);
+const NO_APPROVE_FLAGS = new Set(["--no-approve", "-na"]);
+
+export function parseLauncherArgs(argv: string[]): LauncherArgs {
+	const rest = [...argv];
+
+	let profile: string | undefined;
+	if (rest[0] !== undefined && !rest[0].startsWith("-")) {
+		profile = rest.shift();
+	}
+	// Consume at most one separator (pi-profile's own); later `--` belong to pi.
+	if (rest[0] === "--") {
+		rest.shift();
+	}
+
+	let trustOverride: boolean | undefined;
+	const piArgs: string[] = [];
+	for (const arg of rest) {
+		if (APPROVE_FLAGS.has(arg)) {
+			trustOverride = true; // last-wins, like pi's own flag handling
+			continue;
+		}
+		if (NO_APPROVE_FLAGS.has(arg)) {
+			trustOverride = false;
+			continue;
+		}
+		piArgs.push(arg);
+	}
+
+	return { profile, piArgs, trustOverride };
+}

package/src/launcher/discovery.ts

@@ -0,0 +1,64 @@
+/**
+ * Launcher-side discovery: the full skill registry plus the configured
+ * global package roots, both read-only, feeding the resolver and the
+ * settings generator.
+ */
+
+import path from "node:path";
+
+import { DefaultPackageManager, SettingsManager } from "@earendil-works/pi-coding-agent";
+
+import {
+	DiscoveredExtensions,
+	discoverExtensions,
+} from "../extension-discovery.ts";
+import type { ConfiguredPackageRoot } from "../settings-generator.ts";
+import { discoverSkills, type SkillEntry } from "../skill-registry.ts";
+import type { LauncherContext } from "./initial-profile.ts";
+
+export interface LauncherDiscovery {
+	skills: SkillEntry[];
+	packages: ConfiguredPackageRoot[];
+	/** Discovered selectable extensions: package entries + loose files. */
+	extensions: DiscoveredExtensions;
+}
+
+/** Resolves a configured package's local root without network access:
+ *  the manager's installed path for npm/git sources, or the local source
+ *  path resolved against the agent dir (Pi's base for user-scope entries). */
+function resolvePackageRoot(source: string, installedPath: string | undefined, agentDir: string): string | undefined {
+	if (installedPath !== undefined) return installedPath;
+	if (source.startsWith("npm:") || source.startsWith("git:") || source.startsWith("github:")) return undefined;
+	const expanded = source.startsWith("~")
+		? path.join(process.env.HOME ?? "", source.slice(1))
+		: source;
+	return path.resolve(agentDir, expanded);
+}
+
+export async function discoverLauncherResources(
+	context: LauncherContext & { projectTrusted: boolean },
+): Promise<LauncherDiscovery> {
+	const settingsManager = SettingsManager.create(context.cwd, context.agentDir, {
+		projectTrusted: context.projectTrusted,
+	});
+	const packageManager = new DefaultPackageManager({
+		cwd: context.cwd,
+		agentDir: context.agentDir,
+		settingsManager,
+	});
+	// User-scope packages only: project-scope packages install under the
+	// project's .pi/npm, which generated global-scope settings cannot reference.
+	const configured = packageManager
+		.listConfiguredPackages()
+		.filter((pkg) => pkg.scope === "user")
+		.map((pkg) => ({ source: pkg.source, root: resolvePackageRoot(pkg.source, pkg.installedPath, context.agentDir) }));
+	const [skills, extensions] = await Promise.all([
+		discoverSkills(context),
+		discoverExtensions({
+			agentDir: context.agentDir,
+			packages: configured,
+			projectDir: context.projectTrusted ? context.cwd : undefined,
+		}),
+	]);
+	return { skills, packages: configured, extensions };
+}

package/src/launcher/initial-profile.ts

@@ -0,0 +1,179 @@
+/**
+ * Initial profile resolution for the launcher.
+ *
+ * Flow: trust check (gatekeeper for everything project-scoped) → positional
+ * name or saved state (project state wins when trusted) → catalog lookup →
+ * skill discovery + resource registry → resolver (glob expansion, dependency
+ * closure, alwaysOn, model validation) → ActivationPlan + full discovery
+ * results for the settings generator. Unknown profiles, malformed
+ * catalogs/registries, and unresolvable resources all fail before Pi spawns.
+ *
+ * The CLI's initial selection is transient: no runtime state is written here.
+ */
+
+import path from "node:path";
+
+import { isRecord, readJsonFile } from "../json-file.ts";
+import { discoverAdapterServerNames } from "../mcp-config.ts";
+import { isAdapterExtension, MissingMcpAdapterError } from "../mcp-coordination.ts";
+import { ProfileCatalog, type ResolvedProfile } from "../profile-catalog.ts";
+import { ActivationError, defaultPlan, resolveProfile, type ActivationPlan } from "../profile-resolver.ts";
+import { resolveProjectTrust } from "../project-trust.ts";
+import { RuntimeStateStore, type RuntimeOverlay } from "../runtime-state-store.ts";
+import { getGlobalStateDir } from "../workspace.ts";
+import { discoverLauncherResources, type LauncherDiscovery } from "./discovery.ts";
+import { checkDeclaredModel } from "./model-check.ts";
+
+export class UnknownProfileError extends Error {
+	constructor(name: string) {
+		super(`unknown profile: ${name}`);
+		this.name = "UnknownProfileError";
+	}
+}
+
+/** Zero-match glob references surface as launch warnings (ADR-0006):
+ *  visible, but never blocking — globs re-expand on every resolution. */
+function unmatchedWarnings(plan: ActivationPlan): string[] {
+	return (plan.unmatched ?? []).map(
+		(reference) => `profile "${plan.profile}": "${reference}" matched nothing this resolution`,
+	);
+}
+
+export interface LauncherContext {
+	/** The user's real agent dir (e.g. ~/.pi/agent). */
+	agentDir: string;
+	/** The project working directory Pi will run in. */
+	cwd: string;
+	/** One-run trust input from --approve / --no-approve (never forwarded to Pi). */
+	trustOverride?: boolean;
+}
+
+export interface InitialProfile {
+	plan: ActivationPlan;
+	/** Full discovery results for the settings generator. Undefined for the
+	 *  default profile (which applies no filtering). */
+	discovery?: LauncherDiscovery;
+	/** The trusted project's `.pi/settings.json` content, when trusted and
+	 *  present. The generator merges it into the base for selection plans. */
+	projectSettings?: Record<string, unknown>;
+	/** Non-fatal notices for the user (e.g. a dangling restored profile that
+	 *  fell back to default). The launcher prints them. */
+	warnings: string[];
+}
+
+/** Reads the real global `defaultProjectTrust` setting (a trust input) and,
+ *  when trusted, the project's `.pi/settings.json`. Exported for the
+ *  session-side surfaces (selector/list/status) that need the same trust
+ *  gate the launcher uses. */
+export async function readTrustInputs(context: LauncherContext): Promise<{
+	projectTrusted: boolean;
+	projectSettings?: Record<string, unknown>;
+}> {
+	const globalSettingsPath = path.join(context.agentDir, "settings.json");
+	const globalSettings = await readJsonFile(globalSettingsPath);
+	const userDefaultProjectTrust =
+		globalSettings.ok && isRecord(globalSettings.value) && typeof globalSettings.value.defaultProjectTrust === "string"
+			? globalSettings.value.defaultProjectTrust
+			: undefined;
+	const projectTrusted = resolveProjectTrust({
+		cwd: context.cwd,
+		agentDir: context.agentDir,
+		trustOverride: context.trustOverride,
+		userDefaultProjectTrust,
+	});
+	if (!projectTrusted) {
+		return { projectTrusted };
+	}
+	const projectSettingsResult = await readJsonFile(path.join(context.cwd, ".pi", "settings.json"));
+	const projectSettings =
+		projectSettingsResult.ok && isRecord(projectSettingsResult.value) ? projectSettingsResult.value : undefined;
+	return { projectTrusted, projectSettings };
+}
+
+export async function resolveInitialProfile(
+	name: string | undefined,
+	context: LauncherContext,
+	options?: { overlay?: RuntimeOverlay },
+): Promise<InitialProfile> {
+	const { projectTrusted, projectSettings } = await readTrustInputs(context);
+	const projectDir = projectTrusted ? context.cwd : undefined;
+	const catalog = await ProfileCatalog.load(context.agentDir, { projectDir });
+
+	let selected = name;
+	const warnings: string[] = [];
+	if (selected === undefined) {
+		// No positional name: the trusted project's saved selection is the more
+		// specific one and wins; otherwise the global state, then default.
+		if (projectTrusted) {
+			selected = (await new RuntimeStateStore(path.join(context.cwd, ".pi")).read()).activeProfile;
+		}
+		selected ??= (await new RuntimeStateStore(getGlobalStateDir(context.agentDir)).read()).activeProfile ?? "default";
+	}
+
+	const profile = catalog.resolve(selected);
+	if (profile === undefined) {
+		// Explicit positional selection fails loudly; a restored selection that
+		// no longer exists falls back to default with a warning instead of
+		// blocking the launch (restore is a convenience, not a commitment).
+		if (name !== undefined) {
+			throw new UnknownProfileError(selected);
+		}
+		warnings.push(`saved profile "${selected}" no longer exists; starting the default profile`);
+		return { plan: defaultPlan(), warnings };
+	}
+	if (profile.source === "builtin") {
+		// The default profile is normally unfiltered. With an overlay it becomes
+		// a synthetic "everything minus disabled" selection (PRD: overlays may
+		// temporarily narrow default's scope). MCP narrowing on default is
+		// rejected — the adapter's own /mcp commands own that surface natively.
+		const overlay = options?.overlay;
+		const narrowed =
+			overlay !== undefined &&
+			((overlay.disabledSkills?.length ?? 0) > 0 ||
+				(overlay.disabledExtensions?.length ?? 0) > 0 ||
+				(overlay.disabledMcps?.length ?? 0) > 0 ||
+				overlay.tools !== undefined);
+		if (!narrowed) {
+			return { plan: defaultPlan(), warnings };
+		}
+		if ((overlay.disabledMcps?.length ?? 0) > 0) {
+			throw new ActivationError(
+				"the default profile has no MCP allowlist to narrow — use the adapter's own /mcp commands instead",
+			);
+		}
+		const synthetic: ResolvedProfile = {
+			name: "default",
+			source: "builtin",
+			definition: { skills: ["*"], extensions: ["*"] },
+		};
+		const discovery = await discoverLauncherResources({ ...context, projectTrusted });
+		const plan = await resolveProfile({
+			profile: synthetic,
+			skills: discovery.skills,
+			extensions: discovery.extensions,
+			overlay,
+		});
+		warnings.push(...discovery.extensions.warnings(), ...unmatchedWarnings(plan));
+		return { plan, discovery, projectSettings, warnings };
+	}
+
+	const discovery = await discoverLauncherResources({ ...context, projectTrusted });
+	const plan = await resolveProfile({
+		profile,
+		skills: discovery.skills,
+		extensions: discovery.extensions,
+		validateModel: (model) => checkDeclaredModel(context.agentDir, model),
+		discoveredMcpServers: profile.definition.mcps?.length
+			? await discoverAdapterServerNames(context.agentDir, projectDir)
+			: undefined,
+		overlay: options?.overlay,
+	});
+	warnings.push(...discovery.extensions.warnings(), ...unmatchedWarnings(plan));
+	if (plan.mcps !== undefined && !plan.extensions.some(isAdapterExtension)) {
+		// Fail before spawn: without the adapter in the active extension set
+		// nobody applies the allowlist, and the declared servers would either
+		// silently do nothing or leak through unfiltered.
+		throw new MissingMcpAdapterError(plan.profile);
+	}
+	return { plan, discovery, projectSettings, warnings };
+}