@f5-sales-demo/xcsh 21.40.0 → 21.41.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "21.40.0",
+	"version": "21.41.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -64,13 +64,13 @@
 	},
 	"dependencies": {
 		"@agentclientprotocol/sdk": "1.4.0",
-		"@f5-sales-demo/pi-agent-core": "21.40.0",
-		"@f5-sales-demo/pi-ai": "21.40.0",
-		"@f5-sales-demo/pi-natives": "21.40.0",
-		"@f5-sales-demo/pi-resource-management": "21.40.0",
-		"@f5-sales-demo/pi-tui": "21.40.0",
-		"@f5-sales-demo/pi-utils": "21.40.0",
-		"@f5-sales-demo/xcsh-stats": "21.40.0",
+		"@f5-sales-demo/pi-agent-core": "21.41.0",
+		"@f5-sales-demo/pi-ai": "21.41.0",
+		"@f5-sales-demo/pi-natives": "21.41.0",
+		"@f5-sales-demo/pi-resource-management": "21.41.0",
+		"@f5-sales-demo/pi-tui": "21.41.0",
+		"@f5-sales-demo/pi-utils": "21.41.0",
+		"@f5-sales-demo/xcsh-stats": "21.41.0",
 		"@mozilla/readability": "^0.6",
 		"@sinclair/typebox": "0.34.52",
 		"@tobilu/qmd": "2.8.3",

package/src/capability/fs.ts

@@ -8,40 +8,47 @@ function resolvePath(filePath: string): string {
 	return path.resolve(filePath);
 }
 
-export async function readFile(filePath: string): Promise<string | null> {
+export async function readFile(filePath: string, signal?: AbortSignal): Promise<string | null> {
 	const abs = resolvePath(filePath);
 	if (contentCache.has(abs)) {
 		return contentCache.get(abs) ?? null;
 	}
 
 	try {
-		const content = await Bun.file(abs).text();
+		signal?.throwIfAborted();
+		const stat = await fs.promises.stat(abs);
+		if (!stat.isFile()) return null;
+		const content = await fs.promises.readFile(abs, { encoding: "utf8", signal });
 		contentCache.set(abs, content);
 		return content;
-	} catch {
+	} catch (error) {
+		if (signal?.aborted) throw error;
 		contentCache.set(abs, null);
 		return null;
 	}
 }
 
-export async function readDirEntries(dirPath: string): Promise<fs.Dirent[]> {
+export async function readDirEntries(dirPath: string, signal?: AbortSignal): Promise<fs.Dirent[]> {
 	const abs = resolvePath(dirPath);
 	if (dirCache.has(abs)) {
 		return dirCache.get(abs) ?? [];
 	}
 
 	try {
+		signal?.throwIfAborted();
 		const entries = await fs.promises.readdir(abs, { withFileTypes: true });
+		signal?.throwIfAborted();
 		dirCache.set(abs, entries);
 		return entries;
-	} catch {
+	} catch (error) {
+		if (signal?.aborted) throw error;
 		dirCache.set(abs, []);
 		return [];
 	}
 }
 
-export async function readDir(dirPath: string): Promise<string[]> {
-	const entries = await readDirEntries(dirPath);
+export async function readDir(dirPath: string, signal?: AbortSignal): Promise<string[]> {
+	const entries = await readDirEntries(dirPath, signal);
 	return entries.map(entry => entry.name);
 }
 
@@ -49,12 +56,14 @@ export async function walkUp(
 	startDir: string,
 	name: string,
 	opts: { file?: boolean; dir?: boolean } = {},
+	signal?: AbortSignal,
 ): Promise<string | null> {
 	const { file = true, dir = true } = opts;
 	let current = resolvePath(startDir);
 
 	while (true) {
-		const entries = await readDirEntries(current);
+		signal?.throwIfAborted();
+		const entries = await readDirEntries(current, signal);
 		const entry = entries.find(e => e.name === name);
 		if (entry) {
 			if (file && entry.isFile()) return path.join(current, name);
@@ -71,10 +80,11 @@ export async function walkUp(
  * Returns the directory containing `.git` (the repo root), or null if not in a git repo.
  * Results are based on the cached readDirEntries, so repeated calls are cheap.
  */
-export async function findRepoRoot(startDir: string): Promise<string | null> {
+export async function findRepoRoot(startDir: string, signal?: AbortSignal): Promise<string | null> {
 	let current = resolvePath(startDir);
 	while (true) {
-		const entries = await readDirEntries(current);
+		signal?.throwIfAborted();
+		const entries = await readDirEntries(current, signal);
 		if (entries.some(e => e.name === ".git")) {
 			return current;
 		}

package/src/capability/index.ts

@@ -114,6 +114,7 @@ async function loadImpl<T>(
 	const results = await Promise.all(
 		providers.map(async provider => {
 			try {
+				ctx.signal?.throwIfAborted();
 				const result = await logger.time(
 					`capability:${capability.id}:${provider.id}`,
 					provider.load.bind(provider),
@@ -121,6 +122,7 @@ async function loadImpl<T>(
 				);
 				return { provider, result };
 			} catch (error) {
+				if (ctx.signal?.aborted) throw error;
 				logger.debug(`capability:${capability.id}:${provider.id}:error`);
 				return { provider, error };
 			}
@@ -235,8 +237,9 @@ export async function loadCapability<T>(capabilityId: string, options: LoadOptio
 
 	const cwd = options.cwd ?? getProjectDir();
 	const home = os.homedir();
-	const repoRoot = await findRepoRoot(cwd);
-	const ctx: LoadContext = { cwd, home, repoRoot };
+	options.signal?.throwIfAborted();
+	const repoRoot = await findRepoRoot(cwd, options.signal);
+	const ctx: LoadContext = { cwd, home, repoRoot, signal: options.signal };
 	const providers = filterProviders(capability, options);
 
 	return await loadImpl(capability, providers, ctx, options);

package/src/capability/types.ts

@@ -16,6 +16,8 @@ export interface LoadContext {
 	home: string;
 	/** Git repository root (directory containing .git), or null if not in a repo */
 	repoRoot: string | null;
+	/** Cancellation for bounded discovery. */
+	signal?: AbortSignal;
 }
 
 /**
@@ -72,6 +74,8 @@ export interface LoadOptions {
 	includeDisabled?: boolean;
 	/** Explicit disabled extension IDs to apply instead of settings. */
 	disabledExtensions?: string[];
+	/** Cancellation for bounded discovery. */
+	signal?: AbortSignal;
 }
 
 /**

package/src/discovery/agents-md.ts

@@ -26,8 +26,9 @@ async function loadAgentsMd(ctx: LoadContext): Promise<LoadResult<ContextFile>>
 	let current = ctx.cwd;
 
 	while (true) {
+		ctx.signal?.throwIfAborted();
 		const candidate = path.join(current, "XCSH.md");
-		const content = await readFile(candidate);
+		const content = await readFile(candidate, ctx.signal);
 
 		if (content !== null) {
 			const parent = path.dirname(candidate);

package/src/discovery/agents.ts

@@ -52,10 +52,10 @@ function getProjectPathCandidates(ctx: LoadContext, ...segments: string[]): stri
 // Skills
 async function loadSkills(ctx: LoadContext): Promise<LoadResult<Skill>> {
 	const projectScans = getProjectPathCandidates(ctx, "skills").map(dir =>
-		scanSkillsFromDir(ctx, { dir, providerId: PROVIDER_ID, level: "project" }),
+		scanSkillsFromDir(ctx, { dir, providerId: PROVIDER_ID, level: "project", signal: ctx.signal }),
 	);
 	const userScans = getUserPathCandidates(ctx, "skills").map(dir =>
-		scanSkillsFromDir(ctx, { dir, providerId: PROVIDER_ID, level: "user" }),
+		scanSkillsFromDir(ctx, { dir, providerId: PROVIDER_ID, level: "user", signal: ctx.signal }),
 	);
 
 	const results = await Promise.all([...projectScans, ...userScans]);
@@ -170,7 +170,7 @@ registerProvider<SlashCommand>(slashCommandCapability.id, {
 // Context Files (AGENTS.md)
 async function loadContextFiles(ctx: LoadContext): Promise<LoadResult<ContextFile>> {
 	const load = async (filePath: string, level: "user" | "project"): Promise<ContextFile | null> => {
-		const content = await readFile(filePath);
+		const content = await readFile(filePath, ctx.signal);
 		if (!content) return null;
 		// filePath is <ancestor>/.agent(s)/AGENTS.md — go up past the config dir to the ancestor
 		const ancestorDir = path.dirname(path.dirname(filePath));
@@ -197,7 +197,7 @@ registerProvider<ContextFile>(contextFileCapability.id, {
 // System Prompt (SYSTEM.md)
 async function loadSystemPrompt(ctx: LoadContext): Promise<LoadResult<SystemPrompt>> {
 	const load = async (filePath: string, level: "user" | "project"): Promise<SystemPrompt | null> => {
-		const content = await readFile(filePath);
+		const content = await readFile(filePath, ctx.signal);
 		if (!content) return null;
 		return { path: filePath, content, level, _source: createSourceMeta(PROVIDER_ID, filePath, level) };
 	};

package/src/discovery/builtin.ts

@@ -225,7 +225,7 @@ async function loadSystemPrompt(ctx: LoadContext): Promise<LoadResult<SystemProm
 	const items: SystemPrompt[] = [];
 
 	const userPath = path.join(ctx.home, PATHS.userAgent, "SYSTEM.md");
-	const userContent = await readFile(userPath);
+	const userContent = await readFile(userPath, ctx.signal);
 	if (userContent) {
 		items.push({
 			path: userPath,
@@ -238,7 +238,7 @@ async function loadSystemPrompt(ctx: LoadContext): Promise<LoadResult<SystemProm
 	const nearestProjectConfigDir = await findNearestProjectConfigDir(ctx.cwd, ctx.repoRoot);
 	if (nearestProjectConfigDir) {
 		const projectPath = path.join(nearestProjectConfigDir.dir, "SYSTEM.md");
-		const projectContent = await readFile(projectPath);
+		const projectContent = await readFile(projectPath, ctx.signal);
 		if (projectContent) {
 			items.push({
 				path: projectPath,
@@ -270,6 +270,7 @@ async function loadSkills(ctx: LoadContext): Promise<LoadResult<Skill>> {
 			providerId: PROVIDER_ID,
 			level: "project",
 			requireDescription: true,
+			signal: ctx.signal,
 		}),
 	);
 
@@ -279,6 +280,7 @@ async function loadSkills(ctx: LoadContext): Promise<LoadResult<Skill>> {
 		providerId: PROVIDER_ID,
 		level: "user",
 		requireDescription: true,
+		signal: ctx.signal,
 	});
 
 	const results = await Promise.all([...projectScans, userScan]);
@@ -814,7 +816,7 @@ async function loadContextFiles(ctx: LoadContext): Promise<LoadResult<ContextFil
 	const warnings: string[] = [];
 
 	const userPath = path.join(ctx.home, PATHS.userAgent, "XCSH.md");
-	const userContent = await readFile(userPath);
+	const userContent = await readFile(userPath, ctx.signal);
 	if (userContent) {
 		items.push({
 			path: userPath,
@@ -827,7 +829,7 @@ async function loadContextFiles(ctx: LoadContext): Promise<LoadResult<ContextFil
 	const nearestProjectConfigDir = await findNearestProjectConfigDir(ctx.cwd, ctx.repoRoot);
 	if (nearestProjectConfigDir) {
 		const projectPath = path.join(nearestProjectConfigDir.dir, "XCSH.md");
-		const projectContent = await readFile(projectPath);
+		const projectContent = await readFile(projectPath, ctx.signal);
 		if (projectContent) {
 			items.push({
 				path: projectPath,

package/src/discovery/claude-plugins.ts

@@ -37,7 +37,7 @@ async function loadSkills(ctx: LoadContext): Promise<LoadResult<Skill>> {
 	const items: Skill[] = [];
 	const warnings: string[] = [];
 
-	const { roots, warnings: rootWarnings } = await listXcshPluginRoots(ctx.home, ctx.cwd);
+	const { roots, warnings: rootWarnings } = await listXcshPluginRoots(ctx.home, ctx.cwd, ctx.signal);
 	warnings.push(...rootWarnings);
 
 	const results = await Promise.all(
@@ -47,6 +47,7 @@ async function loadSkills(ctx: LoadContext): Promise<LoadResult<Skill>> {
 				dir: skillsDir,
 				providerId: PROVIDER_ID,
 				level: scopeToLevel(root.scope),
+				signal: ctx.signal,
 			});
 			return { root, result };
 		}),

package/src/discovery/claude.ts

@@ -132,7 +132,7 @@ async function loadContextFiles(ctx: LoadContext): Promise<LoadResult<ContextFil
 	const userBase = getUserClaude(ctx);
 	const userClaudeMd = path.join(userBase, "CLAUDE.md");
 
-	const userContent = await readFile(userClaudeMd);
+	const userContent = await readFile(userClaudeMd, ctx.signal);
 	if (userContent !== null) {
 		items.push({
 			path: userClaudeMd,
@@ -144,7 +144,7 @@ async function loadContextFiles(ctx: LoadContext): Promise<LoadResult<ContextFil
 
 	const projectBase = getProjectClaude(ctx);
 	const projectClaudeMd = path.join(projectBase, "CLAUDE.md");
-	const projectContent = await readFile(projectClaudeMd);
+	const projectContent = await readFile(projectClaudeMd, ctx.signal);
 	if (projectContent !== null) {
 		const depth = calculateDepth(ctx.cwd, path.dirname(projectBase), path.sep);
 		items.push({
@@ -175,6 +175,7 @@ async function loadSkills(ctx: LoadContext): Promise<LoadResult<Skill>> {
 				dir: path.join(current, CONFIG_DIR, "skills"),
 				providerId: PROVIDER_ID,
 				level: "project",
+				signal: ctx.signal,
 			}),
 		);
 		if (current === (ctx.repoRoot ?? ctx.home)) break;
@@ -184,7 +185,7 @@ async function loadSkills(ctx: LoadContext): Promise<LoadResult<Skill>> {
 	}
 
 	const [userResult, ...projectResults] = await Promise.allSettled([
-		scanSkillsFromDir(ctx, { dir: userSkillsDir, providerId: PROVIDER_ID, level: "user" }),
+		scanSkillsFromDir(ctx, { dir: userSkillsDir, providerId: PROVIDER_ID, level: "user", signal: ctx.signal }),
 		...projectScans,
 	]);
 
@@ -407,7 +408,7 @@ async function loadSystemPrompts(ctx: LoadContext): Promise<LoadResult<SystemPro
 	const userBase = getUserClaude(ctx);
 	const userSystemMd = path.join(userBase, "SYSTEM.md");
 
-	const content = await readFile(userSystemMd);
+	const content = await readFile(userSystemMd, ctx.signal);
 	if (content !== null) {
 		items.push({
 			path: userSystemMd,

package/src/discovery/codex.ts

@@ -56,7 +56,7 @@ async function loadContextFiles(ctx: LoadContext): Promise<LoadResult<ContextFil
 
 	// User level only: ~/.codex/AGENTS.md
 	const agentsMd = path.join(ctx.home, SOURCE_PATHS.codex.userBase, "AGENTS.md");
-	const agentsContent = await readFile(agentsMd);
+	const agentsContent = await readFile(agentsMd, ctx.signal);
 	if (agentsContent) {
 		items.push({
 			path: agentsMd,
@@ -221,11 +221,13 @@ async function loadSkills(ctx: LoadContext): Promise<LoadResult<Skill>> {
 			dir: userSkillsDir,
 			providerId: PROVIDER_ID,
 			level: "user",
+			signal: ctx.signal,
 		}),
 		scanSkillsFromDir(ctx, {
 			dir: projectSkillsDir,
 			providerId: PROVIDER_ID,
 			level: "project",
+			signal: ctx.signal,
 		}),
 	]);
 

package/src/discovery/gemini.ts

@@ -129,7 +129,7 @@ async function loadContextFiles(ctx: LoadContext): Promise<LoadResult<ContextFil
 	// User-level: ~/.gemini/GEMINI.md
 	const userGeminiMd = getUserPath(ctx, "gemini", "GEMINI.md");
 	if (userGeminiMd) {
-		const content = await readFile(userGeminiMd);
+		const content = await readFile(userGeminiMd, ctx.signal);
 		if (content) {
 			items.push({
 				path: userGeminiMd,
@@ -143,7 +143,7 @@ async function loadContextFiles(ctx: LoadContext): Promise<LoadResult<ContextFil
 	// Project-level: .gemini/GEMINI.md
 	const projectGeminiMd = getProjectPath(ctx, "gemini", "GEMINI.md");
 	if (projectGeminiMd) {
-		const content = await readFile(projectGeminiMd);
+		const content = await readFile(projectGeminiMd, ctx.signal);
 		if (content) {
 			const projectBase = getProjectPath(ctx, "gemini", "");
 			const depth = projectBase ? calculateDepth(ctx.cwd, projectBase, path.sep) : 0;
@@ -335,7 +335,7 @@ async function loadSystemPrompt(ctx: LoadContext): Promise<LoadResult<SystemProm
 	// User-level: ~/.gemini/system.md
 	const userSystemMd = getUserPath(ctx, "gemini", "system.md");
 	if (userSystemMd) {
-		const content = await readFile(userSystemMd);
+		const content = await readFile(userSystemMd, ctx.signal);
 		if (content) {
 			items.push({
 				path: userSystemMd,
@@ -349,7 +349,7 @@ async function loadSystemPrompt(ctx: LoadContext): Promise<LoadResult<SystemProm
 	// Project-level: .gemini/system.md
 	const projectSystemMd = getProjectPath(ctx, "gemini", "system.md");
 	if (projectSystemMd) {
-		const content = await readFile(projectSystemMd);
+		const content = await readFile(projectSystemMd, ctx.signal);
 		if (content) {
 			items.push({
 				path: projectSystemMd,

package/src/discovery/github.ts

@@ -35,7 +35,7 @@ async function loadContextFiles(ctx: LoadContext): Promise<LoadResult<ContextFil
 
 	const copilotInstructionsPath = getProjectPath(ctx, "github", "copilot-instructions.md");
 	if (copilotInstructionsPath) {
-		const content = await readFile(copilotInstructionsPath);
+		const content = await readFile(copilotInstructionsPath, ctx.signal);
 		if (content) {
 			const fileDir = path.dirname(copilotInstructionsPath);
 			const depth = calculateDepth(ctx.cwd, fileDir, path.sep);

package/src/discovery/helpers.ts

@@ -282,6 +282,7 @@ export interface ScanSkillsFromDirOptions {
 	providerId: string;
 	level: "user" | "project";
 	requireDescription?: boolean;
+	signal?: AbortSignal;
 }
 
 // Stable ordering used for skill lists in prompts: name (case-insensitive), then name, then path.
@@ -304,8 +305,11 @@ export async function scanSkillsFromDir(
 
 	let entries: fs.Dirent[];
 	try {
+		options.signal?.throwIfAborted();
 		entries = await fs.promises.readdir(dir, { withFileTypes: true });
+		options.signal?.throwIfAborted();
 	} catch (error) {
+		if (options.signal?.aborted) throw error;
 		if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
 			warnings.push(`Failed to read skills directory: ${dir} (${String(error)})`);
 		}
@@ -313,7 +317,7 @@ export async function scanSkillsFromDir(
 	}
 	const loadSkill = async (skillPath: string) => {
 		try {
-			const content = await readFile(skillPath);
+			const content = await readFile(skillPath, options.signal);
 			if (!content) return;
 			const { frontmatter, body } = parseFrontmatter(content, { source: skillPath });
 			if (frontmatter.enabled === false) {
@@ -333,13 +337,15 @@ export async function scanSkillsFromDir(
 				level,
 				_source: createSourceMeta(providerId, skillPath, level),
 			});
-		} catch {
+		} catch (error) {
+			if (options.signal?.aborted) throw error;
 			warnings.push(`Failed to read skill file: ${skillPath}`);
 		}
 	};
 
 	const work = [];
 	for (const entry of entries) {
+		options.signal?.throwIfAborted();
 		if (entry.name.startsWith(".")) continue;
 		if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
 		const skillPath = path.join(dir, entry.name, "SKILL.md");
@@ -679,12 +685,13 @@ export function parseXcshPluginsRegistry(content: string): XcshPluginsRegistry |
  * This is the single source of truth for "active project root" used by install,
  * uninstall, list, upgrade, discovery, and doctor. Deterministic for a given `cwd`.
  */
-export async function resolveActiveProjectRegistryPath(cwd: string): Promise<string | null> {
+export async function resolveActiveProjectRegistryPath(cwd: string, signal?: AbortSignal): Promise<string | null> {
 	// Pass 1: walk up looking for an existing .xcsh/ directory (nearest wins).
 	// Stop before os.homedir() — ~/.xcsh/ is the user-level config dir, not a project root.
 	const homeDir = os.homedir();
 	let dir = path.resolve(cwd);
 	while (dir !== homeDir) {
+		signal?.throwIfAborted();
 		try {
 			const stat = await fs.promises.stat(path.join(dir, CONFIG_DIR_NAME));
 			if (stat.isDirectory()) {
@@ -701,6 +708,7 @@ export async function resolveActiveProjectRegistryPath(cwd: string): Promise<str
 	// Pass 2: walk up looking for .git as a fallback anchor.
 	dir = path.resolve(cwd);
 	while (dir !== homeDir) {
+		signal?.throwIfAborted();
 		try {
 			await fs.promises.stat(path.join(dir, ".git"));
 			return path.join(dir, CONFIG_DIR_NAME, "plugins", "installed_plugins.json");
@@ -737,6 +745,9 @@ export async function resolveOrDefaultProjectRegistryPath(cwd: string): Promise<
 }
 
 const pluginRootsCache = new Map<string, { roots: XcshPluginRoot[]; warnings: string[] }>();
+const pluginSummariesCache = new Map<string, XcshPluginSummary[]>();
+const pluginSummariesInFlight = new Map<string, Promise<{ summaries: XcshPluginSummary[]; generation: number }>>();
+let pluginCacheGeneration = 0;
 
 /**
  * List all installed marketplace plugin roots from the plugin cache.
@@ -748,8 +759,10 @@ const pluginRootsCache = new Map<string, { roots: XcshPluginRoot[]; warnings: st
 export async function listXcshPluginRoots(
 	home: string,
 	cwd?: string,
+	signal?: AbortSignal,
 ): Promise<{ roots: XcshPluginRoot[]; warnings: string[] }> {
-	const resolvedProjectPath = cwd ? await resolveActiveProjectRegistryPath(cwd) : null;
+	signal?.throwIfAborted();
+	const resolvedProjectPath = cwd ? await resolveActiveProjectRegistryPath(cwd, signal) : null;
 	const cacheKey = `${home}:${resolvedProjectPath ?? ""}`;
 	const cached = pluginRootsCache.get(cacheKey);
 	if (cached) return cached;
@@ -758,7 +771,7 @@ export async function listXcshPluginRoots(
 	const warnings: string[] = [];
 	const projectRoots: XcshPluginRoot[] = [];
 	const marketplaceStates = new Map<string, MarketplaceRegistryEntry>();
-	const marketplacesContent = await readFile(path.join(home, getConfigDirName(), "marketplaces.json"));
+	const marketplacesContent = await readFile(path.join(home, getConfigDirName(), "marketplaces.json"), signal);
 	if (marketplacesContent) {
 		const marketplacesRegistry = tryParseJson<{ marketplaces?: MarketplaceRegistryEntry[] }>(marketplacesContent);
 		for (const marketplace of marketplacesRegistry?.marketplaces ?? []) {
@@ -769,7 +782,7 @@ export async function listXcshPluginRoots(
 	// ── Installed plugins registry ───────────────────────────────────────────
 	// Path derived from `home` (not os.homedir()) so test isolation works when home is overridden.
 	const registryPath = path.join(home, getConfigDirName(), "plugins", "installed_plugins.json");
-	const content = await readFile(registryPath);
+	const content = await readFile(registryPath, signal);
 	if (content) {
 		const registry = parseXcshPluginsRegistry(content);
 		if (registry) {
@@ -812,7 +825,7 @@ export async function listXcshPluginRoots(
 	// Project entries take precedence over user entries for the same plugin ID.
 	// Skip if the project registry is the same file as the user registry (home === cwd).
 	if (resolvedProjectPath && resolvedProjectPath !== registryPath) {
-		const projectContent = await readFile(resolvedProjectPath);
+		const projectContent = await readFile(resolvedProjectPath, signal);
 		if (projectContent) {
 			const projectRegistry = parseXcshPluginsRegistry(projectContent);
 			if (projectRegistry) {
@@ -890,6 +903,22 @@ export interface XcshPluginSummary {
 	description: string;
 }
 
+export interface XcshPluginSummaryLoadDependencies {
+	resolveProjectRegistryPath: (cwd: string, signal?: AbortSignal) => Promise<string | null>;
+	loadRoots: (
+		home: string,
+		cwd?: string,
+		signal?: AbortSignal,
+	) => Promise<{ roots: XcshPluginRoot[]; warnings: string[] }>;
+	loadSummary: (root: { plugin: string; path: string }, signal?: AbortSignal) => Promise<XcshPluginSummary>;
+}
+
+export interface XcshPluginSummaryLoadResult {
+	summaries: XcshPluginSummary[];
+	cacheStatus: "completed" | "cached";
+	generation: number;
+}
+
 /**
  * Sanitize a manifest/package description for single-line rendering in the system prompt.
  * Collapses whitespace runs to single spaces, trims, and caps length (appending "…" if truncated).
@@ -903,7 +932,10 @@ function sanitizePluginDescription(description: unknown): string {
 }
 
 /** Read a plugin's human name+description from its own manifest. Fail-safe: never throws. */
-export async function readPluginSummary(root: { plugin: string; path: string }): Promise<XcshPluginSummary> {
+export async function readPluginSummary(
+	root: { plugin: string; path: string },
+	signal?: AbortSignal,
+): Promise<XcshPluginSummary> {
 	// Precedence mirrors MarketplaceManager#resolvePluginVersion.
 	const candidates: Array<{ rel: string; pick: (m: any) => { name?: string; description?: string } }> = [
 		{ rel: ".xcsh-plugin/plugin.json", pick: m => ({ name: m?.name, description: m?.description }) },
@@ -913,32 +945,85 @@ export async function readPluginSummary(root: { plugin: string; path: string }):
 		},
 	];
 	for (const c of candidates) {
+		signal?.throwIfAborted();
 		try {
-			const m = await Bun.file(path.join(root.path, c.rel)).json();
+			const manifestPath = path.join(root.path, c.rel);
+			const stat = await fs.promises.stat(manifestPath);
+			if (!stat.isFile()) continue;
+			const content = await fs.promises.readFile(manifestPath, { encoding: "utf8", signal });
+			const m = JSON.parse(content);
 			const { name, description } = c.pick(m);
 			if (name || description) {
 				return { id: root.plugin, name: name ?? root.plugin, description: sanitizePluginDescription(description) };
 			}
-		} catch {
+		} catch (error) {
+			if (signal?.aborted) throw error;
 			// try next candidate
 		}
 	}
 	return { id: root.plugin, name: root.plugin, description: "" };
 }
 
-/** All installed plugins as {name, description}, sorted by name, deduped by plugin id. */
-export async function listXcshPluginSummaries(home: string, cwd?: string): Promise<XcshPluginSummary[]> {
-	try {
-		const { roots } = await listXcshPluginRoots(home, cwd);
+const defaultPluginSummaryLoadDependencies: XcshPluginSummaryLoadDependencies = {
+	resolveProjectRegistryPath: resolveActiveProjectRegistryPath,
+	loadRoots: listXcshPluginRoots,
+	loadSummary: readPluginSummary,
+};
+
+/** Load the installed-plugin summary snapshot, deduplicating concurrent discovery by home/project scope. */
+export async function loadXcshPluginSummaries(
+	home: string,
+	cwd?: string,
+	signal?: AbortSignal,
+	dependencies: XcshPluginSummaryLoadDependencies = defaultPluginSummaryLoadDependencies,
+): Promise<XcshPluginSummaryLoadResult> {
+	signal?.throwIfAborted();
+	const resolvedProjectPath = cwd ? await dependencies.resolveProjectRegistryPath(cwd, signal) : null;
+	const cacheKey = `${home}:${resolvedProjectPath ?? ""}`;
+	const cached = pluginSummariesCache.get(cacheKey);
+	if (cached) return { summaries: cached, cacheStatus: "cached", generation: pluginCacheGeneration };
+
+	const existing = pluginSummariesInFlight.get(cacheKey);
+	if (existing) {
+		const result = await existing;
+		return { ...result, cacheStatus: "cached" };
+	}
+
+	const generation = pluginCacheGeneration;
+	const load = (async () => {
+		signal?.throwIfAborted();
+		const { roots } = await dependencies.loadRoots(home, cwd, signal);
 		const seen = new Set<string>();
 		const out: XcshPluginSummary[] = [];
 		for (const r of roots) {
+			signal?.throwIfAborted();
 			if (seen.has(r.plugin)) continue;
 			seen.add(r.plugin);
-			out.push(await readPluginSummary(r));
+			out.push(await dependencies.loadSummary(r, signal));
 		}
-		return out.sort((a, b) => a.name.localeCompare(b.name));
-	} catch {
+		const summaries = out.sort((a, b) => a.name.localeCompare(b.name));
+		if (generation === pluginCacheGeneration) pluginSummariesCache.set(cacheKey, summaries);
+		return { summaries, generation };
+	})();
+	pluginSummariesInFlight.set(cacheKey, load);
+	try {
+		return { ...(await load), cacheStatus: "completed" };
+	} finally {
+		if (pluginSummariesInFlight.get(cacheKey) === load) pluginSummariesInFlight.delete(cacheKey);
+	}
+}
+
+/** All installed plugins as {name, description}, sorted by name, deduped by plugin id. */
+export async function listXcshPluginSummaries(
+	home: string,
+	cwd?: string,
+	signal?: AbortSignal,
+	dependencies?: XcshPluginSummaryLoadDependencies,
+): Promise<XcshPluginSummary[]> {
+	try {
+		return (await loadXcshPluginSummaries(home, cwd, signal, dependencies)).summaries;
+	} catch (error) {
+		if (signal?.aborted) throw error;
 		return [];
 	}
 }
@@ -947,7 +1032,10 @@ export async function listXcshPluginSummaries(home: string, cwd?: string): Promi
  * Clear the plugin roots cache (useful for testing or when plugins change).
  */
 export function clearXcshPluginRootsCache(): void {
+	pluginCacheGeneration += 1;
 	pluginRootsCache.clear();
+	pluginSummariesCache.clear();
+	pluginSummariesInFlight.clear();
 	preloadedPluginRoots = [...injectedPluginDirRoots];
 	// Re-warm preloaded roots asynchronously so sync LSP config reads stay valid
 	if (lastPreloadHome) {
@@ -955,6 +1043,11 @@ export function clearXcshPluginRootsCache(): void {
 	}
 }
 
+/** Monotonic generation used by session snapshots to detect explicit plugin invalidation. */
+export function getXcshPluginCacheGeneration(): number {
+	return pluginCacheGeneration;
+}
+
 // ── Preloaded plugin roots (for sync consumers like LSP config) ─────────────
 // Populated at startup by preloadPluginRoots(). Read synchronously by
 // getPreloadedPluginRoots(). Safe degradation: empty array if not warmed.