gentle-pi 0.3.9 → 0.4.0

package/README.md

@@ -353,6 +353,8 @@ Saved globally at:
 
 Existing project-local `.pi/gentle-ai/models.json` files are still read as a legacy fallback when no global model config exists, but `/gentle:models` writes the shared global config.
 
+Inside `/gentle:models`, press `x` to export the saved routing to `~/.pi/gentle-ai/models.export.json`, or `r` to restore from that file after confirmation. Export uses a versioned envelope and restore writes the normal `models.json` shape before applying routing to agents.
+
 Config shape (per agent):
 
 ```json
@@ -376,11 +378,20 @@ Legacy string entries are still accepted and treated as `model`-only config.
 | `/gentle-ai:status`              | Shows package, SDD asset, OpenSpec, and global model config status. |
 | `/gentle:models`                 | Opens global model + effort assignment UI.                          |
 | `/gentle:persona`                | Switches persona mode.                                              |
+| `/gentle:banner`                 | Configures startup banner rose, text logo, and color preset.        |
+| `/gentle:toggle-rose`            | Toggles the startup rose.                                           |
+| `/gentle:toggle-text-logo`       | Toggles the startup text logo.                                      |
+| `/gentle:banner-color`           | Selects a startup banner color preset.                              |
 | `/sdd-init`                      | Initializes or refreshes `openspec/config.yaml`.                    |
 | `/gentle-ai:install-sdd`         | Repairs missing global SDD runtime assets without overwriting files. |
 | `/gentle-ai:install-sdd --force` | Force-refreshes installed global SDD assets.                         |
+
 | `/skill-registry:refresh`        | Regenerates `.atl/skill-registry.md`.                               |
 
+Package-owned global SDD runtime assets are also refreshed automatically on session start when `gentle-pi` changes. Project-local `.pi/agents` and `.pi/chains` remain manual overrides and are never overwritten by startup refresh.
+
+Startup banner settings are global and default to the current pink rose + text logo. Supported color presets are `pink`, `cyan`, `yellow`, and `green`. The `/gentle-ai:*` aliases are also available for every banner command.
+
 Startup flag:
 
 ```text

package/extensions/gentle-ai.ts

@@ -53,10 +53,17 @@ function sddGlobalAssetDriftCount(): number {
 					stale += 1;
 					continue;
 				}
-				if (
-					readFileSync(join(assetDir, entry.name), "utf8") !==
-					readFileSync(installedPath, "utf8")
-				) {
+				const packaged = readFileSync(join(assetDir, entry.name), "utf8");
+				const installed = readFileSync(installedPath, "utf8");
+				const comparablePackaged =
+					assetSubdir === "agents"
+						? updateFrontmatterRouting(packaged, undefined)
+						: packaged;
+				const comparableInstalled =
+					assetSubdir === "agents"
+						? updateFrontmatterRouting(installed, undefined)
+						: installed;
+				if (comparablePackaged !== comparableInstalled) {
 					stale += 1;
 				}
 			} catch {
@@ -181,8 +188,29 @@ const CONFIRM_BASH_PATTERNS: RegExp[] = [
 	/\bpi\s+remove\b/,
 ];
 
+const PATH_GUARDED_TOOL_NAMES = new Set(["read", "write", "edit"]);
+const PATH_INPUT_KEYS = new Set([
+	"path",
+	"paths",
+	"file",
+	"files",
+	"filePath",
+	"filePaths",
+]);
+const SENSITIVE_PATH_PATTERNS: RegExp[] = [
+	/(^|\/)\.ssh(?:\/|$)/,
+	/(^|\/)\.credentials(?:\/|$)/,
+	/(^|\/)library\/keychains(?:\/|$)/,
+	/(^|\/)\.aws\/credentials$/,
+	/(^|\/)\.config\/gh\/hosts\.ya?ml$/,
+	/(^|\/)secrets(?:\/|$)/,
+	/(^|\/)\.env(?:$|[./_-])/,
+	/\.(?:pem|key|p12|pfx)$/,
+];
+
 const SDD_AGENT_NAMES = [
 	"sdd-init",
+	"sdd-onboard",
 	"sdd-explore",
 	"sdd-proposal",
 	"sdd-spec",
@@ -293,6 +321,62 @@ function commandRequiresConfirmation(command: string): boolean {
 	return CONFIRM_BASH_PATTERNS.some((pattern) => pattern.test(command));
 }
 
+function normalizePolicyPath(value: string): string {
+	return value.trim().replace(/^~(?=\/|$)/, homedir()).replace(/\\/g, "/").toLowerCase();
+}
+
+function isSensitivePath(value: string): boolean {
+	const normalized = normalizePolicyPath(value);
+	return SENSITIVE_PATH_PATTERNS.some((pattern) => pattern.test(normalized));
+}
+
+function collectPathInputs(value: unknown, key?: string): string[] {
+	if (typeof value === "string") return key && PATH_INPUT_KEYS.has(key) ? [value] : [];
+	if (Array.isArray(value)) return value.flatMap((item) => collectPathInputs(item, key));
+	if (!isRecord(value)) return [];
+	return Object.entries(value).flatMap(([entryKey, entryValue]) =>
+		collectPathInputs(entryValue, entryKey),
+	);
+}
+
+function hasWritableEngramTool(pi: ExtensionAPI): boolean {
+	try {
+		const getActiveTools = (pi as unknown as { getActiveTools?: () => unknown[] })
+			.getActiveTools;
+		if (typeof getActiveTools !== "function") return false;
+		const tools = getActiveTools.call(pi);
+		return tools.some((tool) => {
+			const name =
+				typeof tool === "string"
+					? tool
+					: isRecord(tool) && typeof tool.name === "string"
+						? tool.name
+						: "";
+			return (
+				name === "mem_save" ||
+				name === "engram_mem_save" ||
+				name.endsWith(".mem_save") ||
+				name.endsWith(".engram_mem_save")
+			);
+		});
+	} catch {
+		return false;
+	}
+}
+
+function evaluateSensitivePathTool(
+	toolName: string,
+	input: unknown,
+): ToolCallEventResult | undefined {
+	if (!PATH_GUARDED_TOOL_NAMES.has(toolName)) return undefined;
+	const sensitivePath = collectPathInputs(input).find(isSensitivePath);
+	if (!sensitivePath) return undefined;
+	return {
+		block: true,
+		reason: `Gentle AI safety policy blocked access to sensitive path: ${sanitizeTerminalText(sensitivePath)}. Ask the user for an explicit safer plan.`,
+	};
+}
+
 async function confirmCommand(
 	command: string,
 	ctx: ExtensionContext,
@@ -333,30 +417,53 @@ function modelConfigPath(_cwd: string): string {
 	return join(gentleAiConfigHome(), "models.json");
 }
 
+function modelExportPath(_cwd: string): string {
+	return join(gentleAiConfigHome(), "models.export.json");
+}
+
+const MODEL_EXPORT_KIND = "gentle-pi.agent_model_routing";
+const MODEL_EXPORT_VERSION = 1;
+
 function legacyProjectModelConfigPath(cwd: string): string {
 	return join(cwd, ".pi", "gentle-ai", "models.json");
 }
 
-function personaConfigPath(cwd: string): string {
+function projectPersonaConfigPath(cwd: string): string {
 	return join(cwd, ".pi", "gentle-ai", "persona.json");
 }
 
-function readPersonaMode(cwd: string): PersonaMode {
-	const path = personaConfigPath(cwd);
-	if (!existsSync(path)) return "gentleman";
+function personaConfigPath(_cwd: string): string {
+	return join(gentleAiConfigHome(), "persona.json");
+}
+
+function readPersonaFile(path: string): PersonaMode | undefined {
+	if (!existsSync(path)) return undefined;
 	try {
 		const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
-		if (!isRecord(parsed)) return "gentleman";
+		if (!isRecord(parsed)) return undefined;
 		return parsed.mode === "neutral" ? "neutral" : "gentleman";
 	} catch {
-		return "gentleman";
+		return undefined;
 	}
 }
 
-function writePersonaMode(cwd: string, mode: PersonaMode): void {
-	const path = personaConfigPath(cwd);
-	mkdirSync(dirname(path), { recursive: true });
-	writeFileSync(path, `${JSON.stringify({ mode }, null, 2)}\n`);
+function readPersonaMode(cwd: string): PersonaMode {
+	return (
+		readPersonaFile(projectPersonaConfigPath(cwd)) ??
+		readPersonaFile(personaConfigPath(cwd)) ??
+		"gentleman"
+	);
+}
+
+function writePersonaMode(cwd: string, mode: PersonaMode): string[] {
+	const paths = [personaConfigPath(cwd)];
+	const projectPath = projectPersonaConfigPath(cwd);
+	if (existsSync(projectPath)) paths.push(projectPath);
+	for (const path of paths) {
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, `${JSON.stringify({ mode }, null, 2)}\n`);
+	}
+	return paths;
 }
 
 function isThinkingLevel(value: unknown): value is ThinkingLevel {
@@ -467,17 +574,58 @@ export async function readModelConfigAsync(
 	return result.status === "valid" ? result.config : {};
 }
 
-function writeModelConfig(cwd: string, config: AgentModelConfig): void {
-	const path = modelConfigPath(cwd);
-	mkdirSync(dirname(path), { recursive: true });
+function normalizeModelConfig(value: unknown): AgentModelConfig | undefined {
+	if (!isRecord(value)) return undefined;
 	const cleaned: AgentModelConfig = {};
-	for (const [name, value] of Object.entries(config)) {
-		const entry = normalizeRoutingEntry(value);
+	for (const [name, entryValue] of Object.entries(value)) {
+		if (!/^[A-Za-z0-9._:@/+%-]+$/.test(name)) continue;
+		const entry = normalizeRoutingEntry(entryValue);
 		if (entry) cleaned[name] = entry;
 	}
+	return cleaned;
+}
+
+function writeModelConfig(cwd: string, config: AgentModelConfig): void {
+	const path = modelConfigPath(cwd);
+	mkdirSync(dirname(path), { recursive: true });
+	const cleaned = normalizeModelConfig(config) ?? {};
 	writeFileSync(path, `${JSON.stringify(cleaned, null, 2)}\n`);
 }
 
+async function writeModelConfigAsync(cwd: string, config: AgentModelConfig): Promise<void> {
+	const path = modelConfigPath(cwd);
+	await mkdir(dirname(path), { recursive: true });
+	const cleaned = normalizeModelConfig(config) ?? {};
+	await writeFile(path, `${JSON.stringify(cleaned, null, 2)}\n`);
+}
+
+function parseModelExport(value: unknown): AgentModelConfig | undefined {
+	if (!isRecord(value)) return undefined;
+	if (value.kind !== MODEL_EXPORT_KIND || value.version !== MODEL_EXPORT_VERSION) return undefined;
+	return normalizeModelConfig(value.agents);
+}
+
+async function exportSavedModelConfig(ctx: ExtensionContext): Promise<number> {
+	const saved = await readSavedModelConfigAsync(ctx.cwd);
+	if (saved.status === "invalid") throw new Error(`Invalid model config: ${saved.path}`);
+	const agents = saved.status === "valid" ? saved.config : {};
+	const path = modelExportPath(ctx.cwd);
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(
+		path,
+		`${JSON.stringify({ kind: MODEL_EXPORT_KIND, version: MODEL_EXPORT_VERSION, agents }, null, 2)}\n`,
+	);
+	return Object.keys(agents).length;
+}
+
+async function readModelExport(ctx: ExtensionContext): Promise<AgentModelConfig | undefined> {
+	try {
+		return parseModelExport(JSON.parse(await readFile(modelExportPath(ctx.cwd), "utf8")));
+	} catch {
+		return undefined;
+	}
+}
+
 function cloneModelConfig(config: AgentModelConfig): AgentModelConfig {
 	return Object.fromEntries(
 		Object.entries(config).map(([name, entry]) => [name, { ...entry }]),
@@ -549,8 +697,10 @@ function listAgentFilesRecursive(dir: string): string[] {
 	const files: string[] = [];
 	for (const entry of readdirSync(dir, { withFileTypes: true })) {
 		const path = join(dir, entry.name);
-		if (entry.isDirectory()) files.push(...listAgentFilesRecursive(path));
-		else if (
+		if (entry.isDirectory()) {
+			if (entry.name === "skills") continue;
+			files.push(...listAgentFilesRecursive(path));
+		} else if (
 			entry.isFile() &&
 			entry.name.endsWith(".md") &&
 			!entry.name.endsWith(".chain.md")
@@ -572,6 +722,7 @@ async function listAgentFilesRecursiveAsync(dir: string): Promise<string[]> {
 	for (const entry of entries) {
 		const path = join(dir, entry.name);
 		if (entry.isDirectory()) {
+			if (entry.name === "skills") continue;
 			files.push(...(await listAgentFilesRecursiveAsync(path)));
 		} else if (
 			entry.isFile() &&
@@ -607,14 +758,15 @@ async function listAgentsFromDirAsync(
 }
 
 function listDiscoverableAgents(cwd: string): AgentEntry[] {
+	const globalAgentDir = join(gentlePiAgentHome(), "agents");
 	const builtinDirs = [
-		join(gentlePiAgentHome(), "agents"),
 		join(PACKAGE_ROOT, "..", "pi-subagents", "agents"),
 		join(cwd, ".pi", "npm", "node_modules", "pi-subagents", "agents"),
 		join(homedir(), ".local", "lib", "node_modules", "pi-subagents", "agents"),
 	];
 	const agents = [
 		...builtinDirs.flatMap((dir) => listAgentsFromDir(dir, "builtin")),
+		...listAgentsFromDir(globalAgentDir, "user"),
 		...listAgentsFromDir(join(homedir(), ".agents"), "user"),
 		...listAgentsFromDir(join(cwd, ".agents"), "project"),
 		...listAgentsFromDir(join(cwd, ".pi", "agents"), "project"),
@@ -632,8 +784,8 @@ function listDiscoverableAgents(cwd: string): AgentEntry[] {
 }
 
 async function listDiscoverableAgentsAsync(cwd: string): Promise<AgentEntry[]> {
+	const globalAgentDir = join(gentlePiAgentHome(), "agents");
 	const builtinDirs = [
-		join(gentlePiAgentHome(), "agents"),
 		join(PACKAGE_ROOT, "..", "pi-subagents", "agents"),
 		join(cwd, ".pi", "npm", "node_modules", "pi-subagents", "agents"),
 		join(homedir(), ".local", "lib", "node_modules", "pi-subagents", "agents"),
@@ -643,6 +795,7 @@ async function listDiscoverableAgentsAsync(cwd: string): Promise<AgentEntry[]> {
 		agents.push(...(await listAgentsFromDirAsync(dir, "builtin")));
 	}
 	const otherDirs: Array<[string, AgentSource]> = [
+		[globalAgentDir, "user"],
 		[join(homedir(), ".agents"), "user"],
 		[join(cwd, ".agents"), "project"],
 		[join(cwd, ".pi", "agents"), "project"],
@@ -845,6 +998,8 @@ interface OverlayComponent {
 type ModelPanelResult =
 	| { type: "save"; config: AgentModelConfig }
 	| { type: "custom"; agent: string | "all"; config: AgentModelConfig }
+	| { type: "export"; config: AgentModelConfig }
+	| { type: "restore"; config: AgentModelConfig }
 	| { type: "cancel" };
 
 const SET_ALL_AGENTS = "Set all agents";
@@ -945,6 +1100,14 @@ class SddModelPanel implements OverlayComponent {
 			this.effortCursor = 0;
 			return;
 		}
+		if (matchesKey(data, "x")) {
+			this.done({ type: "export", config: this.draft });
+			return;
+		}
+		if (matchesKey(data, "r")) {
+			this.done({ type: "restore", config: this.draft });
+			return;
+		}
 		if (matchesKey(data, "c")) {
 			const row = this.rows[this.cursor];
 			if (row === SET_ALL_AGENTS)
@@ -1121,7 +1284,7 @@ class SddModelPanel implements OverlayComponent {
 		lines.push("");
 		lines.push(
 			line(
-				"j/k: scroll • g/G: top/bottom • enter: change model / confirm • e: effort • i: inherit • c: custom • ctrl+s: save • esc: back",
+				"j/k scroll • enter model/save • e effort • i inherit • c custom • x export • r restore • ctrl+s save • esc back",
 			),
 		);
 		return lines;
@@ -1255,8 +1418,54 @@ async function handleModelsCommand(ctx: ExtensionContext): Promise<void> {
 	}
 	let config = savedConfig.status === "valid" ? savedConfig.config : {};
 	let result = await showSddModelPanel(ctx, config);
-	while (result.type === "custom") {
+	while (result.type === "custom" || result.type === "export" || result.type === "restore") {
 		config = cloneModelConfig(result.config);
+		if (result.type === "export") {
+			try {
+				const count = await exportSavedModelConfig(ctx);
+				ctx.ui.notify(`el Gentleman exported ${count} saved model routing entr${count === 1 ? "y" : "ies"} to ${modelExportPath(ctx.cwd)}.`, "info");
+			} catch (error) {
+				ctx.ui.notify(`Model routing export failed: ${error instanceof Error ? error.message : String(error)}`, "warning");
+			}
+			result = await showSddModelPanel(ctx, config);
+			continue;
+		}
+		if (result.type === "restore") {
+			const restored = await readModelExport(ctx);
+			if (!restored) {
+				ctx.ui.notify(`Model routing restore failed: ${modelExportPath(ctx.cwd)} is missing or invalid.`, "warning");
+				result = await showSddModelPanel(ctx, config);
+				continue;
+			}
+			const approved = await ctx.ui.confirm("Restore saved model routing?", `Replace ${modelConfigPath(ctx.cwd)} with ${modelExportPath(ctx.cwd)}`);
+			if (approved) {
+				try {
+					await writeModelConfigAsync(ctx.cwd, restored);
+				} catch (error) {
+					ctx.ui.notify(`Model routing restore failed before writing config: ${error instanceof Error ? error.message : String(error)}`, "warning");
+					result = await showSddModelPanel(ctx, config);
+					continue;
+				}
+				config = restored;
+				try {
+					const applyResult = await applyModelConfigAsync(ctx.cwd, restored);
+					ctx.ui.notify([
+						"el Gentleman restored global model config.",
+						`Import: ${modelExportPath(ctx.cwd)}`,
+						`Global config: ${modelConfigPath(ctx.cwd)}`,
+						`Agents updated: ${applyResult.updated}`,
+					].join("\n"), "info");
+				} catch (error) {
+					ctx.ui.notify([
+						"el Gentleman restored global model config, but applying it to agents failed.",
+						`Global config: ${modelConfigPath(ctx.cwd)}`,
+						`Apply error: ${error instanceof Error ? error.message : String(error)}`,
+					].join("\n"), "warning");
+				}
+			}
+			result = await showSddModelPanel(ctx, config);
+			continue;
+		}
 		const current =
 			result.agent === "all"
 				? "inherit"
@@ -1319,17 +1528,26 @@ async function handlePersonaCommand(ctx: ExtensionContext): Promise<void> {
 		[...PERSONA_OPTIONS],
 	);
 	if (selected !== "gentleman" && selected !== "neutral") return;
-	writePersonaMode(ctx.cwd, selected);
+	const writtenPaths = writePersonaMode(ctx.cwd, selected);
 	ctx.ui.notify(
 		[
 			`el Gentleman persona set to: ${selected}`,
-			`Config: ${personaConfigPath(ctx.cwd)}`,
+			`Global config: ${personaConfigPath(ctx.cwd)}`,
+			...(writtenPaths.length > 1
+				? [`Project override updated: ${projectPersonaConfigPath(ctx.cwd)}`]
+				: []),
 			"Run /reload or start a new Pi session for already-injected prompts to refresh.",
 		].join("\n"),
 		"info",
 	);
 }
 
+/** @internal */
+export const __testing = {
+	listAgentsFromDir,
+	listAgentsFromDirAsync,
+};
+
 export default function gentleAi(pi: ExtensionAPI): void {
 	function runSddPreflight(ctx: ExtensionContext): Promise<SddPreflightPreferences> {
 		return ensureSddPreflight(ctx, {
@@ -1341,7 +1559,7 @@ export default function gentleAi(pi: ExtensionAPI): void {
 
 	pi.on("session_start", async (_event, ctx) => {
 		try {
-			const installResult = installSddAssets(ctx.cwd, false);
+			const installResult = installSddAssets(ctx.cwd, true);
 			const modelResult = await applySavedModelConfig(ctx);
 			if (ctx.hasUI && modelResult.invalidPath) {
 				ctx.ui.notify(
@@ -1396,6 +1614,11 @@ export default function gentleAi(pi: ExtensionAPI): void {
 	});
 
 	pi.on("tool_call", async (event, ctx) => {
+		const sensitivePathDenied = evaluateSensitivePathTool(
+			event.toolName,
+			event.input,
+		);
+		if (sensitivePathDenied) return sensitivePathDenied;
 		if (event.toolName !== "bash") return undefined;
 		if (!isRecord(event.input) || typeof event.input.command !== "string")
 			return undefined;
@@ -1472,6 +1695,50 @@ export default function gentleAi(pi: ExtensionAPI): void {
 		},
 	});
 
+	pi.registerCommand("gentle-ai:doctor", {
+		description: "Run read-only Gentle AI diagnostics for this Pi workspace.",
+		handler: async (_args, ctx) => {
+			const agentsInstalled = existsSync(
+				join(gentlePiAgentHome(), "agents", "sdd-apply.md"),
+			);
+			const chainsInstalled = existsSync(
+				join(gentlePiAgentHome(), "chains", "sdd-full.chain.md"),
+			);
+			const openspecConfigured = existsSync(
+				join(ctx.cwd, "openspec", "config.yaml"),
+			);
+			const skillRegistryPresent = existsSync(
+				join(ctx.cwd, ".atl", "skill-registry.md"),
+			);
+			const staleSddAssets = sddGlobalAssetDriftCount();
+			const staleLocalOverrides = sddLocalOverrideDriftCount(ctx.cwd);
+			const modelConfig = await readSavedModelConfigAsync(ctx.cwd);
+			const engramActive = hasWritableEngramTool(pi);
+			const lines = [
+				"el Gentleman doctor",
+				`${agentsInstalled ? "pass" : "fail"}: Global SDD agents ${agentsInstalled ? "installed" : "missing"}`,
+				`${chainsInstalled ? "pass" : "fail"}: Global SDD chains ${chainsInstalled ? "installed" : "missing"}`,
+				`${staleSddAssets === 0 ? "pass" : "warn"}: Global SDD asset drift ${staleSddAssets} file(s)`,
+				`${staleLocalOverrides === 0 ? "pass" : "warn"}: Project-local SDD override drift ${staleLocalOverrides} file(s)`,
+				`${openspecConfigured ? "pass" : "warn"}: OpenSpec config ${openspecConfigured ? "present" : "missing"}`,
+				`${skillRegistryPresent ? "pass" : "warn"}: Skill registry ${skillRegistryPresent ? "present" : "missing"}`,
+				`${modelConfig.status === "invalid" ? "fail" : "pass"}: Global model config ${modelConfig.status}`,
+				"pass: Sensitive-path guard active for read/write/edit tools",
+				`${engramActive ? "pass" : "warn"}: Engram memory tools ${engramActive ? "active" : "not active in this session"}`,
+			];
+			if (!agentsInstalled || !chainsInstalled) {
+				lines.push("remedy: run /gentle-ai:install-sdd --force to refresh global SDD assets intentionally");
+			}
+			if (modelConfig.status === "invalid") {
+				lines.push(`remedy: fix or remove ${modelConfig.path}`);
+			}
+			ctx.ui.notify(
+				lines.join("\n"),
+				lines.some((line) => line.startsWith("fail:")) ? "warning" : "info",
+			);
+		},
+	});
+
 	pi.registerCommand("gentle-ai:status", {
 		description: "Show Gentle AI package status for this project.",
 		handler: async (_args, ctx) => {

package/extensions/skill-registry.ts

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { watch } from "node:fs";
+import { existsSync, type FSWatcher, watch } from "node:fs";
 import {
 	access,
 	mkdir,
@@ -11,6 +11,7 @@ import {
 } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, join, normalize, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 const REGISTRY_REL_PATH = ".atl/skill-registry.md";
@@ -26,6 +27,14 @@ const NO_SKILL_REGISTRY_ENV = "GENTLE_PI_NO_SKILL_REGISTRY";
 const LEGACY_PROJECT_REGISTRY_REL_PATH = ".pi/extensions/skill-registry.ts";
 const LEGACY_PROJECT_REGISTRY_DISABLED_REL_PATH =
 	".pi/extensions/skill-registry.ts.disabled";
+const SKILL_REGISTRY_EXTENSION_SOURCE_KEY =
+	"__gentlePiSkillRegistryExtensionSource";
+const activeWatchers = new Set<FSWatcher>();
+
+interface SkillRegistryExtensionGlobal {
+	[SKILL_REGISTRY_EXTENSION_SOURCE_KEY]?: string;
+}
+
 async function pathExists(path: string): Promise<boolean> {
 	try {
 		await access(path);
@@ -54,6 +63,7 @@ function userSkillDirs(): string[] {
 		join(home, ".claude/skills"),
 		join(home, ".gemini/skills"),
 		join(home, ".gemini/antigravity/skills"),
+		join(home, ".trae/skills"),
 		join(home, ".cursor/skills"),
 		join(home, ".copilot/skills"),
 		join(home, ".codex/skills"),
@@ -70,6 +80,7 @@ function projectSkillDirs(cwd: string): string[] {
 		join(cwd, ".opencode/skills"),
 		join(cwd, ".claude/skills"),
 		join(cwd, ".gemini/skills"),
+		join(cwd, ".trae/skills"),
 		join(cwd, ".cursor/skills"),
 		join(cwd, ".github/skills"),
 		join(cwd, ".codex/skills"),
@@ -108,11 +119,12 @@ async function findSkillFiles(root: string): Promise<string[]> {
 }
 
 function parseFrontmatter(source: string): { name?: string; description?: string; body: string } {
-	if (!source.startsWith("---\n")) return { body: source };
-	const end = source.indexOf("\n---", 4);
-	if (end === -1) return { body: source };
-	const fm = source.slice(4, end);
-	const body = source.slice(end + 4).replace(/^\n/, "");
+	const normalized = source.replace(/\r\n?/g, "\n");
+	if (!normalized.startsWith("---\n")) return { body: normalized };
+	const end = normalized.indexOf("\n---", 4);
+	if (end === -1) return { body: normalized };
+	const fm = normalized.slice(4, end);
+	const body = normalized.slice(end + 4).replace(/^\n/, "");
 	const out: { name?: string; description?: string } = {};
 	const lines = fm.split("\n");
 	for (let i = 0; i < lines.length; i++) {
@@ -415,6 +427,52 @@ function shouldSkipSkillRegistryStartup(
 	);
 }
 
+function normalizeExtensionSource(source: string): string {
+	return source.split(/[?#]/, 1)[0];
+}
+
+function extensionSourcePath(source: string): string | undefined {
+	const cleanSource = normalizeExtensionSource(source);
+	if (!cleanSource.startsWith("file:")) return undefined;
+	try {
+		return comparablePath(fileURLToPath(cleanSource));
+	} catch {
+		return undefined;
+	}
+}
+
+function shouldSkipDuplicateExtensionLoad(
+	source = import.meta.url,
+	cwd = process.cwd(),
+	state = globalThis as typeof globalThis & SkillRegistryExtensionGlobal,
+): boolean {
+	const currentPath = extensionSourcePath(source);
+	const projectLocalPath = comparablePath(join(cwd, "extensions", "skill-registry.ts"));
+	if (currentPath && currentPath !== projectLocalPath && existsSync(projectLocalPath)) {
+		return true;
+	}
+
+	const currentSource = currentPath ?? normalizeExtensionSource(source);
+	const existingSource = state[SKILL_REGISTRY_EXTENSION_SOURCE_KEY];
+	if (!existingSource) {
+		state[SKILL_REGISTRY_EXTENSION_SOURCE_KEY] = currentSource;
+		return false;
+	}
+	return existingSource !== currentSource;
+}
+
+function closeSkillRegistryWatchers(): void {
+	for (const watcher of activeWatchers) {
+		try {
+			watcher.close();
+		} catch {
+			// Best-effort shutdown; stale handles must not block process exit.
+		}
+	}
+	activeWatchers.clear();
+	watchedCwds.clear();
+}
+
 async function startSkillRegistryWatcher(
 	cwd: string,
 	notify: (message: string) => void,
@@ -443,7 +501,8 @@ async function startSkillRegistryWatcher(
 	};
 	for (const dir of dirs) {
 		try {
-			watch(dir, { recursive: true }, refresh);
+			const watcher = watch(dir, { recursive: true }, refresh);
+			activeWatchers.add(watcher);
 		} catch {
 			// Some filesystems do not support recursive watches; session_start/manual refresh still work.
 		}
@@ -460,9 +519,21 @@ export const __testing = {
 	parseFrontmatter,
 	renderRegistry,
 	shouldSkipSkillRegistryStartup,
+	shouldSkipDuplicateExtensionLoad,
+	startSkillRegistryWatcher,
+	closeSkillRegistryWatchers,
+	activeWatcherCount() {
+		return activeWatchers.size;
+	},
 };
 
 export default function (pi: ExtensionAPI) {
+	if (shouldSkipDuplicateExtensionLoad()) return;
+
+	pi.on("session_shutdown", () => {
+		closeSkillRegistryWatchers();
+	});
+
 	pi.registerFlag(NO_SKILL_REGISTRY_FLAG, {
 		description: "Skip the Gentle AI skill registry refresh and watcher on startup.",
 		type: "boolean",
@@ -487,9 +558,11 @@ export default function (pi: ExtensionAPI) {
 					"warning",
 				);
 			}
-			await startSkillRegistryWatcher(ctx.cwd, (message) => {
-				if (ctx.hasUI) ctx.ui.notify(message, "info");
-			});
+			if (ctx.hasUI) {
+				await startSkillRegistryWatcher(ctx.cwd, (message) => {
+					ctx.ui.notify(message, "info");
+				});
+			}
 			if (quarantinedLegacy) {
 				setTimeout(() => {
 					void (async () => {