pi-profile-switch 0.13.1 → 0.14.0

package/README.md

@@ -10,15 +10,15 @@ Named profiles for [Pi](https://github.com/badlogic/pi-mono). A profile is a nam
 npm install -g pi-profile-switch
 ```
 
-Requires [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) (installed automatically as a peer dependency).
+Requires [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) 0.99.1 or newer (installed automatically as a peer dependency). Use `npm install -g`, not `pi install` — this package provides the `pi-profile` launcher.
 
 ## Quick start
 
 ```bash
-# Launch with the built-in default profile (all resources, plain Pi behavior)
+# Built-in default profile: all resources, plain Pi behavior
 pi-profile
 
-# Launch with the seeded read-only ask profile
+# Starter read-only ask profile
 pi-profile ask
 
 # Anything after -- is passed to pi verbatim
@@ -27,58 +27,28 @@ pi-profile ask -- --model openai/gpt-5.4
 
 ## Define your own profiles
 
-Profiles live in two directories, with one JSON file per profile:
+Profiles live in two directories, one JSON file per profile:
 
 | Path | Scope |
 | --- | --- |
-| `~/.pi-profile-switch/profiles/<name>.json` | Global, all projects. `PI_PROFILE_SWITCH_DIR` overrides the workspace root. |
-| `<project>/.pi/profiles/<name>.json` | Project-level, trusted projects only. |
+| `~/.pi-profile-switch/profiles/<name>.json` | Global, all projects. `PI_PROFILE_SWITCH_DIR` overrides the root directory. |
+| `<project>/.pi/profiles/<name>.json` | Project-level, trusted projects only. Completely replaces a global profile with the same name. |
 
-Create or change a profile by editing or creating a `<name>.json` file directly — schema: [`schemas/profiles.schema.json`](schemas/profiles.schema.json).
+Write the JSON directly (schema: [`schemas/profiles.schema.json`](schemas/profiles.schema.json)), or configure profiles conversationally: the package ships a [`profile-config`](skills/profile-config/SKILL.md) skill that creates, edits, and deletes profiles. Profiles created with a `skills` list include `"profile-config"` by default (unless you opt out or cover it with a wildcard like `"*"`), keeping configuration available after switching.
 
-You can also configure profiles conversationally: the package ships a **`profile-config`** skill (distributed to `<agentDir>/skills/profile-config/` — best-effort on install, and guaranteed in place at every launcher startup) that guides the agent to clarify requirements, discover resources, and write or remove profile files. Profiles created with a `skills` list include `"profile-config"` by default (unless explicitly opted out or covered by a wildcard like `"*"`), keeping configuration available after switching. Details: [`skills/profile-config/SKILL.md`](skills/profile-config/SKILL.md).
+When the global profiles directory has no profile yet, pi-profile-switch writes a starter **`ask`** profile — read-only Q&A and code exploration. It assumes nothing about your setup; edit or delete it freely. See [`examples/ask.json`](examples/ask.json).
 
-pi-profile-switch seeds the global `profiles/` directory with a starter **`ask`** profile (`ask.json`) — best-effort on install, and guaranteed in place at every launcher startup — read-only Q&A and code exploration. It assumes nothing about your setup; edit or delete it freely:
-
-```json
-{
-  "label": "Ask & Discuss",
-  "description": "Read-only Q&A and code exploration; no file modifications or command execution",
-  "skills": [],
-  "extensions": [],
-  "tools": ["read", "grep", "find", "ls"],
-  "instructions": "You are in read-only discussion mode. Answer questions and explain code without modifying any files or running shell commands."
-}
-```
-
-One profile can use every field at once. This example `impl` profile (`impl.json`) loads the TDD skill and your internal skills; wires up two MCP servers; allows the built-in tools; restricts GitHub MCP tools while denying Linear tools; and pins the model and standing instructions:
+A profile that uses every field:
 
 ```json
 {
   "label": "Implementation",
   "description": "Full-powered implementation profile: every available field, pinned model",
-  "skills": [
-    "tdd",
-    "internal-*"
-  ],
-  "mcps": [
-    "github",
-    "linear"
-  ],
-  "tools": [
-    "read",
-    "grep",
-    "find",
-    "ls",
-    "bash",
-    "edit",
-    "write"
-  ],
+  "skills": ["tdd", "internal-*"],
+  "mcps": ["github", "linear"],
+  "tools": ["read", "grep", "find", "ls", "bash", "edit", "write"],
   "mcp_tools": {
-    "github": [
-      "search",
-      "get_issue"
-    ],
+    "github": ["search", "get_issue"],
     "linear": []
   },
   "defaultProvider": "anthropic",
@@ -88,42 +58,54 @@ One profile can use every field at once. This example `impl` profile (`impl.json
 }
 ```
 
-How fields resolve:
+How the fields behave:
 
 - `skills`, `extensions`, `mcps`, `tools` take names or globs (e.g. `"internal-*"`) referencing resources you already installed or configured — profiles never copy them. Installed packages and files in standard locations are discovered automatically; no registration needed.
-- `tools` expands strictly against Pi's non-MCP tool registry — built-ins and extension-contributed tools, attributed by registration ownership (`sourceInfo`). Available MCP tools remain usable independently of `tools`.
+- `tools` expands strictly against Pi's non-MCP tool registry — built-ins and extension-contributed tools, attributed by registration ownership (`sourceInfo`). Available MCP tools remain usable independently of `tools`. When a profile declares `tools` and at least one MCP server is enabled, Pi's native MCP discovery entry points (`codemode` and `tool_search`) stay active even if you did not list them; unrelated non-MCP tools excluded by `tools` stay excluded.
 - `mcp_tools` defines per-server MCP tool filtering: keys are literal configured server names and values are literal MCP tool names as exposed by Pi's built-in MCP extension. Globs are not accepted. An omitted server keeps native access to all its tools; a nonempty array allows only matched tools; an empty array (`[]`) denies all tools for that server while leaving it enabled. Unmatched selectors remain restrictive and are not diagnosed, so confirm selectors with the server before writing them.
 - **Migration notes:**
   - Former MCP references in `tools` (e.g. `mcp__*`, `<server>_*`) no longer govern MCP access. Move desired MCP tool restrictions to `mcp_tools`.
   - Prefixed selectors (e.g. `<server>_<tool>` forms used by previous MCP integrations) no longer apply; replace them with the literal tool names from Pi's built-in MCP extension.
 - `mcps` references servers from your Pi user-level MCP configuration (`~/.config/mcp/mcp.json`, `~/.agents/mcp.json`, `~/.agents/mcp/mcp.json`, and `<agentDir>/mcp.json`); connection details stay in those files.
   - **Omitting `mcps`** leaves all discovered user-level servers at their normal availability.
-  - **`mcps: []`** disables every discovered user-level server, including agentDir-only servers; every unselected user-level server is explicitly marked `enabled: false` in the generated instance `mcp.json`. Project-level servers are never narrowed.
+  - **`mcps: []`** disables every discovered user-level server, including agentDir-only servers; every unselected user-level server keeps its full definition and is explicitly marked `enabled: false` in the generated instance `mcp.json`. Project-level servers are never narrowed.
   - Trusted project-level MCP servers are always kept enabled and are never narrowed by `mcps`.
   - Servers using `type: "sse"` cannot be selected; migrate them to streamable HTTP before referencing them in a profile.
+  - A later user-level source replaces a same-named server from an earlier source in full (no field-wise merging), so connection and credential fields are never inherited across files.
+  - A profile that declares neither `mcps` nor `mcp_tools` treats a malformed user-level MCP source as a non-fatal diagnostic (printed on stderr with the file path) and starts with the remaining valid sources. Declaring `mcps` or a nonempty `mcp_tools` makes the same malformed source fail activation, because the allowlist cannot be trusted.
 - The instance `mcp.json` is always a generated snapshot of the merged user-level configuration. In-session `pi mcp add` edits the instance copy, and the next `/profile use` or `/profile reload` overwrites it with the profile's snapshot.
 - Any field you omit keeps plain Pi behavior.
+- `label` and `description` are display metadata. `defaultProvider` and `defaultModel` (declared together) set the startup model; `defaultThinkingLevel` sets its thinking level; `instructions` is appended to the system prompt.
+- `skills`, `extensions`, `mcps`, and `tools` reference installed resources by name or glob; profiles never copy resources. `tools` covers non-MCP tools only (built-ins and extension tools).
+- `mcp_tools` selects tools inside MCP servers by literal server and tool name — globs are rejected. Omit a server to leave it unchanged, use `[]` to deny all of its tools while keeping the server enabled, or list names to allow only those. A literal selector that matches nothing stays restrictive without warning; a server that is unknown, disabled, or project-only fails activation with candidates.
+- `mcps` names user-level servers from `~/.config/mcp/mcp.json`, `~/.agents/mcp.json`, `~/.agents/mcp/mcp.json`, and `<agentDir>/mcp.json`. Omit it to leave all servers as configured; use `[]` to disable every user-level server. Project-level servers (`.pi/mcp.json`) are read by Pi itself and are never narrowed. Legacy SSE servers cannot be selected.
+- Older profiles expressed MCP tool access through `mcp__*` or `<server>_*` entries in `tools`; use `mcp_tools` instead.
+- Every omitted field keeps plain Pi behavior.
 
-The files in [`examples/`](examples/) mirror the two profiles above: `ask.json` is the seeded starter, `example.json` the full-field demo.
+The instance's `mcp.json` is generated by the launcher. Running `pi mcp add` inside a session only edits that generated copy, and the next profile switch or reload overwrites it — edit your real MCP configuration instead.
 
-## Commands
+[`examples/`](examples/) contains the full example above and the starter `ask`.
 
-The `/profile` command family manages everything in-session:
+## Commands
 
 | Command | What it does |
 | --- | --- |
-| `/profile` | Interactive profile picker; without interactive UI it prints the profile list instead |
-| `/profile use <name>` / `/profile reload` | Switch / reload without restarting (rollback on failure) |
-| `/profile status` | Active profile details: resolved resources and paths, stored overlay, MCP server tri-state |
-| `/profile overlay disable\|enable skill\|extension\|mcp\|tool <name-or-glob>` | Narrow / un-narrow the active profile for this session only; `disable` entries accept names or globs |
-| `/profile overlay clear` | Discard the overlay and reactivate the profile exactly as declared |
+| `/profile` | Show the available profiles and pick one (interactive selector; prints the list outside the TUI). |
+| `/profile use <name>` | Switch profiles now. The session reloads with the new resources; a failed switch rolls back. The choice is remembered for the next launch. |
+| `/profile reload` | Re-read the active profile file after editing it. |
+| `/profile status` | Report the active profile, resolved resources and paths, overlay, MCP server state, and conflicts. |
+| `/profile overlay disable\|enable skill\|extension\|mcp\|tool <name-or-glob>` | Narrow or restore resources for this session only. |
+| `/profile overlay clear` | Drop the overlay and use the profile as written. |
 
-All forms work in every mode, including non-interactive ones (`--mode rpc|print|json`); the bare selector degrades to the profile list where no interactive UI exists. The overlay is a runtime-only narrowing: it is never written to a catalog file and never survives a restart. Tools follow the same disable/enable model as the other resource kinds: a tool `disable` entry narrows the profile's resolved tool references — or the runtime's full available tool set when the profile declares no `tools`.
+All forms work in every mode, including non-interactive ones (`--mode rpc|text|json`); the bare selector degrades to the profile list where no interactive UI exists. The overlay is a runtime-only narrowing: it is never written to a catalog file and never survives a restart. Tools follow the same disable/enable model as the other resource kinds: a tool `disable` entry narrows the profile's resolved tool references — or the runtime's full available tool set when the profile declares no `tools`.
+All of these work in every mode, including non-interactive ones (`--mode text`, `--mode json`, `--mode rpc`). An overlay lives only in the current runtime: it is never written to your profile files and is gone after a restart. Disabling MCP servers with an overlay is not possible on the built-in `default` profile — it has no server list to narrow.
 
 ## Docs
 
-- [Architecture](docs/architecture/overview.md) · [ADRs](docs/adr/) · [Glossary](CONTEXT.md)
-- JSON Schemas: [`schemas/`](schemas/)
+- Field reference: [`schemas/profiles.schema.json`](schemas/profiles.schema.json)
+- Architecture and terminology: [`docs/architecture/overview.md`](docs/architecture/overview.md) and [`CONTEXT.md`](CONTEXT.md)
+- Decisions: [`docs/adr/`](docs/adr/)
+- Authoring guide: [`skills/profile-config/SKILL.md`](skills/profile-config/SKILL.md)
 
 ## License
 

package/README.zh-CN.md

@@ -10,7 +10,7 @@
 npm install -g pi-profile-switch
 ```
 
-依赖 [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)（作为 peer dependency 自动安装）。
+需要 [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) 0.99.1 或更新版本（作为 peer dependency 自动安装）。请用 `npm install -g` 安装，而不是 `pi install`：本包提供的是 `pi-profile` 启动器。
 
 ## 快速上手
 
@@ -18,7 +18,7 @@ npm install -g pi-profile-switch
 # 使用内建 default profile 启动（全量资源，等同原生 Pi）
 pi-profile
 
-# 使用 starter 只读 ask profile 启动
+# 使用初始的只读 ask profile 启动
 pi-profile ask
 
 # -- 后面的参数原样传给 pi
@@ -27,62 +27,28 @@ pi-profile ask -- --model openai/gpt-5.4
 
 ## 自定义 profile
 
-profile 保存在两个目录中，每个 profile 对应一个独立 JSON 文件：
+profile 保存在两个目录中，每个 profile 对应一个 JSON 文件：
 
 | 路径 | 作用域 |
 | --- | --- |
 | `~/.pi-profile-switch/profiles/<name>.json` | 全局，对所有项目生效。`PI_PROFILE_SWITCH_DIR` 可自定义根目录。 |
-| `<项目>/.pi/profiles/<name>.json` | 项目级，仅对已信任项目生效。 |
+| `<项目>/.pi/profiles/<name>.json` | 项目级，仅对已信任项目生效；同名时会完全替换全局 profile。 |
 
-直接编辑或新建 `<name>.json` 即可创建或修改 profile——schema 见 [`schemas/profiles.schema.json`](schemas/profiles.schema.json)。
+直接写 JSON 文件即可（schema 见 [`schemas/profiles.schema.json`](schemas/profiles.schema.json)），也可以让 agent 帮你改：本包自带 [`profile-config`](skills/profile-config/SKILL.md) skill，能创建、修改和删除 profile。只要新建的 profile 声明了 `skills`，默认会包含 `"profile-config"`（除非你明确排除，或已被 `"*"` 之类的 glob 覆盖），这样切过去之后还能继续用对话调整。
 
-你也可以通过对话让 agent 帮你配置：随包附带的 **`profile-config`** skill（安装时 best-effort 分发、launcher 启动时保证就位，位于 `<agentDir>/skills/profile-config/`）会指导 agent 澄清需求、发现资源并读写 profile 文件。按约定，生成声明了 `skills` 的 profile 时默认包含 `"profile-config"`（除非明确排除或已被 `*` 等 glob 覆盖），确保切换到新 profile 后仍可持续对话配置。详情见 [`skills/profile-config/SKILL.md`](skills/profile-config/SKILL.md)。
+全局 `profiles/` 目录里还没有 profile 时，pi-profile-switch 会写入一个初始 **`ask`** profile——只读问答与代码走读。它不假设你安装过任何插件，可随意修改或删除。见 [`examples/ask.json`](examples/ask.json)。
 
-pi-profile-switch 会向全局 `profiles/` 目录播种一个初始 **`ask`** profile（`ask.json`）——安装时 best-effort、launcher 启动时保证就位——它是只读的问答与代码走读模式。它不假设你安装过任何插件，可随意修改或删除：
-
-```json
-{
-  "label": "Ask & Discuss",
-  "description": "Read-only Q&A and code exploration; no file modifications or command execution",
-  "skills": [],
-  "extensions": [],
-  "tools": ["read", "grep", "find", "ls"],
-  "instructions": "You are in read-only discussion mode. Answer questions and explain code without modifying any files or running shell commands."
-}
-```
-
-一个 profile 可以同时使用全部字段。下面这个 `impl` profile 示例（`impl.json`）加载 TDD skill、mcp-scripting skill（pi-mcp-adapter 自带）和你的内部 skills；接入两个 MCP server；允许内建工具并按 server 细化 MCP 工具；同时钉住模型与常驻 instructions：
+一个用到全部字段的 profile：
 
 ```json
 {
   "label": "Implementation",
   "description": "Full-powered implementation profile: every available field, pinned model",
-  "skills": [
-    "tdd",
-    "internal-*",
-    "mcp-scripting"
-  ],
-  "extensions": [
-    "pi-mcp-adapter"
-  ],
-  "mcps": [
-    "github",
-    "linear"
-  ],
-  "tools": [
-    "read",
-    "grep",
-    "find",
-    "ls",
-    "bash",
-    "edit",
-    "write"
-  ],
+  "skills": ["tdd", "internal-*"],
+  "mcps": ["github", "linear"],
+  "tools": ["read", "grep", "find", "ls", "bash", "edit", "write"],
   "mcp_tools": {
-    "github": [
-      "search",
-      "get_issue"
-    ],
+    "github": ["search", "get_issue"],
     "linear": []
   },
   "defaultProvider": "anthropic",
@@ -92,41 +58,39 @@ pi-profile-switch 会向全局 `profiles/` 目录播种一个初始 **`ask`** pr
 }
 ```
 
-字段解析规则：
+字段行为：
 
-- `skills`、`extensions`、`mcps`、`tools` 接受名称或 glob（如 `"internal-*"`），引用你已安装或已配置的资源——profile 从不复制资源。已安装的包和标准目录下的文件会被自动发现，无需注册。
-- `tools` 仅针对 Pi 的非 MCP 工具展开（内建工具与 extension 提供的工具，根据注册归属 `sourceInfo` 判定）。可用的 MCP 工具独立于 `tools` 保持可用。
-- `mcp_tools` 按 server 细化 MCP 工具策略：键为字面 MCP server 名称，值为 pi-mcp-adapter 的字面 selector（原始名或带前缀名；两种写法都可能选中同一个工具）。此字段不接受 glob。省略的 server 保留其全部原生工具访问；非空数组仅允许匹配到的工具；空数组（`[]`）禁用该 server 的全部工具，同时保持 server 处于启用状态。未匹配的 selector 仍保持限制且不会收到诊断，因此编写前请通过 adapter/server 确认可用写法。
-- 非空的 `mcp_tools` 即使在省略 `mcps` 时也需要 `pi-mcp-adapter`。只有当 profile selector 与已有的 `includeTools` 字面值完全相同，或已有列表是 `"*"` 时才能安全组合；否则会在写入 runtime 文件前报错。已有的 `excludeTools` 限制仍然生效。
-- **迁移提示**：旧 profile 中写入 `tools` 的 MCP 工具名称或 glob（如 `mcp__*`、`<server>_*`）不再控制 MCP 访问；如有需要请迁移至 `mcp_tools`。
-- `mcps` 引用 pi-mcp-adapter 配置中的 server；连接细节留在 adapter 自己的配置里。
-  - **省略 `mcps`**：保留所有已发现用户级 server 的原生可用性。
-  - **`mcps: []` 且选中了 `pi-mcp-adapter`**：禁用所有已发现用户级 server（共享位置的 server 会被显式标记为 `disabled`；仅位于 agentDir 的 server 会从生成的实例 `mcp.json` 中省略）。
-  - **`mcps: []` 但未选中 `pi-mcp-adapter`**：该声明不生效，不会读取 MCP 配置、改变 server 可用性，也不会因配置文件损坏而报错。
-  - 受信任的项目级 MCP server 始终保持启用，不受 `mcps` 收窄。
-- 未写的字段保持原生 Pi 行为。
+- `label`、`description` 仅用于显示。`defaultProvider` 与 `defaultModel` 需同时声明，用于指定启动模型；`defaultThinkingLevel` 指定思考等级；`instructions` 会追加到系统提示词。
+- `skills`、`extensions`、`mcps`、`tools` 以名称或 glob 引用已安装的资源；profile 不会复制资源。`tools` 只涉及非 MCP 工具（内置工具和扩展工具）。
+- `mcp_tools` 按字面 server 名和工具名选择 MCP 工具，不接受 glob。省略某个 server 表示保持原样，写 `[]` 表示禁用它的全部工具但保留 server 本身，列出名称表示只允许这些工具。字面选择器匹配不到内容时仍保持限制且不报错；server 未知、已禁用或只存在于项目级配置时，激活会失败并给出候选。
+- `mcps` 列出用户级 server，可来自 `~/.config/mcp/mcp.json`、`~/.agents/mcp.json`、`~/.agents/mcp/mcp.json` 和 `<agentDir>/mcp.json`。省略表示全部保持原样；写 `[]` 表示禁用所有用户级 server。项目级 server（`.pi/mcp.json`）由 Pi 自己读取，profile 不会收窄。旧的 SSE server 无法选择。
+- 旧版 profile 用 `tools` 里的 `mcp__*`、`<server>_*` 表达 MCP 工具访问；现在请改用 `mcp_tools`。
+- 未声明的字段完全保持原生 Pi 行为。
 
-[`examples/`](examples/) 中的两个文件与上面一一对应：`ask.json` 是播种的初始 profile，`example.json` 是全字段演示。
+实例目录里的 `mcp.json` 由启动器生成。在会话里执行 `pi mcp add` 只会改到这份生成副本，下次切换 profile 或重载时会被覆盖——要永久生效，请直接修改你自己的 MCP 配置。
 
-## 命令
+[`examples/`](examples/) 里有上面的完整示例和初始 `ask`。
 
-`/profile` 命令族完成所有会话内操作：
+## 命令
 
 | 命令 | 作用 |
 | --- | --- |
-| `/profile` | 交互式选择 profile；无交互界面时打印 profile 列表 |
-| `/profile use <name>` / `/profile reload` | 会话内切换 / 重载（失败自动回滚） |
-| `/profile status` | 查看活动 profile 详情：解析后的资源与路径、已存 overlay、MCP server 三态 |
-| `/profile overlay disable\|enable skill\|extension\|mcp\|tool <name-or-glob>` | 仅本次会话收窄 / 恢复活动 profile；`disable` 接受名称或 glob |
-| `/profile overlay clear` | 丢弃 overlay，完全按定义重新激活 profile |
+| `/profile` | 显示可选 profile 并选择（TUI 里是交互式选择器，非 TUI 下打印列表）。 |
+| `/profile use <name>` | 立即切换 profile。会话会用新资源重载；切换失败会回滚。选择会被记住，下次启动继续使用。 |
+| `/profile reload` | 修改 profile 文件后重新读取。 |
+| `/profile status` | 显示当前 profile、解析出的资源与路径、overlay、MCP server 状态以及冲突。 |
+| `/profile overlay disable\|enable skill\|extension\|mcp\|tool <name-or-glob>` | 只对当前会话收窄或恢复资源。 |
+| `/profile overlay clear` | 去掉 overlay，按 profile 本来的写法运行。 |
 
-所有命令在非交互模式（`--mode rpc|print|json`）下同样生效；裸 `/profile` 在无交互界面时降级为 profile 列表。overlay 是会话级收窄：绝不写入 catalog 文件，也不会跨重启保留。tool 与其他资源类别使用相同的 disable/enable 模型：tool `disable` 条目收窄 profile 解析出的工具引用；profile 未声明 `tools` 时，则收窄运行时的全部可用工具集。
+以上命令在所有模式下都可用，包括非交互模式（`--mode text`、`--mode json`、`--mode rpc`）。overlay 只作用于当前运行期：不会写入 profile 文件，重启后即消失。内建的 `default` profile 不能用 overlay 禁用 MCP server——它没有可供收窄的 MCP 白名单。
 
 ## 文档
 
-- [架构设计](docs/architecture/overview.md) · [ADR](docs/adr/) · [术语表](CONTEXT.md)
-- JSON Schema：[`schemas/`](schemas/)
+- 字段参考：[`schemas/profiles.schema.json`](schemas/profiles.schema.json)
+- 架构与术语：[`docs/architecture/overview.md`](docs/architecture/overview.md)、[`CONTEXT.md`](CONTEXT.md)
+- 设计决策：[`docs/adr/`](docs/adr/)
+- Profile 编写指南：[`skills/profile-config/SKILL.md`](skills/profile-config/SKILL.md)
 
-## 许可证
+## License
 
 MIT

package/bin/pi-profile.ts

@@ -67,6 +67,9 @@ try {
 		console.error(`pi-profile: warning: ${warning}`);
 	}
 	const generated = await generateRuntimeDir(plan, { agentDir, discovery, projectDir });
+	for (const warning of generated.warnings) {
+		console.error(`pi-profile: warning: ${warning}`);
+	}
 	process.exitCode = await spawnPi({
 		generated,
 		piArgs: args.piArgs,

package/extensions/pi-profile/index.ts

@@ -224,7 +224,17 @@ export default function piProfileExtension(pi: ExtensionAPI): void {
 					const mcpDiscovery = await loadMergedMcpServers(
 						plan.agentDir,
 						projectTrusted ? ctx.cwd : undefined,
+						{
+							invalidSource:
+								plan.mcps !== undefined ||
+								(plan.mcpTools !== undefined && Object.keys(plan.mcpTools).length > 0)
+									? "throw"
+									: "diagnose",
+						},
 					);
+					for (const diagnostic of mcpDiscovery.diagnostics ?? []) {
+						notify(diagnostic, "warning");
+					}
 					const discoveredMcpServers = Object.keys(mcpDiscovery.servers).sort();
 					const disabledMcpServers = discoveredMcpServers.filter(
 						(server) => mcpDiscovery.servers[server]?.enabled === false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-profile-switch",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "Named profiles for Pi: reference skills, extensions, MCP servers, and tools per workflow, switched without restarting. Install: npm install -g pi-profile-switch (not pi install).",
   "type": "module",
   "keywords": [
@@ -30,10 +30,10 @@
     "test:watch": "vitest"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
+    "@earendil-works/pi-coding-agent": ">=0.99.1"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-coding-agent": ">=0.99.1",
     "@types/node": "^24.0.0",
     "ajv": "^8.20.0",
     "typescript": "^5.8.0",

package/src/launcher/initial-profile.ts

@@ -169,7 +169,7 @@ export async function resolveInitialProfile(
 		(options?.overlay?.disabledMcps?.length ?? 0) > 0,
 	);
 	const mcpDiscovery = needsMcp
-		? await loadMergedMcpServers(context.agentDir, projectDir)
+		? await loadMergedMcpServers(context.agentDir, projectDir, { invalidSource: "throw" })
 		: undefined;
 
 	const plan = await resolveProfile({

package/src/launcher/spawn.ts

@@ -3,8 +3,8 @@
  *
  * The spawned pi gets: the pi-profile extension via `-e` and the user's
  * arguments verbatim. stdio is inherited so interactive
- * TUI, RPC, and print modes all behave natively; exit codes and signals
- * propagate.
+ * TUI, text, JSON, and RPC modes all behave natively; exit codes and
+ * signals propagate.
  */
 
 import { spawn } from "node:child_process";

package/src/mcp-config.ts

@@ -13,8 +13,10 @@
  * (read for ownership classification only — Pi reads the file itself).
  * The legacy project-root `.mcp.json` source is not read.
  *
- * Malformed config files fail loudly — a broken mcp.json must not silently
- * read as "no servers" and reject every reference.
+ * Malformed config files follow the discovery tier: strict mode throws
+ * `McpConfigError` (a broken mcp.json must not silently read as "no servers"
+ * under an explicit MCP policy); diagnostic mode skips the malformed source
+ * with a path-bearing diagnostic so valid sources still merge.
  */
 
 import { homedir } from "node:os";
@@ -34,6 +36,10 @@ export class McpConfigError extends Error {
 
 export interface McpDiscoveryOptions {
 	homeDir?: string;
+	/** How an unreadable or malformed source is handled. "throw" (default)
+	 *  fails discovery with `McpConfigError`; "diagnose" skips the source and
+	 *  records a path-bearing diagnostic so valid sources still merge. */
+	invalidSource?: "throw" | "diagnose";
 }
 
 export interface MergedMcpResult {
@@ -48,6 +54,10 @@ export interface MergedMcpResult {
 	/** The merged user-level configuration object, with later sources
 	 *  overriding earlier ones per server name. */
 	baseConfig?: Record<string, unknown>;
+	/** Path-bearing diagnostics for sources skipped in "diagnose" mode.
+	 *  Always populated by `loadMergedMcpServers`; absent from hand-built
+	 *  discovery fixtures. */
+	diagnostics?: string[];
 }
 
 function setOwnRecordValue<T>(record: Record<string, T>, key: string, value: T): void {
@@ -98,14 +108,19 @@ export async function loadMergedMcpServers(
 	projectDir?: string,
 	options?: McpDiscoveryOptions,
 ): Promise<MergedMcpResult> {
+	const invalidSource = options?.invalidSource ?? "throw";
 	const sources = getStandardMcpConfigSources(agentDir, projectDir, options);
 	const seenPaths = new Set<string>();
 	const servers: Record<string, Record<string, unknown>> = {};
 	const sharedServers = new Set<string>();
 	const projectServers = new Set<string>();
 	const serverOwners: Record<string, "user" | "project"> = {};
+	const diagnostics: string[] = [];
 	let baseConfig: Record<string, unknown> | undefined;
 
+	/** Strict mode fails discovery; diagnostic mode records the path and
+	 *  skips only that source, leaving valid sources available. */
+
 	for (const source of sources) {
 		const resolvedPath = path.resolve(source.path);
 		if (seenPaths.has(resolvedPath)) continue;
@@ -114,11 +129,26 @@ export async function loadMergedMcpServers(
 		const result = await readJsonFile(resolvedPath);
 		if (!result.ok) {
 			if (result.reason === "missing") continue;
+			if (invalidSource === "diagnose") {
+				diagnostics.push(`MCP config is not valid JSON: ${resolvedPath}`);
+				continue;
+			}
 			throw new McpConfigError(`MCP config is not valid JSON: ${resolvedPath}`, resolvedPath);
 		}
 		if (!isRecord(result.value)) {
+			if (invalidSource === "diagnose") {
+				diagnostics.push(`MCP config must be a JSON object: ${resolvedPath}`);
+				continue;
+			}
 			throw new McpConfigError(`MCP config must be a JSON object: ${resolvedPath}`, resolvedPath);
 		}
+		if (result.value.mcpServers !== undefined && !isRecord(result.value.mcpServers)) {
+			if (invalidSource === "diagnose") {
+				diagnostics.push(`"mcpServers" must be a JSON object: ${resolvedPath}`);
+				continue;
+			}
+			throw new McpConfigError(`"mcpServers" must be a JSON object: ${resolvedPath}`, resolvedPath);
+		}
 
 		if (!source.isProject) {
 			// Merge user-level base configuration: later sources override
@@ -128,9 +158,6 @@ export async function loadMergedMcpServers(
 		}
 
 		if (result.value.mcpServers === undefined) continue;
-		if (!isRecord(result.value.mcpServers)) {
-			throw new McpConfigError(`"mcpServers" must be a JSON object: ${resolvedPath}`, resolvedPath);
-		}
 		for (const [name, def] of Object.entries(result.value.mcpServers)) {
 			// Align discovery with JSON semantics: inherited prototype keys are
 			// never treated as discoverable server names.
@@ -140,11 +167,13 @@ export async function loadMergedMcpServers(
 			}
 			if (source.isProject === true) projectServers.add(name);
 			setOwnRecordValue(serverOwners, name, source.isProject === true ? "project" : "user");
-			const previous = Object.hasOwn(servers, name) ? servers[name] : undefined;
-			const merged = isRecord(def) ? { ...(previous ?? {}), ...def } : { ...(previous ?? {}) };
-			setOwnRecordValue(servers, name, merged);
+			// Whole-definition precedence: a later definition replaces the same-named
+			// server entirely. Connection, credential, and exposure fields are never
+			// inherited from an earlier source, so a later URL cannot pick up an
+			// earlier authorization header (D1).
+			setOwnRecordValue(servers, name, isRecord(def) ? { ...def } : {});
 		}
 	}
 
-	return { servers, sharedServers, projectServers, serverOwners, baseConfig };
+	return { servers, sharedServers, projectServers, serverOwners, baseConfig, diagnostics };
 }

package/src/profile-resolver.ts

@@ -48,11 +48,27 @@ export class ActivationError extends Error {
 	}
 }
 
-/** Pi's built-in tool names (pi 0.85.1 `allToolNames`; not exported by the
+/** Pi's built-in tool names (pi 0.99.2 `allToolNames`; not exported by the
  *  SDK). The integration suite guards drift. Literal tool names pass through
  *  regardless — extension-provided tools are unknowable before spawn. */
 export const BUILTIN_TOOL_NAMES = ["read", "bash", "powershell", "edit", "write", "grep", "find", "ls"] as const;
 
+/** User-level, enabled MCP server names, sorted — the set a profile can
+ *  actually select via `mcps` or narrow via `mcp_tools`. Project-owned and
+ *  source-disabled servers are not usable candidates. */
+function userLevelMcpCandidates(mcpDiscovery: MergedMcpResult): string[] {
+	return Object.keys(mcpDiscovery.servers)
+		.filter((s) => {
+			const isUser =
+				Object.hasOwn(mcpDiscovery.serverOwners, s) &&
+				mcpDiscovery.serverOwners[s] === "user" &&
+				!mcpDiscovery.projectServers.has(s);
+			const isEnabled = mcpDiscovery.servers[s]?.enabled !== false;
+			return isUser && isEnabled;
+		})
+		.sort();
+}
+
 const VALID_THINKING_LEVELS = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
 
 /** Immutable, fully resolved activation set. */
@@ -182,7 +198,12 @@ function expandReferences<T>(
 	universe: readonly T[],
 	nameOf: (item: T) => string,
 	kind: string,
-	options?: { literalMustExist?: boolean; onZeroMatch?: (reference: string) => void },
+	options?: {
+		literalMustExist?: boolean;
+		onZeroMatch?: (reference: string) => void;
+		/** Custom literal-miss failure (e.g. with near-miss candidates). Throws. */
+		literalMissError?: (reference: string) => never;
+	},
 ): T[] {
 	const selected = new Map<string, T>();
 	for (const reference of references) {
@@ -204,6 +225,10 @@ function expandReferences<T>(
 				selected.set(reference, reference as T);
 				continue;
 			}
+			const missError = options?.literalMissError;
+			if (missError !== undefined) {
+				missError(reference);
+			}
 			throw new ActivationError(`unknown ${kind}: "${reference}" does not match any discovered ${kind}`);
 		}
 		selected.set(reference, item);
@@ -250,6 +275,17 @@ export async function resolveProfile(input: ResolveInput): Promise<ActivationPla
 			}
 			mcps = expandReferences(definition.mcps, input.discoveredMcpServers, (name) => name, "MCP server", {
 				onZeroMatch: (reference) => unmatched.push(`mcp:${reference}`),
+				literalMissError: (reference) => {
+					const candidates =
+						input.mcpDiscovery !== undefined
+							? userLevelMcpCandidates(input.mcpDiscovery)
+							: [...(input.discoveredMcpServers ?? [])].sort();
+					const suffix =
+						candidates.length > 0
+							? ` (usable candidates: ${candidates.join(", ")})`
+							: " (no user-level servers are discovered)";
+					throw new ActivationError(`unknown MCP server: "${reference}"${suffix}`);
+				},
 			});
 			if (input.mcpDiscovery !== undefined) {
 				const discovery = input.mcpDiscovery;
@@ -327,17 +363,9 @@ export async function resolveProfile(input: ResolveInput): Promise<ActivationPla
 		}
 
 		const mcpDiscovery = input.mcpDiscovery;
-		const usableCandidates = Object.keys(mcpDiscovery.servers)
-			.filter((s) => {
-				const isUser =
-					Object.hasOwn(mcpDiscovery.serverOwners, s) &&
-					mcpDiscovery.serverOwners[s] === "user" &&
-					!mcpDiscovery.projectServers.has(s);
-				const isEnabled = mcpDiscovery.servers[s]?.enabled !== false;
-				const isAllowedByMcps = mcps === undefined || mcps.includes(s);
-				return isUser && isEnabled && isAllowedByMcps;
-			})
-			.sort();
+		const usableCandidates = userLevelMcpCandidates(mcpDiscovery).filter(
+			(s) => mcps === undefined || mcps.includes(s),
+		);
 		const candidateMsg = usableCandidates.length > 0 ? ` (usable candidates: ${usableCandidates.join(", ")})` : "";
 
 		for (const serverKey of mcpToolKeys) {
@@ -479,6 +507,14 @@ export function buildInstanceMcpConfig(
 			mcpDiscovery.serverOwners[serverName] === "project" || mcpDiscovery.projectServers.has(serverName);
 		if (isProjectOwned) continue;
 
+		// A selected server the winning source explicitly disables fails with a
+		// fix, never a silent enablement override (D1).
+		if (mcps?.includes(serverName) === true && originalDef.enabled === false) {
+			throw new ActivationError(
+				`profile "${profileName}": selected MCP server "${serverName}" is disabled in its source configuration; enable it there or remove it from "mcps"`,
+			);
+		}
+
 		// A server explicitly selected by mcps whose definition uses a
 		// transport Pi's built-in MCP extension cannot use fails activation.
 		if (mcps?.includes(serverName) === true && originalDef.type === "sse") {
@@ -502,11 +538,14 @@ export function buildInstanceMcpConfig(
 		setOwnRecordValue(filteredServers, serverName, def);
 	}
 
-	// Unselected user-level servers are explicitly disabled.
+	// Unselected user-level servers keep their complete winning definition and
+	// are explicitly disabled. Pi validates the transport before `enabled`, so
+	// a transport-less placeholder would warn on every valid disabled server.
 	if (mcps !== undefined) {
 		for (const userName of userServers) {
 			if (mcps.includes(userName)) continue;
-			setOwnRecordValue(filteredServers, userName, { enabled: false });
+			const unselectedDef = mcpDiscovery.servers[userName] ?? {};
+			setOwnRecordValue(filteredServers, userName, { ...unselectedDef, enabled: false });
 		}
 	}
 

package/src/settings-generator.ts

@@ -48,7 +48,7 @@ import path from "node:path";
 import { buildInstanceMcpConfig, type ActivationPlan } from "./profile-resolver.ts";
 import { getInstancesRootDir } from "./workspace.ts";
 import { isRecord } from "./json-file.ts";
-import { loadMergedMcpServers } from "./mcp-config.ts";
+import { loadMergedMcpServers, type MergedMcpResult } from "./mcp-config.ts";
 import type { SkillEntry } from "./skill-registry.ts";
 
 /** A configured global package and its resolved install/local root. */
@@ -83,6 +83,9 @@ export interface GeneratedRuntime {
 	runtimeDir: string;
 	/** Environment variables for the spawned pi process. */
 	env: Record<string, string>;
+	/** Non-fatal diagnostics (e.g. malformed MCP sources skipped under an
+	 *  undeclared MCP policy). The launcher prints them on stderr. */
+	warnings: string[];
 }
 
 /** Files managed explicitly by pi-profile in runtimeDir; excluded from auto-symlinking. */
@@ -193,6 +196,32 @@ function userSkillExclusions(userSkills: unknown, agentDir: string, runtimeDir:
 	return exclusions;
 }
 
+/** Pi's built-in MCP discovery entry points (see installed Pi
+ *  `dist/extensions/mcp/index.js`, `codemode/tool.js`, `tool-search/tool.js`).
+ *  These are the tools a narrowed `tools` profile must keep reachable when an
+ *  MCP server is enabled; their identities are Pi's, not a profile field. */
+const MCP_GATEWAY_TOOL_NAMES = ["codemode", "tool_search"] as const;
+
+/** Whether the prepared effective MCP set contains at least one enabled
+ *  server (user-level snapshot entries with `enabled !== false`, plus any
+ *  enabled trusted-project server Pi reads itself). */
+function hasEnabledMcpServer(
+	instanceMcpConfig: Record<string, unknown>,
+	discovery: MergedMcpResult,
+): boolean {
+	const snapshotServers = instanceMcpConfig.mcpServers;
+	if (isRecord(snapshotServers)) {
+		for (const def of Object.values(snapshotServers)) {
+			if (isRecord(def) && def.enabled !== false) return true;
+		}
+	}
+	for (const name of discovery.projectServers) {
+		const def = discovery.servers[name];
+		if (def !== undefined && def.enabled !== false) return true;
+	}
+	return false;
+}
+
 function buildSelectionSettings(
 	plan: ActivationPlan,
 	userSettings: Record<string, unknown>,
@@ -405,14 +434,47 @@ export interface ResolvedNames {
 /** Writes settings.json + pi-profile.json into an existing runtime dir and
  *  keeps the trust.json link in place for every profile: Pi reads its
  *  project-scope decision from that path, and project-level resources belong
- *  to Pi's trust gate rather than to the profile. */
+ *  to Pi's trust gate rather than to the profile.
+ *
+ *  All generated content (settings, launch plan, MCP snapshot, diagnostics)
+ *  is prepared in memory before any runtime file is touched, so a discovery
+ *  failure can never leave a half-written runtime dir (D3). */
 export async function writeRuntimeFiles(
 	runtimeDir: string,
 	plan: ActivationPlan,
 	options: RuntimeFileOptions,
-): Promise<void> {
+): Promise<{ warnings: string[] }> {
+	const warnings: string[] = [];
 	const settings = await computeSettings(plan, options, runtimeDir);
-	await writeFile(path.join(runtimeDir, "settings.json"), `${JSON.stringify(settings, null, 2)}\n`);
+
+	// Prepare the MCP snapshot and diagnostics before the write stage. A
+	// declared mcps or nonempty mcp_tools policy is strict; an undeclared
+	// policy diagnoses malformed sources by path and keeps valid ones (D2).
+	const hasMcpPolicy =
+		plan.mcps !== undefined || (plan.mcpTools !== undefined && Object.keys(plan.mcpTools).length > 0);
+	const discovery = await loadMergedMcpServers(
+		options.agentDir,
+		options.projectDir,
+		{
+			...(options.homeDir !== undefined ? { homeDir: options.homeDir } : {}),
+			invalidSource: hasMcpPolicy ? "throw" : "diagnose",
+		},
+	);
+	warnings.push(...(discovery.diagnostics ?? []));
+	const instanceMcpConfig = buildInstanceMcpConfig(plan.profile, discovery, plan.mcps, plan.mcpTools);
+
+	// When a profile narrows `tools` and the effective MCP set still has an
+	// enabled server, keep Pi's native MCP discovery entry points reachable
+	// (D4). The marker drives the session-start preservation; the
+	// defaultTools baseline covers the boot window before session_start.
+	const mcpGateways = plan.tools !== undefined && hasEnabledMcpServer(instanceMcpConfig, discovery);
+	if (mcpGateways) {
+		const current = Array.isArray(settings.defaultTools) ? (settings.defaultTools as string[]) : [];
+		settings.defaultTools = [
+			...current,
+			...MCP_GATEWAY_TOOL_NAMES.filter((name) => !current.includes(name)),
+		];
+	}
 
 	// The launch plan feeds the in-pi extension: tool re-application after
 	// reload (the tools strict allowlist), in-session switching, status
@@ -420,33 +482,31 @@ export async function writeRuntimeFiles(
 	// agentDir is the REAL agent dir — the extension needs it for trust
 	// checks, state files, and catalog reads (its own
 	// PI_CODING_AGENT_DIR points at this runtime dir).
-	await writeFile(
-		path.join(runtimeDir, "pi-profile.json"),
-		`${JSON.stringify(
-			{
-				profile: plan.profile,
-				source: plan.source,
-				agentDir: options.agentDir,
-				...(plan.tools !== undefined ? { tools: plan.tools } : {}),
-				...(plan.toolReferences !== undefined ? { toolReferences: plan.toolReferences } : {}),
-				...(plan.disabledTools !== undefined ? { disabledTools: plan.disabledTools } : {}),
-				...(plan.mcps !== undefined ? { mcps: plan.mcps } : {}),
-				...(plan.mcpTools !== undefined ? { mcpTools: plan.mcpTools } : {}),
-				// The resolved sets feed /profile status (absolute paths) and the
-				// glob-delta diff against the previous activation.
-				resolved: {
-					skills: plan.skills.map((skill) => ({ name: skill.name, filePath: skill.filePath })),
-					extensions: plan.extensions,
-				},
-				// Zero-match glob references (ADR-0009) — surfaced by /profile status
-				// so a typo'd glob is visible instead of silently selecting nothing.
-				...(plan.unmatched !== undefined ? { unmatched: plan.unmatched } : {}),
-				...options.planExtras,
-			},
-			null,
-			2,
-		)}\n`,
-	);
+	const launchPlan = {
+		profile: plan.profile,
+		source: plan.source,
+		agentDir: options.agentDir,
+		...(plan.tools !== undefined ? { tools: plan.tools } : {}),
+		...(plan.toolReferences !== undefined ? { toolReferences: plan.toolReferences } : {}),
+		...(plan.disabledTools !== undefined ? { disabledTools: plan.disabledTools } : {}),
+		...(plan.mcps !== undefined ? { mcps: plan.mcps } : {}),
+		...(plan.mcpTools !== undefined ? { mcpTools: plan.mcpTools } : {}),
+		...(mcpGateways ? { mcpGateways: true } : {}),
+		// The resolved sets feed /profile status (absolute paths) and the
+		// glob-delta diff against the previous activation.
+		resolved: {
+			skills: plan.skills.map((skill) => ({ name: skill.name, filePath: skill.filePath })),
+			extensions: plan.extensions,
+		},
+		// Zero-match glob references (ADR-0009) — surfaced by /profile status
+		// so a typo'd glob is visible instead of silently selecting nothing.
+		...(plan.unmatched !== undefined ? { unmatched: plan.unmatched } : {}),
+		...options.planExtras,
+	};
+
+	// --- write stage: all content is ready; no reads re-run here. ---
+	await writeFile(path.join(runtimeDir, "settings.json"), `${JSON.stringify(settings, null, 2)}\n`);
+	await writeFile(path.join(runtimeDir, "pi-profile.json"), `${JSON.stringify(launchPlan, null, 2)}\n`);
 
 	// Every profile gets the link, dangling allowed: Pi's stored trust decision
 	// is what makes a trusted project's resources visible, and a decision Pi
@@ -460,20 +520,11 @@ export async function writeRuntimeFiles(
 
 	// MCP Servers generation: the instance mcp.json is always a generated
 	// snapshot of the merged user-level configuration; it is never a symlink
-	// or a copy of the real agentDir file (ADR-0016).
+	// or a copy of the real agentDir file (ADR-0016). The replacement content
+	// was prepared above, so the old file is removed only once its successor
+	// is ready to write.
 	const mcpInstancePath = path.join(runtimeDir, "mcp.json");
 	try { await rm(mcpInstancePath); } catch {}
-	const discovery = await loadMergedMcpServers(
-		options.agentDir,
-		options.projectDir,
-		options.homeDir !== undefined ? { homeDir: options.homeDir } : undefined,
-	);
-	const instanceMcpConfig = buildInstanceMcpConfig(
-		plan.profile,
-		discovery,
-		plan.mcps,
-		plan.mcpTools,
-	);
 	await writeFile(mcpInstancePath, JSON.stringify(instanceMcpConfig, null, 2));
 
 	// Instructions generation (Ticket 04)
@@ -486,6 +537,8 @@ export async function writeRuntimeFiles(
 
 	// Full-fidelity symlink mirroring and dangling link cleanup (Ticket 02).
 	await syncAgentSymlinks(options.agentDir, runtimeDir);
+
+	return { warnings };
 }
 
 /**
@@ -595,12 +648,13 @@ export async function generateRuntimeDir(
 	// their switches) rewrite each other's files (ADR-0010).
 	const runtimeDir = await mkdtemp(path.join(runtimeRoot, "launch-"));
 
-	await writeRuntimeFiles(runtimeDir, plan, options);
+	const { warnings } = await writeRuntimeFiles(runtimeDir, plan, options);
 
 	return {
 		runtimeDir,
 		env: {
 			PI_CODING_AGENT_DIR: runtimeDir,
 		},
+		warnings,
 	};
 }

package/src/startup-notifier.ts

@@ -4,7 +4,7 @@
  * Two independent sources, checked once per Pi process launch and presented
  * through a caller-supplied NoticeSurface:
  *
- * - npm package metadata: compare the running package version against the
+ * - npm dist-tags: compare the running package version against the
  *   registry's installable `latest` dist-tag and remind once per target
  *   version (design decision 2: authority and cache).
  * - a single maintainer-reviewed `announcements.json` feed (design decision
@@ -30,9 +30,9 @@ import { isRecord } from "./json-file.ts";
 export const ANNOUNCEMENTS_URL =
 	"https://raw.githubusercontent.com/VincentFF/pi-profile-switch/main/announcements.json";
 
-/** npm registry package metadata; the installable stable version is read
- *  from `dist-tags.latest`, never from the largest published version. */
-const NPM_METADATA_URL = "https://registry.npmjs.org/pi-profile-switch";
+/** npm registry dist-tags; the installable stable version is read from
+ *  top-level `latest`, never from the largest published version. */
+const NPM_DIST_TAGS_URL = "https://registry.npmjs.org/-/package/pi-profile-switch/dist-tags";
 
 /** Hard ceiling on one remote check; the timer is unref'd so a pending
  *  check never keeps a short-lived Pi process alive. */
@@ -261,10 +261,10 @@ function parseNpmLatest(text: string): string {
 	} catch {
 		throw new InvalidContentError("response is not valid JSON");
 	}
-	if (!isRecord(raw) || !isRecord(raw["dist-tags"]) || typeof raw["dist-tags"].latest !== "string") {
-		throw new InvalidContentError("missing dist-tags.latest");
+	if (!isRecord(raw) || typeof raw.latest !== "string") {
+		throw new InvalidContentError("missing latest");
 	}
-	const latest = raw["dist-tags"].latest;
+	const latest = raw.latest;
 	if (parseVersion(latest) === undefined) {
 		throw new InvalidContentError(`malformed latest version: ${JSON.stringify(latest)}`);
 	}
@@ -574,7 +574,7 @@ async function run(options: StartupNotifierOptions): Promise<void> {
 		const refreshedNpm = await refreshSource<{ latest: string }>({
 			dir,
 			name: "npm-latest",
-			url: NPM_METADATA_URL,
+			url: NPM_DIST_TAGS_URL,
 			label: "npm registry",
 			cache: npmCache,
 			parse: (text) => ({ latest: parseNpmLatest(text) }),

package/src/switching/apply-plan.ts

@@ -49,6 +49,11 @@ export interface LaunchPlanFile {
 	disabledTools?: string[];
 	mcps?: string[];
 	mcpTools?: Record<string, string[]>;
+	/** Marks a narrowed `tools` profile whose effective MCP set still has an
+	 *  enabled server; session start must retain Pi's native MCP discovery
+	 *  entry points (codemode / tool_search) if they were natively
+	 *  registered (D4). */
+	mcpGateways?: boolean;
 	switchedFrom?: string;
 	persistSelection?: boolean;
 	clearOverlay?: boolean;
@@ -99,6 +104,14 @@ export function isMcpOwnedTool(tool: {
 	return info.path === "builtin:mcp";
 }
 
+/** Pi's native MCP discovery entry points and their built-in source paths
+ *  (see installed Pi `dist/extensions/index.js`). A same-named tool from any
+ *  other source is never treated as an MCP gateway. */
+const MCP_GATEWAYS = [
+	{ name: "codemode", sourcePath: "builtin:codemode" },
+	{ name: "tool_search", sourcePath: "builtin:tool-search" },
+] as const;
+
 /** Applies the plan carried by the runtime dir's pi-profile.json. */
 export async function applyLaunchPlan(input: {
 	runtimeDir: string;
@@ -116,7 +129,7 @@ export async function applyLaunchPlan(input: {
 
 	// --- tools ---
 	const hasOverlayDisables = plan.disabledTools !== undefined && plan.disabledTools.length > 0;
-	if (plan.toolReferences !== undefined || hasOverlayDisables) {
+	if (plan.toolReferences !== undefined || hasOverlayDisables || plan.mcpGateways === true) {
 		const allTools = surface.getAllTools();
 		const mcpToolNames: string[] = [];
 		const nonMcpToolNames: string[] = [];
@@ -155,6 +168,7 @@ export async function applyLaunchPlan(input: {
 			active = allTools.map((tool) => tool.name);
 		}
 
+		const disabledSet = new Set<string>();
 		if (hasOverlayDisables) {
 			const allLiveNames = allTools.map((tool) => tool.name);
 			const { expanded: disabled, droppedLiterals: vanishedEntries } = expandToolReferences(
@@ -167,9 +181,33 @@ export async function applyLaunchPlan(input: {
 					`profile "${plan.profile}": overlay tool entries ${vanishedEntries.map((name) => JSON.stringify(name)).join(", ")} match nothing in Pi's live registry`,
 				);
 			}
-			const disabledSet = new Set(disabled);
+			for (const name of disabled) disabledSet.add(name);
 			active = active.filter((name) => !disabledSet.has(name));
 		}
+
+		// Native MCP discovery entry points stay reachable for narrowed `tools`
+		// profiles when the plan marked them (D4). Only the built-in
+		// registration counts; an explicit overlay disable still wins.
+		if (plan.mcpGateways === true) {
+			for (const gateway of MCP_GATEWAYS) {
+				if (disabledSet.has(gateway.name)) continue;
+				const registered = allTools.find((tool) => tool.name === gateway.name);
+				if (registered === undefined) {
+					warnings.push(
+						`profile "${plan.profile}": MCP entry point ${JSON.stringify(gateway.name)} is unavailable because its built-in extension did not register it`,
+					);
+					continue;
+				}
+				if (registered.sourceInfo?.path === gateway.sourcePath) {
+					if (!active.includes(gateway.name)) active.push(gateway.name);
+				} else {
+					warnings.push(
+						`profile "${plan.profile}": MCP entry point ${JSON.stringify(gateway.name)} is registered by ${registered.sourceInfo?.path ?? "an unknown source"}, not the built-in extension; it was not used as an MCP gateway`,
+					);
+				}
+			}
+		}
+
 		surface.setActiveTools(active);
 	}
 

package/src/switching/switch-profile.ts

@@ -204,22 +204,7 @@ export async function switchProfile(
 					...(previousPlan.mcps !== undefined ? { mcps: previousPlan.mcps } : {}),
 				}
 			: undefined;
-	await writeRuntimeFiles(deps.runtimeDir, resolved.plan, {
-		agentDir: deps.realAgentDir,
-		projectDir: resolved.projectDir,
-		discovery: resolved.discovery,
-		planExtras: {
-			...(isSwitch && current.profile !== undefined ? { switchedFrom: current.profile } : {}),
-			// `/profile use` persists; `/profile reload` keeps the current
-			// profile's existing persistence (launch selections stay transient).
-			persistSelection: options?.reloadCurrent === true ? current.persistSelection : true,
-			// A switch discards the previous profile's overlay; the post-reload
-			// instance drops it from the state file. Customize/reset manage the
-			// overlay directly and never set this.
-			...(options?.clearOverlay === true ? { clearOverlay: true } : {}),
-			...(previousResolved !== undefined ? { previousResolved } : {}),
-		},
-	});
+	const warnings = [...resolved.warnings];
 
 	const rollback = async (cause: string): Promise<never> => {
 		// Restore the verified snapshot and reload again — the runtime must
@@ -236,7 +221,26 @@ export async function switchProfile(
 		);
 	};
 
+	// The write-and-reload interval is one rollback boundary: a failure in any
+	// write after the first, or in reload, restores every managed file (D3).
 	try {
+		const written = await writeRuntimeFiles(deps.runtimeDir, resolved.plan, {
+			agentDir: deps.realAgentDir,
+			projectDir: resolved.projectDir,
+			discovery: resolved.discovery,
+			planExtras: {
+				...(isSwitch && current.profile !== undefined ? { switchedFrom: current.profile } : {}),
+				// `/profile use` persists; `/profile reload` keeps the current
+				// profile's existing persistence (launch selections stay transient).
+				persistSelection: options?.reloadCurrent === true ? current.persistSelection : true,
+				// A switch discards the previous profile's overlay; the post-reload
+				// instance drops it from the state file. Customize/reset manage the
+				// overlay directly and never set this.
+				...(options?.clearOverlay === true ? { clearOverlay: true } : {}),
+				...(previousResolved !== undefined ? { previousResolved } : {}),
+			},
+		});
+		warnings.push(...written.warnings);
 		await deps.reload();
 	} catch (error) {
 		await rollback(error instanceof Error ? error.message : String(error));
@@ -257,5 +261,5 @@ export async function switchProfile(
 		}
 	}
 
-	return { profile: resolved.plan.profile, warnings: resolved.warnings };
+	return { profile: resolved.plan.profile, warnings };
 }