@oh-my-pi/pi-coding-agent 16.0.0 → 16.0.1

package/src/eval/py/prelude.py

@@ -519,7 +519,7 @@ if "__omp_prelude_loaded__" not in globals():
         text = res.get("text") if isinstance(res, dict) else res
         return json.loads(text) if schema is not None else text
 
-    def agent(prompt, *, agent_type="task", model=None, label=None, schema=None):
+    def agent(prompt, *, agent_type="task", model=None, label=None, schema=None, return_handle=False):
         """Run a subagent and return its final output.
 
         `agent_type` selects the subagent definition (default "task"). Pass
@@ -527,6 +527,15 @@ if "__omp_prelude_loaded__" not in globals():
         id, and `schema` to request structured JSON output; when `schema` is
         supplied the parsed object is returned. Share background by writing a
         local:// file and referencing it in the prompt.
+
+        Set `return_handle=True` to receive a DAG node dict instead of bare
+        text: ``{"text", "output", "handle", "id", "agent"}`` where ``handle``
+        is the spawned agent's recoverable ``agent://<id>`` URI. A downstream
+        ``pipeline``/``parallel`` stage embeds that ``handle`` (or ``output``)
+        in its prompt so a large transcript flows through the graph by
+        reference, never re-inlined. When ``schema`` is also set the parsed
+        object lands under ``"data"``. If the bridge returns no recoverable id
+        the node still resolves with ``handle=None`` — the helper never throws.
         """
         args = {"prompt": prompt}
         if agent_type is not None:
@@ -539,7 +548,22 @@ if "__omp_prelude_loaded__" not in globals():
             args["schema"] = schema
         res = _bridge_call("__agent__", args)
         text = res.get("text") if isinstance(res, dict) else res
-        return json.loads(text) if schema is not None else text
+        parsed = json.loads(text) if schema is not None else text
+        if not return_handle:
+            return parsed
+        details = res.get("details") if isinstance(res, dict) else None
+        if not isinstance(details, dict) or details.get("id") is None:
+            return {"text": text, "output": text, "handle": None, "id": None, "agent": None}
+        node = {
+            "text": text,
+            "output": text,
+            "handle": f"agent://{details['id']}",
+            "id": details["id"],
+            "agent": details.get("agent"),
+        }
+        if schema is not None:
+            node["data"] = parsed
+        return node
 
     def _concurrency_limit():
         """Worker-pool ceiling from the host ``task.maxConcurrency`` setting.

package/src/extensibility/custom-commands/bundled/review/index.ts

@@ -17,6 +17,7 @@ import type { HookCommandContext } from "../../../../extensibility/hooks/types";
 import reviewCustomRequestTemplate from "../../../../prompts/review-custom-request.md" with { type: "text" };
 import reviewHeadlessRequestTemplate from "../../../../prompts/review-headless-request.md" with { type: "text" };
 import reviewRequestTemplate from "../../../../prompts/review-request.md" with { type: "text" };
+import * as gh from "../../../../tools/gh";
 import * as git from "../../../../utils/git";
 import * as jj from "../../../../utils/jj";
 
@@ -45,6 +46,25 @@ interface CurrentReviewDiff {
 	mode: string;
 }
 
+interface ReviewPrRef {
+	repo: string;
+	number: number;
+	raw: string;
+	kind: "github-url" | "pr-url";
+}
+
+interface ParsedReviewArgs {
+	prRef: ReviewPrRef | undefined;
+	extraInstructions: string;
+}
+
+type ReviewMenuChoice =
+	| { kind: "detected-pr"; ref: ReviewPrRef }
+	| { kind: "base-branch" }
+	| { kind: "uncommitted" }
+	| { kind: "commit" }
+	| { kind: "custom" };
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Exclusion patterns for noise files
 // ─────────────────────────────────────────────────────────────────────────────
@@ -204,6 +224,7 @@ function getDiffPreview(hunks: string, maxLines: number): string {
 const MAX_DIFF_CHARS = 50_000; // Don't include diff above this
 const MAX_FILES_FOR_INLINE_DIFF = 20; // Don't include diff if more files than this
 const DEFAULT_LARGE_DIFF_INSTRUCTION = "MUST run `git diff`/`git show` for assigned files";
+const DEFAULT_CONTEXT_INSTRUCTION = "MAY read full file context as needed via `read`";
 const GIT_UNCOMMITTED_DIFF_INSTRUCTION =
 	"MUST run both `git diff -- <path>` and `git diff --cached -- <path>` for assigned files";
 const JJ_UNCOMMITTED_DIFF_INSTRUCTION = "MUST run `jj --ignore-working-copy diff --git -- <path>` for assigned files";
@@ -215,7 +236,7 @@ function buildReviewPrompt(
 	mode: string,
 	stats: DiffStats,
 	rawDiff: string,
-	options: { additionalInstructions?: string; diffInstruction?: string } = {},
+	options: { additionalInstructions?: string; diffInstruction?: string; contextInstruction?: string } = {},
 ): string {
 	const agentCount = getRecommendedAgentCount(stats);
 	const skipDiff = rawDiff.length > MAX_DIFF_CHARS || stats.files.length > MAX_FILES_FOR_INLINE_DIFF;
@@ -242,6 +263,7 @@ function buildReviewPrompt(
 		linesPerFile,
 		additionalInstructions: options.additionalInstructions,
 		diffInstruction: options.diffInstruction ?? DEFAULT_LARGE_DIFF_INSTRUCTION,
+		contextInstruction: options.contextInstruction ?? DEFAULT_CONTEXT_INSTRUCTION,
 	});
 }
 
@@ -253,6 +275,203 @@ function buildHeadlessReviewPrompt(focus?: string): string {
 	return prompt.render(reviewHeadlessRequestTemplate, { focus });
 }
 
+const REVIEW_CONTEXT_PR_LIMIT = 3;
+const REPO_SEGMENT_PATTERN = /^[A-Za-z0-9_.-]+$/;
+const PR_SCHEME_PATTERN = /^pr:\/\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)\/([1-9]\d*)(?:\/diff(?:\/(?:all|[1-9]\d*))?)?$/;
+const PR_REF_TEXT_PATTERN = /https:\/\/github\.com\/[^\s<>"']+|pr:\/\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/[^\s<>"']+/g;
+
+function stripTrailingPrRefPunctuation(text: string): string {
+	return text.replace(/[.,)\]>]+$/g, "");
+}
+
+function isValidRepoSegment(segment: string | undefined): segment is string {
+	return segment !== undefined && REPO_SEGMENT_PATTERN.test(segment);
+}
+
+function parsePositivePrNumber(value: string | undefined): number | undefined {
+	if (value === undefined || !/^[1-9]\d*$/.test(value)) return undefined;
+	const parsed = Number(value);
+	return Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+
+function parseGithubPrUrl(text: string): ReviewPrRef | undefined {
+	let url: URL;
+	try {
+		url = new URL(text);
+	} catch {
+		return undefined;
+	}
+
+	if (url.protocol !== "https:" || url.hostname !== "github.com") return undefined;
+
+	const parts = url.pathname.split("/").filter(Boolean);
+	if (parts.length < 4 || parts[2] !== "pull") return undefined;
+
+	const [owner, repo, , numberPart] = parts;
+	if (!isValidRepoSegment(owner) || !isValidRepoSegment(repo)) return undefined;
+
+	const number = parsePositivePrNumber(numberPart);
+	if (number === undefined) return undefined;
+
+	return { repo: `${owner}/${repo}`, number, raw: text, kind: "github-url" };
+}
+
+function parsePrSchemeRef(text: string): ReviewPrRef | undefined {
+	const match = PR_SCHEME_PATTERN.exec(text);
+	if (!match) return undefined;
+
+	const [, owner, repo, numberPart] = match;
+	const number = parsePositivePrNumber(numberPart);
+	if (number === undefined) return undefined;
+
+	return { repo: `${owner}/${repo}`, number, raw: text, kind: "pr-url" };
+}
+
+function parseReviewPrRef(text: string): ReviewPrRef | undefined {
+	const candidate = stripTrailingPrRefPunctuation(text);
+	return parseGithubPrUrl(candidate) ?? parsePrSchemeRef(candidate);
+}
+
+function buildPrLargeDiffInstruction(ref: ReviewPrRef): string {
+	const prDiffUrl = `pr://${ref.repo}/${ref.number}/diff`;
+	return `MUST read assigned PR file diffs from \`${prDiffUrl}/all\` or per-file \`${prDiffUrl}/<index>\`; NEVER use local \`git diff\`/\`git show\` for PR diff content`;
+}
+
+function buildPrContextInstruction(ref: ReviewPrRef): string {
+	const prDiffUrl = `pr://${ref.repo}/${ref.number}/diff`;
+	return `MUST NOT read local workspace files for PR file context; use the fetched PR diff and \`${prDiffUrl}/all\` or per-file \`${prDiffUrl}/<index>\` only`;
+}
+
+function extractReviewPrRefFromArgs(args: string[]): ParsedReviewArgs {
+	let prRef: ReviewPrRef | undefined;
+	let prRefIndex = -1;
+	for (const [idx, arg] of args.entries()) {
+		const parsed = parseReviewPrRef(arg);
+		if (parsed) {
+			prRef = parsed;
+			prRefIndex = idx;
+			break;
+		}
+	}
+
+	return {
+		prRef,
+		extraInstructions: args.filter((_, idx) => idx !== prRefIndex).join(" "),
+	};
+}
+
+function extractReviewPrRefsFromText(text: string): ReviewPrRef[] {
+	return Array.from(text.matchAll(PR_REF_TEXT_PATTERN), match => parseReviewPrRef(match[0])).filter(
+		(ref): ref is ReviewPrRef => ref !== undefined,
+	);
+}
+
+function buildReviewPromptFromDiff(
+	ctx: HookCommandContext,
+	mode: string,
+	diffText: string,
+	extraInstructions: string | undefined,
+	emptyMessage: string,
+	options: { diffInstruction?: string; filteredMessage?: string; contextInstruction?: string } = {},
+): string | undefined {
+	if (!diffText.trim()) {
+		if (ctx.hasUI) ctx.ui.notify(emptyMessage, "warning");
+		return undefined;
+	}
+
+	const stats = parseDiff(diffText);
+	if (stats.files.length === 0) {
+		if (ctx.hasUI)
+			ctx.ui.notify(options.filteredMessage ?? "No reviewable files (all changes filtered out)", "warning");
+		return undefined;
+	}
+
+	return buildReviewPrompt(mode, stats, diffText, {
+		additionalInstructions: extraInstructions,
+		diffInstruction: options.diffInstruction,
+		contextInstruction: options.contextInstruction,
+	});
+}
+
+async function buildPrReviewPrompt(
+	api: CustomCommandAPI,
+	ctx: HookCommandContext,
+	ref: ReviewPrRef,
+	extraInstructions: string,
+): Promise<string | undefined> {
+	let diffText: string;
+	try {
+		const lookup = await gh.getOrFetchPrDiff({ cwd: api.cwd, repo: ref.repo, number: ref.number });
+		diffText = lookup.payload.unified;
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		const failure = `Failed to fetch PR diff for ${ref.repo}#${ref.number}: ${message}`;
+		if (ctx.hasUI) {
+			ctx.ui.notify(failure, "error");
+			return undefined;
+		}
+		return failure;
+	}
+
+	const promptText = buildReviewPromptFromDiff(
+		ctx,
+		`PR ${ref.repo}#${ref.number}`,
+		diffText,
+		extraInstructions || undefined,
+		`PR ${ref.repo}#${ref.number} has no diff content available`,
+		{ diffInstruction: buildPrLargeDiffInstruction(ref), contextInstruction: buildPrContextInstruction(ref) },
+	);
+	if (promptText !== undefined || ctx.hasUI) return promptText;
+	return `Unable to review PR ${ref.repo}#${ref.number}: no diff content available.`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function getTextContentParts(content: unknown): string[] {
+	if (typeof content === "string") return [content];
+	if (!Array.isArray(content)) return [];
+
+	const parts: string[] = [];
+	for (const item of content) {
+		if (isRecord(item) && item.type === "text" && typeof item.text === "string") {
+			parts.push(item.text);
+		}
+	}
+	return parts;
+}
+
+function findRecentPrRefs(ctx: HookCommandContext, limit: number): ReviewPrRef[] {
+	const refs: ReviewPrRef[] = [];
+	const seen = new Set<string>();
+	const entries = ctx.sessionManager.getBranch();
+
+	for (let idx = entries.length - 1; idx >= 0 && refs.length < limit; idx--) {
+		const entry = entries[idx];
+		if (entry?.type !== "message") continue;
+		const message = entry.message;
+		if (message.role !== "user" && message.role !== "assistant") continue;
+
+		const parts = getTextContentParts(message.content);
+		for (let partIdx = parts.length - 1; partIdx >= 0; partIdx--) {
+			const part = parts[partIdx];
+			const partRefs = extractReviewPrRefsFromText(part);
+			for (let refIdx = partRefs.length - 1; refIdx >= 0; refIdx--) {
+				const ref = partRefs[refIdx];
+				const key = `${ref.repo.toLowerCase()}#${ref.number}`;
+				if (seen.has(key)) continue;
+				seen.add(key);
+				refs.push(ref);
+				if (refs.length >= limit) break;
+			}
+			if (refs.length >= limit) break;
+		}
+	}
+
+	return refs;
+}
+
 export class ReviewCommand implements CustomCommand {
 	name = "review";
 	description = "Launch interactive code review";
@@ -260,36 +479,56 @@ export class ReviewCommand implements CustomCommand {
 	constructor(private api: CustomCommandAPI) {}
 
 	async execute(args: string[], ctx: HookCommandContext): Promise<string | undefined> {
-		if (!ctx.hasUI) {
-			return buildHeadlessReviewPrompt(args.length > 0 ? args.join(" ") : undefined);
+		const parsedArgs = extractReviewPrRefFromArgs(args);
+		if (parsedArgs.prRef) {
+			return buildPrReviewPrompt(this.api, ctx, parsedArgs.prRef, parsedArgs.extraInstructions);
 		}
 
-		// Inline args act as additional instructions appended to the generated prompt.
-		// When present, skip option 4 (editor) — the args already provide the instructions.
-		const extraInstructions = args.length > 0 ? args.join(" ") : undefined;
+		const extraInstructions = parsedArgs.extraInstructions || undefined;
+		if (!ctx.hasUI) {
+			return buildHeadlessReviewPrompt(extraInstructions);
+		}
 
-		const menuItems = extraInstructions
-			? [
-					"1. Review against a base branch (PR Style)",
-					"2. Review uncommitted changes",
-					"3. Review a specific commit",
-				]
-			: [
-					"1. Review against a base branch (PR Style)",
-					"2. Review uncommitted changes",
-					"3. Review a specific commit",
-					"4. Custom review instructions",
-				];
+		const choices: Array<{ label: string; value: ReviewMenuChoice }> = [
+			...findRecentPrRefs(ctx, REVIEW_CONTEXT_PR_LIMIT).map(ref => ({
+				label: `Review PR ${ref.repo}#${ref.number} from conversation`,
+				value: { kind: "detected-pr" as const, ref },
+			})),
+			{
+				label: "1. Review against a base branch (PR Style)",
+				value: { kind: "base-branch" },
+			},
+			{
+				label: "2. Review uncommitted changes",
+				value: { kind: "uncommitted" },
+			},
+			{
+				label: "3. Review a specific commit",
+				value: { kind: "commit" },
+			},
+		];
+
+		if (!extraInstructions) {
+			choices.push({
+				label: "4. Custom review instructions",
+				value: { kind: "custom" },
+			});
+		}
 
-		const mode = await ctx.ui.select("Review Mode", menuItems);
+		const selected = await ctx.ui.select(
+			"Review Mode",
+			choices.map(choice => choice.label),
+		);
+		if (!selected) return undefined;
 
-		if (!mode) return undefined;
+		const selectedChoice = choices.find(choice => choice.label === selected)?.value;
+		if (!selectedChoice) return undefined;
 
-		const modeNum = parseInt(mode[0], 10);
+		switch (selectedChoice.kind) {
+			case "detected-pr":
+				return buildPrReviewPrompt(this.api, ctx, selectedChoice.ref, extraInstructions ?? "");
 
-		switch (modeNum) {
-			case 1: {
-				// PR-style review against base branch
+			case "base-branch": {
 				const branches = await getGitBranches(this.api);
 				if (branches.length === 0) {
 					ctx.ui.notify("No git branches found", "error");
@@ -308,62 +547,43 @@ export class ReviewCommand implements CustomCommand {
 					return undefined;
 				}
 
-				if (!diffText.trim()) {
-					ctx.ui.notify(`No changes between ${baseBranch} and ${currentBranch}`, "warning");
-					return undefined;
-				}
-
-				const stats = parseDiff(diffText);
-				if (stats.files.length === 0) {
-					ctx.ui.notify("No reviewable files (all changes filtered out)", "warning");
-					return undefined;
-				}
-
-				return buildReviewPrompt(
+				return buildReviewPromptFromDiff(
+					ctx,
 					`Reviewing changes between \`${baseBranch}\` and \`${currentBranch}\` (PR-style)`,
-					stats,
 					diffText,
-					{ additionalInstructions: extraInstructions },
+					extraInstructions,
+					`No changes between ${baseBranch} and ${currentBranch}`,
 				);
 			}
 
-			case 2: {
+			case "uncommitted": {
 				const reviewDiff = await getUncommittedReviewDiff(this.api).catch(err => {
 					ctx.ui.notify(`Failed to get diff: ${err instanceof Error ? err.message : String(err)}`, "error");
 					return undefined;
 				});
 				if (!reviewDiff) return undefined;
 
-				if (!reviewDiff.diffText.trim()) {
-					ctx.ui.notify(reviewDiff.emptyMessage ?? "No diff content found", "warning");
-					return undefined;
-				}
-
-				const stats = parseDiff(reviewDiff.diffText);
-				if (stats.files.length === 0) {
-					ctx.ui.notify("No reviewable files (all changes filtered out)", "warning");
-					return undefined;
-				}
-
-				return buildReviewPrompt(reviewDiff.mode, stats, reviewDiff.diffText, {
-					additionalInstructions: extraInstructions,
-					diffInstruction: reviewDiff.diffInstruction,
-				});
+				return buildReviewPromptFromDiff(
+					ctx,
+					reviewDiff.mode,
+					reviewDiff.diffText,
+					extraInstructions,
+					reviewDiff.emptyMessage ?? "No diff content found",
+					{ diffInstruction: reviewDiff.diffInstruction },
+				);
 			}
 
-			case 3: {
-				// Specific commit
+			case "commit": {
 				const commits = await getRecentCommits(this.api, 20);
 				if (commits.length === 0) {
 					ctx.ui.notify("No commits found", "error");
 					return undefined;
 				}
 
-				const selected = await ctx.ui.select("Select commit to review", commits);
-				if (!selected) return undefined;
+				const selectedCommit = await ctx.ui.select("Select commit to review", commits);
+				if (!selectedCommit) return undefined;
 
-				// Extract commit hash from selection (format: "abc1234 message")
-				const hash = selected.split(" ")[0];
+				const hash = selectedCommit.split(" ")[0];
 
 				let diffText: string;
 				try {
@@ -373,24 +593,17 @@ export class ReviewCommand implements CustomCommand {
 					return undefined;
 				}
 
-				if (!diffText.trim()) {
-					ctx.ui.notify("Commit has no diff content", "warning");
-					return undefined;
-				}
-
-				const stats = parseDiff(diffText);
-				if (stats.files.length === 0) {
-					ctx.ui.notify("No reviewable files in commit (all changes filtered out)", "warning");
-					return undefined;
-				}
-
-				return buildReviewPrompt(`Reviewing commit \`${hash}\``, stats, diffText, {
-					additionalInstructions: extraInstructions,
-				});
+				return buildReviewPromptFromDiff(
+					ctx,
+					`Reviewing commit \`${hash}\``,
+					diffText,
+					extraInstructions,
+					"Commit has no diff content",
+					{ filteredMessage: "No reviewable files in commit (all changes filtered out)" },
+				);
 			}
 
-			case 4: {
-				// Custom instructions with opportunistic current-diff context.
+			case "custom": {
 				const instructions = await ctx.ui.editor(
 					"Enter custom review instructions",
 					"Review the following:\n\n",
@@ -403,7 +616,6 @@ export class ReviewCommand implements CustomCommand {
 
 				if (reviewDiff?.diffText.trim()) {
 					const stats = parseDiff(reviewDiff.diffText);
-					// Even if all files filtered, include the custom instructions
 					return buildReviewPrompt(
 						`Custom review: ${instructions.split("\n")[0].slice(0, 60)}…`,
 						stats,
@@ -417,9 +629,6 @@ export class ReviewCommand implements CustomCommand {
 
 				return buildCustomReviewPrompt(instructions);
 			}
-
-			default:
-				return undefined;
 		}
 	}
 }

package/src/extensibility/plugins/loader.ts

@@ -9,6 +9,7 @@ import * as path from "node:path";
 import { getPluginsLockfile, getPluginsNodeModules, getPluginsPackageJson, isEnoent } from "@oh-my-pi/pi-utils";
 import { getConfigDirPaths } from "../../config";
 import { installLegacyPiSpecifierShim } from "./legacy-pi-compat";
+import { normalizePluginRuntimeConfig } from "./runtime-config";
 import type { InstalledPlugin, PluginManifest, PluginRuntimeConfig, ProjectPluginOverrides } from "./types";
 
 installLegacyPiSpecifierShim();
@@ -28,9 +29,9 @@ installLegacyPiSpecifierShim();
 async function loadRuntimeConfig(home?: string): Promise<PluginRuntimeConfig> {
 	const lockPath = getPluginsLockfile(home);
 	try {
-		return await Bun.file(lockPath).json();
+		return normalizePluginRuntimeConfig(await Bun.file(lockPath).json());
 	} catch (err) {
-		if (isEnoent(err)) return { plugins: {}, settings: {} };
+		if (isEnoent(err)) return normalizePluginRuntimeConfig({});
 		throw err;
 	}
 }

package/src/extensibility/plugins/manager.ts

@@ -15,6 +15,7 @@ import { type GitSource, parseGitUrl } from "./git-url";
 import { installLegacyPiSpecifierShim, loadLegacyPiModule } from "./legacy-pi-compat";
 import { resolvePluginManifestEntries } from "./loader";
 import { extractPackageName, parsePluginSpec } from "./parser";
+import { normalizePluginRuntimeConfig } from "./runtime-config";
 import type {
 	DoctorCheck,
 	DoctorOptions,
@@ -124,11 +125,11 @@ export class PluginManager {
 	async #loadRuntimeConfig(): Promise<PluginRuntimeConfig> {
 		const lockPath = getPluginsLockfile();
 		try {
-			return await Bun.file(lockPath).json();
+			return normalizePluginRuntimeConfig(await Bun.file(lockPath).json());
 		} catch (err) {
-			if (isEnoent(err)) return { plugins: {}, settings: {} };
+			if (isEnoent(err)) return normalizePluginRuntimeConfig({});
 			logger.warn("Failed to load plugin runtime config", { path: lockPath, error: String(err) });
-			return { plugins: {}, settings: {} };
+			return normalizePluginRuntimeConfig({});
 		}
 	}
 

package/src/extensibility/plugins/marketplace/fetcher.ts

@@ -192,8 +192,33 @@ export function parseMarketplaceCatalog(content: string, filePath: string): Mark
 
 // ── fetchMarketplace ──────────────────────────────────────────────────
 
-/** Relative path from a marketplace root to its catalog file. */
-const CATALOG_RELATIVE_PATH = path.join(".claude-plugin", "marketplace.json");
+/**
+ * Catalog paths tried in priority order: omp-namespaced override first, then
+ * the Claude Code-compatible fallback so existing marketplaces keep loading.
+ */
+const CATALOG_RELATIVE_PATHS: readonly string[] = [
+	path.join(".omp-plugin", "marketplace.json"),
+	path.join(".claude-plugin", "marketplace.json"),
+];
+
+async function readMarketplaceCatalog(root: string): Promise<{ catalogPath: string; content: string }> {
+	const tried: string[] = [];
+	for (const rel of CATALOG_RELATIVE_PATHS) {
+		const catalogPath = path.join(root, rel);
+		tried.push(catalogPath);
+		try {
+			const content = await Bun.file(catalogPath).text();
+			return { catalogPath, content };
+		} catch (err) {
+			if (isEnoent(err)) continue;
+			throw err;
+		}
+	}
+	throw new Error(
+		`Marketplace catalog not found at ${tried.map(p => `"${p}"`).join(" or ")}. ` +
+			`Ensure the directory exists and contains one of: ${CATALOG_RELATIVE_PATHS.join(", ")}.`,
+	);
+}
 
 /**
  * Expand a `~/...` path to an absolute path using os.homedir().
@@ -220,21 +245,7 @@ export async function fetchMarketplace(source: string, cacheDir: string): Promis
 
 	if (type === "local") {
 		const resolved = path.resolve(expandHome(source));
-		const catalogPath = path.join(resolved, CATALOG_RELATIVE_PATH);
-
-		let content: string;
-		try {
-			content = await Bun.file(catalogPath).text();
-		} catch (err) {
-			if (isEnoent(err)) {
-				throw new Error(
-					`Marketplace catalog not found at "${catalogPath}". ` +
-						`Ensure the directory exists and contains a .claude-plugin/marketplace.json file.`,
-				);
-			}
-			throw err;
-		}
-
+		const { catalogPath, content } = await readMarketplaceCatalog(resolved);
 		const catalog = parseMarketplaceCatalog(content, catalogPath);
 		return { catalog };
 	}
@@ -280,27 +291,14 @@ async function cloneAndReadCatalog(url: string, cacheDir: string): Promise<Fetch
 	logger.debug(`[marketplace] cloning ${url} → ${tmpDir}`);
 	await git.clone(url, tmpDir);
 
-	const catalogPath = path.join(tmpDir, CATALOG_RELATIVE_PATH);
-	let content: string;
 	try {
-		content = await Bun.file(catalogPath).text();
-	} catch (err) {
-		await fs.rm(tmpDir, { recursive: true, force: true });
-		if (isEnoent(err)) {
-			throw new Error(`Cloned repository has no marketplace catalog at ${CATALOG_RELATIVE_PATH}`);
-		}
-		throw err;
-	}
-
-	let catalog: MarketplaceCatalog;
-	try {
-		catalog = parseMarketplaceCatalog(content, catalogPath);
+		const { catalogPath, content } = await readMarketplaceCatalog(tmpDir);
+		const catalog = parseMarketplaceCatalog(content, catalogPath);
+		return { catalog, clonePath: tmpDir };
 	} catch (err) {
 		await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
-		throw err;
+		throw new Error(`Cloned repository ${url}: ${(err as Error).message}`, { cause: err });
 	}
-
-	return { catalog, clonePath: tmpDir };
 }
 
 /**

package/src/extensibility/plugins/runtime-config.ts

@@ -0,0 +1,9 @@
+import type { PluginRuntimeConfig } from "./types";
+
+/** Normalizes persisted plugin runtime config across legacy lockfile shapes. */
+export function normalizePluginRuntimeConfig(config: Partial<PluginRuntimeConfig>): PluginRuntimeConfig {
+	return {
+		plugins: config.plugins ?? {},
+		settings: config.settings ?? {},
+	};
+}