pi-profile-switch 0.3.0 → 0.3.1

package/README.md

@@ -6,7 +6,7 @@ Named profiles for [Pi](https://github.com/badlogic/pi-mono). A profile selects
 
 A shipped `read-only` preset covers the read-and-report workflow; other workflows you write yourself — a profile can narrow the tool set, hide skills, pin a model, or add instructions.
 
-`pi-profile-switch` is a plain Pi package (ADR-0007). It installs like any other extension, leaves Pi's configuration directory untouched, and keeps sessions, packages, project trust, and every other installed extension native.
+`pi-profile-switch` is a plain Pi package (ADR-0007). It installs like any other extension, keeps Pi's configuration directory as the single source of truth, and keeps sessions, packages, project trust, and every other installed extension native. The only file it adds is the default catalog below.
 
 ## Install
 
@@ -16,6 +16,8 @@ pi install npm:pi-profile-switch
 
 Requires [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) (installed automatically as a peer dependency).
 
+Pi packages have no install hook, so the default catalog is written the first time the extension loads (in any mode, including `--mode rpc`): if `~/.pi/agent/profiles.json` does not exist, it is created from the shipped `read-only` profile. An existing file is never read, rewritten, or backed up — delete it to get the default back.
+
 ## Quick start
 
 ```bash
@@ -29,7 +31,9 @@ pi --profile read-only
 pi --profile default
 ```
 
-Create profiles with `/profile create`, which writes `~/.pi/agent/profiles.json` (global) or `<project>/.pi/profiles.json` (project, trusted projects only). The wizard offers the shipped `read-only` preset — Pi's built-in tools only, no skills, MCP servers, or model assumed — or a blank definition.
+A fresh install already holds one profile, `read-only`; activate it with `pi --profile read-only` or `/profile use read-only`.
+
+Create more with `/profile create`, which writes `~/.pi/agent/profiles.json` (global) or `<project>/.pi/profiles.json` (project, trusted projects only). The wizard offers the shipped `read-only` preset — Pi's built-in tools only, no skills, MCP servers, or model assumed — or a blank definition.
 
 A preset is a one-time copy into your catalog: it is not tracked, so a package update never changes a profile you already created. Profiles **reference** resources by name — they never copy them. [`examples/profiles.example.json`](examples/profiles.example.json) is a complete catalog with several profiles covering every field; replace its resource names with ones you own.
 
@@ -42,7 +46,7 @@ A preset is a one-time copy into your catalog: it is not tracked, so a package u
 | `instructions` | Text appended to the system prompt every turn |
 | `model` | Session-start model preset; an explicit `--model`/`--thinking` or a model recorded in the session wins |
 | `skills` | What the model sees in the prompt's skills list. Every installed skill stays loaded and callable by the user through `/skill:name` |
-| `mcp` | Which MCP servers the session exposes: the profile's allowlist is written into the adapter's own config (`~/.pi/agent/mcp.json`), disabling every other server. Servers you keep in that file move to `mcp.user.json`; connection details stay in your config, never in the profile |
+| `mcps` | Which MCP servers the session exposes: the profile's allowlist is written into the adapter's own config (`~/.pi/agent/mcp.json`), disabling every other server. Servers you keep in that file move to `mcp.user.json`; connection details stay in your config, never in the profile. The legacy key `mcp` is still read and becomes `mcps` the next time the profile is saved |
 | `tools` | Active tool set: declared names/globs become the active set; names that register later (MCP, extensions) are applied when they appear |
 
 Anything a profile does not declare keeps Pi's native behavior, and `default` declares nothing.
@@ -69,7 +73,7 @@ All commands work in non-interactive modes (`--mode rpc|print|json`); CRUD wizar
 - **Reference, never copy** — profiles point at resources you already own and maintain.
 - **Pi-native** — the configuration directory is Pi's own, so sessions, extension config, packages, context files, and trust behave exactly as they do in plain Pi.
 - **Fail safe** — untrusted project directories are never read; a failed activation applies nothing and reports the cause.
-- **No manual reload** — switching re-applies runtime state in place and the next turn's prompt carries the new selection. Only a change to the MCP selection rebuilds the runtime, automatically, in the same session.
+- **No manual reload** — switching re-applies runtime state in place and the next turn's prompt carries the new selection. Only a change to the MCP selection rebuilds the runtime, automatically, in the same session, and the switch survives that rebuild: the rebuild continues the selection you made, it does not fall back to the profile you started with.
 
 ## Docs
 

package/README.zh-CN.md

@@ -6,7 +6,7 @@
 
 随包提供一个 `read-only` 预设覆盖「读代码 + 报告」的工作流；其余工作流由你自己定义——profile 可以收窄工具集、隐藏 skill、固定模型或附加指令。
 
-`pi-profile-switch` 是普通 Pi package（ADR-0007）：像其他扩展一样安装，不改动 Pi 的配置目录，session、packages、项目信任和其他扩展全部保持原生。
+`pi-profile-switch` 是普通 Pi package（ADR-0007）：像其他扩展一样安装，配置目录始终是 Pi 自己的那一份，session、packages、项目信任和其他扩展全部保持原生。它只在配置目录里新增一个文件，就是下面这个默认 catalog。
 
 ## 安装
 
@@ -16,6 +16,8 @@ pi install npm:pi-profile-switch
 
 依赖 [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)（作为 peer dependency 自动安装）。
 
+Pi package 没有安装钩子，因此默认 catalog 在扩展首次加载时写入（任何模式都会执行，包括 `--mode rpc`）：`~/.pi/agent/profiles.json` 不存在时，用随包的 `read-only` profile 创建它。已存在的文件不会被读取、改写或备份——删掉它即可拿回默认值。
+
 ## 快速上手
 
 ```bash
@@ -29,7 +31,9 @@ pi --profile read-only
 pi --profile default
 ```
 
-用 `/profile create` 创建 profile，写入 `~/.pi/agent/profiles.json`（全局）或 `<项目>/.pi/profiles.json`（项目级，仅限已信任项目）。向导提供随包的 `read-only` 预设——只用 Pi 内建工具，不假设任何 skill、MCP server 或模型——也可以从空定义开始。
+新安装已经带有一个 `read-only` profile，用 `pi --profile read-only` 或 `/profile use read-only` 激活。
+
+用 `/profile create` 创建更多 profile，写入 `~/.pi/agent/profiles.json`（全局）或 `<项目>/.pi/profiles.json`（项目级，仅限已信任项目）。向导提供随包的 `read-only` 预设——只用 Pi 内建工具，不假设任何 skill、MCP server 或模型——也可以从空定义开始。
 
 预设只被复制一次：它不被跟踪，包升级不会改动你已经创建的 profile。Profile 只**引用**资源，从不复制资源。[`examples/profiles.example.json`](examples/profiles.example.json) 是覆盖全部字段的完整 catalog，示例中的资源名请替换成你本机已有的名字。
 
@@ -42,7 +46,7 @@ pi --profile default
 | `instructions` | 每个 turn 追加到 system prompt 末尾 |
 | `model` | 会话启动的模型预设；显式 `--model`/`--thinking` 或 session 历史中记录的模型优先 |
 | `skills` | 模型在 prompt skills 列表中看到的内容；所有已安装 skill 仍保持加载，用户可用 `/skill:name` 手动调用 |
-| `mcp` | 本次会话暴露哪些 MCP server：白名单写入 adapter 自己的配置（`~/.pi/agent/mcp.json`），其余 server 一律标为 disabled。你原本放在该文件里的 server 会迁移到 `mcp.user.json`；连接参数只在你自己的配置里，从不进入 profile |
+| `mcps` | 本次会话暴露哪些 MCP server：白名单写入 adapter 自己的配置（`~/.pi/agent/mcp.json`），其余 server 一律标为 disabled。你原本放在该文件里的 server 会迁移到 `mcp.user.json`；连接参数只在你自己的配置里，从不进入 profile。旧键 `mcp` 仍可读取，下次保存 profile 时变为 `mcps` |
 | `tools` | 活动工具集：声明的名字/glob 成为活动集合；之后才注册的工具（MCP、扩展）在出现时补上 |
 
 未声明的字段保持 Pi 原生行为，`default` 什么都不声明。
@@ -69,7 +73,7 @@ pi --profile default
 - **引用而非复制**——profile 指向你自己拥有和维护的资源。
 - **Pi 原生**——配置目录就是 Pi 自己的目录，session、扩展配置、packages、context 文件和信任行为与原生 Pi 完全一致。
 - **失败安全**——未信任的项目目录从不读取；激活失败时不应用任何设置并报出原因。
-- **无需手动 reload**——切换在原位重新应用运行时状态，下一个 turn 的 prompt 直接带上新选择；只有 MCP 选择变化时才会自动重建运行时（同一 session）
+- **无需手动 reload**——切换在原位重新应用运行时状态，下一个 turn 的 prompt 直接带上新选择；只有 MCP 选择变化时才会自动重建运行时（同一 session），且切换结果在重建后保持不变：重建沿用你刚做的选择，不会退回启动时的 profile
 
 ## 文档
 

package/examples/profiles.example.json

@@ -19,7 +19,7 @@
         "code-review",
         "git-*"
       ],
-      "mcp": [
+      "mcps": [
         "github"
       ],
       "tools": [
@@ -56,7 +56,7 @@
         "git-commit",
         "test-*"
       ],
-      "mcp": [
+      "mcps": [
         "github"
       ],
       "tools": [

package/extensions/pi-profile-switch/index.ts

@@ -12,6 +12,7 @@ import { probeAdapterPresence } from "../../src/mcp-coordination.ts";
 import { readSessionChoices } from "../../src/model-selection.ts";
 import { buildProfileBadge, PROFILE_STATUS_KEY, renderProfileBadge } from "../../src/profile-badge.ts";
 import type { ProfileDefinition } from "../../src/profile-catalog.ts";
+import { seedDefaultProfilesSync } from "../../src/default-profiles.ts";
 import {
 	formatSelectionWarnings,
 	formatSkillWarnings,
@@ -26,8 +27,10 @@ import {
 	type SkillsFilterOutcome,
 } from "../../src/skill-selection.ts";
 import {
+	appliedProfile,
 	detectExplicitDeclarations,
 	readProfileFlag,
+	recordAppliedProfile,
 	registerProfileFlag,
 	resolveStartupProfile,
 } from "../../src/startup-selection.ts";
@@ -69,10 +72,14 @@ import { buildStatusReport, formatStatusMarkdown } from "../../src/switching/sta
  * all native.
  *
  * Responsibilities:
+ * - load: seed `<agentDir>/profiles.json` from the shipped default catalog
+ *   when the file does not exist yet (Pi packages have no install hook), and
+ *   report a failure once at `session_start`.
  * - `session_start`: resolve the startup profile (`--profile <flag>`, else
- *   the saved selection, else `default`), then apply the runtime parts of
- *   the selection — model preset, active tools, MCP allowlist. A failed
- *   activation applies nothing and reports loudly.
+ *   the saved selection, else `default`; every start after the first
+ *   continues the selection this process already applied), then apply the
+ *   runtime parts of the selection — model preset, active tools, MCP
+ *   allowlist. A failed activation applies nothing and reports loudly.
  * - `before_agent_start`: rebuild the system prompt each turn — replace the
  *   skills section with the profile's visible set and append the profile's
  *   instructions. Unselected skills stay loaded and `/skill:`-invocable.
@@ -123,11 +130,21 @@ export default function piProfileExtension(pi: ExtensionAPI): void {
 	registerProfileFlag(pi);
 	const argv = process.argv.slice(2);
 	const explicit = detectExplicitDeclarations(argv);
+	const loadAgentDir = getAgentDir();
+	// Install-time default: Pi packages have no install hook, so the first
+	// load seeds <agentDir>/profiles.json from the shipped catalog. The write
+	// is idempotent, never overwrites a user catalog, and a failure is
+	// reported at session_start instead of blocking the load.
+	let seedWarning: string | undefined;
+	try {
+		seedDefaultProfilesSync(loadAgentDir);
+	} catch (error) {
+		seedWarning = `pi-profile-switch: could not write the default profiles.json — ${error instanceof Error ? error.message : String(error)}`;
+	}
 	// pi-mcp-adapter reads its config before any session event fires (and, for
 	// eager servers, at its own load time), so the startup profile's overlay
 	// is generated here, synchronously. Pi applies CLI flag values only after
 	// extension loading, hence argv.
-	const loadAgentDir = getAgentDir();
 	const adapterInstalled = adapterPresent({
 		agentDir: loadAgentDir,
 		argv,
@@ -135,11 +152,15 @@ export default function piProfileExtension(pi: ExtensionAPI): void {
 	});
 	if (adapterInstalled) {
 		const requestedConfigPath = readFlagFromArgv(argv, "mcp-config");
+		// A reload's overlay belongs to the run's current selection: the same
+		// continuation `session_start` applies right after this pass.
+		const runProfile = appliedProfile();
 		syncStartupMcpOverlay({
 			agentDir: loadAgentDir,
 			cwd: process.cwd(),
 			argv,
 			...(requestedConfigPath === undefined ? {} : { overridePath: requestedConfigPath }),
+			...(runProfile === undefined ? {} : { continuation: runProfile }),
 		});
 	}
 	let current: Activation | undefined;
@@ -243,6 +264,8 @@ export default function piProfileExtension(pi: ExtensionAPI): void {
 			overlay: options?.overlay ?? null,
 			persist: options?.persist ?? true,
 		});
+		// The run's current selection, for the reload continuation.
+		recordAppliedProfile(result.selection.name);
 		setCurrent(ctx, activationOf(result, deps.live.skills !== undefined));
 		reportWarnings(ctx, formatSelectionWarnings(result.selection));
 		return result;
@@ -461,11 +484,20 @@ export default function piProfileExtension(pi: ExtensionAPI): void {
 		}
 	}
 
-	pi.on("session_start", async (_event, ctx) => {
+	pi.on("session_start", async (event, ctx) => {
 		setCurrent(ctx, undefined);
 		filterWarningShown = false;
+		if (seedWarning !== undefined) {
+			notify(ctx, seedWarning, "warning");
+			seedWarning = undefined;
+		}
 		const agentDir = getAgentDir();
 		const projectTrusted = ctx.isProjectTrusted();
+		// Every session start after the first (reload, new, resume, fork)
+		// continues the selection this process already applied. The `--profile`
+		// flag is a startup directive: re-reading it here would silently
+		// resurrect the profile the user just left.
+		const continuation = event.reason === "startup" ? undefined : appliedProfile();
 		const requested = readProfileFlag(pi);
 		let startup;
 		try {
@@ -474,6 +506,7 @@ export default function piProfileExtension(pi: ExtensionAPI): void {
 				cwd: ctx.cwd,
 				projectTrusted,
 				...(requested !== undefined ? { requested } : {}),
+				...(continuation !== undefined ? { continuation } : {}),
 			});
 		} catch (error) {
 			notify(ctx, error instanceof Error ? error.message : String(error), "error");
@@ -492,6 +525,7 @@ export default function piProfileExtension(pi: ExtensionAPI): void {
 				});
 			}
 		} catch (error) {
+			recordAppliedProfile(undefined);
 			notify(ctx, error instanceof Error ? error.message : String(error), "error");
 			reportWarnings(ctx, startup.warnings);
 		}
@@ -687,7 +721,7 @@ export default function piProfileExtension(pi: ExtensionAPI): void {
 				const reactivated = await activate(ctx, profile.name, { overlay: overlay ?? null, persist: true });
 				notify(
 					ctx,
-					`${action}d MCP server "${server}" in profile "${profile.name}" (mcp: [${result.mcp.join(", ")}])`,
+					`${action}d MCP server "${server}" in profile "${profile.name}" (mcps: [${result.mcps.join(", ")}])`,
 					"info",
 				);
 				await reloadForMcpOverlay(ctx, reactivated.selection);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-profile-switch",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Named profiles for Pi: skills, MCP servers, tools, model, and instructions per workflow — switched in place in the same session.",
   "type": "module",
   "keywords": [

package/schemas/profiles.schema.json

@@ -44,12 +44,12 @@
           },
           "description": "Skill names or globs. Controls what the model sees in the system prompt's skills section; every loaded skill stays callable by the user through /skill:name."
         },
-        "mcp": {
+        "mcps": {
           "type": "array",
           "items": {
             "type": "string"
           },
-          "description": "MCP server names or globs, discovered by pi-mcp-adapter configuration. Connection details stay in adapter-managed config."
+          "description": "MCP server names or globs, discovered by pi-mcp-adapter configuration. Connection details stay in adapter-managed config. The legacy key \"mcp\" is still accepted on read and migrates to \"mcps\" on the next save."
         },
         "tools": {
           "type": "array",

package/src/default-profiles.ts

@@ -0,0 +1,59 @@
+/**
+ * DefaultProfiles: the catalog a fresh install starts from.
+ *
+ * Pi packages have no install hook (docs/packages.md) — `pi install` only
+ * unpacks the package and runs `npm install` — so "installing the default
+ * profiles" can only happen the first time the extension actually loads.
+ * `seedDefaultProfilesSync` therefore runs at load time, before any session
+ * event, and is idempotent: an existing catalog file is never read, rewritten,
+ * or backed up, and the package never seeds again once the file exists.
+ *
+ * The seeded content is the shipped preset catalog, exactly what
+ * `examples/profiles.json` publishes, reached through the same
+ * `PROFILE_PRESETS` data `/profile create` offers — one definition, so the
+ * three cannot drift. The `read-only` profile declares built-in tools and
+ * instructions only: it activates on a machine with no skills, no
+ * `pi-mcp-adapter`, and no credentials, and it changes nothing until the
+ * user selects it.
+ *
+ * `profile-presets.test.ts` pins the content contract: this catalog equals
+ * the published `examples/profiles.json` and every definition is
+ * resource-free.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+import { DEFAULT_PROFILE_NAME, PROFILE_SCHEMA_VERSION } from "./profile-catalog.ts";
+import { PROFILE_PRESETS } from "./profile-presets.ts";
+
+/** The catalog written to `<agentDir>/profiles.json` on first load. */
+export const DEFAULT_PROFILE_CATALOG = {
+	schemaVersion: PROFILE_SCHEMA_VERSION,
+	profiles: Object.fromEntries(
+		PROFILE_PRESETS.filter((preset) => preset.name !== DEFAULT_PROFILE_NAME).map((preset) => [
+			preset.name,
+			preset.definition,
+		]),
+	),
+};
+
+export type DefaultSeedResult =
+	/** The agent dir had no catalog and now holds the default one. */
+	| "seeded"
+	/** A catalog file was already there; it was not touched. */
+	| "present";
+
+/**
+ * Writes `<agentDir>/profiles.json` when it does not exist yet. Synchronous
+ * on purpose: the load-time call site cannot await, and the write is one small
+ * file. Existing files win unconditionally — an empty or hand-written catalog
+ * is a user decision, not a missing default.
+ */
+export function seedDefaultProfilesSync(agentDir: string, catalog: unknown = DEFAULT_PROFILE_CATALOG): DefaultSeedResult {
+	const target = path.join(agentDir, "profiles.json");
+	if (existsSync(target)) return "present";
+	mkdirSync(agentDir, { recursive: true });
+	writeFileSync(target, `${JSON.stringify(catalog, null, 2)}\n`);
+	return "seeded";
+}

package/src/profile-catalog.ts

@@ -12,6 +12,12 @@
  * - Unknown fields (an `extensions` declaration left over from v0.1.0, an
  *   inheritance key) are ignored silently; saving drops them, so a written
  *   definition always matches the current shape.
+ * - The catalog key for MCP servers is `mcps` (plural, like `skills` and
+ *   `tools`). The legacy name `mcp` is still READ as an alias so an
+ *   existing catalog keeps its allowlist; `mcps` wins when both keys are
+ *   present, and a value of the wrong type fails loudly either way.
+ *   Definitions always carry the canonical `mcps` field in memory, and
+ *   profile-catalog-store.ts drops a file's legacy key on its next write.
  *
  * Invariants:
  * - The built-in `default` profile never exists in either file and cannot be
@@ -44,7 +50,7 @@ export interface ProfileDefinition {
 	label?: string;
 	description?: string;
 	skills?: string[];
-	mcp?: string[];
+	mcps?: string[];
 	tools?: string[];
 	model?: ProfileModel;
 	instructions?: string;
@@ -79,6 +85,27 @@ function readStringArray(value: unknown, field: string, profileName: string): st
 	return value as string[];
 }
 
+/** Legacy catalog key names, still accepted on read (canonical name wins).
+ *  The write paths (/profile CRUD, /mcp enable|disable) delete the alias, so
+ *  a file migrates to the canonical spelling the next time it is saved. */
+export const LEGACY_FIELD_ALIASES = { mcps: "mcp" } as const;
+
+/** Reads an array-of-strings field under its canonical name or a legacy
+ *  alias. Both spellings are validated when present, so a value of the
+ *  wrong type never passes silently through either key. */
+function readAliasedStringArray(
+	raw: Record<string, unknown>,
+	canonical: string,
+	legacy: string,
+	profileName: string,
+): string[] | undefined {
+	for (const key of [canonical, legacy]) {
+		if (raw[key] !== undefined) readStringArray(raw[key], key, profileName);
+	}
+	const source = raw[canonical] !== undefined ? canonical : legacy;
+	return readStringArray(raw[source], source, profileName);
+}
+
 function readOptionalString(value: unknown, field: string, profileName: string): string | undefined {
 	if (value === undefined) return undefined;
 	if (typeof value !== "string") {
@@ -100,10 +127,12 @@ export function parseProfileDefinition(name: string, raw: unknown): ProfileDefin
 	if (label !== undefined) definition.label = label;
 	const description = readOptionalString(raw.description, "description", name);
 	if (description !== undefined) definition.description = description;
-	for (const field of ["skills", "mcp", "tools"] as const) {
+	for (const field of ["skills", "tools"] as const) {
 		const entries = readStringArray(raw[field], field, name);
 		if (entries !== undefined) definition[field] = entries;
 	}
+	const mcps = readAliasedStringArray(raw, "mcps", LEGACY_FIELD_ALIASES.mcps, name);
+	if (mcps !== undefined) definition.mcps = mcps;
 	if (raw.model !== undefined) {
 		if (!isRecord(raw.model) || typeof raw.model.provider !== "string" || typeof raw.model.id !== "string") {
 			throw new CatalogError(`profile "${name}": "model" must be an object with string "provider" and "id"`);

package/src/profile-resolver.ts

@@ -5,7 +5,7 @@
  * ADR-0007 semantics:
  * - `skills` resolves to a visibility filter (see skill-selection.ts), not
  *   to loaded resources: every skill stays loaded and user-invocable.
- * - `mcp` resolves to a runtime server allowlist; a declared MCP intent that
+ * - `mcps` resolves to a runtime server allowlist; a declared MCP intent that
  *   cannot be satisfied (adapter absent, literal server unknown) fails the
  *   activation before anything is applied.
  * - `tools` resolves to an active tool set; literals the live registry does
@@ -136,7 +136,7 @@ function resolveMcp(
 	if (!live.adapterPresent) {
 		throw new SelectionError(
 			`profile "${profileName}" declares MCP servers but pi-mcp-adapter is not active in this session — ` +
-				`install the adapter or remove the "mcp" declaration`,
+				`install the adapter or remove the "mcps" declaration`,
 		);
 	}
 	const selected: string[] = [];
@@ -201,7 +201,7 @@ export function resolveSelection(input: {
 	const definition = profile.definition;
 
 	const skills = resolveSkills(definition.skills, overlay?.disabledSkills ?? [], live.skills);
-	const mcp = resolveMcp(definition.mcp, overlay?.disabledMcp ?? [], live.mcp, profile.name);
+	const mcp = resolveMcp(definition.mcps, overlay?.disabledMcp ?? [], live.mcp, profile.name);
 	const tools = input.suppressTools === true
 		? { pendingTools: [], warning: { toolsUnmatched: [] } }
 		: resolveTools(overlay?.tools ?? definition.tools, live.toolNames);

package/src/runtime-state-store.ts

@@ -33,6 +33,11 @@ export function stateDirFor(source: ProfileSource, dirs: { agentDir: string; cwd
 export interface RuntimeState {
 	activeProfile?: string;
 	overlay?: RuntimeOverlay;
+	/** Patch-only marker: clears `activeProfile` from the store it is sent
+	 *  to, and to that store alone. A profile switch sends it to the OTHER
+	 *  scope's store, so a stale project selection cannot shadow the new
+	 *  global choice on the next startup. Never stored, never read back. */
+	otherActiveProfile?: undefined;
 }
 
 export interface RuntimeOverlay {
@@ -112,6 +117,7 @@ export class RuntimeStateStore {
 			if (patch.overlay === undefined) delete next.overlay;
 			else next.overlay = patch.overlay;
 		}
+		if ("otherActiveProfile" in patch) delete next.activeProfile;
 		await this.write(next);
 		return next;
 	}

package/src/startup-mcp-scope.ts

@@ -73,14 +73,19 @@ export function resolveProjectTrustedSync(agentDir: string, cwd: string): boolea
 	return readDefaultProjectTrustSync(agentDir) === "always";
 }
 
-/** The saved selection for this run: project state wins over global state
- *  (project state only when trusted), then the built-in default. */
+/** The profile this pass generates the overlay for: this process's already
+ *  applied selection (`continuation`) first — a reload must not regress to
+ *  the `--profile` flag — then the flag, then the saved selection: project
+ *  state wins over global state (project state only when trusted), then the
+ *  built-in default. */
 export function resolveStartupProfileNameSync(input: {
 	agentDir: string;
 	cwd: string;
 	projectTrusted: boolean;
 	argv: readonly string[];
+	continuation?: string;
 }): string {
+	if (input.continuation !== undefined && input.continuation.length > 0) return input.continuation;
 	const requested = readFlagFromArgv(input.argv, "profile");
 	if (requested !== undefined && requested.length > 0) return requested;
 	const project = input.projectTrusted
@@ -97,6 +102,9 @@ export interface McpOverlaySyncInput {
 	projectTrusted?: boolean;
 	/** Effective `--mcp-config`; undefined means the managed overlay path. */
 	overridePath?: string;
+	/** The selection this process already applied: a reload's overlay belongs
+	 *  to it, not to the `--profile` flag. */
+	continuation?: string;
 	/** The command line, for the load pass (Pi applies flag values only after
 	 *  extension loading, so `--profile` is read from here). */
 	argv?: readonly string[];
@@ -126,6 +134,7 @@ export function syncStartupMcpOverlay(
 				cwd: input.cwd,
 				projectTrusted: trust ?? resolveProjectTrustedSync(input.agentDir, input.cwd),
 				argv: input.argv ?? [],
+				...(input.continuation === undefined ? {} : { continuation: input.continuation }),
 			});
 		const refs = input.mcpRefs ?? readProfileMcpRefsSync({ ...input, name: profileName, trust });
 		return writeOverlayForRefs({ ...input, refs });
@@ -228,7 +237,7 @@ function readActiveProfile(statePath: string): string | undefined {
 	return typeof name === "string" && name.length > 0 ? name : undefined;
 }
 
-/** The profile's raw `mcp` references; `"unknown"` when the profile or its
+/** The profile's raw `mcps` references; `"unknown"` when the profile or its
  *  catalog cannot be read (caller falls back to "no filtering"). */
 function readProfileMcpRefsSync(
 	input: McpOverlaySyncInput & { name: string; trust: boolean | undefined },
@@ -241,7 +250,7 @@ function readProfileMcpRefsSync(
 		: new Map<string, ProfileDefinition>();
 	if (global === "error" || project === "error") return "unknown";
 	const definition = project.get(input.name) ?? global.get(input.name);
-	return definition === undefined ? "unknown" : definition.mcp;
+	return definition === undefined ? "unknown" : definition.mcps;
 }
 
 function readCatalogSync(filePath: string): Map<string, ProfileDefinition> | "error" {

package/src/startup-selection.ts

@@ -5,6 +5,12 @@
  *   one-run selection: it is never written back to runtime state.
  * - Without the flag the saved selection applies: the trusted project's
  *   state wins over the global state, then the built-in `default`.
+ * - Every session start after the first continues THIS process's selection
+ *   (`continuation`): the flag is a startup directive, and re-reading it
+ *   after an in-session switch would resurrect the profile the user just
+ *   left. A continuation that no longer resolves falls back like a saved
+ *   selection, with a warning, because a deleted profile must not strand the
+ *   runtime.
  * - A saved selection that no longer resolves falls back to `default` with
  *   a warning — restore is a convenience, not a commitment. An explicit
  *   flag value never falls back: an unknown name is a loud error.
@@ -94,19 +100,70 @@ async function legacyRegistryWarnings(input: {
 	return warnings;
 }
 
-/** Resolves the profile name for this session: explicit flag → trusted
- *  project state → global state → default. Never writes state. */
+/**
+ * The profile this process last applied. Kept on `globalThis` because Pi
+ * re-imports extension modules on every reload (jiti) — module state resets
+ * exactly when it is needed. It is a run-scoped fact, not saved state: the
+ * `--profile` flag must not resurrect itself over an in-session switch when
+ * the MCP overlay change rebuilds the runtime.
+ */
+const RUN_SELECTION_KEY = "pi-profile-switch:applied-profile";
+
+interface RunSelection {
+	appliedProfile?: string;
+}
+
+function runSelection(): RunSelection {
+	const holder = globalThis as unknown as Record<string, RunSelection | undefined>;
+	const current = holder[RUN_SELECTION_KEY] ?? {};
+	holder[RUN_SELECTION_KEY] = current;
+	return current;
+}
+
+/** Records the profile this process applied (startup or in-session).
+ *  `undefined` clears the record; a fresh process starts empty. */
+export function recordAppliedProfile(name: string | undefined): void {
+	runSelection().appliedProfile = name;
+}
+
+/** The profile this process is running, or undefined before the first
+ *  activation. */
+export function appliedProfile(): string | undefined {
+	return runSelection().appliedProfile;
+}
+
+/** Resolves the profile name for this session: the run's current selection
+ *  (`continuation`) → explicit flag → trusted project state → global state →
+ *  default. Never writes state.
+ *
+ *  `requested` is the CLI flag: an unknown name is a loud error.
+ *  `continuation` is what this process already applied, passed on every
+ *  session start after the first: it keeps the in-session switch, and falls
+ *  back (with a warning) when the name no longer resolves. */
 export async function resolveStartupProfile(input: {
 	agentDir: string;
 	cwd: string;
 	projectTrusted: boolean;
 	requested?: string;
+	continuation?: string;
 }): Promise<StartupProfile> {
 	const catalog = await ProfileCatalog.load(input.agentDir, {
 		projectDir: input.projectTrusted ? input.cwd : undefined,
 	});
 	const warnings: string[] = await legacyRegistryWarnings(input);
 
+	// The continuation first: this process already applied it, so the flag
+	// (a startup directive) has had its say.
+	if (input.continuation !== undefined) {
+		if (catalog.resolve(input.continuation) !== undefined) {
+			return { name: input.continuation, warnings };
+		}
+		warnings.push(
+			`profile ${JSON.stringify(input.continuation)} no longer exists — restoring the saved selection; ` +
+				`available: [${catalog.list().map((profile) => profile.name).join(", ")}]`,
+		);
+	}
+
 	if (input.requested !== undefined) {
 		if (catalog.resolve(input.requested) === undefined) {
 			throw new UnknownProfileError(input.requested, catalog.list().map((profile) => profile.name));

package/src/switching/activate-profile.ts

@@ -82,6 +82,18 @@ export async function resolveProfileSelection(
 	return resolveSelection({ profile, overlay, live: deps.live, suppressTools });
 }
 
+/** Drops a stale saved selection from the scope that no longer owns it. A
+ *  project state file left behind by a previous project profile shadows the
+ *  new global choice on the next startup (project state wins), so the switch
+ *  path clears it; the scope's overlay stays, because that belongs to the
+ *  profile it was created for. */
+async function clearOtherSelection(stateDir: string): Promise<void> {
+	const store = new RuntimeStateStore(stateDir);
+	if ((await store.read()).activeProfile !== undefined) {
+		await store.update({ otherActiveProfile: undefined });
+	}
+}
+
 /** Activates a profile: resolve, validate, optionally persist, apply. */
 export async function activateProfile(
 	name: string,
@@ -100,10 +112,27 @@ export async function activateProfile(
 	}
 
 	if (options?.persist !== false) {
-		await new RuntimeStateStore(stateDirFor(selection.source, deps)).update({
-			activeProfile: selection.name,
-			overlay: overlay ?? undefined,
-		});
+		// Exactly one scope holds the saved selection: the project state file
+		// for a project profile, the global one otherwise (including the
+		// built-in `default`). A project profile is only reachable in a
+		// trusted project, so an untrusted project is skipped exactly like
+		// its catalog read — its state file stays untouched (ADR-0007).
+		const ownDir = stateDirFor(selection.source, deps);
+		const projectDir = stateDirFor("project", deps);
+		const writable = selection.source !== "project" || deps.projectTrusted;
+		if (writable) {
+			await new RuntimeStateStore(ownDir).update({
+				activeProfile: selection.name,
+				overlay: overlay ?? undefined,
+			});
+			// The scope that owned the previous selection must let go of it,
+			// or the next startup restores it: project state wins over global.
+			// An untrusted project is never read or written here either.
+			const otherDir = selection.source === "project" ? stateDirFor("global", deps) : projectDir;
+			if (otherDir !== ownDir && (otherDir !== projectDir || deps.projectTrusted)) {
+				await clearOtherSelection(otherDir);
+			}
+		}
 	}
 
 	const result = await applySelection({ selection, surface: deps.surface, preset });

package/src/switching/mcp-toggle.ts

@@ -1,7 +1,7 @@
 /**
  * McpToggle: persistent, profile-scoped `/mcp enable|disable` (ticket 10).
  *
- * The profile's `mcp` array in its OWNING catalog is the profile-scoped
+ * The profile's `mcps` array in its OWNING catalog is the profile-scoped
  * state store (ticket 04 established that pi-mcp-adapter@2.33.0 has no
  * allowlist/profile-state API — ADR-0002's assumed store does not exist;
  * pi-profile-switch owns the contract). The runtime effect is the caller's
@@ -20,7 +20,13 @@
  */
 
 import { discoverAdapterServerNames } from "../mcp-config.ts";
-import { CatalogError, DEFAULT_PROFILE_NAME, type ProfileDefinition, type ProfileSource } from "../profile-catalog.ts";
+import {
+	CatalogError,
+	DEFAULT_PROFILE_NAME,
+	LEGACY_FIELD_ALIASES,
+	type ProfileDefinition,
+	type ProfileSource,
+} from "../profile-catalog.ts";
 import { catalogStore, readCatalogScope, type CatalogScope } from "./profile-crud.ts";
 
 export async function setMcpServerEnabled(
@@ -32,7 +38,7 @@ export async function setMcpServerEnabled(
 	},
 	server: string,
 	enabled: boolean,
-): Promise<{ mcp: string[]; changed: boolean }> {
+): Promise<{ mcps: string[]; changed: boolean }> {
 	const { name, source } = input.profile;
 	if (name === DEFAULT_PROFILE_NAME || source === "builtin") {
 		throw new CatalogError(
@@ -60,16 +66,18 @@ export async function setMcpServerEnabled(
 		throw new CatalogError(`profile "${input.profile.name}" not found in the ${scope} catalog`);
 	}
 
-	const current = definition.mcp ?? [];
+	const current = definition.mcps ?? [];
 	if (enabled === current.includes(server)) {
-		return { mcp: current, changed: false }; // already in the requested state
+		return { mcps: current, changed: false }; // already in the requested state
 	}
 	const next = enabled ? [...current, server] : current.filter((name) => name !== server);
 	// Drop the key entirely when empty (exactOptionalPropertyTypes; a
-	// written `mcp: undefined` would also misrepresent the definition).
+	// written `mcps: undefined` would also misrepresent the definition) and
+	// drop the legacy alias, so one save migrates the file to `mcps`.
 	const rest = { ...definition };
-	delete rest.mcp;
-	const updated: ProfileDefinition = next.length > 0 ? { ...rest, mcp: next } : rest;
+	delete rest.mcps;
+	const updated: ProfileDefinition = next.length > 0 ? { ...rest, mcps: next } : rest;
+	delete (updated as Record<string, unknown>)[LEGACY_FIELD_ALIASES.mcps];
 	await catalogStore(input, scope).upsert(input.profile.name, updated);
-	return { mcp: next, changed: true };
+	return { mcps: next, changed: true };
 }

package/src/switching/profile-wizard.ts

@@ -75,7 +75,7 @@ async function captureDefinition(
 
 	const listFields = [
 		["skills", "skills (comma-separated names or globs, empty = all visible)"],
-		["mcp", "mcp servers (names or globs, empty = none)"],
+		["mcps", "MCP servers (names or globs, empty = none)"],
 		["tools", "tools (names or globs, empty = pi default set)"],
 	] as const;
 	for (const [field, prompt] of listFields) {