pi-profile-switch 0.2.0 → 0.3.0

package/README.md

@@ -29,30 +29,11 @@ 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:
-
-```json
-{
-  "schemaVersion": 1,
-  "profiles": {
-    "read-only": {
-      "label": "Read-only",
-      "description": "Read-only session; no skills or MCP servers assumed — add your own.",
-      "tools": [
-        "read",
-        "grep",
-        "find",
-        "ls"
-      ],
-      "instructions": "Read-only session: inspect and report; never create, edit, rename, or delete files.\nIf a change is needed, describe it in your reply instead of applying it.\nDo not run commands that modify state (installs, formatters, commits, pushes, network writes).\nPrefer an available skill or MCP tool when it fits the request; otherwise use the tools you have.\nGround claims in evidence: cite file:line and separate verified facts from inferences.\nReply in English."
-    }
-  }
-}
-```
+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 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.json`](examples/profiles.json) is that same preset as a catalog; the field reference is [`schemas/profiles.schema.json`](schemas/profiles.schema.json).
+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.
 
-`schemaVersion` is 1. A profile cannot select extensions: they load natively in every profile, so manage them with `pi install`.
+`schemaVersion` is 1 and is the only accepted value. A profile cannot select extensions: they load natively in every profile, so manage them with `pi install`.
 
 ## What a profile controls
 
@@ -61,7 +42,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` | Runtime server allowlist published to `pi-mcp-adapter`; connection details stay in the adapter's own config |
+| `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 |
 | `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.
@@ -74,7 +55,7 @@ In the TUI, the `/profile` command family manages everything in-session:
 | --- | --- |
 | `/profile` | Interactive profile picker |
 | `/profile list` / `/profile status` | Show profiles / active profile details |
-| `/profile use <name>` | Switch instantly — same session, no reload |
+| `/profile use <name>` | Switch in place — same session; when the MCP selection changes, the runtime reloads automatically to re-apply it |
 | `/profile create\|edit\|delete\|duplicate` | Guided profile CRUD (TUI only) |
 | `/profile customize` / `/profile reset` | Narrow the active profile for this session only |
 | `/mcp enable\|disable <server>` | Toggle MCP servers in the active profile |
@@ -88,12 +69,11 @@ 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 reload** — switching re-applies runtime state in place; the next turn's prompt carries the new selection.
+- **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.
 
 ## Docs
 
 - [Architecture](docs/architecture/overview.md) · [ADRs](docs/adr/) · [Glossary](CONTEXT.md) (Chinese)
-- JSON Schema: [`schemas/profiles.schema.json`](schemas/profiles.schema.json)
 
 ## License
 

package/README.zh-CN.md

@@ -29,30 +29,11 @@ pi --profile read-only
 pi --profile default
 ```
 
-用 `/profile create` 创建 profile，写入 `~/.pi/agent/profiles.json`（全局）或 `<项目>/.pi/profiles.json`（项目级，仅限已信任项目）。向导提供随包的 `read-only` 预设——只用 Pi 内建工具，不假设任何 skill、MCP server 或模型——也可以从空定义开始：
-
-```json
-{
-  "schemaVersion": 1,
-  "profiles": {
-    "read-only": {
-      "label": "Read-only",
-      "description": "Read-only session; no skills or MCP servers assumed — add your own.",
-      "tools": [
-        "read",
-        "grep",
-        "find",
-        "ls"
-      ],
-      "instructions": "Read-only session: inspect and report; never create, edit, rename, or delete files.\nIf a change is needed, describe it in your reply instead of applying it.\nDo not run commands that modify state (installs, formatters, commits, pushes, network writes).\nPrefer an available skill or MCP tool when it fits the request; otherwise use the tools you have.\nGround claims in evidence: cite file:line and separate verified facts from inferences.\nReply in English."
-    }
-  }
-}
-```
+用 `/profile create` 创建 profile，写入 `~/.pi/agent/profiles.json`（全局）或 `<项目>/.pi/profiles.json`（项目级，仅限已信任项目）。向导提供随包的 `read-only` 预设——只用 Pi 内建工具，不假设任何 skill、MCP server 或模型——也可以从空定义开始。
 
-预设只被复制一次：它不被跟踪，包升级不会改动你已经创建的 profile。Profile 只**引用**资源，从不复制资源。[`examples/profiles.json`](examples/profiles.json) 就是同一个预设构成的 catalog；字段参考见 [`schemas/profiles.schema.json`](schemas/profiles.schema.json)。
+预设只被复制一次：它不被跟踪，包升级不会改动你已经创建的 profile。Profile 只**引用**资源，从不复制资源。[`examples/profiles.example.json`](examples/profiles.example.json) 是覆盖全部字段的完整 catalog，示例中的资源名请替换成你本机已有的名字。
 
-`schemaVersion` 为 1。Profile 不选择 extension：extensions 在所有 profile 中原生加载，请用 `pi install` 管理。
+`schemaVersion` 为 1，也是唯一接受的值。Profile 不选择 extension：extensions 在所有 profile 中原生加载，请用 `pi install` 管理。
 
 ## Profile 控制的范围
 
@@ -61,7 +42,7 @@ pi --profile default
 | `instructions` | 每个 turn 追加到 system prompt 末尾 |
 | `model` | 会话启动的模型预设；显式 `--model`/`--thinking` 或 session 历史中记录的模型优先 |
 | `skills` | 模型在 prompt skills 列表中看到的内容；所有已安装 skill 仍保持加载，用户可用 `/skill:name` 手动调用 |
-| `mcp` | 发布给 `pi-mcp-adapter` 的运行时 server allowlist；连接参数仍由 adapter 自己管理 |
+| `mcp` | 本次会话暴露哪些 MCP server：白名单写入 adapter 自己的配置（`~/.pi/agent/mcp.json`），其余 server 一律标为 disabled。你原本放在该文件里的 server 会迁移到 `mcp.user.json`；连接参数只在你自己的配置里，从不进入 profile |
 | `tools` | 活动工具集：声明的名字/glob 成为活动集合；之后才注册的工具（MCP、扩展）在出现时补上 |
 
 未声明的字段保持 Pi 原生行为，`default` 什么都不声明。
@@ -74,7 +55,7 @@ pi --profile default
 | --- | --- |
 | `/profile` | 交互式选择 profile |
 | `/profile list` / `/profile status` | 列出 profile / 查看活动 profile 详情 |
-| `/profile use <name>` | 即时切换——同一 session，无 reload |
+| `/profile use <name>` | 原位切换——同一 session；当 MCP 选择发生变化时会自动 reload 以重新应用 |
 | `/profile create\|edit\|delete\|duplicate` | 向导式 profile 增删改（仅 TUI） |
 | `/profile customize` / `/profile reset` | 仅本次会话收窄活动 profile |
 | `/mcp enable\|disable <server>` | 在活动 profile 中开关 MCP server |
@@ -88,12 +69,11 @@ pi --profile default
 - **引用而非复制**——profile 指向你自己拥有和维护的资源。
 - **Pi 原生**——配置目录就是 Pi 自己的目录，session、扩展配置、packages、context 文件和信任行为与原生 Pi 完全一致。
 - **失败安全**——未信任的项目目录从不读取；激活失败时不应用任何设置并报出原因。
-- **无 reload**——切换在原位重新应用运行时状态；下一个 turn 的 prompt 直接带上新选择。
+- **无需手动 reload**——切换在原位重新应用运行时状态，下一个 turn 的 prompt 直接带上新选择；只有 MCP 选择变化时才会自动重建运行时（同一 session）
 
 ## 文档
 
 - [架构设计](docs/architecture/overview.md) · [ADR](docs/adr/) · [术语表](CONTEXT.md)
-- JSON Schema：[`schemas/profiles.schema.json`](schemas/profiles.schema.json)
 
 ## 许可证
 

package/examples/profiles.example.json

@@ -0,0 +1,74 @@
+{
+  "schemaVersion": 1,
+  "profiles": {
+    "read-only": {
+      "label": "Read-only",
+      "description": "Read-only session; no skills or MCP servers assumed — add your own.",
+      "tools": [
+        "read",
+        "grep",
+        "find",
+        "ls"
+      ],
+      "instructions": "Read-only session: inspect and report; never create, edit, rename, or delete files.\nIf a change is needed, describe it in your reply instead of applying it.\nDo not run commands that modify state (installs, formatters, commits, pushes, network writes).\nPrefer an available skill or MCP tool when it fits the request; otherwise use the tools you have.\nGround claims in evidence: cite file:line and separate verified facts from inferences.\nReply in English."
+    },
+    "review": {
+      "label": "Code review",
+      "description": "Review a diff or a branch: read the change, report findings, modify nothing.",
+      "skills": [
+        "code-review",
+        "git-*"
+      ],
+      "mcp": [
+        "github"
+      ],
+      "tools": [
+        "read",
+        "grep",
+        "find",
+        "ls",
+        "bash"
+      ],
+      "model": {
+        "provider": "anthropic",
+        "id": "claude-sonnet-4-5",
+        "thinkingLevel": "high"
+      },
+      "instructions": "Review only: read the change under review, then report findings with file:line evidence.\nNever edit tracked files, commit, or push; describe the required fix instead.\nSeparate verified behavior from suspected issues."
+    },
+    "plan": {
+      "label": "Plan",
+      "description": "Research a change and write the plan; no edits, no implementation.",
+      "skills": [],
+      "tools": [
+        "read",
+        "grep",
+        "find",
+        "ls",
+        "bash"
+      ],
+      "instructions": "Planning session: research the code first, then write the plan in your reply.\nDo not create, edit, rename, or delete files."
+    },
+    "implement": {
+      "label": "Implement",
+      "description": "Full tool access for implementing a change end to end.",
+      "skills": [
+        "git-commit",
+        "test-*"
+      ],
+      "mcp": [
+        "github"
+      ],
+      "tools": [
+        "read",
+        "grep",
+        "find",
+        "ls",
+        "bash",
+        "edit",
+        "write"
+      ],
+      "instructions": "Implement the requested change: read before writing, keep the diff minimal.\nRun the tests that cover your change and report the exact commands."
+    }
+  }
+}

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

@@ -6,6 +6,7 @@ import {
 	type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 
+import { adapterPresent } from "../../src/adapter-presence.ts";
 import { discoverAdapterServerNames } from "../../src/mcp-config.ts";
 import { probeAdapterPresence } from "../../src/mcp-coordination.ts";
 import { readSessionChoices } from "../../src/model-selection.ts";
@@ -30,6 +31,11 @@ import {
 	registerProfileFlag,
 	resolveStartupProfile,
 } from "../../src/startup-selection.ts";
+import {
+	readFlagFromArgv,
+	syncMcpOverlayForSelection,
+	syncStartupMcpOverlay,
+} from "../../src/startup-mcp-scope.ts";
 import { retryPendingTools, type ApplySurface } from "../../src/switching/apply-profile.ts";
 import {
 	activateProfile,
@@ -115,7 +121,27 @@ const PROFILE_USAGE = [
 
 export default function piProfileExtension(pi: ExtensionAPI): void {
 	registerProfileFlag(pi);
-	const explicit = detectExplicitDeclarations(process.argv.slice(2));
+	const argv = process.argv.slice(2);
+	const explicit = detectExplicitDeclarations(argv);
+	// 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,
+		probeAnswered: probeAdapterPresence(pi.events),
+	});
+	if (adapterInstalled) {
+		const requestedConfigPath = readFlagFromArgv(argv, "mcp-config");
+		syncStartupMcpOverlay({
+			agentDir: loadAgentDir,
+			cwd: process.cwd(),
+			argv,
+			...(requestedConfigPath === undefined ? {} : { overridePath: requestedConfigPath }),
+		});
+	}
 	let current: Activation | undefined;
 	let filterWarningShown = false;
 	/** The last badge written to the footer, so a refresh only talks to Pi
@@ -239,6 +265,75 @@ export default function piProfileExtension(pi: ExtensionAPI): void {
 		});
 	}
 
+	/** `session_start` re-check. The load-time pass cannot know an interactive
+	 *  trust answer, and the adapter has already read its config by now — so a
+	 *  difference is written for the next reload and reported instead. */
+	function reportMcpOverlayState(
+		ctx: ExtensionContext,
+		profileName: string,
+		selection: ResolvedSelection,
+		input: { agentDir: string; cwd: string; projectTrusted: boolean },
+	): void {
+		const configOverride = readFlagFromArgv(argv, "mcp-config");
+		const sync = syncStartupMcpOverlay({
+			agentDir: input.agentDir,
+			cwd: input.cwd,
+			projectTrusted: input.projectTrusted,
+			profileName,
+			argv,
+			...(configOverride === undefined ? {} : { overridePath: configOverride }),
+		});
+		if (sync.error !== undefined) {
+			notify(ctx, `pi-profile-switch: MCP overlay unavailable — ${sync.error}`, "warning");
+			return;
+		}
+		if (!sync.managed) {
+			if (selection.mcp !== undefined) {
+				notify(
+					ctx,
+					`pi-profile-switch: --mcp-config points at another file — profile "${profileName}" cannot filter MCP servers`,
+					"warning",
+				);
+			}
+			return;
+		}
+		if (!sync.changed) return;
+		notify(ctx, `pi-profile-switch: MCP config updated for profile "${profileName}" — run /reload to apply`, "warning");
+	}
+
+	/** Repoints the adapter at the overlay for a just-activated selection and
+	 *  rebuilds the runtime when the MCP surface actually moved. Must be the
+	 *  caller's LAST use of `ctx`: `reload()` invalidates the old context. */
+	async function reloadForMcpOverlay(ctx: ExtensionCommandContext, selection: ResolvedSelection): Promise<void> {
+		if (!adapterInstalled) return;
+		const configOverride = readFlagFromArgv(argv, "mcp-config");
+		const sync = syncMcpOverlayForSelection({
+			agentDir: getAgentDir(),
+			cwd: ctx.cwd,
+			projectTrusted: ctx.isProjectTrusted(),
+			allowed: selection.mcp === undefined ? "all" : selection.mcp,
+			...(configOverride === undefined ? {} : { overridePath: configOverride }),
+		});
+		if (sync.error !== undefined) {
+			notify(ctx, `pi-profile-switch: MCP overlay not updated — ${sync.error}`, "warning");
+			return;
+		}
+		if (!sync.managed) {
+			if (selection.mcp !== undefined) {
+				notify(
+					ctx,
+					`pi-profile-switch: --mcp-config points at another file — profile "${selection.name}" cannot filter MCP servers`,
+					"warning",
+				);
+			}
+			return;
+		}
+		if (!sync.changed) return;
+		notify(ctx, `profile "${selection.name}": MCP servers updated — reloading runtime`, "info");
+		await ctx.waitForIdle();
+		await ctx.reload();
+	}
+
 	/** Bare `/profile`: the interactive picker, with a list fallback for
 	 *  modes without dialogs. */
 	async function runPicker(ctx: ExtensionCommandContext, entries: ProfileListEntry[]): Promise<void> {
@@ -258,6 +353,7 @@ export default function piProfileExtension(pi: ExtensionAPI): void {
 		if (chosen === undefined || chosen.name === current?.selection.name) return;
 		const result = await activate(ctx, chosen.name, { force: true, overlay: null, persist: true });
 		notify(ctx, `profile active: ${result.selection.name}`, "info");
+		await reloadForMcpOverlay(ctx, result.selection);
 	}
 
 	/** `/profile create|duplicate|edit|delete`: TUI-only catalog CRUD. */
@@ -319,8 +415,9 @@ export default function piProfileExtension(pi: ExtensionAPI): void {
 			if (wizard === undefined) return;
 			await editProfile(scopeInput, wizard.scope, wizard.name, wizard.definition);
 			if (current !== undefined && name === current.selection.name) {
-				await activate(ctx, name, { persist: true });
+				const reactivated = await activate(ctx, name, { persist: true });
 				notify(ctx, `saved and reactivated profile "${name}"`, "info");
+				await reloadForMcpOverlay(ctx, reactivated.selection);
 			} else {
 				notify(ctx, `saved profile "${name}" (inactive — runtime untouched)`, "info");
 			}
@@ -358,6 +455,7 @@ export default function piProfileExtension(pi: ExtensionAPI): void {
 		if (isActive) {
 			const result = await activate(ctx, replacement ?? name, { force: replacement !== undefined, persist: true });
 			notify(ctx, `deleted "${name}" (${scope}); profile active: ${result.selection.name}`, "info");
+			await reloadForMcpOverlay(ctx, result.selection);
 		} else {
 			notify(ctx, `deleted profile "${name}" (${scope})`, "info");
 		}
@@ -384,8 +482,15 @@ export default function piProfileExtension(pi: ExtensionAPI): void {
 		try {
 			// Startup activation never persists (a `--profile` selection is for
 			// this run only) and never applies a stored overlay.
-			await activate(ctx, startup.name, { persist: false, overlay: null });
+			const activated = await activate(ctx, startup.name, { persist: false, overlay: null });
 			reportWarnings(ctx, startup.warnings);
+			if (adapterInstalled) {
+				reportMcpOverlayState(ctx, startup.name, activated.selection, {
+					agentDir,
+					cwd: ctx.cwd,
+					projectTrusted,
+				});
+			}
 		} catch (error) {
 			notify(ctx, error instanceof Error ? error.message : String(error), "error");
 			reportWarnings(ctx, startup.warnings);
@@ -498,6 +603,7 @@ export default function piProfileExtension(pi: ExtensionAPI): void {
 					case "use": {
 						const result = await activate(ctx, rest[0] as string, { force: true, overlay: null, persist: true });
 						notify(ctx, `profile active: ${result.selection.name}`, "info");
+						await reloadForMcpOverlay(ctx, result.selection);
 						return;
 					}
 					case "customize": {
@@ -578,12 +684,13 @@ export default function piProfileExtension(pi: ExtensionAPI): void {
 				// catalog; the stored overlay is preserved.
 				const overlay = (await new RuntimeStateStore(stateDirFor(profile.source, { agentDir, cwd: ctx.cwd })).read())
 					.overlay;
-				await activate(ctx, profile.name, { overlay: overlay ?? null, persist: true });
+				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(", ")}])`,
 					"info",
 				);
+				await reloadForMcpOverlay(ctx, reactivated.selection);
 			} catch (error) {
 				notify(ctx, error instanceof Error ? error.message : String(error), "error");
 			}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-profile-switch",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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

@@ -10,8 +10,8 @@
   "additionalProperties": false,
   "properties": {
     "schemaVersion": {
-      "description": "1 is current. 2 is the number v0.1.0 wrote for the same field shape and still reads; saves always write 1.",
-      "enum": [1, 2]
+      "description": "Catalog format version. Only 1 is accepted.",
+      "const": 1
     },
     "profiles": {
       "type": "object",
@@ -44,13 +44,6 @@
           },
           "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."
         },
-        "extensions": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Ignored. Extensions always load natively (ADR-0007) and are managed with pi install; the field is accepted so existing catalogs keep validating."
-        },
         "mcp": {
           "type": "array",
           "items": {

package/src/adapter-presence.ts

@@ -0,0 +1,75 @@
+/**
+ * AdapterPresence: a cheap, deterministic "is pi-mcp-adapter installed?"
+ * check that does not depend on extension load order.
+ *
+ * The overlay mechanism only exists to serve the adapter; when the adapter is
+ * absent the extension must not register the `mcp-config` flag default and
+ * must not write anything. Signals, in order of reliability:
+ *
+ * 1. Pi's npm package root (`<agentDir>/npm/node_modules/pi-mcp-adapter`).
+ * 2. The command line (`-e <path>` / `--extension <path>`).
+ * 3. Pi settings `packages` entries.
+ * 4. The adapter's own event-bus presence probe, when it answered during
+ *    extension loading (only reliable when the adapter loaded first).
+ *
+ * Any failure reads as "absent": a false negative only disables the overlay,
+ * while a false positive could hide the user's own Pi-global slot file.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+import { isRecord } from "./json-file.ts";
+
+const ADAPTER_PACKAGE = "pi-mcp-adapter";
+
+export interface AdapterPresenceInput {
+	agentDir: string;
+	argv: readonly string[];
+	/** Result of the adapter's event-bus probe, when the caller ran one. */
+	probeAnswered?: boolean;
+}
+
+export function adapterPresent(input: AdapterPresenceInput): boolean {
+	if (input.probeAnswered === true) return true;
+	try {
+		for (const candidate of [
+			path.join(input.agentDir, "npm", "node_modules", ADAPTER_PACKAGE),
+			path.join(input.agentDir, "node_modules", ADAPTER_PACKAGE),
+		]) {
+			if (existsSync(candidate)) return true;
+		}
+		return argvMentionsAdapter(input.argv) || settingsListAdapter(input.agentDir);
+	} catch {
+		return false;
+	}
+}
+
+function argvMentionsAdapter(argv: readonly string[]): boolean {
+	for (let index = 0; index < argv.length; index++) {
+		const token = argv[index] ?? "";
+		if (token.includes(ADAPTER_PACKAGE)) return true;
+		if ((token === "-e" || token === "--extension") && (argv[index + 1] ?? "").includes(ADAPTER_PACKAGE)) {
+			return true;
+		}
+	}
+	return false;
+}
+
+function settingsListAdapter(agentDir: string): boolean {
+	try {
+		const raw: unknown = JSON.parse(readFileSync(path.join(agentDir, "settings.json"), "utf8"));
+		if (!isRecord(raw) || !Array.isArray(raw.packages)) return false;
+		return raw.packages.some((entry) => {
+			const source =
+				typeof entry === "string"
+					? entry
+					: isRecord(entry) && typeof entry.source === "string"
+						? entry.source
+						: undefined;
+			return source !== undefined && source.includes(ADAPTER_PACKAGE);
+		});
+	} catch {
+		return false;
+	}
+}

package/src/json-file.ts

@@ -5,6 +5,7 @@
  * fallback); this helper only classifies the outcome.
  */
 
+import { readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 
 export type JsonFileResult =
@@ -30,6 +31,25 @@ 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/mcp-config.ts

@@ -1,23 +1,32 @@
 /**
- * AdapterConfigDiscovery: reads the MCP server NAMES pi-mcp-adapter would
- * discover from its pi-native config files, without ever managing them.
+ * AdapterConfigDiscovery: reads what pi-mcp-adapter would load from its
+ * pi-native FILE sources — server names for reference validation, and the
+ * "Pi global override" slot document for the generated overlay.
  *
- * pi-profile-switch never stores MCP connection parameters or credentials
- * (ADR-0002); this module reads only the `mcpServers` key names so an
- * activation can validate a profile's `mcp` references before applying it.
+ * Discovery mirrors the adapter's own source order (later sources override
+ * earlier ones): shared global MCP config, the two `.agents` globals, the Pi
+ * global override slot (`--mcp-config`, else `<agentDir>/mcp.json`), then the
+ * project's `.mcp.json` and `.pi/mcp.json` (project sources only when Pi
+ * reports the project trusted — an untrusted project's config is never read).
  *
- * Discovery scope (documented limitation): the pi-native files only — the
- * global `<agentDir>/mcp.json` and, when trusted, the project's
- * `.pi/mcp.json`. Servers defined solely in the adapter's editor-specific
- * legacy locations (~/.claude/mcp.json et al.) are invisible here; profiles
- * referencing them fail activation validation. The pi-native files are the
- * adapter's documented default, so keep configs there.
+ * Not covered (documented limitation): the adapter's opt-in host discovery
+ * (`~/.claude.json`, `~/.cursor/mcp.json`, …), package manifests (`pi.mcp`)
+ * and agent/Claude plugin sources. Their servers are namespaced and cannot be
+ * referenced by a profile today; the overlay still disables them when a name
+ * happens to match one it knows.
+ *
+ * pi-profile-switch never writes these files and never exposes connection
+ * parameters; the slot document is read only to be carried into the generated
+ * overlay, because that file replaces the slot.
  *
  * Malformed config files fail loudly — a broken mcp.json must not silently
  * read as "no servers" and reject every reference.
  */
 
-import { isRecord, readJsonFile } from "./json-file.ts";
+import { homedir } from "node:os";
+import path from "node:path";
+
+import { isRecord, readJsonFileSync } from "./json-file.ts";
 
 export class McpConfigError extends Error {
 	readonly filePath: string;
@@ -29,35 +38,145 @@ export class McpConfigError extends Error {
 	}
 }
 
-async function readServerNames(filePath: string): Promise<string[]> {
-	const result = await readJsonFile(filePath);
-	if (!result.ok) {
-		if (result.reason === "missing") {
-			return [];
+export interface AdapterMcpSource {
+	label: string;
+	filePath: string;
+	scope: "global" | "project";
+	/** True for the slot `--mcp-config` replaces. */
+	slot: boolean;
+}
+
+export interface AdapterMcpDiscoveryInput {
+	agentDir: string;
+	cwd: string;
+	projectTrusted: boolean;
+	/** The effective `--mcp-config` value, when one is in play. */
+	overridePath?: string;
+	/** Home directory override; tests point this at their fixture. */
+	homeDir?: string;
+}
+
+/** The adapter's file sources, in its own precedence order. Paths are
+ *  de-duplicated: the adapter skips a source whose read path equals the slot. */
+export function adapterMcpSources(input: AdapterMcpDiscoveryInput): AdapterMcpSource[] {
+	const home = input.homeDir ?? homedir();
+	const slotPath = path.resolve(input.overridePath ?? path.join(input.agentDir, "mcp.json"));
+	const candidates: AdapterMcpSource[] = [
+		{ label: "shared global MCP config", filePath: path.join(home, ".config", "mcp", "mcp.json"), scope: "global", slot: false },
+		{ label: ".agents MCP config", filePath: path.join(home, ".agents", "mcp.json"), scope: "global", slot: false },
+		{ label: ".agents/mcp MCP config", filePath: path.join(home, ".agents", "mcp", "mcp.json"), scope: "global", slot: false },
+		{ label: "Pi global MCP override", filePath: slotPath, scope: "global", slot: true },
+	];
+	if (input.projectTrusted) {
+		candidates.push(
+			{ label: "project MCP config", filePath: path.resolve(input.cwd, ".mcp.json"), scope: "project", slot: false },
+			{ label: "project Pi MCP override", filePath: path.resolve(input.cwd, ".pi", "mcp.json"), scope: "project", slot: false },
+		);
+	}
+	const seen = new Set<string>();
+	return candidates.filter((source) => {
+		if (source.slot) return true; // the slot is always the read path
+		if (seen.has(source.filePath)) return false;
+		seen.add(source.filePath);
+		return true;
+	});
+}
+
+export interface AdapterMcpView {
+	/** Read path of the slot `--mcp-config` replaces. */
+	slotPath: string;
+	/** Parsed slot document (verbatim), when the file exists. */
+	slotDocument?: Record<string, unknown>;
+	slotNames: string[];
+	/** Server names from the other file sources. */
+	otherNames: string[];
+	/** Union of slot and other names, sorted. */
+	serverNames: string[];
+}
+
+/** Synchronous read: the extension-load pass must finish before the adapter's
+ *  session initialization, and the files are tiny. */
+export function readAdapterMcpViewSync(input: AdapterMcpDiscoveryInput): AdapterMcpView {
+	const sources = adapterMcpSources(input);
+	const slot = sources.find((source) => source.slot);
+	const slotPath = slot?.filePath ?? path.join(input.agentDir, "mcp.json");
+	let slotDocument: Record<string, unknown> | undefined;
+	const slotNames: string[] = [];
+	const otherNames = new Set<string>();
+	for (const source of sources) {
+		if (source.slot) {
+			const document = readMcpDocumentSync(source.filePath);
+			if (document === undefined) continue;
+			slotDocument = document;
+			slotNames.push(...serverNames(document, source.filePath));
+			continue;
 		}
+		const document = readMcpDocumentSync(source.filePath);
+		if (document === undefined) continue;
+		for (const name of serverNames(document, source.filePath)) otherNames.add(name);
+	}
+	for (const name of slotNames) otherNames.delete(name);
+	return {
+		slotPath,
+		...(slotDocument === undefined ? {} : { slotDocument }),
+		slotNames,
+		otherNames: [...otherNames].sort(),
+		serverNames: [...new Set([...slotNames, ...otherNames])].sort(),
+	};
+}
+
+/** Async twin for the runtime paths (selection, status, toggles). */
+export async function readAdapterMcpView(input: AdapterMcpDiscoveryInput): Promise<AdapterMcpView> {
+	return readAdapterMcpViewSync(input);
+}
+
+/** Server names from every source EXCEPT the slot file. The slot is generated
+ *  by pi-profile-switch, so it must not feed back into the next generation —
+ *  otherwise a stub would look like a source server and vanish on the next
+ *  write. */
+export function readAdapterOtherServerNamesSync(input: AdapterMcpDiscoveryInput): string[] {
+	const names = new Set<string>();
+	for (const source of adapterMcpSources(input)) {
+		if (source.slot) continue;
+		const document = readMcpDocumentSync(source.filePath);
+		if (document === undefined) continue;
+		for (const name of serverNames(document, source.filePath)) names.add(name);
+	}
+	return [...names].sort();
+}
+
+/** Server names the adapter would discover. `projectDir` is passed only when
+ *  the trust check passed. */
+export async function discoverAdapterServerNames(
+	agentDir: string,
+	projectDir?: string,
+	homeDir?: string,
+): Promise<string[]> {
+	return readAdapterMcpViewSync({
+		agentDir,
+		cwd: projectDir ?? process.cwd(),
+		projectTrusted: projectDir !== undefined,
+		...(homeDir === undefined ? {} : { homeDir }),
+	}).serverNames;
+}
+
+/** Missing file → undefined; malformed → McpConfigError. */
+export function readMcpDocumentSync(filePath: string): Record<string, unknown> | undefined {
+	const result = readJsonFileSync(filePath);
+	if (!result.ok) {
+		if (result.reason === "missing") return undefined;
 		throw new McpConfigError(`MCP config is not valid JSON: ${filePath}`, filePath);
 	}
 	if (!isRecord(result.value)) {
 		throw new McpConfigError(`MCP config must be a JSON object: ${filePath}`, filePath);
 	}
-	if (result.value.mcpServers === undefined) {
-		return [];
-	}
-	if (!isRecord(result.value.mcpServers)) {
-		throw new McpConfigError(`"mcpServers" must be a JSON object: ${filePath}`, filePath);
-	}
-	return Object.keys(result.value.mcpServers);
+	return result.value;
 }
 
-/** Server names the adapter would discover: global agentDir config plus the
- *  trusted project's config. Pass `projectDir` only when the trust check
- *  passed — an untrusted project's config is never read. */
-export async function discoverAdapterServerNames(agentDir: string, projectDir?: string): Promise<string[]> {
-	const names = new Set(await readServerNames(`${agentDir}/mcp.json`));
-	if (projectDir !== undefined) {
-		for (const name of await readServerNames(`${projectDir}/.pi/mcp.json`)) {
-			names.add(name);
-		}
+function serverNames(document: Record<string, unknown>, filePath: string): string[] {
+	if (document.mcpServers === undefined) return [];
+	if (!isRecord(document.mcpServers)) {
+		throw new McpConfigError(`"mcpServers" must be a JSON object: ${filePath}`, filePath);
 	}
-	return [...names].sort();
+	return Object.keys(document.mcpServers);
 }

package/src/mcp-overlay-file.ts

@@ -0,0 +1,35 @@
+/**
+ * McpOverlayFile: the only writer of the generated MCP overlay.
+ *
+ * Invariants:
+ * - Atomic (temporary file + rename) so a reader never sees a half-written
+ *   document.
+ * - Written only when the bytes change: a profile switch that does not move
+ *   the MCP selection produces no write and therefore no reload.
+ * - Mode 0600: the overlay carries the Pi-global slot's definitions verbatim
+ *   when the user keeps servers there, and those definitions may embed
+ *   credentials even though the overlay itself never introduces any.
+ */
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+/** Current bytes, or undefined when the file is missing/unreadable. */
+export function readMcpOverlaySync(overlayPath: string): string | undefined {
+	try {
+		return readFileSync(overlayPath, "utf8");
+	} catch {
+		return undefined;
+	}
+}
+
+/** Writes `content` when it differs from what is on disk. Returns true when
+ *  the file changed. */
+export function writeMcpOverlayIfChangedSync(overlayPath: string, content: string): boolean {
+	if (readMcpOverlaySync(overlayPath) === content) return false;
+	mkdirSync(path.dirname(overlayPath), { recursive: true });
+	const temporary = `${overlayPath}.tmp-${process.pid}`;
+	writeFileSync(temporary, content, { mode: 0o600 });
+	renameSync(temporary, overlayPath);
+	return true;
+}

package/src/mcp-overlay.ts

@@ -0,0 +1,122 @@
+/**
+ * McpOverlay: the PURE half of the profile-scoped MCP filter.
+ *
+ * `pi-mcp-adapter` has no runtime allowlist channel (ADR-0002 amendment), so
+ * the profile's `mcp` declaration is enforced by a generated config file the
+ * adapter reads as its "Pi global override" slot (the slot `--mcp-config`
+ * replaces). The file is a DISABLE OVERLAY: entries carry no connection
+ * parameters and no credentials — `{ "<server>": { "disabled": true } }` is
+ * the adapter's own idiom for `/mcp disable`, and its config merge is
+ * per-field, so a stub merges onto the definition owned by the user's own
+ * file.
+ *
+ * One exception is structural: because the overlay file REPLACES the Pi
+ * global slot, the servers the user keeps in that slot are carried over
+ * verbatim from the sidecar (`mcp.user.json`); a hand-written slot file is
+ * adopted into the sidecar before the first overwrite.
+ *
+ * `allowed` semantics:
+ * - `"all"` — the profile declares no `mcp`: nothing is disabled.
+ * - `[]` — every discovered server is disabled.
+ * - `["github", …]` — everything outside the list is disabled.
+ */
+
+import path from "node:path";
+
+import { isRecord } from "./json-file.ts";
+import { matchesReference } from "./name-matching.ts";
+
+/**
+ * The generated overlay REPLACES the adapter's Pi-global slot, so it lives at
+ * the slot's default path. The user's own Pi-global servers move to a sidecar
+ * that this package never writes except when adopting a hand-written slot.
+ */
+export const MCP_SLOT_FILE_NAME = "mcp.json";
+export const MCP_SOURCE_FILE_NAME = "mcp.user.json";
+/** Top-level key marking a file as generated. The adapter ignores unknown
+ *  top-level keys, so the marker never reaches it as configuration. */
+export const MCP_GENERATED_MARKER = "piProfileSwitch";
+
+/** The adapter's Pi-global slot: the generated overlay. */
+export function mcpSlotPath(agentDir: string): string {
+	return path.join(agentDir, MCP_SLOT_FILE_NAME);
+}
+
+/** The user-owned sidecar holding the Pi-global servers verbatim. */
+export function mcpSourcePath(agentDir: string): string {
+	return path.join(agentDir, MCP_SOURCE_FILE_NAME);
+}
+
+/** True when the document was produced by pi-profile-switch. */
+export function isGeneratedOverlay(value: unknown): boolean {
+	if (!isRecord(value)) return false;
+	const marker = value[MCP_GENERATED_MARKER];
+	return isRecord(marker) && marker.generated === true;
+}
+
+/** True for the credential-free stubs the overlay adds for servers defined in
+ *  the adapter's other sources. */
+export function isDisabledStub(value: unknown): boolean {
+	return isRecord(value) && Object.keys(value).length === 1 && value.disabled === true;
+}
+
+/** Server names a profile's `mcp` references resolve to. `undefined` (the
+ *  profile declares nothing) means "no filtering" and is reported as the
+ *  literal `"all"`. Glob references follow the same rules as every other
+ *  profile reference. */
+export function resolveAllowedServers(
+	refs: readonly string[] | undefined,
+	discovered: readonly string[],
+): readonly string[] | "all" {
+	if (refs === undefined) return "all";
+	const allowed = new Set<string>();
+	for (const ref of refs) {
+		for (const name of discovered) {
+			if (matchesReference(ref, name)) allowed.add(name);
+		}
+	}
+	return [...allowed];
+}
+
+export interface McpOverlayInput {
+	/** Parsed Pi-global slot document, when the user has one. */
+	slotDocument?: Record<string, unknown>;
+	/** Server names defined in the adapter's other file sources. */
+	otherServerNames: readonly string[];
+	allowed: readonly string[] | "all";
+}
+
+/** Builds the overlay document. Server order is sorted so the serialized
+ *  bytes are stable and a rewrite only happens on a real change. */
+export function buildMcpOverlay(input: McpOverlayInput): Record<string, unknown> {
+	const allowed = input.allowed === "all" ? undefined : new Set(input.allowed);
+	const slotServers = isRecord(input.slotDocument?.mcpServers) ? input.slotDocument.mcpServers : {};
+	const servers: Record<string, unknown> = {};
+	for (const [name, definition] of Object.entries(slotServers)) {
+		if (allowed === undefined || allowed.has(name) || !isRecord(definition)) {
+			servers[name] = definition;
+			continue;
+		}
+		servers[name] = { ...definition, disabled: true };
+	}
+	for (const name of input.otherServerNames) {
+		if (name in servers) continue; // the slot's definition owns the name
+		if (allowed === undefined || allowed.has(name)) continue;
+		servers[name] = { disabled: true };
+	}
+	const document: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(input.slotDocument ?? {})) {
+		if (key !== "mcpServers" && key !== MCP_GENERATED_MARKER) document[key] = value;
+	}
+	document[MCP_GENERATED_MARKER] = { generated: true, version: 1 };
+	document.mcpServers = Object.fromEntries(
+		Object.entries(servers).sort(([left], [right]) => left.localeCompare(right)),
+	);
+	return document;
+}
+
+/** Stable serialization: two runs with the same semantics produce the same
+ *  bytes, so the writer can skip no-op writes. */
+export function serializeMcpOverlay(document: Record<string, unknown>): string {
+	return `${JSON.stringify(document, null, 2)}\n`;
+}

package/src/profile-catalog-store.ts

@@ -37,7 +37,7 @@ export class ProfileCatalogStore {
 
 	/** Validated definitions: missing file → empty; malformed → CatalogError
 	 *  (catalog errors never pass silently, even on the write path).
-	 *  Unknown fields (a legacy `extensions` declaration) are dropped. */
+	 *  Unknown fields (an `extensions` key left over from v0.1.0) are dropped. */
 	async readDefinitions(): Promise<Map<string, ProfileDefinition>> {
 		const result = await readJsonFile(this.#filePath);
 		if (!result.ok) {

package/src/profile-catalog.ts

@@ -7,11 +7,11 @@
  * - A profile references skills, MCP servers, and tools, and may declare
  *   instructions and a model preset. Extensions are not a profile resource:
  *   every installed extension loads natively in every profile.
- * - schemaVersion 1 is current. Version 2 describes the same fields — the
- *   number only marked the era in which `extensions` was still a profile
- *   resource — and reads the same; every save writes version 1.
- * - A legacy `extensions` field is ignored silently, like any other unknown
- *   field: extensions load natively and are managed with `pi install`.
+ * - schemaVersion 1 is the only accepted version: any other value fails
+ *   loudly instead of guessing at a shape.
+ * - 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.
  *
  * Invariants:
  * - The built-in `default` profile never exists in either file and cannot be
@@ -30,8 +30,6 @@ import path from "node:path";
 import { isRecord, readJsonFile } from "./json-file.ts";
 
 export const PROFILE_SCHEMA_VERSION = 1;
-/** The number v0.1.0 wrote for the same field shape: read, never written. */
-const LEGACY_SCHEMA_VERSION = 2;
 export const DEFAULT_PROFILE_NAME = "default";
 
 export interface ProfileModel {
@@ -91,8 +89,8 @@ function readOptionalString(value: unknown, field: string, profileName: string):
 
 /** Parses one raw profile definition; exported for the write-side store
  *  (profile-catalog-store.ts) so anything written is loadable. Unknown
- *  fields are ignored by design — a legacy `extensions` declaration is
- *  dropped silently, exactly like any other unknown key. */
+ *  fields are ignored by design — an `extensions` key left over from
+ *  v0.1.0 is dropped silently, exactly like any other unknown key. */
 export function parseProfileDefinition(name: string, raw: unknown): ProfileDefinition {
 	if (!isRecord(raw)) {
 		throw new CatalogError(`profile "${name}" must be an object`);
@@ -125,7 +123,7 @@ export function parseCatalogDocument(value: unknown, filePath: string): Map<stri
 		throw new CatalogError(`${filePath}: catalog must be an object`);
 	}
 	const version = value.schemaVersion;
-	if (version !== PROFILE_SCHEMA_VERSION && version !== LEGACY_SCHEMA_VERSION) {
+	if (version !== PROFILE_SCHEMA_VERSION) {
 		throw new CatalogError(
 			`${filePath}: unsupported schemaVersion ${JSON.stringify(version)} (expected ${PROFILE_SCHEMA_VERSION})`,
 		);

package/src/profile-presets.ts

@@ -25,8 +25,9 @@
  * - `instructions` states behavior, never a capability name, and stays
  *   short: Pi appends it to the system prompt on every turn.
  *
- * `test/profile-presets.test.ts` enforces every rule above and asserts
- * `examples/profiles.json` is exactly this catalog.
+ * `test/profile-presets.test.ts` enforces every rule above, asserts
+ * `examples/profiles.json` is exactly this catalog, and asserts each preset
+ * appears verbatim in `examples/profiles.example.json`.
  */
 
 import type { ProfileDefinition } from "./profile-catalog.ts";

package/src/startup-mcp-scope.ts

@@ -0,0 +1,262 @@
+/**
+ * StartupMcpScope: derives the profile-scoped MCP overlay at times when a
+ * full activation has not (or may not yet) run.
+ *
+ * Two callers:
+ * - The extension-load pass: must be synchronous and must finish before
+ *   pi-mcp-adapter reads its config at `session_start` (and, for eager
+ *   servers, at its own load time). Pi applies CLI flag values only AFTER
+ *   extension loading, so the `--profile` / `--mcp-config` values are read
+ *   from argv here; trust is mirrored from Pi's own resolution order
+ *   (`hasTrustRequiringProjectResources` → stored decision →
+ *   `defaultProjectTrust`; an interactive first-time prompt is not yet
+ *   answerable at load time and counts as untrusted).
+ * - The switch pass: the caller already has the resolved allowlist, so the
+ *   overlay is derived from it directly.
+ *
+ * The generated file IS the adapter's Pi-global slot (`<agentDir>/mcp.json`):
+ * flag injection is impossible (Pi rejects two extensions registering the
+ * same flag), so the mechanism works with the slot the adapter already reads.
+ * The user's own Pi-global servers live in the sidecar `mcp.user.json`.
+ *
+ * Failure policy: a profile name that cannot be resolved (missing, malformed
+ * catalog, unknown name) falls back to "no filtering" — the generated overlay
+ * then changes nothing, and the real problem is reported loudly by the
+ * activation that runs right after. A foreign `--mcp-config` disables
+ * management entirely: the user's explicit file is never overwritten.
+ */
+
+import { hasTrustRequiringProjectResources, ProjectTrustStore } from "@earendil-works/pi-coding-agent";
+import path from "node:path";
+
+import { isRecord, readJsonFileSync } from "./json-file.ts";
+import { readAdapterOtherServerNamesSync, readMcpDocumentSync } from "./mcp-config.ts";
+import {
+	buildMcpOverlay,
+	isDisabledStub,
+	isGeneratedOverlay,
+	MCP_GENERATED_MARKER,
+	mcpSlotPath,
+	mcpSourcePath,
+	resolveAllowedServers,
+	serializeMcpOverlay,
+} from "./mcp-overlay.ts";
+import { writeMcpOverlayIfChangedSync } from "./mcp-overlay-file.ts";
+import { DEFAULT_PROFILE_NAME, parseCatalogDocument, type ProfileDefinition } from "./profile-catalog.ts";
+
+/** Reads `--<name> <value>` / `--<name>=<value>` without Pi's parser (Pi
+ *  applies extension flag values only after extension loading). Last wins. */
+export function readFlagFromArgv(argv: readonly string[], name: string): string | undefined {
+	const long = `--${name}`;
+	let value: string | undefined;
+	for (let index = 0; index < argv.length; index++) {
+		const token = argv[index] ?? "";
+		if (token === long) {
+			const next = argv[index + 1];
+			if (next !== undefined && !next.startsWith("--")) value = next;
+			continue;
+		}
+		if (token.startsWith(`${long}=`)) {
+			const inline = token.slice(long.length + 1);
+			if (inline.length > 0) value = inline;
+		}
+	}
+	return value;
+}
+
+/** True when Pi itself would consider `cwd` trusted right now. Mirrors
+ *  `resolveProjectTrusted` minus extension votes and the interactive prompt. */
+export function resolveProjectTrustedSync(agentDir: string, cwd: string): boolean {
+	if (!hasTrustRequiringProjectResources(cwd)) return true;
+	const stored = new ProjectTrustStore(agentDir).get(cwd);
+	if (stored !== null) return stored;
+	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. */
+export function resolveStartupProfileNameSync(input: {
+	agentDir: string;
+	cwd: string;
+	projectTrusted: boolean;
+	argv: readonly string[];
+}): string {
+	const requested = readFlagFromArgv(input.argv, "profile");
+	if (requested !== undefined && requested.length > 0) return requested;
+	const project = input.projectTrusted
+		? readActiveProfile(path.join(input.cwd, ".pi", "pi-profile-state.json"))
+		: undefined;
+	return project ?? readActiveProfile(path.join(input.agentDir, "pi-profile-state.json")) ?? DEFAULT_PROFILE_NAME;
+}
+
+export interface McpOverlaySyncInput {
+	agentDir: string;
+	cwd: string;
+	/** Pi's trust decision. Omitted on the extension-load pass, where Pi has
+	 *  not resolved trust yet; the module mirrors Pi's own order then. */
+	projectTrusted?: boolean;
+	/** Effective `--mcp-config`; undefined means the managed overlay path. */
+	overridePath?: 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[];
+	homeDir?: string;
+}
+
+export interface McpOverlaySyncResult {
+	overlayPath: string;
+	/** False when a foreign `--mcp-config` owns the adapter's slot. */
+	managed: boolean;
+	changed: boolean;
+	/** Set when nothing was written; the caller surfaces it as a warning. */
+	error?: string;
+}
+
+/** Load-time (and `session_start` re-check) pass. `profileName` short-circuits
+ *  the state lookup when the caller already activated a profile. */
+export function syncStartupMcpOverlay(
+	input: McpOverlaySyncInput & { profileName?: string; mcpRefs?: readonly string[] | undefined },
+): McpOverlaySyncResult {
+	try {
+		const trust = input.projectTrusted;
+		const profileName =
+			input.profileName ??
+			resolveStartupProfileNameSync({
+				agentDir: input.agentDir,
+				cwd: input.cwd,
+				projectTrusted: trust ?? resolveProjectTrustedSync(input.agentDir, input.cwd),
+				argv: input.argv ?? [],
+			});
+		const refs = input.mcpRefs ?? readProfileMcpRefsSync({ ...input, name: profileName, trust });
+		return writeOverlayForRefs({ ...input, refs });
+	} catch (error) {
+		return {
+			overlayPath: mcpSlotPath(input.agentDir),
+			managed: true,
+			changed: false,
+			error: error instanceof Error ? error.message : String(error),
+		};
+	}
+}
+
+/** Switch pass: the caller already resolved the allowlist. */
+export function syncMcpOverlayForSelection(
+	input: McpOverlaySyncInput & { allowed: readonly string[] | "all" },
+): McpOverlaySyncResult {
+	try {
+		return writeOverlay({ ...input, refs: input.allowed });
+	} catch (error) {
+		return {
+			overlayPath: mcpSlotPath(input.agentDir),
+			managed: true,
+			changed: false,
+			error: error instanceof Error ? error.message : String(error),
+		};
+	}
+}
+
+function writeOverlayForRefs(input: McpOverlaySyncInput & { refs: readonly string[] | undefined | "unknown" }): McpOverlaySyncResult {
+	// An unresolvable profile is not an error here: the generated overlay
+	// then filters nothing and the activation reports the real problem.
+	const refs = input.refs === "unknown" ? undefined : input.refs;
+	return writeOverlay({ ...input, refs });
+}
+
+function writeOverlay(input: McpOverlaySyncInput & { refs: readonly string[] | undefined | "all" }): McpOverlaySyncResult {
+	const overlayPath = mcpSlotPath(input.agentDir);
+	if (input.overridePath !== undefined && path.resolve(input.overridePath) !== overlayPath) {
+		return { overlayPath, managed: false, changed: false };
+	}
+	const projectTrusted = input.projectTrusted ?? resolveProjectTrustedSync(input.agentDir, input.cwd);
+	const discovery = {
+		agentDir: input.agentDir,
+		cwd: input.cwd,
+		projectTrusted,
+		...(input.homeDir === undefined ? {} : { homeDir: input.homeDir }),
+	};
+	// The slot is ours; a slot written by hand is adopted into the sidecar
+	// before the first overwrite, so a user's Pi-global servers survive.
+	const sourcePath = mcpSourcePath(input.agentDir);
+	adoptHandWrittenSlotSync(overlayPath, sourcePath);
+	const sourceDocument = readMcpDocumentSync(sourcePath);
+	const sourceNames = isRecord(sourceDocument?.mcpServers) ? Object.keys(sourceDocument.mcpServers) : [];
+	const otherNames = readAdapterOtherServerNamesSync(discovery);
+	const allowed =
+		input.refs === "all"
+			? "all"
+			: resolveAllowedServers(input.refs, [...new Set([...sourceNames, ...otherNames])].sort());
+	const content = serializeMcpOverlay(
+		buildMcpOverlay({
+			...(sourceDocument === undefined ? {} : { slotDocument: sourceDocument }),
+			otherServerNames: otherNames,
+			allowed,
+		}),
+	);
+	return { overlayPath, managed: true, changed: writeMcpOverlayIfChangedSync(overlayPath, content) };
+}
+
+/** A slot file without the generated marker holds the user's own Pi-global
+ *  servers (from before this package managed the slot, or from a manual
+ *  edit). Move them — plus the slot's non-server keys — into the sidecar
+ *  before the slot is overwritten. Stub entries are skipped: they describe
+ *  servers owned by the adapter's other sources. */
+function adoptHandWrittenSlotSync(slotPath: string, sourcePath: string): void {
+	const slot = readMcpDocumentSync(slotPath);
+	if (slot === undefined || isGeneratedOverlay(slot)) return;
+	const sidecar = readMcpDocumentSync(sourcePath) ?? {};
+	const sidecarServers = isRecord(sidecar.mcpServers) ? sidecar.mcpServers : {};
+	const servers: Record<string, unknown> = { ...sidecarServers };
+	const slotServers = isRecord(slot.mcpServers) ? slot.mcpServers : {};
+	for (const [name, definition] of Object.entries(slotServers)) {
+		if (isDisabledStub(definition)) continue;
+		servers[name] = definition;
+	}
+	const document: Record<string, unknown> = { ...sidecar };
+	delete document[MCP_GENERATED_MARKER];
+	for (const [key, value] of Object.entries(slot)) {
+		if (key === "mcpServers" || key === MCP_GENERATED_MARKER) continue;
+		document[key] = value;
+	}
+	document.mcpServers = Object.fromEntries(Object.entries(servers).sort(([left], [right]) => left.localeCompare(right)));
+	writeMcpOverlayIfChangedSync(sourcePath, `${JSON.stringify(document, null, 2)}\n`);
+}
+
+function readActiveProfile(statePath: string): string | undefined {
+	const result = readJsonFileSync(statePath);
+	if (!result.ok || !isRecord(result.value)) return undefined;
+	const name = result.value.activeProfile;
+	return typeof name === "string" && name.length > 0 ? name : undefined;
+}
+
+/** The profile's raw `mcp` 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 },
+): readonly string[] | undefined | "unknown" {
+	if (input.name === DEFAULT_PROFILE_NAME) return undefined;
+	const trusted = input.trust ?? resolveProjectTrustedSync(input.agentDir, input.cwd);
+	const global = readCatalogSync(path.join(input.agentDir, "profiles.json"));
+	const project = trusted
+		? readCatalogSync(path.join(input.cwd, ".pi", "profiles.json"))
+		: 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;
+}
+
+function readCatalogSync(filePath: string): Map<string, ProfileDefinition> | "error" {
+	const result = readJsonFileSync(filePath);
+	if (!result.ok) return result.reason === "missing" ? new Map<string, ProfileDefinition>() : "error";
+	try {
+		return parseCatalogDocument(result.value, filePath);
+	} catch {
+		return "error";
+	}
+}
+
+function readDefaultProjectTrustSync(agentDir: string): string | undefined {
+	const result = readJsonFileSync(path.join(agentDir, "settings.json"));
+	if (!result.ok || !isRecord(result.value)) return undefined;
+	const value = result.value.defaultProjectTrust;
+	return typeof value === "string" ? value : undefined;
+}