@selesai/code 0.13.39 → 0.14.0

package/dist/core/package-manager.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, globSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 function getEnv() {
     if (process.platform !== "linux" || Object.keys(process.env).length > 0) {
@@ -21,15 +21,17 @@ function getEnv() {
     }
 }
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { globSync } from "glob";
 import ignore from "ignore";
 import { minimatch } from "minimatch";
-import { maxSatisfying, rcompare, satisfies, valid, validRange } from "semver";
+import { gt, maxSatisfying, rcompare, satisfies, valid, validRange } from "semver";
 import { CONFIG_DIR_NAME, getBundledExtensionsDir } from "../config.js";
 import { spawnProcess, spawnProcessSync } from "../utils/child-process.js";
 import { parseGitUrl } from "../utils/git.js";
 import { canonicalizePath, isLocalPath, markPathIgnoredByCloudSync, resolvePath } from "../utils/paths.js";
+import { stripBom } from "../utils/text.js";
 import { isStdoutTakenOver } from "./output-guard.js";
+import { readPiManifest } from "./pi-manifest.js";
+import { BUILTIN_PATH_PREFIX } from "./source-info.js";
 const NETWORK_TIMEOUT_MS = 10000;
 const UPDATE_CHECK_CONCURRENCY = 4;
 const GIT_UPDATE_CONCURRENCY = 4;
@@ -58,6 +60,9 @@ function getNpmVersionRange(version) {
  *   4  package resource (origin: "package")
  */
 function resourcePrecedenceRank(m) {
+    // Built-in extensions load after file and package extensions, whichever scope enables them.
+    if (m.source === "builtin")
+        return 5;
     if (m.origin === "package")
         return 4;
     const scopeBase = m.scope === "project" ? 0 : 2;
@@ -134,6 +139,15 @@ function isOverridePattern(s) {
 function hasGlobPattern(s) {
     return s.includes("*") || s.includes("?");
 }
+/** Glob entries discover visible paths; exact entries can target dot paths or symlinked trees. */
+function expandPackageGlob(pattern, root) {
+    return globSync(pattern, { cwd: root })
+        .map((match) => resolve(root, match))
+        .filter((path) => relative(root, path)
+        .split(sep)
+        .every((segment) => segment === ".." || !segment.startsWith(".")))
+        .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
 function splitPatterns(entries) {
     const plain = [];
     const patterns = [];
@@ -239,7 +253,11 @@ function collectSkillEntries(dir, mode, ignoreMatcher, rootDir) {
                 }
             }
             const relPath = toPosixPath(relative(root, fullPath));
-            if (mode === "pi" && dir === root && isFile && entry.name.endsWith(".md") && !ig.ignores(relPath)) {
+            const shouldIncludeMarkdownFile = isFile &&
+                entry.name.endsWith(".md") &&
+                !ig.ignores(relPath) &&
+                ((mode === "pi" && dir === root) || (mode === "agents" && dir !== root));
+            if (shouldIncludeMarkdownFile) {
                 entries.push(fullPath);
                 continue;
             }
@@ -361,20 +379,10 @@ function collectAutoThemeEntries(dir) {
     }
     return entries;
 }
-function readPiManifestFile(packageJsonPath) {
-    try {
-        const content = readFileSync(packageJsonPath, "utf-8");
-        const pkg = JSON.parse(content);
-        return pkg.pi ?? null;
-    }
-    catch {
-        return null;
-    }
-}
 function resolveExtensionEntries(dir) {
     const packageJsonPath = join(dir, "package.json");
     if (existsSync(packageJsonPath)) {
-        const manifest = readPiManifestFile(packageJsonPath);
+        const manifest = readPiManifest(packageJsonPath);
         if (manifest?.extensions?.length) {
             const entries = [];
             for (const extPath of manifest.extensions) {
@@ -617,6 +625,7 @@ export class DefaultPackageManager {
     cwd;
     agentDir;
     settingsManager;
+    builtinExtensions;
     globalNpmRoot;
     globalNpmRootCommandKey;
     progressCallback;
@@ -624,6 +633,7 @@ export class DefaultPackageManager {
         this.cwd = resolvePath(options.cwd);
         this.agentDir = resolvePath(options.agentDir);
         this.settingsManager = options.settingsManager;
+        this.builtinExtensions = options.builtinExtensions ?? [];
     }
     setProgressCallback(callback) {
         this.progressCallback = callback;
@@ -741,12 +751,25 @@ export class DefaultPackageManager {
             }, globalBaseDir);
         }
         const collisions = this.addAutoDiscoveredResources(accumulator, globalSettings, projectSettings, globalBaseDir, projectBaseDir);
+        // Built-in extensions are enabled unless the user `extensions` setting excludes them, for example
+        // with `-builtin:mcp`. A matching `+`, `-`, or `!` entry in the project setting overrides that.
+        for (const name of this.builtinExtensions) {
+            const path = `${BUILTIN_PATH_PREFIX}${name}`;
+            const projectEnabled = applyAutoloadDisabledPatterns([path], getOverridePatterns(projectSettings.extensions ?? []), projectBaseDir).get(path);
+            this.addResource(accumulator.extensions, path, { source: "builtin", scope: projectEnabled === undefined ? "user" : "project", origin: "top-level" }, projectEnabled ?? isEnabledByOverrides(path, globalSettings.extensions ?? [], globalBaseDir));
+        }
         return this.toResolvedPaths(accumulator, collisions);
     }
     async resolveExtensionSources(sources, options) {
         const accumulator = this.createAccumulator();
         const scope = options?.temporary ? "temporary" : options?.local ? "project" : "user";
-        const packageSources = sources.map((source) => ({ pkg: source, scope }));
+        // `-e builtin:<name>` loads a built-in extension; the resource loader reports unknown names.
+        for (const source of sources.filter((source) => source.startsWith(BUILTIN_PATH_PREFIX))) {
+            this.addResource(accumulator.extensions, source, { source: "builtin", scope, origin: "top-level" }, true);
+        }
+        const packageSources = sources
+            .filter((source) => !source.startsWith(BUILTIN_PATH_PREFIX))
+            .map((source) => ({ pkg: source, scope }));
         await this.resolvePackageSources(packageSources, accumulator);
         return this.toResolvedPaths(accumulator, []);
     }
@@ -912,7 +935,7 @@ export class DefaultPackageManager {
         }
         try {
             const targetVersion = await this.getLatestNpmVersion(source.version ? source.spec : source.name, source.range);
-            return targetVersion !== installedVersion;
+            return gt(targetVersion, installedVersion);
         }
         catch {
             // Preserve existing update behavior when version lookup fails.
@@ -1030,6 +1053,7 @@ export class DefaultPackageManager {
                     installedPath = this.getNpmInstallPath(parsed, resolvedScope);
                 }
                 metadata.baseDir = installedPath;
+                metadata.packageRoot = installedPath;
                 this.collectPackageResources(installedPath, accumulator, filter, metadata);
                 continue;
             }
@@ -1044,6 +1068,7 @@ export class DefaultPackageManager {
                     await this.refreshTemporaryGitSource(parsed, resolvedSource);
                 }
                 metadata.baseDir = installedPath;
+                metadata.packageRoot = installedPath;
                 this.collectPackageResources(installedPath, accumulator, filter, metadata);
             }
         }
@@ -1070,6 +1095,7 @@ export class DefaultPackageManager {
             }
             if (stats.isDirectory()) {
                 metadata.baseDir = resolved;
+                metadata.packageRoot = resolved;
                 const resources = this.collectPackageResources(resolved, accumulator, filter, metadata);
                 if (!resources) {
                     this.addResource(accumulator.extensions, resolved, metadata, true);
@@ -1198,7 +1224,7 @@ export class DefaultPackageManager {
         }
         try {
             const targetVersion = await this.getLatestNpmVersion(source.version ? source.spec : source.name, source.range);
-            return targetVersion !== installedVersion;
+            return gt(targetVersion, installedVersion);
         }
         catch {
             return false;
@@ -1210,7 +1236,7 @@ export class DefaultPackageManager {
             return undefined;
         try {
             const content = readFileSync(packageJsonPath, "utf-8");
-            const pkg = JSON.parse(content);
+            const pkg = JSON.parse(stripBom(content));
             return pkg.version;
         }
         catch {
@@ -1449,21 +1475,46 @@ export class DefaultPackageManager {
     }
     getPackageManagerName() {
         const npmCommand = this.getNpmCommand();
-        const commandParts = [npmCommand.command, ...npmCommand.args];
-        const separatorIndex = commandParts.lastIndexOf("--");
-        const packageManagerCommand = separatorIndex >= 0 ? commandParts[separatorIndex + 1] : npmCommand.command;
-        return packageManagerCommand ? basename(packageManagerCommand).replace(/\.(cmd|exe)$/i, "") : "";
+        const normalizeCommandName = (command) => basename(command).replace(/\.(cmd|exe)$/i, "");
+        const supportedPackageManagers = new Set(["npm", "pnpm", "bun"]);
+        const directCommand = normalizeCommandName(npmCommand.command);
+        const separatorIndex = npmCommand.args.lastIndexOf("--");
+        if (separatorIndex >= 0) {
+            const wrappedCommand = npmCommand.args[separatorIndex + 1];
+            return wrappedCommand ? normalizeCommandName(wrappedCommand) : directCommand;
+        }
+        if (supportedPackageManagers.has(directCommand))
+            return directCommand;
+        const wrappedPackageManagers = [
+            ...new Set(npmCommand.args.map(normalizeCommandName).filter((command) => supportedPackageManagers.has(command))),
+        ];
+        if (wrappedPackageManagers.length > 1) {
+            throw new Error(`Ambiguous npmCommand package managers: ${wrappedPackageManagers.join(", ")}`);
+        }
+        return wrappedPackageManagers[0] ?? directCommand;
     }
     async runNpmCommand(args, options) {
         const npmCommand = this.getNpmCommand();
         await this.runCommand(npmCommand.command, [...npmCommand.args, ...args], options);
     }
     getGitDependencyInstallArgs() {
-        const configuredCommand = this.settingsManager.getNpmCommand();
-        if (configuredCommand && configuredCommand.length > 0) {
-            return ["install", "--ignore-scripts"];
+        switch (this.getPackageManagerName()) {
+            case "bun":
+                return ["install", "--ignore-scripts", "--omit=dev", "--omit=peer"];
+            case "pnpm":
+                return [
+                    "install",
+                    "--ignore-scripts",
+                    "--prod",
+                    "--config.auto-install-peers=false",
+                    "--config.strict-peer-dependencies=false",
+                    "--config.strict-dep-builds=false",
+                ];
+            case "npm":
+                return ["install", "--ignore-scripts", "--omit=dev", "--legacy-peer-deps"];
+            default:
+                return ["install", "--ignore-scripts"];
         }
-        return ["install", "--omit=dev", "--ignore-scripts"];
     }
     runNpmCommandSync(args) {
         const npmCommand = this.getNpmCommand();
@@ -1529,6 +1580,7 @@ export class DefaultPackageManager {
             this.ensureGitIgnore(gitRoot);
         }
         mkdirSync(dirname(targetDir), { recursive: true });
+        rmSync(this.getGitUpdateMarkerPath(targetDir), { force: true });
         try {
             await this.runCommand("git", ["clone", source.repo, targetDir]);
             if (source.ref) {
@@ -1558,6 +1610,53 @@ export class DefaultPackageManager {
         const target = await this.getLocalGitUpdateTarget(targetDir);
         await this.ensureGitRef(targetDir, target.fetchArgs, target.ref);
     }
+    hasMissingGitDependencies(targetDir) {
+        const packageJsonPath = join(targetDir, "package.json");
+        if (!existsSync(packageJsonPath))
+            return false;
+        try {
+            const manifest = JSON.parse(stripBom(readFileSync(packageJsonPath, "utf-8")));
+            if (!manifest.dependencies ||
+                typeof manifest.dependencies !== "object" ||
+                Array.isArray(manifest.dependencies)) {
+                return false;
+            }
+            const nodeModulesDir = resolve(targetDir, "node_modules");
+            return Object.keys(manifest.dependencies).some((name) => {
+                const dependencyPath = resolve(nodeModulesDir, name);
+                if (!dependencyPath.startsWith(`${nodeModulesDir}${sep}`))
+                    return false;
+                return !existsSync(dependencyPath);
+            });
+        }
+        catch {
+            return false;
+        }
+    }
+    async repairMissingGitDependencies(targetDir) {
+        if (!this.hasMissingGitDependencies(targetDir))
+            return;
+        await this.runNpmCommand(this.getGitDependencyInstallArgs(), { cwd: targetDir });
+    }
+    getGitUpdateMarkerPath(targetDir) {
+        return join(dirname(targetDir), `.${basename(targetDir)}.pi-update-incomplete`);
+    }
+    async cleanAndInstallGitDependencies(targetDir, markerPath) {
+        // Clean untracked files (extensions should be pristine). If this fails after
+        // deleting dependencies, repair them so the existing extension still loads.
+        try {
+            await this.runCommand("git", ["clean", "-fdx"], { cwd: targetDir });
+        }
+        catch (error) {
+            await this.repairMissingGitDependencies(targetDir).catch(() => { });
+            throw error;
+        }
+        const packageJsonPath = join(targetDir, "package.json");
+        if (existsSync(packageJsonPath)) {
+            await this.runNpmCommand(this.getGitDependencyInstallArgs(), { cwd: targetDir });
+        }
+        rmSync(markerPath, { force: true });
+    }
     async ensureGitRef(targetDir, fetchArgs, ref) {
         // Fetch only the ref we will reset to, avoiding unrelated branch/tag noise.
         await this.runCommand("git", fetchArgs, { cwd: targetDir });
@@ -1570,16 +1669,19 @@ export class DefaultPackageManager {
             cwd: targetDir,
             timeoutMs: NETWORK_TIMEOUT_MS,
         });
+        const markerPath = this.getGitUpdateMarkerPath(targetDir);
         if (localHead.trim() === targetHead.trim()) {
+            if (existsSync(markerPath)) {
+                await this.cleanAndInstallGitDependencies(targetDir, markerPath);
+            }
+            else {
+                await this.repairMissingGitDependencies(targetDir);
+            }
             return;
         }
+        writeFileSync(markerPath, "", "utf-8");
         await this.runCommand("git", ["reset", "--hard", commitRef], { cwd: targetDir });
-        // Clean untracked files (extensions should be pristine)
-        await this.runCommand("git", ["clean", "-fdx"], { cwd: targetDir });
-        const packageJsonPath = join(targetDir, "package.json");
-        if (existsSync(packageJsonPath)) {
-            await this.runNpmCommand(this.getGitDependencyInstallArgs(), { cwd: targetDir });
-        }
+        await this.cleanAndInstallGitDependencies(targetDir, markerPath);
     }
     async refreshTemporaryGitSource(source, sourceStr) {
         if (isOfflineModeEnabled()) {
@@ -1596,9 +1698,8 @@ export class DefaultPackageManager {
     }
     async removeGit(source, scope) {
         const targetDir = this.getGitInstallPath(source, scope);
-        if (!existsSync(targetDir))
-            return;
         rmSync(targetDir, { recursive: true, force: true });
+        rmSync(this.getGitUpdateMarkerPath(targetDir), { force: true });
         this.pruneEmptyGitParents(targetDir, this.getGitInstallRoot(scope));
     }
     pruneEmptyGitParents(targetDir, installRoot) {
@@ -1712,7 +1813,8 @@ export class DefaultPackageManager {
     }
     getGitInstallPath(source, scope) {
         if (scope === "temporary") {
-            return this.getTemporaryDir(`git-${source.host}`, source.path);
+            // Include the ref in the hash so each pinned ref gets its own checkout.
+            return this.getTemporaryDir(`git-${source.host}`, source.path, source.ref);
         }
         const installRoot = this.getGitInstallRoot(scope);
         if (!installRoot) {
@@ -1730,10 +1832,10 @@ export class DefaultPackageManager {
         }
         return join(this.agentDir, "git");
     }
-    getTemporaryDir(prefix, suffix) {
+    getTemporaryDir(prefix, suffix, ref) {
         const root = this.resolveManagedPath(getExtensionTempFolder(this.agentDir), prefix);
         const hash = createHash("sha256")
-            .update(`${prefix}-${suffix ?? ""}`)
+            .update(`${prefix}-${suffix ?? ""}${ref ? `@${ref}` : ""}`)
             .digest("hex")
             .slice(0, 8);
         return this.resolveManagedPath(root, hash, suffix ?? "");
@@ -1779,7 +1881,7 @@ export class DefaultPackageManager {
             }
             return true;
         }
-        const manifest = this.readPiManifest(packageRoot);
+        const manifest = readPiManifest(join(packageRoot, "package.json"));
         if (manifest) {
             for (const resourceType of RESOURCE_TYPES) {
                 const entries = manifest[resourceType];
@@ -1802,7 +1904,7 @@ export class DefaultPackageManager {
         return hasAnyDir;
     }
     collectDefaultResources(packageRoot, resourceType, target, metadata) {
-        const manifest = this.readPiManifest(packageRoot);
+        const manifest = readPiManifest(join(packageRoot, "package.json"));
         const entries = manifest?.[resourceType];
         if (entries) {
             this.addManifestEntries(entries, packageRoot, resourceType, target, metadata);
@@ -1849,7 +1951,7 @@ export class DefaultPackageManager {
      * that pass the manifest's own patterns.
      */
     collectManifestFiles(packageRoot, resourceType) {
-        const manifest = this.readPiManifest(packageRoot);
+        const manifest = readPiManifest(join(packageRoot, "package.json"));
         const entries = manifest?.[resourceType];
         if (entries && entries.length > 0) {
             const allFiles = this.collectFilesFromManifestEntries(entries, packageRoot, resourceType);
@@ -1864,20 +1966,6 @@ export class DefaultPackageManager {
         const allFiles = collectResourceFiles(conventionDir, resourceType);
         return { allFiles, enabledByManifest: new Set(allFiles) };
     }
-    readPiManifest(packageRoot) {
-        const packageJsonPath = join(packageRoot, "package.json");
-        if (!existsSync(packageJsonPath)) {
-            return null;
-        }
-        try {
-            const content = readFileSync(packageJsonPath, "utf-8");
-            const pkg = JSON.parse(content);
-            return pkg.pi ?? null;
-        }
-        catch {
-            return null;
-        }
-    }
     addManifestEntries(entries, root, resourceType, target, metadata) {
         if (!entries)
             return;
@@ -1896,12 +1984,7 @@ export class DefaultPackageManager {
             if (!hasGlobPattern(entry)) {
                 return [resolve(root, entry)];
             }
-            return globSync(entry, {
-                cwd: root,
-                absolute: true,
-                dot: false,
-                nodir: false,
-            }).map((match) => resolve(match));
+            return expandPackageGlob(entry, root);
         });
         return this.collectFilesFromPaths(resolved, resourceType);
     }

package/dist/core/package-manager.test.js

@@ -18,7 +18,7 @@ describe("extensionEntryName", () => {
         expect(extensionEntryName(join(root, "question", "index.ts"), root)).toBe("question");
     });
 });
-describe("auto-discovered skills are opt-in by default", () => {
+describe("auto-discovered skills match Pi automatic discovery", () => {
     let root;
     const SKILL_BODY = "---\nname: {name}\ndescription: A test skill.\n---\n\n# {name}\n";
     beforeEach(() => {
@@ -32,7 +32,7 @@ describe("auto-discovered skills are opt-in by default", () => {
         mkdirSync(dir, { recursive: true });
         writeFileSync(join(dir, "SKILL.md"), SKILL_BODY.replaceAll("{name}", name));
     }
-    it("defaults auto-discovered user skills to disabled (opt-in)", async () => {
+    it("defaults auto-discovered user skills to enabled", async () => {
         makeSkill(root, "alpha");
         makeSkill(root, "beta");
         const settingsManager = SettingsManager.inMemory({});
@@ -40,13 +40,13 @@ describe("auto-discovered skills are opt-in by default", () => {
         const resolved = await pm.resolve();
         const localSkills = resolved.skills.filter((s) => s.path.startsWith(root));
         expect(localSkills.length).toBe(2);
-        expect(localSkills.every((s) => s.enabled === false)).toBe(true);
+        expect(localSkills.every((s) => s.enabled)).toBe(true);
     });
-    it("enables a user skill when it is force-included via a + pattern", async () => {
+    it("honors exclusion and force-inclusion patterns", async () => {
         makeSkill(root, "alpha");
         makeSkill(root, "beta");
         const settingsManager = SettingsManager.inMemory({
-            skills: ["+skills/alpha/SKILL.md"],
+            skills: ["!skills/**", "+skills/alpha/SKILL.md"],
         });
         const pm = new DefaultPackageManager({ cwd: root, agentDir: root, settingsManager });
         const resolved = await pm.resolve();

package/dist/core/pi-manifest.d.ts

@@ -0,0 +1,9 @@
+export interface PiManifest {
+    extensions?: string[];
+    skills?: string[];
+    prompts?: string[];
+    themes?: string[];
+    /** Selesai: agent definitions shipped by packages. */
+    agents?: string[];
+}
+export declare function readPiManifest(packageJsonPath: string): PiManifest | null;

package/dist/core/pi-manifest.js

@@ -0,0 +1,25 @@
+import { readFileSync } from "node:fs";
+import { stripBom } from "../utils/text.js";
+const RESOURCE_FIELDS = ["extensions", "skills", "prompts", "themes", "agents"]; // Selesai: + agents
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function readPiManifest(packageJsonPath) {
+    try {
+        const pkg = JSON.parse(stripBom(readFileSync(packageJsonPath, "utf-8")));
+        if (!isObject(pkg) || !isObject(pkg.pi)) {
+            return null;
+        }
+        const manifest = {};
+        for (const field of RESOURCE_FIELDS) {
+            const entries = pkg.pi[field];
+            if (Array.isArray(entries) && entries.every((entry) => typeof entry === "string")) {
+                manifest[field] = entries;
+            }
+        }
+        return manifest;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/prompt-templates.d.ts

@@ -1,3 +1,4 @@
+import type { ResourceDiagnostic } from "./diagnostics.ts";
 import { type SourceInfo } from "./source-info.ts";
 /**
  * Represents a prompt template loaded from a markdown file
@@ -39,13 +40,17 @@ export interface LoadPromptTemplatesOptions {
     /** Include default prompt directories. */
     includeDefaults: boolean;
 }
+export interface LoadPromptTemplatesResult {
+    templates: PromptTemplate[];
+    diagnostics: ResourceDiagnostic[];
+}
 /**
  * Load all prompt templates from:
  * 1. Global: agentDir/prompts/
  * 2. Project: cwd/{CONFIG_DIR_NAME}/prompts/
  * 3. Explicit prompt paths
  */
-export declare function loadPromptTemplates(options: LoadPromptTemplatesOptions): PromptTemplate[];
+export declare function loadPromptTemplates(options: LoadPromptTemplatesOptions): LoadPromptTemplatesResult;
 /**
  * Expand a prompt template if it matches a template name.
  * Returns the expanded content or the original text if not a template.

package/dist/core/prompt-templates.js

@@ -79,41 +79,59 @@ export function substituteArgs(content, args) {
     });
 }
 function loadTemplateFromFile(filePath, sourceInfo) {
+    const diagnostics = [];
+    let rawContent;
     try {
-        const rawContent = readFileSync(filePath, "utf-8");
-        const { frontmatter, body } = parseFrontmatter(rawContent);
-        const name = basename(filePath).replace(/\.md$/, "");
-        // Get description from frontmatter or first non-empty line
-        let description = frontmatter.description || "";
-        if (!description) {
-            const firstLine = body.split("\n").find((line) => line.trim());
-            if (firstLine) {
-                // Truncate if too long
-                description = firstLine.slice(0, 60);
-                if (firstLine.length > 60)
-                    description += "...";
-            }
+        rawContent = readFileSync(filePath, "utf-8");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "failed to read prompt template file";
+        diagnostics.push({ type: "warning", message, path: filePath });
+        return { template: null, diagnostics };
+    }
+    let frontmatter;
+    let body;
+    try {
+        ({ frontmatter, body } = parseFrontmatter(rawContent));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "failed to parse prompt template file";
+        diagnostics.push({ type: "warning", message, path: filePath });
+        return { template: null, diagnostics };
+    }
+    const name = basename(filePath).replace(/\.md$/, "");
+    // Get description from frontmatter or first non-empty line
+    let description = typeof frontmatter.description === "string" ? frontmatter.description : "";
+    if (!description) {
+        const firstLine = body.split("\n").find((line) => line.trim());
+        if (firstLine) {
+            // Truncate if too long
+            description = firstLine.slice(0, 60);
+            if (firstLine.length > 60)
+                description += "...";
         }
-        return {
+    }
+    const argumentHint = typeof frontmatter["argument-hint"] === "string" ? frontmatter["argument-hint"] : undefined;
+    return {
+        template: {
             name,
             description,
-            ...(frontmatter["argument-hint"] && { argumentHint: frontmatter["argument-hint"] }),
+            ...(argumentHint && { argumentHint }),
             content: body,
             sourceInfo,
             filePath,
-        };
-    }
-    catch {
-        return null;
-    }
+        },
+        diagnostics,
+    };
 }
 /**
  * Scan a directory for .md files (non-recursive) and load them as prompt templates.
  */
 function loadTemplatesFromDir(dir, getSourceInfo) {
     const templates = [];
+    const diagnostics = [];
     if (!existsSync(dir)) {
-        return templates;
+        return { templates, diagnostics };
     }
     try {
         const entries = readdirSync(dir, { withFileTypes: true });
@@ -132,17 +150,18 @@ function loadTemplatesFromDir(dir, getSourceInfo) {
                 }
             }
             if (isFile && entry.name.endsWith(".md")) {
-                const template = loadTemplateFromFile(fullPath, getSourceInfo(fullPath));
-                if (template) {
-                    templates.push(template);
+                const result = loadTemplateFromFile(fullPath, getSourceInfo(fullPath));
+                if (result.template) {
+                    templates.push(result.template);
                 }
+                diagnostics.push(...result.diagnostics);
             }
         }
     }
     catch {
-        return templates;
+        return { templates, diagnostics };
     }
-    return templates;
+    return { templates, diagnostics };
 }
 /**
  * Load all prompt templates from:
@@ -156,6 +175,11 @@ export function loadPromptTemplates(options) {
     const promptPaths = options.promptPaths;
     const includeDefaults = options.includeDefaults;
     const templates = [];
+    const diagnostics = [];
+    const addResult = (result) => {
+        templates.push(...result.templates);
+        diagnostics.push(...result.diagnostics);
+    };
     const globalPromptsDir = join(resolvedAgentDir, "prompts");
     const projectPromptsDir = resolve(resolvedCwd, CONFIG_DIR_NAME, "prompts");
     const isUnderPath = (target, root) => {
@@ -187,8 +211,8 @@ export function loadPromptTemplates(options) {
         });
     };
     if (includeDefaults) {
-        templates.push(...loadTemplatesFromDir(globalPromptsDir, getSourceInfo));
-        templates.push(...loadTemplatesFromDir(projectPromptsDir, getSourceInfo));
+        addResult(loadTemplatesFromDir(globalPromptsDir, getSourceInfo));
+        addResult(loadTemplatesFromDir(projectPromptsDir, getSourceInfo));
     }
     // 3. Load explicit prompt paths
     for (const rawPath of promptPaths) {
@@ -199,20 +223,22 @@ export function loadPromptTemplates(options) {
         try {
             const stats = statSync(resolvedPath);
             if (stats.isDirectory()) {
-                templates.push(...loadTemplatesFromDir(resolvedPath, getSourceInfo));
+                addResult(loadTemplatesFromDir(resolvedPath, getSourceInfo));
             }
             else if (stats.isFile() && resolvedPath.endsWith(".md")) {
-                const template = loadTemplateFromFile(resolvedPath, getSourceInfo(resolvedPath));
-                if (template) {
-                    templates.push(template);
+                const result = loadTemplateFromFile(resolvedPath, getSourceInfo(resolvedPath));
+                if (result.template) {
+                    templates.push(result.template);
                 }
+                diagnostics.push(...result.diagnostics);
             }
         }
-        catch {
-            // Ignore read failures
+        catch (error) {
+            const message = error instanceof Error ? error.message : "failed to read prompt template path";
+            diagnostics.push({ type: "warning", message, path: resolvedPath });
         }
     }
-    return templates;
+    return { templates, diagnostics };
 }
 /**
  * Expand a prompt template if it matches a template name.