pi-profile-switch 0.4.6 → 0.4.9

package/README.md

@@ -2,9 +2,7 @@
 
 [English](README.md) | [中文](README.zh-CN.md)
 
-Named profiles for [Pi](https://github.com/badlogic/pi-mono). A profile references a set of existing skills, extensions, MCP servers, and tools — switch between them in the same Pi process, without restarting.
-
-Use a read-only profile for Q&A and code exploration, a full-powered one for implementation — all against the same installed resources.
+Named profiles for [Pi](https://github.com/badlogic/pi-mono). A profile is a named capability bundle you define: skills, extensions, MCP servers, tools (including tools exposed by MCP servers and extensions), model defaults, and extra system-prompt instructions. Switch bundles inside a running Pi session — no restart.
 
 ## Install
 
@@ -27,7 +25,18 @@ pi-profile ask
 pi-profile ask -- --model openai/gpt-5.4
 ```
 
-On install, pi-profile-switch seeds `~/.pi-profile-switch/profiles.json` (global, fallback to `~/.pi/agent/profiles.json` for migration; custom root via `PI_PROFILE_SWITCH_DIR`) with a starter **`ask`** profile — read-only Q&A and code exploration. It assumes nothing about your setup; edit or delete it freely:
+## Define your own profiles
+
+Profiles live in two JSON files, both optional:
+
+| File | Scope |
+| --- | --- |
+| `~/.pi-profile-switch/profiles.json` | Global, all projects. `PI_PROFILE_SWITCH_DIR` overrides the root; `~/.pi/agent/profiles.json` is read as a legacy fallback for migration. |
+| `<project>/.pi/profiles.json` | Project-level, trusted projects only. |
+
+Create or change a profile by editing the JSON directly — schema: [`schemas/profiles.schema.json`](schemas/profiles.schema.json).
+
+On install, pi-profile-switch seeds the global file with a starter **`ask`** profile — read-only Q&A and code exploration. It assumes nothing about your setup; edit or delete it freely:
 
 ```json
 {
@@ -45,7 +54,56 @@ On install, pi-profile-switch seeds `~/.pi-profile-switch/profiles.json` (global
 }
 ```
 
-Project-level profiles live in `<project>/.pi/profiles.json` (trusted projects only). Profiles **reference** resources by name — they never copy them. Installed packages and files in standard locations are discovered automatically; no registration needed. Complete configuration examples live in [`examples/`](examples/): `profiles.json` is the seeded starter above, and `example.json` demonstrates every available field (skills, extensions, MCP servers, tools, model defaults, instructions).
+One profile can use every field at once. This example `impl` profile loads the TDD skill, the mcp-scripting skill (shipped by pi-mcp-adapter), and your internal skills; wires up two MCP servers; allows the built-in tools plus both servers' MCP tools by glob; and pins the model and standing instructions:
+
+```json
+{
+  "schemaVersion": 1,
+  "profiles": {
+    "impl": {
+      "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",
+        "mcp__*",
+        "github_*",
+        "linear_*"
+      ],
+      "defaultProvider": "anthropic",
+      "defaultModel": "claude-sonnet-4-5",
+      "defaultThinkingLevel": "high",
+      "instructions": "Prefer small, verifiable changes. Run the test suite before claiming completion."
+    }
+  }
+}
+```
+
+How fields resolve:
+
+- `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 against Pi's live tool registry — built-ins, extension-provided tools, and tools exposed by MCP servers. MCP tools are registered as `mcp__<server>` (proxy) and `<server>_<tool>` (direct tools, the adapter's default `toolPrefix`), so globs like `mcp__*` and `github_*` cover them.
+- `mcps` references servers from your pi-mcp-adapter configuration; connection details stay in the adapter's own config.
+- Any field you omit keeps plain Pi behavior.
+
+The files in [`examples/`](examples/) mirror the two profiles above: `profiles.json` is the seeded starter, `example.json` the full-field demo.
 
 ## Commands
 
@@ -61,12 +119,6 @@ In the TUI, the `/profile` command family manages everything in-session:
 
 All commands work in non-interactive modes (`--mode rpc|print|json`); CRUD wizards are TUI-only.
 
-## Guarantees
-
-- **Reference, never copy** — profiles point at resources you already own and maintain.
-- **Pi-native** — anything a profile doesn't explicitly control keeps plain Pi behavior.
-- **Fail safe** — untrusted project directories are never read; a failed switch rolls back to the last working configuration.
-
 ## Docs
 
 - [Architecture](docs/architecture/overview.md) · [ADRs](docs/adr/) · [Glossary](CONTEXT.md) (Chinese)

package/README.zh-CN.md

@@ -2,9 +2,7 @@
 
 [English](README.md) | [中文](README.zh-CN.md)
 
-[Pi](https://github.com/badlogic/pi-mono) 的命名 profile 扩展。一个 profile 引用一组已存在的 skills、extensions、MCP server 和 tools，并在同一 Pi 进程内切换，无需重启。
-
-问答与代码走读用只读 profile，实现需求用全量 profile——全部基于同一套已安装的资源。
+[Pi](https://github.com/badlogic/pi-mono) 的命名 profile 扩展。一个 profile 是你自定义的命名能力组合：skills、extensions、MCP server、tools（包括 MCP server 和 extension 提供的工具）、默认模型，以及追加到系统提示词的 instructions。在同一个运行中的 Pi 会话里切换这些组合，无需重启。
 
 ## 安装
 
@@ -27,7 +25,18 @@ pi-profile ask
 pi-profile ask -- --model openai/gpt-5.4
 ```
 
-安装时，pi-profile-switch 会向 `~/.pi-profile-switch/profiles.json`（全局，支持 `PI_PROFILE_SWITCH_DIR` 环境变量自定义，向下兼容 `~/.pi/agent/profiles.json`）写入一个初始 **`ask`** profile——只读的问答与代码走读模式。它不假设你安装过任何插件，可随意修改或删除：
+## 自定义 profile
+
+profile 定义在两个 JSON 文件中，均可选：
+
+| 文件 | 作用域 |
+| --- | --- |
+| `~/.pi-profile-switch/profiles.json` | 全局，对所有项目生效。`PI_PROFILE_SWITCH_DIR` 可自定义根目录；`~/.pi/agent/profiles.json` 作为遗留路径向下兼容，用于迁移。 |
+| `<项目>/.pi/profiles.json` | 项目级，仅对已信任项目生效。 |
+
+直接编辑 JSON 即可创建或修改 profile——schema 见 [`schemas/profiles.schema.json`](schemas/profiles.schema.json)。
+
+安装时，pi-profile-switch 会向全局文件播种一个初始 **`ask`** profile——只读的问答与代码走读模式。它不假设你安装过任何插件，可随意修改或删除：
 
 ```json
 {
@@ -45,7 +54,56 @@ pi-profile ask -- --model openai/gpt-5.4
 }
 ```
 
-项目级 profile 定义在 `<项目>/.pi/profiles.json`（仅限已信任项目）。Profile 只**引用**资源，从不复制资源。已安装的包和标准目录下的文件会被自动发现，无需注册。完整配置案例见 [`examples/`](examples/)：`profiles.json` 即上面的初始 profile，`example.json` 演示全部可用字段（skills、extensions、MCP server、tools、默认模型、instructions）。
+一个 profile 可以同时使用全部字段。下面这个 `impl` profile 示例加载 TDD skill、mcp-scripting skill（pi-mcp-adapter 自带）和你的内部 skills；接入两个 MCP server；tool 白名单用 glob 覆盖内建工具和这两个 server 的 MCP 工具；并钉住模型与常驻 instructions：
+
+```json
+{
+  "schemaVersion": 1,
+  "profiles": {
+    "impl": {
+      "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",
+        "mcp__*",
+        "github_*",
+        "linear_*"
+      ],
+      "defaultProvider": "anthropic",
+      "defaultModel": "claude-sonnet-4-5",
+      "defaultThinkingLevel": "high",
+      "instructions": "Prefer small, verifiable changes. Run the test suite before claiming completion."
+    }
+  }
+}
+```
+
+字段解析规则：
+
+- `skills`、`extensions`、`mcps`、`tools` 接受名称或 glob（如 `"internal-*"`），引用你已安装或已配置的资源——profile 从不复制资源。已安装的包和标准目录下的文件会被自动发现，无需注册。
+- `tools` 针对 Pi 的实时工具注册表展开——内建工具、extension 提供的工具，以及 MCP server 暴露的工具。MCP 工具注册为 `mcp__<server>`（代理）和 `<server>_<tool>`（直接工具，adapter 默认 `toolPrefix`），因此 `mcp__*`、`github_*` 这类 glob 可以覆盖它们。
+- `mcps` 引用 pi-mcp-adapter 配置中的 server；连接细节留在 adapter 自己的配置里。
+- 未写的字段保持原生 Pi 行为。
+
+[`examples/`](examples/) 中的两个文件与上面一一对应：`profiles.json` 是播种的初始 profile，`example.json` 是全字段演示。
 
 ## 命令
 
@@ -61,12 +119,6 @@ pi-profile ask -- --model openai/gpt-5.4
 
 非交互模式（`--mode rpc|print|json`）下命令同样生效；CRUD 向导仅 TUI 可用。
 
-## 保证
-
-- **引用而非复制**——profile 指向你自己拥有和维护的资源。
-- **Pi 原生**——profile 未显式控制的一切保持原生 Pi 行为。
-- **失败安全**——未信任的项目目录从不读取；切换失败回滚到上一份可用配置。
-
 ## 文档
 
 - [架构设计](docs/architecture/overview.md) · [ADR](docs/adr/) · [术语表](CONTEXT.md)

package/examples/example.json

@@ -6,7 +6,8 @@
       "description": "Full-powered implementation profile: every available field, pinned model",
       "skills": [
         "tdd",
-        "internal-*"
+        "internal-*",
+        "mcp-scripting"
       ],
       "extensions": [
         "pi-mcp-adapter"
@@ -22,7 +23,10 @@
         "ls",
         "bash",
         "edit",
-        "write"
+        "write",
+        "mcp__*",
+        "github_*",
+        "linear_*"
       ],
       "defaultProvider": "anthropic",
       "defaultModel": "claude-sonnet-4-5",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-profile-switch",
-  "version": "0.4.6",
-  "description": "Named profiles for Pi: reference skills, extensions, MCP servers, and tools per workflow, switched without restarting.",
+  "version": "0.4.9",
+  "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": [
     "pi-package",

package/src/extension-discovery.ts

@@ -1,27 +1,34 @@
 /**
  * ExtensionDiscovery: implicit, read-only discovery of selectable extensions
- * (ADR-0006), so profiles can reference extensions without any
+ * (ADR-0006/0007), so profiles can reference extensions without any
  * registration step.
  *
- * Two implicit sources, both Pi-native and side-effect free:
- * - Configured user packages: each package's `package.json#pi.extensions`
- *   declares its extension entry files; the package name (or an alias like
- *   the `npm:` source string) is the profile-facing reference.
- * - Loose extension files: `<agentDir>/extensions/*.{ts,js}` and, for
- *   trusted projects, `<projectDir>/.pi/extensions/*.{ts,js}`, referenced by
- *   filename stem.
+ * Two implicit sources, both resolved by Pi itself:
+ * - Configured packages: `DefaultPackageManager.resolve()` expands each
+ *   package's `package.json#pi.extensions` (files, directories, globs, the
+ *   package's own `+`/`-`/`!` filters, `.gitignore` rules) exactly like the
+ *   spawned pi does at startup. The package name — or an alias such as the
+ *   `npm:` source string — is the profile-facing reference.
+ * - Loose extension files: `<agentDir>/extensions/**` and, for trusted
+ *   projects, `<projectDir>/.pi/extensions/**`, referenced by a path-derived
+ *   ID ("conventions", "guards/review").
  *
- * Discovery never executes extension code and never installs anything: a
- * package contributes entries only for declared files that exist on disk.
+ * This module owns naming, merging, selection, and glob expansion only. Entry
+ * enumeration is Pi's own, so a new Pi convention (or a fix to one) cannot
+ * silently diverge from what the spawned pi actually loads.
+ *
+ * Discovery stays side-effect free: `resolve()` is called with
+ * `onMissing: "skip"`, which never installs and never touches the network,
+ * and extension code is never imported.
  */
 
-import { readdir, readFile, stat } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
 
+import { DefaultPackageManager, SettingsManager, type PackageManager } from "@earendil-works/pi-coding-agent";
 import { minimatch } from "minimatch";
 
 import { isRecord } from "./json-file.ts";
-import type { ConfiguredPackageRoot } from "./settings-generator.ts";
 
 export interface DiscoveredPackage {
 	/** Selectable package name: package.json "name", or the source minus its
@@ -32,12 +39,14 @@ export interface DiscoveredPackage {
 	source: string;
 	/** Absolute install/local root of the package. */
 	root: string;
-	/** Absolute paths of declared `pi.extensions` entries that exist on disk. */
+	/** Absolute paths of the package's enabled extension entries. */
 	entries: string[];
 }
 
 export interface DiscoveredLocalExtension {
-	/** Selectable ID: the filename stem ("conventions" for conventions.ts). */
+	/** Selectable ID: the path under the extensions dir, without the file
+	 *  extension and with a trailing "/index" collapsed ("conventions",
+	 *  "guards/review"). */
 	id: string;
 	entry: string;
 }
@@ -72,7 +81,7 @@ function toPosix(filePath: string): string {
 	return filePath.split(path.sep).join("/");
 }
 
-async function exists(filePath: string): Promise<boolean> {
+async function isFile(filePath: string): Promise<boolean> {
 	try {
 		return (await stat(filePath)).isFile();
 	} catch {
@@ -205,7 +214,7 @@ export class DiscoveredExtensions {
 				const pkgEntries = this.#packageEntries(pkg);
 				if (pkgEntries.length === 0) {
 					throw new ExtensionError(
-						`package "${reference}" declares no extension entries (its pi.extensions files are missing or shadowed by local files)`,
+						`package "${reference}" declares no extension entries (missing on disk, filtered out by its settings package entry, or shadowed by local files)`,
 					);
 				}
 				for (const pkgEntry of pkgEntries) add(pkgEntry);
@@ -220,7 +229,7 @@ export class DiscoveredExtensions {
 				const resolved = reference.startsWith("~/")
 					? path.join(process.env.HOME ?? "", reference.slice(1))
 					: path.resolve(reference);
-				if (!(await exists(resolved))) {
+				if (!(await isFile(resolved))) {
 					throw new ExtensionError(`extension path not found: ${resolved}`);
 				}
 				add({ id: resolved, entry: resolved, origin: "path" });
@@ -233,8 +242,6 @@ export class DiscoveredExtensions {
 	}
 }
 
-const LOOSE_FILE_PATTERN = /\.(ts|js)$/;
-
 /** Derives a package name from its source string when package.json is
  *  unreadable: strips the npm:/git:/github: prefix and any version spec
  *  (scoped names keep their "@scope/" prefix). */
@@ -252,93 +259,141 @@ export function packageNameFromSource(source: string): string {
 	return name;
 }
 
-/** Reads one installed package's declared extension entries. Packages
- *  without a readable package.json or without `pi.extensions` contribute
- *  nothing (skills-only packages are the common case). Declared entries
- *  missing on disk are skipped — the spawned pi reports load errors itself. */
-async function readPackageExtensions(pkg: ConfiguredPackageRoot): Promise<DiscoveredPackage | undefined> {
-	if (pkg.root === undefined) return undefined;
-	let manifest: unknown;
-	try {
-		manifest = JSON.parse(await readFile(path.join(pkg.root, "package.json"), "utf8"));
-	} catch {
-		return undefined; // not installed yet or unreadable — nothing selectable
-	}
-	if (!isRecord(manifest)) return undefined;
-	const pi = manifest.pi;
-	const declared =
-		isRecord(pi) && Array.isArray(pi.extensions) ? pi.extensions.filter((e): e is string => typeof e === "string") : [];
-	if (declared.length === 0) return undefined;
-	const entries: string[] = [];
-	for (const rel of declared) {
-		const entry = path.resolve(pkg.root, rel);
-		if (await exists(entry)) entries.push(entry);
-	}
-	if (entries.length === 0) return undefined;
-	const name = typeof manifest.name === "string" && manifest.name.length > 0 ? manifest.name : packageNameFromSource(pkg.source);
-	return { name, source: pkg.source, root: pkg.root, entries };
+/** Selectable ID for a loose extension file: its path under the extensions
+ *  dir without the file extension, with a trailing "/index" collapsed so a
+ *  directory-style extension is referenced by its directory name. */
+function looseId(filePath: string, extensionsDir: string): string {
+	const rel = toPosix(path.relative(extensionsDir, filePath));
+	const collapsed = rel.replace(/(?:^|\/)index\.(ts|js)$/, "");
+	const base = collapsed === "" ? rel : collapsed;
+	return base.replace(/\.(ts|js)$/, "");
 }
 
-/** Lists loose extension files in one directory; missing dir → empty.
- *  A `.ts`/`.js` stem pair resolves to the `.ts` file (Pi's convention:
- *  TypeScript sources are the canonical form) and is reported, not silent. */
-async function scanLooseDir(dir: string, warnings: string[]): Promise<DiscoveredLocalExtension[]> {
-	let files: string[];
+/** Reads a package's display name from its manifest, falling back to the
+ *  source string when the manifest is missing or has no name. */
+async function readPackageName(root: string, source: string): Promise<string> {
 	try {
-		files = (await readdir(dir)).filter((name) => LOOSE_FILE_PATTERN.test(name));
+		const manifest: unknown = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+		if (isRecord(manifest) && typeof manifest.name === "string" && manifest.name.length > 0) return manifest.name;
 	} catch {
-		return [];
-	}
-	const byStem = new Map<string, string>();
-	for (const name of files.sort()) {
-		const stem = name.replace(LOOSE_FILE_PATTERN, "");
-		const full = path.join(dir, name);
-		const existing = byStem.get(stem);
-		if (existing !== undefined) {
-			if (!existing.endsWith(".ts") && name.endsWith(".ts")) {
-				warnings.push(`extension "${stem}" exists as both .ts and .js in ${dir}; the .ts file is used`);
-				byStem.set(stem, full);
-			}
-			continue;
-		}
-		byStem.set(stem, full);
+		// Not installed (a skipped source) or unreadable — derive from source.
 	}
-	return [...byStem.entries()].map(([id, entry]) => ({ id, entry }));
+	return packageNameFromSource(source);
 }
 
-export async function discoverImplicitExtensions(options: {
+export interface DiscoverExtensionsOptions {
+	/** Project working directory (Pi's cwd). */
+	cwd: string;
+	/** The user's real agent dir (e.g. ~/.pi/agent). */
 	agentDir: string;
-	/** Configured user-scope packages with resolved roots (launcher discovery). */
-	packages: ConfiguredPackageRoot[];
-	/** Trusted project dir; untrusted projects are never scanned. */
-	projectDir?: string;
-}): Promise<ImplicitExtensionDiscovery> {
+	/**
+	 * Whether the project at `cwd` is trusted (the launcher's trust check).
+	 * Untrusted projects contribute nothing: no project settings packages, no
+	 * `.pi/extensions` files. Defaults to false.
+	 */
+	projectTrusted?: boolean;
+}
+
+/** Builds the Pi package manager that owns discovery for one cwd/agentDir. */
+function createPackageManager(options: DiscoverExtensionsOptions): PackageManager {
+	const settingsManager = SettingsManager.create(options.cwd, options.agentDir, {
+		projectTrusted: options.projectTrusted ?? false,
+	});
+	return new DefaultPackageManager({
+		cwd: options.cwd,
+		agentDir: options.agentDir,
+		settingsManager,
+	});
+}
+
+interface PackageGroup {
+	source: string;
+	root: string;
+	entries: string[];
+	/** Some declared entry exists on disk, even if all are disabled — keeps
+	 *  "package is filtered out" distinguishable from "package has no
+	 *  extensions". */
+	known: boolean;
+}
+
+/** Runs Pi's own resolution once and classifies the result into pi-profile's
+ *  selectable model. */
+async function resolveImplicit(packageManager: PackageManager, agentDir: string): Promise<ImplicitExtensionDiscovery> {
 	const warnings: string[] = [];
+	// `skip` is the API's read-only mode: missing sources are reported as
+	// absent instead of triggering an install (no network, no mutation).
+	const resolved = await packageManager.resolve(async () => "skip");
+	// Sort for deterministic IDs and ordering: Pi preserves directory read
+	// order, which varies by filesystem.
+	const resources = [...resolved.extensions].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+
+	const groups = new Map<string, PackageGroup>();
+	const userLoose = new Map<string, DiscoveredLocalExtension>();
+	const projectLoose = new Map<string, DiscoveredLocalExtension>();
+
+	for (const resource of resources) {
+		const { source, scope, origin, baseDir } = resource.metadata;
+		if (origin === "package") {
+			// Project-scope packages install under the project's .pi/npm, which
+			// generated global-scope settings cannot reference.
+			if (scope === "project") continue;
+			if (baseDir === undefined) continue;
+			const group = groups.get(source) ?? { source, root: baseDir, entries: [], known: false };
+			// A local source with no manifest and no convention dir resolves to
+			// the directory itself; the loader imports paths verbatim, so it is
+			// not selectable and must not be advertised.
+			if (await isFile(resource.path)) {
+				group.known = true;
+				if (resource.enabled && !group.entries.includes(resource.path)) group.entries.push(resource.path);
+			}
+			groups.set(source, group);
+			continue;
+		}
+		// Settings-declared paths (`extensions: [...]`) are already concrete
+		// files, so profiles reference them directly instead of through a
+		// derived ID; only auto-discovered directory contents become IDs.
+		if (!resource.enabled || source !== "auto") continue;
+		const extensionsDir = path.join(baseDir ?? agentDir, "extensions");
+		const id = looseId(resource.path, extensionsDir);
+		const target = scope === "project" ? projectLoose : userLoose;
+		const existing = target.get(id);
+		if (existing === undefined) {
+			target.set(id, { id, entry: resource.path });
+			continue;
+		}
+		// Pi reports a `.ts`/`.js` stem pair as two entries; keep its
+		// TypeScript-first convention, but say so instead of silently
+		// shadowing the file the loader would pick.
+		if (!existing.entry.endsWith(".ts") && resource.path.endsWith(".ts")) {
+			warnings.push(`extension "${id}" exists as both .ts and .js in ${extensionsDir}; the .ts file is used`);
+			target.set(id, { id, entry: resource.path });
+		}
+	}
 
 	const packages: DiscoveredPackage[] = [];
-	for (const pkg of options.packages) {
-		const discovered = await readPackageExtensions(pkg);
-		if (discovered !== undefined) packages.push(discovered);
+	for (const group of groups.values()) {
+		if (!group.known) continue;
+		packages.push({
+			name: await readPackageName(group.root, group.source),
+			source: group.source,
+			root: group.root,
+			entries: group.entries,
+		});
 	}
 
-	const globalLocal = await scanLooseDir(path.join(options.agentDir, "extensions"), warnings);
-	const merged = new Map<string, DiscoveredLocalExtension>(globalLocal.map((entry) => [entry.id, entry]));
-	if (options.projectDir !== undefined) {
-		// Project loose files override same-ID global ones, mirroring the
-		// project-over-global catalog override convention.
-		for (const entry of await scanLooseDir(path.join(options.projectDir, ".pi", "extensions"), warnings)) {
-			merged.set(entry.id, entry);
-		}
-	}
+	// Project loose files override same-ID global ones, mirroring the
+	// project-over-global catalog override convention.
+	const merged = new Map(userLoose);
+	for (const [id, entry] of projectLoose) merged.set(id, entry);
 
 	return { packages, local: [...merged.values()], warnings };
 }
 
-export async function discoverExtensions(options: {
-	agentDir: string;
-	packages: ConfiguredPackageRoot[];
-	projectDir?: string;
-}): Promise<DiscoveredExtensions> {
+export async function discoverImplicitExtensions(options: DiscoverExtensionsOptions): Promise<ImplicitExtensionDiscovery> {
+	return await resolveImplicit(createPackageManager(options), options.agentDir);
+}
+
+export async function discoverExtensions(options: DiscoverExtensionsOptions): Promise<DiscoveredExtensions> {
 	const raw = await discoverImplicitExtensions(options);
 	return new DiscoveredExtensions(raw.packages, raw.local, raw.warnings);
 }

package/src/launcher/discovery.ts

@@ -54,10 +54,12 @@ export async function discoverLauncherResources(
 		.map((pkg) => ({ source: pkg.source, root: resolvePackageRoot(pkg.source, pkg.installedPath, context.agentDir) }));
 	const [skills, extensions] = await Promise.all([
 		discoverSkills(context),
+		// Extension discovery resolves through Pi's own package manager, so it
+		// only needs the same cwd/agentDir/trust inputs as skill discovery.
 		discoverExtensions({
+			cwd: context.cwd,
 			agentDir: context.agentDir,
-			packages: configured,
-			projectDir: context.projectTrusted ? context.cwd : undefined,
+			projectTrusted: context.projectTrusted,
 		}),
 	]);
 	return { skills, packages: configured, extensions };